muse-crew 0.7.11 → 0.7.12

package/API.md

@@ -50,10 +50,11 @@ Atomically claim a task for a workflow step. Used by the dispatcher and by workf
 | `identity` | string (1–80) | yes | The crew identity performing the step (e.g. `sage`, `wren`) |
 | `step` | string (1–120) | no | The workflow phase name |
 | `notes` | string (≤ 3000) | no | Defaults to `""` |
+| `expected_next_phase` | string (1–120) | no | The `next_phase` routing the dispatcher launched this run for. When the claim wins, the matching `next_phase` is cleared in the **same transaction** as the winning session insert — there is no claim→consume window for a platform death to replay the routing through. Only an exact match clears; a stale or superseded routing survives. Returned as `next_phase_consumed: true/false` on the winning response (absent when the field was not passed). A losing claim never touches `next_phase`. |
 
 Returns one of:
 
-- `{ "ok": true, "claimed": true, "session_id": "<uuid>", "session": {...} }`
+- `{ "ok": true, "claimed": true, "session_id": "<uuid>", "session": {...}, "next_phase_consumed": true/false }`
 - `{ "ok": true, "claimed": false, "reason": "already_claimed", "existing_session_id": "<uuid>" }`
 
 `claimed` is the single field callers branch on. `reason` is present only when `claimed` is false.
@@ -66,9 +67,22 @@ Send a stuck or failed task to a specific workflow phase for recovery.
 |-------|------|----------|-------|
 | `task_id` | uuid | yes | |
 | `action` | `"send_to"` | yes | Only `send_to` is supported |
-| `target_phase` | string (1–120) | yes | The phase to send the task to |
+| `target_phase` | string (1–120) | yes | The phase to send the task to — must be a phase of the task's workflow (validated against the workflow's phase registry; unknown phases fail closed) |
 | `updated_description` | string (≤ 5000) | no | Optional revised description |
 
+Recovery intent, not a verdict: accepts a latest session of `failed`, `timed_out`, or `stalled` — or no session at all (pre-claim platform death). Rejects a `running` latest session (work in flight) and terminal task states. Sets `tasks.next_phase` to the target and moves `parked`/`todo` tasks to `in_progress`. Inserts **no** session: recovery never consumes retry budget. The dispatcher routes the task to `next_phase` one-shot (bypassing the retry cap); the launched workflow's successful self-claim clears it atomically (`claim-task` with `expected_next_phase`). Returns the task and `valid_phases`.
+
+### `consume-next-phase`
+
+One-shot consumption of a routed `next_phase`. Retained as an idempotent public helper for out-of-band recovery tooling — workflows no longer call this; `claim-task` with `expected_next_phase` clears the routed `next_phase` in the same transaction as the winning session insert, so the old claim→consume death window is closed.
+
+| Field | Type | Required | Notes |
+|-------|------|----------|-------|
+| `task_id` | uuid | yes | |
+| `expected` | string (1–120) | yes | The `next_phase` value the dispatcher routed on |
+
+Clears `tasks.next_phase` only when the stored value still matches `expected` (atomic conditional update). Returns `{ "consumed": true/false }`. A newer `recovertask` written in the race window survives a stale consumer.
+
 ### `parktask`
 
 Atomically park a task for human attention: sets `state` to `parked`, writes the explanatory `note` event, and settles every `running` session for the task — in one transaction. Either all land or none do: callers never see a note without a park, a park without a note, or a parked task with a ghost `running` session left behind (a terminal task transition settles its sessions). Settled sessions move to `failed` — the status `recovertask` accepts, so recovery works immediately after a park — with `ended_at` stamped and `Parked: <message>` appended to their notes; `failure_reason` stays null.
@@ -306,7 +320,7 @@ The platform records workflow run status in `runtime.workflow_runs` — separate
 Two layers, in order of preference:
 
 1. **Prevention — the launcher stays alive.** Async workflow `agent()` authorization is tied to the launcher's lifetime: if the cron tick ends while a workflow is still running, the workflow's next `agent()` call fails. So the poll tick runs with a 90-minute execution timeout (`timeout_secs: 5400` in `seed/crons.json`) and its Step 5 monitor stays alive until every launched run reaches a terminal state. A launcher that outlives its runs never triggers the failure in the first place.
-2. **Recovery — per-tick correlation through the durable mapping.** If the launcher dies early anyway (platform kill, cell recycle), the next tick's Step 0 finds the dead run, `record-platform-failure` correlates it via the `platform_run_tasks` mapping, and `retry-platform-failure` requeues the task — at most ~3 minutes later, with the ghost session settled so the dispatcher treats it as a retry candidate immediately.
+2. **Recovery — per-tick correlation through the durable mapping.** If the launcher dies early anyway (platform kill, cell recycle), the next tick's Step 0 finds the dead run, `record-platform-failure` correlates it via the `platform_run_tasks` mapping, and `retry-platform-failure` requeues the task — at most ~15 minutes later, with the ghost session settled so the dispatcher treats it as a retry candidate immediately.
 
 ### `record-platform-failure`
 

package/docs/guide.md

