okstra 0.148.1 → 0.150.0

package/docs/architecture.md

@@ -304,7 +304,7 @@ The standard `okstra` workflow applies the following team contract consistently
 - Model defaults are provider and functional-role policy. Fallbacks include Claude lead/analyser=`opus`, Codex lead/analyser=`gpt-5.6-sol`, Claude report writer=`sonnet`, Antigravity=`gemini-3.1-pro`, Grok analyser=`grok-build-0.1`, and Kimi analyser=`kimi-k2.7-code`.
 - Before the final judgment, each required role in the current run's worker roster must have either a result or an explicit terminal status (`completed`, `timeout`, `error`, `not-run`).
 - Every attempted worker (`completed`, `timeout`, `error`) must have an assigned worker prompt history file under the current run's `prompts/` directory.
-- Worker timing begins at the atomic transition to `in-progress`, which records `workers[].startedAt` in `team-state.json`; prompt creation time is not a dispatch proxy. `okstra worker-state transition` and both dispatch adapters share `dispatch_state.transition_worker_status`, while `okstra worker-liveness --team-state ... --worker ...` reads that timestamp as the launch-grace authority.
+- Worker timing begins at the atomic transition to `in-progress`, which records `workers[].startedAt` in `team-state.json`; prompt creation time is not a dispatch proxy. `okstra worker-state transition` and both dispatch adapters share `dispatch_state.transition_worker_status`, while `okstra worker-liveness --team-state ... --worker ...` reads that timestamp as the launch-grace authority for both probe kinds — the in-process audit sidecar is reused on re-dispatch, so only `startedAt` separates the previous attempt's last heartbeat from this dispatch's silence.
 - An unnamed generic parallel worker is not accepted as a substitute for a required role.
 
 ### Cross-task worker prompt policy and final-verification boundaries

package/docs/cli.md

