okstra 0.34.1 → 0.36.1

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

@@ -68,7 +68,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 6. Extract the assigned model execution value for `Gemini worker`.
    - First, use the value explicitly assigned in the lead prompt.
    - If the lead prompt only lists the display model, use the canonical execution value from the referenced task bundle metadata (`task-manifest.json` → `resultContract.requiredWorkerRoles[]` for the gemini role).
-   - If no assigned model execution value can be determined, immediately return `GEMINI_MODEL_MISSING: assigned Gemini model execution value was not provided`. Do NOT fall back to training-data defaults — historical Gemini defaults (e.g. `gemini-1.5-flash`) are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
+   - If no assigned model execution value can be determined, immediately return `GEMINI_MODEL_MISSING: assigned Gemini model execution value was not provided`. Do NOT fall back to training-data defaults — historical Gemini defaults like `gemini-1.5-flash` are NOT acceptable substitutes for the assigned model. Returning the sentinel is the correct behavior; the lead is responsible for fixing its prompt and redispatching.
    - This rule applies equally to convergence reverify rounds. The reverify prompt MUST carry the same `**Model:**` line as the initial run (see `okstra-convergence` skill, "Required reverify-prompt anchor headers"). If the line is absent in a reverify prompt, return `GEMINI_MODEL_MISSING` rather than guessing.
 
 7. If installed, dispatch the wrapper as a **background** Bash command and poll for completion. The two-minute foreground Bash timeout is insufficient for implementation-phase Gemini runs and forced workers into ad-hoc background dispatch with lost output. The polling contract below is the formal replacement.
@@ -79,7 +79,7 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
    ```
    Call `Bash` with `run_in_background: true`. Capture the returned `bash_id` (a.k.a. `shell_id`). Pass the positional arguments verbatim — do NOT use environment variables, `cd`, `&&` chains, or pipes from `cat`. Substitute the literal extracted Project Root, model execution value, prompt-history path, and worktree path. The fourth argument is **mandatory for implementation phase** (extract from `EXECUTOR_WORKTREE_PATH` in the lead prompt's run context or the `**Worktree:**` / `cwd for every mutating command:` line) and **may be omitted only for non-implementation analysis phases** that do not mutate the worktree. The wrapper handles `-p -`, `-m`, `-o text`, `--include-directories`, the stdin redirect from the prompt file, and stderr suppression internally. Calling `gemini` directly (without the wrapper) is an error in this skill: the redirect tokens disqualify the prefix match against `Bash(gemini:*)` and produce a permission prompt every dispatch.
 
-   **Poll loop (BashOutput-only, 30-minute hard cap):**
+   **Poll loop (BashOutput-only, 30-minute cap):**
    - Record `start_ts` at dispatch time via a single `Bash` call: `date +%s` (output captured).
    - Repeat:
      1. Call `BashOutput(bash_id: <shell_id>)`. Inspect `status`. The harness's `BashOutput` primitive already waits internally for new output before returning; back-to-back calls are the canonical wait mechanism for a background shell.
@@ -108,6 +108,8 @@ The wrapper exists because Claude Code's Bash permission matcher rejects simple-
 
    d. **Normal return.** Otherwise (`exit_code == 0` AND result file exists), concatenate the wrapper's accumulated stdout from `BashOutput` and return it as-is without modification.
 
+9. When `Task Type` is `improvement-discovery`, the lead's Phase 1.5 reflect-back log at `<RUN_DIR>/state/phase-1.5-grilling.md` is the authoritative scope and lens definition. Read its `Resolved scope` and `Resolved lenses` blocks and do NOT re-interpret the brief's raw `scan-scope` / `priority-lenses` fields. Findings that violate the resolved lens whitelist or scope are rejected by `validators/validate-improvement-report.py`.
+
 ## Stop Condition
 
 This wrapper is a thin Bash-execution shell over the Gemini CLI (via `okstra-gemini-exec.sh`). The CLI process itself is the analysis engine; this subagent's only job is to dispatch it and forward output. Therefore:
@@ -126,7 +128,7 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 ## Prompt Composition
 
 - The lead prompt must include both `**Project Root:** <absolute-path>` (at the top) and `Assigned worker prompt history path: <path>`.
-- Treat that path as the canonical worker prompt history artifact for the current run.
+- Treat the prompt-history path as the canonical worker prompt history artifact for the current run, resolved to absolute against `Project Root` if given as relative.
 - The assigned model execution value is canonical for CLI execution. Do not substitute a different Gemini model unless the task bundle explicitly changes it.
 - Pass the prompt received from Lead directly to gemini after persisting the exact prompt to the assigned path.
 - Include context (code, diff, file paths) if provided.
@@ -138,11 +140,12 @@ This wrapper does NOT invoke MCP tools directly. MCP availability inside the Gem
 
 ## Required Reading Before Any Analysis
 
-Before producing any output, you MUST ensure the underlying Gemini CLI run reads every input file enumerated in the `[Required reading]` block of the lead's prompt from the very first character to the very last character. For analysis workers this includes the task brief, analysis profile, analysis material (if present), reference expectations, and the carry-in clarification response (if present). Analysis workers do NOT read `final-report-template.md` — that file is for the Report writer worker only (see `okstra-team-contract` "Audience-scoped enumeration"). Producing findings without the template is the intended contract; the report writer in Phase 6 owns final-report structure.
+Before invoking the Gemini CLI, you MUST:
+
+1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and verify the CLI run will Read that file end-to-end (canonical SSOT for the Required Reading + Error Reporting + Output sections contract). The lead's prompt body — which you persist verbatim and feed into Gemini via stdin — already contains this anchor; do not strip it.
+2. Verify the lead's prompt body lists the per-run input files under `## Inputs` (task-brief, analysis-profile, analysis-material if present, reference-expectations, clarification-response if carry-in). Analysis workers do NOT read `final-report-template.md` — that file is for the report writer only.
 
