okstra 0.165.3 → 0.166.0

package/docs/for-ai/skills/okstra-run.md

@@ -225,12 +225,13 @@ When `task-type == implementation` and the render-args `chain-stages` CSV has 2
 
 1. Re-call render-bundle with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit` — do not pass it by hand). The `io`-only conformance waiver·concurrent-run·git-reconcile gates apply identically to each stage's render-bundle.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl`.
-3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary.
+3. After confirming the `done` row was written, move to the next stage. Clean up context (leftover panes·finished teammates) at each stage boundary. A `status:"failed"` row in place of `done` means the stage ended `FAIL` — stop the queue per the FAIL branch below.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion.
 
 - **Next stage not yet ready — normal termination:** When a stage in the queue is occupied by another implementation run as started/reserved and render-bundle is rejected with `--stage N already in progress or reserved by another run` (StageTargetError), this is not an exception — **terminate the chain normally** and report the remaining queue (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`).
+- **Stage ended FAIL — stop the queue and report:** When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row instead of `done`. **Stop the queue there** and report the failed stage, its report path, and the remaining queue. Do not continue to the next stage even when it is dependency-independent — later work must not be stacked on a confirmed regression. The `failed` row frees the occupancy, so `--stage <N>` re-enters that stage on its preserved worktree and branch.
 - **Exception gate during chaining:** If render-bundle raises a concurrent-run conflict or git stale-SHA reconciliation, **stop the chain at that stage** and present the gate to the user per the Step 5 procedure. Once the user resolves it, resume the remaining queue in place. Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining.
 
 ## Forbidden patterns

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.165.3",
+  "version": "0.166.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.165.3",
-  "builtAt": "2026-08-11T07:58:44.694Z",
+  "package": "0.166.0",
+  "builtAt": "2026-08-11T10:29:58.327Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/host-orchestration/implementation.md

@@ -53,5 +53,8 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 ### Next stage not yet ready — normal termination (not an exception gate)
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
+### Stage ended FAIL — stop the queue and report (not an exception gate)
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -99,9 +99,9 @@ Required checkpoints:
 - `PROGRESS: phase-1-intake complete` — after all intake reads return.
 - `PROGRESS: phase-2-prompts preparing <N> worker prompts` — at the start of Phase 2, before any `Write` to the assigned prompt paths.
 - `PROGRESS: phase-3-team-create <adapter-specific-status>` — after selected-adapter setup is recorded in team-state. The stable phase id is retained for artifact compatibility.
-- `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before `dispatch_worker`.
+- `PROGRESS: phase-4-dispatch worker=<role> model=<model>` — once per worker, immediately before `dispatch_worker`. `<role>` is the **roster** role, exactly as team-state's `workers[].role` records it (`Claude worker`, `Codex worker`) — the checkpoint is matched against that entry, so a phase-specific functional label (`Claude verifier`, `Codex executor`) names no roster worker and fails the check. Only `claude-worker`-style hyphenation of the same roster role is also accepted.
 - `PROGRESS: phase-5-poll pending=<n> done=<m>` — emitted on each wakeup while the pending set is non-empty.
-- `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified.
+- `PROGRESS: phase-5-collect worker=<role> status=<terminal-status>` — once per worker, immediately after the result file is verified. `<role>` is the roster role, same rule as `phase-4-dispatch` above.
 - `PROGRESS: phase-5.5-convergence round=<N> queue=<count>` — at the start of each convergence round (Phase 5.5).
 - `PROGRESS: phase-5.6-critic provider=<provider> gaps=<n>` — after the critic result is collected (Phase 5.6, opt-in; the critic dispatch itself fires concurrently with the first 5.5 reverify round). Omitted when `convergence.critic.enabled == false`.
 - `PROGRESS: phase-batch-cleanup panes=<n>` — immediately after cleaning up the previous batch's panes, at each batch boundary (① just before the first `phase-5.5-convergence` round ② just before the `phase-6-synthesis` report-writer dispatch). `<n>` is the number of panes reclaimed at that boundary — worker-compute panes plus completed teammate panes, which are panes too — read from the cleanup's `--list` pass taken immediately before the reclaim, never estimated. Expose only the counts and NEVER expose `%NNN`/lead-pane.id/raw worker handles. Just before the first batch (analysis-worker dispatch) there is nothing to clean up, so it is a no-op and the marker is omitted.

package/runtime/prompts/profiles/_implementation-deliverable.md

@@ -59,7 +59,8 @@ are collected and convergence finished. Phase 1-5 do not need it.
 
 - Parse the executor's `### Stage Carry Evidence` JSON block. If absent or unparsable, end with status `contract-violated` and route to a follow-up `error-analysis`.
 - The `### Stage Carry Evidence` JSON may include `designPrepEvidence[]`. Emit a row only when this stage produced concrete evidence that refines an effective PREP item: `itemId`, the injected `assessmentFingerprint`, `resolution`, and non-empty `evidence[]` are required; `overrides` is optional and only records observed, non-authoritative refinements. Carry evidence never represents user approval. Downstream resolution accepts it only from transitive dependency stages with the matching fingerprint.
-- For this run's single stage: write its JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json`. Refuse to overwrite an existing file (one stage = one sidecar; re-runs are out of scope for this version).
-- For this run's single stage: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (this run's final-report path relative to the run root), and the SHA of HEAD. Append it with `okstra_ctl.consumers.append_consumer` (NOT a raw filesystem write) — that call honours the consumers lock AND releases this stage's worktree-registry occupancy, so later runs stop seeing a finished stage as a concurrent run. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
+- **A `FAIL` synthesised verdict withholds the two writes below.** They are what marks the stage `done`, so performing them on a stage whose verifier found a blocking defect stacks the next stage on a confirmed regression. When the synthesised verdict is `FAIL`: write NO carry sidecar, and append a `status:"failed"` row in place of the `done` row — same `okstra_ctl.consumers.append_consumer` call, carrying `report_path` and the SHA of HEAD. That row is terminal *without* completion: dependent stages stay blocked because this stage is not done, while its worktree-registry occupancy is released so a fix run can re-enter the same stage number — `--stage <N>` reuses the preserved worktree and branch instead of provisioning a new one. State the reason in the report's `Stage sidecar evidence` section as `withheld`. **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` accepts a missing carry file only when that field is non-empty, so silently skipping the sidecar still fails the run.
+- On a non-`FAIL` verdict, for this run's single stage: write its JSON verbatim to `runs/<impl-task-key>/carry/stage-<N>.json`. Refuse to overwrite an existing file (one stage = one sidecar; a fix run re-entering after a `failed` row writes the first one, because a withheld stage never wrote it).
+- On a non-`FAIL` verdict, for this run's single stage: append a `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` with `completed_at`, `carry_path`, `report_path` (this run's final-report path relative to the run root), and the SHA of HEAD. Append it with `okstra_ctl.consumers.append_consumer` (NOT a raw filesystem write) — that call honours the consumers lock AND releases this stage's worktree-registry occupancy, so later runs stop seeing a finished stage as a concurrent run. `report_path` lets `final-verification` cite each stage's originating report when assembling its Source Implementation Report list.
 - The verifier round, Phase 5.5 convergence, and this Phase 6 report run **once per run** over this stage's diff — NOT per step.
 - Quote this stage's new contents (the sidecar JSON in full and the new consumers row by itself) in the final report's `Stage sidecar evidence` deliverable section.

