okstra 0.125.5 → 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.5",
+  "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.5",
-  "builtAt": "2026-07-20T12:43:22.033Z",
+  "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/`.
@@ -87,7 +87,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
-- **Verdict Card consistency.** `verdictCard.verdictToken` / `.direction` / `.nextStep` MUST byte-match `finalVerdict.verdictToken` / `.direction` / `.nextStep` and `recommendedNextSteps[0].text`. The renderer pulls both from the same data structure — duplicating values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
+- **Verdict Card consistency.** `verdictCard.verdictToken` and `verdictCard.direction` MUST byte-match `finalVerdict.verdictToken` / `.direction`; `validators/validate-run.py` diffs both and fails the run on divergence. `verdictCard.nextStep` names the same action as `finalVerdict.nextStep` and `recommendedNextSteps[0].text` but is written as the actionable command the reader runs (e.g. `/okstra-run task-key=… task-type=release-handoff`) where the other two are prose — it is deliberately not a byte copy. Duplicating the compared values across `verdictCard` and `finalVerdict` is intentional so the validator can diff them.
 - **Reader Summary.** Populate `readerSummary` when the schema excerpt exposes it. It is the human-first entrypoint for both Markdown and HTML: one sentence for the decision, one for the human action required, one for blockers, one for audit sections safe to skip on first read, and one runnable recommended command. Do not duplicate raw evidence tables here.
 - **§7 phase-continuation row (mandatory for non-terminal task-types).** When `header.taskType` is one of `requirements-discovery` / `implementation-planning` / `error-analysis` / `implementation` / `final-verification`, `followUpTasks` MUST contain at least one row whose `origin` is `phase-continuation`, `suggestedTaskType` equals the next phase (byte-identical to `finalVerdict.nextStep`'s referenced phase), `newTaskId` reuses the current task-id, `autoSpawn` is `"no"`, and `priority` is `"P0"`. For `release-handoff` runs, omit the phase-continuation row. Schema `allOf` clause enforces this via `contains`.
 - **No deprecated sections.** The schema has no `4.5.8 User Approval Request` body field, no `4.5.9 Open Questions`, no `5.1 Additional Material Request`, no `5.2 User Confirmation Questions` — clarifications go under the unified `clarificationItems[]` array.

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/prompts/profiles/_common-contract.md

@@ -70,7 +70,7 @@ profile document.
   - the same `final-report.md` file is the canonical artifact carried into the next run; the user appends answers inline before rerunning. The preferred turn-around is `scripts/okstra.sh --resume-clarification --task-key <project-id>:<task-group>:<task-id>` (opens the latest report in `$EDITOR`, then auto-reruns the same phase with `--clarification-response` carry-in). The lower-level form `--clarification-response <path>` remains available for scripted runs.
   - if a clarification response was carried in for this run, render the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it), walk every `C-*` row of the prior report's `## 1. Clarification Items` table, reconcile each one against new evidence, and update its `Status` to `resolved` or `obsolete` before issuing the next decision/verdict. When no carry-in path was provided, omit the `## 0.` heading entirely — the validator fails reports that emit an empty Section 0 stub (e.g. "No prior clarification response was provided for this run.").
 - Verdict Card (shared — applies to every final-report regardless of profile):
-  - The top-of-report `## Verdict Card` block is mandatory in every final-report. Its `Verdict Token`, `Direction`, and `Next Step` cells MUST byte-match the corresponding cells in `## 7. Final Verdict` and the first item of `## 3. Recommended Next Steps`. The validator treats the card as a non-authoritative index — when card values diverge from the authoritative sections, the run is `contract-violated`.
+  - The top-of-report `## Verdict Card` block is mandatory in every final-report. Its `Verdict Token` and `Direction` cells MUST byte-match the corresponding cells in `## 7. Final Verdict` — the card is a non-authoritative index and divergence makes the run `contract-violated`. **Enforced:** `validators/validate-run.py` `_validate_verdict_card_consistency` (token, on the rendered markdown) and `_validate_verdict_card_fields` (direction, on data.json). The `Next Step` cell points at the SAME action as `## 7. Final Verdict` and the first item of `## 3. Recommended Next Steps`, but is written as the actionable command the reader runs (`/okstra-run task-type=release-handoff`) where §7 states it as prose — it is not a byte copy and is not compared.
 - Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 6.` / `## 2.` tables in the final-report):
   - **Worker-side item IDs (free-form but unique within the worker).** Every row item in sections 1–5 (and any optional section 6) of an analysis worker's output MUST carry an item ID that is unique within that one worker's result file. The ID convention is the worker's choice — `F-001` / `F-002` per the suggested schema, `1.1` / `1.2` / `1.3` as Codex tends to use, or any other shape — but it MUST appear as the leading column of the row (for table-form items) or as a `[<ID>]` prefix (for bullet/numbered items). Workers that emit findings without IDs make cross-worker reconciliation impossible.
   - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. The `Source items` column (or, where the template still calls it `Supporting workers` / `Workers (position)` / `Source`, that same column) MUST list every contributing worker:item pair (e.g. `claude:F-001, codex:1.1, antigravity:F-3`) so a reviewer can trace the synthesised row back to each worker's original wording without re-reading every worker-results file. Bare worker names without item IDs (e.g. `claude, codex, antigravity`) are deprecated for these tables; the validator does not yet fail on them but the readability pass treats it as a contract violation.

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