-- The lead's prompt body, which you persist verbatim and feed into Gemini via stdin, already contains the explicit list of files and the end-to-end reading rule. Do not strip or summarize that block before passing it to the CLI.
-- For the carry-in clarification response, the CLI must walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface. The structural similarity between the prior final report and the upcoming output is the most common reason this step gets skipped — do not repeat that.
-- The wrapper writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/gemini-worker-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). The sidecar's body begins with `# Gemini Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading (e.g. `- Read task-brief.md end-to-end (147 lines).`). The main Gemini output MUST NOT contain a `## 0. Reading Confirmation` heading — the validator now fails worker-results that contain one. If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+The CLI writes a Reading Confirmation block to the **audit sidecar** at `runs/<task-type>/worker-results/gemini-worker-audit-<task-type>-<seq>.md`. The sidecar's body begins with `# Gemini Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading. The main Gemini output MUST NOT contain a `## 0. Reading Confirmation` heading — the validator fails worker-results that contain one. If any file was skipped, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
 
 ## Worker Output Structure
 
@@ -227,3 +230,27 @@ pre-flight terminal status, not a runtime CLI error.
 - Return error messages as-is on failure.
 - Do not summarize or modify Gemini results.
 - Sections 1–5 of the worker output are the common core shared with the Claude and Codex workers — the dispatched prompt asks identical questions for all three roles, and the Gemini CLI must answer all of them, not only requirement-interpretation findings. Your specialization (requirement interpretation, consistency, safety, documentation quality, alternative viewpoints) belongs only in optional Section 6 as additive depth. A Gemini result whose Findings section is populated solely with requirement-interpretation items is in breach of contract; see `skills/okstra-team-contract/SKILL.md` "Worker Output Contract".
+
+## Stage evidence emission (BLOCKING, implementation task only)
+
+When this run's `task_type` is `implementation` and you are acting as the **Executor**, after the Stage Validation `post` commands all return exit code 0 you MUST emit a single JSON document matching `docs/superpowers/specs/2026-05-20-implementation-planning-multi-stage-design.md` §3.2:
+
+```json
+{
+  "schemaVersion": 1,
+  "sourcePlanPath": "<approved-plan path>",
+  "stageNumber": <int>,
+  "stageTitle": "<from Stage Map>",
+  "completedAt": "<ISO-8601 with tz>",
+  "stageCommitRange": { "base": "<sha>", "head": "<sha>" },
+  "filesChanged": ["<rel/path>", "..."],
+  "newIdentifiers": ["<name>", "..."],
+  "stepResults": [{"step": <int>, "status": "done", "commit": "<sha>"}],
+  "validationsPassed": ["<label>", "..."],
+  "notes": []
+}
+```
+
+Emit this as a fenced ```json``` block in your worker result under the heading `### Stage Carry Evidence`. The lead (`Claude lead`) is responsible for persisting the block as `runs/<impl-task-key>/carry/stage-<N>.json` — you do not write the file yourself.
+
+This applies only when `task_type` is `implementation`. For other task types, skip this block entirely.

package/runtime/agents/workers/report-writer-worker.md

@@ -16,6 +16,10 @@ tools: ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "TodoWrite", "WebFetch"
 
 You are the `Report writer worker` for okstra cross-verification. Your sole responsibility is to **author the final-report data.json** (the JSON SSOT) at the assigned `Result Path`, plus an audit sidecar. You are NOT an analysis worker — you do not produce independent findings, you do not vote in convergence, and you do not re-do the workers' analysis.
 
+- The `**Report Language:**` header in your dispatch prompt is already
+  resolved to `en` or `ko` by the lead. Copy it verbatim into
+  `data.json.meta.reportLanguage`. Never write `auto` here.
+
 ## Authority
 
 You are the canonical author of `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` for this run. Claude lead has explicitly delegated file-authorship to you. The lead reviews your output but does not write the file.
@@ -56,18 +60,22 @@ Do NOT duplicate the data.json contents here — the data.json is the canonical
 
 ## Required Reading Before Authoring
 
-Before writing the data.json, you MUST read every input file enumerated in the `[Required reading]` block of the lead's prompt from the very first character to the very last character. This always includes:
+Before writing the data.json, you MUST:
+
+1. Extract the absolute path from the lead's `**Worker Preamble Path:**` anchor header and Read that file end-to-end (canonical SSOT for the Required Reading + Error Reporting + Anchor contract — this overrides per-spec restatements).
+2. Read every input file the lead enumerated under `## Inputs` (or equivalent heading) in the dispatch prompt body, end-to-end (single `Read` call with no `offset`/`limit`; page through with explicit offsets only when a file is too large for one read).
 
-- `schemas/final-report-v1.0.schema.json` — the JSON Schema you must conform to. The renderer + validator both consume this.
-- `templates/reports/final-report.template.md` — the Jinja2 template the renderer uses. Read this to understand which data.json fields appear where in the rendered markdown, but do NOT edit it.
+For the report writer specifically, the `## Inputs` list always includes:
+
+- `schemas/final-report-v1.0.schema.json` — the JSON Schema you must conform to. The renderer + validator both consume it.
+- `templates/reports/final-report.template.md` — the Jinja2 template the renderer uses. Read it to understand which data.json fields appear where in the rendered markdown; do NOT edit it.
+- `templates/reports/i18n/en.json` and `templates/reports/i18n/ko.json`.
 - Every analysis worker's result file under `worker-results/`.
-- `state/convergence-<task-type>-<seq>.json` (if present).
+- `state/convergence-<task-type>-<seq>.json` (if present). When present, reproduce its `roundHistory[]`, `round2SkippedReason`, and `finalClassificationCounts` verbatim into the final report's Section 1 Round History sub-table — do not recompute from worker results.
+
+For the carry-in `clarification-response.md` (if present), walk every row of `## 5. Clarification Items` including rows whose `User input` cell is blank — a blank cell with `Status=open` is a signal you must surface in the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it when the carry-in path is non-empty). When no carry-in path was provided, OMIT the `## 0.` heading entirely — do NOT write an empty-state stub.
 
-- Use a single `Read` call per file with no `offset` and no `limit`. If a file is too large for one read, page through it with explicit `offset` / `limit` calls covering the full file.
-- For the carry-in `clarification-response.md` (if present), walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) including rows whose `User input` cell is blank — a blank cell with `Status=open` is itself a signal you must surface in the conditional `## 0. Clarification Response Carried In From Previous Run` section (the template's `RENDER_IF` guard activates it when the carry-in path is non-empty). The fact that the file you write has a structurally similar section 5 is NOT an excuse to skim. When no carry-in path was provided, OMIT the `## 0.` heading entirely — do NOT write an empty-state stub.
-- Open every analysis-worker result file under `worker-results/` end-to-end. Do not summarize them from convergence output alone — convergence captures classifications, not full evidence.
-- Write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). The sidecar's body begins with `# Report Writer Worker Audit — <task-key>` followed by one short line per input file confirming end-to-end reading. The main final-report and the main worker-results file MUST NOT contain a `## 0. Reading Confirmation` heading — the validator now fails reports that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating the report.
-- When the convergence-state file is present, read it fully and reproduce the `roundHistory[]` array, `round2SkippedReason`, and `finalClassificationCounts` in the final report's Section 1 Round History sub-table. Do not derive these values from worker results alone — they live in `state/convergence-<task-type>-<seq>.json`.
+Write a Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md`. The main final-report and the main worker-results file MUST NOT contain a `## 0. Reading Confirmation` heading. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating the report.
 
 ## Authoring Contract
 
@@ -75,7 +83,7 @@ You author the final-report data.json (the JSON SSOT). The schema is `schemas/fi
 
 The rendered markdown (`final-report-<task-type>-<seq>.md`) is produced by `scripts/okstra-render-final-report.py` immediately after you write the data.json. The HTML view (`*.html`) is produced from the markdown by Phase 7 step 1.5 (`scripts/okstra-render-report-views.py`). The data.json is the only file you write; the rest are derived.
 
-Hard rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
+Rules (the schema enforces most of these — they are listed here so you know *what* to populate, not *how* to validate):
 
 - `header.reportAuthor` is `"Report writer worker"`; `header.reportOwner` is `"Claude lead"`. Set author to `"Claude lead"` only for `release-handoff` runs (single-lead by design) or a recorded report-writer dispatch failure fallback.
 - **Source items (worker:item) preservation.** Every `consensus[].sourceItems`, `differences[].workersPosition[].itemId`, and `evidence.primary[].sourceItems` entry MUST carry the worker:item-id pair (e.g. `claude:F-001`, `codex:1.1`, `gemini:F-3`, or `lead:mcp-1` for lead-only evidence). The schema enforces this via the `SourceItem` regex; bare worker-name lists no longer parse.
@@ -92,6 +100,7 @@ Hard rules (the schema enforces most of these — they are listed here so you kn
 - If evidence is missing, write `"I don't know"` in the relevant statement field rather than fabricating confidence.
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
+- When the `Task Type` is `improvement-discovery`, populate `## 4.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate-improvement-report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes.
 
 Write the data.json with your `Write` tool against the absolute `Result Path`. Then invoke the renderer (`Bash`): `python3 scripts/okstra-render-final-report.py <data.json path>`. Confirm both files exist and respond with a short status line: `data.json written to <abs path>; markdown rendered to <abs path>. Sections populated: <count>.`
 

