okstra 0.102.2 → 0.102.4

package/docs/superpowers/specs/2026-06-13-forbidden-actions-ssot-design.md

@@ -1,134 +0,0 @@
-# Forbidden-Actions SSOT Design (P2-2)
-
-**Goal:** Eliminate the drift between the two places per-phase *forbidden actions* are authored, by making one JSON file the single source of truth (SSOT) from which both the launch-prompt boundary and the profile body derive.
-
-**Scope:** `forbidden` only. `allowed`, required-workers, and profile `Purpose`/`Non-goals` are explicitly out of scope (user decision; see Non-goals).
-
-**Format:** JSON data file (no YAML — the repo deliberately ships no YAML parser; `scripts/okstra_ctl/wizard.py:128` hand-parses frontmatter "no yaml dep", CLAUDE.md "stdlib first"). User-confirmed.
-
----
-
-## 1. Current state (verified)
-
-Per-phase forbidden actions are authored in **two** places and injected into the lead from **two** surfaces in a single run:
-
-- **Python literal** — [`scripts/okstra_ctl/workflow.py:36`](../../../scripts/okstra_ctl/workflow.py) `PHASE_RULES[<phase>]["forbidden"]`, a `"  - item\n"`-joined string. `compute_workflow_state` ([workflow.py:233](../../../scripts/okstra_ctl/workflow.py)) emits it as `PHASE_FORBIDDEN_ACTIONS`, injected into [`prompts/launch.template.md:16`](../../../prompts/launch.template.md) "Current Phase Boundary".
-- **Profile prose** — `prompts/profiles/<phase>.md`. The full profile body is rendered into `analysis-profile.md` ([run.py:1812](../../../scripts/okstra_ctl/run.py)) and read by the lead.
-
-Crucially, only **2 of 7** profiles carry a `Forbidden actions` block that duplicates `PHASE_RULES`:
-
-| task type | profile forbidden block? | PHASE_RULES.forbidden? | duplicated? |
-|---|---|---|---|
-| requirements-discovery | no (`Non-goals` only, [requirements-discovery.md:57](../../../prompts/profiles/requirements-discovery.md)) | yes | no |
-| improvement-discovery | no (`Non-goals` only) | yes | no |
-| error-analysis | no (`Non-goals` only) | yes | no |
-| implementation-planning | no (`Non-goals` only) | yes | no |
-| **implementation** | **yes** ([implementation.md:34](../../../prompts/profiles/implementation.md), 8 items) | yes (13 items) | **yes, divergent** |
-| final-verification | no (`Non-goals` only) | yes | no |
-| **release-handoff** | **yes** ([release-handoff.md:62](../../../prompts/profiles/release-handoff.md), 15 items) | yes (11 items) | **yes, divergent** |
-
-`Non-goals` is a *distinct concept* (scope guidance) from `Forbidden actions` (`contract-violated` safety rules). It is **not** consolidated by this work.
-
-So the drift-prone duplication is exactly **implementation** and **release-handoff**, where the profile block and `PHASE_RULES` have diverged (different item counts, wording, ordering) with no test guarding them.
-
----
-
-## 2. Design
-
-### 2.1 SSOT file
-
-Create `prompts/profiles/forbidden-actions.json`:
-
-```json
-{
-  "requirements-discovery": ["...", "..."],
-  "improvement-discovery": ["..."],
-  "error-analysis": ["..."],
-  "implementation-planning": ["..."],
-  "implementation": ["..."],
-  "final-verification": ["..."],
-  "release-handoff": ["..."],
-  "unknown": ["..."]
-}
-```
-
-- Each value is the ordered list of forbidden-action items (one string per current `  - ` bullet, **without** the leading `  - `).
-- `unknown` mirrors `PHASE_RULES_UNKNOWN["forbidden"]`.
-- Lives under `prompts/profiles/` so it resolves the same way the profile `.md` files do (`workspace_root / "prompts" / "profiles" / ...`, [run.py:1073](../../../scripts/okstra_ctl/run.py)) and is synced into `runtime/` by `tools/build.mjs` (prompts/ is a build source).
-
-### 2.2 Rendering & injection
-
-In `workflow.py`:
-
-- `def load_phase_forbidden(workspace_root: Path) -> dict[str, str]` — explicit IO: `json.load` the file, render each phase's list to the existing `"  - item\n"` string shape via a pure helper `render_forbidden(items: list[str]) -> str`. Raise `FileNotFoundError`/`PrepareError`-style if missing (fail loud, no silent stale fallback).
-- `compute_workflow_state(..., forbidden_by_phase: dict[str, str])` — new **required** keyword arg; `PHASE_FORBIDDEN_ACTIONS = forbidden_by_phase.get(task_type, forbidden_by_phase["unknown"])`.
-- **Delete** the `"forbidden"` key from every `PHASE_RULES` entry and from `PHASE_RULES_UNKNOWN`. `PHASE_RULES` keeps `"allowed"` only.
-
-In `run.py` (the only two `compute_workflow_state` call sites, [run.py:2012](../../../scripts/okstra_ctl/run.py), [run.py:2232](../../../scripts/okstra_ctl/run.py)):
-
-- Load `forbidden_by_phase = workflow.load_phase_forbidden(workspace_root)` once (where `workspace_root` is already resolved for the profile file) and pass it to both calls.
-- In `_write_instruction_set_sources` ([run.py:1798](../../../scripts/okstra_ctl/run.py)), add `{{PHASE_FORBIDDEN_ACTIONS}}` to the placeholder substitution applied to `profile_rendered`, using the rendered string for `inp.task_type`.
-
-### 2.3 Profile body changes (only impl + release-handoff)
-
-- [implementation.md:34-42](../../../prompts/profiles/implementation.md): keep the header line `- Forbidden actions — universal (any occurrence → terminal status \`contract-violated\`):`, replace the 8 hand-written bullets with the single token `{{PHASE_FORBIDDEN_ACTIONS}}`.
-- [release-handoff.md:62-77](../../../prompts/profiles/release-handoff.md): keep the header line `- Forbidden actions (any occurrence → terminal status \`contract-violated\`):`, replace the 15 hand-written bullets (incl. the nested push-variant sub-list) with `{{PHASE_FORBIDDEN_ACTIONS}}`.
-- The other 5 profiles are **untouched** (their `Non-goals` blocks stay; they have no forbidden duplication).
-
-### 2.4 Canonical content (reconciliation)
-
-For the 5 non-duplicated phases, the JSON list = current `PHASE_RULES.forbidden`, **verbatim** (launch injection byte-identical, nothing else references it).
-
-For the 2 duplicated phases the JSON list = the **union** (lose no rule from either source):
-
-- **implementation** = `PHASE_RULES["implementation"]["forbidden"]` (13 items, the near-superset) with the profile's `git push ... --dry-run` nuance folded into the publish/push item. Every profile item maps into a PHASE_RULES item (git push, publish, DB, infra, API-write, sub-agents, Edit/Write-before-gate, verifier-read-only).
-- **release-handoff** = the profile's detailed 15-item list ([release-handoff.md:62-77](../../../prompts/profiles/release-handoff.md), the superset: explicit `--force`/`--force-with-lease`/`-f`/`+refspec`, base-branch push, `--no-verify`, `gh release create`/`edit` + `twine upload` + publish set, source edits, unselected command, weaker-flag retry, `TeamCreate`/`Agent` ban, unrecognised-reply). All `PHASE_RULES` release-handoff items are already covered by it.
-
-### 2.5 Disclosed behavior changes
-
-Nothing is lost; one surface becomes *more complete* for the 2 phases:
-
-- **implementation**: profile body forbidden grows 8 → 13 items (now equals the launch boundary). Launch injection ≈ unchanged.
-- **release-handoff**: launch boundary forbidden grows 11 → 15 items (now equals the detailed profile list). Profile body ≈ unchanged.
-
-All other phases: byte-identical on both surfaces.
-
----
-
-## 3. Tests (TDD)
-
-- `tests/test_phase_forbidden_ssot.py`:
-  - `load_phase_forbidden` covers every key in `PHASE_RULES` + `unknown` (no phase missing; no extra phase).
-  - `render_forbidden(["a","b"]) == "  - a\n  - b"` (exact shape match for injection).
-  - `compute_workflow_state(..., forbidden_by_phase=load_phase_forbidden(repo_root))` emits `PHASE_FORBIDDEN_ACTIONS` equal to the rendered JSON for a sample phase.
-  - `PHASE_RULES` no longer contains a `"forbidden"` key (regression guard against re-introducing the duplicate).
-- `tests/test_profile_forbidden_placeholder.py` (or extend an existing profile/prompt-metadata test):
-  - `implementation.md` and `release-handoff.md` contain `{{PHASE_FORBIDDEN_ACTIONS}}` and **no** hand-written bullet under the `Forbidden actions` header.
-  - the 5 other profiles contain neither a `Forbidden actions` block nor the placeholder (untouched).
-- Existing suite must stay green, especially `tests/test_workflow_phase_sequence.py` (update its `compute_workflow_state` calls to pass `forbidden_by_phase`), `validators/validate-workflow.sh`, and the launch-template render tests.
-
----
-
-## 4. Non-goals
-
-- `allowed` outputs consolidation — left as-is, including the `release-handoff.md:54` "Allowed actions" block that also overlaps `PHASE_RULES` allowed. (Possible future P2-2b.)
-- Required/optional workers, `Purpose`, `Non-goals` — untouched (different parsers, no forbidden drift).
-- The 5 non-duplicated profiles' `Non-goals` prose — untouched.
-- No new third-party dependency (JSON via stdlib).
-- `runtime/` is never hand-edited; `npm run build` syncs the new JSON.
-
----
-
-## 5. File summary
-
-| File | Change |
-|---|---|
-| `prompts/profiles/forbidden-actions.json` | **create** — the SSOT (7 phases + `unknown`) |
-| `scripts/okstra_ctl/workflow.py` | add `render_forbidden`, `load_phase_forbidden`; `compute_workflow_state` takes `forbidden_by_phase`; delete `PHASE_RULES[*]["forbidden"]` |
-| `scripts/okstra_ctl/run.py` | load `forbidden_by_phase`, pass to both `compute_workflow_state` calls, add `{{PHASE_FORBIDDEN_ACTIONS}}` to profile rendering |
-| `prompts/profiles/implementation.md` | replace forbidden bullets with placeholder |
-| `prompts/profiles/release-handoff.md` | replace forbidden bullets with placeholder |
-| `tests/test_phase_forbidden_ssot.py` | **create** |
-| `tests/test_profile_forbidden_placeholder.py` | **create** |
-| `tests/test_workflow_phase_sequence.py` | update `compute_workflow_state` calls |
-| `CHANGES.md`, plan doc | record |

