okstra 0.125.6 → 0.127.0

package/docs/architecture.md

@@ -732,7 +732,8 @@ Errors that occur while workers (Claude/Codex/Antigravity worker, Report writer,
 
 ### Live-log mirror (codex / antigravity wrapper)
 
-- On every dispatch, `scripts/okstra-codex-exec.sh` and `scripts/okstra-antigravity-exec.sh` create a `<prompt>.log` sidecar next to the prompt path and mirror stdout there (`tee`, preserving the exit code with `PIPESTATUS[0]`). stderr is appended to the same file, preserving the subagent stderr-capture contract, and the file is truncated on each dispatch. This solves the problem where a calling subagent polls `BashOutput` every 60 seconds, leaving users unable to detect a stalled state during long-running work such as large-codebase scans in analysis or cargo / pytest in implementation.
+- On every dispatch, `scripts/okstra-codex-exec.sh` and `scripts/okstra-antigravity-exec.sh` create a `<prompt>.log` sidecar next to the prompt path and mirror stdout there through a named FIFO (which keeps the CLI a single addressable PID for the idle watchdog). stderr is appended to the same file, preserving the subagent stderr-capture contract, and the file is truncated on each dispatch. This solves the problem where a calling subagent polls `BashOutput` every 60 seconds, leaving users unable to detect a stalled state during long-running work such as large-codebase scans in analysis or cargo / pytest in implementation.
+- **Per-block cap on the codex log copy** (`okstra_log_mirror` in `scripts/okstra-codex-exec.sh`): workers read their required inputs end-to-end per the Worker Preamble's *Reading rules*, so a single report read can dump 170KB+ into the log and observed sidecars reach 8MB. The mirror keeps the first `log_block_line_cap` (120) lines of each output block and replaces the remainder with a `[okstra log-mirror] N line(s) elided` marker, draining every 500 elided lines so the idle watchdog keeps seeing writes. **Only the log copy is capped** — the stdout passthrough stays byte-identical, so the dispatching subagent's `BashOutput` and Phase 5 synthesis are unaffected (`tests-js/codex-log-mirror.test.mjs` asserts that byte-identity). The marker set is codex-specific; the claude wrapper emits `--output-format=stream-json` and does not share this filter.
 - When tmux is reachable in the lead environment, the wrapper automatically splits a sibling pane and runs `tail -F <log-path>`. The trace-pane title appends `-tail` to the caller (worker) pane title: `<cli>-<role>-<pid>-tail` (for example, `codex-worker-93421-tail`). At the same time, the caller (worker) pane title is set to `<cli>-<role>-<pid>`. `<pid>` is the wrapper's own PID, so multiple workers with the same role spawned concurrently remain distinguishable, and operators can visually map `<caller> ↔ <caller>-tail`. **Caller-pane resolution**—because the Claude Code Bash tool now removes both `$TMUX` and `$TMUX_PANE` from the environment, the wrapper does not depend on environment variables. It (1) derives `<RUN_DIR>` as `dirname(dirname(prompt_path))` from the prompt path (paths.py SSOT), and (2) reads `<RUN_DIR>/state/lead-pane.id`, written once by the lead in its foreground pane, as the split anchor. This remains reliable for background dispatches, unlike active-pane guessing, even if the user changes panes. If the file is absent or the pane is stale, it falls back to `tmux display-message -p '#{pane_id}'` (the active pane). The trace split explicitly anchors to that caller pane with `-t`. The role is the wrapper's fifth optional positional argument and defaults to `worker`. The caller pane title is captured and restored by an EXIT trap, preventing stale titles across dispatches. Focus returns to the caller pane, and the trace pane remains after CLI exit so its scrollback is available. All paths silently degrade when tmux is unreachable, splitting fails, or tmux is outdated.
 - **Run-scoped tagging for cleanup**: A trace pane's `tail -F` is a child of the tmux shell and survives Claude's exit. The wrapper tags each spawned pane with `tmux set-option -p @okstra_trace_run=<RUN_DIR>`, and `okstra-trace-cleanup.sh` discovers panes server-wide from that tag via `tmux list-panes -a` and runs `tmux kill-pane`. It requires neither tmux environment variables nor a pane-ID registry. Because the tag is run-scoped, it does not kill trace panes from other simultaneous okstra runs. Cleanup has two entry forms: the lead invokes it with `--run-dir <RUN_DIR>` to clean traces and worker-agent panes for that run, or the `hooks.SessionEnd` entry in `templates/reports/settings.template.json` invokes it with `--reap` to clean all trace panes tagged below `$CLAUDE_PROJECT_DIR/.okstra/` when no single run directory exists at session end. Missing tmux and stale pane IDs silently degrade.
 - **Automatic cleanup on phase transitions, including worker-agent panes**: `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` closes not only tagged trace panes but also worker-agent panes occupied by dispatched subagents. These harness-owned panes cannot be tagged, so the script identifies them within the lead session (`tmux list-panes -s -t <lead-pane>`) through a title allowlist: `claude-worker` / `codex-worker` / `antigravity-worker` / `report-writer-worker`. Implementation role titles such as `claude-executor` / `codex-verifier` / `agy-executor-tail`, and FleetView teammate prefixes `✳ ` / `⠂ `, are also treated as okstra panes. Session scoping and exclusion of the lead's own pane are determined by `<RUN_DIR>/state/lead-pane.id`; the lead pane is never killed even if its title matches. Immediately before dispatching workers for a new phase (before the `PROGRESS: phase-5.5-convergence` / `phase-6-synthesis` marker), the lead calls this script with `--run-dir` to clean previous-phase panes without prompting.

package/docs/project-structure-overview.md

@@ -169,6 +169,7 @@ Runtime/install asset changes follow this checklist:
 | `resolve-task-key` | `src/commands/inspect/resolve-task-key.mjs` | Resolve a bare task-id to candidate task-keys from the project catalog |
 | `set-work-status` | `src/commands/inspect/set-work-status.mjs` | Set a task's user-managed `workStatus` in task-manifest.json (Python: `okstra_ctl.set_work_status`) |
 | `time-report`, `log-report`, `error-report`, `error-zip` | `src/commands/inspect/*.mjs` | Read-side task runtime, wrapper log, and error aggregation helpers |
+| `worker-liveness` | `src/commands/inspect/worker-liveness.mjs` | Report whether pending workers are still alive, so the lead's poll ends a stalled wait early instead of paying the deadline (Python: `okstra_ctl.worker_liveness`) |
 | `context-cost` | `src/commands/inspect/context-cost.mjs` | Estimate task bundle file/read context cost |
 | `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
 | `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
@@ -249,6 +250,7 @@ Important modules:
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `batch.py`, `backfill.py` | `~/.okstra` run index and history operations |
 | `run_index_row.py` | single reference point for creating / slimming / hydrating a `~/.okstra` run-index row — runId SSOT, preserves projectId raw |
 | `error_report.py`, `error_log_core.py`, `error_zip.py` | backend for the okstra-inspect errors/error-zip facets — `error_log_core` is the read-only core that globs/parses/aggregates `errors-*.jsonl`, `error_report` renders the errors facet, and `error_zip` collects cross-project run directories, allowlist-anonymizes, aggregates clusters, and produces a zip |
+| `worker_heartbeat.py`, `worker_liveness.py` | `worker_heartbeat` is the single definition of the `- PROGRESS:` heartbeat line shape and its 5-minute (+60s grace) cadence budget, shared by the Phase 7 audit (`validators/validate_session_conformance.py`) and the live probe; `worker_liveness` backs `okstra worker-liveness`, reporting a pending worker as `stalled` (heartbeat past the budget) or `did-not-launch` (no wrapper `.log`/`.status.json` past the launch grace) |
 | `log_report.py`, `time_report.py` | read-side backend for the okstra-inspect logs/time facets (`okstra log-report` is the wrapper sidecar log inventory, `okstra time-report` is per-task time aggregation) |
 | `rollup.py` | read-side backend for the okstra-rollup skill — fans the catalog out per task-group (or the whole project) and deterministically aggregates each task's run count, elapsed time (raw ms), error count, and latest report path, plus group-level totals/status, category, and phase distribution. Reuses the `time_report`/`error_log_core` functions and delegates report-body synthesis to the skill |
 | `usage_report.py` | Read-only okstra-usage backend — scans the whole current project's recent run timelines, defaults to 30 days, and returns task-type coverage, raw/billable tokens, known USD cost, CPU-sum and wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.125.6",
+  "version": "0.127.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.125.6",
-  "builtAt": "2026-07-20T13:12:23.932Z",
+  "package": "0.127.0",
+  "builtAt": "2026-07-20T14:29:59.831Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/report-writer-worker.md

@@ -67,7 +67,7 @@ Before writing the data.json, you MUST:
 
 For the report writer specifically, the `## Inputs` list always includes:
 
-- `<instruction-set>/final-report-schema.json` — the **per-task-type excerpt** of the data.json schema (scoped to this run's task-type at prep time: other task-types' deliverable blocks and their unreachable `$defs` are stripped). This is the shape you must author. Read this, NOT the full `schemas/final-report-v1.0.schema.json` (it is not in the task bundle and its `schemas/...` path is not resolvable here). Validation still runs against the full schema post-hoc, so the excerpt never relaxes the contract.
+- `<instruction-set>/final-report-schema.json` — the **per-task-type excerpt** of the data.json schema (scoped to this run's task-type at prep time: other task-types' deliverable blocks and their unreachable `$defs` are stripped). This is the shape you must author. Read this, NOT the full `schemas/final-report-v1.0.schema.json` (it is not in the task bundle and its `schemas/...` path is not resolvable here). Validation still runs against the full schema post-hoc, so the excerpt never relaxes the contract. The excerpt is frozen at prep time and carries the okstra version it was cut from (`x-okstraCutFromVersion`); if the renderer rejects a field the excerpt told you to write, the runtime upgraded mid-run — the renderer's error names the version skew, and the **installed schema wins**.
 - `<instruction-set>/final-report-template.md` — the **phase-stripped** Jinja2 template the renderer uses (only this run's §4.x deliverable block remains). Read it to understand which data.json fields appear where in the rendered markdown; do NOT edit it, and do NOT pull the full `templates/reports/final-report.template.md` source.
 - `templates/reports/i18n/en.json` and `templates/reports/i18n/ko.json`.
 - Every analysis worker's result file under `worker-results/`.

package/runtime/bin/okstra-antigravity-exec.sh

@@ -283,8 +283,14 @@ if (( idle_timeout_secs > 0 )); then
       # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
       # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
       # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
-      last_mtime="$(stat -c %Y "$log_path" 2>/dev/null)"
-      [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null)"
+      #
+      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
+      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
+      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
+      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
+      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
+      [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0
       now=$(date +%s)
       idle=$(( now - last_mtime ))

package/runtime/bin/okstra-claude-exec.sh

@@ -126,8 +126,14 @@ if (( idle_timeout_secs > 0 )); then
       # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
       # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
       # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
-      last_mtime="$(stat -c %Y "$log_path" 2>/dev/null)"
-      [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null)"
+      #
+      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
+      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
+      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
+      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
+      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
+      [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0
       now=$(date +%s)
       idle=$(( now - last_mtime ))

package/runtime/bin/okstra-codex-exec.sh

@@ -167,6 +167,57 @@ log_path="${prompt_path%.md}.log"
 [[ "$log_path" == "$prompt_path" ]] && log_path="${prompt_path}.log"
 : > "$log_path"
 
+# Per-block line cap applied to the LOG COPY of codex's stdout (see
+# okstra_log_mirror below). Workers read their required inputs end-to-end per
+# templates/worker-prompt-preamble.md "Reading rules", so one report read can
+# dump 170KB+ into the log; observed sidecar logs reach 8MB and account for
+# ~93% of a project's `.okstra/` bytes (`okstra log-report` inventories them).
+# 120 lines keeps each block's command and the head of its output — enough to
+# reconstruct what ran — while cutting the whole-file dumps that dominate.
+log_block_line_cap=120
+
+# Mirror stdin to stdout verbatim AND to <log-path> with a per-block cap.
+#
+# Only the log copy is capped. The stdout passthrough is never filtered, so the
+# dispatching subagent's `BashOutput` still receives codex's output verbatim for
+# Phase 5 synthesis, and the model's own context is unaffected — the log is a
+# *copy* of output codex already produced, not an input to anything except a
+# human post-mortem and the `tail -n 10` diagnostic in
+# agents/workers/_cli-wrapper-template.md.
+#
+# A "block" starts at one of codex's own top-level markers. Misreading a marker
+# only resets the counter (less truncation); it can never drop a line from
+# stdout. The marker set is codex-specific — the claude wrapper emits
+# `--output-format=stream-json` and must NOT reuse this filter as-is.
+okstra_log_mirror() {
+  awk -v logf="$1" -v cap="$2" '
+    function drain() {
+      if (elided > 0) {
+        printf "  [okstra log-mirror] %d line(s) elided from this block\n", elided >> logf
+        fflush(logf)
+        elided = 0
+      }
+    }
+    /^(exec|codex|thinking|user)$/ { drain(); kept = 0 }
+    {
+      print
+      fflush()
+      kept++
+      if (kept <= cap) {
+        print >> logf
+        fflush(logf)
+      } else {
+        elided++
+        # Periodic drain keeps the log mtime moving: the idle watchdog below
+        # polls that mtime as its liveness proxy and would otherwise SIGTERM
+        # codex partway through a long elided block.
+        if (elided >= 500) drain()
+      }
+    }
+    END { drain(); close(logf) }
+  '
+}
+
 # stdout-mirror FIFO path (created at the dispatch block below). Declared here,
 # before the EXIT trap is defined, so the trap's cleanup reference is always set
 # under `set -u`.
@@ -293,11 +344,11 @@ fi
 # stdin redirect, stderr capture, and pipeline mirroring are intentionally
 # inside the wrapper — this is the entire reason this script exists.
 #
-# stdout: tee'd to both the live log (for `tail -f`) AND the wrapper's own
-#         stdout (so the subagent's `BashOutput` still captures the final
-#         text verbatim for Phase 5 synthesis). Implemented via process
-#         substitution so codex itself stays a single addressable PID we
-#         can SIGTERM from the watchdog.
+# stdout: mirrored to both the live log (for `tail -f`, capped per block by
+#         okstra_log_mirror) AND the wrapper's own stdout (verbatim, so the
+#         subagent's `BashOutput` still captures the final text for Phase 5
+#         synthesis). Implemented via a FIFO so codex itself stays a single
+#         addressable PID we can SIGTERM from the watchdog.
 # stderr: appended to the live log only — mirrors the prior `2>/dev/null`
 #         contract of keeping the wrapper's stderr stream clean.
 # exit:   codex's own exit code is preserved by `wait`.
@@ -325,7 +376,7 @@ fi
 stdout_fifo="${log_path}.stdout.fifo"
 rm -f "$stdout_fifo"
 mkfifo "$stdout_fifo"
-tee -a "$log_path" < "$stdout_fifo" &
+okstra_log_mirror "$log_path" "$log_block_line_cap" < "$stdout_fifo" &
 stdout_tee_pid=$!
 
 # Disable git's fsmonitor for every git command codex runs in this process
@@ -363,8 +414,14 @@ if (( idle_timeout_secs > 0 )); then
       # GNU `stat -c` 우선 + 숫자 검증. BSD-ism `stat -f %m` 은 Linux 에서 깨끗이
       # 실패하지 않고 비숫자 파일시스템 출력으로 성공해 아래 산술을 set -u 에서
       # 깨뜨린다 — file_mtime(lib/okstra/interactive.sh) 와 동일 가드.
-      last_mtime="$(stat -c %Y "$log_path" 2>/dev/null)"
-      [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null)"
+      #
+      # `|| true` 는 필수다. macOS 에는 GNU `stat -c` 가 없어 exit 1 이고,
+      # `2>/dev/null` 은 stderr 만 막지 종료코드는 막지 못한다. 이 워치독은 명시적
+      # `( ) &` 서브셸이라 위쪽 `set -e` 를 상속하므로, 실패한 할당 하나가 첫 폴링에서
+      # 워치독을 통째로 죽인다 — 조용히, 로그 한 줄 없이. file_mtime 이 같은 코드로도
+      # 멀쩡한 것은 항상 `$( )` 안에서 호출돼 errexit 을 상속하지 않기 때문이다.
+      last_mtime="$(stat -c %Y "$log_path" 2>/dev/null || true)"
+      [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime="$(stat -f %m "$log_path" 2>/dev/null || true)"
       [[ "$last_mtime" =~ ^[0-9]+$ ]] || last_mtime=0
       now=$(date +%s)
       idle=$(( now - last_mtime ))

package/runtime/prompts/lead/adapters/claude-code.md

@@ -62,6 +62,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 - Follow the core Result Path + terminal-status completion contract. The Claude adapter's wake mechanism is one `Bash(run_in_background: true)` poll covering every pending Result Path, not foreground sleep or an idle-notification dependency. A spawn acknowledgement is never completion.
 - The background poll uses a per-worker deadline of twice the expected duration: 20 minutes for `requirements-discovery`, 30 for `error-analysis`, 40 for `implementation-planning`, 40 for `implementation`, and 20 for `final-verification`. On timeout, record terminal status and apply the core's single shared retry budget.
 - The Claude worker heartbeat audit sidecar must update at least every five minutes while its result is pending. A missing or stale heartbeat consumes the same one-retry budget; after the second silent hang, record `timeout`. The result file remains the authoritative completion signal.
+- **The background poll checks liveness, not only Result Paths.** Result Paths change once, at the very end, so polling them alone pays the full deadline for a worker that died at minute three. Each poll iteration MUST also run, in the same background shell, one `okstra worker-liveness` call covering every pending worker — `--audit <audit-sidecar-path>` for each in-process Claude worker, `--prompt <prompt-history-path>` for each CLI-wrapper worker. It exits non-zero when a worker is `stalled` (heartbeat older than the cadence budget) or `did-not-launch`; either verdict ends the wait for that worker immediately and spends the core's one-retry budget, rather than waiting out the deadline. The command reports only — it never kills or re-dispatches. It shares its heartbeat budget with the Phase 7 audit (`okstra_ctl.worker_heartbeat`), so a worker the live probe passes cannot fail the post-hoc one for cadence.
 - The Claude Code harness blocks long foreground sleeps and shorter-sleep circumvention loops. Keep the result poll in a single background shell and let wrapper agents use their documented `BashOutput` loop.
 - On approved cleanup, reconcile the current live session roster before sending shutdown requests. Never target the lead session.
 - Collect usage before teardown. Resume through the recorded Claude session id and keep all run artifacts authoritative.

package/runtime/prompts/lead/convergence.md

@@ -255,7 +255,7 @@ Call `await_workers(handles)` through the same adapter and apply the shared term
 
 ### Required reverify-prompt anchor headers (BLOCKING)
 
-Every reverify prompt MUST start with these 7 anchor headers — in this exact order, before any other content:
+Every reverify prompt MUST start with these 8 anchor headers — in this exact order, before any other content:
 
 ```
 **Project Root:** <absolute-path>
@@ -265,8 +265,11 @@ Assigned worker prompt history path: <Project Root>/<Prompt History Path>
 **Model:** <role>, <modelExecutionValue>
 **Errors log path:** <absolute-path>
 **Errors sidecar path:** <absolute-path>
+**Read scope:** Read only the paths this prompt enumerates (`[Required reading]`, `## Inputs`, verification-target paths) plus source/evidence paths a finding must cite. Host session instructions (SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs) do NOT apply inside an okstra worker run: do not auto-read `graphify-out/`, `SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an un-enumerated file seems essential, record it under *Missing Information or Assumptions* instead of reading it.
 ```
 
+`**Read scope:**` is carried verbatim, not dropped: lightweight mode omits `**Worker Preamble Path:**`, so this line is the ONLY place a reverify worker receives the read allowlist — and a prompt with no `[Required reading]` block is exactly where a worker is most likely to fall back on host session instructions instead.
+
 The two errors paths carry the same absolute values the lead forwarded in the initial Phase 4 dispatch for that role (source: the launch prompt's `## Run Logs (error-log wiring)` section). Omitting either one makes a CLI-wrapper worker return `<WORKER>_ERRORS_PATH_MISSING` before it invokes its CLI — the path-delivery contract in [team-contract](./team-contract.md) "Error reporting" is not relaxed for reverify, because a reverify dispatch can fail the same way an initial dispatch can.
 
 Relative to the Phase 4 anchor set rendered by `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`, a reverify prompt adds `**Model:**` and drops two anchors whose targets lightweight mode never reads: `**Worker Preamble Path:**` and `**Coding preflight pack:**`.

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

@@ -244,7 +244,30 @@ okstra error-log append-from-worker \
   --task-key <taskKey> --agent <agent> --agent-role <role> --model <model>
 ```
 
-For Codex/Antigravity wrappers: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `okstra error-log append-observed --error-type cli-failure ...` with the captured exit code, duration, message, and stderr excerpt. The wrapper subagent records this through its selected adapter — Lead does NOT need to re-record. Token usage is not inferred from dispatch return values; call `collect_usage` at the start of Phase 7.
+`--agent`, `--agent-role`, and `--error-type` are **closed enums**, not free-form labels — the role names used elsewhere in these contracts (`Codex worker`, `Claude worker`) are rejected. Use exactly:
+
+- `--agent` — `claude-worker` | `codex-worker` | `antigravity-worker` | `report-writer`
+- `--agent-role` — `lead` | `worker` | `report-writer`
+- `--error-type` — `cli-failure` | `contract-violation` | `tool-failure`
+
+For a lead-attributed event there is no value in the list above — the selected adapter names the lead identity to pass.
+
+For Codex/Antigravity wrappers: if the CLI returns non-zero, times out, or hits a rate limit, immediately call `append-observed` with the captured exit code, duration, message, and stderr excerpt. `append-observed` additionally requires `--phase`, `--command`, and `--command-kind`, so copy this form rather than trimming the one above:
+
+```bash
+okstra error-log append-observed \
+  --out <absolute-errors-log-path-from-launch-prompt> \
+  --task-key <taskKey> --phase 5.5 \
+  --agent codex-worker --agent-role worker --model <model> \
+  --error-type cli-failure \
+  --command "okstra-codex-exec.sh <project-root> <model> <prompt-path>" \
+  --command-kind wrapper \
+  --exit-code 124 --duration-ms 1800000 \
+  --message "reverify-r1 wrapper never launched" \
+  --stderr-excerpt "<last stderr lines, or use --stderr-excerpt-file>"
+```
+
+The wrapper subagent records this through its selected adapter — Lead does NOT need to re-record. Token usage is not inferred from dispatch return values; call `collect_usage` at the start of Phase 7.
 
 ## Phase 5.5: Convergence loop
 

package/runtime/prompts/lead/report-writer.md

@@ -43,7 +43,7 @@ The prompt MUST include, in this order at the top:
    - `**Errors sidecar path:** <absolute-path>` — this worker's per-run sidecar JSON (`worker-results/report-writer-worker-errors-<task-type>-<seq>.json`).
 7. `**Model:** Report writer worker, <modelExecutionValue>` (resolved per Phase 5.5 anchor-header rules)
 8. The full `[Required reading]` clause (see [team-contract](./team-contract.md)) — for Phase 6 it adds two **per-task-type, instruction-set-local** read-only files, both scoped to this run's task-type by `okstra-ctl` at prep time:
-   - `<instruction-set>/final-report-schema.json` — a task-type excerpt of the data.json schema (the other task-types' deliverable blocks and their unreachable `$defs` are stripped; ~38% of the full schema is `$defs` alone). This is your authoring contract for the data.json shape. Do **NOT** pull the full `schemas/final-report-v1.0.schema.json` — it carries all task-types and its `schemas/...` path is not part of the task bundle. (Validation still runs against the full schema post-hoc via the renderer, so the excerpt never relaxes the contract.)
+   - `<instruction-set>/final-report-schema.json` — a task-type excerpt of the data.json schema (the other task-types' deliverable blocks and their unreachable `$defs` are stripped; ~38% of the full schema is `$defs` alone). This is your authoring aid for the data.json shape — the installed schema, not the excerpt, is what the run is judged against. Do **NOT** pull the full `schemas/final-report-v1.0.schema.json` — it carries all task-types and its `schemas/...` path is not part of the task bundle. (Validation still runs against the full schema post-hoc via the renderer, so the excerpt never relaxes the contract.)
    - `<instruction-set>/final-report-template.md` — the **phase-stripped** template (every other task-type's §5.x deliverable block removed by `render.py`'s `_strip_phase_blocks`, leaving only your run's §5.x). Do **NOT** also pull the full `templates/reports/final-report.template.md` source (it re-adds ~330 lines of other phases' deliverables and is not in the task bundle).
 9. A one-line MCP pointer instead of the verbatim block (redundant — the brief is already in the report-writer's Required reading, item 8): `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).`
 10. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history data (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker populates `crossVerification.roundHistory` in the data.json so Section 6 can show which rounds executed, queue sizes, and why Round 2 was (or was not) skipped. The renderer prints the full per-round table only when more than one round ran; single-round or zero-round histories are auto-collapsed to a one-line summary.

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

@@ -118,6 +118,9 @@ After each worker subagent returns (regardless of role), Lead MUST verify the ca
 - The wrapper subagent returned an explicit `*_RESULT_MISSING` sentinel (codex-worker / antigravity-worker step 8c — `CODEX_RESULT_MISSING` / `ANTIGRAVITY_RESULT_MISSING`).
 - The result file is absent at the resolved absolute path even though the worker returned without a `*_RESULT_MISSING` sentinel — for example, claude-worker returned its final assistant message but never persisted the artifact, or the wrapper exited 0 and the codex/antigravity sub-agent forwarded raw stdout despite the contract.
 - The result file exists but cannot be parsed (frontmatter unreadable, sections 1–5 entirely missing). A truncated file in the middle of section 5 is NOT covered here — it goes to the validator's regular `error` path, not the retry path.
+- `okstra worker-liveness` reports the worker `did-not-launch` — neither `<prompt-path>.log` nor `<prompt-path>.status.json` exists past the launch grace (default 60s). The wrapper writes its status sidecar before invoking the CLI and hard-fails loudly with a distinct exit code on every argument check before that, so the absence of BOTH artifacts means the dispatch itself never reached the script. Without this trigger the only evidence was a lead noticing two missing files by eye, and the run paid the full polling cap for a worker that never started.
+- `okstra worker-liveness` reports the worker `stalled` — its audit sidecar's newest `- PROGRESS:` heartbeat is older than the cadence budget, or the sidecar carries no heartbeat at all. This is the in-process equivalent of the CLI wrappers' idle watchdog: the wrapper reaps a silent CLI itself, but nothing reaped a silent `claude-worker` until its deadline.
+- The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
 
 **One-retry policy:**
 

package/runtime/python/okstra_ctl/design_surfaces.py

@@ -180,11 +180,28 @@ def _stage_rows(planning: Mapping[str, Any]) -> dict[int, Mapping[str, Any]]:
     return rows
 
 
-def _stage_for_selected_path(
+_LINE_RANGE_SUFFIX = re.compile(r":\d+(?:-\d+)?$")
+
+
+def _stages_for_selected_path(
     path: str,
     stages: Mapping[int, Mapping[str, Any]],
-) -> int:
-    normalised = _normalise(path)
+) -> list[int]:
+    """Every stage whose stepwise ``files`` cells touch *path*.
+
+    A file legitimately edited by more than one stage — the task-level
+    ``qa/conformance-manifest.json`` is the standard case, since each
+    conformance-declaring stage registers its own entry — yields one design
+    surface per stage, which is what the consumer keys on. Requiring a single
+    owner instead would force the plan to hide an edit, collapse stage
+    boundaries, or re-add the line-range suffixes that used to disambiguate
+    stages by accident.
+
+    Zero stages is still an error: the recommended option declares a file that
+    no step creates or edits.
+    """
+    normalised = _LINE_RANGE_SUFFIX.sub("", _normalise(path))
+    path_pattern = rf"(?<![\w./@-]){re.escape(normalised)}(?![\w./@-])"
     matched = []
     for stage_number, stage in stages.items():
         files = [
@@ -192,14 +209,13 @@ def _stage_for_selected_path(
             for step in stage.get("stepwiseExecution") or []
             if isinstance(step, Mapping)
         ]
-        path_pattern = rf"(?<![\w./@-]){re.escape(normalised)}(?![\w./@-])"
         if any(re.search(path_pattern, cell) is not None for cell in files):
             matched.append(stage_number)
-    if len(matched) != 1:
+    if not matched:
         raise DesignSurfaceError(
-            f"selected option path {path!r} is not mapped to a stage exactly once"
+            f"selected option path {path!r} is not mapped to a stage"
         )
-    return matched[0]
+    return matched
 
 
 def detect_design_surfaces(
@@ -226,13 +242,13 @@ def detect_design_surfaces(
         if not isinstance(row, Mapping):
             continue
         path = str(row.get("path") or "")
-        stage_number = _stage_for_selected_path(path, stages)
-        for kind, evidence in _matching_rule_evidence(
-            step=None,
-            field="files",
-            value=path,
-        ):
-            grouped.setdefault((stage_number, kind), []).append(evidence)
+        for stage_number in _stages_for_selected_path(path, stages):
+            for kind, evidence in _matching_rule_evidence(
+                step=None,
+                field="files",
+                value=path,
+            ):
+                grouped.setdefault((stage_number, kind), []).append(evidence)
     rule_order = {rule.kind: index for index, rule in enumerate(RULES)}
     return [
         DesignSurfaceTrigger(stage, kind, tuple(grouped[(stage, kind)]))

package/runtime/python/okstra_ctl/render_final_report.py

@@ -52,6 +52,8 @@ from okstra_ctl.final_report_schema import SchemaError, load_schema, validate as
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
 from okstra_ctl.md_table import UNESCAPED_PIPE_RE, escape_pipes
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
+from okstra_ctl.schema_excerpt import excerpt_cut_from_version
+from okstra_ctl.seeding import installed_version
 
 
 DEFAULT_TEMPLATE_REL = ("templates", "reports", "final-report.template.md")
@@ -125,6 +127,21 @@ def _yaml_inline_list(values: list[str]) -> str:
     return "[" + ", ".join(_yaml_scalar(v) for v in values) + "]"
 
 
+def _md_quote(value: str | None, width: int = 2) -> str:
+    """Re-mark every continuation line of a multi-line blockquote value.
+
+    The template supplies the first line's ``  > ``; lines 2..n arrive at
+    column 0, where they end the enclosing list item and drag the bullets
+    that follow into one run-on paragraph.
+    """
+    text = "" if value is None else str(value)
+    pad = " " * width
+    lines = text.split("\n")
+    return "\n".join(
+        [lines[0]] + [f"{pad}>{' ' + line if line else ''}" for line in lines[1:]]
+    )
+
+
 # --- Index / scroll-anchor post-render pass -------------------------------
 # After Jinja2 renders the body, every report gets a top-of-report index and
 # clickable scroll anchors. An ID is *defined* when it is the leading token of
@@ -424,6 +441,11 @@ def _build_environment(template_dir: Path) -> Environment:
     # cannot split a markdown table row. Table-cell interpolations only —
     # never code blocks / headings / prose, where `\|` would render verbatim.
     env.filters["mdcell"] = escape_pipes
+    # `mdquote` re-marks continuation lines of a blockquote nested in a list
+    # item; the fenced siblings use Jinja's builtin `indent` for the same
+    # reason. Both exist because only the first line of an interpolation
+    # inherits the template's leading indent.
+    env.filters["mdquote"] = _md_quote
     return env
 
 
@@ -516,6 +538,47 @@ def find_default_template(start: Path | None = None) -> Path:
     )
 
 
+def _bundle_excerpt_path(data_path: Path) -> Path | None:
+    """The task bundle's schema excerpt, found by walking up from *data_path*."""
+    for ancestor in data_path.resolve().parents:
+        candidate = ancestor / "instruction-set" / "final-report-schema.json"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _with_excerpt_drift_hint(
+    exc: FinalReportRenderError, data_path: Path
+) -> FinalReportRenderError:
+    """Name the version skew behind a schema failure, when that is the cause.
+
+    A long run straddles its own runtime upgrade: the report-writer authors
+    against the excerpt frozen into the bundle at prep time, while the renderer
+    validates against the installed schema. Without this the author sees only
+    `additional property ... not allowed` for a field the excerpt told it to
+    write, and has no way to tell a real mistake from a stale bundle.
+    """
+    if "schema validation" not in str(exc):
+        return exc
+    excerpt_path = _bundle_excerpt_path(data_path)
+    if excerpt_path is None:
+        return exc
+    try:
+        cut_from = excerpt_cut_from_version(
+            json.loads(excerpt_path.read_text(encoding="utf-8"))
+        )
+    except (OSError, json.JSONDecodeError):
+        return exc
+    current = installed_version()
+    if not cut_from or not current or cut_from == current:
+        return exc
+    return FinalReportRenderError(
+        f"{exc} — the bundle's schema excerpt ({excerpt_path}) was cut from okstra "
+        f"{cut_from} but validation ran on {current}; author against the installed "
+        "schema, not the excerpt, or re-prepare the bundle."
+    )
+
+
 def render_to_file(
     data_path: Path,
     output_path: Path,
@@ -542,11 +605,14 @@ def render_to_file(
     # 설치본에서 항상 'could not locate template' 으로 실패한다(OKSTRA_HOME 을
     # 수동 설정해야 했던 원인). 프로젝트별 override 는 --template 으로 한다.
     resolved_template = template_path or find_default_template()
-    rendered = render(
-        data,
-        template_path=resolved_template,
-        report_language=report_language,
-    )
+    try:
+        rendered = render(
+            data,
+            template_path=resolved_template,
+            report_language=report_language,
+        )
+    except FinalReportRenderError as exc:
+        raise _with_excerpt_drift_hint(exc, data_path) from exc
 
     output_path.parent.mkdir(parents=True, exist_ok=True)
     tmp = output_path.with_suffix(output_path.suffix + f".tmp.{os.getpid()}")

package/runtime/python/okstra_ctl/run.py

@@ -1709,7 +1709,9 @@ def _render_lead_prompt_and_snapshot(
     # still has the phase-stripped template + skill structure guide, and
     # validation runs against the full schema regardless.
     try:
-        _excerpt = build_schema_excerpt(load_schema(), inp.task_type)
+        _excerpt = build_schema_excerpt(
+            load_schema(), inp.task_type, installed_version()
+        )
         Path(ctx["FINAL_REPORT_SCHEMA_PATH"]).write_text(
             json.dumps(_excerpt, indent=2, ensure_ascii=False) + "\n",
             encoding="utf-8",

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -72,7 +72,16 @@ def _conditional_applies(entry: dict, task_type: str) -> bool:
     return task_type in (enum or [])
 
 
-def build_schema_excerpt(schema: dict, task_type: str) -> dict:
+EXCERPT_VERSION_KEY = "x-okstraCutFromVersion"
+
+
+def excerpt_cut_from_version(excerpt: dict) -> str:
+    """The okstra version *excerpt* was cut from; empty when unstamped."""
+    value = excerpt.get(EXCERPT_VERSION_KEY)
+    return value if isinstance(value, str) else ""
+
+
+def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "") -> dict:
     """Return a task-type-scoped copy of *schema*.
 
     Drops the per-type property blocks that do not belong to *task_type*,
@@ -81,6 +90,11 @@ def build_schema_excerpt(schema: dict, task_type: str) -> dict:
     def reachable from a kept property or conditional). Top-level metadata
     and ``required`` are preserved (``required`` never lists per-type
     blocks, but it is filtered defensively).
+
+    *cut_from_version* stamps the excerpt with the runtime that produced it.
+    Bundle prep and report render can be hours apart and the runtime upgrades
+    itself in between, so a mismatch is what turns an opaque "additional
+    property … not allowed" into "the bundle excerpt is from an older okstra".
     """
     keep_per_type = _TASK_TYPE_PROPERTY.get(task_type)
     drop_props = _ALL_PER_TYPE_PROPERTIES - ({keep_per_type} if keep_per_type else set())
@@ -119,4 +133,6 @@ def build_schema_excerpt(schema: dict, task_type: str) -> dict:
         excerpt["allOf"] = all_of
     if reachable:
         excerpt["$defs"] = {k: v for k, v in defs.items() if k in reachable}
+    if cut_from_version:
+        excerpt[EXCERPT_VERSION_KEY] = cut_from_version
     return excerpt

package/runtime/python/okstra_ctl/worker_heartbeat.py

@@ -0,0 +1,50 @@
+"""Heartbeat primitives shared by the live liveness probe and the Phase 7 audit.
+
+`claude-worker` appends `- PROGRESS: <stage> <ISO-8601-UTC>` lines to its audit
+sidecar so a silent hang is visible while the run is still recoverable. The
+Phase 7 validator has always parsed those lines post-hoc; `worker_liveness`
+reads them mid-run. Both must agree on what "stale" means, so the line shape and
+the cadence budget live here rather than in either consumer.
+"""
+from __future__ import annotations
+
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+# claude-worker audit 사이드카의 heartbeat 라인 (claude-worker.md "Heartbeat").
+HEARTBEAT_LINE_RE = re.compile(
+    r"^-[ \t]*PROGRESS:[ \t]*(?P<stage>\S+)[ \t]+(?P<ts>\S+)[ \t]*$", re.MULTILINE
+)
+
+# 계약상 cadence 는 5분. append 직전 측정한 시각과 실제 쓰기 사이 지연을 흡수하는
+# 고정 grace 60초를 더한다.
+HEARTBEAT_MAX_GAP_SECONDS = 5 * 60 + 60
+
+
+def parse_timestamp(raw: str) -> datetime | None:
+    """A heartbeat's ISO-8601 timestamp as an aware datetime, or None."""
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def latest_heartbeat(sidecar: Path) -> datetime | None:
+    """The newest parseable heartbeat in *sidecar*, or None when it has none.
+
+    Takes the maximum rather than the last line: a regressing timestamp is the
+    Phase 7 validator's finding to report, and treating it as "stale" here would
+    kill a worker that is in fact still writing.
+    """
+    try:
+        text = sidecar.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    stamps = [
+        parsed
+        for match in HEARTBEAT_LINE_RE.finditer(text)
+        if (parsed := parse_timestamp(match.group("ts"))) is not None
+    ]
+    return max(stamps) if stamps else None

package/runtime/python/okstra_ctl/worker_liveness.py

@@ -0,0 +1,140 @@
+"""Mid-run liveness probe for pending workers (`okstra worker-liveness`).
+
+The CLI wrappers reap a silent CLI themselves via their idle watchdog, but the
+lead's own wait had no equivalent: it polled Result Paths, which only change at
+the very end, so a worker that died at minute 3 was still waited on until its
+20–40 minute deadline. Two contracts named that failure without a mechanism —
+`adapters/claude-code.md` ("a missing or stale heartbeat consumes the same
+one-retry budget") and the absence of any `did-not-launch` status at all.
+
+This module is that mechanism. It reports, not decides: the lead reads the
+verdict and spends its existing one-retry budget.
+
+Two probes, matching the two ways a pending worker goes quiet:
+
+* ``--audit`` — a `claude-worker` audit sidecar. Stale past the heartbeat
+  cadence (or present with no heartbeat at all) means the in-process worker
+  hung. Uses the same line shape and budget the Phase 7 validator applies.
+* ``--prompt`` — a CLI-wrapper prompt-history path. Neither `<prompt>.log` nor
+  `<prompt>.status.json` past the launch grace means the wrapper never ran —
+  the dispatch itself failed, which no artifact otherwise distinguishes from a
+  worker that has merely not finished.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_ctl.worker_heartbeat import HEARTBEAT_MAX_GAP_SECONDS, latest_heartbeat
+
+DEFAULT_LAUNCH_GRACE_SECONDS = 60
+
+
+def _log_path(prompt: Path) -> Path:
+    """The wrapper's live log, named as okstra-*-exec.sh names it."""
+    return prompt.with_suffix(".log") if prompt.suffix == ".md" else Path(f"{prompt}.log")
+
+
+def probe_heartbeat(sidecar: Path, now: datetime, max_idle: float) -> dict:
+    """Liveness of one in-process worker, read from its audit sidecar."""
+    probe = {"kind": "heartbeat", "path": str(sidecar)}
+    if not sidecar.is_file():
+        # The worker writes the sidecar early but not instantly; absence is the
+        # launch probe's business, not a hang.
+        return {**probe, "state": "pending", "reason": "audit sidecar not written yet"}
+    beat = latest_heartbeat(sidecar)
+    if beat is None:
+        return {
+            **probe,
+            "state": "stalled",
+            "reason": "audit sidecar carries no `- PROGRESS:` heartbeat",
+        }
+    idle = (now - beat).total_seconds()
+    state = "stalled" if idle > max_idle else "live"
+    return {
+        **probe,
+        "state": state,
+        "idleSeconds": int(idle),
+        "lastHeartbeat": beat.isoformat(),
+        "reason": (
+            f"no heartbeat for {int(idle)}s (budget {int(max_idle)}s)"
+            if state == "stalled"
+            else ""
+        ),
+    }
+
+
+def probe_launch(prompt: Path, now: datetime, grace: float) -> dict:
+    """Whether the wrapper behind *prompt* ever started."""
+    log, status = _log_path(prompt), Path(f"{prompt}.status.json")
+    probe = {"kind": "launch", "path": str(prompt)}
+    if log.exists() or status.exists():
+        return {**probe, "state": "live", "reason": ""}
+    if not prompt.is_file():
+        return {**probe, "state": "pending", "reason": "prompt history not written yet"}
+    waited = now.timestamp() - prompt.stat().st_mtime
+    if waited <= grace:
+        return {**probe, "state": "pending", "reason": "within launch grace"}
+    return {
+        **probe,
+        "state": "did-not-launch",
+        "waitedSeconds": int(waited),
+        "reason": (
+            f"neither {log.name} nor {status.name} exists {int(waited)}s after the "
+            f"prompt was written (grace {int(grace)}s)"
+        ),
+    }
+
+
+def probe_all(
+    audits: list[str],
+    prompts: list[str],
+    *,
+    now: datetime,
+    max_idle: float,
+    launch_grace: float,
+) -> dict:
+    probes = [probe_heartbeat(Path(p), now, max_idle) for p in audits]
+    probes += [probe_launch(Path(p), now, launch_grace) for p in prompts]
+    unhealthy = [p for p in probes if p["state"] in ("stalled", "did-not-launch")]
+    return {"ok": not unhealthy, "checkedAt": now.isoformat(), "probes": probes,
+            "unhealthy": unhealthy}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="okstra worker-liveness",
+        description="Report whether pending workers are still alive (read-only).",
+    )
+    parser.add_argument("--audit", action="append", default=[],
+                        help="claude-worker audit sidecar path (repeatable)")
+    parser.add_argument("--prompt", action="append", default=[],
+                        help="CLI-wrapper prompt-history path (repeatable)")
+    parser.add_argument("--max-idle", type=float, default=HEARTBEAT_MAX_GAP_SECONDS,
+                        help="heartbeat staleness budget in seconds")
+    parser.add_argument("--launch-grace", type=float, default=DEFAULT_LAUNCH_GRACE_SECONDS,
+                        help="seconds a wrapper may take to write its first artifact")
+    parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
+    args = parser.parse_args(argv)
+
+    if not args.audit and not args.prompt:
+        parser.error("pass at least one --audit or --prompt path")
+
+    result = probe_all(
+        args.audit,
+        args.prompt,
+        now=datetime.now(timezone.utc),
+        max_idle=args.max_idle,
+        launch_grace=args.launch_grace,
+    )
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    # Non-zero on an unhealthy worker so a poll loop can branch on the exit code
+    # without parsing the JSON.
+    return 0 if result["ok"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -11,6 +11,25 @@ class WorkerPromptHeaderError(Exception):
     """Raised when worker prompt anchor headers cannot be rendered."""
 
 
+# The Worker Preamble's "Reading rules" already allowlist the worker's reads to
+# okstra-enumerated paths, but the preamble is a *path* the worker opens partway
+# into its run — by then a host SessionStart hook or a global CLAUDE.md /
+# AGENTS.md project-conditional has already told it to read `graphify-out/`,
+# skill catalogs, and similar non-okstra artifacts. Restating the scope inline
+# puts the rule in front of the worker before its first tool call, which is the
+# only point at which it can still win over those host instructions.
+READ_SCOPE_HEADER = (
+    "**Read scope:** Read only the paths this prompt enumerates "
+    "(`[Required reading]`, `## Inputs`, verification-target paths) plus "
+    "source/evidence paths a finding must cite. Host session instructions "
+    "(SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs) do "
+    "NOT apply inside an okstra worker run: do not auto-read `graphify-out/`, "
+    "`SKILL.md`, or other artifacts outside `<PROJECT_ROOT>/.okstra/`. If an "
+    "un-enumerated file seems essential, record it under *Missing Information "
+    "or Assumptions* instead of reading it."
+)
+
+
 def worker_prompt_headers(
     *,
     project_root: Path,
@@ -34,6 +53,7 @@ def worker_prompt_headers(
             f"**Errors sidecar path:** "
             f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
         ),
+        READ_SCOPE_HEADER,
     ]
 
 

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

@@ -464,14 +464,14 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - Path (project-relative): `{{ releaseHandoff.sourceVerificationReport.path }}`
 - Quoted `Verdict Token` row from that report's `## 7.` table:
-  > {{ releaseHandoff.sourceVerificationReport.verdictTokenQuote }}
+  > {{ releaseHandoff.sourceVerificationReport.verdictTokenQuote | mdquote(2) }}
 
 ### 5.6.2 Feature Branch & Working-Tree State{% if t("releaseHandoff.branchStateAside") != "captured at run start" %} ({{ t("releaseHandoff.branchStateAside") }}){% endif %}
 
 - Feature branch: `{{ releaseHandoff.featureBranchState.branchName }}`
 - {{ t("releaseHandoff.gitStatusShortLabel") }}:
   ```
-  {{ releaseHandoff.featureBranchState.gitStatusShort }}
+  {{ releaseHandoff.featureBranchState.gitStatusShort | indent(2) }}
   ```
 - {{ t("releaseHandoff.existingPrLabel") }}: `{{ releaseHandoff.featureBranchState.existingPrUrl or '(none)' }}`
 
@@ -542,7 +542,7 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - Plan file (project-relative): `{{ implementation.approvedPlanReference.planFile }}`
 - Approval evidence:
-  > {{ implementation.approvedPlanReference.approvalEvidence }}
+  > {{ implementation.approvedPlanReference.approvalEvidence | mdquote(2) }}
 - {{ t("executionMeta.runExecutorWorktreePath") }}: `{{ implementation.approvedPlanReference.executorWorktreePath }}`
 - {{ t("executionMeta.runBaseRef") }}: `{{ implementation.approvedPlanReference.baseRefSha }}`
 
@@ -587,11 +587,11 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 - Stage: `{{ implementation.stageSidecarEvidence.stageNumber }}` — {{ implementation.stageSidecarEvidence.stageTitle }}
 - Carry sidecar JSON:
   ```json
-  {{ implementation.stageSidecarEvidence.carryJson }}
+  {{ implementation.stageSidecarEvidence.carryJson | indent(2) }}
   ```
 - Appended `consumers.jsonl` rows:
 {% for row in implementation.stageSidecarEvidence.consumerRows -%}
-  > {{ row }}
+  > {{ row | mdquote(2) }}
 {% endfor %}
 
 ### 5.7.6 Validation Evidence
@@ -647,19 +647,19 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 - Path (project-relative): `{{ finalVerification.sourceImplementationReport.path }}`
 - {{ t("evidenceMeta.commitListSummary") }}:
-  > {{ finalVerification.sourceImplementationReport.commitListQuote }}
+  > {{ finalVerification.sourceImplementationReport.commitListQuote | mdquote(2) }}
 - {{ t("evidenceMeta.diffSummaryQuote") }}:
-  > {{ finalVerification.sourceImplementationReport.diffSummaryQuote }}
+  > {{ finalVerification.sourceImplementationReport.diffSummaryQuote | mdquote(2) }}
 - {{ t("evidenceMeta.targetWorktreePath") }}: `{{ finalVerification.sourceImplementationReport.worktreePath }}`
 - {{ t("evidenceMeta.implementationBaseRef") }}: `{{ finalVerification.sourceImplementationReport.implementationBaseRef }}`
 - {{ t("evidenceMeta.capturedHeadSha") }}: `{{ finalVerification.sourceImplementationReport.capturedHeadSha }}`
 - {{ t("evidenceMeta.gitStatusAtRunStart") }}:
   ```
-  {{ finalVerification.sourceImplementationReport.gitStatusShort }}
+  {{ finalVerification.sourceImplementationReport.gitStatusShort | indent(2) }}
   ```
 - {{ t("evidenceMeta.gitDiffStatAtRunStart") }}:
   ```
-  {{ finalVerification.sourceImplementationReport.gitDiffStat }}
+  {{ finalVerification.sourceImplementationReport.gitDiffStat | indent(2) }}
   ```
 {% if verificationScope in ['whole-task', 'single-stage'] %}- {{ t("finalVerification.verificationScope") }}: `{{ verificationScope }}`
 {% endif %}{% if finalVerification.stageReports %}- {{ t("finalVerification.stageReportsLabel") }}:

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

@@ -101,6 +101,7 @@ Every worker prompt MUST begin with these anchor headers, in this exact order, b
 6. `**Coding preflight pack:** <absolute-path>` — points to the installed runtime resource pack under `<OKSTRA_HOME>/prompts/coding-preflight`. Implementation executors and verifiers use this to read `overview.md`, `clean-code.md`, and routed language/framework/architecture resources. Other worker roles may ignore it.
 7. `**Errors log path:** <absolute-path>` — run-level JSONL (see Error reporting above).
 8. `**Errors sidecar path:** <absolute-path>` — per-worker JSON (see Error reporting above).
+9. `**Read scope:** …` — restates the *Reading rules* allowlist inline. This file is anchor 5, a path the worker opens partway into its run; by then a host SessionStart hook or a global `CLAUDE.md` / `AGENTS.md` project-conditional has already pointed it at `graphify-out/`, skill catalogs, and similar non-okstra artifacts. Only the inline copy arrives before the worker's first tool call.
 
 **Exception — reverify dispatches.** A Phase 5.5 re-verification prompt (its `**Prompt History Path:**` carries a `-reverify-r<N>-` segment) deliberately omits anchors 5 and 6 and adds a `**Model:**` line — lightweight mode reads neither this file nor the preflight pack. The two errors-path anchors are NOT omitted; that gate applies to reverify prompts unchanged. The reverify anchor set is owned by `prompts/lead/convergence.md` "Required reverify-prompt anchor headers".
 

package/runtime/validators/forbidden_actions.py

@@ -15,9 +15,10 @@ Bash tool_use 명령을 phase deny-list 와 대조해 위반을 기계적으로
 한계 1: claude-code 세션 jsonl 만 스캔한다. codex/antigravity lead·worker 는 동일 형식의
 tool_use transcript 를 ~/.claude/projects 에 남기지 않으므로 이 스캐너의 사정권 밖이며,
 해당 런타임의 금지 행위는 여전히 수동 감사에 의존한다.
-한계 2: deny-list 는 Bash 명령 문자열 전체를 검색하므로, 금지 토큰이 인자/메시지에
-등장하는 경우(예: `git commit -m "... npm publish ..."`)도 위반으로 잡힐 수 있다.
-`cd <path> && <cmd>` 형태 때문에 명령 head 앵커링은 불가하므로 이 잔여 오탐은 감수한다.
+한계 2: deny-list 는 heredoc 본문을 걷어낸(strip_heredoc_bodies) 명령 문자열 전체를
+검색하므로, 금지 토큰이 인자/메시지에 등장하는 경우(예: `git commit -m "... npm
+publish ..."`)는 여전히 위반으로 잡힐 수 있다. `cd <path> && <cmd>` 형태 때문에 명령
+head 앵커링은 불가하므로 이 잔여 오탐은 감수한다.
 """
 from __future__ import annotations
 
@@ -47,6 +48,43 @@ _UNIVERSAL = [
 ]
 _NON_HANDOFF_PUSH = ("git push", re.compile(r"\bgit\s+push\b"))
 
+_HEREDOC_START = re.compile(r"<<-?\s*(['\"]?)([A-Za-z_][A-Za-z0-9_]*)\1")
+
+
+def strip_heredoc_bodies(command: str) -> str:
+    """heredoc 본문을 걷어낸 명령 문자열.
+
+    heredoc 안의 토큰은 실행되는 명령이 아니라 파일에 **기록되는 데이터**다.
+    implementation-planning 은 배포 명령을 서술하는 계획서를 산출물로 내고 그
+    문서를 `python3 - <<'PY'` / `cat > … <<EOF` 로 패치하므로, 본문을 그대로
+    스캔하면 정상 경로에서 매 run 오탐이 난다. heredoc 시작 줄과 종료 구분자는
+    남겨 실제 명령 위치의 토큰은 계속 잡는다.
+
+    종료 구분자가 뒤에 없으면 아무것도 걷어내지 않는다 — `python3 -c "1 << shift"`
+    같은 시프트 연산이 heredoc 으로 오인돼 뒤따르는 진짜 명령을 숨기지 않도록,
+    본문 제거는 짝이 맞는 구분자를 실제로 찾았을 때만 한다.
+    """
+    lines = command.split("\n")
+    kept: list[str] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        kept.append(line)
+        index += 1
+        start = _HEREDOC_START.search(line)
+        if not start:
+            continue
+        delimiter = start.group(2)
+        end = next(
+            (i for i in range(index, len(lines)) if lines[i].strip() == delimiter),
+            None,
+        )
+        if end is None:
+            continue
+        kept.append(lines[end])
+        index = end + 1
+    return "\n".join(kept)
+
 
 def forbidden_patterns_for(task_type: str) -> list[tuple[str, re.Pattern]]:
     """task_type(=phase profile) 의 deny-list. 모든 phase 가 _UNIVERSAL 을 받고,
@@ -104,8 +142,9 @@ def _scan_one(
                 if block.get("type") != "tool_use" or block.get("name") != "Bash":
                     continue
                 command = (block.get("input") or {}).get("command") or ""
+                executed = strip_heredoc_bodies(command)
                 for label, pattern in patterns:
-                    if pattern.search(command):
+                    if pattern.search(executed):
                         hits.append((label, command))
                         break  # one violation per command — most-specific pattern wins
     return hits

package/runtime/validators/validate-implementation-plan-stages.py

@@ -12,10 +12,12 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import List, Tuple
 
-# scripts/ is not a package; insert it so okstra_ctl is importable directly.
-_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
+# scripts/ (repo) and python/ (installed under ~/.okstra/lib) are not packages;
+# insert whichever exists so okstra_ctl is importable directly.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
 

package/runtime/validators/validate-report-views.py

@@ -24,10 +24,10 @@ import re
 import sys
 from pathlib import Path
 
-REPO_ROOT = Path(__file__).resolve().parents[1]
-SCRIPTS_DIR = REPO_ROOT / "scripts"
-if str(SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(SCRIPTS_DIR))
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.clarification_items import (  # noqa: E402
     parse_clarification_items,

package/runtime/validators/validate-run.py

@@ -11,13 +11,14 @@ import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
-# Make the in-tree ``okstra_ctl`` package importable when this validator
-# runs from the repo (the installed runtime already has ~/.okstra/lib/python
-# on PYTHONPATH so the import is a no-op there).
+# Make the okstra packages importable however this validator is reached:
+# ``scripts/`` next to the repo checkout, ``python/`` next to the installed
+# copy under ~/.okstra/lib. The manifests advertise the bare script path, so
+# it must self-bootstrap rather than rely on an inherited PYTHONPATH.
 _VALIDATORS_DIR = Path(__file__).resolve().parent
-_SCRIPTS_DIR = _VALIDATORS_DIR.parent / "scripts"
-if _SCRIPTS_DIR.is_dir() and str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
 
 try:
     from okstra_ctl.final_report_schema import (

package/runtime/validators/validate-schedule.py

@@ -17,10 +17,12 @@ import re
 import sys
 from pathlib import Path
 
-# scripts/ is not a package; insert it so okstra_ctl is importable directly.
-_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
+# scripts/ (repo) and python/ (installed under ~/.okstra/lib) are not packages;
+# insert whichever exists so okstra_ctl is importable directly.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.md_table import split_pipe_row  # noqa: E402
 

package/runtime/validators/validate_fanout.py

@@ -10,9 +10,10 @@ import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
-_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
 from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402

package/runtime/validators/validate_improvement_report.py

@@ -12,10 +12,12 @@ import sys
 from dataclasses import dataclass, field
 from pathlib import Path
 
-# scripts/ is not a package; insert it so okstra_ctl is importable directly.
-_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
+# scripts/ (repo) and python/ (installed under ~/.okstra/lib) are not packages;
+# insert whichever exists so okstra_ctl is importable directly.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
 
 from okstra_ctl.improvement_lenses import (
     LENSES,

package/runtime/validators/validate_session_conformance.py

@@ -26,6 +26,18 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
 
+# scripts/ (repo) and python/ (installed under ~/.okstra/lib) are not packages;
+# insert whichever exists so okstra_ctl is importable directly.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
+
+from okstra_ctl.worker_heartbeat import (  # noqa: E402
+    HEARTBEAT_LINE_RE,
+    HEARTBEAT_MAX_GAP_SECONDS,
+)
+
 _DISPATCHED_STATUSES = {"completed", "timeout", "error", "in-progress"}
 _WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
 _ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -39,13 +51,10 @@ _PROGRESS_LINE_RE = re.compile(
     re.MULTILINE,
 )
 
-# claude-worker audit 사이드카의 heartbeat 라인 (claude-worker.md "Heartbeat").
-_HEARTBEAT_LINE_RE = re.compile(
-    r"^-[ \t]*PROGRESS:[ \t]*(?P<stage>\S+)[ \t]+(?P<ts>\S+)[ \t]*$", re.MULTILINE
-)
-# 계약상 cadence 는 5분. append 직전 측정한 시각과 실제 쓰기 사이 지연을 흡수하는
-# 고정 grace 60초를 더한다.
-_HEARTBEAT_MAX_GAP_SECONDS = 5 * 60 + 60
+# heartbeat 라인 shape 과 cadence 예산은 okstra_ctl.worker_heartbeat 정본을 쓴다 —
+# `okstra worker-liveness` 가 run 도중 같은 판정을 내리므로 정의가 갈리면 안 된다.
+_HEARTBEAT_LINE_RE = HEARTBEAT_LINE_RE
+_HEARTBEAT_MAX_GAP_SECONDS = HEARTBEAT_MAX_GAP_SECONDS
 
 # Phase 5/6 진입 전 lead 가 Read 해야 하는 implementation 프로파일 sidecar.
 # 절대 경로는 레이어(repo / runtime / 설치본)마다 다르지만 basename 은 동일하다.

package/src/cli-registry.mjs

@@ -159,6 +159,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Inventory wrapper sidecar logs by size and task (read-only)"],
   },
+  {
+    name: "worker-liveness",
+    module: "./commands/inspect/worker-liveness.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Report whether pending workers are still alive (read-only)"],
+  },
   {
     name: "error-report",
     module: "./commands/inspect/error-report.mjs",

package/src/commands/inspect/worker-liveness.mjs

@@ -0,0 +1,31 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra worker-liveness — report whether pending workers are still alive
+
+Usage:
+  okstra worker-liveness [--audit <path>]... [--prompt <path>]...
+                         [--max-idle <seconds>] [--launch-grace <seconds>] [--json]
+
+--audit   a claude-worker audit sidecar; stale past the heartbeat cadence means
+          the in-process worker hung.
+--prompt  a CLI-wrapper prompt-history path; no sibling .log or .status.json
+          past the launch grace means the wrapper never started.
+
+Output: JSON { ok, checkedAt, probes[], unhealthy[] }. Exit 1 when any worker is
+stalled or did not launch, so a poll loop can branch on the exit code. Read-only:
+it reports, it never kills or re-dispatches.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.worker_liveness",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/commands/lifecycle/preflight.mjs

@@ -1,5 +1,8 @@
 import { checkProject } from "./check-project.mjs";
 import { runEnsureInstalled } from "./install.mjs";
+import { missingHelperScripts } from "../../lib/helper-scripts.mjs";
+import { resolveInstalledScript } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra preflight — one-call skill preflight (ensure-installed + check-project)
 
@@ -11,8 +14,9 @@ verifies the target project has .okstra/project.json. Prints one JSON object:
 
   ok: true   {ok, projectRoot, projectJsonPath, projectId}
   ok: false  {ok, stage, reason, ...}
-             stage: install | resolve | project_json_missing |
-                    project_json_invalid | python | parse
+             stage: install | helper_scripts_missing | resolve |
+                    project_json_missing | project_json_invalid |
+                    python | parse
 
 Options:
   --runtime <name>   Runtime whose assets must be present (e.g. claude-code);
@@ -48,6 +52,12 @@ function emit(payload) {
   process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
 }
 
+// A BLOCKING lead step calls these mid-run; resolving them here turns a stale
+// install into an up-front failure instead of a dead end hours into a run.
+async function findMissingHelperScripts() {
+  return missingHelperScripts(await resolvePaths(), resolveInstalledScript);
+}
+
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -76,6 +86,19 @@ export async function run(args) {
     return installCode === 2 ? 2 : 1;
   }
 
+  const missingHelpers = await findMissingHelperScripts();
+  if (missingHelpers.length > 0) {
+    emit({
+      ok: false,
+      stage: "helper_scripts_missing",
+      missingHelpers,
+      reason:
+        `${missingHelpers.length} helper script(s) a lead prompt can call are not ` +
+        "installed — run 'okstra install' to repair before starting a run.",
+    });
+    return 1;
+  }
+
   const { code, payload } = await checkProject({ cwd: opts.cwd });
   emit(payload);
   return code;

package/src/lib/helper-scripts.mjs

@@ -0,0 +1,23 @@
+// Single source of truth for the python helper scripts that `okstra <cmd>`
+// subcommands front through runInstalledScript(). Preflight asserts every one
+// of them resolves under ~/.okstra/bin so a stale install fails at the cheap
+// environment gate instead of at the blocking lead step that calls it mid-run.
+// A contract test keeps this list in step with the `scriptName:` literals in
+// src/commands/**.
+
+export const HELPER_SCRIPT_NAMES = Object.freeze([
+  "okstra-error-log.py",
+  "okstra-incremental-carry.py",
+  "okstra-incremental-scope.py",
+  "okstra-inject-report-index.py",
+  "okstra-render-final-report.py",
+  "okstra-render-report-views.py",
+  "okstra-spawn-followups.py",
+  "okstra-token-usage.py",
+]);
+
+// `resolve` is the same resolver the wrappers call, so preflight cannot pass a
+// script the dispatch path would then fail to find.
+export function missingHelperScripts(paths, resolve) {
+  return HELPER_SCRIPT_NAMES.filter((name) => !resolve(paths, name));
+}

package/src/lib/python-helper.mjs

@@ -4,7 +4,7 @@ import { join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildPythonpath, resolvePaths } from "./paths.mjs";
 
-function resolveInstalledScript(paths, scriptName) {
+export function resolveInstalledScript(paths, scriptName) {
   // Prefer the installed copy under ~/.okstra/bin (what production users run);
   // fall back to the in-repo source when invoked from a checkout that has not
   // been installed (dev / CI).