okstra 0.177.0 → 0.177.1

package/runtime/validators/validate-run.py

@@ -51,6 +51,10 @@ from okstra_ctl.conformance import (  # noqa: E402
     qa_result_from_dict,
     validate_conformance_manifest,
 )
+from okstra_ctl.dispatch_state import (  # noqa: E402
+    DispatchError,
+    v2_worker_state_key,
+)
 from okstra_ctl.paths import RunRef  # noqa: E402
 from okstra_ctl.report_contract import CURRENT_REPORT_SCHEMA_VERSION  # noqa: E402
 from okstra_ctl.release_gate import (  # noqa: E402
@@ -862,6 +866,12 @@ def extract_contract(
         required_worker_roles = []
         failures.append("requiredWorkerRoles is missing from run/task manifest")
 
+    optional_worker_roles = run_contract.get("optionalWorkerRoles")
+    if not isinstance(optional_worker_roles, list):
+        optional_worker_roles = task_contract.get("optionalWorkerRoles")
+    if not isinstance(optional_worker_roles, list):
+        optional_worker_roles = []
+
     lead_role = (
         run_contract.get("leadRole")
         or task_contract.get("leadRole")
@@ -892,6 +902,7 @@ def extract_contract(
             or ""
         ),
         "required_worker_roles": required_worker_roles,
+        "optional_worker_roles": optional_worker_roles,
         "required_agent_status_entries": [
             item
             for item in required_agent_status_entries
@@ -1216,6 +1227,24 @@ def _is_legal_concurrent_run_skip(
     )
 
 
+def _dispatch_roster_key(row: Mapping[str, Any]) -> str:
+    """The roster worker this dispatch row started, v1 or v2.
+
+    A v2 row carries no `workerId` — `_validate_agent_dispatch_contract`
+    fails the run when one is present, calling it a v1/v2 identity mix. So
+    reading the roster key off that field alone left every v2 row invisible
+    and reported workers okstra had in fact started as never dispatched. The
+    v2 projection is the one dispatch itself uses.
+    """
+    worker_id = str(row.get("workerId", "")).strip()
+    if worker_id:
+        return worker_id
+    try:
+        return v2_worker_state_key(row)
+    except DispatchError:
+        return ""
+
+
 def _validate_cmux_workers_were_dispatched_by_okstra(
     team_state: dict,
     workers: list,
@@ -1243,9 +1272,11 @@ def _validate_cmux_workers_were_dispatched_by_okstra(
     if str(adapter.get("name", "")).strip() != "cmux":
         return
     recorded = {
-        str(row.get("workerId", "")).strip()
+        key
         for row in team_state.get("workerDispatches") or []
         if isinstance(row, dict)
+        for key in (_dispatch_roster_key(row),)
+        if key
     }
     missing = []
     for worker in workers:
@@ -1447,7 +1478,15 @@ def validate_team_state(
         if status != "completed" and not reason:
             failures.append(f"{role} with status `{status}` must include a reason")
 
-    unexpected_roles = set(by_role) - set(expected_workers)
+    # A declared optional role may appear in the roster and may equally be
+    # absent: the run states which ones it can dispatch (today, the critics),
+    # and running one is not a contract violation.
+    optional_roles = {
+        str(worker.get("role", "")).strip()
+        for worker in contract.get("optional_worker_roles", [])
+        if isinstance(worker, dict) and str(worker.get("role", "")).strip()
+    }
+    unexpected_roles = set(by_role) - set(expected_workers) - optional_roles
     for role in sorted(unexpected_roles):
         failures.append(f"unexpected worker role detected: {role}")
 
@@ -1621,60 +1660,46 @@ def _scan_token_usage_summary(
 # a section heading line (not as inline text inside a paragraph or table).
 _VERDICT_CARD_HEADING_RE = re.compile(r"^##[ \t]+Verdict Card\b", re.MULTILINE)
 
-_V2_AI_HANDOFF_HEADINGS = (
-    "## AI Handoff Summary",
-    "## Clarification and User Decisions",
-    "## Evidence Ledger",
-    "## Task Deliverable:",
-    "## Cross Verification Audit",
-    "## Execution Audit",
-    "## Token and Cost Audit",
-)
-
-
-# `humanSummary` / `userNarrative` belong to the human HTML. The AI Markdown
-# renders field names as headings or bold labels
-# (scripts/okstra_ctl/report_markdown.py `humanise`), so this matches the two
-# forms the renderer can emit rather than the raw JSON key — a key name in
-# quotes no longer appears anywhere in the Markdown. Anchored to the start of a
-# line so the same words inside worker prose are not a violation.
-_V2_HUMAN_ONLY_RENDERED_RE = re.compile(
-    r"^(?:#{2,6}[ \t]+(?P<heading>Human Summary|User Narrative)[ \t]*$"
-    r"|[ \t]*-[ \t]+\*\*(?P<label>Human Summary|User Narrative)\*\*[ \t]*:)",
-    re.MULTILINE,
-)
-
-
-def _validate_v2_ai_handoff(content: str, failures: list[str]) -> None:
-    positions: list[int] = []
-    for heading in _V2_AI_HANDOFF_HEADINGS:
-        count = content.count(heading)
-        if count != 1:
+def _validate_v2_report(
+    report_data: Mapping[str, Any],
+    required_agent_status_entries: list[str],
+    failures: list[str],
+) -> None:
+    """Contract checks for a schema-v2 report, read from its data.json.
+
+    The AI-handoff markdown is a deterministic rendering of this record, so the
+    checks that used to scan it — heading count and order, human-only fields
+    leaking into the AI artifact, a Reading Confirmation heading — were asking
+    whether the renderer had done its job, not whether the report was sound.
+    Schema enforcement in `render_final_report._enforce_schema` already answers
+    the second question, and the first is settled by the template. What is left
+    is the pair of facts the markdown could only ever carry second-hand: which
+    agents the run must account for, and whether the token cells were filled.
+
+    Both are scanned over the serialized record, as text, because that is what
+    the markdown scan was. Requiring each label to equal an
+    `executionStatus[].role` would be a stricter rule than the contract states
+    anywhere: the schema types `role` as a free string, no prompt or worker spec
+    fixes its vocabulary, and `okstra_token_usage.report._match_worker_index`
+    treats function-role spellings ("Analysis verifier", "Acceptance critic") as
+    a shape reports do take — matching them by containment, never equality.
+    Tightening this belongs with an authoring rule that says what to write, not
+    on its own. Nothing is lost by reading the record instead of its rendering:
+    the labels never come from the template or the i18n dictionaries.
+    """
+    serialized = json.dumps(report_data, ensure_ascii=False)
+    for label in required_agent_status_entries:
+        if label not in serialized:
             failures.append(
-                "schema-v2 AI handoff markdown requires exactly one "
-                f"`{heading}` heading; found {count}."
+                f"final report does not include required agent status entry: {label}"
             )
-            continue
-        positions.append(content.index(heading))
-    if len(positions) == len(_V2_AI_HANDOFF_HEADINGS) and positions != sorted(
-        positions
-    ):
-        failures.append(
-            "schema-v2 AI handoff markdown heading order does not match "
-            "templates/reports/final-report-v2.template.md."
-        )
-    for match in _V2_HUMAN_ONLY_RENDERED_RE.finditer(content):
-        field = match.group("heading") or match.group("label")
-        failures.append(
-            "schema-v2 AI handoff markdown contains human-only field "
-            f"{field!r}; render it only in the task-specific HTML."
-        )
-    if READING_CONFIRMATION_HEADING_RE.search(content) is not None:
-        failures.append(
-            "final report contains a `## 0. Reading Confirmation` heading — "
-            "Reading Confirmation lives in the worker audit sidecar, never "
-            "in the AI handoff markdown."
-        )
+    for placeholder in TOKEN_PLACEHOLDERS:
+        if placeholder in serialized:
+            failures.append(
+                f"final report contains unsubstituted token placeholder `{placeholder}` — "
+                "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
+            )
+
 
 # Top-of-report Index block. The renderer
 # (scripts/okstra_ctl/render_final_report.py) injects `<a id="report-index">`
@@ -1782,16 +1807,34 @@ def _load_conformance_results(qa_dir: Path, manifest: dict) -> dict:
     return results
 
 
-_DIFF_SUMMARY_RE = re.compile(r"^###\s+5\.7\.3\b.*?(?=^###\s|\Z)", re.MULTILINE | re.DOTALL)
-_DIFF_ROW_PATH_RE = re.compile(r"^\|\s*`([^`]+)`\s*\|", re.MULTILINE)
+def _diff_summary_files(report_data: Mapping[str, Any]) -> list[str]:
+    """implementation 리포트가 신고한 변경 파일 목록 (`implementation.diffSummary.files[].file`).
 
+    렌더된 §5.7.3 표를 정규식으로 긁던 자리다. 표는 data.json 의 이 배열에서
+    렌더되는 파생물이라, 표를 읽는 쪽은 렌더 형식이 바뀔 때마다 조용히 빈
+    목록을 돌려주고 — conformance / self-mock 두 게이트가 전부 통과로 열렸다.
+    스키마가 `implementation` 블록에서 `diffSummary` 를 required 로 잡고
+    `rawStat` 이 비어있지 않으면 `files` 최소 1행을 요구하므로, 여기서는
+    구조가 어긋난 경우만 빈 목록으로 떨어뜨린다.
 
-def _parse_diff_summary_files(content: str) -> list[str]:
-    """implementation 리포트 §5.7.3 Diff Summary 표의 첫 셀(백틱 경로)들을 추출."""
-    section = _DIFF_SUMMARY_RE.search(content)
-    if section is None:
+    `diffSummary` 를 가진 task-type 은 implementation 뿐이다. final-verification
+    은 diff 를 `diffSummaryQuote` 문자열로만 인용하므로 두 게이트는 거기서
+    (md 를 읽던 시절과 똑같이) vacuous 하다.
+    """
+    implementation = report_data.get("implementation")
+    if not isinstance(implementation, Mapping):
+        return []
+    diff_summary = implementation.get("diffSummary")
+    if not isinstance(diff_summary, Mapping):
         return []
-    return _DIFF_ROW_PATH_RE.findall(section.group(0))
+    rows = diff_summary.get("files")
+    if not isinstance(rows, list):
+        return []
+    return [
+        row["file"]
+        for row in rows
+        if isinstance(row, Mapping) and isinstance(row.get("file"), str) and row["file"]
+    ]
 
 
 _STAGE_RUN_DIR_RE = re.compile(r"^stage-\d+$")
@@ -2155,12 +2198,12 @@ def _validate_planning_conformance_declared(report_path: Path, failures: list[st
 
 
 def _validate_conformance_surfaces(
-    report_path: Path,
+    report_data: Mapping[str, Any],
     scoped_manifest: dict,
     surface_patterns: object,
     failures: list[str],
 ) -> None:
-    changed_files = _parse_diff_summary_files(report_path.read_text(encoding="utf-8"))
+    changed_files = _diff_summary_files(report_data)
     if not changed_files:
         return
     uncovered = (
@@ -2196,6 +2239,7 @@ def _validate_conformance(
     own stage suffix. Whole-task runs evaluate every entry.
     """
     warnings: list[str] = []
+    report_data = _load_final_report_data(report_path)
     # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
     # implementation/final-verification 가 공유한다. report_path 는
     # task_root/runs/<task-type>/reports/final-report.md (implementation 은
@@ -2236,7 +2280,7 @@ def _validate_conformance(
                     f"{manifest_path} is absent"
                 )
         _validate_conformance_surfaces(
-            report_path,
+            report_data,
             empty_scoped_manifest,
             surface_patterns,
             failures,
@@ -2300,7 +2344,7 @@ def _validate_conformance(
                 f"docs/superpowers/specs/2026-06-07-stage-conformance-qa-design.md."
             )
     _validate_conformance_surfaces(
-        report_path,
+        report_data,
         scoped,
         surface_patterns,
         failures,
@@ -2638,13 +2682,13 @@ def _validate_selfmock(report_path: Path, failures: list[str]) -> None:
     Stage-isolated runs read their own `self-mock-stage-<N>.json`; whole-task runs
     read the flat `self-mock.json`.
 
-    Only the implementation template renders the §5.7.3 diff summary
-    (`templates/reports/final-report-v2.template.md:589`); a final-verification report
-    quotes the diff as a blockquote instead, so this gate is vacuous there by
-    design — self-mock is enforced at the implementation stage, and
-    final-verification is a read-only re-verify that adds no test files.
+    Only an implementation report carries `implementation.diffSummary.files[]`;
+    a final-verification report records the diff as the `diffSummaryQuote`
+    string instead, so this gate is vacuous there by design — self-mock is
+    enforced at the implementation stage, and final-verification is a read-only
+    re-verify that adds no test files.
     """
-    changed = _parse_diff_summary_files(report_path.read_text(encoding="utf-8"))
+    changed = _diff_summary_files(_load_final_report_data(report_path))
     test_files = [
         path
         for path in changed
@@ -2745,8 +2789,8 @@ def _check_selfmock_changed_files(
     `--changed-file` is what the mutation adapters select their production
     sources from. Omit it and every adapter gets an empty target set, which is
     not a finding but reads like one had been looked for. Requiring the sidecar
-    to account for every file in the §5.7.3 diff summary keeps "gate B saw this
-    stage" apart from "gate B was handed nothing".
+    to account for every file in `implementation.diffSummary.files[]` keeps
+    "gate B saw this stage" apart from "gate B was handed nothing".
 
     Coverage is asked of the WHOLE diff, not just its test files: the production
     sources are precisely the part gate A never looks at.
@@ -2771,7 +2815,8 @@ def _check_selfmock_changed_files(
             f"the mutation gate — {sidecar} records changedFiles={declared}. Each "
             "adapter picks its production sources out of that set, so a file left "
             "out is a file no mutant was ever generated for. Pass every path from "
-            "the §5.7.3 diff summary with `--changed-file`, production sources "
+            "the report's `implementation.diffSummary.files[]` with `--changed-file`, "
+            "production sources "
             "included — filtering to the test files leaves gate B nothing to run "
             "on and reports a pass it never earned."
         )
@@ -2835,6 +2880,10 @@ def validate_report(
         failures.append(f"final report is missing: {report_path}")
         return
 
+    if (report_data or {}).get("schemaVersion") == "2.0":
+        _validate_v2_report(report_data or {}, required_agent_status_entries, failures)
+        return
+
     content = report_path.read_text()
     for label in required_agent_status_entries:
         if label not in content:
@@ -2849,10 +2898,6 @@ def validate_report(
                 "run `okstra-token-usage.py ... --substitute-data <report-path>` during Phase 7"
             )
 
-    if (report_data or {}).get("schemaVersion") == "2.0":
-        _validate_v2_ai_handoff(content, failures)
-        return
-
     # Catch the "workers typed `0` / `pending` instead of the placeholder"
     # failure mode that bypasses the placeholder check above.
     _scan_token_usage_summary(

package/runtime/validators/validate_session_conformance.py

@@ -1034,7 +1034,7 @@ def _check_batch_cleanup_checkpoints(
     실제로 일어났는지 (prompts/profiles/_common-contract.md 'Phase-start cleanup').
     R1=convergence round 1 직전, R2=report-writer dispatch 직전(수렴이 있었으면
     마지막 라운드 이후 별도 1회). ISO-8601 ts 는 lexicographic 비교가 곧 시간순."""
-    detail = "prompts/profiles/_common-contract.md 'Phase-start cleanup'"
+    detail = "prompts/lead/okstra-lead-contract.md 'Run-scoped worker-resource lifecycle'"
     cleanup_ts = sorted(ts for ts, _line in by_phase.get("phase-batch-cleanup", []))
     conv_ts = sorted(ts for ts, _line in by_phase.get("phase-5.5-convergence", []))
     synth_ts = sorted(ts for ts, _line in by_phase.get("phase-6-synthesis", []))

package/runtime/bin/okstra-trace-cleanup.sh

@@ -1,185 +0,0 @@
-#!/usr/bin/env bash
-#
-# okstra-trace-cleanup.sh — close the harness-owned worker panes of an okstra run.
-#
-# The panes this closes are the teammate panes the HARNESS splits for dispatched
-# worker agents. okstra does not create them and cannot tag them, so they are
-# found by a title allowlist scoped to the lead's window. They accumulate until
-# the pane budget runs out, and `shutdown_request` only idles the agent without
-# freeing its pane — this script is the only thing that closes them, which is why
-# the lead calls it at every round boundary and before every user gate.
-#
-# Two tag-driven paths used to live here and both are gone:
-#
-#   - Worker-compute panes of the `tmux-pane` dispatch backend, tagged
-#     `@okstra_worker_run`. That backend was removed — a worker now gets a cmux
-#     surface or a cli-wrapper subprocess, and neither is a tmux pane okstra owns.
-#   - Trace panes, tagged `@okstra_trace_run` / `@okstra_status`, which the
-#     provider wrappers used to split as `tail -F` siblings. The wrappers became
-#     four-line entrypoints and worker progress renders into the worker's own
-#     pane, so nothing had spawned a trace pane for some time.
-#
-# With both writers gone the tag scan matched nothing, so it was removed along
-# with the two modes that existed only to drive it (`--reap`, which the SessionEnd
-# hook called, and `--reclaim-completed`, which `okstra-subagent-reclaim.sh` drove
-# from SubagentStop / TaskCompleted). Those hooks are gone from the seeded
-# settings too.
-#
-# Invocation:
-#
-#   --run-dir <RUN_DIR>   Closes the run's worker-agent panes (`claude-worker` /
-#                         `codex-worker` / `antigravity-worker` /
-#                         `report-writer-worker` and the FleetView teammate
-#                         prefixes), scoped to the LEAD's WINDOW. The lead pane is
-#                         read from `<RUN_DIR>/state/lead-pane.id` (recorded once
-#                         by the lead in its own foreground pane — reliable even
-#                         though Claude Code's Bash tool strips `$TMUX` /
-#                         `$TMUX_PANE`); it scopes the scan and is NEVER killed.
-#                         Window scope keeps a second lead running in another
-#                         window of the same session out of range.
-#
-# `--list` (alias `--dry-run`) prints `<pane_id>\t<pane_title>` per pane instead
-# of killing.
-#
-# `--keep <substr>` (repeatable) spares any pane whose current title contains
-# <substr>, in both the kill and the list set. Used to preserve an in-flight
-# report-writer at a round boundary.
-#
-# Failures are tolerated silently — a stale pane id, no tmux, or a locked tmux
-# client must never prevent Claude from exiting cleanly.
-
-set -u
-
-# Caller-pane resolution helper (okstra_resolve_caller_pane) — see
-# lib/okstra/tmux-pane.sh. Used as the lead-pane fallback below so a missing /
-# stale lead-pane.id resolves to the pane THIS process actually runs in (via
-# ancestor-PID ↔ tmux pane_pid matching), never a foreign active-client pane.
-# Bin-sibling path in repo + installed layouts; degrade silently if absent.
-_clean_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
-[ -r "$_clean_script_dir/lib/okstra/tmux-pane.sh" ] && . "$_clean_script_dir/lib/okstra/tmux-pane.sh"
-
-MODE="kill"   # kill | list
-run_dir=""
-KEEP_PATTERNS=()   # --keep <substr>: panes whose title contains substr are spared from kill/list
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --list|--dry-run) MODE="list" ;;
-    --run-dir)        shift; run_dir="${1-}" ;;
-    --run-dir=*)      run_dir="${1#--run-dir=}" ;;
-    --keep)           shift; KEEP_PATTERNS+=("${1-}") ;;
-    --keep=*)         KEEP_PATTERNS+=("${1#--keep=}") ;;
-    -h|--help)
-      cat <<'USAGE'
-usage: okstra-trace-cleanup.sh --run-dir <RUN_DIR> [--list] [--keep <substr>]...
-
-  --run-dir            okstra run directory; closes that run's worker-agent panes.
-  --list               print "<pane_id>\t<pane_title>" per pane; no kill.
-  --dry-run            alias for --list.
-  --keep <substr>      exclude any pane whose title contains <substr> from the
-                       kill/list set (repeatable). Used to spare an in-flight
-                       report-writer at a round boundary.
-USAGE
-      exit 0 ;;
-    *)
-      printf 'okstra-trace-cleanup.sh: unknown option: %s\n' "$1" >&2
-      exit 2 ;;
-  esac
-  shift
-done
-
-if [[ -z "$run_dir" ]]; then
-  printf 'okstra-trace-cleanup.sh: --run-dir <RUN_DIR> is required\n' >&2
-  exit 2
-fi
-
-# Lead pane. Prefer the value the lead recorded in its own foreground pane; fall
-# back to the active-pane probe. Rejected if the recorded pane is gone.
-lead_pane=""
-lead_pane_file="$run_dir/state/lead-pane.id"
-[[ -r "$lead_pane_file" ]] && lead_pane="$(head -n1 "$lead_pane_file" 2>/dev/null || true)"
-if [[ -z "$lead_pane" ]] || ! tmux display-message -p -t "$lead_pane" '#{pane_id}' >/dev/null 2>&1; then
-  if type okstra_resolve_caller_pane >/dev/null 2>&1; then
-    lead_pane="$(okstra_resolve_caller_pane 2>/dev/null || true)"
-  else
-    lead_pane="$(tmux display-message -p '#{pane_id}' 2>/dev/null || true)"
-  fi
-fi
-
-_title_in_okstra_scope() {
-  local title="$1"
-  case "$title" in
-    # Claude/FleetView teammate panes may carry the task title instead of the
-    # worker id. These glyph prefixes are the only stable tmux-side signal.
-    "✳ "*|"⠂ "*)
-      return 0 ;;
-    *claude-worker*|*claude-executor*|*claude-verifier*)
-      return 0 ;;
-    *codex-worker*|*codex-executor*|*codex-verifier*)
-      return 0 ;;
-    *agy-worker*|*agy-executor*|*agy-verifier*)
-      return 0 ;;
-    *antigravity-worker*|*antigravity-executor*|*antigravity-verifier*)
-      return 0 ;;
-    *report-writer-worker*|*report-writer*)
-      return 0 ;;
-  esac
-  return 1
-}
-
-# A collected pane whose current title contains any --keep substring is spared.
-_keep_excluded() {
-  local pid="$1" title pat
-  (( ${#KEEP_PATTERNS[@]} )) || return 1
-  title=$(tmux display-message -p -t "$pid" '#{pane_title}' 2>/dev/null || true)
-  for pat in "${KEEP_PATTERNS[@]}"; do
-    [[ -n "$pat" && "$title" == *"$pat"* ]] && return 0
-  done
-  return 1
-}
-
-collect_okstra_panes() {
-  local -a panes=()
-  local pid title
-
-  # Title-allowlisted worker-agent panes in the lead's WINDOW. `list-panes -t
-  # <pane>` (no `-s`, no `-a`) resolves the window containing that pane and lists
-  # only that window's panes. Split-pane teammates always land in the lead's
-  # window, so this catches all of THIS run's worker panes while a second okstra
-  # lead in another window of the same tmux session is left untouched. Skipped
-  # when the lead pane is unknown.
-  [[ -n "$lead_pane" ]] || return 0
-  while IFS=$'\t' read -r pid title; do
-    [[ -n "$pid" ]] || continue
-    [[ "$pid" == "$lead_pane" ]] && continue
-    if _title_in_okstra_scope "$title"; then
-      panes+=("$pid")
-    fi
-  done < <(tmux list-panes -t "$lead_pane" \
-             -F '#{pane_id}'$'\t''#{pane_title}' 2>/dev/null || true)
-
-  # Drop any pane a --keep pattern spares (in-flight report-writer).
-  if (( ${#panes[@]} )); then
-    printf '%s\n' "${panes[@]}" | awk 'NF && !seen[$0]++' | while IFS= read -r _pid; do
-      _keep_excluded "$_pid" && continue
-      printf '%s\n' "$_pid"
-    done
-  fi
-}
-
-if [[ "$MODE" == "list" ]]; then
-  while IFS= read -r pane_id; do
-    [[ -n "$pane_id" ]] || continue
-    # `display-message -p` resolves a *live* pane's title; for stale ids tmux
-    # exits non-zero — fall back to an empty title rather than failing.
-    title=$(tmux display-message -p -t "$pane_id" '#{pane_title}' 2>/dev/null || true)
-    printf '%s\t%s\n' "$pane_id" "$title"
-  done < <(collect_okstra_panes)
-  exit 0
-fi
-
-while IFS= read -r pane_id; do
-  [[ -n "$pane_id" ]] || continue
-  tmux kill-pane -t "$pane_id" 2>/dev/null || true
-done < <(collect_okstra_panes)
-
-exit 0