package/runtime/prompts/profiles/_implementation-executor.md

@@ -11,7 +11,7 @@ until Phase 5 ends, then drop from active context for Phase 6/7.
 
 ## Executor role binding (carried over from the thin core)
 
-- **Executor dispatch labelling.** The core functional role label is `<provider>-executor` (e.g. `codex-executor`). Provider, role, and model identity are owned by `prompts/lead/okstra-lead-contract.md` "Model assignments"; the selected runtime adapter owns provider-native dispatch-label mapping (including any `name` / `**Pane role:**` fields) and token-attribution wiring under its "Semantic operation mapping".
+- **Executor dispatch labelling.** The core functional role label is `<provider>-executor` (e.g. `codex-executor`). Provider, role, and model identity are owned by `prompts/lead/okstra-lead-contract.md` "Model assignments"; the selected runtime adapter owns provider-native dispatch-label mapping (including any `name` / `**Pane role:**` fields) and token-attribution wiring under its "Semantic operation mapping". This functional label is NOT what the run's PROGRESS checkpoints carry: `phase-4-dispatch` / `phase-5-collect` name the roster role team-state records (`Codex worker`), because that is the entry the Phase 7 conformance check matches them against.
 - The `Executor` (bound in `implementation.md` thin core) is the **only worker permitted to mutate project files**. All other workers run read-only. A `runner=native-session` executor uses the selected host adapter's native edit and command primitives. A `runner=cli-wrapper` executor mutates files inside its provider CLI's auto-edit mode. The safety rules in this sidecar apply identically to both runners.
 - When the thin core's Task worktree block resolves status to `created` or `reused`, the Executor MUST run every Edit / Write / build / test / commit command with the worktree path as cwd. Treat it as `project_root` for the duration of this run. Do NOT mutate the caller's original checkout. Do NOT `cd` out of the worktree to reach files. If a file outside the worktree is genuinely needed, treat it as a planning gap: record it in `Out-of-plan edits` and continue.
   - **How to set the working directory**: every command and native edit MUST target `{{EXECUTOR_WORKTREE_PATH}}`, never the lead session's original project directory. The selected runtime adapter owns the exact native command syntax. Provider CLI wrappers inject the worktree at the CLI layer. For tools that accept an explicit working-directory flag (`git -C <path>`, `cargo --manifest-path`, `pytest --rootdir`), prefer that form.
