/01-check-state

name: headless-step-check-state
description: "First build step of the Hostinger Headless flow, run right after connect. Works out where a given domain's build stands — is a run already in progress, does the site already exist, how far did it get — by reconciling the global workspace state under ~/.hostinger/<domain>/ with what the Hostinger connector reports, then guides the user to continue, switch or buy a domain, or start over. Owns all resume/position logic for the flow."

headless-step-check-state

The first build step of the Hostinger Headless flow (orchestrated by `hostinger.com/headless/skill.md`), run right after connect. Connect has already connected the Hostinger connector and confirmed the account can build. Your job here is to **figure out where this domain stands and agree the route with the user** before any new work begins. This step owns all resume/position logic — no other stage second-guesses it.

Nothing in this step creates, provisions, deploys, or deletes anything. It reads and guides.

---

Where state lives

Everything for a domain lives under the global site workspace **`~/.hostinger/<domain>/`** — one directory per domain, under the user's home (`~` = `$HOME`), **not** the current working directory. The directory name **is** the domain, so `state.json` inside does not store it. Because it's global, `~/.hostinger/` holds every site the user has built and each one is discoverable and resumable from any directory — no collisions.

`state.json` shape (`stage` is the *next* stage to run; `provision` is the background task's status, present only once provision has fired):

{ "tool": "claude-code", "stage": "content_model",
  "provision": { "status": "in_progress", "domain": "<domain>", "started_at": "…" },
  "updated_at": "…" }

`provision.status` is `in_progress` or `completed` — but it is a **hint**: always re-verify it against `hosting_websites_list-setups` (Step 1) before trusting it to gate an instance-barrier step.

---

Step 0 — Start the run log

Before anything else, start a run and the stage (see *Run log and build report* in the top-level `SKILL.md`):

node <skill>/run-log.mjs <domain> run-start --tool <tool> --model <model> --skill <skill version>
node <skill>/run-log.mjs <domain> stage-start check_state

If an earlier run on this domain never wrote its report, `run-start` closes it as `abandoned` first.

Then send any build reports that haven't reached Hostinger yet (that abandoned run, or a send that failed last time):

node <skill>/run-log.mjs <domain> unsent

Each line is `<run> <path>`. For each, send the file through `hosting_headless_submit-build-report` and record the result, as described in *Run log and build report* in the top-level `SKILL.md`. One try each. Don't ask first; if any went out, say so in one line (e.g. "Sent 1 earlier build report to Hostinger."). Don't let a failure hold up this step. Check-state runs once per session. A follow-up after the final report, in the same session, doesn't come back here: it calls `run-resume` (see *Run log and build report* in the top-level `SKILL.md`).

Step 1 — Is a build actively running right now? (check this before anything else)

Keep two things separate, and **never guess from a timestamp.**

• **A platform build actively in progress** — the only *reliable* "running now" signal. Check

`hosting_websites_list-setups { "domain": "<domain>" }` and exact-match the domain row:

• `status: running` → provisioning is underway **right now** (a background provision from an earlier

turn). Don't start a second one — reconcile `state.json`'s `provision` to `in_progress`, and either resume prepare work while it finishes or poll it to `completed` at the barrier.

• `status: failed` → not running; route to provision to self-heal (Step 3).
• `completed` → provision is done; set `provision.status` to `completed`. Instance-barrier steps

(content push, frontend data, deploy) are now unblocked.

• no row → not provisioned yet; carry on.

This check **is** the source of truth for `provision.status`: a stored `in_progress`/`completed` in `state.json` is only a hint until this reconciles it.

• **A `.lock`** — `~/.hostinger/<domain>/.lock`. It only tells you *a previous run

touched this domain*. **Do not judge it by age** — a 2-minute-old lock and a 3-year-old lock get the same treatment, and a lock on its own is **not** a reason to interrupt the user. Carry it into Step 5: if there's nothing to resume (new build), silently take it over; only if there's real state to resume do you also ask *is another Claude window building this domain right now?* (yes → stop; no → take over).

Once you're actively working this domain, **acquire/refresh the lock** (write the current timestamp), and **release it on a clean stop** (Step 6). The lock marks an active session, nothing more.

---

Step 2 — Read the workspace directory

Look at `~/.hostinger/<domain>/`:

• **Absent** → no history for this domain in the workspace.
• **Present** → read `state.json` (its `stage`) and whatever artifacts exist (`brief.md`,

`site.json`, …). Treat these as a hint, not the truth.

---

Step 3 — Verify against reality (reality wins)

Query the Hostinger connector — the local files are never trusted on their own:

• **Does the site exist?** `hosting_websites_list { "domain": "<domain>" }`. ⚠️ This filter is a

**case-insensitive substring match**, not exact — so `test.com` would also return `shop.test.com`. **Compare each returned row's `domain` to your target for an *exact* match** (case-insensitive) and ignore the rest. No exact row ⇒ the domain is free. An exact row ⇒ the site exists; note its `website_type` (`headless`, `wordpress`, `nodejs`, …) and `username`.

• **How far did it get?** If the site exists, check its setup via

`hosting_websites_list-setups { "domain": "<domain>" }` (exact-match the row the same way):

• `status: completed` → provi