okstra 0.121.1 → 0.123.0

package/runtime/bin/lib/okstra/usage.sh

@@ -29,7 +29,7 @@ optional arguments:
                        (1) ancestor of cwd that contains .okstra/project.json,
                        (2) \`git rev-parse --show-toplevel\` from cwd. Errors out if neither resolves.
   --directive        Free-form user-supplied directive carried into the run as a "## Directive" section
-                       inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule)
+                       inside instruction-set/analysis-material.md. Lead, workers, and skills (e.g. okstra-schedule-gen)
                        may treat this as a hard hint that overrides default heuristics. Use to express intent
                        like "render a Gantt even with single XL task" or "emphasize rollout risk".
   --fix-cycle <yes|no> When re-entering an entry phase (requirements-discovery / error-analysis /
@@ -90,7 +90,7 @@ options:
                       (Antigravity worker is optional; add \`antigravity\` explicitly, e.g. --workers claude,codex,antigravity,report-writer)
   --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
   --claude-model       Model for Claude worker. Default: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
-  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6
+  --codex-model        Model for Codex worker. Default: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or lead model default
@@ -124,7 +124,7 @@ model defaults:
   Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
   Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
-  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6
+  Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
 

package/runtime/prompts/launch.template.md

@@ -5,7 +5,7 @@
 
 ## Progress reporting (BLOCKING)
 
-Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the okstra lead contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows.
+Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at every checkpoint enumerated in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Progress reporting (BLOCKING)") — phase-1-intake start/complete, phase-2-prompts, phase-3-team-create, phase-4-dispatch (per worker), phase-5-collect (per worker), phase-5.5-convergence (per round), phase-6-synthesis, phase-7-persist, and final `complete`. One line per checkpoint, never batched, never replaced with prose. This is the only signal the user has during multi-minute silent windows.
 
 ## Current Phase Boundary
 
@@ -19,7 +19,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 {{VERIFICATION_TARGET}}
 {{STAGE_INTEGRATION}}
 - Phase advancement requires a new okstra invocation launched with `--task-type {{WORKFLOW_NEXT_RECOMMENDED_PHASE}}` after this run's final report is written and approved. The lead must not write source code, run builds/migrations/deployments, or otherwise produce artifacts of a different phase from inside this run.
-- See `Lifecycle Phase Boundaries` in the okstra lead contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}`) for the canonical rules and the phase-transition checklist.
+- See `Lifecycle Phase Boundaries` in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}`) for the canonical rules and the phase-transition checklist.
 
 {{TEAM_CREATION_GATE}}
 
@@ -58,7 +58,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
   - Codex worker: `{{CODEX_WORKER_ERRORS_SIDECAR_PATH}}`
   - Antigravity worker: `{{ANTIGRAVITY_WORKER_ERRORS_SIDECAR_PATH}}`
   - Report writer worker: `{{REPORT_WRITER_WORKER_ERRORS_SIDECAR_PATH}}`
-- The paths above are the values; the wiring duties — injecting the `**Errors log path:**` / `**Errors sidecar path:**` header pair into every dispatch prompt, and dumping each terminated worker's sidecar via `okstra error-log append-from-worker` — are defined once in the okstra lead contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Errors log path wiring (BLOCKING)"). Follow that section; do not re-derive the rules from this block.
+- The paths above are the values; the wiring duties — injecting the `**Errors log path:**` / `**Errors sidecar path:**` header pair into every dispatch prompt, and dumping each terminated worker's sidecar via `okstra error-log append-from-worker` — are defined once in the lifecycle core contract (`{{OKSTRA_LEAD_CONTRACT_PATH}}` "Errors log path wiring (BLOCKING)"). Follow that section; do not re-derive the rules from this block.
 
 ## Executor Worktree
 
@@ -76,7 +76,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 
 {{AVAILABLE_MCP_SERVERS}}
 - The full usage policy and per-phase rules live in the analysis packet's `Available MCP Servers` extract. Inject only the one-line pointer below into each analysis-worker prompt: `**MCP servers:** follow the analysis packet's "Available MCP Servers" section (already in your Required reading).`
-- **Invocation rule (forward to every worker prompt)**: MCP tools are addressed by their tool name through the host's tool interface — **never via `Bash`**. Claude-side workers call the tool directly (e.g. `mcp__<server>__<tool>`). Codex/Antigravity workers call through their CLI's own MCP transport (e.g. `codex mcp call ...`). Running the tool name as a shell command is a contract violation and will always fail regardless of permission grants.
+- **Invocation rule (forward to every worker prompt)**: MCP tools are addressed through the executing worker provider's native tool interface — never by running the tool name as a shell command. In-process workers call the tool directly; CLI workers use that CLI's configured MCP transport. A worker without the configured MCP server records `MCP not available in this CLI` instead of guessing.
 - Codex worker and Antigravity worker run external CLIs; they can only use these MCP servers if their own CLI configs mirror them. If not, instruct the worker to record `MCP not available in this CLI` in its `Missing Information or Assumptions` block rather than guessing or shell-falling-back.
 - MCP queries are evidence-grade. Cite server, table, and the SELECT used in worker output. MCP must NOT be used as a write path in any phase, including `implementation`.
 