@@ -82,7 +82,8 @@ persisted prompt lacks the heading `Coding-conventions preflight`
   ```
 
   The file MUST NOT exist before the run starts (overwrite is refused — see `--force-stage` non-goal). **Enforced:** `validators/validate-run.py` `_validate_stage_carry_sidecar_exists` fails a run that declares `stageSidecarEvidence` without the file on disk. Transcribing the JSON into the report is not the same as writing it: `consumers` treats the carry file as the source of truth for marking the stage `done`, so a missing file leaves the stage permanently incomplete and blocks every dependent stage with a `PrepareError` — while this run reports success.
-- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. On completion, append a `status:"done"` row with `carry_path` populated for this stage number.
+- **An external Tier 3 non-PASS does NOT withhold the carry evidence.** A Tier 3 entry whose `requires` include `http`, `external`, or `db` is advisory. Its FAIL, MISSING, no result, startup failure, or credential / network / service absence gets recorded honestly — exact command, exit code, output tail, marked `ADVISORY` in `Validation evidence` — and you emit the carry evidence anyway. Only Tier 1 and Tier 2 failures withhold it. Withholding on an external result is what actually blocks the stage: the carry file is the only thing that can mark a stage `done`, the verifier re-runs that same command from the host (where a call your sandbox could not complete often passes), and a stage the verifier then PASSes can never be closed because its evidence was never written.
+- **Reverse link (BLOCKING).** The runtime already appended a `status:"started"` row for this stage before the run began. The terminal row belongs to the lead's post-stage persistence and is verdict-gated — `status:"done"` with `carry_path` on a non-`FAIL` verdict, `status:"failed"` on `FAIL` (`_implementation-deliverable.md` §"Lead post-stage persistence").
 - **No PR / push in this phase.** This run produces local commits, carry sidecar evidence, verifier results, and the implementation final report only. Push and PR creation belong exclusively to the later `release-handoff` phase after `final-verification` returns `accepted`.
 
 ## Allowed actions during the run

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -9,7 +9,7 @@ at Phase 5, BEFORE constructing the verifier worker dispatch prompts.
 
 ## Verifier roles (resolved at run-prep time)
 
-- **Verifier dispatch labelling.** The core functional role label is `<provider>-verifier` (here, and identically in `final-verification`). Provider, role, and model identity are owned by `prompts/lead/okstra-lead-contract.md` "Model assignments"; the selected runtime adapter owns provider-native dispatch-label mapping (including any `name` / `**Pane role:**` fields) and token-attribution wiring under its "Semantic operation mapping".
+- **Verifier dispatch labelling.** The core functional role label is `<provider>-verifier` (here, and identically in `final-verification`). Provider, role, and model identity are owned by `prompts/lead/okstra-lead-contract.md` "Model assignments"; the selected runtime adapter owns provider-native dispatch-label mapping (including any `name` / `**Pane role:**` fields) and token-attribution wiring under its "Semantic operation mapping". This functional label is NOT what the run's PROGRESS checkpoints carry: `phase-4-dispatch` / `phase-5-collect` name the roster role team-state records (`Claude worker`, `Codex worker`), because that is the entry the Phase 7 conformance check matches them against.
 - The verifier slots are `Claude verifier` and `Codex verifier`, plus `Antigravity verifier` **only when `antigravity` is in the resolved `--workers` roster**. Every verifier in the resolved roster is dispatched regardless of which provider holds the executor role; the executor's own provider is run *separately* as a verifier (a fresh CLI session with no shared context) so that no verdict is produced from the same session that wrote the diff. Verifiers MUST NOT call Edit, Write, or any Bash command that mutates files outside the run's artifact directories. If a verifier wants a fix, it records the recommendation in its worker result; it does not apply the fix itself.
 - Session isolation — not model-variant divergence — is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window, so reusing the same model variant for executor and same-provider verifier is acceptable. Different model variants (e.g. executor=opus / Claude verifier=sonnet) remain recommended when available.
 - Phase-specific model defaults override the shared defaults: `Claude verifier`=`opus`, `Codex verifier`=`gpt-5.6-sol`, `Antigravity verifier`=`gemini-3.1-pro` (only when present in the roster). The `Executor`'s model is taken from the provider-specific worker model corresponding to `--executor`: claude→`--claude-model` (default `opus`), codex→`--codex-model` (default `gpt-5.6-sol`), antigravity→`--antigravity-model` (default `gemini-3.1-pro`).

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -196,7 +196,7 @@ For a `host-text` mapping, render each numbered item as its option label followe
 
 ## Run-scoped resource lifecycle
 
-- At run start, record `teamName` as the audit label and `teamCreate: { attempted: false, status: "implicit", splitPane: <bool> }` in team-state. A concurrent run records `status: "skipped", reason: "concurrent-run"`. Populate `lead.sessionId`; the session transcript lives under `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`.
+- At run start, record `teamName` as the audit label in team-state and populate `lead.sessionId`; the session transcript lives under `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`. You do NOT write `teamCreate`: `okstra team dispatch` records the implicit-team marker (`{ attempted: false, status: "implicit" }`) itself, on every dispatch path, because v2.1.178 made that value a constant rather than a judgment. The one marker that IS yours is the concurrent-run decision — a concurrent run records `teamCreate: { attempted: false, status: "skipped", reason: "concurrent-run" }` **before** the first dispatch, and dispatch then leaves it alone.
 - Record the lead pane once with `mkdir -p "<RUN_DIR>/state" && { . "$HOME/.okstra/bin/lib/okstra/tmux-pane.sh" 2>/dev/null && okstra_resolve_caller_pane; } > "<RUN_DIR>/state/lead-pane.id" 2>/dev/null || true`. This is silent setup and must not gate cleanup; the cleanup script protects the lead pane itself.
 - Collect and persist token usage before any live-roster cleanup, including cleanup between batches and the run-end shutdown sequence.
 - Before each new worker batch (and before the next phase's render-bundle), reclaim the prior round's completed teammate panes in two passes, adding `--keep report-writer-worker` to **both** passes while the report writer is in flight. First source the count: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` never kills and prints one `<pane_id>\t<pane_title>` line per pane it would reclaim — count those lines as `<n>`. Then perform the reclaim by running the same command **without** `--list`, and emit the neutral contract's `PROGRESS: phase-batch-cleanup panes=<n>` checkpoint with that count. Call both passes after collecting that round's results and token usage and before the next dispatch, so no in-flight worker pane is caught. This `tmux kill-pane`s the harness teammate panes; `shutdown_request` only idles the agent and never frees the pane, so it stays part of the run-end sequence for roster/token hygiene. In a non-tmux session there are no panes, both passes no-op, and `<n>` is `0` — still emit the checkpoint. The lead pane (read from `<RUN_DIR>/state/lead-pane.id`) is always preserved.