package/runtime/bin/okstra-central.sh

@@ -102,11 +102,11 @@ print(json.dumps({k: v for k, v in zip(it, it)}, ensure_ascii=False))
     PROJECT_ROOT "${PROJECT_ROOT-}" \
     TASK_GROUP "${TASK_GROUP-}" \
     TASK_ID "${TASK_ID-}" \
-    ANALYSIS_TYPE "${ANALYSIS_TYPE-}" \
+    TASK_TYPE "${TASK_TYPE-}" \
     OKSTRA_RUN_SEQ "$_run_seq" \
     RUN_TIMESTAMP_ISO "${RUN_TIMESTAMP_ISO-}" \
-    SELECTED_REVIEWERS "${SELECTED_REVIEWERS-}" \
-    LEAD_MODEL_DISPLAY "${LEAD_MODEL_DISPLAY-}" \
+    RECOMMENDED_ANALYSERS "${RECOMMENDED_ANALYSERS-}" \
+    LEAD_MODEL "${LEAD_MODEL-}" \
     RUN_DIR_RELATIVE_PATH "${RUN_DIR_RELATIVE_PATH-}" \
     FINAL_REPORT_RELATIVE_PATH "${FINAL_REPORT_RELATIVE_PATH-}" \
     FINAL_STATUS_RELATIVE_PATH "${FINAL_STATUS_RELATIVE_PATH-}" \
@@ -134,11 +134,11 @@ with lockfile.open("r+") as lock:
         project_root=payload["PROJECT_ROOT"],
         task_group=payload["TASK_GROUP"],
         task_id=payload["TASK_ID"],
-        task_type=payload.get("ANALYSIS_TYPE", ""),
+        task_type=payload.get("TASK_TYPE", ""),
         run_seq=int(payload["OKSTRA_RUN_SEQ"]),
         when=payload["RUN_TIMESTAMP_ISO"],
-        workers=[w for w in payload.get("SELECTED_REVIEWERS", "").split(",") if w],
-        lead_model=payload.get("LEAD_MODEL_DISPLAY", ""),
+        workers=[w for w in payload.get("RECOMMENDED_ANALYSERS", "").split(",") if w],
+        lead_model=payload.get("LEAD_MODEL", ""),
         run_dir_rel=payload.get("RUN_DIR_RELATIVE_PATH", ""),
         final_report_rel=payload.get("FINAL_REPORT_RELATIVE_PATH", ""),
         final_status_rel=payload.get("FINAL_STATUS_RELATIVE_PATH", ""),

package/runtime/bin/okstra-codex-exec.sh

@@ -187,19 +187,35 @@ python3 "$script_dir/okstra-wrapper-status.py" \
   init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
   >>"$log_path" 2>&1 || true
 
+# Resolve caller pane id robustly. tmux normally exports both `$TMUX` and
+# `$TMUX_PANE` to processes started inside a pane, but Claude Code's Bash
+# tool can drop `$TMUX_PANE` while preserving `$TMUX` — which would
+# silently skip the caller-pane rename below AND let `tmux split-window`
+# attach the trace pane to whatever tmux currently considers active
+# (not necessarily Claude's pane). When the wrapper is launched from
+# Claude Code, the Claude session's pane IS the active pane at this
+# moment, so falling back to `display-message -p '#{pane_id}'` recovers
+# the correct id.
+caller_pane="${TMUX_PANE:-}"
+if [[ -z "$caller_pane" && -n "${TMUX:-}" ]]; then
+  caller_pane=$(tmux display-message -p '#{pane_id}' 2>/dev/null || true)
+fi
+
 # Pane titles: worker (caller) pane gets `codex-<role>-<pid>`; the sibling
-# trace pane appends `-trace`. The wrapper PID disambiguates concurrent
-# dispatches of the same role (e.g. two `codex-worker` panes spawned in
-# parallel) so the operator can match worker ↔ trace at a glance.
+# trace pane appends `-trace[from=<caller-pane-id>]`. The wrapper PID
+# disambiguates concurrent dispatches of the same role; the embedded
+# caller pane id keeps the trace ↔ worker mapping visible even if the
+# worker pane's title is later overwritten by the parent process (e.g.
+# Claude Code's TUI emitting OSC 2 escape sequences on its own pane).
 pane_label="codex-${role}-$$"
-trace_label="${pane_label}-trace"
+trace_label="${pane_label}-trace[from=${caller_pane:-?}]"
 
 # Capture the caller pane's current title so the EXIT trap can restore it
 # once the wrapper returns. Empty when not in tmux or capture fails — the
 # restore step degrades to a no-op in that case.
 original_caller_title=""
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  original_caller_title=$(tmux display-message -p -t "$TMUX_PANE" '#{pane_title}' 2>/dev/null || true)
+if [[ -n "$caller_pane" ]]; then
+  original_caller_title=$(tmux display-message -p -t "$caller_pane" '#{pane_title}' 2>/dev/null || true)
 fi
 
 _okstra_status_finish() {
@@ -210,16 +226,16 @@ _okstra_status_finish() {
   python3 "$script_dir/okstra-wrapper-status.py" \
     finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
     >>"$log_path" 2>&1 || true
-  if [[ -n "${TMUX_PANE:-}" && -n "$original_caller_title" ]]; then
-    tmux select-pane -t "$TMUX_PANE" -T "$original_caller_title" 2>/dev/null || true
+  if [[ -n "$caller_pane" && -n "$original_caller_title" ]]; then
+    tmux select-pane -t "$caller_pane" -T "$original_caller_title" 2>/dev/null || true
   fi
 }
 trap _okstra_status_finish EXIT
 
 # Label the caller (worker) pane now that the restore trap is armed. Any
 # failure after this point still rewinds the title to its prior value.
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  tmux select-pane -t "$TMUX_PANE" -T "$pane_label" 2>/dev/null || true
+if [[ -n "$caller_pane" ]]; then
+  tmux select-pane -t "$caller_pane" -T "$pane_label" 2>/dev/null || true
 fi
 
 # When a tmux session is reachable, split a sibling pane that tails the live
@@ -227,35 +243,40 @@ fi
 # for the wrapper to exit. This fires in every phase the wrapper is invoked
 # from (analysis, error-analysis, implementation-planning, implementation,
 # …) — long-running codex dispatches are not implementation-specific. The
-# new pane carries the title `codex-<role>-<pid>-trace` (matching the
-# caller pane's `codex-<role>-<pid>` label so worker ↔ trace pairs are
-# greppable); `role` is the optional 5th positional arg (defaults to
-# `worker`); callers that dispatch a different role (e.g. `executor`) must
-# pass it explicitly. The `<pid>` suffix is the wrapper's PID and
-# disambiguates concurrent dispatches of the same role. The pane uses
-# `tail -F`
-# (follow-by-name) so it survives any truncation a re-dispatch performs on
-# the same log path. Failures are tolerated silently: missing $TMUX, a tmux
-# that refuses to split (size constraints, locked client), or a stale socket
+# new pane carries the title `codex-<role>-<pid>-trace[from=<caller-pane>]`
+# so the operator can map trace ↔ worker by pane id even when the worker
+# pane title is later overwritten by Claude Code. The split is explicitly
+# anchored to the caller pane (`-t "$caller_pane"`) to avoid attaching to
+# tmux's idle active pane when `$TMUX_PANE` was missing. `role` is the
+# optional 5th positional arg (defaults to `worker`); callers that
+# dispatch a different role (e.g. `executor`) must pass it explicitly.
+# The `<pid>` suffix is the wrapper's PID and disambiguates concurrent
+# dispatches of the same role. The pane uses `tail -F` (follow-by-name)
+# so it survives any truncation a re-dispatch performs on the same log
+# path. Failures are tolerated silently: missing $TMUX, a tmux that
+# refuses to split (size constraints, locked client), or a stale socket
 # all degrade to "log file is still on disk; the operator can tail it
-# manually from any terminal." The wrapper does NOT switch focus to the new
-# pane — control returns to the caller's pane via `tmux last-pane`.
+# manually from any terminal." The wrapper does NOT switch focus to the
+# new pane — control returns to the caller's pane via `tmux last-pane`.
 if [[ -n "${TMUX:-}" ]]; then
-  trace_pane=$(tmux split-window -h -P -F '#{pane_id}' \
-    -c "$(dirname "$log_path")" \
+  split_args=(-h -P -F '#{pane_id}' -c "$(dirname "$log_path")")
+  if [[ -n "$caller_pane" ]]; then
+    split_args+=(-t "$caller_pane")
+  fi
+  trace_pane=$(tmux split-window "${split_args[@]}" \
     "tail -F $(printf '%q' "$log_path")" 2>/dev/null || true)
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "$trace_label" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
     # Register the spawned pane so the `SessionEnd` hook (see
     # `okstra-trace-cleanup.sh`) can kill it when the caller's Claude
-    # session exits. Scope by caller `$TMUX_PANE` — the pane Claude itself
-    # is attached to — so concurrent Claude instances in the same tmux
+    # session exits. Scope by `$caller_pane` — the pane Claude itself is
+    # attached to — so concurrent Claude instances in the same tmux
     # session do not stomp each other's trace panes.
-    if [[ -n "${TMUX_PANE:-}" ]]; then
+    if [[ -n "$caller_pane" ]]; then
       registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
       mkdir -p "$registry_dir" 2>/dev/null || true
-      safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+      safe_pane="${caller_pane//[^A-Za-z0-9]/_}"
       printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
     fi
   fi

package/runtime/bin/okstra-gemini-exec.sh

@@ -136,19 +136,31 @@ python3 "$script_dir/okstra-wrapper-status.py" \
   init "$status_path" "$(basename "$0")" "$role" "$$" "$started_ts" "$log_path" \
   >>"$log_path" 2>&1 || true
 
+# Resolve caller pane id robustly. See `okstra-codex-exec.sh` for the full
+# rationale — kept in lock-step: tmux normally exports both `$TMUX` and
+# `$TMUX_PANE`, but Claude Code's Bash tool can drop `$TMUX_PANE` while
+# preserving `$TMUX`, which silently skips the caller-pane rename and
+# lets `tmux split-window` attach to whatever tmux considers active.
+caller_pane="${TMUX_PANE:-}"
+if [[ -z "$caller_pane" && -n "${TMUX:-}" ]]; then
+  caller_pane=$(tmux display-message -p '#{pane_id}' 2>/dev/null || true)
+fi
+
 # Pane titles: worker (caller) pane gets `gemini-<role>-<pid>`; the sibling
-# trace pane appends `-trace`. The wrapper PID disambiguates concurrent
-# dispatches of the same role (e.g. two `gemini-worker` panes spawned in
-# parallel) so the operator can match worker ↔ trace at a glance.
+# trace pane appends `-trace[from=<caller-pane-id>]`. The wrapper PID
+# disambiguates concurrent dispatches of the same role; the embedded
+# caller pane id keeps the trace ↔ worker mapping visible even if the
+# worker pane's title is later overwritten by the parent process (e.g.
+# Claude Code's TUI emitting OSC 2 escape sequences on its own pane).
 pane_label="gemini-${role}-$$"
-trace_label="${pane_label}-trace"
+trace_label="${pane_label}-trace[from=${caller_pane:-?}]"
 
 # Capture the caller pane's current title so the EXIT trap can restore it
 # once the wrapper returns. Empty when not in tmux or capture fails — the
 # restore step degrades to a no-op in that case.
 original_caller_title=""
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  original_caller_title=$(tmux display-message -p -t "$TMUX_PANE" '#{pane_title}' 2>/dev/null || true)
+if [[ -n "$caller_pane" ]]; then
+  original_caller_title=$(tmux display-message -p -t "$caller_pane" '#{pane_title}' 2>/dev/null || true)
 fi
 
 _okstra_status_finish() {
@@ -159,40 +171,46 @@ _okstra_status_finish() {
   python3 "$script_dir/okstra-wrapper-status.py" \
     finish "$status_path" "$exit_code" "$ended_ts" "$duration_ms" \
     >>"$log_path" 2>&1 || true
-  if [[ -n "${TMUX_PANE:-}" && -n "$original_caller_title" ]]; then
-    tmux select-pane -t "$TMUX_PANE" -T "$original_caller_title" 2>/dev/null || true
+  if [[ -n "$caller_pane" && -n "$original_caller_title" ]]; then
+    tmux select-pane -t "$caller_pane" -T "$original_caller_title" 2>/dev/null || true
   fi
 }
 trap _okstra_status_finish EXIT
 
 # Label the caller (worker) pane now that the restore trap is armed. Any
 # failure after this point still rewinds the title to its prior value.
-if [[ -n "${TMUX_PANE:-}" ]]; then
-  tmux select-pane -t "$TMUX_PANE" -T "$pane_label" 2>/dev/null || true
+if [[ -n "$caller_pane" ]]; then
+  tmux select-pane -t "$caller_pane" -T "$pane_label" 2>/dev/null || true
 fi
 
 # When a tmux session is reachable, split a sibling pane tailing the log so
 # the operator can watch progress live. This fires in every phase the
 # wrapper is invoked from — long-running gemini dispatches are not
-# implementation-specific. Title `gemini-<role>-<pid>-trace` (matching the
-# caller pane's `gemini-<role>-<pid>` label so worker ↔ trace pairs are
-# greppable). `role` is the optional 5th positional arg (defaults to
-# `worker`); callers that dispatch a different role must pass it
-# explicitly. The `<pid>` suffix is the wrapper's PID and disambiguates
-# concurrent dispatches of the same role. See the codex wrapper for the
-# full design rationale and the silent-degrade failure model.
+# implementation-specific. Title `gemini-<role>-<pid>-trace[from=<caller-pane>]`
+# so the operator can map trace ↔ worker by pane id even when the worker
+# pane title is later overwritten by Claude Code. The split is explicitly
+# anchored to the caller pane to avoid attaching to tmux's idle active
+# pane when `$TMUX_PANE` was missing. `role` is the optional 5th
+# positional arg (defaults to `worker`); callers that dispatch a
+# different role must pass it explicitly. The `<pid>` suffix is the
+# wrapper's PID and disambiguates concurrent dispatches of the same role.
+# See the codex wrapper for the full design rationale and the
+# silent-degrade failure model.
 if [[ -n "${TMUX:-}" ]]; then
-  trace_pane=$(tmux split-window -h -P -F '#{pane_id}' \
-    -c "$(dirname "$log_path")" \
+  split_args=(-h -P -F '#{pane_id}' -c "$(dirname "$log_path")")
+  if [[ -n "$caller_pane" ]]; then
+    split_args+=(-t "$caller_pane")
+  fi
+  trace_pane=$(tmux split-window "${split_args[@]}" \
     "tail -F $(printf '%q' "$log_path")" 2>/dev/null || true)
   if [[ -n "$trace_pane" ]]; then
     tmux select-pane -t "$trace_pane" -T "$trace_label" 2>/dev/null || true
     tmux last-pane 2>/dev/null || true
     # See `okstra-codex-exec.sh` for the registry rationale — kept in lock-step.
-    if [[ -n "${TMUX_PANE:-}" ]]; then
+    if [[ -n "$caller_pane" ]]; then
       registry_dir="${TMPDIR:-/tmp}/okstra-trace-panes"
       mkdir -p "$registry_dir" 2>/dev/null || true
-      safe_pane="${TMUX_PANE//[^A-Za-z0-9]/_}"
+      safe_pane="${caller_pane//[^A-Za-z0-9]/_}"
       printf '%s\n' "$trace_pane" >> "$registry_dir/${safe_pane}.list" 2>/dev/null || true
     fi
   fi

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

@@ -26,8 +26,9 @@ _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.render_final_report import (  # noqa: E402
-    RenderError,
+    FinalReportRenderError,
     render_to_file,
 )
 
@@ -68,6 +69,15 @@ def main(argv: list[str]) -> int:
             "the repo-local copy."
         ),
     )
+    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')."
+        ),
+    )
     parser.add_argument(
         "--force",
         action="store_true",
@@ -88,8 +98,9 @@ def main(argv: list[str]) -> int:
             args.data,
             output,
             template_path=args.template,
+            report_language=args.report_language,
         )