@@ -91,7 +91,7 @@ Emit one `PROGRESS: <phase-id> <verb-phrase>` line as plain user-facing text at
 
 The **default is full re-verification**. Only narrow this re-run to the impacted stages when the deterministic `okstra incremental-scope` CLI returns `mode == "incremental"`; on any doubt, stay full. This procedure fires ONLY when this run's task-type is `implementation-planning` AND a prior final report exists for this task-key (its data.json at `runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json`, where `<prev-seq>` is the most recent prior implementation-planning run's seq). For every other task-type, ignore this block and re-verify normally. This branches on the CLI's `mode` output only — it does NOT re-implement the safety logic in the prompt.
 
-1. **Resolve the impacted stage set (safety condition C2 — your discretionary judgement).** For each answered `C-*` row you reconciled in §1, decide which **Stage Map stage numbers** (from the prior plan's `## 5.5 Stage Map`) the answer touches. Rules:
+1. **Resolve the impacted stage set (safety condition C2 — your discretionary judgement).** For each answered `C-*` row you reconciled in §1, decide which **Stage Map stage numbers** (from the prior plan's `## 5.5 Stage Map`) the answer touches. Also collect the IDs of any PREP items changed by the carried response. Rules:
    - Pass ONLY stage numbers that appear in that Stage Map. Never invent or guess a stage number — a number absent from the graph must never enter `--impacted` (it would leak into `reverify_stages`).
    - If you cannot map a touched item to a real stage with confidence, leave the impacted set **EMPTY** — an empty set forces `mode == "full"`. Widening to full is always the safe choice; guessing is not.
    - If any answer overturns the selected Option, restructures the stages, or changes the recommended approach (rather than a localized detail), also leave the impacted set **EMPTY**.
@@ -104,7 +104,8 @@ The **default is full re-verification**. Only narrow this re-run to the impacted
      --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
      --cur-base-sha {{EXECUTOR_WORKTREE_BASE_REF}} \
      --prev-base-sha <prior baseRef from step 2> \
-     --impacted <csv of impacted stage numbers, empty for full>
+     --impacted <csv of impacted stage numbers, empty for full> \
+     --prep-items <csv of changed PREP item ids, empty when none>
    ```
    The CLI reads the plan's dependency graph from the top-level `## 5.5 Stage Map` (`implementationPlanning.stageMap`), which is authoritative for the impacted stage numbers — there is no per-option stage graph. The CLI prints JSON `{mode, reverify_stages, carry_stages, reason}`. Instruct the report-writer to record this JSON verbatim into this run's data.json as `implementationPlanning.incrementalDecision` (keys `mode`, `reverifyStages`, `carryStages`, `reason`) — the renderer turns it into the `### 0.1 Incremental Re-Verification Scope` audit block, and the validator fails an `incremental`-mode run whose Section 0 omits that block.
 4. **`mode == "full"`** → run the existing full re-verification path unchanged; ignore `reverify_stages` / `carry_stages`.
@@ -115,6 +116,8 @@ The **default is full re-verification**. Only narrow this re-run to the impacted
      --prev-data runs/implementation-planning/reports/final-report-implementation-planning-<prev-seq>.data.json \
      --cur-data <this run's data.json> \
      --prev-seq <prev-seq> \
+     --carry-stages <csv from incrementalDecision.carry_stages> \
+     --reverify-stages <csv from incrementalDecision.reverify_stages> \
      --out <this run's data.json>
    ```
    A non-zero exit (`CarryError` — schema drift between the two runs) means the carry is unsafe: fall back to **full** — discard the incremental result and re-verify every stage. Note: `verdictCard` / `finalVerdict` are NEVER carried — this run re-computes them from the re-verified plus carried plan items.

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

@@ -0,0 +1,104 @@
+# Claude Code Lead Runtime Adapter
+
+## Scope
+
+This adapter maps the neutral Okstra lead operations to Claude Code host primitives. Read it only when the rendered launch prompt selects `leadRuntime=claude-code`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `claude-code` |
+| `leadRoleLabel` | `Claude lead` |
+| `userPromptMode` | `native-question` |
+| `workerDispatchBackend` | `team` |
+| `sessionAccounting` | `claude-jsonl` |
+| `resumeMode` | `session-id` |
+| `teardownMode` | `teammate-shutdown` |
+| `leadEventSource` | `claude-jsonl+artifact` |
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Use the host file-read primitive and preserve the core contract's read order. |
+| `write_artifact` | Use the host file-write primitive only for paths authorized by the active lifecycle phase. |
+| `prompt_user` | Use the native question tool for approvals and clarifications; do not infer an answer from silence. |
+| `dispatch_worker` | Dispatch `Agent(name: "<role>", run_in_background: true)` without `team_name`; apply the assigned model as specified below. |
+| `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
+| `redispatch_worker` | Dispatch a fresh `Agent(...)` session with the same prompt plus the core reverify/retry reason. |
+| `shutdown_workers` | Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` only to confirmed-complete teammates selected for cleanup. |
+| `record_lead_event` | Emit the required `PROGRESS:` line as assistant text and persist core-required state/artifact updates. |
+| `collect_usage` | Run `okstra token-usage` against the team-state; it reads the run-scoped `~/.claude/projects` session JSONL evidence. |
+
+## Dispatch variants
+
+- The session owns one implicit team. `TeamCreate` and `TeamDelete` are absent on current Claude Code builds; never probe for them and never pass `team_name`.
+- Set `name` to the core-assigned functional role label so token attribution can match `agentName`.
+- Map the core assignment key to the native `subagent_type` field: `claude-worker`, `codex-worker`, `antigravity-worker`, or `report-writer-worker`. Never substitute `general-purpose` for a rostered Report writer worker.
+- For in-process Claude and report-writer roles, map `modelExecutionValue` to the supported family token and pass it as the `model` argument. CLI-wrapper roles apply their model in the wrapper and remain `inherit` at the Agent layer.
+- A resumed lead can dispatch a fresh worker; resume is not a valid reason to omit a rostered role.
+
+### Dispatch-time model enforcement
+
+- `Claude worker` and `Report writer worker` definitions declare `model: inherit`; the lead MUST override that default by passing the assigned family token (`fable`, `opus`, `sonnet`, or `haiku`) as the `Agent(...)` `model` argument.
+- Codex and Antigravity wrapper agents remain `inherit` at the Agent layer because their exact `modelExecutionValue` is applied by the wrapper CLI's own model argument.
+- Missing or unsupported family-token mapping is a pre-dispatch contract failure. Never inherit the lead model, choose a nearby alias, or switch provider silently.
+- Every analysis dispatch sets `name: "<workerId>-worker"`; convergence retries append `-reverify-r<N>`, implementation uses the functional `-executor` / `-verifier` suffix, and report writing uses `report-writer`. These values are retained as `agentName` in session JSONL for usage attribution.
+- Every Codex / Antigravity prompt includes `**Pane role:** <functional-role>` so the wrapper's optional fifth argument names both its caller pane and trace pane.
+- The Agent SDK auto-loads the in-process `claude-worker` definition, so that worker's prompt body may be shorter than CLI-wrapper prompt bodies; every worker still receives the same Worker Preamble pointer and core inputs.
+- A retry keeps the same Agent `name`. When logging a twice-failed CLI-wrapper attempt, reference both attempts' `bash_ids` and prompt-history paths.
+- An internally detected contract violation without a specific worker uses `--agent "claude-lead"` in the error-log event.
+
+### Reverify, critic, and report-writer assignments
+
+- Reverify dispatch uses a fresh one-shot `Agent(...)` call named `<workerId>-worker-reverify-r<N>`. Preserve the initial worker's definition and map an in-process Claude assignment's `modelExecutionValue` to its exact family token; CLI-wrapper assignments remain `inherit` at the Agent layer and apply the exact model in their wrapper.
+- Critic dispatch uses `name: "<provider>-worker-critic"`, `dispatchKind: "critic"`, and the exact mapped model from `config.critic.modelExecutionValue`. If that value cannot be mapped, record `critic-skipped: model-unresolved` and do not dispatch.
+- Report-writer dispatch uses `name: "report-writer"` and maps the roster assignment's `modelExecutionValue` to the supported family token. The prompt's `**Model:**` header must carry the same execution value.
+- Each variant persists its prompt path, Result Path, worker-results path, error paths, and `dispatchKind` before dispatch. Completion uses the shared background Result Path poll; an Agent acknowledgement never completes the variant.
+
+## Completion, cleanup, and resume
+
+- Follow the core Result Path + terminal-status completion contract. The Claude adapter's wake mechanism is one `Bash(run_in_background: true)` poll covering every pending Result Path, not foreground sleep or an idle-notification dependency. A spawn acknowledgement is never completion.
+- The background poll uses a per-worker deadline of twice the expected duration: 20 minutes for `requirements-discovery`, 30 for `error-analysis`, 40 for `implementation-planning`, 40 for `implementation`, and 20 for `final-verification`. On timeout, record terminal status and apply the core's single shared retry budget.
+- The Claude worker heartbeat audit sidecar must update at least every five minutes while its result is pending. A missing or stale heartbeat consumes the same one-retry budget; after the second silent hang, record `timeout`. The result file remains the authoritative completion signal.
+- The Claude Code harness blocks long foreground sleeps and shorter-sleep circumvention loops. Keep the result poll in a single background shell and let wrapper agents use their documented `BashOutput` loop.
+- On approved cleanup, reconcile the current live session roster before sending shutdown requests. Never target the lead session.
+- Collect usage before teardown. Resume through the recorded Claude session id and keep all run artifacts authoritative.
+
+### CLI-wrapper polling
+
+- Start `okstra-codex-exec.sh` / `okstra-antigravity-exec.sh` with `Bash(run_in_background: true)` and poll `BashOutput(bash_id)` back-to-back until terminal completion. Never add a foreground sleep.
+- Return accumulated stdout on success. On a non-zero `exit_code`, record the real code and observed duration.
+- At the 1800-second cap, inspect the live log mtime once. Recent output grants one extension to 2100 seconds; otherwise call `KillShell(shell_id)`, record exit code 124, and return the wrapper timeout sentinel.
+- Keep the wrapper subagent alive throughout polling so its JSONL timestamp window covers the underlying CLI rollout.
+
+### Session accounting
+
+- At the start of Phase 7, run `okstra token-usage /abs/path/to/run/state/team-state-<task-type>-<seq>.json --write --summary` with the literal team-state path.
+- Read the lead and Claude-side wrapper evidence from `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; attribute workers by the dispatch `agentName` recorded above.
+- Resolve `teamName` from `state.teamName` or `state.team.teamName` and use the full manifest-provided value as the team needle. If it is missing, the collector's short-form fallback cannot match worker JSONLs and records those workers as `source: "unavailable"`.
+- Keep underlying Codex and Antigravity CLI usage separate from the Claude wrapper-session usage. Persist `leadUsage`, per-worker usage, and `usageSummary` before report substitution and cleanup.
+
+## Run-scoped resource lifecycle
+
+- At run start, record `teamName` as the audit label and `teamCreate: { attempted: false, status: "implicit", splitPane: <bool> }` in team-state. A concurrent run records `status: "skipped", reason: "concurrent-run"`. Populate `lead.sessionId`; the session transcript lives under `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`.
+- Record the lead pane once with `mkdir -p "<RUN_DIR>/state" && { . "$HOME/.okstra/bin/lib/okstra/tmux-pane.sh" 2>/dev/null && okstra_resolve_caller_pane; } > "<RUN_DIR>/state/lead-pane.id" 2>/dev/null || true`. This is silent setup and must not gate cleanup; the cleanup script protects the lead pane itself.
+- Collect and persist token usage before any live-roster cleanup, including cleanup between batches and the run-end shutdown sequence.
+- Before each new worker batch, run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`, then send `SendMessage(to: <name>, message: { type: "shutdown_request" })` only to confirmed-complete teammates from the prior batch. Never target the lead or an incomplete critic/reverify worker.
+- After batch cleanup, record the current live session generation with `okstra token-usage "<TEAM_STATE_PATH>" --record-observed-session --project-root "<PROJECT_ROOT>"`. This protects usage accounting when Claude Code re-issues the session id after resume or compaction.
+- Claude Code cannot delete the implicit team or surgically remove an idle roster entry. Explain that teammates may remain visible until session end and, when needed, give the manual action `Delete team <teamName> in Teams/FleetView`.
+- The `SessionEnd` hook runs `$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end` as the safety net for the current live session.
+
+### Run-end cleanup sequence (BLOCKING)
+
+1. Call `collect_usage` through this adapter and persist usage before inspecting or changing any residual resource.
+2. Run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>"` exactly once and inspect the current live roster without mutating it.
+3. If no residual pane and no current live roster exists, skip the question and perform no cleanup operation.
+4. Otherwise call `prompt_user` exactly once with this binary prompt. This one answer controls the complete residual pane and teammate set; never ask a second teammate-only question.
+   > This phase is ending. The following Okstra panes and worker teammates remain — close and clean them up?
+   > <quoted `--list` output>
+   > (Yes) Close everything and clean up teammates / (No) Keep everything
+5. On `keep`, preserve every residual resource and show `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"` plus the manual Teams/FleetView action.
+6. On approved `clean`, emit the teardown checkpoint, run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`, then run `$HOME/.okstra/bin/okstra-team-reconcile.sh --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"` exactly once. The resolver reads the current live session's `~/.claude/teams/session-<live>/config.json`, falling back to the snapshot directory only when the live directory is absent, and prints `dismissible-member: <name>` records.
+7. Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each printed, confirmed-complete non-lead member. The `message` MUST be the object literal shown, NEVER a JSON string in a text field. Never target the lead or use `TaskStop`; teammates are not background tasks.

package/runtime/prompts/lead/adapters/codex.md

@@ -0,0 +1,45 @@
+# Codex Lead Runtime Adapter
+
+## Scope
+
+This adapter maps the neutral Okstra lead operations to the Codex artifact-first CLI path. Read it only when the rendered launch prompt selects `leadRuntime=codex`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `codex` |
+| `leadRoleLabel` | `Codex lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `cli-wrapper` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `artifact-checkpoint` |
+| `teardownMode` | `process-cleanup` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current host's file interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the host text/question interface and stop at approval gates until an explicit answer arrives. |
+| `dispatch_worker` | Run `okstra codex-dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `await_workers` | Treat the synchronous dispatch return plus team-state terminal records and Result Paths as completion evidence. |
+| `redispatch_worker` | Invoke a fresh `okstra codex-dispatch` worker attempt for the selected role and record the retry/reverify dispatch kind. |
+| `shutdown_workers` | Perform process cleanup when a wrapper remains live; otherwise this operation is a no-op recorded in state. |
+| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `collect_usage` | Collect artifact/rollout-backed usage through the existing Okstra token-usage path; never read Claude session JSONL as a substitute. |
+
+## Codex dispatch details
+
+- Do not invoke Claude Code team or subagent tools.
+- The prepared run manifest and team-state are the dispatch authority. Unsupported explicitly requested workers fail; an adapter must not silently change the roster.
+- Report-writer execution keeps the existing explicit opt-in policy in this milestone: dispatch requires `--enable-codex-report-writer` and an explicit `--report-writer-codex-model` value.
+- Reverify and critic retries invoke a fresh worker attempt and persist the core-supplied `dispatchKind` (`reverify-r<N>` or `critic`) in the dispatch record; never reuse a prior rollout as a new vote.
+- Report-writer completion requires both the data.json Result Path and the worker-results audit path, even when the synchronous dispatch command exits successfully.
+
+## Completion, cleanup, and resume
+
+- A successful synchronous dispatch return alone is insufficient; verify terminal state, every required completion path, and the corresponding worker-dispatch audit record before counting the worker as complete.
+- Resume from run artifacts and lead-events checkpoints. Do not invent a Claude session id.

package/runtime/prompts/lead/adapters/external.md

@@ -0,0 +1,46 @@
+# External Lead Runtime Adapter
+
+## Scope
+
+This adapter maps the neutral Okstra lead operations to a generic host using Okstra-owned tmux panes. Read it only when the rendered launch prompt selects `leadRuntime=external`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `external` |
+| `leadRoleLabel` | `Okstra lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `tmux-pane` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `artifact-checkpoint` |
+| `teardownMode` | `pane-teardown` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current host's file or shell interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the host text/question interface and require an explicit approval or clarification response. |
+| `dispatch_worker` | Run `okstra team dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `await_workers` | Run `okstra team await --project-root <root> --run-manifest <path>` through the host's asynchronous shell facility. |
+| `redispatch_worker` | Create the core-specified fresh jobs file and dispatch it with a new `dispatchKind`; never reuse a live worker conversation. |
+| `shutdown_workers` | Run `okstra team teardown --project-root <root> --run-manifest <path>` only after the user-approved cleanup gate. |
+| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `collect_usage` | Collect artifact/CLI-log-backed usage through the existing Okstra token-usage path; never substitute another runtime's session log. |
+
+## External dispatch details
+
+- Do not invoke Claude Code team tools or `okstra codex-dispatch`.
+- Worker completion is valid only from `workerDispatches[]`, terminal status sidecars, and required Result Paths. Pane creation alone is not completion.
+- Reverify uses a fresh jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json`, sets `dispatchKind: "reverify-r<N>"`, and dispatches with `okstra team dispatch --project-root <root> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>`.
+- Report-writer uses a fresh one-job jobs file with `dispatchKind: "report-writer"` and the same schema, then dispatches through `okstra team dispatch --project-root <root> --run-manifest <path> --jobs-file <jobs-file>`.
+- Every reverify or report-writer jobs file carries `workerId`, `provider`, `role`, `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`. For reverify, set `role` to `worker-reverify-r<N>` for the pane title. The report-writer completion paths include both data.json and the worker-results audit file.
+- After either dispatch, run `okstra team await --project-root <root> --run-manifest <path>` before evaluating terminal status or completion paths.
+
+## Completion, cleanup, and resume
+
+- Await through `okstra team await`; raw Result Path polling is forbidden for this backend.
+- Resume from run artifacts and lead-events checkpoints. After usage collection, persistence, and the core user-approval gate, run `okstra team teardown --project-root <root> --run-manifest <path>` and tear down only Okstra-owned panes recorded for the run.

package/runtime/prompts/lead/context-loader.md

@@ -81,10 +81,10 @@ After identifying the task root in `task-manifest.json`, derive all paths accord
 │   └── <task-type>/            (Run scope isolated per task-type, e.g. error-analysis)
 │       ├── manifests/          (run-manifest-<task-type>-<seq>.json)
 │       ├── state/              (team-state-<task-type>-<seq>.json, convergence-<task-type>-<seq>.json)
-│       ├── prompts/            (claude-execution-prompt-<task-type>-<seq>.md and worker prompt history files)
+│       ├── prompts/            (run prompt path and worker prompt history paths recorded in the manifest)
 │       ├── reports/            (final-report-<task-type>-<seq>.md)
 │       ├── status/             (final-<task-type>-<seq>.status)
-│       ├── sessions/           (claude-resume-<task-type>-<seq>.sh)
+│       ├── sessions/           (runtime-specific resume artifacts when the selected adapter supports them)
 │       ├── logs/               (errors-<task-type>-<seq>.jsonl, optional)
 │       └── worker-results/
 │           ├── claude-worker-<task-type>-<seq>.md
@@ -147,6 +147,6 @@ Information produced after completing this contract:
 - Reference list of config files/deployment manifests and task-level expected values
 - Current run status and presence of existing worker results
 - Current run prompt history contract for attempted workers
-- Candidate `teamName` for Phase 3 hand-off: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule); implementation stage runs append `-s<N>` — the launch prompt's Teammate Dispatch Gate block carries the final name verbatim
-- Current Claude `lead.sessionId` (the in-flight Claude Code session) — required by `team-contract` when registering the lead in `team-state.json`
-- Resume command path: from `task-manifest.json` → `latestResumeCommandPath` (fallback: latest `runs/<task-type>/sessions/claude-resume-*.sh` by mtime). Never reconstruct the filename — the `<seq>` counter is category-local and may diverge from `manifests/`.
+- Candidate `teamName` for the manifest/team-state audit identity: `okstra-<task-key>` (with task-key slugified per Step 1's slug rule); implementation stage runs append `-s<N>`. The selected runtime adapter owns whether an adapter-specific audit label is exposed in the launch prompt's "Runtime Adapter Dispatch Gate (BLOCKING)" setup facts; this common contract does not guarantee that label for every runtime.
+- Current lead session/checkpoint identity, when supplied by the selected adapter
+- Resume artifact path from `task-manifest.json.artifacts.resumeCommandPath`; never reconstruct a runtime-specific filename

package/runtime/prompts/lead/convergence.md

@@ -12,7 +12,7 @@
   - [Convergence Test](#convergence-test)
 - [Verification Mode](#verification-mode)
 - [Adversarial Verification Mode](#adversarial-verification-mode)
-- [Re-verification Agent Dispatch](#re-verification-agent-dispatch)
+- [Re-verification Dispatch](#re-verification-dispatch)
 - [Convergence State Artifact](#convergence-state-artifact)
 - [Coverage critic pass](#coverage-critic-pass)
 - [Acceptance critic pass (final-verification)](#acceptance-critic-pass-final-verification)
@@ -74,7 +74,7 @@ Read the worker result files generated in Phase 4/5 and extract individual findi
    - Items with multiple tickets (e.g. `TICKET-123, TICKET-456`) expand to a set of ticket keys.
    - Items tagged `unknown` keep the literal `unknown` as their ticket key.
 2. For each finding, record the summary, evidence (file path, line number, basis), the worker who identified it, **the worker-internal item ID assigned by that worker** (e.g. `F-001`, `1.1`, `F-3` — see `prompts/profiles/_common-contract.md` "Cross-worker traceability" SSOT), and the parsed ticket set. The item ID is persisted on the finding record as `findings[].discoveredBy.<worker>.itemId` and on each cross-worker confirmation as `findings[].sourceItems[]` (one entry per contributing `<worker>:<item-id>` pair). The final-report's `## 6.1 Consensus` / `## 6.2 Differences` / `## 2.1 Primary Evidence` tables read this list verbatim into their `Source items` columns — without this, the synthesised `C-NNN` row has no traceable link back to the original worker wording.
-3. Claude Lead groups findings based on semantic similarity AND ticket-set equality:
+3. The lead groups findings based on semantic similarity AND ticket-set equality:
   - Same semantics + same ticket set across 2+ workers → immediately reach `full consensus`.
   - Same semantics but disjoint ticket sets → keep as separate groups (do NOT over-merge across tickets).
   - Only one worker confirms a finding → `unique`, enter the verification queue.
@@ -165,7 +165,7 @@ A reverify dispatch that returns a **terminal non-result** (`timeout`, `error`,
 Rules:
 
 1. For each affected finding, append a `votes[W].verdict = "verification-error"` entry instead of `disagree`, plus the wrapper's captured exit reason in `votes[W].explanation`.
-2. Record one event per failed dispatch via `okstra error-log append-observed --error-type cli-failure --agent <worker> ...` (the worker wrapper does this for Codex/Antigravity; for Claude worker timeouts the lead does it).
+2. Record one event per failed dispatch via `okstra error-log append-observed --error-type cli-failure --agent <worker> ...` (the worker wrapper does this for wrapper failures; for in-process worker timeouts the lead does it).
 3. Add an entry to the round's `skippedWorkers[]` with `{worker: <W>, reason: "dispatch-non-result", terminalStatus: <timeout|error|not-run>}`.
 4. If at least one dispatch was issued AND all reverify dispatches in a round terminate as non-result (mirroring the pseudocode's `len(dispatches) > 0` guard), the round is treated as gate-closed: write `round2SkippedReason: "all-reverify-non-result"` (even if the round in question is round 1 — i.e. round 2 never runs because round 1 produced no usable votes), record one `contract-violation` event per non-result dispatch, and exit the WHILE loop.
 5. Section 6 (Specialization Lens) of a worker output is OUT of convergence scope per "Convergence scope" above — its absence is NEVER a `verification-error`.
@@ -248,31 +248,16 @@ ELSE:
 
 Design intent: one `counter-evidence` refute is enough to deny a claim consensus (it cannot rise above `contested` no matter how many others AGREE), while a single `burden-not-met` doubt does not by itself sink an otherwise-surviving claim — only a majority of burden-not-met doubts does. When every non-discoverer refutes (all_others_disagree), the finding is worker-unique regardless of whether those refutes were counter-evidence or burden-not-met — only the discoverer still holds it. A SUPPLEMENT/caveat with zero disagrees lands partial-consensus rather than full-consensus, because a caveat means the claim does not pass cleanly (this differs from the collaborative classifier, where SUPPLEMENT counts as full agreement).
 
-## Re-verification Agent Dispatch
+## Re-verification Dispatch
 
 ### Sponsorship Optimization
 
-Processing is performed by spawning each worker once per round. All findings to be verified by that worker are included in a single prompt.
+For each analysis worker with a non-empty current round's `items_for_W` batch, build one reverify prompt and call `redispatch_worker(assignment, prompt, reason)` exactly once per worker through the selected runtime adapter. The batch contains only that worker's eligible findings from the current verification queue; final classification labels never select dispatch targets. The assignment, model, prompt path, Result Path, worker-results path, errors paths, and `dispatchKind` come from the current run artifacts. Every reverify is a fresh one-shot session.
 
-```text
-Agent(
-  description: "Re-verify findings for <task-key> round <N>",
-  prompt: "<re-verification prompt with findings batch>",
-  name: "<role-slug>-reverify-r<N>",
-  subagent_type: "<same as initial execution>",
-  run_in_background: true,   # no team_name — implicit team; see team-contract Operating Rule 0
-  model: "<same as initial execution>",
-  mode: "auto"
-)
-```
-
-- Claude / in-process worker: spawn with `Agent(name: ..., run_in_background: true)` per [team-contract](./team-contract.md) rule 0 (split-pane when `$TMUX` is set)
-- CLI (Codex / Antigravity) worker: inject `**Pane role:** worker-reverify-r<N>` (the Agent `name` minus the `<cli>-` prefix) into the reverify prompt body so the tmux trace pane reads `<cli>-worker-reverify-r<N>` per [okstra-lead-contract](./okstra-lead-contract.md) "Agent `name` on dispatch".
+Call `await_workers(handles)` through the same adapter and apply the shared terminal-status/completion-path contract before counting a vote. The selected adapter owns native invocation spelling and any jobs-file/CLI fields. This contract owns only the reverify payload and verdict semantics.
 
-For `tmux-pane` backend runs, do not use the Agent snippet. For each reverify round, write a jobs file at `runs/<task-type>/state/reverify-jobs-r<N>-<task-type>-<seq>.json` with `dispatchKind: "reverify-r<N>"` and worker entries containing `workerId`, `provider`, `role` (set to `worker-reverify-r<N>` for the pane title), `modelExecutionValue`, `promptPath`, `resultPath`, `workerResultPath`, and `completionPaths`; then run `okstra team dispatch --project-root <dir> --run-manifest <path> --dispatch-kind reverify-r<N> --jobs-file <jobs-file>` followed by `okstra team await --project-root <dir> --run-manifest <path>`.
 
-
-**Completion detection per round (BLOCKING).** The spawn acks are NOT completion — detect each round's completion via the SSOT protocol in [team-contract](./team-contract.md) "Worker-completion detection (self-scheduled polling)", with the pending set reconstructed from that round's dispatched workers' Result Paths. Do NOT end the turn with a prose "waiting" statement.
+**Completion detection per round (BLOCKING).** A dispatch acknowledgement is NOT completion — detect each round's completion via the SSOT protocol in [team-contract](./team-contract.md) "Worker-completion detection", with the pending set reconstructed from that round's dispatched workers' Result Paths. Do NOT end the turn with a prose "waiting" statement.
 
 ### Required reverify-prompt anchor headers (BLOCKING)
 
@@ -292,9 +277,7 @@ Assigned worker prompt history path: <Project Root>/<Prompt History Path>
 2. `team-state-<task-type>-<seq>.json` → `workers[].usage.cliModel` for that role (initial run's actual execution value)
 3. The `**Model:**` line of the initial Phase 4 prompt for that role (read from its persisted prompt-history file)
 
-If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra error-log append-observed`. Do NOT guess, do NOT fall back to training-data defaults — for codex this silently produces `o4-mini` instead of the assigned `gpt-5.6`-class model.
-
-For Codex/Antigravity wrapper subagents, the `**Model:** <role>, <modelExecutionValue>` line is what their wrapper extracts to pass into the underlying CLI's `--model` flag. Omitting it forces the wrapper to fall back to its own training-data knowledge of the CLI's historical default.
+If none of the three is available, **abort the reverify dispatch for that role** and record a `contract-violation` event via `okstra error-log append-observed`. Do NOT guess or fall back to a runtime default. The selected adapter receives the exact value through the assignment and owns how it reaches the worker runtime. The current Codex catalog default is `gpt-5.6-sol`, but that reference value never replaces the manifest assignment.
 
 ### Reverify prompt: required-reading suppression
 
@@ -524,8 +507,8 @@ The critic input is the Round 0 consolidated finding list. Reverify rounds only
 - **Dispatch**: immediately after Round 0 grouping, CONCURRENTLY with the first reverify round's dispatches. When the verification queue is empty after Round 0 (no reverify round runs), dispatch right after grouping. Concurrent dispatch to the same provider is safe — the critic result path (`<provider>-critic-...`) never collides with a reverify result path.
 - **Gap verification + merge**: only after BOTH the finding-convergence loop has exited AND the critic result is collected, and BEFORE the Phase 6 report-writer dispatch. If the loop exited `aborted-non-result`, do NOT dispatch a gap-verification round — surface the gaps as unverified `clarification` items per §"Gap verification" and record that fact.
 
-### Dispatch (reused worker)
-Dispatch ONE pass to the `config.critic.provider`'s existing subagent (`claude-worker` / `codex-worker` / `antigravity-worker`) with `model = config.critic.modelExecutionValue` — no new agent type, `name: "<provider>-worker-critic"`. If `config.critic.modelExecutionValue` is null/empty (model could not be resolved), skip the critic pass and record `critic-skipped: model-unresolved` in the convergence state rather than dispatching with no model. For a CLI (Codex / Antigravity) critic dispatch, inject `**Pane role:** worker-critic` into the prompt body so the trace pane reads `<cli>-worker-critic` per [okstra-lead-contract](./okstra-lead-contract.md) "Agent `name` on dispatch". Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
+### Dispatch (fresh one-shot)
+Dispatch one fresh pass to `config.critic.provider` through `redispatch_worker`, with `model = config.critic.modelExecutionValue` and `dispatchKind = "critic"`. If the model value is empty, record `critic-skipped: model-unresolved`; never dispatch without a model. Result path: `runs/<task-type>/worker-results/<provider>-critic-<task-type>-<seq>.md`. The critic prompt seeds the consolidated findings and asks ONLY for coverage gaps:
 
 ```
 You are the coverage critic for <task-key>. Below are the consolidated findings
@@ -546,7 +529,7 @@ Each critic gap enters the verification queue as a finding with `originWorker =
 
 ## Acceptance critic pass (final-verification)
 
-The `final-verification` phase reuses the SAME reused-worker dispatch AND the same dispatch timing as §"Coverage critic pass" §"When" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule) — the delivered work the critic inspects is likewise fixed before the reverify round starts. Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
+The `final-verification` phase uses the same fresh one-shot `redispatch_worker` pattern and the same dispatch timing as §"Coverage critic pass" §"When" (provider + `config.critic.modelExecutionValue` from the `convergence.critic` block; default off; same model-unresolved skip rule) — the delivered work the critic inspects is likewise fixed before the reverify round starts. Only the prompt, the verification semantics, and the output sink differ — final-verification's findings are defects/blockers, so the critic acts as an **acceptance devil's advocate** (find reasons NOT to accept), and its candidate blockers are NEVER dropped (that would suppress real defects).
 
 ### Prompt