@@ -729,7 +729,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra rollup [--task-group <group>] [--project-root <dir>] [--cwd <dir>]` | Read-only backend for the okstra-rollup skill. For every catalog task, or one task group, it emits JSON with per-task run counts, raw duration in ms, error counts, latest report paths, group totals, and status/category/phase distributions. Omitting `--task-group` targets the whole project catalog. The caller skill formats raw ms as HH:MM:SS and synthesizes report prose. Use the `okstra inspect` family for a single-task drill-down |
 | `okstra usage-report [--days <positive-int>] [--project-root <dir>] [--cwd <dir>] [--json]` | Read-only backend for the okstra-usage skill. Defaults to the whole current project's last 30 days and emits task-type run coverage, raw/billable tokens, known USD cost, CPU-sum milliseconds, wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |
 | `okstra worker-state transition --team-state <path> --worker <id> --status <in-progress\|completed\|timeout\|error\|not-run> [--reason <text>] [--model <execution-value>]` | Atomically update one persisted worker row. `in-progress` records the authoritative `startedAt` and clears `endedAt`; terminal states record `endedAt`; `timeout`, `error`, and `not-run` require a reason. Dispatch adapters use this same transition path, so CLI-backed and in-process orchestration share the status timestamp contract |
-| `okstra worker-liveness [--audit <path>]… [--team-state <path> --worker <id>]… [--max-idle <seconds>] [--launch-grace <seconds>] [--json]` | Judge whether pending workers are still alive so the lead's poll ends a stalled wait early instead of paying the full deadline. Both selectors repeat and may be mixed in one call. `--audit` takes an in-process worker audit sidecar and reports `stalled` when its `- PROGRESS:` heartbeat is past the idle budget. Each `--team-state` must have a paired `--worker`; that selector resolves the worker's prompt and starts launch grace from its persisted `startedAt`, then reports `did-not-launch` when neither the wrapper `.log` nor `.status.json` appears. Healthy probes report `live`. It only judges—it never kills or re-dispatches. Exit 1 on an unhealthy verdict, so a poll loop can branch without parsing JSON. The heartbeat line shape and budget come from the `okstra_ctl.worker_heartbeat` SSOT shared with the Phase 7 audit (`validators/validate_session_conformance.py`) |
+| `okstra worker-liveness [--team-state <path> --worker <id>]… [--max-idle <seconds>] [--launch-grace <seconds>] [--json]` | Judge whether pending workers are still alive so the lead's poll ends a stalled wait early instead of paying the full deadline. The selector repeats; each `--team-state` must have a paired `--worker`. The worker row's `livenessMode` picks the probe: `audit-heartbeat` reads its `auditSidecarPath` and reports `stalled` when the `- PROGRESS:` heartbeat is past the idle budget; `wrapper-status` reads its `promptPath` and reports `did-not-launch` when neither the wrapper `.log` nor `.status.json` appears. Both graces start at the persisted `startedAt`, never at an artifact mtime — the audit sidecar is reused on re-dispatch, so a heartbeat older than this dispatch counts as no signal yet rather than a stall. Healthy probes report `live`. It only judges—it never kills or re-dispatches. Exit 1 on an unhealthy verdict, so a poll loop can branch without parsing JSON. The heartbeat line shape and budget come from the `okstra_ctl.worker_heartbeat` SSOT shared with the Phase 7 audit (`validators/validate_session_conformance.py`) |
 | `okstra log-report [--project-root <dir>] [--cwd <dir>] [--top <N>] [--json]` | Read-only inventory of wrapper transcript `.log` files and their sibling prompt `.md` files. Each ranked entry preserves `path` / `sizeBytes` for compatibility and also reports `transcriptPath`, `transcriptBytes`, `promptPath`, `promptBytes`, and `transcriptToPromptRatio`; totals distinguish prompt bytes from transcript bytes and count paired files. Ranking remains transcript-size descending |
 | `okstra recap <assemble\|record\|note> <task-root\|task-key> …` | Backend for the okstra-inspect `recap` facet. `assemble` is read-only and prints a JSON summary of phase transitions across a task's runs. `record --kind <summary\|qa> --mode <artifact\|code> --answer <text> [--question <text>] [--citation <path:line> …]` appends one line to `<task-root>/recap/recap-log.jsonl` and never mutates other artifacts. `note --kind <verification-evidence\|decision-draft\|analysis-note> --slug <topic> --purpose <text> --scope-note <text> (--body <markdown>\|--body-file <path>)` writes an agent-authored note to `<task-root>/notes/` and prints its path plus the `--clarification-response` argument for feeding it into a later run |
 | `okstra user-response <list\|show\|write> …` | Backend for the `/okstra-user-response` skill: answer a task's open clarification questions in-session and write the response sidecar. `list --home <dir> --project <id> [--limit <n>]` finds reports with open questions; `show --report <md>` reads one report's questions; `write --report <md> --answers <json> [--approval <json>] [--task-key <key>]` writes the sidecar. Each answer carries a `disposition` of `answer` or `reframe`; a `reframe` is carried into the next run as a re-scoped brief. JSON output; exit 0 ok / 1 error |

package/docs/project-structure-overview.md

@@ -267,7 +267,7 @@ Important modules:
 | `index.py`, `jsonl.py`, `reconcile.py`, `listing.py`, `batch.py`, `backfill.py` | `~/.okstra` run index and history operations |
 | `run_index_row.py` | single reference point for creating / slimming / hydrating a `~/.okstra` run-index row — runId SSOT, preserves projectId raw |
 | `error_report.py`, `error_log_core.py`, `error_zip.py` | backend for the okstra-inspect errors/error-zip facets — `error_log_core` is the read-only core that globs/parses/aggregates `errors-*.jsonl`, `error_report` renders the errors facet, and `error_zip` collects cross-project run directories, allowlist-anonymizes, aggregates clusters, and produces a zip |
-| `worker_heartbeat.py`, `worker_liveness.py` | `worker_heartbeat` is the single definition of the `- PROGRESS:` heartbeat line shape and its 5-minute (+60s grace) cadence budget, shared by the Phase 7 audit (`validators/validate_session_conformance.py`) and the live probe; `worker_liveness` backs `okstra worker-liveness`, reporting a pending worker as `stalled` (heartbeat past the budget) or `did-not-launch` (no wrapper `.log`/`.status.json` past the launch grace) |
+| `worker_heartbeat.py`, `worker_liveness.py` | `worker_heartbeat` is the single definition of the `- PROGRESS:` heartbeat line shape and its 5-minute (+60s grace) cadence budget, shared by the Phase 7 audit (`validators/validate_session_conformance.py`) and the live probe; `worker_liveness` backs `okstra worker-liveness`, resolving each pending worker from its team-state row (`livenessMode` picks the artifact, `startedAt` anchors the grace) and reporting `stalled` (heartbeat past the budget, or none yet for this dispatch past the grace) or `did-not-launch` (no wrapper `.log`/`.status.json` past the launch grace) |
 | `log_report.py`, `time_report.py` | read-side backend for the okstra-inspect logs/time facets (`okstra log-report` pairs each wrapper transcript `.log` with its sibling prompt `.md` and reports both byte counts without changing legacy transcript-size fields; `okstra time-report` is per-task time aggregation) |
 | `rollup.py` | read-side backend for the okstra-rollup skill — fans the catalog out per task-group (or the whole project) and deterministically aggregates each task's run count, elapsed time (raw ms), error count, and latest report path, plus group-level totals/status, category, and phase distribution. Reuses the `time_report`/`error_log_core` functions and delegates report-body synthesis to the skill |
 | `usage_report.py` | Read-only okstra-usage backend — scans the whole current project's recent run timelines, defaults to 30 days, and returns task-type coverage, raw/billable tokens, known USD cost, CPU-sum and wall-clock milliseconds, unavailable reason counts, and unmatched pricing models |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.148.1",
+  "version": "0.150.0",
   "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.148.1",
-  "builtAt": "2026-08-04T05:55:30.824Z",
+  "package": "0.150.0",
+  "builtAt": "2026-08-05T03:48:23.472Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/translator-worker.md

@@ -0,0 +1,67 @@
+---
+name: translator-worker
+description: |
+  Use this agent when okstra is in Phase 7 and the run's report language is not `en`. This agent translates the final-report's reader-facing strings into a sidecar the HTML renderer overlays. It is NOT an analysis worker — it produces no findings and never edits the report itself.
+
+  <example>
+  Context: okstra finished Phase 6 with `meta.reportLanguage: "ko"` and is entering Phase 7.
+  user: "okstra this task bundle"
+  assistant: "Phase 7 — dispatching translator-worker to write the ko translation sidecar."
+  <commentary>The okstra skill dispatches this agent before `okstra report-finalize` so `render-views` has a sidecar to overlay.</commentary>
+  </example>
+color: cyan
+model: inherit
+tools: ["Bash", "Read", "Write", "Glob", "Grep"]
+---
+
+**Write one file**: the translation sidecar at the assigned `Result Path`. That is the `Translator worker`'s sole responsibility. You are NOT an analysis worker — you produce no findings, you vote in nothing, and you never edit the final-report data.json, its Markdown sibling, or its HTML.
+
+The data.json is the English SSOT that every later phase and validator reads. Your sidecar is presentation: the HTML renderer overlays it onto an in-memory copy so only the human report speaks the reader's language.
+
+## Procedure
+
+1. Read your dispatch prompt's `**Report Language:**` header. It is already resolved to a concrete language — never `auto`.
+2. Build your work list:
+
+   ```bash
+   okstra report-translate extract <data.json path>
+   ```
+
+   It writes `<stem>.translation-source.json`, a map of JSON Pointer to the English text at it. Those pointers are the whole job — you never invent one, and every value the renderer reads as machinery (ids, paths, commands, enum tokens, CSS-class values, verbatim quotes) has already been withheld from you.
+3. Write the sidecar at `Result Path`, same shape, with each value translated:
+
+   ```json
+   {
+     "lang": "<language>",
+     "sourceData": "final-report-<task-type>-<seq>.data.json",
+     "strings": { "/humanSummary/headline": "…" }
+   }
+   ```
+
+4. Verify before you return:
+
+   ```bash
+   okstra report-translate check <Result Path>
+   ```
+
+   A non-zero exit means a pointer resolves nowhere — you altered or invented one. Fix it and re-run. Do not return on a failing check.
+
+## How to translate
+
+You are a translator who reads code. Judge every term on whether the translation or the original carries the meaning faster to a working developer in the target language, and pick that one. The goal is a reader who understands the report sooner, not a document with no English left in it.
+
+- **Never touch**: code identifiers, file paths, CLI commands and flags, model names, commit SHAs, URLs, and anything already inside backticks. Reproduce them character for character.
+- **Keep the English word** when that is what developers in the target language actually say. Forcing a native coinage onto `commit`, `worktree`, `merge`, `lint`, `diff`, `stage`, `rollback` or `PR` makes the sentence *slower* to read, not more local.
+- **Translate the explanation.** Connective prose — why something matters, what a reader should do, what a finding means — is where the translation earns its place. Carry the meaning, not the word order.
+- **Do not translate literally.** A word-for-word rendering that is technically correct and unreadable has failed. Say what the sentence means the way a developer would say it.
+- **Gloss on first use, once.** When a technical term does need translating, write it as `<translation>(<English>)` the first time it appears in the document, then use the translation alone. Never gloss the same term twice.
+- **One claim per sentence.** Where the English stacks four clauses behind em-dashes, split it. The reader gains nothing from the original's punctuation.
+- **Match the register.** A verdict line is terse; a rationale paragraph is explanatory. Do not inflate a three-word cell into a sentence, or compress a paragraph into a fragment.
+- **Leave it out when you cannot do it justice.** An omitted pointer renders in English, which is a correct fallback. A confident mistranslation is not.
+
+## What you never do
+
+- Never edit the data.json, the Markdown sibling, or the HTML. Your only output is the sidecar.
+- Never add, remove, or re-order pointers relative to the extract output.
+- Never translate a value the extract step did not offer you. Their absence is deliberate — the renderer reads them as machinery, and a translated one breaks the page silently.
+- Never return the sidecar contents inline. The file on disk is the artifact.

package/runtime/bin/okstra-render-final-report.py

@@ -26,7 +26,6 @@ _HERE = Path(__file__).resolve().parent
 # scripts; for in-repo invocation we add ``scripts/`` explicitly.
 sys.path.insert(0, str(_HERE))
 
-from okstra_ctl.i18n import SUPPORTED_LANGS  # noqa: E402
 from okstra_ctl.final_report_paths import final_report_markdown_path  # noqa: E402
 from okstra_ctl.render_final_report import (  # noqa: E402
     FinalReportRenderError,
@@ -62,15 +61,6 @@ def main(argv: list[str]) -> int:
             "repo-local report template."
         ),
     )
-    parser.add_argument(
-        "--report-language",
-        choices=list(SUPPORTED_LANGS),
-        default=None,
-        help=(
-            "Override the language passed into the renderer. When omitted, "
-            "the renderer reads data.json.meta.reportLanguage (fallback 'en')."
-        ),
-    )
     args = parser.parse_args(argv)
 
     output = args.output or final_report_markdown_path(args.data)
@@ -80,7 +70,6 @@ def main(argv: list[str]) -> int:
             args.data,
             output,
             template_path=args.template,
-            report_language=args.report_language,
         )
     except FinalReportRenderError as exc:
         print(f"error: {exc}", file=sys.stderr)

package/runtime/bin/okstra-render-report-views.py

@@ -138,9 +138,29 @@ def _v2_run_meta(data: dict, markdown_path: Path, args: argparse.Namespace):
         task_type,
         seq,
         args.source_report or markdown_path.name,
+        _elapsed_ms(markdown_path, task_type, seq),
     )
 
 
+def _elapsed_ms(markdown_path, task_type: str, seq: str) -> int | None:
+    """Wall-clock milliseconds for this run, or None when it cannot be measured.
+
+    The measurement lives in the run's team-state, not in the report data, so
+    the CLI resolves it here rather than teaching the renderer about run
+    layout. A missing or timestamp-less state yields None — the header then
+    omits the field instead of printing a zero.
+    """
+    from okstra_ctl.report_view_artifacts import team_state_path_for_report
+    from okstra_ctl.time_report import wall_clock_ms
+
+    state_path = team_state_path_for_report(markdown_path, task_type, seq)
+    try:
+        state = json.loads(state_path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return wall_clock_ms(state) or None if isinstance(state, dict) else None
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
         description="Render the self-contained HTML view of an okstra final-report."

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

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""CLI entrypoint for the Phase 7 translation sidecar.
+
+Usage:
+  okstra-report-translate.py extract <path-to-final-report.data.json>
+  okstra-report-translate.py check <path-to-sidecar.i18n.<lang>.json>
+
+``extract`` writes the translator's work list — every pointer the report holds
+a translatable string at, paired with the English text. The translator fills
+in the values rather than authoring pointers, so a sidecar cannot cite a path
+the document does not have.
+
+``check`` is the translator's own gate before it returns: it resolves every
+pointer in the sidecar against the report and reports what is still English.
+Without it a bad sidecar surfaces at render time, after the worker is gone.
+
+This script is the canonical single-reference-point. The Node CLI
+(``bin/okstra report-translate``) is a thin wrapper that spawns it.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[1]
+SCRIPTS_DIR = REPO_ROOT / "scripts"
+HOME_LIB = (
+    Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra")))
+    / "lib"
+    / "python"
+)
+
+# Prefer dev sources when present, fall back to install — a stale install
+# without this module would otherwise shadow the in-repo copy.
+if (SCRIPTS_DIR / "okstra_ctl" / "report_translation.py").is_file():
+    if str(SCRIPTS_DIR) in sys.path:
+        sys.path.remove(str(SCRIPTS_DIR))
+    sys.path.insert(0, str(SCRIPTS_DIR))
+    if HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
+        sys.path.append(str(HOME_LIB))
+elif HOME_LIB.is_dir() and str(HOME_LIB) not in sys.path:
+    sys.path.insert(0, str(HOME_LIB))
+
+from okstra_ctl.report_translation import extract, overlay  # noqa: E402
+from okstra_ctl.final_report_paths import (  # noqa: E402
+    translation_sidecar_path,
+    translation_source_path,
+)
+
+
+def _load(path: Path) -> dict:
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise SystemExit(f"error: cannot read {path}: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"error: {path} is not valid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise SystemExit(f"error: {path} must hold a JSON object")
+    return payload
+
+
+def cmd_extract(args: argparse.Namespace) -> int:
+    data_path = Path(args.data).resolve()
+    data = _load(data_path)
+    strings = extract(data)
+    out_path = translation_source_path(data_path)
+    lang = str((data.get("meta") or {}).get("reportLanguage") or "")
+    out_path.write_text(
+        json.dumps(
+            {
+                "lang": lang,
+                "sourceData": data_path.name,
+                "strings": strings,
+            },
+            ensure_ascii=False,
+            indent=2,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "sourcePath": str(out_path),
+                "sidecarPath": str(translation_sidecar_path(data_path, lang)) if lang else "",
+                "lang": lang,
+                "stringCount": len(strings),
+                "charCount": sum(len(v) for v in strings.values()),
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 0
+
+
+def cmd_check(args: argparse.Namespace) -> int:
+    sidecar_file = Path(args.sidecar).resolve()
+    sidecar = _load(sidecar_file)
+    strings = sidecar.get("strings")
+    if not isinstance(strings, dict):
+        raise SystemExit(f"error: {sidecar_file} has no 'strings' object")
+    source_name = str(sidecar.get("sourceData") or "")
+    if not source_name:
+        raise SystemExit(f"error: {sidecar_file} does not name its sourceData")
+    data_path = sidecar_file.parent / source_name
+    if not data_path.is_file():
+        raise SystemExit(f"error: sourceData not found beside the sidecar: {data_path}")
+
+    _, report = overlay(_load(data_path), strings)
+    offered = report.applied + len(report.untranslated)
+    payload = {
+        "ok": not report.unresolved,
+        "applied": report.applied,
+        "offered": offered,
+        "untranslated": list(report.untranslated),
+        "unresolved": list(report.unresolved),
+    }
+    print(json.dumps(payload, ensure_ascii=False))
+    if report.unresolved:
+        # A pointer that resolves nowhere means the sidecar was written against
+        # a different report. Rendering it would silently drop those strings.
+        sys.stderr.write(
+            f"error: {len(report.unresolved)} pointer(s) do not resolve in "
+            f"{data_path.name}\n"
+        )
+        return 1
+    return 0
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra-report-translate.py",
+        description="Build and verify the final-report translation sidecar.",
+    )
+    sub = parser.add_subparsers(dest="op", required=True)
+
+    extract_cmd = sub.add_parser("extract", help="write the translator's work list")
+    extract_cmd.add_argument("data", help="path to final-report-<type>-<seq>.data.json")
+    extract_cmd.set_defaults(func=cmd_extract)
+
+    check_cmd = sub.add_parser("check", help="verify a filled sidecar against its report")
+    check_cmd.add_argument("sidecar", help="path to final-report-<type>-<seq>.i18n.<lang>.json")
+    check_cmd.set_defaults(func=cmd_check)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/prompts/lead/adapters/claude-code.md

@@ -64,7 +64,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 - Follow the core Result Path + terminal-status completion contract. The Claude adapter's wake mechanism is one `Bash(run_in_background: true)` poll covering every pending Result Path, not foreground sleep or an idle-notification dependency. A spawn acknowledgement is never completion.
 - The background poll uses a per-worker deadline of twice the expected duration: 20 minutes for `requirements-discovery`, 30 for `error-analysis`, 40 for `implementation-planning`, 40 for `implementation`, and 20 for `final-verification`. On timeout, record terminal status and apply the core's single shared retry budget.
 - Each in-process worker heartbeat audit sidecar must update at least every five minutes while its result is pending. A missing or stale heartbeat consumes the same one-retry budget; after the second silent hang, record `timeout`. The result file remains the authoritative completion signal.
-- **The background poll checks liveness, not only Result Paths.** Result Paths change once, at the very end, so polling them alone pays the full deadline for a worker that died at minute three. Each poll iteration MUST also run, in the same background shell, one `okstra worker-liveness` call covering every pending worker — `--audit <audit-sidecar-path>` for each in-process worker, and a paired `--team-state <path> --worker <id>` for each CLI-wrapper worker. The dispatch record's `livenessMode` selects the selector; never infer it from provider or filename. The wrapper selector resolves its prompt path and authoritative dispatch `startedAt` from team-state. It exits non-zero when a worker is `stalled` (heartbeat older than the cadence budget) or `did-not-launch`; either verdict ends the wait for that worker immediately and spends the core's one-retry budget, rather than waiting out the deadline. The command reports only — it never kills or re-dispatches. It shares its heartbeat budget with the Phase 7 audit (`okstra_ctl.worker_heartbeat`), so a worker the live probe passes cannot fail the post-hoc one for cadence.
+- **The background poll checks liveness, not only Result Paths.** Result Paths change once, at the very end, so polling them alone pays the full deadline for a worker that died at minute three. Each poll iteration MUST also run, in the same background shell, one `okstra worker-liveness` call covering every pending worker — one paired `--team-state <path> --worker <id>` per worker, in-process and CLI-wrapper alike. The probe reads that worker row's `livenessMode` to pick the artifact and its `startedAt` as the grace anchor; never pass an artifact path yourself and never infer the transport from provider or filename. It exits non-zero when a worker is `stalled` (heartbeat older than the cadence budget) or `did-not-launch`; either verdict ends the wait for that worker immediately and spends the core's one-retry budget, rather than waiting out the deadline. The command reports only — it never kills or re-dispatches. It shares its heartbeat budget with the Phase 7 audit (`okstra_ctl.worker_heartbeat`), so a worker the live probe passes cannot fail the post-hoc one for cadence.
 - The Claude Code harness blocks long foreground sleeps and shorter-sleep circumvention loops. Keep the result poll in a single background shell and let wrapper agents use their documented `BashOutput` loop.
 - On approved cleanup, reconcile the current live session roster before sending shutdown requests. Never target the lead session.
 - Collect usage before teardown. Resume through the recorded Claude session id and keep all run artifacts authoritative.

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

@@ -370,6 +370,7 @@ The detailed persistence checklist and the BLOCKING token-usage collector invoca
 
 Order of operations:
 
+0. **Translation (conditional).** Read `meta.reportLanguage` from the final-report data.json. When it is `en`, skip this step entirely — there is nothing to translate and no worker to pay for. When it is anything else, dispatch `Translator worker` with `**Report Language:**` set to that value and `**Result Path:**` set to `runs/<task-type>/reports/final-report-<task-type>-<seq>.i18n.<lang>.json`. The worker builds its own work list with `okstra report-translate extract` and gates itself with `okstra report-translate check`; Lead verifies the sidecar exists before continuing. The data.json stays English — the sidecar is presentation, overlaid by `render-views` in step 2, and a missing one degrades to an English HTML rather than failing the run.
 1. Run the token-usage collector with `--substitute-data`. The final-report data.json MUST already exist; the collector populates its token / cost cells and re-renders the markdown sibling.
 2. Verify both the final-report data.json and rendered markdown exist at the expected paths. When `Report writer worker` is in the roster, that worker authored the data.json + invoked the renderer in Phase 6 — Lead's job here is to **verify** schema validation passes and structure matches the template output.
 3. Update team-state artifact (preserve usage fields written by the script).

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

@@ -195,8 +195,10 @@ Token Summary Generation Rules:
 - **You populate the data.json in Phase 6, BEFORE Phase 7 runs the collector.** Set `tokenUsage.lead.totalTokens` / `.billableTokens` / `.costUsd`, the `worker` and `grand` rows, `tokenUsage.cli.costUsd`, and each `executionStatus[].{totalTokens,billableTokens,costUsd,durationMs,cliTotalTokens,cliCostUsd}` to JSON `null`. The renderer emits `--` for nulls; `okstra-token-usage.py --substitute-data` populates them in Phase 7 and re-renders the markdown. Never set these cells to `0`, `"not-collected"`, `"--"`, `"N/A"`, or any other sentinel: nulls are the only valid placeholder, and the substitution step depends on them being null when it runs.
 - Set `meta.reportLanguage` to the resolved `en` or `ko` value passed in
   **Report Language**. `auto` is forbidden in this field — the lead has
-  already resolved it. The renderer reads this field as SSOT when no
-  CLI `--report-language` flag is given.
+  already resolved it. The field records **which language the human HTML
+  renders in**, not the language you author in: you always author English
+  (see "Writing Guidelines" below). Phase 7 reads it to decide whether to
+  dispatch the translator.
 - All values come from `usageSummary` (populated by `scripts/okstra-token-usage.py` at the start of Phase 7). Do not estimate or invent.
 - **Lead** row: `usageSummary.leadTotalTokens` / `usageSummary.leadBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.lead`.
 - **Worker subtotal** row: `usageSummary.workerTotalTokens` / `usageSummary.workerBillableEquivalentTokens` / `usageSummary.estimatedCostUsd.claudeWorkers`.
@@ -330,17 +332,16 @@ Every field MUST anchor its claim with at least one evidence reference — a `pa
 - Write in Markdown. **Prefer tables over prose bullet lists** for any section that enumerates multiple items with the same shape (evidence rows, risks, options, dependencies, rollback steps, follow-ups, open questions). Bullets are reserved for short, single-line standalone statements (e.g., "- No additional information requested."). When the template provides a table form, do NOT degrade it back to bullets in the rendered report. **Exception — `## Background and Rationale` (`rationale`) is deliberately prose**: it is connected narrative explaining the *why*, not a same-shape enumeration, so write full sentences there rather than forcing it into a table.
 - **Do not restate the same conclusion verbatim across sections.** The Verdict Card and Reader Summary are *digests*: give the outcome in one or two sentences and point to `## 7. Final Verdict` / `## 5.8.8 Routing Recommendation` for the full reasoning, rather than copying their multi-clause conclusion word-for-word. Only the `Verdict Token` and `Direction` cells must byte-match §7 (per the Verdict Card contract above). `Next Step` must point to the same routing target as §7, but its actionable command and prose need not be byte-identical. The prose conclusion must not be a duplicate.
 - **Keep each sentence to one main idea.** A single sentence that stacks four or five clauses with em-dashes and nested parentheticals (300+ characters) is hard to read, and the renderer can only line-break at sentence ends — so break such reasoning into separate sentences. Facts, evidence, and IDs still live in the tables; prose carries only the connective *why*.
