okstra 0.18.0 → 0.18.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.18.0",
+  "version": "0.18.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.18.0",
-  "builtAt": "2026-05-13T11:17:29.529Z",
+  "package": "0.18.1",
+  "builtAt": "2026-05-13T13:27:26.867Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/SKILL.md

@@ -175,12 +175,21 @@ Spawn **analysis workers only** in the same turn (Phase 4 in Teams mode; Phase 5
 
 The no-`team_name` fallback (Phase 5) is only legal when team-state's `teamCreate.status` is `"error"` for this run. If `teamCreate` is missing or `attempted: false`, the correct action when an Agent dispatch is rejected for a missing team is to GO BACK to Phase 3 and call `TeamCreate` — never to strip `team_name` and continue.
 
-After each worker terminates (any terminal status), if a worker errors sidecar exists at `runs/.../worker-results/<role-slug>-errors.json`, dump it to the run error log:
+### Errors log path wiring (BLOCKING)
+
+The launch prompt's `## Run Logs (error-log wiring)` section gives Lead the resolved absolute paths for the run-level errors log and every per-worker sidecar. When Lead constructs each worker's dispatch prompt body, Lead MUST inject the matching two header lines verbatim:
+
+- `**Errors log path:** <absolute run-level errors log path from launch prompt>`
+- `**Errors sidecar path:** <absolute per-worker sidecar path matching the dispatched worker>`
+
+Workers are contractually required to extract these two lines and abort with `<WORKER>_ERRORS_PATH_MISSING` if either is absent (see each worker definition's "Path extraction (BLOCKING)" block). Omitting these headers reproduces the historical bug class where every run's `errors-<task-type>-<seq>.jsonl` stayed empty because workers had only template placeholders to work from.
+
+After each worker terminates (any terminal status), if its errors sidecar exists, dump it to the run error log using the same resolved paths from the launch prompt:
 
 ```bash
 python3 scripts/okstra-error-log.py append-from-worker \
-  --sidecar <sidecar> \
-  --out <runDir>/logs/errors-<task-type>-<seq>.jsonl \
+  --sidecar <absolute-sidecar-path-from-launch-prompt> \
+  --out <absolute-errors-log-path-from-launch-prompt> \
   --task-key <taskKey> --agent <agent> --agent-role <role> --model <model>
 ```
 

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

@@ -92,13 +92,15 @@ If you find yourself thinking "let me double-check section 3" or "I should read
 
 This agent is responsible for recording its own tool failures via `scripts/okstra-error-log.py`:
 
-**Tool failure (worker-reported)** — if `Write` of the prompt history file, `mkdir`, any MCP call, or any other pre-/in-analysis tool call fails (non-zero exit, exception, or empty result where data was required), append a `tool-failure` entry to the worker errors sidecar at:
+**Path extraction (BLOCKING).** Before recording anything, extract the absolute sidecar path from the lead's dispatch prompt body:
 
-```
-runs/<task-type>/worker-results/claude-worker-errors-<task-type>-<seq>.json
-```
+- `**Errors sidecar path:** <abs-path>` — this worker's per-run sidecar JSON.
 
-The sidecar follows the schema in `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). If the file does not exist, create it with `{"schemaVersion": 1, "errors": []}` then append. Lead will dump it to the run error log after this subagent terminates.
+If the header line is absent from the dispatch prompt, return `CLAUDE_WORKER_ERRORS_PATH_MISSING: lead prompt did not include **Errors sidecar path:** header` without proceeding. Do NOT synthesize the path from `runs/<task-type>/...` — that template syntax is documentation only and historically led to silent log loss.
+
+**Tool failure (worker-reported)** — if `Write` of the prompt history file, `mkdir`, any MCP call, or any other pre-/in-analysis tool call fails (non-zero exit, exception, or empty result where data was required), append a `tool-failure` entry to the worker errors sidecar at the absolute path extracted from the `**Errors sidecar path:**` header. If the file does not exist, create it with `{"schemaVersion": 1, "errors": []}` then append.
+
+The sidecar follows the schema in `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). Lead will dump it to the run error log after this subagent terminates.
 
 There is NO `cli-failure` category for this worker — Claude worker has no external CLI to invoke. Treat MCP errors and Bash errors uniformly as `tool-failure`.
 

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

@@ -148,19 +148,26 @@ This contract mirrors the `okstra-team-contract` skill's Worker Output Contract
 The wrapper agent (this Codex worker subagent) is responsible for recording
 two kinds of errors via `scripts/okstra-error-log.py`:
 
-1. **Wrapper-internal tool failure (worker-reported)** — if `Write` of the
-   prompt history file, `mkdir`, or any pre-CLI tool call fails, append a
-   `tool-failure` entry to the worker errors sidecar at:
+**Path extraction (BLOCKING).** Before recording anything, extract the
+following two absolute paths verbatim from the lead's dispatch prompt body:
 
-   ```
-   runs/<task-type>/worker-results/codex-worker-errors-<task-type>-<seq>.json
-   ```
+- `**Errors log path:** <abs-path>` — the run-level errors JSONL.
+- `**Errors sidecar path:** <abs-path>` — this worker's per-run sidecar JSON.
 
-   The sidecar follows the schema in
-   `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). If the
-   file does not exist, create it with `{"schemaVersion": 1, "errors": []}`
-   then append. Lead will dump it to the run error log after this subagent
-   terminates.
+If either header line is absent from the dispatch prompt, return
+`CODEX_ERRORS_PATH_MISSING: lead prompt did not include **Errors log path:** / **Errors sidecar path:** headers`
+without proceeding. Do NOT synthesize the path from `<runDir>/logs/...` —
+historical bug class: workers writing to a literally-named template path
+and the run-level error log staying empty.
+
+1. **Wrapper-internal tool failure (worker-reported)** — if `Write` of the
+   prompt history file, `mkdir`, or any pre-CLI tool call fails, append a
+   `tool-failure` entry to the worker errors sidecar at the absolute path
+   extracted from the `**Errors sidecar path:**` header. If the file does
+   not exist, create it with `{"schemaVersion": 1, "errors": []}` then
+   append. The sidecar follows the schema in
+   `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). Lead
+   will dump it to the run error log after this subagent terminates.
 
 2. **CLI failure (lead-observed)** — if the wrapper's final `BashOutput`
    reports a non-zero `exit_code`, the 30-minute polling cap is hit, or the
@@ -171,7 +178,7 @@ two kinds of errors via `scripts/okstra-error-log.py`:
 
    ```bash
    python3 scripts/okstra-error-log.py append-observed \
-     --out "<runDir>/logs/errors-<task-type>-<seq>.jsonl" \
+     --out "<absolute-errors-log-path-from-lead-prompt>" \
      --task-key "<task-key>" \
      --phase "<phase>" \
      --agent codex-worker --agent-role worker \
@@ -184,10 +191,10 @@ two kinds of errors via `scripts/okstra-error-log.py`:
      --stderr-excerpt-file "<captured-stderr-path or omit>"
    ```
 
-   The lead prompt provides `<runDir>`, `<task-key>`, and `<phase>` alongside
-   the prompt history path. If any of these are missing, fall back to logging
-   to the worker errors sidecar instead — never silently swallow a CLI
-   failure.
+   The lead prompt provides `**Errors log path:**`, `<task-key>`, and
+   `<phase>` alongside the prompt history path. If any of these are
+   missing, fall back to logging to the worker errors sidecar instead —
+   never silently swallow a CLI failure.
 
 Do not record a `cli-failure` for `CODEX_NOT_INSTALLED` returns — that is a
 pre-flight terminal status, not a runtime CLI error.

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

@@ -148,19 +148,26 @@ This contract mirrors the `okstra-team-contract` skill's Worker Output Contract
 The wrapper agent (this Gemini worker subagent) is responsible for recording
 two kinds of errors via `scripts/okstra-error-log.py`:
 
-1. **Wrapper-internal tool failure (worker-reported)** — if `Write` of the
-   prompt history file, `mkdir`, or any pre-CLI tool call fails, append a
-   `tool-failure` entry to the worker errors sidecar at:
+**Path extraction (BLOCKING).** Before recording anything, extract the
+following two absolute paths verbatim from the lead's dispatch prompt body:
 
-   ```
-   runs/<task-type>/worker-results/gemini-worker-errors-<task-type>-<seq>.json
-   ```
+- `**Errors log path:** <abs-path>` — the run-level errors JSONL.
+- `**Errors sidecar path:** <abs-path>` — this worker's per-run sidecar JSON.
 
-   The sidecar follows the schema in
-   `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). If the
-   file does not exist, create it with `{"schemaVersion": 1, "errors": []}`
-   then append. Lead will dump it to the run error log after this subagent
-   terminates.
+If either header line is absent from the dispatch prompt, return
+`GEMINI_ERRORS_PATH_MISSING: lead prompt did not include **Errors log path:** / **Errors sidecar path:** headers`
+without proceeding. Do NOT synthesize the path from `<runDir>/logs/...` —
+historical bug class: workers writing to a literally-named template path
+and the run-level error log staying empty.
+
+1. **Wrapper-internal tool failure (worker-reported)** — if `Write` of the
+   prompt history file, `mkdir`, or any pre-CLI tool call fails, append a
+   `tool-failure` entry to the worker errors sidecar at the absolute path
+   extracted from the `**Errors sidecar path:**` header. If the file does
+   not exist, create it with `{"schemaVersion": 1, "errors": []}` then
+   append. The sidecar follows the schema in
+   `skills/okstra-team-contract/SKILL.md` (Optional errors sidecar). Lead
+   will dump it to the run error log after this subagent terminates.
 
 2. **CLI failure (lead-observed)** — if the wrapper's final `BashOutput`
    reports a non-zero `exit_code`, the 30-minute polling cap is hit, or the
@@ -171,7 +178,7 @@ two kinds of errors via `scripts/okstra-error-log.py`:
 
    ```bash
    python3 scripts/okstra-error-log.py append-observed \
-     --out "<runDir>/logs/errors-<task-type>-<seq>.jsonl" \
+     --out "<absolute-errors-log-path-from-lead-prompt>" \
      --task-key "<task-key>" \
      --phase "<phase>" \
      --agent gemini-worker --agent-role worker \
@@ -184,10 +191,10 @@ two kinds of errors via `scripts/okstra-error-log.py`:
      --stderr-excerpt-file "<captured-stderr-path or omit>"
    ```
 
-   The lead prompt provides `<runDir>`, `<task-key>`, and `<phase>` alongside
-   the prompt history path. If any of these are missing, fall back to logging
-   to the worker errors sidecar instead — never silently swallow a CLI
-   failure.
+   The lead prompt provides `**Errors log path:**`, `<task-key>`, and
+   `<phase>` alongside the prompt history path. If any of these are
+   missing, fall back to logging to the worker errors sidecar instead —
+   never silently swallow a CLI failure.
 
 Do not record a `cli-failure` for `GEMINI_NOT_INSTALLED` returns — that is a
 pre-flight terminal status, not a runtime CLI error.

package/runtime/prompts/launch.template.md

@@ -46,6 +46,21 @@ Invoke the `okstra` skill now. Read the manifests below for all task metadata, p
 - Final status: `{{FINAL_STATUS_RELATIVE_PATH}}`
 - Validator: `{{RUN_VALIDATOR_RELATIVE_PATH}}`
 
+## Run Logs (error-log wiring)
+
+- Run-level errors log (absolute): `{{RUN_ERRORS_LOG_PATH}}`
+- Run-level errors log (relative): `{{RUN_ERRORS_LOG_RELATIVE_PATH}}`
+- Worker error sidecars (absolute):
+  - Claude worker: `{{CLAUDE_WORKER_ERRORS_SIDECAR_PATH}}`
+  - Codex worker: `{{CODEX_WORKER_ERRORS_SIDECAR_PATH}}`
+  - Gemini worker: `{{GEMINI_WORKER_ERRORS_SIDECAR_PATH}}`
+  - Report writer worker: `{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH}}`
+- When dispatching any worker you MUST inject **two header lines** into the dispatch prompt body so the worker subagent can record errors without guessing paths:
+  - `**Errors log path:** <absolute run-level errors log path>`
+  - `**Errors sidecar path:** <absolute per-worker sidecar path matching the dispatched worker>`
+- These lines are the canonical contract — worker subagents extract them verbatim and pass them to `okstra-error-log.py append-observed --out ...` (run-level cli-failure / contract-violation events) and to their internal sidecar writes (worker-reported tool-failure events) respectively.
+- After each worker terminates, dump its sidecar into the run-level errors log via `python3 scripts/okstra-error-log.py append-from-worker --sidecar <sidecar-path> --out <run-errors-log-path> --task-key {{TASK_KEY}} --agent <worker-id> --agent-role worker --model <assigned-model-execution-value>` (per `okstra-team-contract` Worker Output Contract).
+
 ## Executor Worktree
 
 - Status: `{{EXECUTOR_WORKTREE_STATUS}}`

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

@@ -4,8 +4,9 @@
 - Required workers:
   - claude
   - codex
-  - gemini
   - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - symptom and trigger clarification

package/runtime/prompts/profiles/final-verification.md

@@ -4,8 +4,9 @@
 - Required workers:
   - claude
   - codex
-  - gemini
   - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - requirement coverage

package/runtime/prompts/profiles/implementation-planning.md

@@ -4,8 +4,9 @@
 - Required workers:
   - claude
   - codex
-  - gemini
   - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
 - Pre-planning context exploration (mandatory before option drafting):
   - read the task brief, related-task briefs, and any cited spec / design doc end-to-end

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

@@ -4,8 +4,9 @@
 - Required workers:
   - claude
   - codex
-  - gemini
   - report-writer
+- Optional workers (opt-in via `--workers`):
+  - gemini — when added to the roster it joins the analyser set; omitted by default
 {{INCLUDE:_common-contract.md}}
 - Primary focus areas:
   - classify the work as bugfix, feature, improvement, refactor, or ops-change

package/runtime/python/okstra_ctl/paths.py

@@ -143,6 +143,12 @@ def compute_run_paths(
     gemini_worker_result = worker_results / f"gemini-worker{suffixes['worker_results']}.md"
     report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
 
+    run_errors_log = run_logs / f"errors-{task_type_segment}-{seqs['state']}.jsonl"
+    claude_worker_errors_sidecar = worker_results / f"claude-worker-errors{suffixes['worker_results']}.json"
+    codex_worker_errors_sidecar = worker_results / f"codex-worker-errors{suffixes['worker_results']}.json"
+    gemini_worker_errors_sidecar = worker_results / f"gemini-worker-errors{suffixes['worker_results']}.json"
+    report_writer_worker_errors_sidecar = worker_results / f"report-writer-worker-errors{suffixes['worker_results']}.json"
+
     run_validator_script = workspace_root / "validators" / "validate-run.py"
 
     abs_paths = {
@@ -193,6 +199,11 @@ def compute_run_paths(
         "CODEX_WORKER_RESULT_FILE": str(codex_worker_result),
         "GEMINI_WORKER_RESULT_FILE": str(gemini_worker_result),
         "REPORT_WRITER_WORKER_RESULT_FILE": str(report_writer_worker_result),
+        "RUN_ERRORS_LOG_FILE": str(run_errors_log),
+        "CLAUDE_WORKER_ERRORS_SIDECAR_FILE": str(claude_worker_errors_sidecar),
+        "CODEX_WORKER_ERRORS_SIDECAR_FILE": str(codex_worker_errors_sidecar),
+        "GEMINI_WORKER_ERRORS_SIDECAR_FILE": str(gemini_worker_errors_sidecar),
+        "REPORT_WRITER_WORKER_ERRORS_SIDECAR_FILE": str(report_writer_worker_errors_sidecar),
         "RUN_VALIDATOR_SCRIPT": str(run_validator_script),
         "RUN_MANIFEST_FILENAME": run_manifest_file.name,
         "RUN_PROMPT_SNAPSHOT_FILENAME": run_prompt_snapshot.name,
@@ -245,6 +256,11 @@ def compute_run_paths(
         ("CODEX_WORKER_RESULT_RELATIVE_PATH", codex_worker_result),
         ("GEMINI_WORKER_RESULT_RELATIVE_PATH", gemini_worker_result),
         ("REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH", report_writer_worker_result),
+        ("RUN_ERRORS_LOG_RELATIVE_PATH", run_errors_log),
+        ("CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", claude_worker_errors_sidecar),
+        ("CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", codex_worker_errors_sidecar),
+        ("GEMINI_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", gemini_worker_errors_sidecar),
+        ("REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", report_writer_worker_errors_sidecar),
         ("LATEST_RUN_RELATIVE_PATH", run_dir),
     ]
     rel_paths = {key: _rel(project_root, target) for key, target in rel_pairs}

package/runtime/python/okstra_ctl/render.py

@@ -1078,6 +1078,16 @@ def render_template_file(template_path: str, output_path: str, ctx: dict) -> Non
         "{{CODEX_WORKER_RESULT_RELATIVE_PATH}}": ctx.get("CODEX_WORKER_RESULT_RELATIVE_PATH", ""),
         "{{GEMINI_WORKER_RESULT_RELATIVE_PATH}}": ctx.get("GEMINI_WORKER_RESULT_RELATIVE_PATH", ""),
         "{{REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH}}": ctx.get("REPORT_WRITER_WORKER_RESULT_RELATIVE_PATH", ""),
+        "{{RUN_ERRORS_LOG_PATH}}": ctx.get("RUN_ERRORS_LOG_FILE", ""),
+        "{{RUN_ERRORS_LOG_RELATIVE_PATH}}": ctx.get("RUN_ERRORS_LOG_RELATIVE_PATH", ""),
+        "{{CLAUDE_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get("CLAUDE_WORKER_ERRORS_SIDECAR_FILE", ""),
+        "{{CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get("CLAUDE_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+        "{{CODEX_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get("CODEX_WORKER_ERRORS_SIDECAR_FILE", ""),
+        "{{CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get("CODEX_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+        "{{GEMINI_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get("GEMINI_WORKER_ERRORS_SIDECAR_FILE", ""),
+        "{{GEMINI_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get("GEMINI_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
+        "{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH}}": ctx.get("REPORT_WRITER_WORKER_ERRORS_SIDECAR_FILE", ""),
+        "{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH}}": ctx.get("REPORT_WRITER_WORKER_ERRORS_SIDECAR_RELATIVE_PATH", ""),
         "{{LEAD_MODEL}}": lead_model,
         "{{LEAD_MODEL_EXECUTION_VALUE}}": lead_model_execution,
         "{{CLAUDE_WORKER_MODEL}}": ctx.get("CLAUDE_WORKER_MODEL_DISPLAY", ""),

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -263,12 +263,27 @@ Schema:
 ```
 
 Workers MUST omit `source` / `recordedAt` / `agent` / `agentRole` / `model` /
-`taskKey`. Claude lead fills those in when dumping the sidecar to
-`runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl` via
-`scripts/okstra-error-log.py append-from-worker`.
+`taskKey`. Claude lead fills those in when dumping the sidecar to the
+run-level errors log (`runs/<task-type>/logs/errors-<task-type>-<seq>.jsonl`)
+via `scripts/okstra-error-log.py append-from-worker`.
 
 Workers MUST use only `errorType: "tool-failure"` in the **sidecar file**.
 
+**Path delivery contract (BLOCKING).** Workers do NOT synthesize the
+run-level errors log path or their sidecar path from the
+`runs/<task-type>/...` template syntax. Both absolute paths are delivered
+by Lead via two dispatch-prompt header lines:
+
+- `**Errors log path:** <absolute path>` — run-level JSONL (`okstra-error-log.py append-observed --out ...`)
+- `**Errors sidecar path:** <absolute path>` — per-worker JSON (`{ "schemaVersion": 1, "errors": [...] }`)
+
+Lead obtains both paths from the launch prompt's `## Run Logs (error-log
+wiring)` section (resolved by the okstra runtime via `paths.py`). If Lead
+omits either header, the worker MUST return `<WORKER>_ERRORS_PATH_MISSING`
+without proceeding — this is the contractual replacement for the previous
+"derive from template placeholders" behavior, which silently produced
+empty run-level error logs in production.
+
 - `cli-failure` events are recorded by the wrapper subagent itself (Codex / Gemini), but **directly to the run-level error log** via `okstra-error-log.py append-observed --error-type cli-failure ...` — NOT via the sidecar. The sidecar is an in-process tool-failure channel only.
 - **Wrapper invocation arity.** Both `okstra-codex-exec.sh` and `okstra-gemini-exec.sh` accept four positional arguments: `<project-root> <model> <prompt-path> [<worktree-path>]`. The fourth (worktree) argument is **mandatory for implementation phase** and optional otherwise. For codex it becomes `--add-dir <worktree>` (sandbox write access); for gemini it is appended to `--include-directories`. Omitting it during implementation causes the codex sandbox to reject every Edit/Write targeting the worktree with EPERM. Workers extract the path from the `**Worktree:**` / `EXECUTOR_WORKTREE_PATH` / `cwd for every mutating command:` line in the lead prompt.
 - **Background dispatch + polling contract (Codex / Gemini wrappers).** Both wrapper subagents MUST dispatch `okstra-codex-exec.sh` / `okstra-gemini-exec.sh` via `Bash(run_in_background: true)` and poll with `BashOutput(bash_id)` on a 60-second cadence, capped at 30 minutes (1800s). The legacy "single foreground `Bash` with 120000ms timeout" rule is retired — it forced workers into ad-hoc background dispatch that lost stdout and silently broke Phase 5 synthesis. The new rule applies in **every phase** (analysis runs typically complete in 1–2 polls, so there is no regression for short jobs). Recording responsibilities: