okstra 0.17.0 → 0.18.1

package/README.kr.md

@@ -6,7 +6,7 @@
 
 ## 1. 용도
 
-`okstra` 는 **Claude Code 안에서 lead + worker 모델로 작업을 cross-verify 하기 위한 정형화된 task 실행 러너**입니다. Claude lead 가 phase 진행을 주도하고, 독립된 분석 worker 3종 — **Claude · Codex · Gemini** — 와 최종 보고서 작성을 전담하는 report-writer 를 dispatch 합니다.
+`okstra` 는 **Claude Code 안에서 lead + worker 모델로 작업을 cross-verify 하기 위한 정형화된 task 실행 러너**입니다. Claude lead 가 phase 진행을 주도하고, 독립된 분석 worker — **기본 Claude · Codex** (Gemini 는 옵션으로 명시할 때만 추가) — 와 최종 보고서 작성을 전담하는 report-writer 를 dispatch 합니다.
 
 설계의 세 가지 원칙:
 

package/README.md

@@ -6,7 +6,7 @@
 
 ## 1. Purpose
 
-`okstra` is a **structured task-execution runner for Claude Code that cross-verifies work with a lead + worker model**. The Claude lead drives phase progression and dispatches three independent analysis workers — **Claude, Codex, Gemini** — plus a dedicated report-writer for the final synthesis.
+`okstra` is a **structured task-execution runner for Claude Code that cross-verifies work with a lead + worker model**. The Claude lead drives phase progression and dispatches independent analysis workers — **Claude and Codex by default** (with **Gemini** available as an opt-in extra) — plus a dedicated report-writer for the final synthesis.
 
 The design rests on three principles:
 

package/docs/kr/architecture.md

@@ -17,7 +17,7 @@
 - **Run lifecycle**: 매 실행마다 per-run 디렉터리(`runs/<timestamp>/`)에 prompt snapshot, sessions/, expected-state, final report 템플릿, run manifest, timeline 이벤트를 저장합니다.
 - **Single python authority**: 모든 prepare wiring(profile/workers/model 해소, path 계산, 9개 render, central record_start)이 [`okstra_ctl.run.prepare_task_bundle()`](scripts/okstra_ctl/run.py) 한 함수에 모여 있습니다. `okstra.sh` 와 `okstra-run` skill 은 같은 함수를 호출하는 thin caller 이며, 환경 변수로 상태를 전달하지 않습니다 — task 정체성·경로·workflow 상태는 모두 디스크 권위 파일에서 매번 계산됩니다.
 - **Claude handoff (두 모드)**: (a) `okstra.sh` 가 새 `claude` 프로세스를 띄우는 전통 방식, (b) `okstra-run` skill 이 현재 claude 세션 안에서 prepare 후 lead 역할을 그대로 인계받는 in-session 모드. 둘 다 `prepare_task_bundle` 의 산출물(instruction-set 등)을 그대로 사용합니다.
-- **Required team contract**: `Claude lead` + `Claude worker` · `Codex worker` · `Gemini worker` · `Report writer worker`의 필수 구성과 Agent Teams 우선 시도를 강제합니다.
+- **Required team contract**: `Claude lead` + 기본 worker `Claude worker` · `Codex worker` · `Report writer worker` 와 Agent Teams 우선 시도를 강제합니다. `Gemini worker` 는 옵션 워커로, `--workers` 또는 프로필의 `- Workers:` 섹션에 명시할 때만 포함됩니다.
 - **User-home install + project-local task bundles**: `npx okstra@latest install` 한 명령이 런타임(`~/.okstra/{lib/python, bin, templates}`) + 스킬 마크다운(`~/.claude/skills/<name>/SKILL.md`) 을 모두 깐다. 대상 프로젝트에는 task bundle 과 discovery metadata 가 `.project-docs/okstra/` 아래 저장되고, **추가로 `<PROJECT_ROOT>/.claude/settings.local.json` 이 `~/.okstra/templates/settings.local.json` 을 가리키는 symlink 로 provisioning** 됩니다 (`okstra setup` 또는 `okstra-ctl` prepare 가 idempotent 하게 관리; 기존에 일반 파일이 있었다면 `.bak.<timestamp>` 로 백업 후 교체). 이 symlink 가 host Claude Code 세션에 자동 로드되어 codex/gemini worker wrapper 호출 권한을 부여하므로, 사용자의 글로벌 `~/.claude/settings.json` 은 건드리지 않으며 별도 `--settings` CLI 주입도 필요 없습니다. (개발용으로는 `okstra-install.sh` 가 `--link` 모드 symlink 설치를 제공합니다.)
 - **Resume and clarification**: `--task-key`, `--resume-clarification`, `--clarification-response`로 같은 task 재개와 lead의 추가 질문 응답 흐름을 지원합니다.
 - **Optional integrations**: worker error sidecar, token usage / cost accounting을 옵션으로 제공합니다.
@@ -223,7 +223,7 @@ per-process 환경 변수에 task 정체성·경로·workflow 상태를 보관
 
 두 모드 모두 동일한 산출물(task-manifest, run-manifest, timeline, instruction-set, central index 등록) 을 만들며, `okstra-ctl` 의 후속 명령(list / show / rerun / reconcile)은 산출물 차이를 알지 못한 채 일관되게 동작합니다.
 - handoff된 메인 Claude는 `Claude lead`로 동작하며 orchestration과 final synthesis를 담당합니다.
-- standard workflow의 required worker role은 `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`입니다.
+- standard workflow의 기본 worker role은 `Claude worker`, `Codex worker`, `Report writer worker`이며, `Gemini worker`는 `--workers` 또는 프로필에서 명시할 때만 포함되는 옵션입니다.
 - worker 역할 분담과 최종 판단은 Claude가 task bundle을 읽고 수행합니다.
 - 사용자 홈에 설치된 okstra Claude assets(`~/.claude/skills`, `~/.claude/agents`) 는 Agent Teams 를 우선 시도하고, 팀 구성이 불가능할 때만 sequential/background fallback 을 사용하도록 Claude 를 유도합니다.
 
@@ -242,11 +242,11 @@ Claude launch prompt 본문은 항상 `prompts/launch.template.md` 템플릿에
 표준 `okstra` workflow는 아래 팀 계약을 runtime prompt, profile, manifest, skill 문서에 공통으로 반영합니다.
 
 - 메인 Claude는 항상 `Claude lead`이며 synthesis-only로 동작합니다.
-- required worker role은 `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`입니다.
+- 기본 required worker role은 `Claude worker`, `Codex worker`, `Report writer worker`입니다. `Gemini worker`는 옵션 워커로, `--workers` 또는 프로필의 `- Workers:` 섹션에 명시될 때만 required 로 포함됩니다.
 - `Report writer worker`는 보고서 구조화와 근거 정리에 집중하지만 최종 synthesis owner는 여전히 `Claude lead`입니다.
-- 기본 모델 계약은 중앙 기본값에서 계산합니다. 기본 fallback은 `Claude lead`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`이며, `Report writer worker`는 별도 override가 없으면 `Claude lead` 모델을 따릅니다(즉, 기본값에서는 `opus`).
-- `Gemini worker`는 반드시 시도해야 합니다.
-- 최종 판단 전에는 각 required worker role별로 결과 또는 명시적인 terminal status(`completed`, `timeout`, `error`, `not-run`)가 필요합니다.
+- 기본 모델 계약은 중앙 기본값에서 계산합니다. 기본 fallback은 `Claude lead`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`(opt-in 시 적용)이며, `Report writer worker`는 별도 override가 없으면 `Claude lead` 모델을 따릅니다(즉, 기본값에서는 `opus`).
+- `Gemini worker`는 옵션이므로 명시 포함된 run에 한해서만 시도 대상이 됩니다.
+- 최종 판단 전에는 현재 run의 worker roster 에 포함된 각 required role별로 결과 또는 명시적인 terminal status(`completed`, `timeout`, `error`, `not-run`)가 필요합니다.
 - 시도된 worker(`completed`, `timeout`, `error`)는 현재 run의 `prompts/` 아래 assigned worker prompt history file을 반드시 가져야 합니다.
 - 이름 없는 generic parallel worker는 required role 대체 수단으로 허용하지 않습니다.
 
@@ -587,7 +587,7 @@ canonical metadata는 항상 `task-manifest.json`을 기준으로 확인합니
 9. `instruction-set/final-report-template.md`를 읽습니다.
 10. current `manifests/run-manifest-<task-type>-<seq>.json`을 읽습니다.
 11. 필요하면 `history/timeline.json`과 이전 run 결과를 참고합니다.
-12. `Claude lead`로서 required worker `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`를 기준으로 역할을 구성합니다.
+12. `Claude lead`로서 현재 run의 worker roster (기본 `Claude worker`, `Codex worker`, `Report writer worker`; `Gemini worker`는 명시 포함된 경우에만)에 따라 역할을 구성합니다.
 13. 각 selected worker prompt를 assigned worker prompt history path로 현재 run의 `prompts/` 아래에 먼저 저장한 뒤 worker를 dispatch합니다.
 14. 각 required worker에 대해 결과 또는 terminal status를 수집합니다.
 15. brief이 더 구체적인 형식을 강제하지 않으면 `final-report-template.md` 구조로 Markdown 최종 보고서를 작성합니다.
@@ -850,7 +850,7 @@ Claude가 작성하는 최종 보고서는 brief에 더 구체적인 형식이
 - 현재 run 세션의 resume helper는 `runs/<task-type>/sessions/claude-resume-<task-type>-<seq>.sh`에 생성됩니다.
 - run directory 내부는 `manifests/`, `state/`, `prompts/`, `reports/`, `status/`, `sessions/`, `worker-results/`처럼 유형별 하위 폴더로 구성되고, prompt snapshot은 `prompts/` 아래에 먼저 준비됩니다.
 - worker 생성과 결과 취합은 Claude가 수행합니다.
-- standard workflow는 `Claude lead` + required worker `Claude worker`, `Codex worker`, `Gemini worker`, `Report writer worker`를 사용합니다.
+- standard workflow는 `Claude lead` + 기본 worker `Claude worker`, `Codex worker`, `Report writer worker`를 사용하고, `Gemini worker`는 명시할 때만 포함되는 옵션입니다.
 - worker 모델은 `--lead-model`, `--claude-model`, `--codex-model`, `--gemini-model`, `--report-writer-model`로 override할 수 있고, 기본값은 `OKSTRA_DEFAULT_*` 환경 변수에서 중앙 관리합니다. fallback 기본값은 `Claude lead`/`Report writer worker`=`opus`, `Claude worker`=`sonnet`, `Codex worker`=`gpt-5.5`, `Gemini worker`=`auto`입니다.
 - `--task-type implementation` 에서는 Executor 역할을 맡을 provider 를 `--executor <claude|codex|gemini>` (또는 `OKSTRA_DEFAULT_EXECUTOR`, fallback `claude`) 로 선택합니다. Executor 만 프로젝트 파일을 mutate 할 수 있고, 나머지 두 provider 와 자기 자신의 provider 가 모두 별도 CLI 세션으로 verifier 로 dispatch 됩니다 (세션 분리만으로도 self-review 안전장치 유지). Executor 의 모델은 선택된 provider 의 worker 모델 플래그(`--claude-model` / `--codex-model` / `--gemini-model`) 를 그대로 재사용하며, run-manifest 의 `teamContract.executor` 블록에 provider / displayName / workerAgent / model 이 기록됩니다.
 - Executor 별 worktree cwd 주입: codex / gemini executor 는 wrapper(`okstra-codex-exec.sh -C` / `okstra-gemini-exec.sh --include-directories`) 가 CLI layer 에서 cwd 를 worktree 로 고정합니다. Claude executor 는 Bash tool 에 per-call cwd 인자가 없어 cwd 민감 toolchain (`cargo`/`npm`/`pnpm`/`bun`/`pytest`/`make`/`go`) 호출을 같은 Bash invocation 안에서 `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>` 로 prefix 합니다 — `bash -lc`/`bash -c` 래핑은 금지되며 (`cd` leading token 이 가려져 permission auto-allow 우회 실패), 작업 디렉터리 플래그 (`git -C`, `cargo --manifest-path` 등) 가 있으면 그것을 우선합니다. 자세한 규약은 `prompts/profiles/implementation.md` 의 *Executor Worktree* 블록과 `agents/workers/claude-worker.md` 의 Executor exception 항목 참고.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.17.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.17.0",
-  "builtAt": "2026-05-13T10:55:45.579Z",
+  "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/python/okstra_ctl/workers.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 from pathlib import Path
 
 ALLOWED_WORKERS = ["claude", "codex", "gemini", "report-writer"]
+DEFAULT_WORKERS = ["claude", "codex", "report-writer"]
 PROFILE_BULLET_HEADERS = {
     "- Workers:",
     "- Required workers:",
@@ -51,11 +52,11 @@ def normalize_workers(value: str) -> list[str]:
     """CSV 입력을 정규화한다.
 
     - 공백 strip, 소문자화, 중복 제거(첫 출현 우선).
-    - 빈 입력이면 `ALLOWED_WORKERS` 전체를 default 로 사용.
+    - 빈 입력이면 `DEFAULT_WORKERS` 를 default 로 사용 (gemini 제외).
     - 허용 외 worker 가 포함되면 `WorkersError`.
     """
     items = [v.strip().lower() for v in (value or "").split(",") if v.strip()]
-    source = items or ALLOWED_WORKERS
+    source = items or DEFAULT_WORKERS
     unknown = [v for v in source if v not in ALLOWED_WORKERS]
     if unknown:
         raise WorkersError(f"unknown workers: {','.join(unknown)}")

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: