okstra 0.191.0 → 0.191.2

package/docs/architecture.md

@@ -938,7 +938,7 @@ Tokens used in each run are collected from lead/worker session transcripts and w
 - Collection sources:
   - Claude lead/workers: per-message `message.usage` in `~/.claude/projects/<cwd-as-dashes>/<sessionId>.jsonl` or `~/.claude/projects/<cwd-as-dashes>/<lead-session>/subagents/agent-a<worker-name>-<hash>.jsonl`. Worker names are recovered from nested-subagent filenames, and only the directory for the current run's `team-state.lead.sessionId` is counted.
   - Codex CLI: final `total_token_usage.total_tokens` in `~/.codex/sessions/Y/M/D/rollout-*.jsonl` (`$CODEX_HOME/sessions` first, then `~/.agent/sessions`). An in-session codex lead (`entryMode: current-session`) opened its rollout before the run and keeps it after, so its cumulative snapshot is the whole session; the lead is counted as the sum of `last_token_usage` over the `token_count` events inside the run window (`codex_session_window_total`), and a session that started before the window still qualifies when it wrote inside it (`find_codex_sessions(active_before_start=True)`).
-  - Grok CLI: the last `usage` snapshot in `~/.grok/sessions/<percent-encoded cwd>/<sessionId>/updates.jsonl`. grok (and kimi) run *inside* the stage worktree, so the directory is encoded from the worktree path, not the project root.
+  - Grok CLI: the sum of the `usage` records in `~/.grok/sessions/<percent-encoded cwd>/<sessionId>/updates.jsonl` — one record is one prompt's usage (`numTurns` model calls, input re-sent each call), not a running total, so the last record alone is only the last prompt. grok (and kimi) run *inside* the stage worktree, so the directory is encoded from the worktree path, not the project root. An in-session grok lead is counted over the records inside the run window (`grok_session_window_total`), and a session that started before the window still qualifies when it wrote inside it (`find_grok_sessions(active_before_start=True)`).
   - Claude workers on a non-Claude host: the wrapper runs `claude -p --session-id <id>`, and the transcript is `~/.claude/projects/<cwd-as-dashes>/<id>.jsonl`, found by the id `workerDispatches[].sessionId` recorded at dispatch.
 - **Attribution key is the dispatch ledger, not the roster row.** `workers[].promptPath` names one prompt — the first dispatch — and v2 lead events carry no `workerId`. Every re-dispatch (reverify, critic-gap, plan-verify, report-writer re-author) is a new wrapper run with its own prompt, `.status.json`, and transcript, and only `team-state.workerDispatches[]` lists them all (`dispatch_state.worker_dispatch_records`, keyed by `workerId` or the last segment of `assignmentRef`). The collector takes one wrapper window per record, unions the transcripts found under each record's `worktreePath` and the project root, and sums them; wall-clock is the sum of the wrapper windows. Observed before this rule (2026-09-08, a codex-host planning run): codex counted 1 of 5 sessions, grok 0 of 1, claude 0 of 7.
   - Antigravity CLI: the `usage` snapshot in the wrapper `<prompt>.status.json` — the runner records the last `usage` the `agy` stream reported (`result.usage` on a run that closed). The CLI writes no transcript under the home directory, and the worker `.log` is the stream rewritten as readable lines, not stream-json.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.191.0",
+  "version": "0.191.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.191.0",
-  "builtAt": "2026-09-08T21:03:17.927Z",
+  "package": "0.191.2",
+  "builtAt": "2026-09-09T06:51:26.651Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/bin/okstra-report-translate.py

@@ -25,6 +25,7 @@ from __future__ import annotations
 import argparse
 import hashlib
 import json
+import re
 import os
 import sys
 from pathlib import Path
@@ -199,17 +200,31 @@ def _translation_block(rows: list[str]) -> str:
     return "\n".join(rows).strip().replace("\\`", "`")
 
 
