okstra 0.125.6 → 0.128.0

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

@@ -91,29 +91,37 @@ If a required header line is absent from the dispatch prompt, return `<SENTINEL_
 
 ## Anchor headers (lead-injected, BLOCKING)
 
-Every worker prompt MUST begin with these anchor headers, in this exact order, before any other content. Workers extract them verbatim.
+Every initial worker prompt MUST begin with the common anchor headers below in this exact order, before any other content. An `implementation` prompt inserts the implementation-only coding-preflight anchor at the documented position. Workers extract the anchors verbatim.
 
 1. `**Project Root:** <absolute-path>` — required so the worker can self-anchor without relying on inherited cwd.
 2. `**Prompt History Path:** <project-relative-path>`
 3. `**Result Path:** <project-relative-path>` — canonical destination for the worker's result file.
 4. `Assigned worker prompt history path: <absolute-path>` — same as the prompt-history path but resolved against `Project Root`. Codex / Antigravity wrapper subagents extract this exact line.
 5. `**Worker Preamble Path:** <absolute-path>` — points to THIS file. Workers Read it end-to-end before doing anything else.
-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.
+6. `**Coding preflight pack:** <absolute-path>` — implementation-only; points to the installed runtime resource pack under `<OKSTRA_HOME>/prompts/coding-preflight`. It is present only when `taskType == implementation` and is absent from every non-implementation initial prompt. Implementation executors and implementation verifiers use it to read `overview.md`, `clean-code.md`, and routed language/framework/architecture resources. A pane display role named `verifier` does not activate this anchor in `final-verification`.
 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".
+**Exception — reverify dispatches.** A Phase 5.5 re-verification prompt (its `**Prompt History Path:**` carries a `-reverify-r<N>-` segment) deliberately omits anchor 5 and adds a `**Model:**` line — lightweight mode reads neither this file nor the implementation-only 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".
 
 For the **implementation phase** specifically, the dispatched prompt MUST also include:
 
 - `**Worktree:** <absolute-path>` — the task worktree path.
 - `cwd for every mutating command: <absolute-path>` — same as Worktree path; used by codex / antigravity wrappers as `--add-dir` / `--include-directories`.
 
-For the **final-verification phase** specifically, the dispatched prompt MUST also include the verification target snapshot so every analyser verifies the SAME target the lead captured at the entry gate:
+For the **final-verification phase** specifically, the dispatched prompt MUST include the compact identity of the canonical verification-target sidecar so every analyser verifies the SAME target the lead captured at the entry gate:
 
 - `**Worktree:** <absolute-path>` — the checkout under verification (read-only).
+- `**Verification scope:** <whole-task|single-stage>` — the selected verification mode.
 - `**Verification base ref:** <base-ref>` — the implementation base for the diff.
-- `**Verification diff stat:** <git diff --stat output>` — the captured diff-stat that bounds the verification scope.
+- `**Verification head ref:** <head-ref>` — the exact delivered revision under verification.
+- `**Verification target path:** <project-relative-path>` — the canonical `instruction-set/verification-target.md` sidecar containing stages, source reports, and the complete captured diff stat.
+- `**Verification target digest:** sha256:<digest>` — the digest over the normalized snapshot body.
+
+Read the sidecar on demand when the full stage/report mapping or diff stat is needed. Do not copy its `Verification diff stat` block into the dispatch prompt.
+
+The initial analysis prompt may contain exactly one `## Run-specific directive` section only when the run has a shared delta not already captured by the packet. The section applies unchanged to every selected analysis worker and is limited to 40 nonblank lines. If it would be longer, the lead writes the shared material into the instruction set and adds its common reference to `analysis-packet.md`; workers must not accept provider-, model-, or worker-specific verification scopes.
 
 For the **improvement-discovery phase** specifically, the dispatched prompt MUST also include the resolved-scope log the lead wrote during Phase 1.5, so workers key off an explicit absolute path instead of re-deriving the run directory:
 

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 (
@@ -57,6 +58,9 @@ from okstra_ctl.design_surfaces import (  # noqa: E402
     detect_design_surfaces,
     expected_prep_plan_item_id,
 )
+from okstra_ctl.worker_prompt_contract import (  # noqa: E402
+    validate_final_verification_prompt_paths,
+)
 
 TERMINAL_STATUSES = {"completed", "timeout", "error", "not-run"}
 ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
@@ -366,6 +370,48 @@ def effective_run_task_type(run_manifest: dict, task_manifest: dict) -> str:
     ).strip()
 
 
+def _validate_final_verification_initial_prompts(
+    data: dict,
+    failures: list[str],
+) -> None:
+    """Validate the selected initial analysis prompts persisted for the run."""
+    if data.get("taskType") != "final-verification":
+        return
+
+    run_manifest = data.get("runManifest") or {}
+    team_contract = run_manifest.get("teamContract") or {}
+    selected_workers = team_contract.get("requiredWorkerRoles") or []
+    selected_ids = {
+        str(worker.get("workerId") or "").strip()
+        for worker in selected_workers
+        if isinstance(worker, dict)
+    }
+    project_root = Path(data["projectRoot"])
+    team_state = data.get("teamState") or {}
+    prompt_paths: dict[str, Path] = {}
+    for worker in team_state.get("workers") or []:
+        if not isinstance(worker, dict):
+            continue
+        worker_id = str(worker.get("workerId") or "").strip()
+        prompt_value = str(worker.get("promptPath") or "").strip()
+        if (
+            worker_id not in selected_ids
+            or worker_id == "report-writer"
+            or not prompt_value
+            or "-reverify-r" in Path(prompt_value).name
+        ):
+            continue
+        prompt_path = Path(prompt_value)
+        prompt_paths[worker_id] = (
+            prompt_path if prompt_path.is_absolute() else project_root / prompt_path
+        )
+
+    errors = validate_final_verification_prompt_paths(prompt_paths)
+    failures.extend(
+        f"final-verification prompt contract: {error}" for error in errors
+    )
+
+
 def _is_legal_concurrent_run_skip(
     team_create: object, concurrent_run_authorized: bool
 ) -> bool:
@@ -3523,6 +3569,15 @@ def main() -> int:
     # contain every required section. Substring checks below are a
     # safety net for hand-edited or pre-v1.0 reports.
     task_type = effective_run_task_type(run_manifest, task_manifest)
+    _validate_final_verification_initial_prompts(
+        {
+            "taskType": task_type,
+            "projectRoot": project_root,
+            "runManifest": run_manifest,
+            "teamState": team_state,
+        },
+        failures,
+    )
     report_contracts = _normalize_report_contracts(
         run_manifest.get("reportContracts")
     )

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/log-report.mjs

@@ -6,9 +6,11 @@ Usage:
   okstra log-report [--project-root <dir>] [--cwd <dir>] [--top <N>] [--json]
 
 Output: JSON { ok, projectRoot, logsRoot, topLargest[], perTask[], totals }.
-Scans <project-root>/.okstra/tasks/**/runs/*/prompts/*.log. Sizes are raw bytes
-and mtimes are epoch seconds — the caller formats KB/MB and ages. Read-only: it
-never deletes logs (cleanup commands stay in the skill).
+Scans <project-root>/.okstra/tasks/**/runs/*/prompts/*.log. Each entry reports
+the wrapper transcript as transcriptBytes and its sibling prompt Markdown as
+promptBytes; sizeBytes remains the transcript-size compatibility field. Sizes
+are raw bytes and mtimes are epoch seconds — the caller formats KB/MB and ages.
+Read-only: it never deletes logs (cleanup commands stay in the skill).
 `;
 
 export async function run(args) {

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).