package/runtime/python/okstra_ctl/cmux.py

@@ -473,9 +473,9 @@ def rpc(method: str, params: dict[str, Any]) -> dict[str, Any]:
 def _open_worker_surface(
     workspace: str, placement: Placement, target: PaneGeometry
 ) -> str:
-    before = _surface_ids(workspace)
+    before = open_surface_ids(workspace)
     _create_surface(workspace, placement, target)
-    new_ids = _surface_ids(workspace) - before
+    new_ids = open_surface_ids(workspace) - before
     if len(new_ids) != 1:
         raise RuntimeError(
             f"cmux opened {len(new_ids)} surfaces where exactly one was expected"
@@ -483,12 +483,14 @@ def _open_worker_surface(
     return new_ids.pop()
 
 
-def _surface_ids(workspace: str) -> set[str]:
-    """Every surface UUID in the workspace.
+def open_surface_ids(workspace: str) -> set[str]:
+    """Every surface UUID the workspace currently holds.
 
-    The new surface is identified by diffing this set rather than by translating
-    the `OK surface:N` echo, because `list-pane-surfaces` reports only the
-    focused pane unless given a `--pane`, and the new pane is not focused.
+    Dispatch diffs this set across a create to identify the new surface, rather
+    than translating the `OK surface:N` echo, because `list-pane-surfaces`
+    reports only the focused pane unless given a `--pane`, and the new pane is
+    not focused. Teardown intersects its recorded ids with it to tell a surface
+    that is still open from one that closed earlier in the run.
     """
     return {
         surface_id

package/runtime/python/okstra_ctl/consumers.py

@@ -1,8 +1,9 @@
 """Append-only writer / reader for `consumers.jsonl` under a plan run's task root.
 
-A row's identity for idempotency is the tuple
-    (impl_task_key, stage, status)
-so the same (started / done) record is never duplicated.
+A stage's lifecycle position is the LAST lifecycle row written for it. An append
+is redundant only when it would not move that position, so the same
+(started / done / failed) record is never duplicated, while a `started` that
+re-enters a stage whose last row is terminal does land.
 force_reappend=True 인 보정 append 만 같은 tuple 을 다른 head_commit 으로 재기록할 수 있다."""
 
 from __future__ import annotations
@@ -17,6 +18,15 @@ from .run_context import consumers_mutex
 
 CONSUMERS_FILENAME = "consumers.jsonl"
 
+# The rows that move a stage through its lifecycle. `started` claims the stage;
+# `done` and `failed` both end that claim. `failed` is terminal WITHOUT
+# completion: dependents stay blocked because the stage is not done, but the
+# stage-key occupancy is released so the same stage number can be re-entered by
+# a fix run. Without it a stage whose verifier returned FAIL stays `active`
+# forever — `done` would be the only exit, and writing it would mark a stage
+# carrying a confirmed regression as complete.
+STAGE_LIFECYCLE_STATUSES = ("started", "done", "failed")
+
 
 @dataclass(frozen=True)
 class StageConsumerState:
@@ -71,19 +81,30 @@ def read_stage_consumer_state(
     return stage_consumer_state_from_rows(rows)
 
 
+def last_lifecycle_status_by_stage(
+    rows: List[Dict[str, Any]],
+) -> Dict[int, str]:
+    """stage → 마지막 lifecycle row 의 status. 파일이 append-only 이므로
+    읽기 순서가 곧 시간 순서다."""
+    out: Dict[int, str] = {}
+    for r in rows:
+        stage = r.get("stage")
+        status = r.get("status")
+        if status in STAGE_LIFECYCLE_STATUSES and isinstance(stage, int):
+            out[stage] = status
+    return out
+
+
 def stage_consumer_state_from_rows(rows: List[Dict[str, Any]]) -> StageConsumerState:
     done_rows = [r for r in rows if r.get("status") == "done"]
     done_by_stage = latest_done_by_stage(rows)
-    started = {
-        r["stage"] for r in rows
-        if r.get("status") == "started" and isinstance(r.get("stage"), int)
-    }
+    last_status = last_lifecycle_status_by_stage(rows)
     return StageConsumerState(
         rows=rows,
         done_rows=done_rows,
         done_by_stage=done_by_stage,
         done_stages=set(done_by_stage.keys()),
-        started_stages=started,
+        started_stages={n for n, s in last_status.items() if s == "started"},
         verified_accepted_stages=verified_accepted_stages(rows),
         pr_covered_stages=pr_covered_stages(rows),
     )
@@ -92,8 +113,9 @@ def stage_consumer_state_from_rows(rows: List[Dict[str, Any]]) -> StageConsumerS
 def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
                     status: str, force_reappend: bool = False,
                     **fields: Any) -> None:
-    if status not in ("started", "done"):
-        raise ValueError(f"status must be 'started' or 'done', got: {status!r}")
+    if status not in STAGE_LIFECYCLE_STATUSES:
+        allowed = " or ".join(repr(s) for s in STAGE_LIFECYCLE_STATUSES)
+        raise ValueError(f"status must be {allowed}, got: {status!r}")
     with consumers_mutex(plan_run_root):
         if not _equivalent_row_exists(plan_run_root, impl_task_key, stage,
                                       status, force_reappend,
@@ -105,16 +127,23 @@ def append_consumer(plan_run_root: Path, *, impl_task_key: str, stage: int,
                 **fields,
             }
             _append_row(plan_run_root, record)
-    # done 은 점유 해제 이벤트이기도 하다 — 중복 append(no-op)에서도 풀어야
+    # 종결 status 는 점유 해제 이벤트이기도 하다 — 중복 append(no-op)에서도 풀어야
     # release 없이 done 만 기록된 과거 run 의 잔존 점유가 다음 호출에서 치유된다.
     if status == "done":
         _release_stage_reservation(impl_task_key, stage)
+    elif status == "failed":
+        _release_stage_occupancy_keeping_branch(impl_task_key, stage)
 
 
 def _equivalent_row_exists(plan_run_root: Path, impl_task_key: str, stage: int,
                            status: str, force_reappend: bool,
                            head_commit: Any) -> bool:
-    for row in read_consumers(plan_run_root):
+    rows = read_consumers(plan_run_root)
+    # 같은 tuple 이 이미 있어도, 그 뒤에 다른 lifecycle row 가 왔다면 이 append 는
+    # stage 의 현재 위치를 옮기는 새 사실이다 — fix run 의 started 재기록이 그 경우다.
+    if last_lifecycle_status_by_stage(rows).get(stage) != status:
+        return False
+    for row in rows:
         if (row.get("impl_task_key") == impl_task_key
                 and row.get("stage") == stage
                 and row.get("status") == status):
@@ -125,22 +154,42 @@ def _equivalent_row_exists(plan_run_root: Path, impl_task_key: str, stage: int,
     return False
 
 
-def _release_stage_reservation(impl_task_key: str, stage: Any) -> None:
-    """done 이 기록된 stage 의 worktree-registry 점유(stage-key)를 해제한다.
-
-    release 는 점유 표시만 푼다 — worktree 디렉토리·브랜치는 보존된다.
-    registry 좌표는 TASK_KEY(`project:group:task`) 각 segment 의
-    safe-segment 와 같다(stage 예약이 그렇게 만들어진다). 형식이 다르면
-    점유 주체가 아니므로 건너뛴다."""
+def _stage_registry_coords(
+    impl_task_key: str, stage: Any,
+) -> Optional[tuple[str, str, str]]:
+    """stage 점유의 registry 좌표. TASK_KEY(`project:group:task`) 각 segment 의
+    safe-segment 와 같다(stage 예약이 그렇게 만들어진다). 형식이 다르면 점유
+    주체가 아니므로 None."""
     parts = impl_task_key.split(":")
     if len(parts) != 3 or not isinstance(stage, int):
-        return
+        return None
     from .ids import _safe_fs_segment
+    return (_safe_fs_segment(parts[0]), _safe_fs_segment(parts[1]),
+            _safe_fs_segment(parts[2]))
+
+
+def _release_stage_reservation(impl_task_key: str, stage: Any) -> None:
+    """done 이 기록된 stage 의 worktree-registry 점유(stage-key)를 해제하고
+    브랜치 슬롯도 반납한다. worktree 디렉토리·브랜치 자체는 보존된다."""
+    coords = _stage_registry_coords(impl_task_key, stage)
+    if coords is None:
+        return
     from . import worktree_registry
-    worktree_registry.release(
-        _safe_fs_segment(parts[0]), _safe_fs_segment(parts[1]),
-        _safe_fs_segment(parts[2]), stage_number=stage,
-    )
+    worktree_registry.release(*coords, stage_number=stage)
+
+
+def _release_stage_occupancy_keeping_branch(
+    impl_task_key: str, stage: Any,
+) -> None:
+    """failed 이 기록된 stage 의 점유 표시만 푼다 — 브랜치 슬롯은 유지한다.
+
+    fix run 은 같은 stage 워크트리·브랜치로 재진입하므로 슬롯이 계속 필요하다
+    (`worktree_registry.release_status` 의 "slot is still needed" 경우)."""
+    coords = _stage_registry_coords(impl_task_key, stage)
+    if coords is None:
+        return
+    from . import worktree_registry
+    worktree_registry.release_status(*coords, stage_number=stage)
 
 
 def _append_row(plan_run_root: Path, record: Dict[str, Any]) -> None:

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -27,7 +27,7 @@ from .dispatch_state import (
     require_string as _require_string,
     resolve_project_path as _resolve_project_path,
     resolve_required_path as _resolve_required_path,
-    set_dispatch_mode as _set_dispatch_mode,
+    record_dispatch_facts as _record_dispatch_facts,
     transition_worker_status as _transition_worker_status,
     string_list as _string_list,
     string_value as _string_value,
@@ -213,14 +213,14 @@ def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
                 "instead of running them concurrently; dispatch panes with "
                 "wait=False"
             )
-        _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.jobs))
+        _record_dispatch_facts(plan.team_state_path, _dispatch_mode(plan.jobs))
         for job in plan.jobs:
             result = _dispatch_job_with_retry(plan, job)
             if result != 0:
                 return result
         return 0
     handles = [_spawn_job(plan, job, 1) for job in plan.jobs]
-    _set_dispatch_mode(plan.team_state_path, _mode_from_handles(handles))
+    _record_dispatch_facts(plan.team_state_path, _mode_from_handles(handles))
     return 0
 
 

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -275,12 +275,32 @@ def _utc_timestamp(value: str | datetime | None) -> str:
     return instant.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
-def set_dispatch_mode(team_state_path: Path, dispatch_mode: str) -> None:
+def record_dispatch_facts(team_state_path: Path, dispatch_mode: str) -> None:
+    """Persist the team-state facts okstra owns at dispatch time.
+
+    `dispatchMode` names the backend the workers actually went out on.
+    `teamCreate` is the implicit-team audit marker: Claude Code v2.1.178 removed
+    the TeamCreate tool, so `{attempted: false, status: "implicit"}` is a
+    constant of a non-concurrent run rather than a lead judgment. validate-run
+    requires it once any worker has been dispatched, and Phase 7 token
+    attribution reads it to locate worker sessions — leaving it for the lead to
+    hand-write failed every dispatch path whose host adapter does not spell the
+    rule out. A marker the launch prompt pre-recorded (the concurrent-run
+    `skipped` decision) belongs to that run and is never overwritten.
+    """
     payload = load_json_object(team_state_path, "team-state")
     payload["dispatchMode"] = dispatch_mode
+    if not _has_recorded_team_create(payload):
+        payload["teamCreate"] = {"attempted": False, "status": "implicit"}
     write_json(team_state_path, payload)
 
 
+def _has_recorded_team_create(team_state: Mapping[str, Any]) -> bool:
+    existing = team_state.get("teamCreate")
+    return (isinstance(existing, dict)
+            and bool(str(existing.get("status") or "").strip()))
+
+
 # --- job facts ----------------------------------------------------------------
 
 def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:

package/runtime/python/okstra_ctl/team.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 
 import argparse
 import json
+import subprocess
 import sys
 from pathlib import Path
 from typing import Any, Mapping, Sequence
@@ -202,11 +203,11 @@ def _reclaimable_panes(
 ) -> list[dict[str, str]]:
     """Everything this run owns and may close.
 
-    Under cmux the recorded ids are the whole list. There is no per-pane tag API
-    to sweep with, and scanning by title would be worse than nothing: cmux labels
-    its own agent surfaces with the same glyph okstra's tmux cleanup treats as a
-    teammate marker, so a sweep could close the lead. Only surfaces okstra
-    created are recorded, so only those can be closed.
+    Under cmux the recorded ids are the only candidates. There is no per-pane tag
+    API to sweep with, and scanning by title would be worse than nothing: cmux
+    labels its own agent surfaces with the same glyph okstra's tmux cleanup
+    treats as a teammate marker, so a sweep could close the lead. Only surfaces
+    okstra created are recorded, so only those can be closed.
     """
     seen: set[str] = set()
     panes: list[dict[str, str]] = []
@@ -214,13 +215,36 @@ def _reclaimable_panes(
         if isinstance(record, dict):
             _append_pane(panes, seen, str(record.get("paneId", "")), "worker")
     if _is_cmux_run(manifest):
-        return panes
+        return _still_open_surfaces(panes)
     lead_pane = tmux.resolve_caller_pane()
     for pane in tmux.list_run_panes(run_dir, lead_pane=lead_pane):
         _append_pane(panes, seen, pane.pane_id, pane.kind)
     return panes
 
 
+def _still_open_surfaces(panes: list[dict[str, str]]) -> list[dict[str, str]]:
+    """The recorded surfaces cmux still shows.
+
+    `workerDispatches` is append-only and nothing prunes it, so a surface closed
+    at an earlier round boundary stays recorded for the rest of the run. Taking
+    the ledger as the residual set makes the run-end cleanup gate offer to close
+    panes that left the screen rounds ago, on a workspace holding none.
+
+    An unreachable cmux keeps the ledger rather than reporting an empty set: a
+    wedged app is not evidence that the surfaces are gone, closing one that
+    already went away is a silent no-op, and skipping a live one strands it on
+    the user's screen for the rest of the session.
+    """
+    workspace = cmux.resolve_lead_workspace()
+    if not workspace:
+        return panes
+    try:
+        open_ids = cmux.open_surface_ids(workspace)
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return panes
+    return [pane for pane in panes if pane["paneId"] in open_ids]
+
+
 def _append_pane(panes: list[dict[str, str]], seen: set[str], pane_id: str, kind: str) -> None:
     if pane_id and pane_id not in seen:
         panes.append({"paneId": pane_id, "kind": kind})

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -49,6 +49,7 @@ _NON_BODY_PREFIXES = (
     "Assigned worker prompt history path:",
     "**Worker Preamble Path:**",
     _EVIDENCE_LEDGER_HEADER_PREFIX,
+    "**Evidence citations:**",
     *ERRORS_PATH_HEADERS,
     "**Read scope:**",
     "**File write mode:**",

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -38,6 +38,23 @@ READ_SCOPE_HEADER = (
 )
 EVIDENCE_LEDGER_HEADER = "**Evidence ledger:** required-v1"
 
+# `required-v1` is a mode name; what it demands lives in the Worker Preamble's
+# "Evidence read ledger". But the preamble reaches the worker as a *path* —
+# eager-include inlines only the role sidecars — so a worker that never opens it
+# gets the switch without the rule, and Phase 7 then fails its result over a
+# citation form the prompt never stated. Restating it inline is what
+# READ_SCOPE_HEADER does, for the same reason: the rule has to be in front of the
+# worker before its first citation, not in a file it may never read.
+EVIDENCE_CITATION_HEADER = (
+    "**Evidence citations:** Append one `- Evidence read: <project-relative "
+    "path, no line suffix>` row to the audit sidecar for every file you open as "
+    "claim evidence, and cite that file in your result with backticks, a line "
+    "suffix, and the identical project-relative path — `src/config/env.ts:1-22`, "
+    "never the bare filename `env.ts:1-22`. A bare filename does not match its "
+    "ledger row and fails exactly like a file you never opened, however many "
+    "times you cited the full path earlier."
+)
+
 # `agy`'s write tool validates the target against the Gemini artifact store
 # whenever the model attaches ArtifactMetadata, and rejects every path outside
 # `~/.gemini/antigravity-cli/brain/<uuid>/`. All okstra worker outputs live under
@@ -103,7 +120,7 @@ def worker_prompt_headers(
             f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}"
         )
     if dispatch_kind == "initial" and plan.audience != "report-writer":
-        headers.append(EVIDENCE_LEDGER_HEADER)
+        headers += [EVIDENCE_LEDGER_HEADER, EVIDENCE_CITATION_HEADER]
     headers.extend([
         f"**Errors log path:** {errors_log_path}",
         f"**Errors sidecar path:** {errors_sidecar_path}",

package/runtime/python/okstra_ctl/worktree.py

@@ -219,7 +219,7 @@ def resolve_stage_worktree_decision(
     safe_task = _safe_segment(task_id_segment)
     existing = worktree_registry.lookup(
         safe_project, safe_group, safe_task, stage_number=stage_number)
-    if existing is not None and existing.status == "active":
+    if existing is not None and _stage_entry_is_reusable(existing):
         return StageWorktreeDecision(
             status="reused",
             path=existing.worktree_path,
@@ -237,6 +237,22 @@ def resolve_stage_worktree_decision(
     )
 
 
+def _stage_entry_is_reusable(entry: worktree_registry.WorktreeEntry) -> bool:
+    """Whether a registered stage worktree can be entered by this run.
+
+    `active` is the live-run case. `released` with the directory still on disk is
+    the fix-run case: a stage whose verifier returned FAIL records a `failed`
+    consumers row, which frees the occupancy but deliberately keeps the worktree
+    and its branch as the reviewable stack. Re-entry MUST reuse that tree —
+    provisioning anew refuses on the existing path and branch. After whole-task
+    final-verification removes the directory the entry stops being reusable, so
+    the stage provisions from scratch.
+    """
+    if entry.status == "active":
+        return True
+    return entry.status == "released" and Path(entry.worktree_path).is_dir()
+
+
 def _safe_segment(value: str) -> str:
     """Sanitise a single path/branch segment.
 

package/runtime/schemas/final-report-v1.0.schema.json

@@ -5042,6 +5042,10 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "withheld": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },

package/runtime/schemas/final-report-v2.0.schema.json

@@ -7114,6 +7114,10 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "withheld": {
+          "type": "string",
+          "minLength": 1
         }
       }
     },

package/runtime/skills/okstra-run/SKILL.md

@@ -320,6 +320,9 @@ If the anchor (`implementation_base_commit`) is reported unresolvable, run the s
 ### Next stage not yet ready — normal termination (not an exception gate)
 Because of the dependency closure, the chain queue **may include a stage that another implementation run has occupied as started/reserved.** That stage's `render-bundle` is rejected with `--stage N already in progress or reserved by another run` (StageTargetError). This is **not** an exception gate needing human judgment but a "next stage not yet ready" situation. On this rejection, **terminate the chain normally** and report the remaining queue to the user (e.g. `remaining queue: stage 4, 5 — resume with okstra-run after occupancy is released`). This is a different branch from the exception gate below (data corruption·concurrent-occupancy conflict confirmation).
 
+### Stage ended FAIL — stop the queue and report (not an exception gate)
+When a stage's synthesised verdict is `FAIL`, Phase 6 writes no carry sidecar and appends a `status:"failed"` row in place of `done` (`prompts/profiles/_implementation-deliverable.md` "Lead post-stage persistence"). **Stop the queue at that stage** and report the failed stage, its report path, and the remaining queue (e.g. `stage 1 FAIL — remaining queue: stage 2, 3, 5; re-enter with okstra-run --stage 1 after the fix`). Do **not** continue to the next stage even when that stage is dependency-independent: an unattended chain that keeps building past a confirmed regression stacks later work on top of it. The `failed` row releases the stage's occupancy, so `--stage <N>` re-enters the same stage on its preserved worktree and branch — there is nothing to unblock by hand.
+
 ### Exception gate during chaining
 If `render-bundle` raises Step 5's concurrent-run conflict detection (concurrent-run branch) or git stale-SHA reconciliation (git-reconcile branch), **stop the chain at that stage** and present the gate to the user exactly as Step 5 prescribes. Once the user resolves the gate, resume the chain in place (continue with the remaining queue). Data corruption·concurrent-occupancy conflicts are confirmed by a human — this is the safety boundary of unattended chaining. (Unlike the "not ready" rejection above, these two branches do not discard the queue; they wait for user resolution.)
 <!-- END FRAGMENT: host-orchestration-implementation -->
@@ -341,12 +344,12 @@ Queue = the topologically-sorted stage list from splitting `orchestration.chainS
 
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become the host-native Okstra lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
-3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage.
+3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage. A `status:"failed"` row instead of `done` means the stage ended `FAIL` — reclaim the panes the same way, then stop the queue per "Stage ended FAIL" above.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.
 
-The two branches that end or pause the queue — "Next stage not yet ready" and "Exception gate during chaining" — are in the host orchestration rules block above.
+The three branches that end or pause the queue — "Next stage not yet ready", "Stage ended FAIL", and "Exception gate during chaining" — are in the host orchestration rules block above.
 
 ## Persisting the PR template scope (release-handoff)
 

package/runtime/templates/implementation-worker-preamble.md

@@ -51,9 +51,10 @@ Every initial implementation prompt begins with these generated common anchors i
 6. `**Worker Error Contract Path:** <absolute-path>`
 7. `**Coding preflight pack:** <absolute-path>`
 8. `**Evidence ledger:** required-v1`
-9. `**Errors log path:** <absolute-path>`
-10. `**Errors sidecar path:** <absolute-path>`
-11. `**Read scope:** <allowlist>`
+9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
+10. `**Errors log path:** <absolute-path>`
+11. `**Errors sidecar path:** <absolute-path>`
+12. `**Read scope:** <allowlist>`
 
 The implementation body additionally carries `**Worktree:**` and its role-sidecar inputs. Do not synthesize any missing path.
 

package/runtime/templates/reports/final-report.template.md

@@ -674,6 +674,9 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 ### 5.7.5 Stage Sidecar Evidence
 
 - Stage: `{{ implementation.stageSidecarEvidence.stageNumber }}` — {{ implementation.stageSidecarEvidence.stageTitle }}
+{% if implementation.stageSidecarEvidence.withheld -%}
+- Carry sidecar **withheld** — not written to `carry/stage-{{ implementation.stageSidecarEvidence.stageNumber }}.json`: {{ implementation.stageSidecarEvidence.withheld }}
+{% endif -%}
 - Carry sidecar JSON:
   ```json
   {{ implementation.stageSidecarEvidence.carryJson | indent(2) }}

package/runtime/templates/worker-prompt-preamble.md

@@ -43,9 +43,10 @@ Every initial analysis prompt begins with these generated anchors in this exact
 6. `**Worker Preamble Path:** <absolute-path>` — selects this analysis preamble.
 7. `**Worker Error Contract Path:** <absolute-path>` — shared by every initial audience.
 8. `**Evidence ledger:** required-v1`
-9. `**Errors log path:** <absolute-path>`
-10. `**Errors sidecar path:** <absolute-path>`
-11. `**Read scope:** <allowlist>`
+9. `**Evidence citations:** <rule>` — the ledger-row and citation-path rule of §"Evidence read ledger", restated inline so it is in front of you before your first citation.
+10. `**Errors log path:** <absolute-path>`
+11. `**Errors sidecar path:** <absolute-path>`
+12. `**Read scope:** <allowlist>`
 
 `final-verification` additionally carries its six verification-target anchors. `improvement-discovery` carries `**Phase 1.5 Grilling Log:**`. Reverify prompts are lightweight and do not use this preamble.
 

package/runtime/validators/validate-run.py

@@ -5061,6 +5061,13 @@ def _validate_stage_carry_sidecar_exists(
     stage = evidence.get("stageNumber")
     if not isinstance(stage, int):
         return
+    # A stage whose verifier returned FAIL must NOT persist its carry: the carry
+    # file is what marks the stage `done`, and doing that would stack the next
+    # stage on a confirmed regression. Such a run states the reason in
+    # `withheld` and records a `failed` consumers row instead, so the absent
+    # file is the correct outcome, not a gap.
+    if str(evidence.get("withheld") or "").strip():
+        return
     # Carry sidecars are stage-SHARED: the next stage's carry-in and
     # `consumers.backfill_done_from_carry` glob them without knowing the
     # producing run's layout. `RunRef.carry()` owns that flat-vs-staged rule;