+_T_HEADING_RE = re.compile(r"^#{1,6}\s+T-\d{3}\b")
+
+
 def _translation_blocks(path: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     blocks: list[str] = []
     current: list[str] | None = None
-    for row in text.splitlines():
+    for number, row in enumerate(text.splitlines(), start=1):
+        # 헤딩 수준이 다른 `### T-NNN` 은 블록 경계로 안 보여 본문에 묻히고, 그러면
+        # 블록 수 불일치라는 엉뚱한 메시지가 났다(실측 2026-09-08: id 164개 전부
+        # 일치, 틀린 것은 `#` 개수뿐). 경계처럼 생긴 줄은 여기서 이름을 대고 거절한다.
+        if _T_HEADING_RE.match(row) and not row.startswith("## T-"):
+            raise SystemExit(
+                f"error: translation heading must be level 2 — line {number} is "
+                f"{row.split()[0]!r}, expected '## T-NNN' ({path.name})"
+            )
         if row.startswith("## T-"):
             if current is not None:
                 blocks.append(_translation_block(current))
             expected = f"## T-{len(blocks) + 1:03d}"
             if row != expected:
-                raise SystemExit(f"error: expected translation heading {expected}")
+                raise SystemExit(
+                    f"error: expected translation heading {expected} at line {number}, "
+                    f"found {row!r} ({path.name})"
+                )
             current = []
         elif current is not None:
             current.append(row)
@@ -232,8 +247,18 @@ def cmd_write(args: argparse.Namespace) -> int:
     _validate_source_payload(source, expected, args.source_digest)
     sources = expected["strings"]
     translated = _translation_blocks(Path(args.translations))
-    if len(translated) != len(sources) or any(not value for value in translated):
-        raise SystemExit("error: translation blocks must match every T-NNN item")
+    if len(translated) != len(sources):
+        raise SystemExit(
+            f"error: translation blocks must match every T-NNN item — "
+            f"{len(translated)} blocks in {Path(args.translations).name}, "
+            f"{len(sources)} items in the translation source"
+        )
+    empty = [f"T-{index + 1:03d}" for index, value in enumerate(translated) if not value]
+    if empty:
+        raise SystemExit(
+            "error: translation blocks must match every T-NNN item — empty: "
+            + ", ".join(empty[:10])
+        )
     lang = expected["lang"]
     sidecar = translation_sidecar_path(data_path, lang)
     if sidecar.is_symlink():

package/runtime/prompts/lead/convergence.md

@@ -89,7 +89,7 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
   - Same semantics but disjoint ticket sets → separate groups (do NOT over-merge across tickets).
   - Only one worker confirms a finding → one single-source group.
 4. When grouping is ambiguous, prefer splitting over merging (avoid over-merging). Semantic matching, ticket-set equality, and evidence interpretation remain lead judgments; the engine does not perform fuzzy matching or decide whether evidence is credible.
-5. Author the fixed grouping Markdown accepted by `okstra convergence prepare-groups --run-manifest <run-manifest> --input <grouping.md>`, then run that command. Python owns the artifact identifier, target path, schema version, task identity, run-manifest reference, and every participant reference. Each Markdown group records ticket IDs, origin worker and evidence, discovering workers, source worker item IDs, and optional captured evidence. An analysis sidetrack with no ticket uses an empty `Tickets:` value, never a placeholder. Use the ordered functional roster: finding workers have the `analysis` audience, the report author has `report-writer`, and the lead uses `lead`. A lead source never votes. Never infer live evidence or functional scope from wording, provider, model, or execution label.
+5. Author the fixed grouping Markdown accepted by `okstra convergence prepare-groups --run-manifest <run-manifest> --input <grouping.md>`, then run that command. Python owns the artifact identifier, target path, schema version, task identity, run-manifest reference, and every participant reference. Each Markdown group records ticket IDs, origin worker and evidence, discovering workers, source worker item IDs, and optional captured evidence. An analysis sidetrack with no ticket uses an empty `Tickets:` value, never a placeholder. Use the ordered functional roster: finding workers have the `analysis` audience, the report author has `report-writer`, and the lead uses `lead`. A lead source never votes. For `implementation` runs the convergence sources are the verifier-role results only — the executor's result is deliverable evidence, not a convergence source (**Enforced:** `_validate_worker_execution_identity` in `scripts/okstra_ctl/convergence_engine.py` rejects an `implementer` source with `analysis audience source role is not allowed`). Never infer live evidence or functional scope from wording, provider, model, or execution label.
 
    The command sets each worker's paired `participantRef` and `sourceRoleExecutionRef` from the run manifest's canonical role state. It sets `sourceRoleExecutionRef` to the selected source `RoleExecution` row's `roleExecutionRef`, not that row's `sourceRoleExecutionRef` field.
 6. Do not write a queue or classification in this grouped-input artifact. `okstra convergence seed` classifies Round 0 the same way in both modes: a group whose sources are **two or more distinct role executions** becomes `full-consensus` immediately, and only single-source groups enter the working queue. Independent co-derivation is already cross-verification — the adversarial burden of proof targets single-source claims, not a finding two roles reached on their own. A source is counted once per analysis worker, and one analysis worker is exactly one `sourceRoleExecutionRef` — the same identity the reverify roster uses for independence — so two roles held by one provider count as two and no role can count twice. **Enforced:** `_parse_workers` rejects a duplicate `workerId` and `_validate_worker_execution_identity` rejects a duplicate `sourceRoleExecutionRef`, both in `scripts/okstra_ctl/convergence_engine.py`. Semantic grouping merges provenance only; it does not decide a single-source finding is reliable. Section 6 never enters the grouped input.

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

@@ -146,7 +146,7 @@ Do NOT replace them with prose ("Now I'm starting Phase 2..."), do NOT skip a ch
 
 `okstra-run` surfaces these lines to the user directly; `okstra lead-progress append` persists them in the selected adapter's declared conformance evidence/event source for post-hoc retrieval.
 
-**Enforcement:** the Phase 7 validator (`validators/validate-run.py` → `validate_session_conformance.py`) reads the selected adapter's declared conformance evidence/event source within the run window and fails the run as `contract-violated` when a required checkpoint is missing — including the per-worker `phase-4-dispatch` / `phase-5-collect` lines (which must name each worker's role) and the `phase-batch-cleanup` lines that MUST precede the first `phase-5.5-convergence` round and the `phase-6-synthesis` report-writer dispatch. When the plan-body state file records two or more rounds, `_check_plan_verify_cleanup_checkpoints` additionally requires a `phase-5.5.9-plan-verify` line per round and a `phase-batch-cleanup` between consecutive rounds. For `implementation`, `_check_progress_checkpoints` additionally requires the `phase-5-stage` announcement once any worker is dispatched, and the `phase-5-stage-complete` line once an implementer worker completed. For activity-contract-v1 planning, `_check_activity_contract` validates the structured worker pairs, verification and self-fix counts, user-decision references, and `A-NNN` ordering. `phase-7-teardown` and `complete` fire after validation and are not checked.
+**Enforcement:** the Phase 7 validator (`validators/validate-run.py` → `validate_session_conformance.py`) reads the selected adapter's declared conformance evidence/event source within the run window and fails the run as `contract-violated` when a required checkpoint is missing — including the per-worker `phase-4-dispatch` / `phase-5-collect` lines (which must name each worker's role) and the `phase-batch-cleanup` lines that MUST precede the first `phase-5.5-convergence` round and the `phase-6-synthesis` report-writer dispatch. When the plan-body state file records two or more rounds, `_check_plan_verify_cleanup_checkpoints` additionally requires a `phase-5.5.9-plan-verify` line per round and a `phase-batch-cleanup` between consecutive rounds. For `implementation`, `_check_progress_checkpoints` additionally requires the `phase-5-stage` announcement once any worker is dispatched, and the `phase-5-stage-complete` line once an implementer worker completed **and** this stage's carry sidecar exists (`_stage_carry_persisted`) — a stage whose carry was withheld (`FAIL` / non-result) is not asked for the line. For activity-contract-v1 planning, `_check_activity_contract` validates the structured worker pairs, verification and self-fix counts, user-decision references, and `A-NNN` ordering. `phase-7-teardown` and `complete` fire after validation and are not checked.
 
 ## Asking the user (BLOCKING)
 

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

@@ -89,7 +89,7 @@ This section adds report-specific checks to [okstra-lead-contract](./okstra-lead
 4. When the check reports `mechanical: true` (every entry is a `replace` or `remove`), run `okstra agent-prompt apply-corrections` with the same arguments: okstra writes the corrected narrative to `reportNarrativePath` and records a `lead-correction-applied` activity row naming the ledger and its correction ids. No writer dispatch, `record-dispatch`, or `link-result` follows; the roster row's result already exists.
 5. Otherwise materialize the writer prompt with the same `--corrections <ledger>` under a new invocation id and prompt path (retire the first attempt's link with `reject-result` as [plan-body-verification](./plan-body-verification.md) describes). okstra renders `## Corrections` (each entry with its label path, current value, replacement or rule, schema constraint, and reason) and `## Output`; the instruction body carries only context.
 
-A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs, and four of six re-runs in the 2026-09-03 measurement were lead instructions that contradicted the authoring contract. Only a narrative whose structure does not parse (line grammar, an unknown top-level field) is re-authored, not corrected: that dispatch needs no ledger, and its body quotes the parser's message. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are exactly what the ledger fixes; the a3 attempt of the 2026-09-03 run carried twenty `SC-` ids that assembly refused and was still a corrective base.
+A report-writer materialization without `--corrections` whose narrative already exists and parses is refused before any prompt is written — free-form corrections cannot be checked before the writer runs, and four of six re-runs in the 2026-09-03 measurement were lead instructions that contradicted the authoring contract. Only a narrative whose structure does not parse (line grammar, an unknown top-level field) is re-authored, not corrected: that dispatch needs no ledger, and its body quotes the parser's message. A narrative that breaks the line grammar is not a produced artifact: the dispatcher settles that attempt as `required worker artifact is unusable: narrative does not parse: …` and retries it inside the same batch, so you see the parser's message at collection, not at Phase 7 assembly (**Enforced:** `okstra_ctl.dispatch_state.unusable_result_defect`, read by `missing_completion_paths` and the `team await` record path). The synthesis packet's Authoring Contract carries the line grammar itself (`report_narrative.NARRATIVE_GRAMMAR_INSTRUCTIONS`), so a writer that reads only the packet still sees it. Value defects — an id outside its pattern, a value outside its enum, a missing required field — leave the structure readable and are exactly what the ledger fixes; the a3 attempt of the 2026-09-03 run carried twenty `SC-` ids that assembly refused and was still a corrective base.
 
 **Enforced:** `_with_report_writer_sections` / `_refuse_free_form_correction` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`, `report_corrections.check_corrections`, `agent/prompt_cli/corrections.run_corrections_apply`; `tests/run/test_agent_prompt_corrections.py` and `tests/contract/test_report_writer_v3_contract.py` keep this procedure in the lead contract.
 

package/runtime/python/okstra_ctl/adapters/hosts/claude-code/relay.md

@@ -133,6 +133,8 @@ For `AskUserQuestion`, map each wizard option to the tool's `{label, description
 
 For a `host-text` mapping, render each numbered item as its option label followed by its description verbatim; preserve every item and its order. The next user message is the raw answer. Do not translate numbers, CSV members, labels, or values before `okstra wizard step`. A sequential group wraps each raw reply in one compact JSON object keyed by `questions[].step`; the wizard owns normalization.
 
+The `confirm` prompt's `label` is the selection summary (one line per resolved input, then the question). Pass it verbatim as the `AskUserQuestion` question text — every line, including `(none)` values — with its three options. Do not replace the summary with a table or a prose digest of your own: a line you drop is a setting the user never saw.
+
 
 ## Semantic operation mapping
 

package/runtime/python/okstra_ctl/adapters/hosts/codex/relay.md

@@ -115,6 +115,10 @@ For `request_user_input`, send one to three questions. Each question carries `id
 For a `host-text` mapping, render each numbered item as its option label followed by its description verbatim; preserve every item and its order. The next user message is the raw answer: do not translate a number such as `1`, a CSV reply such as `1, 3`, an option label, or an option value before `okstra wizard step`. For `sequential-group`, collect one raw reply per question in order and build one compact JSON object keyed by the corresponding `questions[].step`; the wizard owns all normalization.
 
 
+### Confirm step
+
+The `confirm` prompt's `label` is the selection summary (one line per resolved input, then the question). Send it verbatim as that question's text — every line, including `(none)` values — and offer its three options. Do not replace the summary with a table or a prose digest of your own; the user is confirming exactly what the wizard resolved, and a line you drop is a setting the user never saw.
+
 ### Runtime-generated selectable screens
 
 `wizard/engine.py` adapts choice screens before returning `next` when the session declares `native_single_select`. `wizard/picker_navigation.py` preserves all original choices while paging long lists, collecting multi-selection through toggle/complete choices, and disambiguating duplicate labels. Oversized or unsupported groups are presented one member at a time. These paths are exercised by `tests/domain/wizard/test_picker_navigation.py` and `test_role_model_selection.py`.

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -2420,9 +2420,15 @@ def _validate_worker_execution_identity(
             )
         allowed_roles = _AUDIENCE_SOURCE_ROLES[worker["audience"]]
         if source.role not in allowed_roles:
+            hint = ""
+            if source.role == "implementer":
+                hint = (
+                    " — the executor's result is deliverable evidence, not a "
+                    "convergence source; group the verifier results instead"
+                )
             raise ConvergenceContractError(
                 f"{worker['audience']} audience source role is not allowed: "
-                f"{source.role}"
+                f"{source.role} (allowed: {', '.join(sorted(allowed_roles))}){hint}"
             )
     source_refs = [worker["sourceRoleExecutionRef"] for worker in workers]
     if len(source_refs) != len(set(source_refs)):

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -31,6 +31,8 @@ from .dispatch_state import (
     load_json_object as _load_json_object,
     link_agent_dispatch_result as _link_agent_dispatch_result,
     missing_completion_paths as _missing_completion_paths,
+    unusable_result_defect,
+    _dispatch_worker_key,
     _plan_verify_result_aliases,
     mutate_team_state as _mutate_team_state,
     require_string as _require_string,
@@ -276,6 +278,9 @@ class WorkerOutcome:
     timeout: bool
     terminal_stage: str
     degraded_from: str
+    # 파일은 있는데 읽을 수 없는 산출물의 사유 — `missing_completion_paths` 에
+    # 그 경로가 함께 들어가고, 실패 사유는 이 문장을 인용한다.
+    artifact_defects: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -631,7 +636,17 @@ def _dispatch_cli_wrapper_batch(
             contract is not None and contract[1].mutation_audit == "batch"
             for contract in contracts
         )
-        if needs_batch and baseline_snapshot is None:
+        # 재시도 라운드는 baseline 을 다시 찍는다. 쓰기 계약은 attempt 소유라
+        # (`_persisted_write_contract`) attempt 2 의 정책 digest 는 attempt 1 과
+        # 다른데, 첫 라운드의 baseline 을 그대로 쓰면 마감의
+        # `_validate_snapshot_authority` 가 `policyDigests` 불일치로 죽고 attempt-N
+        # 사이드카는 끝내 안 써진다(실측 2026-09-08, translator attempt 2:
+        # 산출물 완전·exit 0 인데 dispatcher 예외). 앞 라운드에서 완주한 동료의
+        # 변경은 그 attempt 의 감사가 이미 판정했으므로 새 baseline 에 흡수돼도
+        # 맞다 — 재시도는 `failed-no-mutation` 뒤에만 오므로(`retry_allowed`)
+        # 미해결 변경이 baseline 으로 세탁되지는 않는다.
+        retry_round = any(attempt > 1 for _job, attempt in prepared)
+        if needs_batch and (baseline_snapshot is None or retry_round):
             baseline_snapshot = _mutation_snapshot(
                 plan, policies, tuple(job for job, _ in prepared)
             )
@@ -1943,9 +1958,15 @@ def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
         timeout=False,
         terminal_stage="exited",
         degraded_from=handle.degraded_from,
+        artifact_defects=_artifact_defects(handle.job),
     )
 
 
+def _artifact_defects(job: WorkerJob) -> tuple[str, ...]:
+    defect = unusable_result_defect(job.worker_id, job.result_path)
+    return (defect,) if defect else ()
+
+
 def _correct_teardown_marked_dispatches(plan: DispatchPlan) -> None:
     """Let the wrapper's own exit settle a record teardown wrote off.
 
@@ -3113,6 +3134,7 @@ def _outcome_from_status(record: Mapping[str, Any], status) -> WorkerOutcome:
         timeout=status.timeout,
         terminal_stage=status.stage,
         degraded_from=_string_value(record.get("degradedFrom")),
+        artifact_defects=_record_artifact_defects(record),
     )
 
 
@@ -3180,8 +3202,11 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
     result_path = Path(_string_value(record.get("resultPath")))
     worker_result = Path(_string_value(record.get("workerResultPath")))
     missing: list[Path] = []
+    worker_id = _dispatch_worker_key(record)
     for path in _record_completion_paths(record):
         if path.is_file():
+            if path == result_path and unusable_result_defect(worker_id, path):
+                missing.append(path)
             continue
         if path in {result_path, worker_result} and any(alias.is_file() for alias in aliases):
             continue
@@ -3189,6 +3214,13 @@ def _record_missing_completion_paths(record: Mapping[str, Any]) -> tuple[Path, .
     return tuple(missing)
 
 
+def _record_artifact_defects(record: Mapping[str, Any]) -> tuple[str, ...]:
+    defect = unusable_result_defect(
+        _dispatch_worker_key(record), Path(_string_value(record.get("resultPath")))
+    )
+    return (defect,) if defect else ()
+
+
 def _should_retry(outcome: WorkerOutcome, attempt: int) -> bool:
     """결과가 없으면 재시도한다 — 기준은 종료 코드가 아니라 산출물이다.
 
@@ -3235,6 +3267,8 @@ def _failure_reason(outcome: WorkerOutcome) -> str:
         return "CLI ended cleanly without emitting a result event"
     if outcome.returncode != 0:
         return f"wrapper exited with code {outcome.returncode}"
+    if outcome.artifact_defects:
+        return "required worker artifact is unusable: " + "; ".join(outcome.artifact_defects)
     if outcome.missing_completion_paths:
         missing = ", ".join(str(path) for path in outcome.missing_completion_paths)
         return f"required worker artifact was not produced: {missing}"

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -53,6 +53,7 @@ from .execution_manifest import (
 from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
 from .final_report_paths import final_report_data_path
 from .report_inputs import report_narrative_path, uses_report_contract_v3
+from .report_narrative import narrative_structure_defect
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_prompt_contract import (
     PromptRecord,
@@ -1636,10 +1637,33 @@ def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
     return BACKEND_MIXED
 
 
+def unusable_result_defect(worker_id: str, result_path: Path) -> str | None:
+    """산출물이 있어도 소비자가 읽을 수 없으면 없는 것이다 — 지금은 서사 한 종류.
+
+    report-writer 의 서사가 줄 문법을 어기면(frontmatter·헤딩으로 된 보통
+    보고서) 조립이 Phase 7 에서 거절하고, 그때는 배치의 재시도가 이미 지나
+    리드가 손으로 재저작을 띄워야 한다 — 실측(2026-09-09, jobs implementation
+    stage-2)에서 리드는 그것을 하지 않고 run 을 닫았다. 수집 시점에 "없는
+    산출물" 로 세면 `_should_retry` 가 같은 배치 안에서 다시 띄운다.
+    """
+    if worker_id != REPORT_WRITER_WORKER_ID or not result_path.is_file():
+        return None
+    try:
+        text = result_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as exc:
+        return f"narrative is unreadable: {exc}"
+    defect = narrative_structure_defect(text)
+    if defect is None:
+        return None
+    return f"narrative does not parse: {defect}"
+
+
 def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
     missing: list[Path] = []
     for path in job.completion_paths:
         if path.is_file():
+            if path == job.result_path and unusable_result_defect(job.worker_id, path):
+                missing.append(path)
             continue
         # reports seq 와 workerResults seq 가 갈라지면 워커는 다른 쪽
         # 파일명으로 쓴다. 둘 중 하나가 있으면 산출물은 있는 것이다.

package/runtime/python/okstra_ctl/execution_mutation_audit.py

@@ -281,12 +281,25 @@ def _validate_snapshot_authority(
     policies: tuple[WritePolicy, ...],
 ) -> None:
     expected = tuple(policy.digest for policy in policies)
-    if (
-        before.root != after.root
-        or before.artifact_root != after.artifact_root
-        or before.policy_digests != expected
-    ):
-        raise MutationAuditError("mutation snapshot does not match batch policies")
+    mismatches: list[str] = []
+    if before.root != after.root:
+        mismatches.append(f"root {before.root} != {after.root}")
+    if before.artifact_root != after.artifact_root:
+        mismatches.append(
+            f"artifactRoot {before.artifact_root} != {after.artifact_root}"
+        )
+    if before.policy_digests != expected:
+        mismatches.append(
+            "policyDigests snapshot=" + ",".join(before.policy_digests)
+            + " policies=" + ",".join(expected)
+        )
+    if mismatches:
+        # 어느 비교가 어긋났는지 없는 예외는 원인 특정이 불가능했다(실측
+        # 2026-09-08: 배치 안 재시도가 attempt 1 의 스냅샷을 attempt 2 의 계약과
+        # 대조해 죽었는데, 메시지는 "does not match batch policies" 뿐이었다).
+        raise MutationAuditError(
+            "mutation snapshot does not match batch policies: " + "; ".join(mismatches)
+        )
 
 
 def _maximum_precision(policy: WritePolicy) -> str:

package/runtime/python/okstra_ctl/report_narrative.py

@@ -29,6 +29,39 @@ class NarrativeContractError(ValueError):
     """서사 입력이 보고서 작성자 소유권이나 Markdown 문법을 위반했다."""
 
 
+# 작성자에게 도달해야 하는 줄 문법 — 합성 패킷의 Authoring Contract 가 이것을
+# 그대로 싣는다. 문법이 preamble 템플릿에만 있던 동안 작성자는 read-scope
+# 규칙대로 패킷만 읽고 frontmatter + 헤딩으로 된 보통 보고서를 냈다(실측
+# 2026-09-09, jobs implementation stage-2: `# OKSTRA Report Narrative` 0회,
+# 조립 거부, 최종 리포트 미발행).
+NARRATIVE_GRAMMAR_INSTRUCTIONS: tuple[str, ...] = (
+    f"Narrative line grammar: the file starts with the line `{TITLE}` and then "
+    "contains only three line shapes — `- **Humanised Field Name**` (one field; "
+    "nest a child by indenting two more spaces), `- Item <N>` (one array entry, "
+    "numbered 1..N without gaps), and `> value` (one scalar; repeat the line for a "
+    "multi-line value; `> _none_` for null, an empty object, or an empty array). "
+    "Blank lines are ignored.",
+    "Every other line is rejected — YAML frontmatter (`---` blocks), Markdown "
+    "headings (`#`, `##`, `###`), pipe tables at column 0, code fences, bare "
+    "paragraphs, JSON. Put such text inside a `> ` value instead. Report assembly "
+    "refuses the file otherwise and the run publishes no report.",
+)
+
+
+def narrative_structure_defect(markdown: str) -> str | None:
+    """줄 문법 위반 메시지, 없으면 None — 수집 시점의 산출물 검사용.
+
+    값 결함(enum 밖 값 등)은 보지 않는다; 그것은 교정 원장이 고친다. 구조가
+    깨진 파일은 원장이 해소될 자료가 없어 재저작 대상이고, 그것을 산출물이
+    있는 것으로 세면 결함이 Phase 7 조립까지 숨어 있다 재저작 없이 run 이 닫힌다.
+    """
+    try:
+        _parse_tree(markdown)
+    except NarrativeContractError as exc:
+        return str(exc)
+    return None
+
+
 class _Node:
     def __init__(self, kind: str, label: str, level: int) -> None:
         self.kind = kind

package/runtime/python/okstra_ctl/report_synthesis_packet.py

@@ -30,6 +30,7 @@ from .final_report_schema import task_block_rules, verdict_token_rule
 from .report_contract import TASK_TYPE_DATA_PROPERTY
 from .report_markdown import humanise
 from .report_narrative import NarrativeContractError, allowed_top_level_fields
+from .report_narrative import NARRATIVE_GRAMMAR_INSTRUCTIONS
 
 
 @dataclass(frozen=True)
@@ -250,6 +251,7 @@ class ReportSynthesisPacket:
                 "format": "report-narrative-v3.0",
                 "sourcePolicy": "read-only-synthesis-packet",
                 "instructions": [
+                    *NARRATIVE_GRAMMAR_INSTRUCTIONS,
                     "Write the complete human-readable report narrative.",
                     "Preserve settled source values, identities, dissent, and user responses.",
                     "Do not invent a value when a source is missing or contradictory.",
@@ -285,6 +287,7 @@ class ReportSynthesisPacket:
             f"- Task type: `{self.task_type}`",
             f"- Result path: `{self.result_path}`",
             "- Output format: `report-narrative-v3.0`",
+            *(f"- {text}" for text in NARRATIVE_GRAMMAR_INSTRUCTIONS),
             "- Input policy: read this synthesis packet as the dispatched source set",
             "- Responsibility: write the complete human-readable narrative while preserving settled values",
             "- Runtime-owned values: session identifiers, token usage, estimated cost, "

package/runtime/python/okstra_ctl/wizard/confirmation.py

@@ -96,10 +96,20 @@ def _worktree_preview_line_impl(state: WizardState) -> str:
 
 
 def _build_confirm(state: WizardState) -> Prompt:
+    """확인 질문의 본문이 곧 선택 요약이다.
+
+    요약을 `okstra wizard confirmation` 의 별도 텍스트로만 두면 리드가 그것을
+    자기 표로 다시 쓰면서 줄을 빠뜨린다(실측 2026-09-08, jobs implementation:
+    리드가 "추가 지시·관련 작업·추가 응답 문서는 모두 없음" 한 줄로 뭉개고
+    directive·base-ref·brief 줄을 뺀 표를 냈다). 네이티브 질문 카드는 질문
+    텍스트를 반드시 그리므로 요약을 질문 텍스트에 싣는다 — 리드가 빼놓을
+    자리가 없다. `okstra wizard confirmation` 은 텍스트 호스트와 재표시용으로
+    같은 블록을 낸다.
+    """
     t = _p(state.workspace_root, "confirm")
     return Prompt(
         step=S_CONFIRM, kind="pick",
-        label=t["label"],
+        label=f"{confirmation_block(state)}\n\n{t['label']}",
         options=[_opt(k, v) for k, v in t["options"].items()],
         echo_template=t["echo_template"],
     )
@@ -328,4 +338,6 @@ def confirmation_block(state: WizardState) -> str:
         lines.append(f"  handoff scope : {scope}")
     if state.task_type == "release-handoff" and state.pr_template_path:
         lines.append(f"  pr-template   : {state.pr_template_path} ({state.pr_template_scope or 'once'})")
+    if state.fix_cycle:
+        lines.append(f"  fix-cycle     : {state.fix_cycle}")
     return "\n".join(lines)

package/runtime/python/okstra_token_usage/collect.py

@@ -32,6 +32,7 @@ from .grok import (
     find_grok_sessions,
     grok_session_is_non_interactive,
     grok_session_total,
+    grok_session_window_total,
 )
 from .paths import claude_project_dir, find_session_jsonl, utc_now
 from .pricing import antigravity_cost_usd, provider_cost_usd
@@ -644,13 +645,15 @@ def _cli_session_totals(
     *,
     window: tuple[str, str] | None = None,
 ) -> list[dict]:
-    """세션별 합계. `window` 는 codex 리드 전용 — run 보다 먼저 열린 세션을 창으로 자른다."""
+    """세션별 합계. `window` 는 리드 전용 — run 보다 먼저 열린 세션을 창으로 자른다."""
     totals = []
     for session_path in session_paths:
         if provider == "codex" and window is not None:
             total = codex_session_window_total(session_path, *window)
         elif provider == "codex":
             total = codex_session_total(session_path)
+        elif provider == "grok" and window is not None:
+            total = grok_session_window_total(session_path, *window)
         elif provider == "antigravity":
             total = (
                 antigravity_status_total(session_path)
@@ -1100,17 +1103,17 @@ def _cli_lead_usage(
         if isinstance(worker, dict)
         for path in ((worker.get("usage") or {}).get("cliSessionPaths") or [])
     }
-    # in-session codex 리드는 run 보다 먼저 열린 세션이다 — 창 안에서 시작한
-    # 세션만 보면 없다고 나오고, 세션 전체를 더하면 다른 task 의 턴이 섞인다.
-    # 창 안에서 활동한 세션을 후보에 넣고 토큰은 창으로 잘라 센다.
-    window = (run_since, run_until) if provider == "codex" else None
+    # in-session 리드(codex·grok)는 run 보다 먼저 열린 세션이다 — 창 안에서
+    # 시작한 세션만 보면 없다고 나오고, 세션 전체를 더하면 다른 task 의 턴이
+    # 섞인다. 창 안에서 활동한 세션을 후보에 넣고 토큰은 창으로 잘라 센다.
+    window = (run_since, run_until)
     if provider == "codex":
         candidates = find_codex_sessions(
             project_root, run_since, run_until, active_before_start=True,
         )
     else:
-        candidates = _cli_sessions_for_windows(
-            provider, project_root, [(run_since, run_until)],
+        candidates = find_grok_sessions(
+            project_root, run_since, run_until, active_before_start=True,
         )
     sessions = _select_cli_lead_sessions(
         provider,

package/runtime/python/okstra_token_usage/grok.py

@@ -1,8 +1,12 @@
 """Grok Build session collectors.
 
 공식 세션 문서는 대화를 ``~/.grok/sessions/`` 에 둔다. cwd 는 퍼센트 인코딩된
-디렉터리 이름이다. 누적 사용량은 ``updates.jsonl`` 의
-``params.update.usage.modelUsage`` 마지막 스냅샷이다.
+디렉터리 이름이다. ``updates.jsonl`` 의 ``params.update.usage`` 행 하나는
+**프롬프트 한 번**의 사용량이다 — ``numTurns`` 는 그 프롬프트 안의 모델 호출
+수이고 ``inputTokens`` 는 매번 컨텍스트 전체라 값이 오르내린다(실측
+2026-09-08, 대화형 세션 3개 39행: 83k → 798k → 406k → 187k …). 세션 합계는
+행의 합이고, 마지막 행은 마지막 프롬프트일 뿐이다. exec 래퍼 워커는 프롬프트가
+하나라 행도 하나다.
 """
 from __future__ import annotations
 
@@ -53,39 +57,55 @@ def _model_snapshot(usage: dict) -> tuple[dict, str | None]:
     return usage, None
 
 
-def grok_session_total(updates_path: Path) -> dict:
-    """마지막 modelUsage 스냅샷. 세션 누적이라 더하지 않는다."""
-    last: dict | None = None
+_SUM_KEYS = (
+    ("totalTokens", "totalTokens"),
+    ("inputTokens", "inputTokens"),
+    ("outputTokens", "outputTokens"),
+    ("cachedInputTokens", "cachedReadTokens"),
+    ("reasoningOutputTokens", "reasoningTokens"),
+    ("durationMs", "apiDurationMs"),
+)
+
+
+def grok_session_window_total(
+    updates_path: Path, since: str | None = None, until: str | None = None,
+) -> dict:
+    """창 안 usage 행의 합. 창이 없으면 세션 전체.
+
+    한 행이 프롬프트 한 번의 사용량이므로 더한다 — 마지막 행만 읽으면 여러
+    프롬프트를 돌린 세션(in-session 리드)은 마지막 프롬프트만 남는다. 창은
+    run 보다 먼저 열린 리드 세션에서 다른 task 의 프롬프트를 걸러 낸다.
+    """
+    sums = {name: 0 for name, _raw in _SUM_KEYS}
     model: str | None = None
     started: str | None = None
     ended: str | None = None
+    counted = 0
     for record in iter_jsonl(updates_path):
         usage = _usage_payload(record)
         if usage is None:
             continue
         iso = _iso_from_unix(record.get("timestamp"))
+        if iso and not ts_in_window(iso, since, until):
+            continue
+        snapshot, snapshot_model = _model_snapshot(usage)
+        for name, raw in _SUM_KEYS:
+            sums[name] += snapshot.get(raw, 0) or 0
+        if snapshot_model:
+            model = snapshot_model
         if iso and started is None:
             started = iso
         if iso:
             ended = iso
-        snapshot, snapshot_model = _model_snapshot(usage)
-        last = snapshot
-        if snapshot_model:
-            model = snapshot_model
-    if last is None:
+        counted += 1
+    if not counted:
         return {"totalTokens": 0, "available": False}
-    return {
-        "totalTokens": last.get("totalTokens", 0) or 0,
-        "inputTokens": last.get("inputTokens", 0) or 0,
-        "outputTokens": last.get("outputTokens", 0) or 0,
-        "cachedInputTokens": last.get("cachedReadTokens", 0) or 0,
-        "reasoningOutputTokens": last.get("reasoningTokens", 0) or 0,
-        "durationMs": last.get("apiDurationMs", 0) or 0,
-        "model": model,
-        "startedAt": started,
-        "endedAt": ended,
-        "available": True,
-    }
+    return {**sums, "model": model, "startedAt": started, "endedAt": ended, "available": True}
+
+
+def grok_session_total(updates_path: Path) -> dict:
+    """세션 전체 — 모든 usage 행의 합."""
+    return grok_session_window_total(updates_path)
 
 
 def _session_started_in_window(
@@ -102,14 +122,38 @@ def _session_started_in_window(
     return False
 
 
+def _session_active_in_window(
+    updates_path: Path, started_at: str, ended_at: str,
+) -> bool:
+    """창보다 먼저 열렸지만 창 안에도 usage 행이 있는 세션 — in-session 리드."""
+    first: str | None = None
+    for record in iter_jsonl(updates_path):
+        iso = _iso_from_unix(record.get("timestamp"))
+        if not iso:
+            continue
+        if first is None:
+            first = iso
+            if not ts_in_window(first, None, started_at):
+                return False
+        if ts_in_window(iso, started_at, ended_at):
+            return True
+    return False
+
+
 def find_grok_sessions(
     cwd: Path,
     started_at: str,
     ended_at: str,
     *,
     session_root: Path | None = None,
+    active_before_start: bool = False,
 ) -> list[Path]:
-    """cwd 로 인코딩된 세션 중 창 안에서 시작된 updates.jsonl."""
+    """cwd 로 인코딩된 세션 중 창 안에서 시작된 updates.jsonl.
+
+    `active_before_start=True` 는 창보다 먼저 시작했지만 창 안에서도 프롬프트를
+    돌린 세션을 더한다 — in-session 리드의 모양이고, 토큰은
+    `grok_session_window_total` 이 창으로 잘라 센다.
+    """
     if not started_at or not ended_at:
         return []
     root = session_root or grok_sessions_root()
@@ -125,8 +169,11 @@ def find_grok_sessions(
             continue
         for session in child.iterdir():
             updates = session / "updates.jsonl"
-            if updates.is_file() and _session_started_in_window(
-                updates, started_at, ended_at
+            if not updates.is_file():
+                continue
+            if _session_started_in_window(updates, started_at, ended_at) or (
+                active_before_start
+                and _session_active_in_window(updates, started_at, ended_at)
             ):
                 matches.append(updates)
     return sorted(matches)

package/runtime/skills/okstra-run/SKILL.md

@@ -215,15 +215,11 @@ When the selected task type is `project-analysis`, `feature-analysis`, or `chang
 
 Do not second-guess the wizard. If the next prompt seems out of place, the bug is in `okstra_ctl.wizard`, not in your interpretation of the user's input.
 
-## Step 4: Show the confirmation block before the final Proceed
+## Step 4: The confirm step's question text is the selection summary
 
-When `next.step == "confirm"`, before relaying the picker, fetch the human-readable selection summary:
+When `next.step == "confirm"`, the prompt's `label` already carries the full selection summary (`선택 확인:` followed by one line per resolved input — task-type, task-key, brief, base-ref, worktree, every role slot, directive, related-tasks, clarification, stage, …) and ends with the question. Render that `label` **verbatim, every line, as the question text** of the `confirm` picker (Proceed / Edit / Abort) — the same way you render any other pick step's label. Do not re-author it as a table, do not summarise it into prose, do not drop a line because its value is `(none)`: the user confirms what is on screen, and a line you left out is a setting they never saw (observed: a lead's own table omitted `directive`, `base-ref` and `brief`). Render the picker **as the final output of that turn** — emit nothing after the picker call.
 
-```bash
-okstra wizard confirmation --state-file /var/folders/.../okstra-wizard.AbCd.json
-```
-
-Output: `{ok: true, text: "Selection summary:\n  task-type     : ...\n  ..."}`. Print `text` to the user, then render the `confirm` picker (Proceed / Edit) **as the final output of that turn** — emit nothing after the picker call.
+`okstra wizard confirmation --state-file <path>` returns the same block as `{ok: true, text: ...}` for a text-only host or when the user asks to see the summary again; it is not a substitute for the label.
 
 ## Step 5: Render the task bundle
 

package/runtime/validators/validate-run.py

@@ -569,7 +569,12 @@ def _validate_agent_dispatch_contract(
         dispatch_id = str(link.get("dispatchId") or "").strip()
         result_path = str(link.get("resultPath") or "").strip()
         if dispatch_id not in ids or not result_path:
-            failures.append("agent result link has no matching dispatch record")
+            # 같은 문장이 링크 수만큼 반복되면 어느 링크인지 알 수 없다 — 대상을 이름한다.
+            failures.append(
+                "agent result link has no matching dispatch record: "
+                f"dispatchId={dispatch_id or '<empty>'} "
+                f"resultPath={Path(result_path).name if result_path else '<empty>'}"
+            )
             continue
         if uses_v2_identity:
             dispatch = ids[dispatch_id]

package/runtime/validators/validate_session_conformance.py

@@ -35,6 +35,7 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
     if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
         sys.path.insert(0, str(_ssot_dir))
 
+from okstra_ctl.paths import RunRef  # noqa: E402
 from okstra_ctl.worker_heartbeat import (  # noqa: E402
     HEARTBEAT_LINE_RE,
     IN_STAGE_PREFIX,
@@ -1521,6 +1522,42 @@ def _check_plan_verify_cleanup_checkpoints(
             )
 
 
+_STAGE_ANNOUNCE_RE = re.compile(r"\bstage=(\d+)\b")
+
+
+def _announced_stage(by_phase: Mapping[str, list[tuple[str, str]]]) -> int | None:
+    for _ts, line in by_phase.get("phase-5-stage", []):
+        matched = _STAGE_ANNOUNCE_RE.search(line)
+        if matched:
+            return int(matched.group(1))
+    return None
+
+
+def _stage_carry_persisted(
+    run_dir: Path, by_phase: Mapping[str, list[tuple[str, str]]]
+) -> bool:
+    """이 stage 의 carry 사이드카가 디스크에 있는가 — 완료 라인의 전제.
+
+    `phase-5-stage-complete` 는 executor 의 `### Stage Carry Evidence` 를 파싱한
+    뒤에만 낼 수 있고, 계약은 executor 가 carry 증거 없이 끝나면(FAIL 또는
+    non-result) 그 라인을 생략하라고 한다. 그런데 검사는 명부의 `completed`
+    만 봐서, 계약대로 생략한 리드가 권고를 받았다(실측 2026-09-08,
+    fontsninja-v3-site dev-10627-2 implementation stage-1: executor 가 상위
+    게이트 부재로 carry 를 의도적으로 보류). FAIL 이면 사이드카를 쓰지 않는다는
+    같은 계약을 `validate-run.py` `_validate_stage_carry_sidecar_exists` 가
+    집행하므로, 그 파일의 존재를 완료 라인의 조건으로 쓴다. stage 번호는 run
+    디렉터리(`stage-<N>`)에서, 없으면 `phase-5-stage stage=<N>` 공지에서 읽는다.
+    """
+    try:
+        ref = RunRef.from_run_dir(run_dir)
+    except ValueError:
+        return True
+    stage = ref.stage if ref.stage is not None else _announced_stage(by_phase)
+    if stage is None:
+        return any(ref.carry_dir.glob("stage-*.json"))
+    return ref.carry(stage).exists()
+
+
 def _check_progress_checkpoints(
     evidence: _LeadEvidence,
     team_state: dict,
@@ -1605,7 +1642,7 @@ def _check_progress_checkpoints(
         )
         require(
             "phase-5-stage-complete",
-            implementer_completed,
+            implementer_completed and _stage_carry_persisted(run_dir, by_phase),
             "immediately after parsing the Executor's `### Stage Carry Evidence` "
             "block — `stage=<N> steps=<done>/<count>` from its stepResults",
         )