okstra 0.173.0 → 0.175.1

package/docs/cli.md

@@ -4,6 +4,8 @@
 >
 > This manual covers the phase-execution flags of `okstra.sh`. For the subcommand reference of the separate `okstra container` entry point, see [container.md](container.md).
 
+The Node CLI requires Node.js 22 or newer. Its TypeScript sources are compiled from `src/**/*.mts` to `dist/**/*.mjs`; `bin/okstra` executes the compiled files. The central state helper remains `scripts/okstra-central.sh`.
+
 ---
 
 ## Index
@@ -28,6 +30,8 @@
   - [`--directive`](#--directive)
   - [`--fix-cycle`](#--fix-cycle)
   - [`--workers`](#--workers)
+  - [`--role-count`](#--role-count)
+  - [`--role-model`](#--role-model)
   - [`--lead-runtime`](#--lead-runtime)
   - [`--claude-model`](#--claude-model)
   - [`--lead-model`](#--lead-model)
@@ -60,7 +64,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 <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>] [--selected-direction <selection-final-report.md>] [--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] [--role-count <role>=<N>] [--role-model <role>=<modelRef>] [--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|grok|kimi] [--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>] [--selected-direction <selection-final-report.md>] [--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.
@@ -467,9 +471,23 @@ The Codex worker (`--workers codex`, `--codex-model`) and Codex lead runtime are
 > - Claude (`--lead-model` / `--claude-model` / `--report-writer-model`): `fable`, `fable-5`, `claude-fable-5`, `opus`, `opus-5`, `claude-opus-5`, `opus-4-8`, `claude-opus-4-8`, `opus-4-7`, `claude-opus-4-7`, `opus-4-6`, `claude-opus-4-6`, `sonnet`, `sonnet-5`, `claude-sonnet-5`, `sonnet-4-6`, `claude-sonnet-4-6`, `haiku`, `haiku-4-5`, `claude-haiku-4-5`, `claude-haiku-4-5-20251001`
 > - Codex (`--codex-model`): `gpt-5.6-sol`, `gpt-5.6`, `gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, `gpt-5.3-codex`, `gpt-5.2`, `codex-auto-review`
 > - Antigravity (`--antigravity-model`): `gemini-3.1-pro` (default), `gemini-3.6-flash`, `gemini-3.5-flash`, and their space-separated aliases. The antigravity worker uses the `agy` CLI to run Gemini-family models, so model IDs retain the `gemini-*` form.
-> - Grok (`--worker-model grok=<model>`): `grok-build-0.1`, `grok-4.5`
+> - Grok (`--worker-model grok=<model>`): `grok-4.6`, `grok-4.5`, `grok-build-0.1`
 > - Kimi (`--worker-model kimi=<model>`): `kimi-k2.7-code`, `kimi-for-coding`, `kimi-k3`, `k3`, `k3-256k` and their registered display aliases
 
+### `--role-count`
+
+Sets the total instance count for one static role: `--role-count <role>=<N>`. Repeat the flag for each role. `N` is the profile total for that role, not an increment. Omit the flag to use the profile default. Dynamic roles, fixed-count roles, and roles absent from the profile reject the flag. lead is a compatibility alias for leader. New records write `leader`.
+
+Role count becomes `RoleInstance` ordinals. `ModelPool` then selects one model per ordinal. A pinned model is kept only when the host can bind it exactly.
+
+### `--role-model`
+
+Pins one model reference onto a role instance, in ordinal order: `--role-model <role>=<modelRef>`. Repeat the flag to fill later ordinals. Fewer models than the confirmed count are filled from the first matching default array. Extra models do not raise the count; set `--role-count <role>=<N>` first. Unknown roles and unknown model refs fail before any worktree or state file is created. A known selectable model may be assigned to any canonical role.
+
+`modelRef` is `<provider>/<model>`, for example `claude/opus-5` or `codex/gpt-5.6-sol`. Legacy `--lead-model`, `--claude-model`, `--codex-model`, `--antigravity-model`, `--worker-model`, `--report-writer-model`, and `--executor` remain compatibility inputs. They convert to role-model selections. A new flag and a legacy flag that name different models for the same role fail.
+
+`okstra model list [--role <role>] [--host <host>] [--json]` prints the catalog without an inference call. `okstra model default set|unset <role> ... --scope project|global` writes `modelDefaults` to `.okstra/project.json` or `~/.okstra/config.json`.
+
 ### `--lead-provider`
 
 Compatibility assertion for previously recorded invocations. The value must match the host-native provider: `claude` on Claude Code, `codex` on Codex, and `antigravity` on Antigravity. It is not an independent lead selector. Other providers belong in the worker roster and run through CLI wrappers; preparation rejects a cross-provider lead rather than recording one model and silently running another.
@@ -528,11 +546,11 @@ Fallback defaults are:
 
 ### `--executor`
 
-Selects the provider that performs the Executor role for `--task-type implementation`. The value is `claude`, `codex`, or `antigravity`; it is ignored for other task types.
+Selects the provider that performs the Executor role for `--task-type implementation`. The value is `claude`, `codex`, `antigravity`, `grok`, or `kimi`; it is ignored for other task types.
 
 - Default: `OKSTRA_DEFAULT_EXECUTOR` → fallback `claude`.
-- The Executor is the **only worker allowed to mutate project files** in this run. The other two providers are dispatched as strict read-only verifiers in the same run.
-- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.6-sol`; with `--executor antigravity`, it comes from `--antigravity-model`, default `gemini-3.1-pro`.
+- The Executor is the **only worker allowed to mutate project files** in this run. The other providers are dispatched as strict read-only verifiers in the same run.
+- The Executor reuses the provider's worker model flag. With `--executor codex`, its model comes from `--codex-model`, default `gpt-5.6-sol`; with `--executor antigravity`, it comes from `--antigravity-model`, default `gemini-3.1-pro`. With `--executor grok`, its model comes from `--worker-model grok=`, default `grok-4.6`.
 - All three Claude, Codex, and Antigravity verifiers are always dispatched regardless of the Executor provider. Even the verifier using the same provider runs in a separate CLI session with isolated context, preserving the self-review safeguard.
 - Codex and Antigravity mutate files through each CLI's auto-edit mode, for example `codex exec --sandbox workspace-write`, without passing through Claude-side Edit/Write tools. Mutations occur in the task worktree described below. Every `okstra-<provider>-exec.sh` entrypoint receives the worktree path as its fourth positional argument and adds it to the worker's write scope, which each provider is told as repeated `--add-dir` (Codex names the project root with `-C` and skips the repeat). Without it, the Codex `workspace-write` sandbox rejects worktree writes with EPERM.
 - **Claude Executor cwd handling**: Claude's Bash tool has no per-call cwd argument and inherits the lead session cwd. To run cwd-sensitive toolchains such as `cargo`, `npm`, `pnpm`, `bun`, `pytest`, `make`, or `go` inside the worktree, prefix the invocation with `cd {{EXECUTOR_WORKTREE_PATH}} && <cmd>`. Keep `cd` as the leading token in a single Bash call so Claude Code permission auto-allow works; do not wrap it in `bash -lc "..."` or `bash -c "..."`, which hides `cd` and causes a permission prompt on every call. Prefer a tool's working-directory option—such as `git -C <path>`, `cargo --manifest-path`, or `pytest --rootdir`—over a `cd && ` chain. Edit/Write/Read tools already use absolute paths and need no cwd handling. This rule applies only to the Claude Executor; the Codex and Antigravity wrappers inject cwd.
@@ -770,7 +788,9 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra install [--runtime claude-code\|codex\|antigravity\|external\|all] [--refresh\|--dry-run\|--link <repo>]` | Install or update the runtime, templates, skills, and agents. The default runtime is `auto`; skill targets are not runtimes. `~/.agents/skills/` is always created, and Claude skills and agents are also installed when `~/.claude` exists |
 | `okstra ensure-installed [--runtime claude-code\|codex\|antigravity\|external\|all] [-q]` | Check installation state and reinstall stale assets for the same runtime. Default `auto` continues without a host signal and checks drift in the Agent skill target and any existing Claude target |
 | `okstra uninstall [--purge -y]` | Remove installed assets. By default, removes files listed by the `installed-skills.json` targets and `installed-agents.json` while preserving user data |
-| `okstra doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, and skill/agent installation. The `codex`, `antigravity`, and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
+| `okstra doctor [--runtime claude-code\|codex\|antigravity\|external\|all] [--phase <phase>] [--json]` | Diagnose the runtime, Python imports, skill/agent installation, and model-pool state. The JSON `modelPool` object reports pool errors, default errors, binding precision, observed model, max write boundary, and invocation downgrade reason. It never sends an inference call. The `codex`, `antigravity`, and `external` runtimes omit Claude skill checks. `--phase` adds readiness checks for `implementation`, `final-verification`, `release-handoff`, or `improvement-discovery` |
+| `okstra model list [--role <role>] [--host <host>] [--json]` | List catalog models for a host and optional role. Unselectable exact bindings report `exact binding unavailable`. No inference call |
+| `okstra model default set\|unset <role> ... --scope project\|global [--cwd <dir>]` | Atomically write or remove `modelDefaults` for one canonical role |
 | `okstra setup --project-id <id>` | Create or update `.okstra/project.json` in the current project |
 | `okstra check-project [--json]` | Verify that the current project is registered |
 | `okstra preflight [--runtime <name>] [--cwd <dir>] [--json]` | Single skill-preflight call combining `ensure-installed`, with silent reinstall when stale, `check-project`, and host-specific `runtimeReadiness` into one JSON response. A `claude-code` host checks project workspace trust. A `codex` current-session host verifies write access to `~/.okstra/worktrees/registry.lock`; a sandbox denial blocks before the wizard with the `switch-codex-to-full-access-and-rerun` action. `antigravity` and `external` hosts return ready without reading Claude Code state. Step 0 of every project-scoped skill converges on this command |
@@ -809,6 +829,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra code-review target --task-key <k> --stage <N> [--project-root <dir>] [--cwd <dir>] [--json]` / `okstra code-review target --branch <name> [--base <ref>] [--date <YYYY-MM-DD>] [--project-root <dir>] [--cwd <dir>] [--json]` | Resolve what a code review reads and where its result file goes. Output is always JSON, so `--json` only makes that explicit. `--project-root` and `--cwd` are shared pre-dispatch arguments and apply to both modes; `--cwd` is only consulted when `--project-root` is absent. Both modes return `{ ok, projectRoot, mode, worktreePath, branch, baseCommit, headCommit, reviewPath, round }`; stage mode additionally returns `taskKey`, `taskRoot`, and `stage`. Stage mode takes the diff base from the `base_ref` recorded on that stage's worktree-registry row when it was provisioned — not from a rule re-applied at review time — and names the result `.okstra/tasks/<task-group>/<task-id>/code-reviews/stage-<NN>.md`, where a re-review of the same stage becomes `-r2`, `-r3`, … (the `round` field). Only a legacy row provisioned before `base_ref` was recorded falls back to re-deriving the base through `stage_targets`, and a failure there is reported as `stage_base_unresolved`. `worktreePath` comes back empty whenever the stage worktree is not usable as a live checkout — the registry row is no longer `active` (whole-task final-verification released it), the row never carried a path, or the recorded directory is gone — and the review then reads the `branch` ref instead. Branch mode uses `--base` when given, otherwise the merge-base with the default branch (`refs/remotes/origin/HEAD`, else `main`/`master`), and names the result `.project-docs/code-reviews/<branch>/<YYYY-MM-DD>-<NN>.md`, where `<NN>` (the `round` field) is the next sequence number for that date — the highest already on disk plus one. Read-only: it resolves paths and creates no directory and no file, so the review directory does not exist until the caller writes the report. Backend for the okstra-code-review skill |
 | `okstra set-work-status <token> <todo\|in-progress\|blocked\|done> [--note <text>] [--task-group <g>] [--project-root <dir>]` | Update user-managed `workStatus` in task-manifest.json, along with `workStatusUpdatedAt` and, when `--note` is supplied, `workStatusNote`. `<token>` is a full task key or bare task ID. It uses the manifest renderer's serialization rules and returns `stage:"ambiguous"` plus `matches[]` when ambiguous |
 | `okstra worktree-lookup <task-key>` | Return the `worktree_registry.lookup` result: reserved path, branch, base ref, and current status |
+| `okstra worktree-status [--path <dir>] [--check-clean]` | Answer "is this worktree clean?" over source paths only, excluding what okstra provisioned there — `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and any nested stage worktree. A bare `git status --porcelain` in a task worktree is never empty for that reason, so a plan step asserting a clean tree with one fails on okstra's scaffolding instead of on the stage's own work; this is the same gate `handoff` and stage integration use. Output is JSON `{ ok, path, clean, entries, excluded }` where `entries` holds the `git status --short` rows that made it dirty. Exit code is 0 regardless unless `--check-clean` is given, which exits 1 on a dirty tree so it can stand as a shell assertion (`okstra worktree-status --check-clean && git tag -f stage-<N>-exit`). A path outside a git work tree exits 2 rather than reporting a clean tree |
 | `okstra plan-validate <plan-path>` | Run `_validate_approved_plan` and report frontmatter `approved` recognition plus unresolved Blocks=approval rows |
 | `okstra render-bundle <args…> [--stage <auto\|N>] [--stages <csv>]` | Thin shim over `prepare_task_bundle(render_only=True)` with the same signature as `python3 -m okstra_ctl.run --render-only`. `--stage` is for `implementation` and `final-verification`: for implementation, `auto` (default) selects the earliest incomplete stage with satisfied dependencies, while `<N>` forces a stage; for final-verification, `<N>` verifies one stage with artifacts under `runs/final-verification/stage-<N>/` and a `-fv-s<N>` team suffix, while an empty value performs whole-task verification with the flat layout. The separate `--stages <csv>` channel is for `release-handoff`: stage-group mode bundles the listed stage numbers into one PR, while an empty value selects whole-task mode. Preparation enforces eligibility—`done` + accepted `verified` + not yet `pr`—and automatically creates an input document that cites verification reports |
 | `okstra profile show <task-type> [--resolved]` | Print a phase profile. `--resolved` expands its `{{INCLUDE:}}` targets and appends the lazy-read sidecars named in the profile body — transitively, because sidecars name sidecars of their own (`_implementation-executor.md` points at the coding-conventions preflight, the diff-review sweep, and the completion self-check). That matters because a profile is assembled from three places, so grepping only the top-level file returns false negatives: `grep clarification prompts/profiles/implementation.md` finds nothing while the assembled profile has many hits. One grep over this output answers whether a task-type covers a rule. The sidecar list is read from the profile body, never hard-coded, so a newly added sidecar is picked up without a code change. Read-only: it writes no manifest and registers no run, which is what separates it from `render-bundle` — `render-bundle` answers the same question but records a run in `recent.jsonl`, so it cannot be used to look something up. Exits 2 for an unknown task-type |
@@ -819,7 +840,7 @@ The `okstra` Node CLI (`bin/okstra`) provides both installer/admin commands and
 | `okstra team dispatch --project-root <dir> --run-manifest <path> [--workers <csv>] [--jobs-file <path>] [--dry-run]` / `okstra team await --project-root <dir> --run-manifest <path> [--json]` / `okstra team teardown --project-root <dir> --run-manifest <path> [--dry-run] [--json]` | Read a `leadRuntime=external` run manifest and dispatch, await, or tear down tmux-pane workers. Default dispatch excludes report writer; Phase 6 selects it explicitly, and mixed analysis/report jobs are rejected. If a tmux pane cannot be created, gracefully degrade to the CLI wrapper and record the fallback in `workerDispatches[].degradedFrom` |
 | `okstra agent-activity append --project-root <dir> --run-manifest <path> --kind <kind> --agent <id> --summary <text> --outcome <outcome> [--plan-item-id <id>]… [--evidence-ref <ref>]… [--command-record <json>]… [--result-path <path>] [--audit-sidecar <path>]` | Append one structured activity to the run manifest's `leadEventsPath`. `kind` accepts `worker-dispatched`, `worker-completed`, `verification-round-completed`, `self-fix-applied`, `user-decision-required`, or `user-decision-evaluated`. `outcome` accepts `pending`, `completed`, `failed`, `blocked`, or `resolved`. Repeated `--command-record` values and `Evidence command` rows from `--audit-sidecar` must contain exactly `command`, `cwd`, `exitCode`, and `outputSummary`; malformed or potentially secret-bearing evidence stops the append. The command requires `activityContractVersion: 1` and returns the assigned `activityId` in JSON. |
 | `okstra agent-activity project --project-root <dir> --run-manifest <path> --data <data.json>` | Project this run's canonical activity events into `agentActivity[]`. The command preserves event order, rejects duplicate or decreasing activity IDs, and replaces no other report field. A historical manifest without `activityContractVersion: 1` returns an empty projection and leaves data.json unchanged. Normal Phase 7 execution reaches this behavior through `report-finalize`; use the standalone command only for diagnostics. |
-| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `project-activity` → `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step, then prints a per-step `[ok]` / `[FAIL]` / `[skip]` summary on stderr so the outcome is legible without parsing the JSON payload. `project-activity` is an in-process byte-preserving no-op for legacy manifests without activity contract v1. Every step is idempotent, so re-running after a fix is safe — but `--only <step>` (repeatable) reruns just the named steps in contractual order. For a non-English report, run `--only project-activity --only check-source` before translator dispatch, then run the full sequence after the translation sidecar exists. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) every lead adapter runs after its report-writer completes. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the six steps individually. |
+| `okstra report-finalize --project-root <dir> --run-manifest <path> --report <final-report.md>` | Run the whole Phase 7 post-report sequence in its contractual order: `project-activity` → `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run`. Stops at the first non-zero exit and names the failing step, except `token-usage`: its input is the lead session log, so a failure there defers rather than deleting the html, follow-ups and validation that come after it — the run still reports `ok: false`, and names that step unless a later one also fails, in which case the later failure is the reason. Whenever a step exits non-zero the command prints the `--only` flags that resume the sequence from the earliest failing step; after a deferral that tail is what re-renders the html the deferred step invalidated. Prints a per-step `[ok]` / `[FAIL]` / `[skip]` summary on stderr so the outcome is legible without parsing the JSON payload. `project-activity` is an in-process byte-preserving no-op for legacy manifests without activity contract v1. Every step is idempotent, so re-running after a fix is safe — but `--only <step>` (repeatable) reruns just the named steps in contractual order. For a non-English report, run `--only project-activity --only check-source` before translator dispatch, then run the full sequence after the translation sidecar exists. This is the same code path (`scripts/okstra_ctl/report_finalize.py`) every lead adapter runs after its report-writer completes. `--workspace-root` is owned by the Node wrapper. Prefer this over invoking the six steps individually. |
 | `okstra render-views <final-report.data.json\|final-report.md>` | The Phase 7 `render-views` step, runnable on its own. Schema v2 data is rendered directly (contract: `schemas/final-report-v2.0.schema.json`) into an always-generated, task-specific human HTML sibling while `templates/reports/final-report-v2.template.md` independently owns the AI handoff Markdown. Passing the Markdown sibling locates the same v2 data.json. Schema v1 and quick reports keep the legacy conditional renderer. The Node wrapper calls `scripts/okstra-render-report-views.py`; `validators/validate-report-views.py` verifies source/schema/template digests, required human fields, form controls, external assets, diagram/table ID parity, and Response ID parity |
 | `okstra design-prep <list\|show\|write>` | Review AI-prepared implementation design requests, inspect their effective confirmed response, or append a confirmed user/wizard response without editing the planning report |
 | `okstra wizard <init\|step\|render-args\|confirmation\|outcome> --state-file <path>` | Interactive input state machine for okstra-run, implemented by `okstra_ctl.wizard`. Seed a state file with `init`, then repeatedly call `step --answer <val>` to receive the next `Prompt` JSON. `--answer` is **required**; use `--no-submit` to peek at the next prompt without submitting a response. A `pick` with more choices than the host picker can display keeps `kind: "pick"` but adds `presentation: "numbered-text"`; render every option as a numbered Markdown list and submit the user's 1-based number, exact value, or exact label. Invalid, out-of-range, and ambiguous answers re-prompt without dropping choices. `render-args` returns the final `render-bundle` argument map, and `confirmation` returns the user echo block. On a completed wizard, `outcome` returns `renderArgs`, `persistActions`, and `confirmationText` together; project/global release-handoff PR-template persistence appears as `persistActions[].command == "config.set"`. For an `implementation` task type, `stage_pick` follows `approved_plan_pick` and selects the stage before `executor_pick`. The brief step appears only for entry task types—requirements-discovery, error-analysis, improvement-discovery, project-analysis, feature-analysis, and change-impact-analysis. Analysis inputs use `feature_evidence_pick` / `feature_evidence`, `project_evidence_pick` / `project_evidence`, and `analysis_target_pick` / `analysis_target`; a revision-requested report prioritizes its same-task, same-type rerun. Downstream lifecycle phases automatically carry the manifest brief, with a three-option `brief_carry` fallback when none is registered; `release-handoff` has no brief and enters multi-select `handoff_stage_pick` for eligible stage groups or the whole task |
@@ -875,4 +896,4 @@ For every dispatch, whichever provider runs it, okstra creates a `runs/<task-typ
 
 **Progress appears in the worker's own pane.** Earlier versions split a sibling `tail -F` trace pane next to each worker; they no longer do, and no trace pane is created at all. Instead the presentation is passed to the entrypoint as `--presentation live|quiet`, and only a backend that opened a pane asks for `live` — the default, and what a `cli-wrapper` subagent dispatch passes, is `quiet`. Under `live` each event becomes one readable row on the worker's own streams — `→ Bash: npm run check`, then `  ← ok (2481 bytes)`, and `!! PERMISSION DENIED — <tool>: <reason>` for a refusal. Under `quiet` progress is withheld and only the worker's closing text is printed, which is what a dispatch on a machine with no pane surface needs. The `.log` sidecar records the progress either way, so withholding it from the screen loses nothing.
 
-Because nothing spawns a trace pane, the `@okstra_trace_run` and `@okstra_status` pane user options have no writer left, and the `okstra-trace-cleanup.sh --reclaim-completed` mode plus the `okstra-subagent-reclaim.sh` hook that drives it now match no panes. Both stay installed and are harmless — the panes they existed to close are no longer created. tmux-pane backend worker-compute panes are still tagged `@okstra_worker_run=<RUN_DIR>`. When Claude receives `/exit`, the `SessionEnd` hook cleans up within `$CLAUDE_PROJECT_DIR/.okstra/` scope by running `okstra-trace-cleanup.sh --reap`. When the lead calls the same script with `--run-dir <RUN_DIR>`, it removes the run's worker-compute panes and dispatched worker-agent panes within the lead-window scope (title scan uses `tmux list-panes -t <lead-pane>`, no `-s`, so a second lead in another window of the same session is out of range), while excluding the lead's own pane. Worker-agent titles include `claude-worker`, `codex-worker`, `antigravity-worker`, `report-writer-worker`, implementation role titles, and FleetView teammate prefixes `✳ ` / `⠂ `. The lead runs `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` at every worker round boundary — after collecting that round's results and before the next dispatch, not once per phase — to reclaim the completed panes. `--keep <substr>` (repeatable) excludes panes whose title contains the substring, which is how an in-flight report writer is preserved (`--keep report-writer-worker`), and `--list` prints the same set without killing so the lead can count what it is about to reclaim. The lead also runs the same reclaim immediately before any user approval/clarification/decision gate (`PROGRESS: phase-gate-cleanup panes=<n>`), and an `okstra-compact-reminder.sh` `SessionStart` hook (matcher `compact`) re-injects this obligation after a `/compact`.
+Every pane tag this script once scanned has lost its writer, so the tag scan is gone along with the two modes that existed only to drive it. `@okstra_trace_run` / `@okstra_status` went inert when the wrappers stopped splitting a trace pane, which retired `--reclaim-completed` and the `okstra-subagent-reclaim.sh` hook behind it; `@okstra_worker_run` went with the `tmux-pane` dispatch backend, which retired `--reap` and its `SessionEnd` hook. What okstra still has to close are the teammate panes the **harness** splits for dispatched worker agents — panes okstra never created and cannot tag. The lead calls `okstra-trace-cleanup.sh --run-dir <RUN_DIR>`, which finds them by a title allowlist within the lead-window scope (`tmux list-panes -t <lead-pane>`, no `-s`, so a second lead in another window of the same session is out of range), while excluding the lead's own pane. Worker-agent titles include `claude-worker`, `codex-worker`, `antigravity-worker`, `report-writer-worker`, implementation role titles, and FleetView teammate prefixes `✳ ` / `⠂ `. The lead runs `okstra-trace-cleanup.sh --run-dir <RUN_DIR>` at every worker round boundary — after collecting that round's results and before the next dispatch, not once per phase — to reclaim the completed panes. `--keep <substr>` (repeatable) excludes panes whose title contains the substring, which is how an in-flight report writer is preserved (`--keep report-writer-worker`), and `--list` prints the same set without killing so the lead can count what it is about to reclaim. The lead also runs the same reclaim immediately before any user approval/clarification/decision gate (`PROGRESS: phase-gate-cleanup panes=<n>`), and an `okstra-compact-reminder.sh` `SessionStart` hook (matcher `compact`) re-injects this obligation after a `/compact`.

package/docs/container.md

@@ -75,7 +75,7 @@ One watcher per container runs in the detached session.
 1. **Lightweight scan** — Fetch incremental logs with `docker compose logs --since` and match only regular expressions (`ERROR`/`FATAL`/`Exception`/`Traceback`/abnormal exit codes, and so on). If there are no matches, proceed to the next interval without an LLM call → zero token cost during healthy periods.
 2. **Deep analysis** — Only when a pattern is detected, the watcher AI analyzes the relevant log window and appends its findings to `findings.md`. Identical error signatures are debounced (meaningful numbers such as HTTP statuses and exit codes are preserved, while only noise such as timestamps and pids is normalized). The watcher **only detects and reports**; it does not modify code or configuration.
 
-Watcher/tail panes carry only the dedicated `@okstra_container_run` tag, so they survive even when a Claude session ends (SessionEnd `--reap`). Stop them with `stop-watcher` or `down`.
+Watcher/tail panes carry only the dedicated `@okstra_container_run` tag and survive a Claude session ending — no session-end hook reclaims panes any more. Stop them with `stop-watcher` or `down`.
 
 ## Labels and artifacts
 

package/docs/contributor-change-matrix.md

@@ -5,12 +5,12 @@ Use this matrix before changing high-risk repo contracts. Update the source file
 | Change | Must update | Tests |
 |---|---|---|
 | Add CLI flag | `src/`, `scripts/okstra_ctl/run.py`, `docs/cli.md`, `prompts/wizard/` | JS CLI tests and pytest CLI contracts |
-| Add Node subcommand | `src/cli-registry.mjs`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
-| Add public skill | `src/lib/skill-catalog.mjs`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
+| Add Node subcommand | `src/cli-registry.mts`, `src/commands/`, `docs/cli.md`, `docs/project-structure-overview.md` | `tests-js/cli-registry.test.mjs` plus command-specific JS/Python tests |
+| Add public skill | `src/lib/skill-catalog.mts`, `.claude-plugin/plugin.json`, `skills/<name>/SKILL.md`, `docs/for-ai/README.md`, `docs/project-structure-overview.md`, `README.md` | `tests-js/skill-catalog.test.mjs`, `tests/contract/test_docs_runtime_contract.py` |
 | Change manager contract | `scripts/okstra_ctl/manager_*.py`, `src/commands/manager.mjs`, `skills/okstra-manager/SKILL.md`, `docs/for-ai/skills/okstra-manager.md`, `docs/cli.md`, `docs/architecture/storage-model.md` | `tests-js/manager.test.mjs`, `tests/test_okstra_manager_*.py` |
 | Add phase | `scripts/okstra_ctl/workflow.py`, `prompts/profiles/`, `validators/`, `tests/` | workflow and validation contract tests |
 | Change worker roster | `prompts/profiles/*.md`, `scripts/okstra_ctl/workers.py`, `tests/contract/test_repo_contracts.py` | worker roster contract tests |
-| Change report section | `schemas/final-report-v1.0.schema.json`, `templates/reports/final-report.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
+| Change report section | `schemas/final-report-v2.0.schema.json`, `templates/reports/final-report-v2.template.md`, `scripts/okstra_ctl/render_final_report.py`, `validators/validate-run.py` | final-report schema, renderer, and validator tests |
 | Maintain Korean review mirrors | `config/korean-sources.json`, `tools/korean-sources/` (`lifecycle.mjs` plus its `lifecycle-*.mjs` support modules, CLI/hooks adapters, and shared workflow), `.agents/skills/sync-korean-sources/`, `.claude/skills/sync-korean-sources/` | `tests-js/korean-sources-*.test.mjs` (`lifecycle`, `cli`, `hooks`, and `skill`) |
 
 `runtime/` is build output. Never edit it directly; change source files and rebuild the runtime payload instead.

package/docs/project-structure-overview.md

@@ -25,12 +25,12 @@
 Current baseline:
 
 - package version: see `package.json`
-- Node CLI entrypoint: `bin/okstra`
+- Node CLI entrypoint: `bin/okstra` (Node.js 22+)
 - Python orchestration authority: `scripts/okstra_ctl/run.py::prepare_task_bundle`
 - lifecycle: `requirements-discovery → error-analysis → implementation-option-selection → implementation-planning → implementation → final-verification → release-handoff`
 - installed skills: 13
 - provider workers: `claude`, `codex`, `antigravity`, `grok`, `kimi`; functional report writer: `report-writer`
-- final report SSOT: current `schemas/final-report-v2.0.schema.json` + `*.data.json`; schema v1 remains a compatibility contract
+- final report SSOT: `schemas/final-report-v2.0.schema.json` + `*.data.json`
 
 Design principles:
 
@@ -46,7 +46,8 @@ Design principles:
 ```text
 okstra/
 ├── bin/okstra                       Node CLI router
-├── src/                             Node command modules
+├── src/                             TypeScript Node command sources (`*.mts`)
+├── dist/                            compiled `.mjs` CLI artifacts; generated
 ├── scripts/                         Python + Bash runtime sources
 │   ├── okstra_ctl/                  orchestration core
 │   ├── okstra_project/              project root / project.json resolver
@@ -145,7 +146,7 @@ Runtime/install asset changes follow this checklist:
 
 `--link <repo>` mode is for development and symlinks installed files back to repo sources.
 
-`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.
+`src/lib/host-registry-client.mts` 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.
 
 ---
 
@@ -155,7 +156,7 @@ Runtime/install asset changes follow this checklist:
 
 `bin/okstra` is a thin dynamic-import router. Every command module exports `run(args) -> Promise<number>` or a named install/uninstall runner.
 
-`src/` is layered: the dispatch table (`src/cli-registry.mjs`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory,pr}/`.
+`src/` is layered: the dispatch table (`src/cli-registry.mts`) stays at the root, shared infrastructure with no command export lives under `src/lib/`, and command modules are grouped by domain under `src/commands/{lifecycle,execute,inspect,report,memory,pr}/`. `npm run build:ts` compiles these sources to `dist/**/*.mjs`; `bin/okstra` executes the compiled output. `scripts/okstra-central.sh` remains the Bash central-state helper.
 
 | Command | Module | Role |
 |---|---|---|
@@ -180,6 +181,7 @@ Runtime/install asset changes follow this checklist:
 | `worker-audit-check` | `src/commands/execute/worker-audit-check.mjs` | Apply the Phase 7 worker audit-sidecar rules while the worker session is still alive, so it can fix its own citations (Python: `okstra_ctl.worker_audit_check`, rules in `okstra_ctl.worker_audit_ledger`) |
 | `context-cost` | `src/commands/inspect/context-cost.mjs` | Estimate task bundle file/read context cost |
 | `worktree-lookup` | `src/commands/execute/worktree-lookup.mjs` | Look up a task-key's registered worktree |
+| `worktree-status` | `src/commands/execute/worktree-status.mjs` | Clean-worktree check over source paths only, excluding okstra's provisioned entries and nested stage worktrees (Python: `okstra_ctl.worktree.dirty_entries_excluding_okstra`) |
 | `plan-validate` | `src/commands/execute/plan-validate.mjs` | Check approved-plan approval marker |
 | `render-bundle` | `src/commands/execute/render-bundle.mjs` | Preview `prepare_task_bundle(render_only=True)` |
 | `profile` | `src/commands/inspect/profile-show.mjs` | Print a phase profile with `{{INCLUDE:}}` expanded and its lazy-read sidecars appended transitively, so one grep answers whether a task-type covers a rule — a top-level grep alone returns false negatives (Python: `okstra_ctl.profile_show`). Read-only, unlike `render-bundle` |
@@ -191,7 +193,7 @@ Runtime/install asset changes follow this checklist:
 | `plan-items` | `src/commands/execute/plan-items.mjs` | Internal admin CLI for deterministic plan-body item extraction and exact-match validation (`extract`/`validate`; Python: `okstra_ctl.plan_items_cli`) |
 | `agent-activity` | `src/commands/report/agent-activity.mjs` | Thin Node shim for `okstra_ctl.agent_activity`; `append` records one run-bound activity and `project` writes the validated event projection into final-report data |
 | `report-finalize` | `src/commands/report/finalize.mjs` | Run the whole Phase 7 post-report sequence in contractual order (Python: `okstra_ctl.report_finalize`) — the single reference point shared with the Codex lead adapter |
-| `render-views` | `src/commands/report/render-views.mjs` | Render schema v2 data with its task-specific human template, or use the schema v1 / quick-report compatibility view |
+| `render-views` | `src/commands/report/render-views.mjs` | Render schema v2 data with its task-specific human template, or use the quick-report compatibility view |
 | `render-final-report`, `inject-report-index` | `src/commands/report/*.mjs` | Render version-selected AI handoff Markdown from data.json; v1 index injection remains compatibility-only |
 | `wizard` | `src/commands/execute/wizard.mjs` | Drive the `okstra-run` interactive state machine, including the final outcome envelope |
 | `token-usage` | `src/commands/execute/token-usage.mjs` | Wrap installed Python token usage CLI |
@@ -225,11 +227,10 @@ Top-level scripts:
 | `okstra-wrapper-status.py` | Standalone writer for one worker status sidecar. No longer on the dispatch path — `worker_runner.py` writes the same document in-process |
 | `okstra-token-usage.py` | Token usage CLI entrypoint |
 | `okstra-render-final-report.py` | Render version-selected final-report Markdown from data.json |
-| `okstra-render-report-views.py` | Render schema v2 task-specific HTML directly from data.json, or a legacy view from schema v1 / quick Markdown |
+| `okstra-render-report-views.py` | Render schema v2 task-specific HTML directly from data.json, or a legacy view from quick Markdown |
 | `okstra-error-log.py` | Normalize worker/lead error sidecars |
 | `okstra-spawn-followups.py` | Follow-up spawning helper |
-| `okstra-trace-cleanup.sh` | tmux okstra pane cleanup (worker-agent + worker-compute, excluding the lead pane), called by the lead at every worker round boundary — not once per phase; `--keep <substr>` (repeatable) spares panes whose title contains the substring, which is how an in-flight `report-writer-worker` survives a boundary; `--list` prints what would be reclaimed without killing. Its `--reclaim-completed` mode keyed on trace panes tagged `@okstra_status`; **no code writes that tag any more**, so the mode is inert rather than wrong — the trace panes it reclaimed are no longer created |
-| `okstra-subagent-reclaim.sh` | entry that walks active runs and drives `--reclaim-completed` (wired to the `SubagentStop`/`TaskCompleted` hooks). **Inert for the same reason** — it still runs and matches nothing. Left installed rather than removed: the hooks are already seeded on user machines, so retiring this is a deliberate follow-up |
+| `okstra-trace-cleanup.sh` | Closes the harness-owned worker-agent panes of a run (excluding the lead pane), called by the lead at every worker round boundary — not once per phase; `--keep <substr>` (repeatable) spares panes whose title contains the substring, which is how an in-flight `report-writer-worker` survives a boundary; `--list` prints what would be reclaimed without killing. The tag-driven paths (`--reap`, `--reclaim-completed`, and the `@okstra_worker_run` / `@okstra_trace_run` / `@okstra_status` scan) were removed once nothing wrote those tags — a title scan scoped to the lead's window is all that remains |
 
 ### 4.3 `scripts/okstra_ctl/` — Python orchestration core
 
@@ -268,9 +269,9 @@ Important modules:
 | `clarification_items.py` | Unified §5 clarification table parser and approval blockers |
 | `md_table.py` | Markdown pipe-table escape/split SSOT — the `mdcell` filter (`escape_pipes`) and the `\|`-aware `split_pipe_row`; shared by the renderer, HTML view, and validators |
 | `qa_commands.py` | QA command deny-list validation for plans |
-| `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance` |
+| `conformance.py` | validates task-level Tier 3 manifests, parses `QA-RESULT`, detects diff capability surfaces, and reduces results to PASS/ADVISORY/BLOCKING; DB/HTTP/external non-PASS is user-owned advisory while local IO and contract defects remain blocking, enforced by `scripts/okstra_ctl/conformance.py::decide_conformance_gate` and `validators/validate-run.py::_validate_conformance`. Also the single definition of the plan's `Conformance tests:` declaration format (`parse_conformance_tests`, `malformed_conformance_stages`), read both at the approval boundary (`run.py::_validate_approved_plan`) and at the end of an implementation run (`validators/validate-run.py`) so the two cannot disagree |
 | `pr_template.py` | PR body template resolution for release-handoff |
-| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Versioned final-report contract: schema v2 data independently produces AI handoff Markdown and human HTML; schema v1 keeps the legacy Markdown/view pipeline |
+| `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report contract: schema v2 data independently produces AI handoff Markdown and human HTML |
 | `report_markdown.py` | Schema-ordered Markdown serialisation of a data.json subtree for the AI handoff report — headings, tables for uniform row sets, prose for narrative fields; field order read from the schema, not from the mapping |
 | `final_report_paths.py`, `report_view_artifacts.py` | Path-helper SSOT for the final-report markdown/data.json pair and the generated view artifacts (HTML view, user-responses directory) |
 | `wizard.py` | `okstra-run` prompt state machine; user-facing Korean strings live in `prompts/wizard/prompts.ko.json` |
@@ -290,7 +291,7 @@ Important modules:
 | `code_review_paths.py` | filesystem-layout SSOT for code-review result files — `stage_review_dir` / `branch_review_dir` plus `next_stage_review` / `next_branch_review`, which read the existing files to derive the next round's name (`stage-<NN>.md`, then `-r2`, `-r3`, …) or the next same-day sequence (`<YYYY-MM-DD>-<NN>.md`), so skill markdown never re-derives a literal review path |
 | `code_review_target.py` | `okstra code-review target` backend — argument validation and JSON shaping only. Stage mode delegates whole to `okstra_project.state.code_review_target_snapshot`; branch mode is resolved here, defaulting the diff base to the merge-base with the default branch (`refs/remotes/origin/HEAD`, else `main`/`master`). Read-only: it never creates the review directory |
 | `session.py`, `tmux.py`, `seeding.py`, `locks.py`, `invocation.py`, `sequence.py`, `ids.py`, `material.py` | Supporting lifecycle helpers |
-| `pane_reclaim.py` | decides which completed trace panes are reclaim targets; imports the in-progress status set from the `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT. Inert alongside `--reclaim-completed` — no trace pane is created any more — but still the owner of that decision if the mechanism returns |
+| `pane_reclaim.py` | resolves which in-progress runs of the current project the `SessionStart(compact)` hook should re-inject the pane-cleanup obligation for; imports the in-progress status set from the `reconcile.NON_TERMINAL_RECENT_STATUSES` SSOT. The completed-pane decision it also used to own went away with `--reclaim-completed` |
 | `improvement_lenses.py` | lens enum SSOT + cap constants for the improvement-discovery phase (DEFAULT 8, ABSOLUTE 12, MIN/MAX PRIORITY 1/4, SOURCE_WORKERS) |
 | `improvement_assignment.py` | improvement-discovery primary-pass lens assignment — round-robins the resolved `requiredWorkerRoles` order over the resolved priority lenses (`assign_primary_lenses`) and validates the resulting map (`validate_primary_lens_assignments`). Only the primary pass rotates; every analyser still confirms the full lens set afterwards |
 | `container.py` | the `okstra container` convergence entrypoint of the okstra-container-build public skill — `provision_container_group` + `up`/`status`/`logs`/`stop-watcher`/`down` dispatch, env-override synthesis, compose argv assembly, and per-container watcher startup |
@@ -333,7 +334,7 @@ Important modules:
 | `plan_derivations.py` | the supersession sweep `_common-contract.md` requires an author to do by hand — extracts the symbols, paths, and ids an answered clarification names and reports every plan string that mentions one. Advisory: it locates candidates and never judges which are now false |
 | `scope_provenance.py` | single source of truth for the scope-provenance grammar every phase-emitted requirement must declare, shared by `validators/validate-run.py` and `validators/validate_fanout.py` so the planning report and fan-out packets cannot drift |
 | `worker_artifact_paths.py` | canonical worker artifact path derivation (e.g. `audit_sidecar_rel` inserts `-audit-` after the first `-worker-` token), so dispatch and validation agree on non-canonical-path rejection |
-| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
+| `report_finalize.py` | Phase 7 post-report sequence **SSOT** — runs `check-source` → `token-usage` → `render-views` → `spawn-followups` → `validate-run` in that load-bearing order, stops at the first non-zero exit and names the failing step — except `token-usage`, whose failure defers so the later steps still produce their artifacts. Both lead paths converge here: the Codex adapter calls it in-process (`codex_dispatch`), a Claude-led run reaches it through `okstra report-finalize`. Neither reimplements the sequence |
 | `wrapper_status.py` | worker wrapper status sidecar reader — the host-side reader of the sidecar `worker_runner.py` writes. `is_terminal` is the one question it answers for the dispatch record and the pane reclaim: does `stage` read `exited` |
 | `worker_runner.py` | runs one worker CLI and records what happened — shared by every provider entrypoint. Owns the `selectors` pump over the child's streams, the stream-arrival idle watchdog (`killpg` on breach), the run-wide progress cap on the log copy, and the status sidecar's whole life. A run that dies after launch still closes its sidecar, so `worker_liveness` never reads a dead worker as running |
 | `worker_request.py` | assembles the `WorkerExecRequest` every strategy then takes on trust: resolved paths, the write scope in the order the CLIs are told it (project root → stage tree → the tree's git-common-dir), the verifier's toolchain grants, and the role's idle budget |
@@ -379,7 +380,7 @@ Token/cost accounting:
 
 | Path | Role |
 |---|---|
-| `templates/reports/final-report.template.md` | Schema v1 compatibility Markdown template |
+| `templates/reports/final-report-v2.template.md` | AI handoff Markdown spine |
 | `templates/reports/final-report-v2.template.md` | Schema v2 AI handoff Markdown spine |
 | `templates/reports/md/tasks/*.template.md`, `md/macros/sections.md` | Eleven dedicated task bodies for the AI handoff Markdown, sibling of `html/tasks/`; shared section macro |
 | `templates/reports/html/base.template.html`, `html/tasks/*.template.html` | Shared HTML shell plus eleven dedicated task templates for human reports; task bodies are not shared |
@@ -395,7 +396,7 @@ Token/cost accounting:
 
 ### 4.8 `schemas/`
 
-`schemas/final-report-v2.0.schema.json` is the current final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; independent renderers produce AI handoff Markdown and task-specific human HTML. `schemas/final-report-v1.0.schema.json` remains supported for existing reports and quick-report compatibility.
+`schemas/final-report-v2.0.schema.json` is the current final-report data.json contract. The report-writer worker writes `final-report-<task-type>-<seq>.data.json`; independent renderers produce AI handoff Markdown and task-specific human HTML.
 
 The deterministic convergence inputs are `schemas/convergence-groups-v1.0.schema.json`, `schemas/convergence-round-results-v1.0.schema.json`, and `schemas/convergence-critic-results-v1.0.schema.json`. `tools/build.mjs` syncs the entire source `schemas/` directory to `runtime/schemas/`; these JSON Schema files are runtime contracts, not Markdown publication-inventory entries.
 
@@ -408,7 +409,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 
 | File | Role |
 |---|---|
-| `validate-run.py` | Version-aware run/final-report validation: schema v2 AI handoff order + structured data rules, with legacy schema v1 Markdown gates preserved |
+| `validate-run.py` | Run/final-report validation: schema v2 AI handoff order + structured data rules |
 | `validate-brief.py`, `validate-brief.sh` | Brief frontmatter/body contract validation |
 | `validate-report-views.py` | HTML view validation (form-control placement / no external URLs / stale source digest / Response ID parity) |
 | `validate_analysis_report.py` | Cross-field validation for the three read-only analysis reports: frozen target/evidence snapshots, current-code evidence, review-source identity, and exact affected-ID resolution coverage on revision reruns |
@@ -421,7 +422,7 @@ Optional (v1.0 backward-compatible) top-level keys:
 
 ### 4.10 `skills/`
 
-13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mjs`; the Claude plugin manifest and the installer both derive from it.
+13 user-facing skills (the only skills `okstra install` copies). The list SSOT is `USER_SKILL_NAMES` in `src/lib/skill-catalog.mts`; the Claude plugin manifest and the installer both derive from it.
 
 Boilerplate shared by several skills (bash invocation rule, outdated-CLI preflight, python bootstrap note) is kept canonical in `skills/_fragments/*.md` and expanded in place inside each `SKILL.md` between `<!-- BEGIN FRAGMENT: <name> -->` / `<!-- END FRAGMENT: <name> -->` markers by `tools/sync-skill-fragments.mjs` (`--check` fails on drift). Sources stay fully expanded, so `runtime/` and installed copies remain self-contained; the guards are `tests-js/skill-fragments.test.mjs` and `tests/contract/test_prompt_fragment_ownership.py`.
 
@@ -492,7 +493,7 @@ they are not published user skills.
 `prepare_task_bundle()` coordinates:
 
 1. Resolve project root and verify/upsert `project.json`.
-2. Resolve profile, required workers, model assignments, executor provider.
+2. Resolve profile, required workers, role counts, `ModelPool` assignments, and the implementer provider. `lead`/`executor` remain input aliases only.
 3. Resolve task identity segments, work category, and the run sequence input needed for path allocation.
 4. Provision or reuse the task-key worktree, or the selected implementation stage worktree for stage-isolated runs.
 5. For an analysis sidetrack, resolve the immutable source commit from the provisioned worktree's `HEAD`, then resolve evidence reports, freshness, and the feature target through `analysis_inputs.py`.
@@ -537,12 +538,20 @@ Current report pipeline:
 4. For implementation-planning, `okstra plan-items extract` creates the complete `P-*` queue, `validate` proves it still matches data.json, and the analyser instances run the separate plan-body verification round.
 5. `scripts/okstra-render-final-report.py` renders compact AI handoff Markdown with `templates/reports/final-report-v2.template.md`.
 6. Token usage substitution fills usage/cost cells.
-7. `scripts/okstra-render-report-views.py` independently selects one of eleven dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks both derived artifacts. Schema v1 and quick Markdown inputs retain their legacy conditional path.
+7. `scripts/okstra-render-report-views.py` independently selects one of eleven dedicated task templates and emits human-facing HTML directly from the same data.json; run validation checks both derived artifacts. A quick Markdown input retains its legacy conditional path.
 
 For the three analysis sidetracks, the HTML view also exports an immutable-source `## ANALYSIS REVIEW` sidecar. A revision rerun carries that sidecar, reanalyzes the whole confirmed scope, and records one `analysisReviewResolution` row for every affected ID before `validate_analysis_report.py` accepts the result.
 
 Both Markdown and HTML are derived, not authoring sources. The schema is the contract.
 
+### 5.4 Role execution and model defaults
+
+- `scripts/okstra_ctl/domain/role.py` — canonical roles and duty mapping.
+- `scripts/okstra_ctl/model_pool.py` — unified catalog lookup.
+- `scripts/okstra_ctl/model_cli.py` — `okstra model list` and atomic `modelDefaults` writes. No inference call.
+- `scripts/okstra_ctl/pane_title.py` — pane titles from stored `executionLabel`.
+- `scripts/okstra_ctl/doctor.py` — `model_pool_diagnostics()` for `okstra doctor --json`.
+
 ---
 
 ## 6. Post-install layout
@@ -674,4 +683,4 @@ Clarifications now live in the unified `## 1. Clarification Items` table. Deprec
 
 ---
 
-*Updated: 2026-07-22 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mjs`, `src/lib/skill-catalog.mjs`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*
+*Updated: 2026-07-22 · Source of truth checked against `package.json`, `bin/okstra`, `src/cli-registry.mts`, `src/lib/skill-catalog.mts`, `tools/build.mjs`, `scripts/`, `skills/`, `agents/`, `templates/`, `schemas/`, `validators/`, and tests.*

package/docs/task-process/README.md

@@ -34,6 +34,8 @@ flowchart TD
 
 `okstra-run` does not call `scripts/okstra.sh`. Instead it goes through `okstra wizard` and `okstra render-bundle` and converges on the same single Python entrypoint, `prepare_task_bundle()`.
 
+The wizard asks role count before role models. `--role-count <role>=<N>` and `--role-model <role>=<modelRef>` are the public inputs. `lead` is a compatibility alias for `leader`. `executor` is a compatibility alias for `implementer`. New records write `leader` and `implementer`.
+
 ## 3. task-type documents
 
 | task-type | Document | One-line purpose |
@@ -63,7 +65,7 @@ flowchart TD
 | worker roster parser | [`scripts/okstra_ctl/workers.py`](../../scripts/okstra_ctl/workers.py) |
 | lead operating contract | [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md) |
 | phase profiles | [`prompts/profiles/`](../../prompts/profiles/) |
-| final report shape / HTML view | [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
+| final report shape / HTML view | [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md), [`scripts/okstra_ctl/report_views.py`](../../scripts/okstra_ctl/report_views.py) |
 
 ## 5. Quick comparison table
 

package/docs/task-process/implementation-planning.md

@@ -33,7 +33,7 @@ flowchart TD
     Defaults --> Workers[worker multi-pick<br/>claude/codex + optional antigravity]
     Workers --> Branch{customize?}
     Branch -->|no| Confirm
-    Branch -->|yes| Models[lead, claude, codex, antigravity if selected, report-writer models]
+    Branch -->|yes| Models[role counts then role models; lead is a compatibility alias for leader]
     Models --> Extras[directive, related tasks, clarification]
     Extras --> Confirm
     Confirm --> Render[render-bundle]
@@ -173,7 +173,7 @@ This phase only produces the plan document. Code-level micro-optimization, sourc
 
 - [`prompts/profiles/implementation-planning.md`](../../prompts/profiles/implementation-planning.md)
 - [`templates/reports/implementation-planning-input.template.md`](../../templates/reports/implementation-planning-input.template.md)
-- [`templates/reports/final-report.template.md`](../../templates/reports/final-report.template.md)
+- [`templates/reports/final-report-v2.template.md`](../../templates/reports/final-report-v2.template.md)
 - [`scripts/okstra_ctl/render.py`](../../scripts/okstra_ctl/render.py)
 - [`validators/validate-run.py`](../../validators/validate-run.py)
 - [`prompts/lead/okstra-lead-contract.md`](../../prompts/lead/okstra-lead-contract.md)

package/docs/task-process/implementation.md

@@ -34,7 +34,7 @@ flowchart TD
     Chain --> Executor[executor pick<br/>claude/codex/antigravity]
     Executor --> Defaults[Use defaults / Customize]
     Defaults -->|defaults| Confirm
-    Defaults -->|customize| Models[lead + executor model + report-writer model]
+    Defaults -->|customize| Models[role-model for leader, implementer, report-writer; executor is a compatibility alias]
     Models --> Extras[directive, related tasks, clarification]
     Extras --> Confirm
     Confirm --> Render[render-bundle]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.173.0",
+  "version": "0.175.1",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",
@@ -14,7 +14,7 @@
   },
   "files": [
     "bin/",
-    "src/",
+    "dist/",
     "runtime/",
     "docs/architecture.md",
     "docs/architecture/",
@@ -30,15 +30,21 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "scripts": {
-    "build": "node tools/build.mjs",
-    "prepack": "node tools/build.mjs",
+    "build:ts": "tsc --project tsconfig.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "build": "npm run build:ts && node tools/build.mjs",
+    "prepack": "npm run build",
     "test:js": "node --test tests-js/*.test.mjs",
     "test:py": "python3 -m pytest tests/",
     "test:workflow": "bash validators/validate-workflow.sh",
     "test:e2e": "bash tests-e2e/run-all.sh",
     "check": "npm run build && npm run test:js && npm run test:py && npm run test:workflow && npm run test:e2e"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "typescript": "^7.0.2"
   }
 }

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.173.0",
-  "builtAt": "2026-08-16T04:09:59.317Z",
+  "package": "0.175.1",
+  "builtAt": "2026-08-17T12:36:07.977Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

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

@@ -26,7 +26,8 @@ invocation. The final prompt's duty contract owns the role boundary,
 responsibility, and prohibited actions. This file owns Claude tool usage,
 artifact persistence, and liveness procedure only. Do not shell out to another
 model CLI, and refuse a dispatch whose prompt has no adjacent verified
-invocation metadata.
+invocation metadata. Consume the stored `executionLabel`; do not infer a role
+from the provider name. `lead` is a compatibility alias for `leader`.
 
 ## Execution Rules
 
@@ -64,7 +65,7 @@ Before producing any output, you MUST:
 2. Read every primary input file the lead enumerated under `## Inputs` (or equivalent heading) end-to-end, following the selected preamble. Analysis workers normally receive `analysis-packet.md`; implementation workers receive their role sidecar and approved deliverable inputs.
 3. When the prompt carries `**Evidence ledger:** required-v1`, follow the selected preamble's `Evidence read ledger` procedure for every claim-evidence file you open. Do not invent a separate audit-row format here.
 
-**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent or a fresh-session tmux pane, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang.
+**Heartbeat — write the audit sidecar EARLY and APPEND per stage (BLOCKING).** This worker runs as an in-process Agent, a cmux surface, or a CLI wrapper subprocess, so the lead has no `BashOutput`-style liveness signal while it waits for your return — the audit sidecar is the only signal that survives a silent hang.
 
 - **Where:** the absolute path in `**Audit sidecar path:**`.
 - **Start (before the per-file reads):** immediately after extracting `Project Root` and the assigned paths, `Write` just the heading line (`# Claude Worker Audit — <task-key>`) plus one `- PROGRESS: started <ISO-8601-UTC>` line.

package/runtime/agents/workers/report-writer-worker.md

@@ -18,7 +18,9 @@ This is the Claude host execution adapter for a materialized Okstra invocation.
 The final prompt's `report-writer` duty contract owns the role boundary,
 required responsibility, and prohibited actions. This file owns only how that
 contract is executed with Claude host tools. Refuse a dispatch whose prompt has
-no adjacent verified invocation metadata.
+no adjacent verified invocation metadata. Consume the stored `executionLabel`.
+The final-report `executionRoles[]` set must equal the execution-manifest
+`roleExecutions[]` set.
 
 - The `**Report Language:**` header in your dispatch prompt is already
   resolved to `en` or `ko` by the lead. Copy it verbatim into

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

@@ -18,7 +18,9 @@ This is the Claude host execution adapter for a materialized Okstra invocation.
 The final prompt's `translator` duty contract owns the role boundary,
 responsibility, and prohibited actions. This file owns only the extraction,
 translation-sidecar, and verification tool procedure. Refuse a dispatch whose
-prompt has no adjacent verified invocation metadata.
+prompt has no adjacent verified invocation metadata. Consume the stored
+`executionLabel`; the translator role remains `translator` even without a team
+roster.
 
 ## Procedure
 

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

@@ -67,6 +67,18 @@ while [[ $# -gt 0 ]]; do
       WORKERS_OVERRIDE="$(require_option_value --workers "${2-}")"
       shift 2
       ;;
+    --role-count)
+      ROLE_COUNTS+=("$(require_option_value --role-count "${2-}")")
+      shift 2
+      ;;
+    --role-model)
+      ROLE_MODELS+=("$(require_option_value --role-model "${2-}")")
+      shift 2
+      ;;
+    --host-session-context-json)
+      HOST_SESSION_CONTEXT_JSON="$(require_option_value --host-session-context-json "${2-}")"
+      shift 2
+      ;;
     --lead-model)
       LEAD_MODEL_OVERRIDE="$(require_option_value --lead-model "${2-}")"
       shift 2

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

@@ -3,7 +3,7 @@
 PROFILE_DIR="$WORKSPACE_ROOT/prompts/profiles"
 PROMPT_TEMPLATE="$WORKSPACE_ROOT/prompts/launch.template.md"
 TASK_INDEX_TEMPLATE="$WORKSPACE_ROOT/templates/project-docs/task-index.template.md"
-FINAL_REPORT_TEMPLATE_SOURCE="$WORKSPACE_ROOT/templates/reports/final-report.template.md"
+FINAL_REPORT_TEMPLATE_SOURCE="$WORKSPACE_ROOT/templates/reports/final-report-v2.template.md"
 RUN_VALIDATOR_PATH="$WORKSPACE_ROOT/validators/validate-run.py"
 OKSTRA_ROOT=""
 OKSTRA_TASKS_ROOT=""
@@ -19,6 +19,9 @@ RESUME_CLARIFICATION_MODE="false"
 RESUME_SESSION_MODE="false"
 RESUME_SESSION_ID=""
 WORKERS_OVERRIDE=""
+ROLE_COUNTS=()
+ROLE_MODELS=()
+HOST_SESSION_CONTEXT_JSON=""
 LEAD_MODEL_OVERRIDE=""
 LEAD_PROVIDER_OVERRIDE=""
 CLAUDE_MODEL_OVERRIDE=""

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

@@ -104,8 +104,8 @@ options:
   --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
+                      One of: claude | codex | antigravity | grok | kimi. Default: OKSTRA_DEFAULT_EXECUTOR or claude.
+                      The Executor is the only worker allowed to mutate project files; the other
                       providers are dispatched as read-only verifiers regardless of this selection.
                       Has no effect on other task types.
   --critic             Provider for the opt-in Phase 5.6 critic pass (coverage gaps /
@@ -132,9 +132,9 @@ model defaults:
   Claude worker: OKSTRA_DEFAULT_CLAUDE_MODEL or opus
   Codex worker: OKSTRA_DEFAULT_CODEX_MODEL or gpt-5.6-sol
   Antigravity worker: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
-  Grok worker: grok-build-0.1 (analyser) or grok-4.5 (critic)
+  Grok worker: grok-4.6
   Kimi worker: kimi-k2.7-code (analyser) or kimi-k3 (critic)
-  Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
+  Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity | grok | kimi)
 
 output:
   Stable task bundles are stored under: