okstra 0.125.5 → 0.127.0

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 (
@@ -1529,6 +1530,32 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
         )
 
 
+def _validate_verdict_card_fields(data: dict, failures: list[str]) -> None:
+    """`verdictCard.direction` must byte-match its authoritative home in §7.
+
+    The markdown check above compares only the Verdict Token, so a Card whose
+    Direction contradicted §7 shipped silently. `nextStep` is deliberately NOT
+    compared: every shipped fixture authors the Card's cell as the actionable
+    command (`/okstra-run task-type=release-handoff`) while §7 states the same
+    action as prose ("Proceed to release-handoff."), so a byte-match rule there
+    would reject the reference reports.
+    """
+    card = data.get("verdictCard")
+    final = data.get("finalVerdict")
+    if not isinstance(card, dict) or not isinstance(final, dict):
+        return
+    card_value = str(card.get("direction") or "").strip()
+    final_value = str(final.get("direction") or "").strip()
+    if not card_value or not final_value or card_value == final_value:
+        return
+    failures.append(
+        f"final-report data.json: verdictCard.direction `{card_value}` does not "
+        f"match finalVerdict.direction `{final_value}` — the Card is a "
+        "non-authoritative index and MUST byte-match §7 "
+        "(_common-contract.md Verdict Card)."
+    )
+
+
 def _load_final_report_data(report_path: Path) -> dict:
     """Best-effort parse of the final-report data.json sibling. Returns {} when
     absent or unparseable — those conditions are already surfaced as failures by
@@ -1596,6 +1623,7 @@ def validate_final_report_data(
 
     _validate_rationale_evidence(data, failures)
     _validate_no_opaque_id_references(data, failures)
+    _validate_verdict_card_fields(data, failures)
     # Phase-agnostic: the coverage critic runs in every finding-producing phase.
     _validate_unverified_critic_gaps_recorded(data, failures)
 
@@ -1907,6 +1935,27 @@ _PLAN_ITEM_SOURCES = (
 )
 
 
+def _plan_item_source_count(planning: dict, field: str) -> int:
+    """Row count for one plan-body deliverable array.
+
+    `stepwiseExecution` has two homes: the top-level array is the legacy flat
+    summary (schema: "Legacy flat summary kept for compatibility only. New
+    reports use stageMap/stages") and is absent from `implementationPlanning.
+    required`, while a current report carries the real steps per stage. Counting
+    only the legacy field made this whole check a no-op for the largest
+    category — a modern plan could drop every `P-Step-*` item and still pass.
+    """
+    rows = [r for r in (planning.get(field) or []) if isinstance(r, dict)]
+    if field != "stepwiseExecution":
+        return len(rows)
+    per_stage = sum(
+        len([s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)])
+        for stage in (planning.get("stages") or [])
+        if isinstance(stage, dict)
+    )
+    return per_stage or len(rows)
+
+
 def _validate_plan_item_extraction_completeness(
     data: dict,
     failures: list[str],
@@ -1934,7 +1983,7 @@ def _validate_plan_item_extraction_completeness(
         if isinstance(it, dict)
     ]
     for field, prefix, label in _PLAN_ITEM_SOURCES:
-        source_count = len([r for r in (ip.get(field) or []) if isinstance(r, dict)])
+        source_count = _plan_item_source_count(ip, field)
         if source_count == 0:
             continue
         extracted = len(
@@ -3041,6 +3090,65 @@ def _validate_forbidden_actions(
     failures.extend(f"forbidden-action: {v}" for v in violations)
 
 
+CLASSIFICATION_COUNT_KEYS = {
+    "full-consensus": "fullConsensus",
+    "partial-consensus": "partialConsensus",
+    "contested": "contested",
+    "worker-unique": "workerUnique",
+}
+
+
+def classification_counts_from_findings(findings) -> dict:
+    """Recompute `finalClassificationCounts` from `findings[].classification`.
+
+    Shared with `tests/contract/test_convergence_state_contract.py` so the
+    invariant has one definition — it used to live only in that test, which
+    meant it was checked against four hand-written fixtures and never against
+    the state a lead actually writes.
+    """
+    counts = {value: 0 for value in CLASSIFICATION_COUNT_KEYS.values()}
+    for finding in findings or []:
+        if not isinstance(finding, dict):
+            continue
+        key = CLASSIFICATION_COUNT_KEYS.get(finding.get("classification"))
+        if key:
+            counts[key] += 1
+    return counts
+
+
+def _validate_convergence_state_counts(run_dir, failures) -> None:
+    """A run's convergence state must agree with its own findings list.
+
+    `finalClassificationCounts` is a lead-authored summary of
+    `findings[].classification`. Nothing recomputed it against the real
+    artifact, so a miscount survived into the report as two different truths
+    (observed on dev-6901 planning 009: declared partial 6 / worker-unique 4
+    against an actual 5 / 5). Downstream readers pick one arbitrarily.
+    """
+    from pathlib import Path as _Path
+
+    state_dir = _Path(run_dir) / "state"
+    if not state_dir.is_dir():
+        return
+    for state_path in sorted(state_dir.glob("convergence-*.json")):
+        try:
+            state = json.loads(state_path.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as exc:
+            failures.append(f"convergence state {state_path.name} unreadable: {exc}")
+            continue
+        declared = state.get("finalClassificationCounts")
+        if not isinstance(declared, dict):
+            continue
+        actual = classification_counts_from_findings(state.get("findings"))
+        if declared != actual:
+            failures.append(
+                f"convergence state {state_path.name}: finalClassificationCounts "
+                f"{declared} does not match findings[].classification {actual}. "
+                "The counts are a summary of the findings list — a mismatch means "
+                "the run reports two different classifications for the same work."
+            )
+
+
 def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
     """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
     실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
@@ -3478,6 +3586,8 @@ def main() -> int:
     if task_type == "requirements-discovery":
         run_dir = report_path.parent.parent
         _validate_requirements_discovery_fanout(run_dir, failures)
+    # Phase-agnostic: convergence runs in every finding-producing phase.
+    _validate_convergence_state_counts(report_path.parent.parent, failures)
     validate_report_views(report_path, failures)
 
     validation_status = "passed" if not failures else "failed"

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",