@@ -17,7 +17,7 @@ This is the full setup and operations reference. If you're new, start with the [
 - A **release** — the first immutable snapshot of the crew's runtime code.
 - An **`.orchestration/` directory** in the crew home with identities, personas, workflow docs, and feedback conventions.
 - A **project registration** — the task service registered as its own first project.
-- **Cron jobs** — the scheduler state declared in `seed/crons.json`: a polling loop (every 3 minutes via Muse's scheduling, even when nobody's in the conversation). Owner is `space:<slug>`, so deleting the task service also removes the crons.
+- **Cron jobs** — the scheduler state declared in `seed/crons.json`: a polling loop (every 15 minutes via Muse's scheduling, even when nobody's in the conversation). Owner is `space:<slug>`, so deleting the task service also removes the crons.
 
 The agent running in the main chat receives the dispatcher's claims and launches each task workflow. Workflows can't launch workflows, so this handoff is structural.
 
@@ -197,7 +197,7 @@ A task in `todo` state becomes eligible for dispatch on the next polling tick. A
 
 ## How the loop works
 
-Every 3 minutes, the `crew-poll` cron fires:
+Every 15 minutes, the `crew-poll` cron fires:
 
 1. **Cron runs the dispatcher** — `crew-dispatch.js` with the task service slug and `crewHome` as arguments.
 
@@ -302,7 +302,7 @@ For tasks that change anything rendered and visible in the project's artifact ("
 
 ### Publish content verification
 
-The artifact builder's `applied` report is derived from the diff the workflow carries to it, so comparing the report to the diff is circular — canary run 8 (2026-09-11) stamped provenance on a hollow build and every phase went green. The workflow therefore never stamps provenance itself: after the build lands it parks with `publish: verification-requested <commit> (build <agent_id|agent_id unobserved>)`. The parent protocol owns the independent content confirmation (parent-driven — see `docs/publish-verification.md`); the park message records the observed builder build identifier as `(build <agent_id|agent_id unobserved>)`, and the parent correlates the read-back's live build agent_id against it — a mismatch logs `publish: build-mismatch <commit> …`, stays parked, and is never stamped (parent-driven — see `docs/publish-verification.md` step 4b). The independent read-back step is currently unavailable: `artifact_inspect` was removed by the platform (2026-09-14) and no agent-callable replacement exists (`artifact.inspect` is malfunction diagnosis, not a read-back tool), so the parent cannot confirm content independently and tasks stay parked at verification-requested until a read-back path exists. QA's provenance check then enforces the stamp mechanically, so an unverified publish fails loudly in QA instead of passing silently.
+The artifact builder's `applied` report is derived from the diff the workflow carries to it, so comparing the report to the diff is circular — canary run 8 (2026-09-11) stamped provenance on a hollow build and every phase went green. The workflow therefore never stamps provenance itself: after the build lands it parks with `publish: verification-requested <commit> (build <agent_id|agent_id unobserved>)`. "Landed" requires positive evidence (canary 2026-09-15, task `1d692d91`): the build poll must have positively observed our build — a running build with the receipt `agent_id`, or a completed-build record matching it. Absence of a running build is not evidence our build ran; an unobserved "done" is an unknown outcome, parked fail-closed with an append-only `unknown` ledger entry — never parked as verification-requested. The parent protocol owns the independent content confirmation (parent-driven — see `docs/publish-verification.md`); the park message records the observed builder build identifier as `(build <agent_id|agent_id unobserved>)`, and the parent correlates the read-back's live build agent_id against it — a mismatch logs `publish: build-mismatch <commit> …`, stays parked, and is never stamped (parent-driven — see `docs/publish-verification.md` step 4b). The independent read-back step is currently unavailable: `artifact_inspect` was removed by the platform (2026-09-14) and no agent-callable replacement exists (`artifact.inspect` is malfunction diagnosis, not a read-back tool), so the parent cannot confirm content independently and tasks stay parked at verification-requested until a read-back path exists. QA's provenance check then enforces the stamp mechanically, so an unverified publish fails loudly in QA instead of passing silently.
 
 ## Identities
 
@@ -424,7 +424,7 @@ crew-release.sh current
 
 2. **Stuck sessions.** If a workflow dies mid-run, its session stays `running` indefinitely and the cron skips it every tick. Manual cleanup is currently required.
 
-3. **No streaming.** The polling loop checks every 3 minutes. There is no webhook or event-driven dispatch.
+3. **No streaming.** The polling loop checks every 15 minutes. There is no webhook or event-driven dispatch.
 
 4. **Single dispatcher.** Only one cron runs the dispatcher. Concurrent ticks are prevented by the session-claiming atomicity, but there is no explicit distributed lock.
 

package/docs/ooda-report.md