-- Write the final report body in the language passed in **Report Language**
-  above (`en` or `ko`). The template's fixed labels (section asides,
-  empty-states, token summary, column headers, release-handoff labels)
-  are i18n-rendered by `okstra-render-final-report.py` from
-  `templates/reports/i18n/<lang>.json`; do not translate those — focus
-  on the prose you author (Section 6 categories, Section 2 evidence
-  narratives, Section 5 risks, Section 3 recommendations, etc.).
-  Code identifiers, file paths, model names, status tokens, and the
-  validator-checked English substrings (`Option Candidates`,
-  `Verdict Token`, `accepted`/`conditional-accept`/`blocked`, etc.)
-  stay in English regardless of Report Language.
+- **Write the report body in English, whatever the Report Language is.**
+  The data.json is the SSOT every later phase, validator and agent reads,
+  and its AI-handoff Markdown sibling has the same audience, so both stay
+  in one language. Only the human HTML follows the reader: when
+  **Report Language** is not `en`, Phase 7 dispatches the translator
+  worker, which writes a sidecar the HTML renderer overlays. You never
+  author that sidecar and never write a second language into the data.json.
+  The HTML's own fixed strings — headings, column headers, empty states,
+  enum labels — come from `templates/reports/html/i18n/<lang>.json` and
+  are not yours to write either.
 - If only one worker is usable, perform a reduced-confidence synthesis
 - If evidence is insufficient, explicitly state "I don't know"
 - If expected values are present in `reference-expectations.md`, list matches, gaps, and missing evidence separately

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