package/docs/superpowers/specs/2026-06-13-neutral-tmux-lead-adapter-design.md

@@ -1,284 +0,0 @@
-# 하네스 중립 tmux worker-dispatch 백엔드 설계
-
-- 날짜: 2026-06-13
-- 상태: 설계 초안 (rev2 — 1차 리뷰 반영: leadRuntime/dispatch-backend 축 분리, 완료 계약 명시, validator 범위 확장)
-- 대상: okstra runtime, lead orchestration contract, worker dispatch backend
-- 선행 문서: [`2026-06-12-codex-lead-adapter-design.md`](2026-06-12-codex-lead-adapter-design.md) — 이 문서는 그 **core + lead adapter split** 위에 **worker dispatch backend** 라는 직교 축을 추가한다. 선행 문서를 먼저 읽었다고 가정한다.
-
-## 1. 배경
-
-okstra core 는 이미 비교적 하네스 중립적이다(선행 §1). 문제는 **lead 실행 계층과 worker dispatch 계층**이고, 둘이 현재 하나의 축(`leadRuntime`)에 얽혀 있다.
-
-오늘 lead+worker 는 두 레인으로 갈라져 있다.
-
-| 레인 | dispatch | 완료 판정 | 관찰성 |
-|---|---|---|---|
-| `claude-code` | 네이티브 `TeamCreate`/`Agent(...)` ([agents/SKILL.md:212](../../../agents/SKILL.md:212)) | result-file 폴링([team-contract:124](../../../skills/okstra-team-contract/SKILL.md:124)) | Claude Teams split-pane + okstra trace pane |
-| `codex` | 동기 `subprocess.run(worker.command)` ([codex_dispatch.py:1033](../../../scripts/okstra_ctl/codex_dispatch.py:1033)), render-only 게이트([run.py:2057](../../../scripts/okstra_ctl/run.py:2057)) | `returncode==0 and not missing_paths` ([codex_dispatch.py:213](../../../scripts/okstra_ctl/codex_dispatch.py:213)) | okstra trace pane 만, **순차** |
-
-사용자 목표: **tmux 세션이기만 하면 어떤 하네스(Claude Code / Codex / pi / generic external CLI / …)에서든, 사용자가 모든 worker pane 을 보면서 lead+worker 가 도는 중립 team layer.**
-
-검토(2026-06-13)에서 확인한 현황:
-
-- worker **실행**: codex/gemini 는 이미 외부 CLI(`codex exec` / `gemini -p -`) via 래퍼 ([okstra-codex-exec.sh:297](../../../scripts/okstra-codex-exec.sh:297)). claude-worker 만 in-process Agent ([agents/SKILL.md:125](../../../agents/SKILL.md:125)).
-- worker **완료 감지**: result-file 폴링 — 네이티브 `idle_notification` 을 **의도적으로 버린** 중립 설계 ([team-contract:143](../../../skills/okstra-team-contract/SKILL.md:143)).
-- **관찰성**: trace pane(`tail -F`)은 okstra 가 `tmux split-window` 로 소유 ([okstra-codex-exec.sh:270](../../../scripts/okstra-codex-exec.sh:270)); worker-**compute** pane 은 하네스가 생성 ([_common-contract.md:36](../../../prompts/profiles/_common-contract.md:36)).
-- **종료 상태 sidecar 가 이미 존재**: 래퍼가 `<prompt>.status.json` 에 `init`/`finish`(`exit_code`·`duration_ms`)/`timeout` 을 기록한다 ([okstra-codex-exec.sh:173-192](../../../scripts/okstra-codex-exec.sh:173), [:229-241](../../../scripts/okstra-codex-exec.sh:229), [:323](../../../scripts/okstra-codex-exec.sh:323)).
-
-### 1.1 핵심 결함 — `leadRuntime` 이 두 개념을 겹쳐 싣는다 (P0)
-
-`leadRuntime` 은 현재 **lead 정체성**(누가 lead 인가)과 **worker dispatch 방식**(어떻게 spawn 하는가)을 동시에 결정한다.
-
-- lead agent/role/label: `_lead_agent`/`_lead_role`/`_lead_agent_label` 이 `leadRuntime=="codex"` 만 분기 ([render.py:73-82](../../../scripts/okstra_ctl/render.py:73)).
-- lead 회계/어댑터: `_lead_adapter` 가 `leadRuntime` 으로 `dispatchMode`+`sessionAccounting` 결정 ([render.py:85-97](../../../scripts/okstra_ctl/render.py:85)).
-- conformance source: `event.lead_runtime != "codex"` 필터([validate_session_conformance.py:219](../../../validators/validate_session_conformance.py:219)), `lead_runtime=="codex"` 분기([:538](../../../validators/validate_session_conformance.py:538)).
-
-따라서 `leadRuntime="tmux"` 로 두면 lead 가 "Claude lead" 로 렌더되고 회계가 `claude-jsonl` 로 잘못 잡힌다(tmux≠codex 이므로 else 분기). **tmux 는 lead runtime 이 아니라 worker dispatch backend 다.** 두 축을 분리한다:
-
-| 축 | 값 | 결정하는 것 | 저장 위치 |
-|---|---|---|---|
-| `leadRuntime` | `claude-code` · `codex` · **`external`(신규)** | lead 정체성·라벨·lead 회계·conformance source | manifest / team-state |
-| **worker dispatch backend** | `team`(Claude Teams) · `cli-wrapper`/`mixed`(codex 현행) · **`tmux-pane`(신규)** | worker 를 어떻게 spawn·표시·완료판정 하는가 | `team_state.dispatchMode` + `workers[].backendType` (기존 필드 재사용) |
-
-두 축은 **직교**한다: `(codex, tmux-pane)`(codex lead + 보이는 pane), `(external, tmux-pane)`(generic external lead + pane), 나아가 `(claude-code, tmux-pane)`(Claude lead 가 Teams 대신 okstra pane 선택)도 표현 가능. 첫 cut 의 타깃은 `(external, tmux-pane)` 이고, 나머지 조합은 축 분리의 공짜 부산물로 두되 우선 구현하지 않는다.
-
-> 단일-참조 주: 별도 `teamBackend` 필드를 새로 만들지 않고 **기존 `team_state.dispatchMode`/`workers[].backendType`** ([codex_dispatch.py:29-30](../../../scripts/okstra_ctl/codex_dispatch.py:29), `BACKEND_CLI_WRAPPER`/`BACKEND_MIXED`)에 값 `tmux-pane` 을 추가한다. `leadAdapter.dispatchMode`(render.py, `render-only`/`team`)는 lead 가 dispatch 하느냐 여부를 가리키는 **다른** 필드임에 유의 — 이 모호성도 본 설계가 §6.1 에서 정리한다.
-
-### 1.2 잔여 종속 + 하드코딩
-
-- claude-worker in-process Agent (의도적으로 `claude --mcp-cli` 미사용, [agents/SKILL.md:125](../../../agents/SKILL.md:125)).
-- Teams roster/`SendMessage`/`TeamDelete`([_common-contract.md:51](../../../prompts/profiles/_common-contract.md:51)), `~/.claude/teams/<team>/config.json` reconcile([team_reconcile.py:17](../../../scripts/okstra_ctl/team_reconcile.py:17)).
-- 닫힌 enum `_ALLOWED_LEAD_RUNTIMES=("claude-code","codex")` ([run.py:270](../../../scripts/okstra_ctl/run.py:270)); dispatcher `leadRuntime=="codex"` 게이트([codex_dispatch.py:857](../../../scripts/okstra_ctl/codex_dispatch.py:857)); render-only 게이트([run.py:2057](../../../scripts/okstra_ctl/run.py:2057)).
-- 고정 `SUPPORTED_CLI_WORKERS={codex,gemini}` ([codex_dispatch.py:25](../../../scripts/okstra_ctl/codex_dispatch.py:25)).
-- codex 전용 lead 프롬프트([render.py:1749](../../../scripts/okstra_ctl/render.py:1749)).
-- validator 의 codex-전용 분기 3곳: dispatchMode 요구([validate-run.py:405](../../../validators/validate-run.py:405)), token autofix skip([validate-run.py:1970](../../../validators/validate-run.py:1970)), conformance source([validate_session_conformance.py:538](../../../validators/validate_session_conformance.py:538)).
-
-## 2. 결정
-
-기존 core + adapter split 에 **`external` leadRuntime + `tmux-pane` dispatch backend** 를 추가한다.
-
-핵심 원칙:
-
-0. **두 축을 분리한다(P0).** `leadRuntime`(정체성/회계/conformance) ⟂ dispatch backend(spawn/표시/완료). 어느 쪽도 상대를 가정하지 않는다.
-1. **추출, not wrapping.** codex 의 dispatch 오케스트레이션([codex_dispatch.py](../../../scripts/okstra_ctl/codex_dispatch.py))을 backend-중립 core 로 추출하고 cli-wrapper/tmux-pane 가 같은 core 를 공유한다(§6.2). codex_dispatch 를 tmux 에서 호출하는 wrapping 금지.
-2. **okstra 가 worker-compute pane 을 소유.** `tmux split-window` 로 pane 생성, 거기서 worker CLI 실행(§6.3).
-3. **완료는 status sidecar 로 판정(P1).** tmux-pane 은 비동기라 `returncode` 가 없다 — 이미 존재하는 `<prompt>.status.json`(`exit_code`/`timeout`/`stage`)을 완료 계약의 SSOT 로 쓴다(§6.4).
-4. **one-shot / re-dispatch 모델 유지.** 살아있는 인터랙티브 teammate 금지 — 세션 격리가 교차검증의 correctness 안전장치(§7).
-5. **lead 는 하네스 shell 도구로 okstra CLI 호출**(네이티브 team 도구 0개). codex 가 `okstra codex-dispatch` 를 부르는 패턴([render.py:1764](../../../scripts/okstra_ctl/render.py:1764))의 일반화.
-
-## 3. 비목표
-
-- **`leadRuntime` 에 `tmux` 를 넣지 않는다**(P0) — tmux 는 dispatch backend 값이다.
-- Claude Teams primitive(`TeamCreate`/`SendMessage`/`TeamDelete`/FleetView) 1:1 재현 금지.
-- **interactive long-running teammate 금지** — `send-keys` 입력 주입 + `capture-pane` 출력 파싱 양방향 대화는 비목표(세션격리 correctness 위배 + 화면 스크래핑 취약 + 큰 비용). worker 는 one-shot.
-- `claude-code`/`codex` 레인 변경/폐기 금지(additive). 기존 사용자 무파손.
-- `prepare_task_bundle`/profile/schema/validator 의 provider 별 fork 금지.
-- tmux 외 멀티플렉서(zellij/screen/컨테이너) 추상화 선제 작성 금지(YAGNI).
-- worker output contract/schema 신설 금지 — logical role/결과 contract 공유, dispatch backend 만 교체.
-- 축 분리로 가능해지는 `(claude-code, tmux-pane)`/`(codex, tmux-pane)` 조합을 **첫 cut 에서 구현/테스트하지 않는다**(축만 열어둠).
-
-## 4. Adapter / backend 경계 (선행 §4 확장)
-
-| 영역 | 소속 | 근거 / 변경 |
-|---|---|---|
-| `prepare_task_bundle`, `worktree*`, `workers.py`, `render*`, `schemas/`, `validators/`, `prompts/profiles/*` | **공통 core** | 선행 §4.1 |
-| convergence algorithm, completion-polling protocol | **공통 core** | runtime/backend 무관 |
-| dispatch 오케스트레이션(retry·lead-events·완료판정·report-writer 후처리) + backend registry | **공통 core (신규 추출)** | §6.2, codex_dispatch 추출 |
-| pane orchestration (`okstra_ctl/tmux.py`) | **공통 core (신규)** | §6.3 |
-| installed skills/agents, `AskUserQuestion`, `TeamCreate`/`Agent`, `claude --resume`, claude jsonl 회계, `TeamDelete`/`~/.claude/teams` | **claude-code adapter / `team` backend** | 선행 §4.2 |
-| codex lead 라벨/프롬프트, codex rollout token 파싱 | **codex adapter** | 선행 §4.3 |
-| `cli-wrapper` 동기 runner | **cli-wrapper backend** | codex 현행 |
-| `external` lead 라벨/프롬프트/회계(`artifact-only`) | **external adapter (신규)** | §6.1 |
-| pane split runner + sidecar 완료 판정 + async-wake + roster=team-state + teardown=kill-pane | **tmux-pane backend (신규)** | §6.3–6.6 |
-
-## 5. Execution modes — (leadRuntime, dispatch backend) 조합
-
-| leadRuntime | backend | 상태 | 설명 |
-|---|---|---|---|
-| `claude-code` | `team` | 기존 | 네이티브 Teams + claude-jsonl conformance |
-| `codex` | `cli-wrapper`/`mixed` | 기존(render-only→dispatch) | codex 순차 subprocess fan-out + event-log conformance |
-| **`external`** | **`tmux-pane`** | **신규(첫 타깃)** | 임의 하네스 lead + okstra 소유 병렬 pane + sidecar 완료 + event-log conformance |
-| `codex`/`claude-code` | `tmux-pane` | 축만 열림(미구현) | 부산물 — 첫 cut 비대상 |
-
-`external` + `tmux-pane` 의 동작:
-
-- **설치**: 공유 runtime/bin/templates/schema/validators 만, `~/.claude` 미터치(§9).
-- **lead**: 임의 하네스 LLM 세션. okstra 가 lead 프로세스를 spawn 하지 않는다(codex 와 동일).
-- **bootstrap**: `okstra render-bundle --lead-runtime external` 가 중립 lead 프롬프트 출력 → 하네스가 lead 컨텍스트에 주입(skill / system prompt / AGENTS.md).
-- **dispatch**: lead 가 shell 로 `okstra team dispatch` 호출 → 공통 dispatch core 가 worker 마다 **자기 pane 에서 병렬 one-shot** 실행.
-- **완료**: result-file + status-sidecar 폴링(§6.4) + async-wake(§6.6).
-- **teardown**: `okstra team teardown` → `kill-pane`([okstra-trace-cleanup.sh](../../../scripts/okstra-trace-cleanup.sh) 재사용).
-
-## 6. 핵심 메커니즘
-
-### 6.1 `external` leadRuntime + 축 분리
-
-- `_ALLOWED_LEAD_RUNTIMES` 에 `"external"` 추가([run.py:270](../../../scripts/okstra_ctl/run.py:270)).
-- `_lead_agent`/`_lead_role`/`_lead_agent_label`/`_lead_adapter` 의 2-way(`codex` vs else)를 **3-way 또는 테이블 구동**으로([render.py:73-97](../../../scripts/okstra_ctl/render.py:73)): `external` → 중립 라벨("okstra lead", 하네스 비특정) + `sessionAccounting:"artifact-only"`.
-- worker dispatch backend 은 `team_state.dispatchMode`/`workers[].backendType` 에 `tmux-pane` 추가([codex_dispatch.py:29-30](../../../scripts/okstra_ctl/codex_dispatch.py:29)). lead 프롬프트의 dispatch 가능 여부는 **backend 가 dispatch 가능한지**로 판단(아래 게이트).
-- render-only 하드게이트([run.py:2057](../../../scripts/okstra_ctl/run.py:2057))와 dispatcher 게이트([codex_dispatch.py:857](../../../scripts/okstra_ctl/codex_dispatch.py:857))를 `leadRuntime` 직접 비교가 아니라 **"dispatch backend 가 구현되어 있는지"**로 일반화: `tmux-pane`/`cli-wrapper` = dispatch 허용, 미구현 backend = render-only.
-
-### 6.2 dispatch core 추출 + worker-backend 레지스트리 (P2 — 경계 명시)
-
-`codex_dispatch.py` 는 단순 runner 가 아니라 오케스트레이터다. 추출 경계를 명시한다.
-
-| 구성요소 | 위치(현재) | 행선지 |
-|---|---|---|
-| dispatch 루프·`_set_dispatch_mode` | [dispatch_plan:190](../../../scripts/okstra_ctl/codex_dispatch.py:190) | **공통 core** |
-| retry 루프·`worker-dispatched` 이벤트·완료판정 | [_dispatch_worker_with_retry:207](../../../scripts/okstra_ctl/codex_dispatch.py:207) | **공통 core** (단, 완료판정은 §6.4 로 추상화) |
-| prompt materialization | [~300](../../../scripts/okstra_ctl/codex_dispatch.py:300) | **공통 core** |
-| report-writer 후처리(token/render-views/followups/validate) | [_post_process_report_writer_result:1036](../../../scripts/okstra_ctl/codex_dispatch.py:1036) | **공통 core** |
-| runner: `cli-wrapper` 동기 실행 | [_run_cli_wrapper_worker:1018](../../../scripts/okstra_ctl/codex_dispatch.py:1018) | **cli-wrapper backend** |
-| codex rollout token 파싱 | okstra_token_usage | **codex adapter** |
-| runner: `tmux-pane` 비동기 split | (신규) | **tmux-pane backend** |
-
-- 고정 `SUPPORTED_CLI_WORKERS`([:25](../../../scripts/okstra_ctl/codex_dispatch.py:25))를 `{worker_id → BackendDescriptor(wrapper, cli_bin, runner, usage_parser)}` 레지스트리로 일반화.
-- **claude CLI backend 추가**: claude-worker 를 `claude --mcp-cli`(또는 비대화 exec) 래퍼로 실행 — okstra 가 의도적으로 안 쓰던 경로([agents/SKILL.md:125](../../../agents/SKILL.md:125))를 **dispatch backend≠team 일 때만** 채택. `(claude-code, team)` 은 계속 in-process Agent(무파손).
-- codex/gemini 래퍼([okstra-codex-exec.sh](../../../scripts/okstra-codex-exec.sh)/[okstra-gemini-exec.sh](../../../scripts/okstra-gemini-exec.sh)) 그대로 재사용.
-
-### 6.3 okstra-owned worker-compute pane
-
-- [okstra_ctl/tmux.py](../../../scripts/okstra_ctl/tmux.py)(현재 rerun 용 `new-session` 만)에 API 추가: `resolve_caller_pane / split_worker_pane / set_pane_title / tag_pane / capture_pane / kill_pane / list_run_panes`.
-- 소스 로직은 검증된 shell 에서 **추출**(중복 금지): split+title+run-scoped tag = [okstra-codex-exec.sh:270-283](../../../scripts/okstra-codex-exec.sh:270), ancestor-PID 리졸브 = [tmux-pane.sh:21](../../../scripts/lib/okstra/tmux-pane.sh:21), tag 기반 kill = [okstra-trace-cleanup.sh](../../../scripts/okstra-trace-cleanup.sh).
-- worker 마다 `split_worker_pane` 로 compute pane 생성 + 그 안에서 worker CLI 병렬 실행. pane 제목 = `<provider>-<role>`(executor/verifier 라벨은 [_implementation-executor.md:14](../../../prompts/profiles/_implementation-executor.md:14) 재사용). 사용자는 전 worker 를 라이브로 본다.
-
-### 6.4 완료 계약 — 동기 → 비동기 (P1, 핵심)
-
-현재 runner 는 **동기**다: `_run_worker → subprocess.run → CompletedProcess(returncode)` ([:1033](../../../scripts/okstra_ctl/codex_dispatch.py:1033)), 그리고 `returncode==0 and not missing_completion_paths` 로 완료 판정([:213](../../../scripts/okstra_ctl/codex_dispatch.py:213)). tmux-pane 은 `split-window` 가 **pane id 만** 즉시 반환하고 worker 는 detached 로 돈다 — `returncode` 가 없다.
-
-→ runner 인터페이스의 **형태를 바꾼다**: `run_worker()→CompletedProcess` 를 `spawn_worker()→WorkerHandle` + `await_worker(handle)→WorkerOutcome(terminal_status, exit_code)` 로 분리.
-
-| backend | spawn | await |
-|---|---|---|
-| `cli-wrapper`(동기) | `subprocess.run` 실행 후 이미 종료된 handle | 즉시 반환(현행 의미 보존) |
-| `tmux-pane`(비동기) | `split-window -P -F '#{pane_id}'` → `{paneId, statusSidecarPath, resultPath}` | (result 파일 존재) **AND** (status sidecar terminal) 폴링 |
-
-- **status sidecar 가 완료 계약의 SSOT**: 래퍼는 이미 `<prompt>.status.json` 에 `init`/`finish`(`exit_code`·`duration_ms`)/`timeout` 을 EXIT trap·watchdog 으로 기록한다([okstra-codex-exec.sh:173-179](../../../scripts/okstra-codex-exec.sh:173), [:229-241](../../../scripts/okstra-codex-exec.sh:229), [:323](../../../scripts/okstra-codex-exec.sh:323), writer = [okstra-wrapper-status.py](../../../scripts/okstra-wrapper-status.py)). `await_worker` 는 이 sidecar 의 terminal `exit_code`/`timeout`/`stage` 를 읽어 동기 `returncode` 를 **대체**한다. 즉 신규 인프라가 아니라 **이미 기록되는 값을 완료 판정에 끌어쓰는 것**.
-- 실패/타임아웃/retry 판정: `stage`+`exit_code`로 "래퍼 미시작 / CLI 실행했으나 산출물 없음 / 정상" 구분(이미 redispatch policy 의도, [:178-179](../../../scripts/okstra-codex-exec.sh:178)). retry 루프([:207](../../../scripts/okstra_ctl/codex_dispatch.py:207))는 `WorkerOutcome` 위에서 그대로 돈다.
-
-### 6.5 roster registry = team-state + dispatch 레코드 (P2)
-
-re-dispatch/reverify 라운드/report-writer 는 worker 당 pane 이 **여러 개** 생긴다(§7). 단일 `paneId` 로는 표현 불가 → **dispatch 레코드 리스트**.
-
-- top-level `workerDispatches[]`(또는 `workers[].dispatches[]`) 각 항목: `{role, kind: initial|retry|reverify-r<N>|report-writer, paneId, backendType, status, statusSidecarPath, resultPath, attempt}`.
-- `teamBackend`/`dispatchMode` 는 team-state 상단에 기록(§1.1 표). `~/.claude/teams` 및 [team_reconcile.py](../../../scripts/okstra_ctl/team_reconcile.py) 의존 제거(claude-code/`team` 전용). teardown = 레코드의 paneId 들 `kill_pane` + team-state 정리.
-
-### 6.6 async-wake shim (유일한 환원 불가 하네스별 조각)
-
-lead 는 "백그라운드 폴 → 완료시 깨어남" 으로 완료를 감지한다([team-contract:131](../../../skills/okstra-team-contract/SKILL.md:131)). 이 "end-turn→resume" primitive 만 하네스마다 다르다.
-
-| 하네스 | primitive |
-|---|---|
-| Claude Code | `Bash(run_in_background:true)` + auto-resume |
-| pi / generic external CLI | `bash(async:true)` + 자동 결과 전달 / `job poll` |
-| Codex | (자체 비동기 메커니즘) |
-
-- `okstra team await --run-dir <dir>` 가 §6.4 폴링을 수행하고, 하네스는 이를 자기 비동기 primitive 로 감싼다. okstra 는 폴링 로직(공통)만 소유, "백그라운드로 띄우는 법" 1줄만 lead 프롬프트가 하네스별로 지시.
-- 긴 foreground blocking 을 죽이는 하네스([team-contract:142](../../../skills/okstra-team-contract/SKILL.md:142))용으로 `okstra team await` 는 주기적 stdout heartbeat 옵션을 둔다.
-- tmux 미가용/blocking 미지원 시 → `cli-wrapper`(동기 subprocess) 로 graceful degrade(codex 현행 흡수).
-
-### 6.7 token accounting
-
-- backend 별 usage 파서. codex rollout JSONL([okstra_token_usage/codex.py](../../../scripts/okstra_token_usage/codex.py))·gemini chat JSON 재사용. claude CLI backend 파서는 신규.
-- lead 자체 token/cost 는 codex 와 동일하게 `leadUsage.source="unavailable"`.
-
-## 7. rework / 반복 처리 (1급 절)
-
-리뷰 중 제기된 질문 — "executor/worker 산출물을 verifier/validator 가 거부하면?" — 의 설계 답. **rework 는 살아있는 teammate 메시지가 아니라 lead 주도 re-dispatch / phase 재진입이며, 중립 모델에서 오늘과 동일하게 동작한다.**
-
-1. **verifier 간 불일치(run 내부, Phase 5.5)** → 새 one-shot reverify 워커 재dispatch([convergence:262](../../../skills/okstra-convergence/SKILL.md:262)), 재검증 항목은 새 프롬프트 본문([convergence:108](../../../skills/okstra-convergence/SKILL.md:108)). 중립 매핑: 라운드마다 새 pane split → §6.5 의 dispatch 레코드에 `reverify-r<N>` 항목 추가.
-2. **verifier 가 산출물 거부** → run 은 verdict 만 렌더하고 종료, in-run 수정 금지([final-verification.md:56](../../../prompts/profiles/final-verification.md:56)); Acceptance Blocker+Routing 이 **새 run** 입력([final-verification.md:54](../../../prompts/profiles/final-verification.md:54), [:40](../../../prompts/profiles/final-verification.md:40)). implementation 도 "기록 후 새 run 라우팅"([implementation.md:37](../../../prompts/profiles/implementation.md:37)). 중립 매핑: 새 run = 새 team/pane, 피드백은 이전 report 파일에서 읽음.
-3. **okstra validator 거부** → lead 가 산출물 수정 또는 report-writer 재dispatch.
-
-**세션 격리는 correctness 요구사항이다** — "Session isolation … is the primary self-review safeguard: each verifier is a separate CLI invocation with its own context window"([_implementation-verifier.md:14](../../../prompts/profiles/_implementation-verifier.md:14)). 컨텍스트 유지 teammate 는 자기확증 편향 → 교차검증 무결성 훼손. §3 의 one-shot 비목표는 한계가 아니라 정확성 설계. 피드백 채널 = 영속 task identity([README §1](../../../README.md:29)) + 파일.
-
-pane 부수효과 2:
-- **라운드마다 pane 누적** → 기존 phase-start pane cleanup([_common-contract.md:36-37](../../../prompts/profiles/_common-contract.md:36))을 **라운드 경계**로 확장.
-- **async-wake 공용** → §6.6 shim 하나가 초기/재dispatch 모두 커버.
-
-## 8. Contract changes
-
-### 8.1 manifest / team-state
-
-```json
-{
-  "leadRuntime": "external",
-  "leadAdapter": { "name": "external", "dispatchMode": "tmux-pane", "sessionAccounting": "artifact-only" },
-  "dispatchMode": "tmux-pane",
-  "workerDispatches": [
-    { "role": "claude", "kind": "initial", "paneId": "%217", "backendType": "claude-cli",
-      "status": "completed", "statusSidecarPath": "...status.json", "resultPath": "..." }
-  ]
-}
-```
-
-### 8.2 validator — codex-전용 분기 3곳을 backend/runtime-aware 로 일반화 (P1)
-
-| 위치 | 현재 | 변경 |
-|---|---|---|
-| [validate-run.py:405](../../../validators/validate-run.py:405) | `leadRuntime=="codex"` → dispatchMode 요구, else → `teamCreate` 강제 | **dispatch backend≠`team`** 이면 dispatchMode 요구; `team` 일 때만 `teamCreate` 검사 |
-| [validate-run.py:1970](../../../validators/validate-run.py:1970) | `leadRuntime=="codex"` → token autofix skip | **sessionAccounting=="artifact-only"**(codex+external) → skip |
-| [validate_session_conformance.py:219](../../../validators/validate_session_conformance.py:219), [:538](../../../validators/validate_session_conformance.py:538) | `lead_runtime=="codex"` → event-log | **claude-jsonl 은 `(claude-code, team)` 에서만**; 그 외 → event-log + sidecar records (artifact-event runtime set 에 `external` 추가, 메시지 문구 일반화) |
-
-추가: dispatchMode enum 에 `tmux-pane` 등록(`CODEX_DISPATCH_MODES` → backend-중립 set 로 확장 또는 별도 set).
-
-## 9. Install / packaging (P2 — 전체 surface)
-
-첫 구현은 **디렉터리 이동 없이** 값/필드/명령만 추가. 손대는 파일:
-
-- [install.mjs:90](../../../src/install.mjs:90) `INSTALL_RUNTIMES` set + `runtimeIncludesClaudeAssets`.
-- [runtime-manifest.mjs:3-9](../../../src/runtime-manifest.mjs:3) `runtimeListForSelection` / `buildRuntimeManifest` asset 플래그.
-- [doctor.mjs:68](../../../src/doctor.mjs:68) `requiredSkillNamesForRuntime`.
-- [cli-registry.mjs:140](../../../src/cli-registry.mjs:140) 옆에 신규 `team`(dispatch/await/teardown) 명령 등록 + CLI help.
-- uninstall / `installed-runtimes.json` 범위 / 관련 tests.
-
-## 10. 단계별 구현 계획 (리뷰 권장 순서)
-
-### Stage 1 — 축 분리 + render-only 중립 bootstrap (dispatch 미개방)
-- `leadRuntime` += `external`; `_lead_*`/`_lead_adapter` 3-way; manifest `dispatchMode` 필드.
-- 중립 lead 프롬프트 렌더(codex gate 형제, [render.py:1749](../../../scripts/okstra_ctl/render.py:1749) 옆).
-- **`external` 도 render-only 유지** — `okstra team` 명령이 없으므로 dispatch 를 열지 않는다([cli-registry.mjs:140](../../../src/cli-registry.mjs:140) 미존재). 깨진 dispatch 프롬프트 방지.
-- 테스트: render 3-way 단위, enum 정규화, manifest 직렬화. **pane/dispatch 없음.**
-
-### Stage 2 — pane orchestration API
-- [okstra_ctl/tmux.py](../../../scripts/okstra_ctl/tmux.py) 에 §6.3 API 추출.
-- 테스트: 명령 빌더 단위 + 실 tmux e2e(mktemp 세션, split/title/tag/list/kill 단언).
-
-### Stage 3 — dispatch core + 완료 계약 (한 묶음, dispatch 개방)
-- codex_dispatch 추출(§6.2 경계) + backend registry + claude CLI backend.
-- runner 인터페이스 `spawn/await` 분리 + status-sidecar 완료 계약(§6.4) + dispatch 레코드(§6.5).
-- 신규 `okstra team dispatch` + `okstra team await` (+ `--dry-run`). 여기서 `external+tmux-pane` render-only 게이트 해제.
-- tmux 미가용 시 cli-wrapper degrade.
-- 테스트: fake worker CLI 로 pane 병렬/sidecar 완료/실패·타임아웃·retry e2e([codex-run-dispatch.integration.test.mjs:79](../../../tests-js/codex-run-dispatch.integration.test.mjs:79) 확장), backend registry 단위.
-
-### Stage 4 — roster/teardown + 라운드경계 cleanup
-- team-state `workerDispatches[]` 기록; `okstra team teardown` = kill-pane; phase/라운드 경계 cleanup 확장(§7).
-- 테스트: teardown·cleanup e2e.
-
-### Stage 5 — async-wake adapter + validator 일반화
-- §6.6 wake shim(운영 하네스 1종부터) + §8.2 validator 3곳 일반화.
-- 테스트: wake/ degrade 경로, validator backend-aware 분기.
-
-### Stage 6 — token accounting + packaging
-- claude CLI usage 파서; §9 install/doctor/registry/uninstall.
-- 테스트: collector backend별, doctor/ install runtime.
-
-## 11. 위험과 대응
-
-| 위험 | 대응 |
-|---|---|
-| `leadRuntime` 과대적재(P0) | `external` runtime + dispatch backend 축 분리; render.py/validator 3곳을 runtime/backend-aware 로 |
-| Stage 1 이 없는 `okstra team` 호출 프롬프트 생성(P1) | Stage 1 은 render-only 만; dispatch 는 명령 존재하는 Stage 3 에서 개방 |
-| 비동기 완료 오판(P1) | status sidecar(`exit_code`/`timeout`/`stage`)를 완료 SSOT 로; result-file 단독 의존 금지 |
-| validator 범위 과소(P1) | codex-전용 3분기를 backend/accounting 기준으로 일반화(§8.2) |
-| 단일 paneId 로 reverify 표현 불가(P2) | `workerDispatches[]` 레코드 리스트(§6.5) |
-| 추출 경계 모호(P2) | §6.2 표로 core/adapter/backend 행선지 명시; runner 인터페이스 형태 변경 명시 |
-| packaging 누락(P2) | runtime-manifest/registry/uninstall/help/tests 포함(§9) |
-| claude CLI backend 비용(in-process 이점 상실) | dispatch backend≠`team` 일 때만; `(claude-code,team)` 유지 |
-| 교차검증 무결성 | 재검증 fresh one-shot 강제(§7), 인터랙티브 teammate 금지 |
-
-## 12. 결론
-
-가능하다. 단, "팀을 raw tmux 에 재발명"이 아니라 **"`leadRuntime` 에서 dispatch backend 를 떼어내고(P0), codex dispatch 를 backend-중립 core 로 추출하고, 비동기 완료를 status sidecar 로 판정(P1), worker-compute pane 을 소유"** 다. okstra core 가 이미 중립이고 codex adapter·status sidecar 가 살아있는 선례이므로, 작업은 새 발명이 아니라 경계 정리다.
-
-**첫 PR = Stage 1**(축 분리 + `external` runtime + render-only 중립 bootstrap, **dispatch 미개방**). 이어 Stage 2(pane API). 실제 dispatch 와 완료 계약은 `okstra team` 명령이 생기는 Stage 3 에서 한 묶음으로 개방한다 — 그 전에는 어떤 단계도 없는 명령을 가리키는 lead 프롬프트를 만들지 않는다.