okstra 0.166.2 → 0.167.0

package/README.md

@@ -225,7 +225,7 @@ Major workflow changes added to `main` after 0.8.0:
 
 - **Automatic isolated worktrees for every task type** — During preparation, `okstra-ctl` runs `git worktree add ~/.okstra/worktrees/<project-id>/<task-group-segment>/<task-id-segment>` once per task key to create an isolated working tree and a `<work-category-namespace>/<task-id-segment>` branch (for example, `feature/dev-9436` or `fix/dev-7311`). The user chooses the base ref with `--base-ref`, using the same choices as the release-handoff PR base picker: `main`, `dev`, `staging`, `preprod`, `prod`, or a custom value. It is required in the first phase; the okstra-run skill collects it through `AskUserQuestion`, while non-interactive callers must pass `--base-ref` explicitly. Later **non-`implementation`** phases for the same task key (`requirements-discovery` → `error-analysis` → `implementation-planning` → `final-verification` → `release-handoff`) reuse the same path and branch. `implementation` runs are **stage-isolated**: each run executes one stage in its own `.../<task>/stage-<N>/` worktree on a `<work-category-namespace>/<task>-s<N>` branch, so independent stages with `depends-on (none)` can run concurrently without sharing a tree. The registry reserves both task keys and **stage keys** with flock. Provisioning is skipped when the caller is already in another worktree or project_root is not a Git repository; stage isolation degrades to a flat path in those cases. Manual cleanup: `git worktree remove <path>` → `git branch -D <branch>` plus release/removal of the registry entry. Details: [`docs/architecture.md`](docs/architecture.md), in the *Task type* section, and [`docs/cli.md#--executor`](docs/cli.md#--executor).
 - **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
-- **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/prd/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
+- **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/pr/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
 - **Host-aware lead adapters** — `okstra-run` resolves the current harness through the same dynamic host registry used by the terminal front door. Claude Code, Codex, Antigravity, Grok, and Kimi keep their matching provider assignment native; `external` remains the explicit all-CLI host. Host and provider are separate axes, and every non-native worker assignment uses its provider's registered CLI wrapper. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.

package/docs/pr-template-usage.md

@@ -19,8 +19,8 @@ If the file named in any of the 4 steps does not exist, it fails immediately wit
 
 ## 2. Default candidate paths
 
-1. `$OKSTRA_SKILLS_DIR/templates/prd/pr-body.template.md` — only when the `OKSTRA_SKILLS_DIR` environment variable is set.
-2. `~/.claude/skills/templates/prd/pr-body.template.md` — the standard location `npx okstra install` installs to.
+1. `$OKSTRA_SKILLS_DIR/templates/pr/pr-body.template.md` — only when the `OKSTRA_SKILLS_DIR` environment variable is set.
+2. `~/.claude/skills/templates/pr/pr-body.template.md` — the standard location `npx okstra install` installs to.
 
 The candidates are tried in priority order, and if all are absent it ends with an explicit error as follows.
 
@@ -28,7 +28,7 @@ The candidates are tried in priority order, and if all are absent it ends with a
 
 ## 3. The original inside the source repository
 
-- [`templates/prd/pr-body.template.md`](../templates/prd/pr-body.template.md) — the original that `npx okstra install` copies to the §2 default location. To change the copy, edit this file and install again.
+- [`templates/pr/pr-body.template.md`](../templates/pr/pr-body.template.md) — the original that `npx okstra install` copies to the §2 default location. To change the copy, edit this file and install again.
 
 ## 4. Configuration commands — persistence
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.166.2",
+  "version": "0.167.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.166.2",
-  "builtAt": "2026-08-11T13:40:27.396Z",
+  "package": "0.167.0",
+  "builtAt": "2026-08-12T03:32:48.888Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -63,7 +63,7 @@ persisted prompt lacks the heading `Coding-conventions preflight`
 
 ## Stage execution contract (this run owns one stage)
 
-- **Sidecar evidence writer (BLOCKING).** When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object with **exactly** these fields (spec `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2), as a fenced ```json``` block in the worker result under the heading `### Stage Carry Evidence`, and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The schema is inlined here because a CLI-wrapper executor runs in its own process and never receives a native worker definition — a carry emitted with an ad-hoc shape (`stage`/`files`/`validation`) is a `contract-violated` gap the lead must rewrite by hand:
+- **Sidecar evidence writer (BLOCKING).** You emit the evidence; you do NOT write the file. `carry/stage-<N>.json` sits inside your task scope, so nothing stops your tools from creating it — but the lead's post-stage persistence is what writes it, and only on a non-`FAIL` verdict. Your own gate passes before the verifier's, so a file you write exists exactly when the verdict may still withhold it: the lead then refuses to overwrite, the report says the sidecar was withheld, and the disk disagrees with the record. Emit the block and stop. When this stage's Stage Validation `post` commands all succeed, the Executor MUST emit a JSON object with **exactly** these fields (spec `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2), as a fenced ```json``` block in the worker result under the heading `### Stage Carry Evidence`, and the lead MUST persist it to `runs/<impl-task-key>/carry/stage-<N>.json`. The schema is inlined here because a CLI-wrapper executor runs in its own process and never receives a native worker definition — a carry emitted with an ad-hoc shape (`stage`/`files`/`validation`) is a `contract-violated` gap the lead must rewrite by hand:
 
   ```json
   {

package/runtime/python/okstra_ctl/adapters/hosts/antigravity/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Antigravity host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. |
+| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through their status sidecars, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh native worker or CLI wrapper attempt according to the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Perform host or process cleanup only for resources owned by this run. |

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

@@ -136,7 +136,7 @@ For a `host-text` mapping, render each numbered item as its option label followe
 | `read_artifacts` | Use the host file-read primitive and preserve the core contract's read order. |
 | `write_artifact` | Use the host file-write primitive only for paths authorized by the active lifecycle phase. |
 | `prompt_user` | Use the native question tool for approvals and clarifications; do not infer an answer from silence. |
-| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. |
+| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
 | `redispatch_worker` | Dispatch a fresh `Agent(...)` session with the same prompt plus the core reverify/retry reason. |
 | `shutdown_workers` | For each confirmed-complete worker selected for cleanup, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to idle the roster member **and** call `TaskStop(task_id: "<name>")` to stop its background task. Both are required; neither subsumes the other. |

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current host's file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await native host workers through the host primitive and CLI workers through synchronous dispatch, then verify team-state terminal records and Result Paths for both. |
 | `redispatch_worker` | Start a fresh native worker or `okstra codex-dispatch` attempt according to the persisted assignment's `runner`, and record the retry/reverify dispatch kind. |
 | `shutdown_workers` | Perform process cleanup when a wrapper remains live; otherwise this operation is a no-op recorded in state. |

package/runtime/python/okstra_ctl/adapters/hosts/external/relay.md

@@ -77,7 +77,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current host's file or shell interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and require an explicit approval or clarification response. |
-| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
 | `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
 | `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |

package/runtime/python/okstra_ctl/adapters/hosts/grok/relay.md

@@ -76,7 +76,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Grok host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
-| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |

package/runtime/python/okstra_ctl/adapters/hosts/kimi/relay.md

@@ -76,7 +76,7 @@ Render every numbered item as its option label followed by its description verba
 | `read_artifacts` | Read the manifest-provided paths through the current Kimi host file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the current host text interface and wait for an explicit answer. |
-| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. |
+| `dispatch_worker` | Follow each persisted assignment's `runner` and use the common host dispatch boundary. **Not in a cmux run:** when the run manifest's `terminalBackend` is `cmux-pane`, `prompts/lead/adapters/cmux.md` overrides this row — start every worker with `okstra team dispatch`, this host's native path included, so okstra owns the panes and the user can watch the work. |
 | `await_workers` | Await through the selected common dispatch backend, then verify terminal state and Result Paths. |
 | `redispatch_worker` | Start a fresh attempt from the persisted assignment and record the supplied dispatch kind. |
 | `shutdown_workers` | Clean up only host or process resources owned by this run. |

package/runtime/python/okstra_ctl/consumers.py

@@ -27,6 +27,11 @@ CONSUMERS_FILENAME = "consumers.jsonl"
 # carrying a confirmed regression as complete.
 STAGE_LIFECYCLE_STATUSES = ("started", "done", "failed")
 
+# The lead has already ruled on a stage whose last row is one of these — `done`
+# closed it, `failed` deliberately did not. Neither may be re-derived from disk:
+# closing a stage is the lead's verdict gate, not a file's existence.
+_LEAD_SETTLED_STATUSES = ("done", "failed")
+
 
 @dataclass(frozen=True)
 class StageConsumerState:
@@ -308,16 +313,29 @@ def _carry_dir(plan_run_root: Path) -> Path:
 def backfill_done_from_carry(plan_run_root: Path) -> int:
     """Recover missing `done` rows from carry sidecars (carry is SSOT).
 
-    For every `runs/implementation/carry/stage-<N>.json` that is complete and
-    not already recorded as `done` in consumers.jsonl, append a `done` row with
-    the head commit read from the carry. Returns the number of rows recovered.
-    Stages with no carry or an unfinished carry are skipped, so the dependency
-    gate still legitimately blocks genuinely-unstarted stages."""
+    Recovers the crash window between the lead writing the carry file and
+    appending the `done` row: for every `runs/implementation/carry/stage-<N>.json`
+    that is complete and whose stage has no terminal row yet, append a `done` row
+    with the head commit read from the carry. Returns the number of rows
+    recovered. Stages with no carry or an unfinished carry are skipped, so the
+    dependency gate still legitimately blocks genuinely-unstarted stages.
+
+    A stage the lead has already ruled on is never re-derived from disk. That
+    includes `failed`: the executor emits its carry evidence when its own Tier 1/2
+    validation passes, which happens BEFORE the verifier's gate, so a carry file
+    exists for exactly the runs where the verifier then returned `FAIL`. Reading
+    the file as completion would promote a stage carrying a confirmed regression
+    to `done` and let its dependents proceed — and it would contradict this
+    module's own rule that a stage's position is its last lifecycle row."""
     carry_dir = _carry_dir(plan_run_root)
     if not carry_dir.is_dir():
         return 0
     existing = read_consumers(plan_run_root)
-    done_stages = {r.get("stage") for r in existing if r.get("status") == "done"}
+    settled_stages = {
+        stage
+        for stage, status in last_lifecycle_status_by_stage(existing).items()
+        if status in _LEAD_SETTLED_STATUSES
+    }
     key_by_stage: Dict[Any, str] = {}
     fallback_key = ""
     for r in existing:
@@ -335,7 +353,7 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
         if not isinstance(carry, dict):
             continue
         stage = _carry_stage_number(carry, cf.name)
-        if stage is None or stage in done_stages:
+        if stage is None or stage in settled_stages:
             continue
         if not _carry_is_complete(carry):
             continue
@@ -358,6 +376,6 @@ def backfill_done_from_carry(plan_run_root: Path) -> int:
             carry_path=carry_path,
             source="carry-backfill",
         )
-        done_stages.add(stage)
+        settled_stages.add(stage)
         recovered += 1
     return recovered

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -31,6 +31,7 @@ from .dispatch_state import (
     transition_worker_status as _transition_worker_status,
     string_list as _string_list,
     string_value as _string_value,
+    TEARDOWN_BEFORE_TERMINAL_REASON,
     utc_now as _utc_now,
     validate_dispatch_prompts as _validate_dispatch_prompts,
     worker_jobs_from_file as _worker_jobs_from_file,
@@ -231,6 +232,7 @@ def await_dispatches(
     timeout_seconds: int | None = None,
     heartbeat_seconds: int = 30,
 ) -> int:
+    _correct_teardown_marked_dispatches(plan)
     deadline = time.monotonic() + timeout_seconds if timeout_seconds is not None else None
     last_heartbeat = 0.0
     while True:
@@ -643,6 +645,35 @@ def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
     )
 
 
+def _correct_teardown_marked_dispatches(plan: DispatchPlan) -> None:
+    """Let the wrapper's own exit settle a record teardown wrote off.
+
+    `okstra team teardown` marks every non-terminal dispatch `error` — right for a
+    worker it killed, wrong for one that had already exited while its record was
+    still `running`, which happens when the lead awaited by polling artifacts
+    instead of `team await` (the component that transitions the record). The run
+    then reports `error` for workers whose wrapper exited 0 with every output in
+    place, and nothing could undo it: teardown's `error` drops the record out of
+    the running set this function's caller scans, so a later await never saw it.
+
+    Only a success is corrected, and only from process-level evidence — the
+    wrapper's terminal status plus its exit code, judged by the same
+    `_outcome_from_status` path every other dispatch goes through. A non-zero exit
+    or a missing output stays an error, and no retry is spawned: teardown has
+    already taken the panes, so re-running here would start work nobody is
+    watching.
+    """
+    for record in _teardown_marked_dispatches(plan.team_state_path):
+        status_path = _optional_path(record.get("statusSidecarPath"))
+        status = read_wrapper_status(status_path) if status_path else None
+        if status is None or not status.is_terminal:
+            continue
+        outcome = _outcome_from_status(record, status)
+        if outcome.returncode != 0 or outcome.missing_completion_paths or outcome.timeout:
+            continue
+        _finish_record(plan, record, outcome)
+
+
 def _advance_running_dispatches(plan: DispatchPlan, records: Sequence[Mapping[str, Any]]) -> None:
     for record in records:
         status_path = _optional_path(record.get("statusSidecarPath"))
@@ -811,6 +842,22 @@ def _update_dispatch_status(
     _write_json(team_state_path, payload)
 
 
+def _teardown_marked_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
+    """Records `okstra team teardown` wrote off, matched by its own reason string
+    so a genuine dispatch error is never mistaken for one."""
+    payload = _load_json_object(team_state_path, "team-state")
+    dispatches = payload.get("workerDispatches")
+    if not isinstance(dispatches, list):
+        return []
+    return [
+        record
+        for record in dispatches
+        if isinstance(record, dict)
+        and record.get("status") == "error"
+        and _string_value(record.get("reason")) == TEARDOWN_BEFORE_TERMINAL_REASON
+    ]
+
+
 def _running_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
     payload = _load_json_object(team_state_path, "team-state")
     dispatches = payload.get("workerDispatches")

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -58,6 +58,12 @@ def detect_terminal_backend() -> str:
 LIVENESS_AUDIT_HEARTBEAT = "audit-heartbeat"
 LIVENESS_WRAPPER_STATUS = "wrapper-status"
 
+# `okstra team teardown` stamps this on a dispatch it wrote off, and a later
+# `okstra team await` matches it to tell those apart from a genuine dispatch
+# error before letting the wrapper's own exit settle them. Two sides of one fact,
+# so the string lives here rather than in whichever module wrote it first.
+TEARDOWN_BEFORE_TERMINAL_REASON = "teardown before terminal status"
+
 # The worktree argument grants the wrapper `--add-dir` write access outside
 # project-root. Only the phases whose workers mutate a stage worktree get it;
 # analysis phases write their artifacts under project-root (see the contract in

package/runtime/python/okstra_ctl/pr_template.py

@@ -6,7 +6,7 @@ release-handoff 단계에서 lead 가 PR 본문을 작성할 때 사용하는
     1. per-run override (okstra-run Step 6 에서 입력)
     2. project: <project_root>/.okstra/project.json 의 ``prTemplatePath``
     3. global:  ~/.okstra/config.json 의 ``prTemplatePath``
-    4. default: ``$OKSTRA_HOME/templates/prd/pr-body.template.md`` (구버전
+    4. default: ``$OKSTRA_HOME/templates/pr/pr-body.template.md`` (구버전
        ``~/.claude/skills/...`` 후보는 backward-compat 로 유지)
 
 경로는 절대경로 또는 ``~`` 시작 경로를 권장한다. 상대경로일 경우 project

package/runtime/python/okstra_ctl/team.py

@@ -19,6 +19,7 @@ from . import tmux
 from .adapters.dispatch import provider_worker_wrappers
 from .adapters.dispatch.cmux import dispatch_port_for_terminal_backend
 from .application.dispatch_assignments import dispatch_assignments
+from .dispatch_state import TEARDOWN_BEFORE_TERMINAL_REASON
 from .dispatch_core import (
     BACKEND_CMUX_PANE,
     BACKEND_TMUX_PANE,
@@ -256,7 +257,7 @@ def _mark_teardown_errors(team_state_path: Path) -> None:
     for record in payload.get("workerDispatches", []):
         if isinstance(record, dict) and record.get("status") not in _TERMINAL_STATUSES:
             record["status"] = "error"
-            record["reason"] = "teardown before terminal status"
+            record["reason"] = TEARDOWN_BEFORE_TERMINAL_REASON
     _write_json(team_state_path, payload)
 
 

package/runtime/python/okstra_ctl/worker_audit_ledger.py

@@ -55,6 +55,12 @@ def _looks_like_file_path(path: str) -> bool:
         return False
     if re.fullmatch(r"[0-9a-fA-F]{7,64}", path):
         return False
+    # A dotted name is the usual filename signal, and an IPv4 literal is dots and
+    # digits too. `127.0.0.1:13306` in a Read-only command log is a host and port —
+    # the worker cannot record an Evidence read of it, so reading it as a citation
+    # fails the run over something it has no way to satisfy.
+    if re.fullmatch(r"\d{1,3}(?:\.\d{1,3}){3}", path):
+        return False
     return (
         "/" in path
         or "." in Path(path).name

package/runtime/skills/okstra-setup/references/project-config.md

@@ -155,7 +155,7 @@ overwriting silently.
 ## D. Project PR body template (release-handoff)
 
 `release-handoff` fills the PR body from a template — by default
-`~/.okstra/templates/prd/pr-body.template.md`. Most projects want their own
+`~/.okstra/templates/pr/pr-body.template.md`. Most projects want their own
 (e.g. `.github/PULL_REQUEST_TEMPLATE.md`). Pre-registration during setup is
 opt-in; the same prompt is offered again on the first `release-handoff` run,
 so deferring (`Later`) is safe.

package/runtime/validators/validate-run.py

@@ -693,6 +693,58 @@ def _is_legal_concurrent_run_skip(
     )
 
 
+def _validate_cmux_workers_were_dispatched_by_okstra(
+    team_state: dict,
+    workers: list,
+    dispatched_statuses: set[str],
+    failures: list[str],
+) -> None:
+    """Under cmux, okstra owns the worker panes — so it must have started them.
+
+    `prompts/lead/adapters/cmux.md` overrides the host relay's worker-dispatch
+    mapping: every lead goes through `okstra team dispatch`, a Claude Code lead
+    included. A lead that follows its own relay instead and starts the worker
+    in-process gets no pane, and the user cannot see the work — which is the whole
+    point of the adapter owning them.
+
+    The tell is the absent record, not the backend: `okstra team` appends a
+    `workerDispatches[]` row for every worker it starts, and an in-process worker
+    leaves none. Backend alone cannot separate the two, because a pane dispatch
+    that degrades legitimately records `backendType: cli-wrapper`
+    (`dispatch_core._dispatch_record`). A worker that was never attempted has no
+    row either, so only attempted statuses are checked.
+    """
+    adapter = team_state.get("leadAdapter")
+    if not isinstance(adapter, dict):
+        return
+    if str(adapter.get("name", "")).strip() != "cmux":
+        return
+    recorded = {
+        str(row.get("workerId", "")).strip()
+        for row in team_state.get("workerDispatches") or []
+        if isinstance(row, dict)
+    }
+    missing = []
+    for worker in workers:
+        if not isinstance(worker, dict):
+            continue
+        if str(worker.get("status", "")).strip() not in dispatched_statuses:
+            continue
+        worker_id = str(worker.get("workerId", "")).strip()
+        if worker_id and worker_id not in recorded:
+            missing.append(worker_id)
+    if missing:
+        failures.append(
+            "team-state.workerDispatches has no record for "
+            f"{', '.join(sorted(missing))} in a cmux run — those workers ran "
+            "without okstra starting them, so they had no pane and the user "
+            "could not watch the work. Under cmux every lead dispatches through "
+            "`okstra team dispatch`, a Claude Code lead included "
+            "(prompts/lead/adapters/cmux.md); the host relay's in-process "
+            "`Agent(...)` mapping does not apply to this run."
+        )
+
+
 def validate_team_state(
     team_state: dict,
     project_root: Path,
@@ -777,6 +829,10 @@ def validate_team_state(
                         f"Found: `{tc_status}`."
                     )
 
+    _validate_cmux_workers_were_dispatched_by_okstra(
+        team_state, workers, dispatched_statuses, failures
+    )
+
     by_role: dict[str, dict] = {}
     for worker in workers:
         if not isinstance(worker, dict):