@@ -125,7 +125,7 @@ Terminal statuses that can be recorded for a worker:
 
 Between wakes, `okstra worker-liveness` is the **only** sanctioned way to ask whether a pending worker is still alive. Do NOT hand-roll a polling script, an `ls` / `stat` loop, or any ad-hoc file-existence check: a lead that writes its own probe owns that probe's bugs, and those bugs surface as *worker* failures — a shell quoting slip silently turns the probe into a no-op that reports health it never measured.
 
-Each probe matches exactly one dispatch backend. The dispatch record's `livenessMode` is authoritative: `audit-heartbeat` registers the in-process audit sidecar, while `wrapper-status` registers the CLI wrapper status sidecar. Do not infer either transport from a worker filename or provider name.
+Each probe matches exactly one dispatch backend. The worker row's `livenessMode` is authoritative and the probe reads it for you: `audit-heartbeat` registers the in-process audit sidecar, while `wrapper-status` registers the CLI wrapper status sidecar. Do not infer either transport from a worker filename or provider name, and do not pass the artifact path yourself.
 
 | Worker | Backend | Flag | What it reads |
 |---|---|---|---|
@@ -148,7 +148,7 @@ After each worker subagent returns (regardless of role), Lead MUST verify the ca
 - The result file is absent at the resolved absolute path even though the worker returned without a `*_RESULT_MISSING` sentinel — for example, claude-worker returned its final assistant message but never persisted the artifact, or the wrapper exited 0 and the codex/antigravity sub-agent forwarded raw stdout despite the contract.
 - The result file exists but cannot be parsed (frontmatter unreadable, sections 1–5 entirely missing). A truncated file in the middle of section 5 is NOT covered here — it goes to the validator's regular `error` path, not the retry path.
 - `okstra worker-liveness --team-state <path> --worker <id>` reports a **CLI-wrapper** worker (`codex` / `antigravity`) `did-not-launch` — neither `<prompt-path>.log` nor `<prompt-path>.status.json` exists after the persisted `startedAt` plus the launch grace (default 60s). The wrapper writes its status sidecar before invoking the CLI and hard-fails loudly with a distinct exit code on every argument check before that, so the absence of BOTH artifacts means the dispatch itself never reached the script. Without this trigger the only evidence was a lead noticing two missing files by eye, and the run paid the full polling cap for a worker that never started.