@@ -63,12 +63,13 @@ Written at phase end via `lib/write-ooda-verdict.js --dir <phase-dir>
 
 ```json
 {
-  "verdict": "PASS",
+  "verdict": "FAIL",
   "attempt": "1",
-  "summary": "Footer fix verified on desktop and mobile.",
-  "expected": "published N hr ago, no Last polled mislabel",
-  "actual": "published 6 hr ago on both viewports",
-  "missing_evidence": []
+  "summary": "Login button missing on desktop header.",
+  "expected": "login button on header",
+  "actual": "no login control in the ARIA tree",
+  "missing_evidence": ["mobile viewport not checked"],
+  "reason": "Header renders but no login control present in the ARIA tree on desktop."
 }
 ```
 
@@ -76,6 +77,12 @@ Written at phase end via `lib/write-ooda-verdict.js --dir <phase-dir>
 was not checked — an honest gap is recorded, never hidden. Unknown/
 inconclusive is neither PASS nor FAIL.
 
+`reason` is REQUIRED and must be non-empty when the verdict is `FAIL` or
+`NOT_POSSIBLE`: the writer rejects a reason-less negative verdict with exit
+2 and writes nothing. A FAIL verdict without a machine-readable reason is
+not writable — the defect that parked the 2026-09-15 canary at Publish was a
+bare `VERDICT: FAIL` with an all-positive report and no recorded reason.
+
 Two records are written:
 
 - `verdict.json` — the LATEST verdict, what the workflow closeout reads.
@@ -121,3 +128,23 @@ No nested agents — the depth-1 work agent runs the browser steps itself.
 3. Open the archived PNGs and compare against the written observations. Never trust prose alone.
 
 The report is the evidence. A QA claim without its OODA report is an unverified claim.
+
+## Reading the verdict back (2026-09-15)
+
+`lib/read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>` is the
+deterministic cross-checker the bugfix QA closeout runs after extracting the
+prose `VERDICT:` line. It prints one JSON line to stdout and never touches
+the clock or randomness:
+
+- Exit 0, `{ok:true, verdict, reason, summary, expected, actual, attempt}` —
+  the record exists, parses, carries a `verdict` field, agrees with the
+  prose expectation, and a FAIL carries a non-empty reason.
+- Exit 2, `{ok:false, code}` — `missing` (no verdict.json), `corrupt`
+  (unparseable or no verdict field), `contradiction` (record disagrees with
+  the prose line), `no_reason` (FAIL with no machine-readable reason).
+
+The prose `VERDICT:` line routes, but `verdict.json` carries the reason the
+workflow reads. On a cross-check failure the QA phase is recorded as failed
+and retried at the same step — an unreasoned or contradictory verdict never
+routes to rework. No LLM judges report-prose consistency; the machine only
+enforces that the reason is present and the records agree.

package/docs/publish-verification.md

@@ -1,11 +1,21 @@
 # Publish content verification — parent protocol
 
-> **BLOCKED (2026-09-14):** `artifact_inspect` was removed by the platform.
-> No agent-callable replacement exists (`artifact.inspect` is malfunction
-> diagnosis, not a read-back tool), so the ferry step below cannot currently
-> run. Tasks park at `publish: verification-requested` and stay parked until
-> a read-back path exists. The rest of this document describes the protocol
-> as designed, so the shape is preserved for when the capability returns.
+> **UNBLOCKED (2026-09-15):** the platform's `artifact_inspect` is still
+> gone, but no platform tool is needed anymore. The platform's artifact
+> edits land in its on-disk working copy of the artifact source
+> (`~/workspace/ts-spaces/<slug>/` — verified empirically 2026-09-15:
+> added lines present, removed lines absent across real platform commits),
+> so `lib/readback-disk.js` performs the read-back deterministically: it
+> reads the working copy and emits the exact machine-readable findings
+> block `lib/verify-publish.js` already parses. No LLM, no async handoff,
+> no prose to parse. The verifier is unchanged — the sensor changed, the
+> judge didn't.
+>
+> Authority boundary: the sensor reads the platform's working copy — the
+> tree the hosted artifact is built/served from. A working copy that is
+> stale relative to a just-applied edit yields honest ABSENT findings and
+> the verifier fails CLOSED (parked). Staleness can only park a task,
+> never stamp provenance.
 
 Provenance is the artifact's claim that its live content came from a specific
 repo commit. The workflow never stamps it. This document is the parent-side
@@ -120,10 +130,16 @@ LLM never judges. The division:
    and never uses `commit^1` as the base: push-time reconcile merges put
    the task's own changes behind an intermediate merge, so `commit^1`
    covers only the reconcile delta (2026-09-14, task `0c53af4e`).