-    except RenderError as exc:
+    except FinalReportRenderError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 1
 

package/runtime/bin/okstra-wrapper-status.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""okstra-wrapper-status.py — heartbeat sidecar writer for codex/gemini wrappers.
+
+The codex/gemini wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`)
+dispatch a long-running CLI under `Bash(run_in_background: true)` and rely on
+`BashOutput` polling for liveness. That polling stream only carries stdout
+plus a binary `running`/`completed` state. Several recovery decisions need
+more — specifically, "did this wrapper start at all, when, and how did it
+finish?" — so the wrappers write a small JSON sidecar at
+`<prompt-path>.status.json` that survives independent of the polling channel.
+
+Consumers:
+
+* `codex-worker` / `gemini-worker` step 8c: read `log_path` to capture a
+  diagnostic tail when `exit_code == 0` but the canonical Result file is
+  absent.
+* Lead: cross-check `started_ts` / `ended_ts` to distinguish "wrapper hung
+  before CLI launched" from "CLI finished but never wrote artifact" when
+  applying the redispatch policy (see okstra-team-contract "Lead Redispatch
+  Policy on Result-Missing").
+
+Failures are deliberately non-fatal for the caller — the wrapper's main
+job is to run the underlying CLI; a missing sidecar must not break that.
+On any error the script prints a one-line diagnostic to stderr and exits 0.
+
+Schema (schemaVersion 1):
+
+    {
+      "schemaVersion": 1,
+      "wrapper": "<basename of caller>",
+      "role":    "<worker|executor|verifier|...>",
+      "pid":     <int — wrapper process pid at init time>,
+      "started_ts": <epoch seconds>,
+      "log_path":   "<absolute path to the wrapper live log>",
+      "stage":      "started" | "exited",
+      "exit_code":   <int, only when stage=exited>,
+      "ended_ts":    <epoch seconds, only when stage=exited>,
+      "duration_ms": <int, only when stage=exited>,
+      "timeout":       <bool, only when killed by idle-watchdog>,
+      "idle_at_ts":    <epoch seconds, only when timeout>,
+      "idle_seconds":  <int, only when timeout>,
+      "terminated_by": "idle-watchdog" (only when timeout)
+    }
+
+CLI:
+
+    okstra-wrapper-status.py init    <status-path> <wrapper> <role> <pid> <started-ts> <log-path>
+    okstra-wrapper-status.py finish  <status-path> <exit-code> <ended-ts> <duration-ms>
+    okstra-wrapper-status.py timeout <status-path> <idle-at-ts> <idle-seconds>
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+
+def warn(msg: str) -> None:
+    print(f"okstra-wrapper-status: {msg}", file=sys.stderr)
+
+
+def atomic_write(path: str, doc: dict) -> None:
+    tmp = path + ".tmp"
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(doc, f, ensure_ascii=False, indent=2)
+        f.write("\n")
+    os.replace(tmp, path)
+
+
+def cmd_init(argv: list[str]) -> None:
+    if len(argv) != 6:
+        warn("init expects: <status-path> <wrapper> <role> <pid> <started-ts> <log-path>")
+        return
+    status_path, wrapper, role, pid, started_ts, log_path = argv
+    doc = {
+        "schemaVersion": 1,
+        "wrapper": wrapper,
+        "role": role,
+        "pid": int(pid),
+        "started_ts": int(started_ts),
+        "log_path": log_path,
+        "stage": "started",
+    }
+    try:
+        atomic_write(status_path, doc)
+    except OSError as exc:
+        warn(f"init: failed to write {status_path}: {exc}")
+
+
+def cmd_finish(argv: list[str]) -> None:
+    if len(argv) != 4:
+        warn("finish expects: <status-path> <exit-code> <ended-ts> <duration-ms>")
+        return
+    status_path, exit_code, ended_ts, duration_ms = argv
+    try:
+        with open(status_path, "r", encoding="utf-8") as f:
+            doc = json.load(f)
+    except FileNotFoundError:
+        warn(f"finish: sidecar absent at {status_path}; skipping")
+        return
+    except (OSError, json.JSONDecodeError) as exc:
+        warn(f"finish: failed to read {status_path}: {exc}")
+        return
+    doc["stage"] = "exited"
+    doc["exit_code"] = int(exit_code)
+    doc["ended_ts"] = int(ended_ts)
+    doc["duration_ms"] = int(duration_ms)
+    try:
+        atomic_write(status_path, doc)
+    except OSError as exc:
+        warn(f"finish: failed to write {status_path}: {exc}")
+
+
+def cmd_timeout(argv: list[str]) -> None:
+    if len(argv) != 3:
+        warn("timeout expects: <status-path> <idle-at-ts> <idle-seconds>")
+        return
+    status_path, idle_at, idle_seconds = argv
+    try:
+        with open(status_path, "r", encoding="utf-8") as f:
+            doc = json.load(f)
+    except FileNotFoundError:
+        warn(f"timeout: sidecar absent at {status_path}; skipping")
+        return
+    except (OSError, json.JSONDecodeError) as exc:
+        warn(f"timeout: failed to read {status_path}: {exc}")
+        return
+    doc["timeout"] = True
+    doc["idle_at_ts"] = int(idle_at)
+    doc["idle_seconds"] = int(idle_seconds)
+    doc["terminated_by"] = "idle-watchdog"
+    try:
+        atomic_write(status_path, doc)
+    except OSError as exc:
+        warn(f"timeout: failed to write {status_path}: {exc}")
+
+
+def main(argv: list[str]) -> int:
+    if len(argv) < 2:
+        warn("missing subcommand (init|finish|timeout)")
+        return 0
+    sub = argv[1]
+    if sub == "init":
+        cmd_init(argv[2:])
+    elif sub == "finish":
+        cmd_finish(argv[2:])
+    elif sub == "timeout":
+        cmd_timeout(argv[2:])
+    else:
+        warn(f"unknown subcommand: {sub}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/runtime/bin/okstra.sh

@@ -68,7 +68,7 @@ if [[ "$ASSUME_YES" != "true" ]] && [[ -t 0 ]] && [[ -t 1 ]]; then
   cat >&2 <<CONFIRM_EOF
 okstra execution summary:
   render only: ${RENDER_ONLY}
-  task type: ${ANALYSIS_TYPE}
+  task type: ${TASK_TYPE}
   project id: ${PROJECT_ID}
   project root: ${PROJECT_ROOT}
   task group: ${TASK_GROUP}
@@ -103,7 +103,7 @@ PY_ARGS=(
   --project-id "$PROJECT_ID"
   --task-group "$TASK_GROUP"
   --task-id "$TASK_ID"
-  --task-type "$ANALYSIS_TYPE"
+  --task-type "$TASK_TYPE"
   --task-brief "$BRIEF_PATH"
 )
 [[ -n "${DIRECTIVE-}" ]] && PY_ARGS+=(--directive "$DIRECTIVE")