-- `okstra worker-liveness --audit` reports an **in-process** worker `stalled` — its registered audit sidecar's newest `- PROGRESS:` heartbeat is older than the cadence budget, or the sidecar carries no heartbeat at all. This is the in-process equivalent of the CLI wrappers' idle watchdog: the wrapper reaps a silent CLI itself, but nothing reaped a silent in-process worker until its deadline.
+- `okstra worker-liveness --team-state <path> --worker <id>` reports an **in-process** worker `stalled` — its registered audit sidecar's newest `- PROGRESS:` heartbeat is older than the cadence budget, or the sidecar carries no heartbeat at all. This is the in-process equivalent of the CLI wrappers' idle watchdog: the wrapper reaps a silent CLI itself, but nothing reaped a silent in-process worker until its deadline. The same selector serves both worker kinds — the sidecar is reused when a worker is re-dispatched, so the probe needs the row's `startedAt` to tell the previous attempt's last heartbeat apart from this dispatch's silence.
 - The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
 
 **One-retry policy:**

package/runtime/prompts/profiles/project-analysis.md

@@ -18,6 +18,24 @@
   - scan scope and excluded areas
   - components, dependency directions, entry points, repositories, and external integrations
   - shallow feature index and unresolved navigation questions
+- Fill these when the repository states them; leave a block out rather than guessing at it:
+  - `projectAnalysis.techStack` — the languages the project is written in with their
+    versions, the frameworks it runs on, and the package manager, build, test, lint,
+    typecheck, format, CI and container tools. Record where each version was read via
+    `versionSource`: a manifest range (`^1.17.0`) and a lockfile pin are different facts,
+    and a mismatch between a pinned server image and a ranged client is a real
+    compatibility risk that collapses if both are written the same way. A tool the
+    project does not have is not a row — its absence belongs in `qualityCoverage`.
+  - `projectAnalysis.internalInterfaces` — the seams components call across, with the
+    signature a caller writes against. `kind` is what the seam is, not where its file
+    sits: `port` for an abstraction a domain declares, `adapter` for an implementation
+    that satisfies one. `ownerComponentId` and every `consumers` entry must name a
+    component this report declares.
+  - `projectAnalysis.workflows` — one run of real work through the system, start to
+    finish: what triggers it and which component does what, in order. This is the only
+    block that says how the parts are used rather than how they are arranged, so a
+    reader can follow a request without reconstructing it from the dependency graph.
+    Each step's `componentId` must name a declared component.
 - Cross-verification mode:
   - Phase 5.5 convergence runs in adversarial mode (`convergence.adversarial=true`).
 - Non-goals:

package/runtime/prompts/profiles/release-handoff.md

@@ -1,5 +1,8 @@
 # Release Handoff Profile
 
+- Record the handoff shape in `releaseHandoff.handoffScope`: `mode` always, plus `stages`
+  and `collectorBranch` in stage-group mode. The report is the only place a reader learns
+  which stages shipped — the collector branch name does not say.
 - Purpose: take an `accepted` final-verification verdict for an already-committed implementation branch and turn it into a delivered push and/or pull request, with explicit user selection at every mutating step. Two modes: **whole-task** (default — the verified task branch becomes one PR) and **stage-group** (a user-selected subset of verified stages is merged into a collector branch and becomes one PR).
 - **Execution model: single-lead, no worker dispatch.** This phase is a thin orchestrator over `git` / `gh`; it does NOT dispatch teammates, does NOT dispatch analysis or drafter sub-agents, and does NOT run convergence. The host-native Okstra lead performs every step inline (drafting PR text, asking the user, running git / gh, writing the final report) — see "Lead-only contract" below.
 - Worker roster: none — this profile intentionally has no `- Required workers:` block; the run is executed entirely by the Okstra lead.

package/runtime/prompts/profiles/requirements-discovery.md

@@ -25,6 +25,13 @@
   - classify the work as bugfix, feature, improvement, refactor, or ops
   - determine whether `error-analysis` or `implementation-planning` is the next safe step. Direct `implementation` handoff is never a valid routing target — implementation requires an approved `implementation-planning` report
   - capture the reporter's **rejection criteria** — the delivered outcome that would make this work wrong or unacceptable — as a routing input. Consume it from the brief's `Desired Outcome` / `Out of Scope` / `Source Material` when present; when it is absent AND it would change the classification (e.g. bugfix vs feature) or the next-phase choice, raise it as one `decision` clarification row with `Evidence checked: none — reporter intent`. Never infer it — this is a reporter-intent signal, the mirror of improvement-discovery's `Anti-goals`
