okstra 0.163.2 → 0.164.0

package/README.md

@@ -20,7 +20,7 @@
 <a id="purpose"></a>
 ## 1. Purpose
 
-`okstra` is a **host-aware, multi-provider task runner that cross-verifies work with a lead + worker model**. The current Claude Code, Codex, or Antigravity host supplies the native lead session; every other selected provider runs through its registered CLI wrapper. Claude remains the compatibility default policy, not the owner of the lifecycle.
+`okstra` is a **host-aware, multi-provider task runner that cross-verifies work with a lead + worker model**. A registered host adapter supplies the lead session, while a separate provider adapter supplies models and worker execution. Claude remains the compatibility default policy, not the owner of the lifecycle.
 
 The design rests on three principles:
 
@@ -35,10 +35,12 @@ Role assignments are persisted separately from the host runtime, but the lead pr
 | Claude | Claude Code | `okstra-claude-exec.sh` | lead, analysis, implementation, report writer |
 | Codex | Codex | `okstra-codex-exec.sh` | lead, analysis, implementation, report writer |
 | Antigravity | Antigravity CLI | `okstra-antigravity-exec.sh` | lead, analysis, and implementation |
-| Grok | none | `okstra-grok-exec.sh` | read-only analyser and critic |
-| Kimi | none | `okstra-kimi-exec.sh` | read-only analyser and critic |
+| Grok | Grok CLI | `okstra-grok-exec.sh` | lead, read-only analyser, and critic |
+| Kimi | Kimi CLI | `okstra-kimi-exec.sh` | lead, read-only analyser, and critic |
 
-Grok and Kimi are intentionally read-only in this release. Their wrappers, model aliases, installation, diagnostics, and usage-pricing paths are integrated, but a real authenticated local invocation still depends on the corresponding CLI being installed and configured.
+Grok and Kimi can now lead through their registered host adapters. Their worker roles remain read-only analyser and critic; executor, verifier, and report-writer roles were not added. A real authenticated local invocation still depends on the corresponding CLI being installed and configured.
+
+`okstra run <host-id-or-alias>` resolves the requested adapter from the host registry and checks its `spawn-process` readiness before starting it. The installed `okstra-run` skill instead uses `current-session`: it declares only the semantic functions the live harness can actually perform (`plain_text_input`, plus any available native single-select, multi-select, or grouped-question function) and reuses the current lead session. User-installed adapters are discovered only from `~/.okstra/adapters/hosts/<id>/` and `~/.okstra/adapters/providers/<id>/`; project-local executable adapter code is ignored.
 
 The next direct-CLI candidates are Mistral Vibe and Qwen Code. DeepSeek V4, GLM-5.2, and MiniMax M2.7 remain API-adapter candidates because their current official coding-agent execution surfaces do not fit Okstra's wrapper contract as directly. Newly published provider models are exposed only after the corresponding local CLI reports them; this keeps model discovery separate from marketing availability.
 
@@ -225,7 +227,7 @@ Major workflow changes added to `main` after 0.8.0:
 - **`release-handoff` lifecycle phase** — runs immediately after `final-verification` returns `verdict=accepted`. The current Okstra lead drafts the candidate messages and PR body inline, then uses the selected host adapter's user-prompt operation for the delivery choices. Only the Git/GitHub CLI commands selected through those menus are run. Force pushes, direct pushes to the base branch, hook bypasses (`--no-verify`), and release publication (`gh release`, `npm publish`, and similar commands) are prohibited. This phase does not edit source code. Profile: [`prompts/profiles/release-handoff.md`](prompts/profiles/release-handoff.md).
 - **Configurable PR body template** (release-handoff) — PR bodies are populated from a Markdown template selected in this order: one-time override (`--pr-template-path` or the okstra-run Step 6 prompt) → `prTemplatePath` in `<project_root>/.okstra/project.json` → `prTemplatePath` in `~/.okstra/config.json` → the skill default at `~/.claude/skills/templates/prd/pr-body.template.md`. Register a template with `okstra config set pr-template-path <path> [--scope project|global]`; project scope accepts a path relative to the project root, while global scope requires an absolute path or a path beginning with `~/`. `okstra config get pr-template-path --scope all` prints every scoped value and the effective winner. The default template contains `## Summary`, `## Changes`, `## Test plan`, and `## Linked issues`, plus HTML comment guidance that the lead removes immediately before PR creation.
 - **Profile worker-roster validation** — `--workers <csv>` and the okstra-run Step 6 worker prompt accept only the worker IDs declared in the selected profile's `Required workers:` block. Requesting a worker absent from the profile—for example, `codex` or `antigravity` for `release-handoff`—fails with a clear error, and the interactive prompt shows only workers accepted by that profile.
-- **Host-aware lead adapters** — the same `okstra-run` skill resolves Claude Code to `leadRuntime=claude-code`, Codex to `leadRuntime=codex`, Antigravity CLI to `leadRuntime=antigravity`, and another explicit host to `external`. Claude Code keeps Claude assignments native, Codex keeps Codex assignments native, and Antigravity keeps Antigravity assignments native; every other selected provider runs through its registered CLI wrapper. The lead provider is derived from the host and cannot be replaced independently. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
+- **Host-aware lead adapters** — `okstra-run` resolves the current harness through the same dynamic host registry used by the terminal front door. Claude Code, Codex, Antigravity, Grok, and Kimi keep their matching provider assignment native; `external` remains the explicit all-CLI host. Host and provider are separate axes, and every non-native worker assignment uses its provider's registered CLI wrapper. `leadAssignment` and every `workerAssignments[]` row record provider, model, and `runner`. `okstra codex-run` and `okstra codex-dispatch` remain low-level artifact/dispatch commands.
 - **Multi-stage `implementation-planning` / `implementation`** — `implementation-planning` always produces a Stage Map and N stage sections. Each stage has no more than six steps, and stages with `depends-on (none)` can be implemented concurrently in separate `implementation` runs. Each `implementation` invocation runs a single stage, selected with `--stage <auto|N>`, and creates an evidence sidecar at `carry/stage-<N>.json` for automatic carry-in to the next stage. The `implementation-planning` run directory accumulates `consumers.jsonl` reverse links that record which run consumed each stage.
 - **AI-prepared design preparation (implementation-planning → implementation)** — `implementation-planning` detects which stages need design input (domain contract, DB/table schema, external interface, transaction/consistency, transformation mapping, lifecycle, rollout/observability, manual user test) and has the AI draft a concrete proposal first, instead of handing the user an empty design document. Each item is assessed as `ready`, `provisional`, `blocked`, or `not-applicable`; a simple task may declare `no-design-inputs`. Phase 7 materializes an Okstra-owned request under `design-prep-requests/`, and `okstra design-prep <list|show|write>` or the okstra-run wizard records the confirmed answer as an **append-only** revision under `design-prep-inputs/`—neither path ever edits the approved planning snapshot. Before creating its worktree, `implementation` resolves only the items its selected stage cites in `stageRefs`: safe `provisional` assumptions are injected into the executor prompt so work proceeds, while an unsafe open decision makes only that stage wait or replan. A markerless legacy plan continues with a `legacy-unassessed` warning. Storage authorities: [`docs/architecture/storage-model.md`](docs/architecture/storage-model.md). CLI: [`docs/cli.md#okstra-design-prep`](docs/cli.md#okstra-design-prep).
 - **Phase 6 plan-body verification (implementation-planning only)** — Immediately after the report-writer worker drafts the final report and before the user approval gate, the lead performs one post-verification round. It extracts `P-Opt-*`, `P-Step-*`, `P-Dep-*`, `P-Val-*`, and `P-Rb-*` plan items from the synthesized `## 5.5` implementation plan deliverables and asks every analyzer worker for an `AGREE`, `DISAGREE(a-e)`, or `SUPPLEMENT` verdict. The aggregate result is `passed`, `passed-with-dissent`, `blocked-by-disagreement`, or `aborted-non-result`. The frontmatter `approved` field is always published as `false`; a blocking result keeps it false and becomes a row in `## 1. Clarification Items`. For fast iteration, opt out with `--no-plan-verification`. Contract details: the "Plan-body verification mode" section of [`prompts/lead/convergence.md`](prompts/lead/convergence.md) and [`docs/cli.md#--no-plan-verification`](docs/cli.md#--no-plan-verification).

package/docs/architecture.md

@@ -16,7 +16,7 @@ Its core capabilities at a glance are:
 - **Profiles by task type**: Loads standard task-type profiles such as `requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, and `release-handoff` to render the instruction set.
 - **Run lifecycle**: Non-stage runs use `runs/<task-type>/` as the run directory, while `implementation` and single-stage `final-verification` use `runs/<task-type>/stage-<N>/`. Manifests, prompts, state, reports, sessions, worker results, and logs accumulate beneath the resolved run directory, and the filename suffix `-<task-type>-<seq>` separates reruns of the same phase.
 - **Single python authority**: All prepare wiring—resolving profiles/workers/models, computing paths, rendering, and central record_start—is concentrated in a single function, [`okstra_ctl.run.prepare_task_bundle()`](../scripts/okstra_ctl/run.py). `okstra.sh` and the `okstra-run` skill are thin callers of that same function and do not pass state through environment variables. Task identity, paths, and workflow state are recalculated from authoritative on-disk files every time.
-- **Host-aware handoff**: Claude Code, Codex, and Antigravity keep their current native session as the lead. The standalone compatibility launcher still starts a new `claude` process by default, while the external adapter uses registered CLI wrappers. Every path consumes the same `prepare_task_bundle` outputs.
+- **Host-aware handoff**: Claude Code, Codex, Antigravity, Grok, and Kimi can keep their current native session as the lead. The standalone compatibility launcher still starts a new `claude` process by default, while the external adapter uses registered CLI wrappers. Every path consumes the same `prepare_task_bundle` outputs.
 - **Required team contract**: The `Required workers:` block in each phase profile is authoritative for the roster. General analysis phases use Claude/Codex analysers plus a report writer by default, while Antigravity, Grok, and Kimi are included only when allowed by both the profile and `--workers`. Lead-oriented phases such as `release-handoff` have separate rosters.
 - **User-home install + project-local task bundles**: One `npx okstra@latest install` command installs the runtime (`~/.okstra/{lib/python, bin, templates, prompts}`) and installs public skills to `~/.agents/skills/` by default. If `~/.claude` exists, it also installs Claude skills and six worker agent definitions (`~/.claude/agents/*-worker.md`). Only user entry-point skills are exposed in the skill list; lead/support operating contracts are installed as runtime resources under `~/.okstra/prompts/` and are not discoverable as skills. Global conversation memory is stored separately from projects under `~/.okstra/memory-book/`. Task bundles and discovery metadata are stored under `.okstra/` in the target project. **In addition, `<PROJECT_ROOT>/.claude/settings.local.json` is provisioned as a symlink to `~/.okstra/templates/settings.local.json`** (`okstra setup` or `okstra-ctl` prepare manages it idempotently; if a regular file already existed, it is preserved as `.bak.<timestamp>` before replacement).
 - **Resume and clarification**: Supports resuming the same task and responding to follow-up questions from the lead through `--task-key`, `--resume-clarification`, and `--clarification-response`.
@@ -149,9 +149,9 @@ Runtime entry points are consolidated in Python packages. Bash and skills only c
 - `prompts/lead/adapters/claude-code.md`, `prompts/lead/adapters/codex.md`, `prompts/lead/adapters/antigravity.md`, and `prompts/lead/adapters/external.md` map the same semantic operations to one selected host runtime. The generated launch prompt exposes the core path plus exactly one adapter path.
 - `prompts/lead/adapters/cmux.md` is selected by environment rather than by runtime: when the run manifest's `terminalBackend` is `cmux-pane`, every lead runtime resolves to it and dispatches through `okstra team`, because okstra owns the worker panes on that path instead of the host. It overrides only the adapter and the dispatch mode; the lead's agent, role, and session accounting still come from its own runtime.
 - Runtime metadata and role assignments are persisted separately, but the lead provider is derived from the host: Claude Code maps to Claude, Codex maps to Codex, and Antigravity CLI maps to Antigravity. New runs persist `hostRuntime`, `leadAssignment`, and `workerAssignments[]`; each assignment records its provider, model, execution value, and resolved `native-session` or `cli-wrapper` runner. `lead-execution-prompt.md` is canonical, while `claude-execution-prompt.md` is a byte-identical compatibility alias for historical consumers.
-- Provider registry and front-door separation are implemented: the active Claude Code, Codex, or Antigravity host owns the native lead session, while non-host providers run through their registered CLI wrappers.
+- Host and provider registries remain separate: the active registered host owns the native lead session, while non-native providers run through their registered CLI wrappers.
 - [`skills/okstra-setup/SKILL.md`](../skills/okstra-setup/SKILL.md) — **first-run bootstrap**. Runs `okstra install` and creates `project.json`.
-- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current Claude Code, Codex, or Antigravity session and calls `prepare_task_bundle` directly.
+- [`skills/okstra-run/SKILL.md`](../skills/okstra-run/SKILL.md) — host-aware in-session entry point that starts an okstra task in the current registered host session and calls `prepare_task_bundle` directly.
 - Thirteen skills are user-invocable: `skills/okstra-setup/SKILL.md`, `skills/okstra-brief-gen/SKILL.md`, `skills/okstra-run/SKILL.md`, `skills/okstra-manager/SKILL.md`, `skills/okstra-memory/SKILL.md`, `skills/okstra-inspect/SKILL.md`, `skills/okstra-rollup/SKILL.md`, `skills/okstra-usage/SKILL.md`, `skills/okstra-schedule-gen/SKILL.md`, `skills/okstra-container-build/SKILL.md`, `skills/okstra-pr-gen/SKILL.md`, `skills/okstra-user-response/SKILL.md`, and `skills/okstra-code-review/SKILL.md`. Only these are copied into the agent skill home. They cover brief authoring, phase execution, cross-project manager task coordination, global Memory Book storage/search, read-side status/history/report/time/logs/cost/errors/recap, task-group-level aggregation of run results (rollup), project-wide historical resource usage, schedule support, local container deployment, PR description generation, clarification-response submission, and census-based code review of a stage or branch diff. `okstra-manager` uses `okstra manager` CLI JSON/launch packets as the source of truth, and stores manager-owned plans, assignments, directives, snapshots, and events under `~/.okstra/managers/<manager-id>/`. `okstra-rollup` is a read-side layer that fans the single-task aggregators from `okstra-inspect` (time/errors/recap) out to a task group or the whole project catalog. The `okstra rollup` CLI owns deterministic aggregation, while the skill (LLM) writes only the synthesized report summary. `okstra-usage` is a separate read-only resource snapshot grouped by lifecycle task type; it does not replace single-task `okstra-inspect` detail or the status/report digest from `okstra-rollup`. The canonical definition of `okstra-inspect` read-side facets is the subcommand table in `skills/okstra-inspect/SKILL.md`. `okstra-inspect logs` provides a read-only inventory and cleanup guidance for the live-log sidecars that the Codex/Antigravity wrappers write on every dispatch at the resolved `<run-dir>/prompts/<worker>-prompt-<phase>-<seq>.log`; for stage executions, the stage-qualified `run_dir` includes `stage-<N>/`. `okstra-inspect cost` summarizes `okstra context-cost`; `okstra-inspect errors` collects a task's okstra-run error logs into a timestamped Markdown error report and prints a summary; and `okstra-inspect recap` answers free-form questions about `.okstra` artifacts in addition to summarizing phases before and after each task run.
 - Internal operating contracts—`context-loader` / `team-contract` / `convergence` / `report-writer` and the lead contract—have moved to `prompts/lead/*.md`. Language-specific coding preflight for implementation/verification workers has moved to `prompts/coding-preflight/*` (overview router + clean-code + three-stage language/framework/architecture selection). All are runtime resources installed under `~/.okstra/prompts/` and are not discoverable as skills. The generated launch prompt provides the lead with absolute paths, and reinstalling prunes the legacy exact-name skill directories `okstra-context-loader` / `okstra-team-contract` / `okstra-convergence` / `okstra-report-writer` / `okstra-coding-preflight` / `okstra`.
 - Plugin manifest: [`../../.claude-plugin/plugin.json`](../.claude-plugin/plugin.json) — referenced by the supplementary `npx skills@latest add Devonshin/okstra` channel. Use `npx okstra@latest install` for normal setup. The plugin manifest exposes only the thirteen user entry points (`okstra-setup`, `okstra-brief-gen`, `okstra-run`, `okstra-manager`, `okstra-memory`, `okstra-inspect`, `okstra-rollup`, `okstra-usage`, `okstra-schedule-gen`, `okstra-container-build`, `okstra-pr-gen`, `okstra-user-response`, `okstra-code-review`).
@@ -263,7 +263,9 @@ Other variables such as `PROJECT_ID`, `TASK_GROUP`, `RUN_*`, `FINAL_*`, and `CLA
 
 ## Host runtime execution behavior
 
-The front door declares its host from harness context, never by looking for installed provider binaries. Claude Code selects the Claude native session; Codex selects the Codex native session. Other selected providers resolve to CLI wrappers. A lead provider that disagrees with an in-session host is rejected before dispatch so the manifest cannot claim a model that never ran.
+Host adapters and model providers are independent axes. The host registry discovers bundled adapters and explicit user installs under `~/.okstra/adapters/hosts/<id>/`; the provider registry uses the parallel `~/.okstra/adapters/providers/<id>/` root. Neither registry executes adapter code found in a project repository. A host descriptor names its native provider, while every non-native worker assignment resolves through the provider's CLI wrapper.
+
+The terminal front door accepts `okstra run <host-id-or-alias>`, resolves it through `HostAdapterRegistry`, and probes `entry_mode="spawn-process"` readiness before starting that adapter's CLI. It does not infer the host from installed provider binaries and does not fall back to another host when the selected adapter is unavailable.
 
 The legacy standalone shell path remains Claude-specific:
 
@@ -274,10 +276,13 @@ The legacy standalone shell path remains Claude-specific:
 - `okstra.sh` performs only this compatibility handoff; the launched session continues under the same Okstra lead contract. Codex-hosted runs do not pass through this shell path.
 
 **Mode B — the `okstra-run` skill hands off within the current host session**
-- Use this when the user is already in Claude Code, Codex, or Antigravity and wants to start a new okstra task there.
-- The skill relays the wizard through the host question/text interface and calls `prepare_task_bundle(render_only=True)` with the explicit host runtime.
+- Use this when the user is already in a registered host and wants to start a new okstra task there.
+- The skill probes `entry_mode="current-session"`, reads the selected relay contract, and declares only the semantic functions the live harness actually exposes: `plain_text_input`, `native_single_select`, `native_multi_select`, and `native_question_group` as available. The wizard receives their intersection with the adapter contract instead of inferring capabilities from a host name.
+- The skill relays the wizard through that semantic interaction plan and calls `prepare_task_bundle(render_only=True)` with the explicit host runtime.
 - It does not launch another lead process. The current host-native session reads `lead-execution-prompt.md` and assumes the Okstra lead role.
 
+Kimi and Grok implement this same lead contract. Their provider roles remain `lead`, `analyser`, and `critic`; they do not gain executor, verifier, or report-writer roles from being lead-capable hosts.
+
 Both modes create identical artifacts (task-manifest, run-manifest, timeline, instruction set, and central-index registration), so subsequent `okstra-ctl` commands (list / show / rerun / reconcile) operate consistently without distinguishing between them.
 - The handed-off native host acts as the Okstra lead, responsible for orchestration and final synthesis.
 - The default worker policy remains Claude + Codex analysis and a Claude report writer. Antigravity, Grok, and Kimi are profile-gated optional assignments; Grok and Kimi are read-only analyser/critic providers.
@@ -602,7 +607,7 @@ On this standalone compatibility path, `okstra.sh` finishes the prepare stage an
 
 **Option B — hand off within the current host session (`okstra-run` skill)**
 
-If you are using Claude Code, Codex, or Antigravity, the current native session assumes the Okstra lead role without launching a replacement lead process. Example triggers: `"run okstra here"`, `"start error-analysis on this project"`.
+When using an installed host adapter, the current native session assumes the Okstra lead role without launching a replacement lead process. Example triggers: `"run okstra here"`, `"start error-analysis on this project"`.
 
 Skill flow:
 

package/docs/cli.md

@@ -59,7 +59,7 @@
 Base command for initial entry with full arguments:
 
 ```bash
-scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-runtime claude-code|codex|antigravity|external] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
+scripts/okstra.sh [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-runtime <host-id-or-alias>] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] [--work-category bugfix|feature|refactor|ops|improvement|unknown] [--base-ref <branch|tag|sha>] [--clarification-response <previous-final-report>] [--approved-plan <plan-path>] [--approve] --project-id <project-id> --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
 ```
 
 Analysis input ownership is narrower than the base shell command. The `/okstra-run` wizard collects `--analysis-target` and `--evidence-inputs` values and passes them internally to `node bin/okstra render-bundle`. `scripts/okstra.sh` does not accept either flag. Because `feature-analysis` requires a target, start that task type with the in-host skill; the two option sections below document the internal Node render inputs, not standalone shell options.
@@ -382,15 +382,18 @@ scripts/okstra.sh --task-type implementation-planning --workers claude,codex --p
 
 ### `--lead-runtime`
 
-Selects the lead execution adapter. The default is `claude-code`.
+Selects a lead adapter by registered host ID or alias. The default is `claude-code`. Terminal `okstra run <host-id-or-alias>` requests the same registry entry and verifies its `spawn-process` readiness before launch; an unavailable selected host is never replaced silently.
 
 Lead runtime independence boundary:
 
 - `claude-code`: the current default execution path. Claude Code v2.1.178 removed `TeamCreate`, and the session owns an implicit team. Workers are dispatched with `Agent(name: ..., run_in_background: true)` without `team_name`. `teamName` is audit/display metadata; Claude session JSONL is used for usage accounting.
 - `codex`: the runtime marker for the Codex lead adapter. `okstra codex-run` owns `--render-only --lead-runtime codex` to prepare a task bundle, and the prepared run manifest can be passed to `okstra codex-dispatch` for CLI-backed worker execution.
 - `antigravity`: the runtime marker for the Antigravity CLI lead adapter. The current Antigravity session owns the native lead, keeps Antigravity assignments native, and routes every other provider through its registered CLI wrapper.
+- `grok` and `kimi`: registered native lead adapters for their corresponding CLIs. They can lead, analyse, and criticise, but they do not add executor, verifier, or report-writer worker roles.
 - `external`: without Claude Code Teams, `--render-only --lead-runtime external` prepares the task bundle and external lead prompt. The lead manages the tmux-pane worker lifecycle with `okstra team dispatch`, `okstra team await`, and `okstra team teardown`. This path does not use `TeamCreate` / `Agent(...)` and uses artifact-only accounting.
 
+Host IDs and providers are separate axes. Bundled and user-installed host adapters resolve from the registry; user adapters must be installed under `~/.okstra/adapters/hosts/<id>/` or `~/.okstra/adapters/providers/<id>/`. Project-local adapter code is not discovered.
+
 The current Claude Code independence boundary covers the external lead prompt and `okstra team *` worker dispatch. non-render `okstra_ctl.run --lead-runtime external` remains blocked; a complete external lead driver remains separate future work. `--runtime external` only selects the runtime adapter. `okstra install` creates `~/.agents/skills/` by default and also installs Claude skills and agents when `~/.claude` exists. Selecting the `claude` worker still requires the local Claude CLI wrapper.
 
 Host-runtime readiness is independent of worker selection. When `/okstra-setup`
@@ -405,10 +408,10 @@ worker roster contains Claude, Codex, or Antigravity.
 
 ### Runtime auto-detection (`auto`)
 
-`okstra run` defaults to `auto`. `auto` resolves to one of `claude-code`, `codex`, `antigravity`, or `external` based on the host through `src/lib/runtime-resolver.mjs`. Precedence: explicit runtime > the `OKSTRA_RUNTIME_HOST` environment variable > Claude Code skill handoff > external when tmux is available > fail fast otherwise. The safe fallback never silently selects a runtime different from the user's intent, and the presence of the `agy` binary alone never selects the Antigravity host.
+`okstra run` defaults to `auto`. `src/lib/host-registry-client.mjs` asks the Python host registry to resolve explicit IDs and aliases, the `OKSTRA_RUNTIME_HOST` environment declaration, Claude Code skill handoff, or the external tmux claim. It fails fast when no adapter claims the session. Installed CLI presence alone never selects a host.
 
-- Inside a supported host, the installed `okstra-run` skill is the front door and reuses the session you are already in.
-- From a terminal, `okstra run <lead>` starts that lead itself: `okstra run` (Claude Code), `okstra run codex`, `okstra run antigravity`. The leading word is an alias for `--lead-runtime`.
+- Inside a registered host, the installed `okstra-run` skill uses `current-session`, declares the live semantic function list, and reuses the session you are already in.
+- From a terminal, `okstra run <host-id-or-alias>` uses `spawn-process` and starts the selected host CLI. The leading word is an alias for `--lead-runtime`.
 - `okstra run external` does not start a lead — it orchestrates an all-CLI run through `okstra team`.
 - Starting a lead whose CLI sandboxes itself prints what is given up and waits for a `y`; `--yes` answers it. Today only Codex asks, because a sandboxed lead can reach neither cmux nor the worker CLIs' own configuration.
 - In a generic terminal with tmux, `okstra run` orchestrates `render-bundle --lead-runtime external` -> `okstra team dispatch` -> `okstra team await`.

package/docs/project-structure-overview.md

@@ -145,7 +145,7 @@ Runtime/install asset changes follow this checklist:
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
-`src/lib/runtime-resolver.mjs` is the single reference point for runtime auto-detection. `src/lib/runtime-readiness.mjs` owns host-specific pre-dispatch readiness behind one provider-neutral result shape; its Claude Code adapter checks project workspace trust, while Codex and external hosts do not inspect Claude state. `okstra install` defaults to `--runtime auto`, records the request and any successful resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree even when host detection is unavailable. Skill targets always include the default Agent-compatible `~/.agents/skills` target, with `~/.claude/skills` also populated when `~/.claude` exists. Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`, not frozen into the install manifest. Claude Code skills pass explicit `--runtime claude-code` / `--lead-runtime claude-code` so they never depend on host auto-detection.
+`src/lib/host-registry-client.mjs` is the single Node boundary for host catalog, ID/alias resolution, and readiness probes. It delegates host policy to `okstra_ctl.entrypoints.hosts`; the Claude Code adapter checks project workspace trust, while other adapters own their own checks. `okstra install` defaults to `--runtime auto`, records the request and any successful resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree even when host detection is unavailable. Skill targets always include the default Agent-compatible `~/.agents/skills` target, with `~/.claude/skills` also populated when `~/.claude` exists. Dynamic capabilities are probed by the selected adapter rather than frozen into the install manifest.
 
 ---
 
@@ -303,7 +303,9 @@ Important modules:
 | `schema_excerpt.py` | generates a task-type-scoped excerpt of the final-report schema — a schema reduction to inject into the worker/lead prompt |
 | `work_categories.py` | requirements-discovery work-category (domain) **SSOT** (`is_valid_category`) — the work-category allowlist is defined only here |
 | `model_discovery.py` | pre-dispatch model-identity normalization for CLI workers — roster-gated label correction + a per-role reasoning-effort policy (deterministic, no per-run improvisation) for CLIs (agy) that bake effort into the model name |
-| `lead_runtime.py` | lead runtime metadata shared by the render and prepare paths (`LeadRuntimeInfo`) |
+| `domain/`, `application/`, `ports/` | Host-neutral values and errors, wizard/run use cases, and the interaction/session/dispatch/accounting port contracts |
+| `registry/host_registry.py`, `registry/provider_registry.py` | Discover bundled adapters plus explicit user installs under `~/.okstra/adapters/{hosts,providers}/<id>/`; project-local adapter code is outside the discovery roots |
+| `adapters/hosts/`, `adapters/providers/` | Six bundled host strategies and the independent provider catalogs; host manifests select a native provider without merging the two axes |
 | `lead_events.py` | structured JSONL events emitted by artifact-accounted lead runtimes |
 | `team_reconcile.py` | stale team-member reconciliation at run-end teardown |
 | `worker_prompt_headers.py` | shared rendering of phase-aware worker prompt anchors (`worker_prompt_headers`): coding-preflight only for implementation and compact target identity for final-verification |
@@ -406,7 +408,7 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 | Skill | User-invocable | Role |
 |---|---:|---|
 | `okstra-brief-gen` | yes | Produce task brief from ticket/doc/link/conversation |
-| `okstra-run` | yes | Start/resume an okstra task in the current Claude Code, Codex, or Antigravity host session |
+| `okstra-run` | yes | Start/resume an okstra task in the current registered host session |
 | `okstra-memory` | yes | Store/search/archive global conversation memory under `~/.okstra/memory-book` |
 | `okstra-inspect` | yes | Unified read-side — sub-commands `status` (lifecycle + workStatus), `history` (past runs / re-run / resume), `report` (find final-report), `time` (elapsed-time breakdown), `logs` (wrapper log inventory + cleanup), `cost` (task bundle context/read cost), `errors` (error-log aggregation), `error-zip` (anonymized cross-project error bundle), `run-audit` (progress-invariant audit over run artifacts), `error-issue` (anomaly → GitHub issue candidates, filed only after explicit approval), `recap` (cross-run phase recap). `SKILL.md` is a thin core (preflight + dispatch table + shared rules) and each sub-command body lives in `skills/okstra-inspect/facets/<sub-command>.md`, lazily read only after dispatch resolves; the 1:1 match between dispatch rows and facet files is enforced by `tests/contract/test_okstra_inspect_facets.py` |
 | `okstra-rollup` | yes | Cross-task roll-up — aggregate runs/time/errors across a task-group (or whole project) and synthesize a digest from the report files |
@@ -432,11 +434,11 @@ Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflig
 | `agents/workers/kimi-worker.params.json` | Kimi read-only analyser/critic wrapper params |
 | `agents/workers/report-writer-worker.md` | data.json SSOT author and audit sidecar writer |
 
-The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Host mappings live under `prompts/lead/adapters/`: `claude-code.md`, `codex.md`, `antigravity.md`, `external.md`, and `cmux.md` (the environment-selected cmux worker backend, read by every task type regardless of lead runtime). All are runtime resources installed under `~/.okstra/prompts/lead/`, not agent skills.
+The neutral lead lifecycle contract lives at `prompts/lead/okstra-lead-contract.md`. Executable host strategies and their relay contracts live together under `scripts/okstra_ctl/adapters/hosts/<host-id>/`; `prompts/lead/adapters/cmux.md` remains the environment-selected cmux worker-backend contract. Lead resources are installed under `~/.okstra/prompts/lead/`, while executable host adapters are installed under `~/.okstra/lib/python/okstra_ctl/adapters/hosts/`. They are runtime resources, not agent skills.
 
 ### 4.12 `tests/` and `tests-e2e/`
 
-- `tests/`: pytest modules, layered into per-domain subfolders — `run/` (prepare/dispatch/run-index core), `contract/` (validator, repo/docs contract, phase rules, profile), `report/` (render, convergence, language, template), `inspect/` (recap, error, context-cost, token-usage), `worktree/` (worktree, stage isolation, reconcile, reclaim), `wizard/`, `handoff/`. The shared path SSOT is `tests/_paths.py` (`REPO_ROOT`/`TESTS_DIR`/`FIXTURES`), and the setting that puts `tests/` on the import path is the repo-root `pytest.ini` (`pythonpath = tests`). Fixtures live in `tests/fixtures/`.
+- `tests/`: pytest modules organized by production boundary. `domain/wizard/` owns wizard state and answer behavior, `application/` owns use-case and render orchestration tests, and `adapters/{hosts,host_contract,providers,dispatch,accounting}/` owns external strategy contracts. Existing `run/`, `contract/`, `report/`, `inspect/`, `worktree/`, and `handoff/` folders retain their narrower responsibilities. The shared path SSOT is `tests/_paths.py` (`REPO_ROOT`/`TESTS_DIR`/`FIXTURES`), and the repo-root `pytest.ini` adds `tests/` to the import path. Fixtures live in `tests/fixtures/`.
 - `tests-e2e/`: `scenario-<id>-<name>.sh` shell scenarios (record-start/reconcile, rerun, task lock, agent install, report view, etc.).
 - Each behavior branch has one owning test at the lowest practical layer.
 - An end-to-end scenario must cross the public CLI or installed-runtime boundary.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.163.2",
+  "version": "0.164.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.163.2",
-  "builtAt": "2026-08-09T12:57:56.931Z",
+  "package": "0.164.0",
+  "builtAt": "2026-08-10T05:52:10.109Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -48,6 +48,7 @@ Unlike the Codex / Antigravity workers, you are an in-process Claude subagent
    - **Executor coding-conventions preflight (BLOCKING, before your first `Edit` / `Write`):** when dispatched as the `Executor`, you MUST run the coding-conventions preflight defined in the executor sidecar (`prompts/profiles/_implementation-executor.md` → "Pre-implementation context exploration") before writing any code. Use this worker prompt's `**Coding preflight pack:**` anchor header; read that pack's `overview.md` and `clean-code.md`, then follow the routed pack's language → framework → architecture stages, iterating every rule and loading every matching resource (for example `frameworks/node-server.md` and `architectures/hexagonal.md` when their conditions match). The preflight pack is a runtime resource, not an auto-invoked skill; read the files via the Read tool by absolute path.
    - **Executor post-write gates (BLOCKING, before your final commit / before claiming done):** the same dispatch prompt carries two gate blocks the lead appends after the preflight — `Pre-commit diff review sweep` (`prompts/profiles/_implementation-diff-review.md`) and `Implementation self-check` (`prompts/profiles/_implementation-self-check.md`). Execute both and record their coverage lines in your worker result exactly as the blocks specify. The codex/antigravity wrappers refuse to launch when an executor prompt lacks these blocks (`*_POSTWRITE_GATE_MISSING`); this worker runs in-process with no wrapper gate, so the contract lands on you directly — if either block is missing from your dispatch prompt, record a `tool-failure` in the errors sidecar and tell the lead to re-dispatch with the blocks included instead of skipping the gates.
    - **Verifier QA-gate exception:** verifier roles MAY use the same `cd <WORKTREE> && <cmd>` shape when executing project-declared `qaCommands` (lint / format / typecheck / test) from `project.json`, since those commands are cwd-sensitive by nature. Outside the QA gate, verifiers still read with absolute paths only — do NOT use `cd` for file inspection.
+   - **Shell commands must not be able to prompt:** this worker runs inside the host session, so its Bash calls see the user's own shell, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form. The confirmation that alias raises has nobody to answer it and the dispatch hangs until it is killed. Invoke these as `command cp` / `command mv` / `command rm` — alias expansion is skipped and the tool behaves exactly as written. Do not reach for `-f` instead; it also changes what the tool does on failure (`rm -f` reports success on a path that never existed).
    - **No extra chaining beyond `cd && cmd`:** the permission matcher only allows the exact two-segment shape `cd <PATH> && <single-command>`. Do NOT append additional pipes, semicolons, redirects, or `&&` chains — e.g. `cd ... && cargo test ... 2>&1 | tail -20; echo "exit:$?"` will trigger a permission prompt every dispatch because the trailing `| tail`, `; echo`, and `2>&1` tokens disqualify the prefix match against `Bash(cargo:*)`. Let Claude Code capture the full stdout/stderr and exit code natively — do not post-process with `tail`, `head`, or `echo "exit:$?"`. If output truncation is genuinely needed, run the command first and read the result in a separate tool call.
 
 5. **MCP usage**: The canonical list of MCP servers and tools available for this run lives in the analysis packet's `Available MCP Servers` section. If the section is absent or says none, treat MCP as unavailable for this run; never infer tools from host configuration. When the task requires inspection of an external system covered by a listed server, call the tool directly by name (e.g. `mcp__<server>__<tool>`). Do NOT shell out via `claude --mcp-cli call ...` or run the tool name as a Bash command — those are not valid invocation paths. If a server you need is not listed, record `MCP not available for this run` in your worker output rather than guessing a tool name.

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

@@ -54,6 +54,11 @@ while [[ $# -gt 0 ]]; do
       RESUME_CLARIFICATION_MODE="true"
       shift
       ;;
+    --resume-session)
+      RESUME_SESSION_MODE="true"
+      RESUME_SESSION_ID="$(require_option_value --resume-session "${2-}")"
+      shift 2
+      ;;
     --yes)
       ASSUME_YES="true"
       shift

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

@@ -16,6 +16,8 @@ OKSTRA_TASK_CATALOG_RELATIVE_PATH=""
 RENDER_ONLY="false"
 ASSUME_YES="false"
 RESUME_CLARIFICATION_MODE="false"
+RESUME_SESSION_MODE="false"
+RESUME_SESSION_ID=""
 WORKERS_OVERRIDE=""
 LEAD_MODEL_OVERRIDE=""
 LEAD_PROVIDER_OVERRIDE=""

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

@@ -3,10 +3,10 @@
 usage() {
   cat >&2 <<USAGE_EOF
 usage:
-  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--lead-runtime claude-code|codex|antigravity|external] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
+  $DISPLAY_COMMAND_NAME [--render-only] [--yes] [--no-plan-verification] --task-type <task-type> [--workers worker1,worker2] [--lead-provider <provider>] [--lead-model <model>] [--worker-model provider=model,...] [--report-writer-provider <provider>] [--report-writer-model <model>] [--lead-runtime <host-id-or-alias>] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity|grok|kimi] [--related-tasks taskA,taskB] --project-id <project-id> [--project-root <path>] --task-group <task-group> --task-id <task-id> --task-brief <brief-path> [--directive <directive>] [--fix-cycle <yes|no>]
 
 summary:
-  $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle. The standalone launcher defaults to an interactive Claude session; supported in-host skills keep the current Claude Code, Codex, or Antigravity session as the native lead.
+  $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle. The standalone launcher defaults to an interactive Claude session; in-host skills keep the current registered host session as the native lead.
   The stable task identifier is composed of project-id + task-group + task-id.
 
   Skills, worker agents, and the codex wrapper are installed once per user under
@@ -88,7 +88,7 @@ options:
   --yes                Skip interactive prompting and confirmation. Requires all required arguments.
   --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer.
                       Optional read-only providers: antigravity, grok, kimi.
-  --lead-provider      Compatibility assertion for the lead assignment. Must match the native Claude Code, Codex, or Antigravity host.
+  --lead-provider      Compatibility assertion for the lead assignment. Must match the selected host adapter's native provider.
   --lead-model         Model for the host-native lead. Default: the selected provider's lead policy.
   --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-sol
@@ -98,8 +98,8 @@ options:
                       Provider for report writer. Supported: claude, codex. Default: claude.
   --report-writer-model
                       Model for report writer worker. Default: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or sonnet
-  --lead-runtime      Lead runtime adapter. Default: claude-code. In-host runs use the
-                      matching native lead; non-host providers use CLI wrappers.
+  --lead-runtime      Registered host ID or alias. Default: claude-code. In-host runs
+                      use current-session; terminal launch uses spawn-process readiness.
   --executor           Provider that performs the Executor role during --task-type=implementation.
                       One of: claude | codex | antigravity. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
                       The Executor is the only worker allowed to mutate project files; the other two

package/runtime/bin/okstra.sh

@@ -58,10 +58,87 @@ okstra_py() {
   PYTHONPATH="$OKSTRA_PYTHONPATH:${PYTHONPATH-}" python3 "$@"
 }
 
+confirm_sandbox_waiver() {
+  local sandbox_note="$1"
+  local lead_executable="$2"
+  local cancel_message="$3"
+  local assume_yes_message="$4"
+  local sandbox_answer
+
+  [[ -z "$sandbox_note" ]] && return
+  printf '\n%s\n' "$sandbox_note" >&2
+  if [[ "$ASSUME_YES" == "true" ]]; then
+    [[ -n "$assume_yes_message" ]] && printf '%s\n\n' "$assume_yes_message" >&2
+    return 0
+  fi
+  printf 'Start %s without its sandbox? [y/N] ' "$lead_executable" >&2
+  read -r sandbox_answer < /dev/tty || sandbox_answer=""
+  if [[ "$sandbox_answer" != "y" && "$sandbox_answer" != "Y" ]]; then
+    printf '%s\n' "$cancel_message" >&2
+    exit 1
+  fi
+}
+
+execute_launch_plan() {
+  local cancel_message="$1"
+  local assume_yes_message="$2"
+  shift 2
+  local launch_plan_file
+  local sandbox_note
+  local env_count
+  local argv_offset
+  local lead_executable
+  local field
+  local -a launch_fields
+  local -a launch_env
+  local -a launch_argv
+
+  launch_plan_file="$(mktemp "${TMPDIR:-/tmp}/okstra-launch-plan.XXXXXX")"
+  if ! okstra_py -m okstra_ctl.entrypoints.hosts "$@" \
+    --format null > "$launch_plan_file"; then
+    rm -f "$launch_plan_file"
+    exit 1
+  fi
+  launch_fields=()
+  while IFS= read -r -d '' field; do
+    launch_fields+=("$field")
+  done < "$launch_plan_file"
+  rm -f "$launch_plan_file"
+  if [[ ${#launch_fields[@]} -lt 4 ]] || \
+    [[ ! "${launch_fields[2]}" =~ ^[0-9]+$ ]]; then
+    printf 'okstra: invalid launch plan\n' >&2
+    exit 1
+  fi
+  sandbox_note="${launch_fields[1]}"
+  env_count="${launch_fields[2]}"
+  argv_offset=$((env_count + 3))
+  if [[ ${#launch_fields[@]} -le $argv_offset ]]; then
+    printf 'okstra: invalid launch plan\n' >&2
+    exit 1
+  fi
+  launch_env=("${launch_fields[@]:3:env_count}")
+  launch_argv=("${launch_fields[@]:argv_offset}")
+  lead_executable="${launch_argv[0]}"
+  confirm_sandbox_waiver \
+    "$sandbox_note" "$lead_executable" "$cancel_message" "$assume_yes_message"
+  cd "${launch_fields[0]}"
+  exec env "${launch_env[@]}" "${launch_argv[@]}"
+}
+
 parse_cli_arguments "$@"
 split_task_key
 
 PROJECT_ROOT="$(resolve_project_root_safe "$PROJECT_ROOT_OVERRIDE")"
+if [[ "$RESUME_SESSION_MODE" == "true" ]]; then
+  if [[ -z "$PROJECT_ROOT" ]]; then
+    PROJECT_ROOT="$(resolve_project_root_strict "$PROJECT_ROOT_OVERRIDE")" || exit 1
+  fi
+  execute_launch_plan \
+    "okstra: resume cancelled" \
+    "" \
+    resume-plan --host "$LEAD_RUNTIME" --entry-mode spawn-process \
+    --project-root "$PROJECT_ROOT" --session-id "$RESUME_SESSION_ID"
+fi
 if [[ "$RESUME_CLARIFICATION_MODE" == "true" ]]; then
   if [[ -z "$PROJECT_ROOT" ]]; then
     PROJECT_ROOT="$(resolve_project_root_strict "$PROJECT_ROOT_OVERRIDE")" \
@@ -80,47 +157,11 @@ if [[ "$LAUNCH_ONLY" == "true" ]]; then
   if [[ -z "$PROJECT_ROOT" ]]; then
     PROJECT_ROOT="$(resolve_project_root_strict "$PROJECT_ROOT_OVERRIDE")" || exit 1
   fi
-  read -r LEAD_EXECUTABLE SANDBOX_NOTE < <(
-    okstra_py - "$LEAD_RUNTIME" <<'PY'
-import sys
-from okstra_ctl.lead_runtime import lead_runtime_info
-from okstra_ctl.models import bare_lead_launch_argv, lead_launch_spec
-provider = lead_runtime_info(sys.argv[1]).agent
-print(bare_lead_launch_argv(provider)[0], lead_launch_spec(provider).sandbox_waiver_note)
-PY
-  )
-  if ! command -v "$LEAD_EXECUTABLE" >/dev/null 2>&1; then
-    printf '%s command not found\n' "$LEAD_EXECUTABLE" >&2
-    exit 1
-  fi
-  if [[ -n "$SANDBOX_NOTE" ]]; then
-    okstra_py - "$LEAD_RUNTIME" <<'PY' >&2
-import sys
-from okstra_ctl.lead_runtime import lead_runtime_info
-from okstra_ctl.models import lead_launch_spec
-print("\n" + lead_launch_spec(lead_runtime_info(sys.argv[1]).agent).sandbox_waiver_note)
-PY
-    if [[ "$ASSUME_YES" != "true" ]]; then
-      printf 'Start %s without its sandbox? [y/N] ' "$LEAD_EXECUTABLE" >&2
-      read -r _sandbox_answer < /dev/tty || _sandbox_answer=""
-      if [[ "$_sandbox_answer" != "y" && "$_sandbox_answer" != "Y" ]]; then
-        printf 'okstra: cancelled\n' >&2
-        exit 1
-      fi
-    fi
-  fi
-  LAUNCH_ARGV=()
-  while IFS= read -r -d '' _arg; do LAUNCH_ARGV+=("$_arg"); done < <(
-    okstra_py - "$LEAD_RUNTIME" <<'PY'
-import sys
-from okstra_ctl.lead_runtime import lead_runtime_info
-from okstra_ctl.models import bare_lead_launch_argv
-for a in bare_lead_launch_argv(lead_runtime_info(sys.argv[1]).agent):
-    sys.stdout.write(a + "\0")
-PY
-  )
-  cd "$PROJECT_ROOT"
-  exec "${LAUNCH_ARGV[@]}"
+  execute_launch_plan \
+    "okstra: cancelled" \
+    "" \
+    launch-plan --host "$LEAD_RUNTIME" --entry-mode spawn-process \
+    --project-root "$PROJECT_ROOT"
 fi
 
 autofill_from_manifest
@@ -232,57 +273,12 @@ if [[ -z "$LAUNCH_JSON" ]]; then
   exit 1
 fi
 
-read -r LEAD_EXECUTABLE PROJECT_ROOT_FROM_PY < <(
-  okstra_py - "$LAUNCH_JSON" <<'PY'
-import json, sys
-d = json.loads(sys.argv[1])
-print(d["leadExecutable"], d["projectRoot"])
-PY
-)
-
-if ! command -v "$LEAD_EXECUTABLE" >/dev/null 2>&1; then
-  printf '%s command not found\n' "$LEAD_EXECUTABLE" >&2
-  exit 1
-fi
-
-# Starting some leads means lowering a protection that CLI applies to itself.
-# okstra never waives it silently: the note says what is given up, and nothing
-# starts without an explicit yes.
-SANDBOX_NOTE="$(
-  okstra_py - "$LAUNCH_JSON" <<'PY'
-import json, sys
-print(json.loads(sys.argv[1])["sandboxWaiverNote"])
-PY
-)"
-if [[ -n "$SANDBOX_NOTE" ]]; then
-  printf '\n%s\n' "$SANDBOX_NOTE" >&2
-  if [[ "$ASSUME_YES" == "true" ]]; then
-    printf 'Proceeding without the sandbox (--yes).\n\n' >&2
-  else
-    printf 'Start %s without its sandbox? [y/N] ' "$LEAD_EXECUTABLE" >&2
-    read -r SANDBOX_ANSWER < /dev/tty || SANDBOX_ANSWER=""
-    if [[ "$SANDBOX_ANSWER" != "y" && "$SANDBOX_ANSWER" != "Y" ]]; then
-      printf 'okstra: cancelled. The task bundle is prepared; rerun to resume it.\n' >&2
-      exit 1
-    fi
-  fi
-fi
-
-# NUL-separated so a prompt carrying newlines or quotes survives the handoff.
-LAUNCH_ARGV=()
-while IFS= read -r -d '' LAUNCH_ARG; do
-  LAUNCH_ARGV+=("$LAUNCH_ARG")
-done < <(
-  okstra_py - "$LAUNCH_JSON" <<'PY'
-import json, sys
-for arg in json.loads(sys.argv[1])["launchArgv"]:
-    sys.stdout.write(arg + "\0")
-PY
-)
-
 # Note: per-session --settings injection was removed. okstra-ctl prepare
 # provisions <PROJECT_ROOT>/.claude/settings.local.json as a symlink to
 # ~/.okstra/templates/settings.local.json, which Claude Code auto-loads
 # whenever it runs inside that project — no CLI flag required.
-cd "$PROJECT_ROOT_FROM_PY"
-exec "${LAUNCH_ARGV[@]}"
+execute_launch_plan \
+  "okstra: cancelled. The task bundle is prepared; rerun to resume it." \
+  "Proceeding without the sandbox (--yes)." \
+  launch-plan --host "$LEAD_RUNTIME" --entry-mode spawn-process \
+  --prepared-launch-json "$LAUNCH_JSON"

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

@@ -4,7 +4,7 @@
 
 This adapter maps the neutral Okstra lead operations to a cmux session, where Okstra owns the worker panes regardless of which model is leading. Read it only when the rendered launch prompt selects it; the run manifest's `terminalBackend` is `cmux-pane` for exactly those runs.
 
-It replaces the per-runtime adapter, not the lead contract. Your own runtime still decides how you read files, ask the user, and record your session — this file only decides how workers are started, awaited, and reclaimed.
+It overrides only the worker-dispatch portion of the selected host relay, not the host or lead contract. Your own runtime still decides how you read files, ask the user, and record your session — this file only decides how workers are started, awaited, and reclaimed.
 
 ## Capability declaration
 

package/runtime/prompts/lead/okstra-lead-contract.md

@@ -58,6 +58,7 @@ Read-side inspection (`/okstra-inspect`) and scheduling (`/okstra-schedule-gen`)
 - Standard worker roles remain `Claude worker`, `Codex worker`, `Antigravity worker`, and `Report writer worker`; these are provider/functional-role identities, not lead-runtime primitives.
 - `Report writer worker`, when in the roster, is the **author** of the final-report file. Lead reviews the draft and may request a revision via a follow-up dispatch, but MUST NOT write the report itself as a "shortcut". The only legal lead-authored fallback is when a Report writer worker dispatch was actually attempted and recorded a terminal status of `error`/`timeout`/`not-run` with an explicit reason in team-state — see [report-writer](./report-writer.md) "Lead-authored fallback".
 - "Session resume", "team is no longer alive", and similar are NOT valid reasons to skip Report writer worker dispatch — see [report-writer](./report-writer.md) "Resume-safe dispatch".
+- A shell command the lead runs must not be able to ask a question. The lead's shell is the user's own, where `cp`, `mv`, and `rm` are commonly aliased to their `-i` form; the confirmation that alias raises has nobody to answer it, so the call hangs until it is killed — observed as a `cp` over an existing state file stalling a whole self-fix round. Invoke these as `command cp` / `command mv` / `command rm`, which skips alias expansion and leaves the tool's own behaviour untouched. `-f` is not a substitute: it changes what the tool does on failure (`rm -f` reports success on a path that never existed).
 - If the brief is incomplete, continue with explicit uncertainty markers rather than fabricating confidence.
 - Required roles must not be replaced by unnamed generic parallel workers. Before the final verdict, every selected worker must have either a saved result file or an explicit terminal status with reason. Any attempted worker with status `completed`, `timeout`, or `error` must also have a saved worker prompt history file at its assigned run-level prompt path.
 

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

@@ -119,7 +119,7 @@
       **Pick the cases by distinct outcome, not by line coverage.** When the stage writes or reconciles state, its meaningfully different outcomes are usually more than three — normal success, target already in the desired state (resume), existing data reused rather than created, a conflicting concurrent state, target absent, and mid-way failure with rollback. Enumerate the ones this stage actually implements and route them across the three lines (the `boundary` line is where resume / already-done / reuse belongs; `failure` carries conflict, absence, and rollback), naming each in the cell rather than collapsing them into "edge input". An implemented outcome with no declared case is a coverage gap the executor will not backfill.
   - **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
     - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
-    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | expected`. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change (no lower time bound; it may span several files that change together); for code steps include actual code or diff sketch. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`expected` = FAIL) — the RED step encodes the case set, not a single happy-path assertion; at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`expected` = PASS); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section (mirrors the executor's per-step exemption in `_implementation-executor.md`). Validator S10c enforces RED-first + GREEN **and** that the `RED:` step's `expected` reads FAIL / the `GREEN:` step's reads PASS; S10e rejects a `TDD exemption:` whose reason is not one of doc-only / config-only / pure-rename (both in `validators/validate-implementation-plan-stages.py`).
+    - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change (no lower time bound; it may span several files that change together); for code steps include actual code or diff sketch. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`) — the RED step encodes the case set, not a single happy-path assertion; at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section (mirrors the executor's per-step exemption in `_implementation-executor.md`). Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its `RED:` / `GREEN:` prefix is a schema conditional (`StageStepRow.allOf`), so a plan whose data.json says otherwise never reaches the validator. S10e rejects a `TDD exemption:` whose reason is not one of doc-only / config-only / pure-rename (both in `validators/validate-implementation-plan-stages.py`).
     - **Per-stage conformance declaration (mandatory one line, in the stage section — same placement freedom as `TDD exemption:`):** the stage MUST carry exactly one of:
       - `Conformance tests: stage-<N> — <task_root>/qa/scripts/stage-<N>.<ext> (requires=[db|io|http|external,...])` — a Tier3 verification script that proves this stage's upstream requirements (brief / requirements-discovery / error-analysis / improvement-discovery → this stage's `Acceptance`) hold against **real** DB rows, real endpoints, or the real external API — NOT mocks. When you emit this line you MUST also (a) write the script to `<task_root>/qa/scripts/stage-<N>.<ext>` and (b) add a matching entry to `<task_root>/qa/conformance-manifest.json` with fields `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (subset of `{db, io, http, external}`), `passContract`, `exemption: null`, `waiver: null`. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <reason>` line per requirement. When the verification body is a test spec, author it with the project's own test framework (devDependency) invoked via a discovery override at `<task_root>/qa/scripts/` (jest: `--config <project config> --roots <task_root>/qa/scripts`) — never hand-roll `describe`/`expect` and never widen the project's own test config; for TypeScript specs also write `<task_root>/qa/scripts/tsconfig.json` extending the project tsconfig with the runner's `types` entry so editors resolve the file.
       - `Conformance exemption: <reason>` — only for stages that touch no db/io/http/external surface, or where unit tests fully cover the increment. (If the eventual `implementation` diff actually touches one of those surfaces, `validate-run.py`'s diff-surface cross-check is BLOCKING — an exemption cannot hide a real db/io/http/external change.)

package/runtime/python/okstra_ctl/adapters/accounting/__init__.py

@@ -0,0 +1,11 @@
+"""Usage-accounting adapters."""
+
+from .claude_jsonl import ClaudeJsonlUsageAccountingPort
+from .cli_artifact import CliArtifactUsageAccountingPort
+from .unavailable import UnavailableUsageAccountingPort
+
+__all__ = (
+    "ClaudeJsonlUsageAccountingPort",
+    "CliArtifactUsageAccountingPort",
+    "UnavailableUsageAccountingPort",
+)

package/runtime/python/okstra_ctl/adapters/accounting/claude_jsonl.py

@@ -0,0 +1,17 @@
+"""Claude JSONL usage-accounting adapter."""
+from __future__ import annotations
+
+from okstra_ctl.ports.usage_accounting import UsageRequest, UsageSnapshot
+from okstra_token_usage.collect import (
+    collect_claude_runtime_usage as collect_runtime_usage,
+)
+
+
+class ClaudeJsonlUsageAccountingPort:
+    def collect(self, request: UsageRequest) -> UsageSnapshot:
+        payload = collect_runtime_usage(
+            request.team_state_path,
+            request.project_root,
+            incremental=request.incremental,
+        )
+        return UsageSnapshot(source="claude-jsonl", payload=payload)