-3. **Ferry (tick worker):** when a read-back tool is available, calls it
-   with the built request, waits for the async handoff, saves the full
-   result JSON to a file. (Currently blocked — no agent-callable tool
-   exists.)
+3. **Ferry (tick worker):** runs the deterministic sensor
+   `lib/readback-disk.js` (`--repo-path`, `--commit`, `--base` — the same
+   base as step 2 — `--slug` from the project's `deploy_slug`, `--task-id`)
+   and saves its stdout to the result file. The sensor exits 0 only when it
+   actually read the working copy; on a non-zero exit the tick must NOT
+   save stdout — log `publish: verification-procedural-error <commit>
+   <stderr>` and leave the task parked for the next tick to retry (a sensor
+   failure is procedural — the read could not be performed — not a content
+   verdict). `build-readback-request.js` is retained for the manual LLM
+   fallback below.
 4. **Certify (code):** `verify-publish.js` parses the inspector's
    machine-readable findings block, compares every added/removed diff line
    against the reported present/absent verdicts, checks build-ID correlation
@@ -194,15 +210,15 @@ For a task parked with `publish: verification-requested <commit>`:
    reconcile merges violate the `merge^1 == previously-published tree`
    invariant, so `commit^1..commit` can omit the task's own fix
    (2026-09-14, task `0c53af4e`).
-3. **Actual content.** When a read-back tool is available, call it with
-   `repair_authorized: false` and the `verbatim_request` built by
-   `lib/build-readback-request.js` (pass `--repo-path`, `--commit`,
-   `--base` (the same base as step 2),
-   `--task-id`, `--slug`, and `--build-agent-id` from the park message's
-   `(build …)` suffix when it is not `agent_id unobserved`). Currently
-   blocked — `artifact_inspect` was removed by the platform (2026-09-14)
-   and no agent-callable replacement exists. The request demands a
-   machine-readable findings block:
+3. **Actual content.** Run `lib/readback-disk.js` with `--repo-path`,
+   `--commit`, `--base` (the same base as step 2), `--slug`, and
+   `--task-id`, and save its stdout to the result file — this is the
+   deterministic read-back; it emits the machine-readable findings block
+   directly. (LLM fallback: if the disk working copy is unavailable, call
+   the artifact inspector with `repair_authorized: false` and the
+   `verbatim_request` built by `lib/build-readback-request.js`, passing
+   `--build-agent-id` from the park message's `(build …)` suffix when it
+   is not `agent_id unobserved`.) The findings block grammar:
    ```
    FILE: <path>
    ADDED: <exact added line> :: PRESENT|ABSENT
@@ -215,9 +231,17 @@ For a task parked with `publish: verification-requested <commit>`:
 4. **Compare mechanically.** For every added (`+`) line in the diff, the
    read-back's machine-readable block must report it PRESENT in the
    artifact's current source. For every removed (`-`) line, it must report
-   it ABSENT. The comparison is computed by `lib/verify-publish.js` — never
-   by eyeballing prose. A missing or malformed findings block fails closed
-   as `unreadable-result`, never as a pass.
+   it ABSENT — with one mechanical exemption: a removed line that also
+   occurs verbatim in untouched code has zero discriminating power (its
+   presence proves nothing about whether the old block survived), so the
+   verifier exempts it instead of failing a good publish. The exemption is
+   computed, never judged: a removed line L in file F is exempt iff L
+   occurs in F's old tree (at `<base>`) strictly more times than the diff
+   removes it (2026-09-15, task `00bca4b8` — a valid publish parked because
+   two removed lines occurred identically in the untouched WorkflowSteps
+   component). The comparison is computed by `lib/verify-publish.js` —
+   never by eyeballing prose. A missing or malformed findings block fails
+   closed as `unreadable-result`, never as a pass.
 4b. **Build-ID correlation.** The read-back may have inspected a different
    build's output than this publish attempt's:
    1. **Expected** = the agent_id in the park message's `(build …)` suffix.

package/lib/AGENTS.md

@@ -19,5 +19,6 @@ Shell scripts for the crew's infrastructure. Called by workflow scripts, cron, a
 - `render-html.js` — deterministic HTML evidence composition (2026-09-15, headless Chromium): renders a local HTML layout to PNG (fixed viewport width, device scale 1, full-page screenshot). Hermetic: remote HTTP(S) assets are blocked and fail the render loudly; relative image paths resolve against the HTML file; local/system fonts only. Exit 3 reports NOT POSSIBLE when Chromium is unavailable. The composition layer above edit-image.py's pixel layer.
 - `see-act.js` — single-step browser driver for experiential QA (2026-09-14): one browser action per invocation (`aria`, `shot`, `click`, `scroll`, `type`), one JSON line on stdout, exit 0/2/3 (3 = NOT POSSIBLE: missing playwright-core or Chromium). Spawns its own loopback forward proxy on an ephemeral port (Chromium blocks direct loopback). The QA work agent closes the OODA loop: run a step, read the screenshot/aria, decide the next. Determinism: no wall-clock reads, no randomness. `SEE_ACT_ARCHIVE_DIR=<phase-dir>` (2026-09-14): every screenshot is archived automatically as `001-shot-desktop.png`, `002-click-mobile.png`, ... (counter in `<dir>/.seq`); `--out` becomes optional; JSON carries `screenshot` + `archived`; explicit `--out` + archive copies into the archive; unusable dir is NOT POSSIBLE exit 3.
 - `append-ooda-step.js` — deterministic writer for the OODA report log (2026-09-14, attempt identity 2026-09-15): `node append-ooda-step.js --log <path> --attempt <id> --step <n> --action <a> --exit <code> [--args <json>] [--screenshot <path>] [--observation <text>]` appends one JSON line to `<phase-dir>/ooda-log.jsonl` (`{step, attempt, action, args, exit, screenshot|null, observation}`). `--attempt` is required; steps must be strictly monotonic within an attempt (a rerun is a new attempt at step 1 — attempts accumulate, never overwrite). Actions: browser (`aria|shot|click|scroll|type`) and image (`crop|zoom|label|nup|compose` — the last five log evidence derivatives made with `lib/edit-image.py` / `lib/render-html.js`; frame-producing actions require `--screenshot`). Corrupt logs or sequence gaps fail loudly (exit 2). No wall-clock reads, no randomness.
-- `write-ooda-verdict.js` — deterministic writer for the OODA terminal verdict (2026-09-14, append-only ledger 2026-09-15): `node write-ooda-verdict.js --dir <phase-dir> --attempt <id> --verdict <PASS|FAIL|NOT_POSSIBLE> --summary <text> --expected <text> --actual <text> --missing <json-array>` writes `<phase-dir>/verdict.json` (the latest verdict) and appends one JSON line to `<phase-dir>/verdicts.jsonl` — the append-only ledger: every attempt's verdict is preserved with a mechanical `seq`, never overwritten; corrupt or non-contiguous ledgers fail loudly. Exit 2 on bad input. See `docs/ooda-report.md`.
+- `write-ooda-verdict.js` — deterministic writer for the OODA terminal verdict (2026-09-14, append-only ledger 2026-09-15): `node write-ooda-verdict.js --dir <phase-dir> --attempt <id> --verdict <PASS|FAIL|NOT_POSSIBLE> --summary <text> --expected <text> --actual <text> --missing <json-array> [--reason <text>]` writes `<phase-dir>/verdict.json` (the latest verdict) and appends one JSON line to `<phase-dir>/verdicts.jsonl` — the append-only ledger: every attempt's verdict is preserved with a mechanical `seq`, never overwritten; corrupt or non-contiguous ledgers fail loudly. `--reason` is REQUIRED and must be non-empty for `FAIL` and `NOT_POSSIBLE` — a reason-less negative verdict fails with exit 2 before anything is written (2026-09-15). Exit 2 on bad input. See `docs/ooda-report.md`.
+- `read-ooda-verdict.js` — deterministic cross-checker for the OODA terminal verdict (2026-09-15): `node read-ooda-verdict.js --dir <phase-dir> --expect <PASS|FAIL>` reads `<dir>/verdict.json`, prints one JSON line to stdout, exits 0 with `{ok:true, verdict, reason, summary, expected, actual, attempt}` when the record agrees with the prose expectation and a FAIL carries a non-empty reason, or exits 2 with `{ok:false, code}` — `missing|corrupt|contradiction|no_reason`. No wall-clock reads, no randomness. The bugfix QA closeout runs it against the prose `VERDICT:` line before any rework routing: a failed cross-check records the phase as failed for retry, never routes to rework.
 - `serve-artifact.js` — local server for a built TS space for experiential QA (2026-09-14): serves `<space-dir>/client/dist` statically and dispatches POST `*/actions` to the compiled server actions with a locally-built Ctx. Prints `READY port=<n>` then serves until killed. Read-only w.r.t. the space directory. Fidelity: the served client and action handlers are the artifact's own built code; the Ctx is locally built (privileged handlers run from the space's own `server/dist/privileged.js` when present; blobs are stored in a per-run temp dir and served back at `/__blobs/<key>`); environment is inherited from the caller. It is not the hosted runtime — tasks that cannot be judged under it must report `NOT POSSIBLE: <reason>`.

package/lib/crew-api.js

@@ -12,7 +12,7 @@
 //
 // Commands (kebab-case) map to API.md actions:
 //   get-dispatch-state, get-state, create-task, update-task, claim-task,
-//   park-task, recover-task, upsert-session, log-event, get-events,
+//   park-task, recover-task, consume-next-phase, upsert-session, log-event, get-events,
 //   create-project, update-project, delete-project, list-projects,
 //   get-project, kill-switch, get-config, update-config,
 //   set-provenance, get-provenance, acknowledge-poll,
@@ -260,6 +260,53 @@ function workflowExists(crewHome, slug) {
   );
 }
 
+// Workflow step names for a slug, from the release registry when present,
+// falling back to the workflow file's own `export const meta` block (the
+// single source of truth the registry is built from). Returns null when the
+// workflow file cannot be found or parsed. Used by recover-task to validate
+// target_phase, and by the dispatcher-side contract tests.
+function workflowStepNames(crewHome, slug) {
+  if (!slug) return null;
+  const candidates = [
+    join(crewHome, "current", "workflows", "registry.json"),
+    join(crewHome, "workflows", "registry.json"),
+  ];
+  for (const regPath of candidates) {
+    try {
+      const reg = JSON.parse(readFileSync(regPath, "utf8"));
+      const entry = reg && reg[slug];
+      if (entry && Array.isArray(entry.steps)) {
+        const names = entry.steps.map((s) => s && s.name).filter((n) => typeof n === "string");
+        if (names.length > 0) return names;
+      }
+    } catch (e) { /* fall through to the meta-block parse */ }
+  }
+  const wfCandidates = [
+    join(crewHome, "current", "workflows", `${slug}.js`),
+    join(crewHome, "workflows", `${slug}.js`),
+  ];
+  for (const wfPath of wfCandidates) {
+    let source;
+    try { source = readFileSync(wfPath, "utf8"); } catch (e) { continue; }
+    const marker = "export const meta = ";
+    const start = source.indexOf(marker);
+    if (start < 0) continue;
+    const bodyStart = start + marker.length;
+    const end = source.indexOf("\n};", bodyStart);
+    if (end < 0) continue;
+    try {
+      // The meta block is a static literal (no function calls); evaluating
+      // the object literal in isolation is safe.
+      const meta = new Function("return (" + source.slice(bodyStart, end + 2) + ");")();
+      if (meta && Array.isArray(meta.steps)) {
+        const names = meta.steps.map((s) => s && s.name).filter((n) => typeof n === "string");
+        if (names.length > 0) return names;
+      }
+    } catch (e) { /* try the next candidate */ }
+  }
+  return null;
+}
+
 // Minimal git-repo validation (ported from the dashboard's validateRepoPath):
 // accepts a repo root (.git dir) or a linked worktree (.git file).
 function isGitRepoPath(p) {
@@ -536,6 +583,17 @@ commands["claim-task"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   const identity = (args.identity ?? "").trim();
   if (identity.length < 1 || identity.length > 80) throw usageError("identity is required (1-80 chars).");
+  // ATOMIC NEXT_PHASE CONSUMPTION (2026-09-15): expected_next_phase is the
+  // routing the dispatcher launched this run for. When the claim wins, the
+  // matching next_phase is cleared in the SAME transaction as the winning
+  // session insert — there is no claim→consume window for a platform death
+  // to replay the routing through. The separate consume-next-phase command
+  // is retained only as an idempotent public helper (out-of-band recovery);
+  // workflows no longer call it.
+  const rawExpected = args.expected_next_phase;
+  const expectedNextPhase = (rawExpected === undefined || rawExpected === null) ? null : String(rawExpected).trim();
+  if (expectedNextPhase !== null && (expectedNextPhase.length < 1 || expectedNextPhase.length > 120))
+    throw usageError("expected_next_phase must be 1-120 chars when provided.");
   const task = requireTask(db, args.task_id);
   const project = requireProject(db, task.project);
   if (project.quiesced) throw conflict("This project is paused. Resume it before claiming tasks.");
@@ -553,23 +611,41 @@ commands["claim-task"] = (db, args) => {
     notes: (args.notes ?? "").trim().slice(0, 3000), caveats: "[]",
     last_heartbeat: now(),
   };
-  // Atomic: the partial unique index on (task_id) WHERE status='running'
-  // turns a duplicate claim into a no-op insert.
-  const info = db.prepare(
-    `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
-      ended_at, notes, caveats, last_heartbeat)
-     VALUES (@id, @task_id, @identity, @step, @status, @started_at,
-      @ended_at, @notes, @caveats, @last_heartbeat)
-     ON CONFLICT DO NOTHING`).run(row);
-  if (info.changes > 0) {
-    return { ok: true, claimed: true, session_id: row.id, session: mapSession({ ...row, failure_reason: null }) };
-  }
-  const existing = db.prepare(
-    `SELECT id FROM agent_sessions
-     WHERE task_id = ? AND status = 'running'
-     ORDER BY started_at DESC LIMIT 1`).get(args.task_id);
-  if (!existing) throw new CrewError("claim_unresolved", "Task claim could not be resolved. Please retry.", 4);
-  return { ok: true, claimed: false, reason: "already_claimed", existing_session_id: existing.id };
+  const timestamp = now();
+  db.exec("BEGIN");
+  try {
+    // Atomic: the partial unique index on (task_id) WHERE status='running'
+    // turns a duplicate claim into a no-op insert.
+    const info = db.prepare(
+      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
+        ended_at, notes, caveats, last_heartbeat)
+       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
+        @ended_at, @notes, @caveats, @last_heartbeat)
+       ON CONFLICT DO NOTHING`).run(row);
+    // Same transaction: only the claim winner consumes, and only when the
+    // stored routing still matches what the dispatcher launched on — a newer
+    // recover-task written in the race window survives untouched.
+    let nextPhaseConsumed = false;
+    if (info.changes > 0 && expectedNextPhase) {
+      const cleared = db.prepare(
+        "UPDATE tasks SET next_phase = NULL, updated_at = ? WHERE id = ? AND next_phase = ?"
+      ).run(timestamp, args.task_id, expectedNextPhase);
+      nextPhaseConsumed = cleared.changes > 0;
+    }
+    db.exec("COMMIT");
+    if (info.changes > 0) {
+      return { ok: true, claimed: true, session_id: row.id, session: mapSession({ ...row, failure_reason: null }),
+        next_phase_consumed: expectedNextPhase ? nextPhaseConsumed : undefined };
+    }
+    const existing = db.prepare(
+      `SELECT id FROM agent_sessions
+       WHERE task_id = ? AND status = 'running'
+       ORDER BY started_at DESC LIMIT 1`).get(args.task_id);
+    if (!existing) throw new CrewError("claim_unresolved", "Task claim could not be resolved. Please retry.", 4);
+    // Lost claim: the winner (or an earlier winner) owns next_phase
+    // consumption — a loser must never clear it.
+    return { ok: true, claimed: false, reason: "already_claimed", existing_session_id: existing.id };
+  } catch (e) { db.exec("ROLLBACK"); throw e; }
 };
 
 // Dispatch reservations: the cron worker creates one after launching a
@@ -845,6 +921,9 @@ commands["retry-platform-failure"] = (db, args) => {
   if (failure.retry_count >= maxRetries) {
     // Park the task — transient failures are not resolving.
     const task = db.prepare("SELECT * FROM tasks WHERE id = ?").get(failure.task_id);
+    if (task && task.state === "done") {
+      return { ok: true, action: "skipped", reason: "task already done — a platform retry never parks a done task", retry_count: failure.retry_count };
+    }
     if (task && task.state !== "parked") {
       const msg = "Platform workflow failed " + (failure.retry_count + 1) + "x: " +
         failure.error_message.substring(0, 200);
@@ -875,19 +954,47 @@ commands["retry-platform-failure"] = (db, args) => {
     }
     return { ok: true, action: "parked", reason: "max retries exceeded", retry_count: failure.retry_count, settled_sessions: 0 };
   }
-  // Clear reservation and re-queue for retry.
+  // Clear the reservation and re-queue for retry — preserving the task's
+  // phase. Canary 2026-09-15 (task 1d692d91): the old code forced
+  // state='todo', so a platform failure during QA restarted the entire
+  // workflow at Triage; Build reimplemented an already-merged and
+  // already-verified task and produced an unrequested variant. The
+  // dispatcher already resumes a failed/timed_out/stalled session at that
+  // session's own step — so the fix is to leave the task's state alone and
+  // settle the ghost session as 'stalled', letting the dispatcher resume at
+  // the failed phase instead of restarting at Triage. 'done' is never
+  // resurrected and 'parked' is never unparked: parked is the designed
+  // human decision point.
+  const retryTask = db.prepare("SELECT id, state FROM tasks WHERE id = ?").get(failure.task_id);
+  if (!retryTask) {
+    return { ok: true, action: "skipped", reason: "task not found" };
+  }
+  if (retryTask.state === "done") {
+    return { ok: true, action: "skipped", reason: "task already done — never resurrected by a platform retry" };
+  }
+  if (retryTask.state === "parked") {
+    return { ok: true, action: "skipped", reason: "task parked — the human decision point, never unparked by a platform retry" };
+  }
+  // The failed phase is the ghost session's step: the dispatcher resumes
+  // failed/timed_out/stalled sessions at that step. Capture it before
+  // settling so the requeue reports where the run will resume.
+  const ghost = db.prepare(
+    `SELECT step FROM agent_sessions WHERE task_id = ? AND status = 'running'
+     ORDER BY started_at DESC LIMIT 1`
+  ).get(failure.task_id);
   db.exec("BEGIN");
   try {
     db.prepare("DELETE FROM dispatch_reservations WHERE task_id = ?").run(failure.task_id);
     db.prepare(
-      "UPDATE tasks SET state = 'todo', updated_at = datetime('now') WHERE id = ? AND state != 'done'"
+      "UPDATE tasks SET updated_at = datetime('now') WHERE id = ?"
     ).run(failure.task_id);
     // Settle the ghost session atomically with the requeue: the platform
     // workflow is dead, but its agent_sessions row still says 'running' —
     // and the dispatcher skips any task whose latest session is running
     // (crew-dispatch.js "work in flight"). Without this, the requeued task
     // would sit until the 1-hour zombie-session sweep. 'stalled' is what
-    // the dispatcher already treats as a retry candidate.
+    // the dispatcher already treats as a retry candidate, resuming at the
+    // session's own step.
     const ts = new Date().toISOString();
     const settled = db.prepare(
       `UPDATE agent_sessions
@@ -905,6 +1012,8 @@ commands["retry-platform-failure"] = (db, args) => {
       ok: true,
       action: "requeued",
       task_id: failure.task_id,
+      state: retryTask.state,
+      resume_step: ghost ? ghost.step : null,
       retry_count: failure.retry_count + 1,
       settled_sessions: Number(settled.changes),
     };
@@ -951,41 +1060,77 @@ commands["recover-task"] = (db, args, ctx) => {
   const targetPhase = (args.target_phase ?? "").trim();
   if (targetPhase.length < 1 || targetPhase.length > 120) throw usageError("target_phase is required (1-120 chars).");
   const task = requireTask(db, args.task_id);
+  if (!task.workflow) throw conflict("This task does not have a workflow with selectable phases.");
+  if (!workflowExists(ctx.crewHome, task.workflow)) throw notFound("Workflow not found.");
+  // Validate the target against the workflow's own phase registry — an
+  // unknown phase fails closed here, never as a dispatcher skip or a
+  // workflow launched at the wrong step.
+  const stepNames = workflowStepNames(ctx.crewHome, task.workflow);
+  if (!stepNames) throw conflict(`Could not read the phase registry for workflow "${task.workflow}".`);
+  if (!stepNames.includes(targetPhase)) {
+    throw conflict(`Unknown phase "${targetPhase}" for workflow "${task.workflow}". Valid phases: ${stepNames.join(", ")}.`);
+  }
+  // Recovery intent, not a verdict: the latest session may be failed,
+  // timed_out, stalled — or absent entirely (the platform died before the
+  // first claim). A running session means work is in flight; completed,
+  // rejected, passed, and superseded sessions have their own normal paths
+  // (next step, rework) and are not recovery targets.
   const latest = db.prepare(
     `SELECT * FROM agent_sessions WHERE task_id = ? ORDER BY started_at DESC LIMIT 1`
   ).get(args.task_id);
-  if (!latest || !["failed", "timed_out"].includes(latest.status)) {
-    throw conflict("The latest session is not failed or timed out.");
+  if (latest && !["failed", "timed_out", "stalled"].includes(latest.status)) {
+    throw conflict(`The latest session is ${latest.status}; recover-task accepts only failed, timed_out, stalled, or no session.`);
   }
-  if (!task.workflow) throw conflict("This task does not have a workflow with selectable phases.");
-  if (!workflowExists(ctx.crewHome, task.workflow)) throw notFound("Workflow not found.");
+  if (["done", "cancelled"].includes(task.state)) {
+    throw conflict(`Task is ${task.state}; recovery applies to todo, in_progress, or parked tasks.`);
+  }
+  // No synthetic session: recovery intent must not consume retry budget.
+  // The dispatcher routes on tasks.next_phase directly (one-shot, consumed
+  // by the claiming workflow), so no failed-session marker is needed to
+  // make the task eligible.
   const timestamp = now();
-  const queued = {
-    id: uuid(), task_id: task.id,
-    identity: latest.identity, step: targetPhase, status: "failed",
-    started_at: timestamp, ended_at: timestamp,
-    notes: (args.updated_description ?? "").trim().slice(0, 5000),
-    caveats: "[]", failure_reason: null, last_heartbeat: timestamp,
-  };
+  const newState = (task.state === "parked" || task.state === "todo") ? "in_progress" : task.state;
+  const note = (args.updated_description ?? "").trim().slice(0, 5000);
   db.exec("BEGIN");
   try {
-    db.prepare("UPDATE tasks SET next_phase = ?, updated_at = ? WHERE id = ?")
-      .run(targetPhase, timestamp, task.id);
-    db.prepare("UPDATE agent_sessions SET ended_at = ? WHERE id = ?").run(timestamp, latest.id);
+    db.prepare("UPDATE tasks SET next_phase = ?, state = ?, updated_at = ? WHERE id = ?")
+      .run(targetPhase, newState, timestamp, task.id);
     db.prepare(
-      `INSERT INTO agent_sessions (id, task_id, identity, step, status, started_at,
-        ended_at, notes, caveats, failure_reason, last_heartbeat)
-       VALUES (@id, @task_id, @identity, @step, @status, @started_at,
-        @ended_at, @notes, @caveats, @failure_reason, @last_heartbeat)`).run(queued);
+      `INSERT INTO events (id, type, task_id, identity, message, timestamp)
+       VALUES (?, 'note', ?, 'recover-task', ?, ?)`
+    ).run(uuid(), task.id,
+      `Recovery: next phase set to ${targetPhase}` +
+      (task.state !== newState ? ` (state ${task.state} -> ${newState})` : "") +
+      (note ? `. ${note}` : ""),
+      timestamp);
     db.exec("COMMIT");
   } catch (e) { db.exec("ROLLBACK"); throw e; }
   const taskStates = new Map(db.prepare("SELECT id, state FROM tasks").all().map((r) => [r.id, r.state]));
   return {
-    task: mapTask({ ...task, next_phase: targetPhase, updated_at: timestamp }, taskStates),
-    session: mapSession(queued),
+    task: mapTask({ ...task, next_phase: targetPhase, state: newState, updated_at: timestamp }, taskStates),
+    valid_phases: stepNames,
   };
 };
 
+// Retained as an idempotent public helper for out-of-band recovery tooling.
+// Workflows no longer call this: claim-task with expected_next_phase clears
+// the routed next_phase in the same transaction as the winning session
+// insert, so the old claim→consume death window is closed. The conditional
+// UPDATE keeps this exactly-once for any other caller: only the claim winner
+// clears, and only when the value still matches what the dispatcher routed
+// on — a newer recover-task written in the race window survives untouched.
+commands["consume-next-phase"] = (db, args) => {
+  if (!args.task_id) throw usageError("task_id is required.");
+  const expected = (args.expected ?? "").trim();
+  if (expected.length < 1 || expected.length > 120) throw usageError("expected is required (1-120 chars).");
+  requireTask(db, args.task_id);
+  const timestamp = now();
+  const info = db.prepare(
+    "UPDATE tasks SET next_phase = NULL, updated_at = ? WHERE id = ? AND next_phase = ?"
+  ).run(timestamp, args.task_id, expected);
+  return { consumed: info.changes > 0, task_id: args.task_id };
+};
+
 commands["upsert-session"] = (db, args) => {
   if (!args.task_id) throw usageError("task_id is required.");
   requireTask(db, args.task_id);