+  - record the rejection criteria in `requirementsDiscovery.rejectionCriteria` with the
+    `source` that produced it. When it was absent and would not have changed the
+    classification or the routing, say so with `source: absent-not-material` — an empty
+    field cannot be told apart from a phase that never looked
+  - record the terminology this phase settled in `requirementsDiscovery.domainAlignment`:
+    whether the glossary and decision records were read, and for every fuzzy or overloaded
+    term, the single canonical form and what decided it
   - identify missing materials that block reliable routing
   - define task continuity expectations for long-running work under the same task key
   - capture approval or confirmation points before the next phase starts

package/runtime/prompts/wizard/prompts.ko.json

@@ -456,7 +456,23 @@
       }
     },
     "workers_override": {
-      "label": "참여시킬 분석 워커를 선택해주세요 (최소 1개). report-writer 는 항상 포함됩니다.",
+      "label": "이번 run 에 추가할 분석 워커를 선택해주세요 (최소 1개, 여러 개 가능).\n기본 워커와 report-writer 는 항상 참여하므로 목록에 없습니다 — 기본 워커에서 일부를 빼려면 '직접 선택'을 고르세요.",
+      "echo_template": "workers: {value}",
+      "labels": {
+        "default_roster": "기본 워커만 ({workers}) — 옵션 워커 추가 없음",
+        "add_optional": "{worker} 추가 (옵션)"
+      },
+      "options": {
+        "__free_input__": "직접 선택 (기본 워커까지 포함한 전체 목록에서 고르기)"
+      },
+      "errors": {
+        "min_one_required": "워커를 최소 1개 선택해주세요",
+        "custom_must_be_alone": "'직접 선택'은 다른 항목과 함께 고를 수 없습니다 — 단독으로 선택해주세요",
+        "unknown_option": "목록에 없는 항목입니다: {values}"
+      }
+    },
+    "workers_custom": {
+      "label": "참여시킬 분석 워커를 직접 선택해주세요 (최소 1개). report-writer 는 항상 포함됩니다.",
       "echo_template": "workers: {value}",
       "options": {
         "_OPTIONAL_SUFFIX": " (옵션)"

package/runtime/python/okstra_ctl/analysis_inputs.py

@@ -5,7 +5,7 @@ import json
 import re
 import subprocess
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Mapping, Sequence
 
@@ -73,7 +73,6 @@ _REPORT_NAME_RE = re.compile(r"^final-report-.+-(?P<run_seq>[^-]+)\.md$")
 _FEATURE_ID_RE = re.compile(r"PF-\d{3}")
 _FULL_COMMIT_RE = re.compile(r"[0-9a-f]{40}")
 _RUN_SEQ_RE = re.compile(r"[0-9]{3}")
-_CREATED_AT_RE = re.compile(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z")
 
 
 def parse_evidence_paths(
@@ -149,15 +148,31 @@ def _validated_commit(value: str, field: str) -> str:
 
 
 def _validated_created_at(value: str) -> str:
-    if _CREATED_AT_RE.fullmatch(value) is None:
-        raise AnalysisInputError(
-            "data.json header.createdAt must use YYYY-MM-DDTHH:MM:SSZ"
-        )
+    """The candidate's creation instant in canonical UTC ``...Z`` form.
+
+    What this field must give the caller is one *comparable* value — candidates
+    are ordered by it. It is not a spelling contract: the report schema requires
+    only a non-empty string, nothing tells a report-writer to emit UTC, and
+    `validate-run` accepts a local offset. Demanding `Z` here made this loader
+    the only reader that rejected a report every other reader had accepted, and
+    the run lost its carry-in candidates without saying why. So normalise.
+
+    An instant with no offset is still refused: guessing its zone would order
+    it wrongly against the others.
+    """
     try:
-        datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
+        instant = datetime.fromisoformat(value.replace("Z", "+00:00"))
     except ValueError as exc:
-        raise AnalysisInputError("data.json header.createdAt is invalid") from exc
-    return value
+        raise AnalysisInputError(
+            "data.json header.createdAt must be an ISO-8601 instant "
+            "(e.g. 2026-08-05T04:25:00Z or 2026-08-05T04:25:00+09:00)"
+        ) from exc
+    if instant.tzinfo is None:
+        raise AnalysisInputError(
+            "data.json header.createdAt carries no UTC offset, so it cannot be "
+            "ordered against the other candidates"
+        )
+    return instant.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 
 
 def _report_path_metadata(project_root: Path, report_path: Path) -> tuple[Path, str, str]:

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -299,17 +299,39 @@ def _top_level_bullet_heading(line: str) -> str:
     return label
 
 
+# Report headings carry a section number and the renderer's scroll anchor
+# (`## 1. Clarification Items <a id="1-clarification-items"></a>`), while the
+# section names above are written bare. Keying a heading by both spellings is
+# what lets a lookup for `Clarification Items` find it — without the alias the
+# Carry-In Extract rendered `No matching source sections were available` for
+# every carry-in ever staged. No section name starts with a digit, so the
+# stripped alias cannot collide with a name meant to be matched literally.
+_HEADING_NUMBER_RE = re.compile(r"^\d+(?:\.\d+)*\.?\s+")
+_HEADING_ANCHOR_RE = re.compile(r'\s*<a id="[^"]*"></a>\s*$')
+
+
+def _heading_alias(heading: str) -> str:
+    return _HEADING_NUMBER_RE.sub("", _HEADING_ANCHOR_RE.sub("", heading)).strip()
+
+
 def _section_map(text: str) -> dict[str, str]:
     result: dict[str, list[str]] = {}
+    aliases: dict[str, str] = {}
     current = ""
     for line in _strip_frontmatter(text).splitlines():
         if line.startswith("## "):
             current = line[3:].strip()
             result.setdefault(current, [])
+            alias = _heading_alias(current)
+            if alias and alias != current:
+                aliases.setdefault(alias, current)
             continue
         if current:
             result[current].append(line)
-    return {key: "\n".join(lines).strip() for key, lines in result.items()}
+    sections = {key: "\n".join(lines).strip() for key, lines in result.items()}
+    for alias, heading in aliases.items():
+        sections.setdefault(alias, sections[heading])
+    return sections
 
 
 def _strip_frontmatter(text: str) -> str: