okstra 0.147.0 → 0.148.0

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-model <model>] [--claude-model <model>] [--codex-model <model>] [--antigravity-model <model>] [--report-writer-model <model>] [--lead-runtime claude-code|codex] [--executor claude|codex|antigravity] [--critic off|claude|codex|antigravity] [--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 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>]
 
 summary:
-  $DISPLAY_TOOL_NAME prepares a task-keyed instruction bundle for Claude Code and launches an interactive Claude session by default.
+  $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.
   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
@@ -75,7 +75,7 @@ optional arguments:
                        workflow.nextRecommendedPhase). Explicit flags always win.
 
 options:
-  --render-only        Render the Claude handoff prompt only. Do not launch Claude.
+  --render-only        Render the host-neutral lead handoff prompt only. Do not launch a session.
   --resume-clarification
                        Interactive convenience mode that wraps --clarification-response.
                        Locates the latest requirements-discovery or error-analysis
@@ -86,24 +86,27 @@ options:
                        (--project-id/--task-group/--task-id or --task-key). Mutually
                        exclusive with --clarification-response and --approved-plan.
   --yes                Skip interactive prompting and confirmation. Requires all required arguments.
-  --workers            Comma-separated worker list for this run. Default: claude,codex,report-writer
-                      (Antigravity worker is optional; add \`antigravity\` explicitly, e.g. --workers claude,codex,antigravity,report-writer)
-  --lead-model         Model for Claude lead. Default: OKSTRA_DEFAULT_LEAD_MODEL or opus
+  --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-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
   --antigravity-model       Model for Antigravity worker. Default: OKSTRA_DEFAULT_ANTIGRAVITY_MODEL or gemini-3.1-pro
+  --worker-model       Provider-qualified worker override CSV, e.g. grok=grok-4.5,kimi=kimi-k3.
+  --report-writer-provider
+                      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.
-                      codex is currently render-only and records Codex adapter
-                      metadata in prepared artifacts without dispatching workers.
+  --lead-runtime      Lead runtime adapter. Default: claude-code. In-host runs use the
+                      matching native lead; non-host providers use CLI wrappers.
   --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
                       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 /
-                      acceptance devil's-advocate). One of: off | claude | codex | antigravity.
+                      acceptance devil's-advocate). One of: off | claude | codex | antigravity | grok | kimi.
                       Default: off.
   --related-tasks      Optional comma-separated related task identifiers. Example: auth-token-refresh,frontend-login-ui
   --work-category      Work-category classification for this task. One of:
@@ -121,11 +124,13 @@ options:
   -h, --help           Show this help.
 
 model defaults:
-  Claude lead: OKSTRA_DEFAULT_LEAD_MODEL or opus
-  Report writer worker: OKSTRA_DEFAULT_REPORT_WRITER_MODEL or Claude lead default
+  Host-native lead: provider policy (Claude default: opus; Codex default: gpt-5.6-sol)
+  Report writer worker: selected provider policy (Claude default: sonnet)
   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)
+  Kimi worker: kimi-k2.7-code (analyser) or kimi-k3 (critic)
   Implementation executor: OKSTRA_DEFAULT_EXECUTOR or claude (one of: claude | codex | antigravity)
 
 output:

package/runtime/bin/okstra-grok-exec.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+exec python3 "$script_dir/okstra-provider-exec.py" grok "$@"

package/runtime/bin/okstra-kimi-exec.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+exec python3 "$script_dir/okstra-provider-exec.py" kimi "$@"

package/runtime/bin/okstra-provider-exec.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""Run an external LLM CLI with the shared okstra wrapper contract."""
+from __future__ import annotations
+
+import json
+import os
+import selectors
+import shutil
+import signal
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+
+@dataclass(frozen=True)
+class ProviderCommand:
+    binary: str
+    wrapper: str
+    build_args: Callable[[str, str, str], list[str]]
+
+
+def _grok_args(prompt: str, model: str, cwd: str) -> list[str]:
+    return [
+        "grok",
+        "-p",
+        prompt,
+        "-m",
+        model,
+        "--output-format",
+        "streaming-json",
+        "--cwd",
+        cwd,
+    ]
+
+
+def _kimi_args(prompt: str, model: str, _cwd: str) -> list[str]:
+    return ["kimi", "-p", prompt, "-m", model, "--output-format", "stream-json"]
+
+
+PROVIDERS = {
+    "grok": ProviderCommand("grok", "okstra-grok-exec.sh", _grok_args),
+    "kimi": ProviderCommand("kimi", "okstra-kimi-exec.sh", _kimi_args),
+}
+
+
+@dataclass(frozen=True)
+class Invocation:
+    provider: ProviderCommand
+    project_root: Path
+    model: str
+    prompt_path: Path
+    execution_root: Path
+    role: str
+    idle_timeout_seconds: int
+
+
+class PreflightError(Exception):
+    def __init__(self, exit_code: int, message: str) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+
+
+def _parse_invocation(argv: list[str]) -> Invocation:
+    if len(argv) < 4 or len(argv) > 7:
+        raise PreflightError(
+            64,
+            "usage: okstra-provider-exec.py <provider> <project-root> <model-execution-value> "
+            "<prompt-path> [worktree-path] [role] [idle-timeout-seconds]",
+        )
+    provider_id, project_root_raw, model, prompt_raw = argv[:4]
+    provider = PROVIDERS.get(provider_id)
+    if provider is None:
+        raise PreflightError(64, f"unsupported provider: {provider_id}")
+    worktree_raw = argv[4] if len(argv) >= 5 else ""
+    role = argv[5] if len(argv) >= 6 and argv[5] else "worker"
+    default_timeout = 1500 if role in {"executor", "verifier"} else 600
+    timeout_raw = argv[6] if len(argv) >= 7 else str(default_timeout)
+    return _validate_invocation(
+        provider, project_root_raw, model, prompt_raw, worktree_raw, role, timeout_raw
+    )
+
+
+def _validate_invocation(
+    provider: ProviderCommand,
+    project_root_raw: str,
+    model: str,
+    prompt_raw: str,
+    worktree_raw: str,
+    role: str,
+    timeout_raw: str,
+) -> Invocation:
+    project_root = Path(project_root_raw)
+    prompt_path = Path(prompt_raw)
+    if not project_root_raw or not project_root.is_dir():
+        raise PreflightError(65, f"project-root is missing or not a directory: {project_root_raw!r}")
+    if not model:
+        raise PreflightError(66, "model-execution-value is empty")
+    if not prompt_raw or not prompt_path.is_file():
+        raise PreflightError(67, f"prompt-path is missing or not a file: {prompt_raw!r}")
+    if not timeout_raw.isdigit():
+        raise PreflightError(69, f"idle-timeout-seconds must be a non-negative integer: {timeout_raw!r}")
+    execution_root = Path(worktree_raw) if worktree_raw else project_root
+    if worktree_raw and not execution_root.is_dir():
+        raise PreflightError(68, f"worktree-path was provided but is not a directory: {worktree_raw!r}")
+    if shutil.which(provider.binary) is None:
+        raise PreflightError(127, f"{provider.binary} CLI is not installed on PATH")
+    return Invocation(
+        provider=provider,
+        project_root=project_root.resolve(),
+        model=model,
+        prompt_path=prompt_path.resolve(),
+        execution_root=execution_root.resolve(),
+        role=role,
+        idle_timeout_seconds=int(timeout_raw),
+    )
+
+
+def _log_path(prompt_path: Path) -> Path:
+    if prompt_path.name.endswith(".md"):
+        return prompt_path.with_name(f"{prompt_path.name[:-3]}.log")
+    return Path(f"{prompt_path}.log")
+
+
+def _write_status(path: Path, status: dict[str, object]) -> None:
+    temporary = Path(f"{path}.tmp")
+    temporary.write_text(json.dumps(status, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _terminate_process(process: subprocess.Popen[bytes]) -> None:
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+    except ProcessLookupError:
+        return
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(process.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        process.wait()
+
+
+def _stream_process(
+    process: subprocess.Popen[bytes], log_file, idle_timeout_seconds: int
+) -> tuple[int, bool, int]:
+    selector = selectors.DefaultSelector()
+    assert process.stdout is not None
+    selector.register(process.stdout, selectors.EVENT_READ)
+    last_output = time.monotonic()
+    timed_out = False
+    idle_seconds = 0
+    while selector.get_map():
+        for key, _ in selector.select(timeout=0.25):
+            chunk = os.read(key.fd, 8192)
+            if not chunk:
+                selector.unregister(key.fileobj)
+                continue
+            last_output = time.monotonic()
+            sys.stdout.buffer.write(chunk)
+            sys.stdout.buffer.flush()
+            log_file.write(chunk)
+            log_file.flush()
+        idle_seconds = int(time.monotonic() - last_output)
+        if idle_timeout_seconds and idle_seconds >= idle_timeout_seconds and process.poll() is None:
+            timed_out = True
+            _terminate_process(process)
+    exit_code = process.wait()
+    return (124 if timed_out else exit_code), timed_out, idle_seconds
+
+
+def _run(invocation: Invocation) -> int:
+    prompt = invocation.prompt_path.read_text(encoding="utf-8")
+    command = invocation.provider.build_args(prompt, invocation.model, str(invocation.execution_root))
+    status_path = Path(f"{invocation.prompt_path}.status.json")
+    log_path = _log_path(invocation.prompt_path)
+    started_ts = int(time.time())
+    started_monotonic = time.monotonic()
+    status: dict[str, object] = {
+        "schemaVersion": 1,
+        "wrapper": invocation.provider.wrapper,
+        "role": invocation.role,
+        "pid": os.getpid(),
+        "started_ts": started_ts,
+        "log_path": str(log_path),
+        "stage": "started",
+    }
+    _write_status(status_path, status)
+    with log_path.open("wb") as log_file:
+        process = subprocess.Popen(
+            command,
+            cwd=invocation.execution_root,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            start_new_session=True,
+        )
+        exit_code, timed_out, idle_seconds = _stream_process(
+            process, log_file, invocation.idle_timeout_seconds
+        )
+    ended_ts = int(time.time())
+    status.update(
+        stage="exited",
+        exit_code=exit_code,
+        ended_ts=ended_ts,
+        duration_ms=int((time.monotonic() - started_monotonic) * 1000),
+    )
+    if timed_out:
+        status.update(
+            timeout=True,
+            idle_at_ts=ended_ts,
+            idle_seconds=idle_seconds,
+            terminated_by="idle-watchdog",
+        )
+    _write_status(status_path, status)
+    return exit_code
+
+
+def main(argv: list[str]) -> int:
+    try:
+        invocation = _parse_invocation(argv[1:])
+        return _run(invocation)
+    except PreflightError as exc:
+        print(f"okstra-provider-exec: {exc}", file=sys.stderr)
+        return exc.exit_code
+    except OSError as exc:
+        print(f"okstra-provider-exec: execution failed: {exc}", file=sys.stderr)
+        return 127 if isinstance(exc, FileNotFoundError) else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/runtime/bin/okstra.sh

@@ -110,10 +110,13 @@ PY_ARGS=(
 [[ -n "${DIRECTIVE-}" ]] && PY_ARGS+=(--directive "$DIRECTIVE")
 [[ -n "${FIX_CYCLE-}" ]] && PY_ARGS+=(--fix-cycle "$FIX_CYCLE")
 [[ -n "${WORKERS_OVERRIDE-}" ]] && PY_ARGS+=(--workers "$WORKERS_OVERRIDE")
+[[ -n "${LEAD_PROVIDER_OVERRIDE-}" ]] && PY_ARGS+=(--lead-provider "$LEAD_PROVIDER_OVERRIDE")
 [[ -n "${LEAD_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--lead-model "$LEAD_MODEL_OVERRIDE")
 [[ -n "${CLAUDE_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--claude-model "$CLAUDE_MODEL_OVERRIDE")
 [[ -n "${CODEX_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--codex-model "$CODEX_MODEL_OVERRIDE")
 [[ -n "${ANTIGRAVITY_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--antigravity-model "$ANTIGRAVITY_MODEL_OVERRIDE")
+[[ -n "${WORKER_MODELS_OVERRIDE-}" ]] && PY_ARGS+=(--worker-model "$WORKER_MODELS_OVERRIDE")
+[[ -n "${REPORT_WRITER_PROVIDER_OVERRIDE-}" ]] && PY_ARGS+=(--report-writer-provider "$REPORT_WRITER_PROVIDER_OVERRIDE")
 [[ -n "${REPORT_WRITER_MODEL_OVERRIDE-}" ]] && PY_ARGS+=(--report-writer-model "$REPORT_WRITER_MODEL_OVERRIDE")
 [[ -n "${LEAD_RUNTIME-}" ]] && PY_ARGS+=(--lead-runtime "$LEAD_RUNTIME")
 [[ -n "${EXECUTOR_OVERRIDE-}" ]] && PY_ARGS+=(--executor "$EXECUTOR_OVERRIDE")

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

@@ -0,0 +1,48 @@
+# Antigravity Lead Runtime Adapter
+
+## Scope
+
+This adapter maps the neutral Okstra lead operations to the current Antigravity CLI host. Read it only when the rendered launch prompt selects `leadRuntime=antigravity`.
+
+## Capability declaration
+
+| Field | Value |
+|---|---|
+| `runtime` | `antigravity` |
+| `leadRoleLabel` | `Antigravity lead` |
+| `userPromptMode` | `host-text` |
+| `workerDispatchBackend` | `mixed` |
+| `initialPromptDeliveryMode` | `eager-include` |
+| `sessionAccounting` | `artifact-only` |
+| `resumeMode` | `artifact-checkpoint` |
+| `teardownMode` | `process-cleanup` |
+| `leadEventSource` | `lead-events-jsonl` |
+
+## Semantic operation mapping
+
+| Operation | Mapping |
+|---|---|
+| `read_artifacts` | Read the manifest-provided paths through the current Antigravity host file interface. |
+| `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
+| `prompt_user` | Ask through the current host text/question interface and stop at approval gates until an explicit answer arrives. |
+| `dispatch_worker` | Dispatch every `runner=native-session` Antigravity assignment through the current host. Dispatch every `runner=cli-wrapper` assignment through its registered provider wrapper. |
+| `await_workers` | Await native host workers through the host primitive and CLI workers through their status sidecars, then verify terminal state and Result Paths. |
+| `redispatch_worker` | Start a fresh native worker or CLI wrapper attempt according to the persisted assignment and record the supplied dispatch kind. |
+| `shutdown_workers` | Perform host or process cleanup only for resources owned by this run. |
+| `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
+| `collect_usage` | Collect host- or artifact-backed usage through the existing Okstra token-usage path; do not substitute another runtime's session log. |
+
+## Antigravity dispatch details
+
+- For convergence reverify, consume the persisted round plan exactly. This adapter may map and transport each returned batch, but it cannot change batch membership and does not classify findings or branch on task type, provider, or model identity.
+- The current Antigravity session is the lead. Never launch another provider as a replacement lead.
+- The prepared run manifest and team-state are the assignment authority. Keep `runner=native-session` assignments in the current host and route `runner=cli-wrapper` assignments through the registered wrapper.
+- Do not infer the current host from an installed `agy` binary. The `antigravity` runtime must come from the active host skill or an explicit runtime flag.
+- Unsupported workers or unavailable models fail before dispatch; do not change the provider, model, or runner silently.
+- Reverify and critic retries use fresh attempts and persist the core-supplied `dispatchKind`.
+- Report-writer completion requires both the data Result Path and the worker-results audit path.
+
+## Completion, cleanup, and resume
+
+- A native host completion or successful wrapper return alone is insufficient. Verify terminal state, every required completion path, and the corresponding dispatch audit record.
+- Resume from run artifacts and lead-event checkpoints. Do not invent Claude or Codex session identifiers.

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

@@ -11,7 +11,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 | `runtime` | `claude-code` |
 | `leadRoleLabel` | `Claude lead` |
 | `userPromptMode` | `native-question` |
-| `workerDispatchBackend` | `team` |
+| `workerDispatchBackend` | `mixed` |
 | `initialPromptDeliveryMode` | `lazy-path-reference` |
 | `sessionAccounting` | `claude-jsonl` |
 | `resumeMode` | `session-id` |
@@ -25,10 +25,10 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 | `read_artifacts` | Use the host file-read primitive and preserve the core contract's read order. |
 | `write_artifact` | Use the host file-write primitive only for paths authorized by the active lifecycle phase. |
 | `prompt_user` | Use the native question tool for approvals and clarifications; do not infer an answer from silence. |
-| `dispatch_worker` | Dispatch `Agent(name: "<role>", run_in_background: true)` without `team_name`; apply the assigned model as specified below. |
+| `dispatch_worker` | Dispatch each assignment through `Agent(name: "<role>", run_in_background: true)` without `team_name`; use an in-process worker for `runner=native-session` and the assigned provider's wrapper worker for `runner=cli-wrapper`. |
 | `await_workers` | Arm one background shell poll for the pending Result Paths; the spawn acknowledgement is not completion. |
 | `redispatch_worker` | Dispatch a fresh `Agent(...)` session with the same prompt plus the core reverify/retry reason. |
-| `shutdown_workers` | Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` only to confirmed-complete teammates selected for cleanup. |
+| `shutdown_workers` | For each confirmed-complete worker selected for cleanup, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to idle the roster member **and** call `TaskStop(task_id: "<name>")` to stop its background task. Both are required; neither subsumes the other. |
 | `record_lead_event` | Emit the required `PROGRESS:` line as assistant text and persist core-required state/artifact updates. |
 | `collect_usage` | Run `okstra token-usage` against the team-state; it reads the run-scoped `~/.claude/projects` session JSONL evidence. |
 
@@ -36,14 +36,14 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 
 - The session owns one implicit team. `TeamCreate` and `TeamDelete` are absent on current Claude Code builds; never probe for them and never pass `team_name`.
 - Set `name` to the core-assigned functional role label so token attribution can match `agentName`.
-- Map the core assignment key to the native `subagent_type` field: `claude-worker`, `codex-worker`, `antigravity-worker`, or `report-writer-worker`. Never substitute `general-purpose` for a rostered Report writer worker.
-- For in-process Claude and report-writer roles, map `modelExecutionValue` to the supported family token and pass it as the `model` argument. CLI-wrapper roles apply their model in the wrapper and remain `inherit` at the Agent layer.
+- Map a `runner=native-session` Claude assignment to `claude-worker`. Map a `runner=cli-wrapper` assignment to `<provider>-worker`; the registered providers currently resolve to `claude-worker`, `codex-worker`, `antigravity-worker`, `grok-worker`, or `kimi-worker`. The functional `report-writer` worker ID does not override its provider assignment. Never substitute `general-purpose` for a rostered worker.
+- For `runner=native-session`, map `modelExecutionValue` to the supported Claude family token and pass it as the `model` argument. CLI-wrapper roles apply their exact model in the provider wrapper and remain `inherit` at the Agent layer.
 - A resumed lead can dispatch a fresh worker; resume is not a valid reason to omit a rostered role.
 
 ### Dispatch-time model enforcement
 
-- `Claude worker` and `Report writer worker` definitions declare `model: inherit`; the lead MUST override that default by passing the assigned family token (`fable`, `opus`, `sonnet`, or `haiku`) as the `Agent(...)` `model` argument.
-- Codex and Antigravity wrapper agents remain `inherit` at the Agent layer because their exact `modelExecutionValue` is applied by the wrapper CLI's own model argument.
+- A native Claude worker definition declares `model: inherit`; the lead MUST override that default by passing the assigned family token (`fable`, `opus`, `sonnet`, or `haiku`) as the `Agent(...)` `model` argument.
+- Every CLI-wrapper agent remains `inherit` at the Agent layer because its exact `modelExecutionValue` is applied by `okstra-claude-exec.sh`, `okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`, `okstra-grok-exec.sh`, or `okstra-kimi-exec.sh` according to the assignment provider.
 - Missing or unsupported family-token mapping is a pre-dispatch contract failure. Never inherit the lead model, choose a nearby alias, or switch provider silently.
 - Every analysis dispatch sets `name: "<workerId>-worker"`; convergence retries append `-reverify-r<N>`, implementation uses the functional `-executor` / `-verifier` suffix, and report writing uses `report-writer`. These values are retained as `agentName` in session JSONL for usage attribution.
 - Every Codex / Antigravity prompt includes `**Pane role:** <functional-role>` so the wrapper's optional fifth argument names both its caller pane and trace pane.
@@ -56,7 +56,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 - For convergence reverify, consume the persisted round plan exactly. This adapter may map and transport each returned batch, but it cannot change batch membership and does not classify findings or branch on task type, provider, or model identity.
 - Reverify dispatch uses a fresh one-shot `Agent(...)` call named `<workerId>-worker-reverify-r<N>`. Preserve the initial worker's definition and map an in-process Claude assignment's `modelExecutionValue` to its exact family token; CLI-wrapper assignments remain `inherit` at the Agent layer and apply the exact model in their wrapper.
 - Critic dispatch uses `name: "<provider>-worker-critic"`, `dispatchKind: "critic"`, and the exact mapped model from `config.critic.modelExecutionValue`. If that value cannot be mapped, record `critic-skipped: model-unresolved` and do not dispatch.
-- Report-writer dispatch uses `name: "report-writer"` and maps the roster assignment's `modelExecutionValue` to the supported family token. The prompt's `**Model:**` header must carry the same execution value.
+- Report-writer dispatch uses `name: "report-writer"`. A native Claude assignment maps `modelExecutionValue` to the supported family token; a CLI-wrapper assignment remains `inherit` at the Agent layer and applies the exact value in its provider wrapper. The prompt's `**Model:**` header must carry the same execution value.
 - Each variant persists its prompt path, Result Path, worker-results path, error paths, and `dispatchKind` before dispatch. Completion uses the shared background Result Path poll; an Agent acknowledgement never completes the variant.
 
 ## Completion, cleanup, and resume
@@ -71,7 +71,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 
 ### CLI-wrapper polling
 
-- Start `okstra-codex-exec.sh` / `okstra-antigravity-exec.sh` with `Bash(run_in_background: true)` and poll `BashOutput(bash_id)` back-to-back until terminal completion. Never add a foreground sleep.
+- Start the assignment's registered wrapper (`okstra-claude-exec.sh`, `okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`, `okstra-grok-exec.sh`, or `okstra-kimi-exec.sh`) with `Bash(run_in_background: true)` and poll `BashOutput(bash_id)` back-to-back until terminal completion. Never add a foreground sleep.
 - Return accumulated stdout on success. On a non-zero `exit_code`, record the real code and observed duration.
 - At the 1800-second cap, inspect the live log mtime once. Recent output grants one extension to 2100 seconds; otherwise call `KillShell(shell_id)`, record exit code 124, and return the wrapper timeout sentinel.
 - Keep the wrapper subagent alive throughout polling so its JSONL timestamp window covers the underlying CLI rollout.
@@ -81,7 +81,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 - At the start of Phase 7, run `okstra token-usage /abs/path/to/run/state/team-state-<task-type>-<seq>.json --write --summary` with the literal team-state path.
 - Read the lead and Claude-side wrapper evidence from `~/.claude/projects/<encoded-cwd>/<sessionId>.jsonl`; attribute workers by the dispatch `agentName` recorded above.
 - Resolve `teamName` from `state.teamName` or `state.team.teamName` and use the full manifest-provided value as the team needle. If it is missing, the collector's short-form fallback cannot match worker JSONLs and records those workers as `source: "unavailable"`.
-- Keep underlying Codex and Antigravity CLI usage separate from the Claude wrapper-session usage. Persist `leadUsage`, per-worker usage, and `usageSummary` before report substitution and cleanup.
+- Keep every underlying provider CLI's usage separate from the Claude wrapper-session usage. Persist `leadUsage`, per-worker usage, and `usageSummary` before report substitution and cleanup.
 
 ## Run-scoped resource lifecycle
 
@@ -89,6 +89,7 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
 - Record the lead pane once with `mkdir -p "<RUN_DIR>/state" && { . "$HOME/.okstra/bin/lib/okstra/tmux-pane.sh" 2>/dev/null && okstra_resolve_caller_pane; } > "<RUN_DIR>/state/lead-pane.id" 2>/dev/null || true`. This is silent setup and must not gate cleanup; the cleanup script protects the lead pane itself.
 - Collect and persist token usage before any live-roster cleanup, including cleanup between batches and the run-end shutdown sequence.
 - Before each new worker batch (and before the next phase's render-bundle), reclaim the prior round's completed teammate panes in two passes, adding `--keep report-writer-worker` to **both** passes while the report writer is in flight. First source the count: `$HOME/.okstra/bin/okstra-trace-cleanup.sh --list --run-dir "<RUN_DIR>" [--keep report-writer-worker]` never kills and prints one `<pane_id>\t<pane_title>` line per pane it would reclaim — count those lines as `<n>`. Then perform the reclaim by running the same command **without** `--list`, and emit the neutral contract's `PROGRESS: phase-batch-cleanup panes=<n>` checkpoint with that count. Call both passes after collecting that round's results and token usage and before the next dispatch, so no in-flight worker pane is caught. This `tmux kill-pane`s the harness teammate panes; `shutdown_request` only idles the agent and never frees the pane, so it stays part of the run-end sequence for roster/token hygiene. In a non-tmux session there are no panes, both passes no-op, and `<n>` is `0` — still emit the checkpoint. The lead pane (read from `<RUN_DIR>/state/lead-pane.id`) is always preserved.
+- Reclaiming a pane does not stop the worker's background task. Every `dispatch_worker` Agent runs with `run_in_background: true`, so a worker whose result is already collected stays a live background task for the rest of the session — that residue is what fills the harness's exit-time `Background work is running` list. At the same batch boundary, right after the pane reclaim, call `TaskStop(task_id: "<name>")` once per worker of the completed batch, passing the exact `name` used at dispatch (`<workerId>-worker`, `<workerId>-worker-reverify-r<N>`, `<provider>-worker-critic`, `report-writer`). Stop only workers whose results were already collected — never an in-flight worker, never the lead, and keep `report-writer` while it is in flight, matching the pane pass's `--keep report-writer-worker`. `TaskStop` on an already-finished task is a no-op; treat a failure as benign, record nothing, and continue the boundary. This runs in a non-tmux session too, where the pane passes no-op but the background tasks still exist.
 - After batch cleanup, record the current live session generation with `okstra token-usage "<TEAM_STATE_PATH>" --record-observed-session --project-root "<PROJECT_ROOT>"`. This protects usage accounting when Claude Code re-issues the session id after resume or compaction.
 - Claude Code cannot delete the implicit team or surgically remove an idle roster entry. Explain that teammates may remain visible until session end and, when needed, give the manual action `Delete team <teamName> in Teams/FleetView`.
 - The `SessionEnd` hook runs `$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end` as the safety net for the current live session.
@@ -104,4 +105,5 @@ This adapter maps the neutral Okstra lead operations to Claude Code host primiti
    > (Yes) Close everything and clean up teammates / (No) Keep everything
 5. On `keep`, preserve every residual resource and show `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"` plus the manual Teams/FleetView action. Tell the user that `keep` holds only until the next boundary: if this session goes on to another phase/batch, that transition's round-boundary cleanup reclaims the kept **completed** panes unattended (in-flight resources and the lead pane are never touched).
 6. On approved `clean`, emit the teardown checkpoint, run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<RUN_DIR>"`, then run `$HOME/.okstra/bin/okstra-team-reconcile.sh --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"` exactly once. The resolver reads the current live session's `~/.claude/teams/session-<live>/config.json`, falling back to the snapshot directory only when the live directory is absent, and prints `dismissible-member: <name>` records.
-7. Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each printed, confirmed-complete non-lead member. The `message` MUST be the object literal shown, NEVER a JSON string in a text field. Never target the lead or use `TaskStop`; teammates are not background tasks.
+7. Send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each printed, confirmed-complete non-lead member. The `message` MUST be the object literal shown, NEVER a JSON string in a text field. Never target the lead.
+8. Call `TaskStop(task_id: "<name>")` for every worker this run dispatched, reusing the step-7 names plus any batch worker already reclaimed earlier. `shutdown_request` only idles the roster member and the step-6 pane reclaim only closes the pane — neither ends the background task, so this step is the one that empties the harness's exit-time `Background work is running` list. Never target the lead; a `TaskStop` on an already-finished task is a benign no-op.

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

@@ -11,7 +11,7 @@ This adapter maps the neutral Okstra lead operations to the Codex artifact-first
 | `runtime` | `codex` |
 | `leadRoleLabel` | `Codex lead` |
 | `userPromptMode` | `host-text` |
-| `workerDispatchBackend` | `cli-wrapper` |
+| `workerDispatchBackend` | `mixed` |
 | `initialPromptDeliveryMode` | `eager-include` |
 | `sessionAccounting` | `artifact-only` |
 | `resumeMode` | `artifact-checkpoint` |
@@ -25,9 +25,9 @@ This adapter maps the neutral Okstra lead operations to the Codex artifact-first
 | `read_artifacts` | Read the manifest-provided paths through the current host's file interface. |
 | `write_artifact` | Write only core-authorized `.okstra/` artifacts and preserve their schemas. |
 | `prompt_user` | Ask through the host text/question interface and stop at approval gates until an explicit answer arrives. |
-| `dispatch_worker` | Run `okstra codex-dispatch --project-root <root> --run-manifest <path>`; use `--dry-run` first when the core requires a dispatch preview. |
-| `await_workers` | Treat the synchronous dispatch return plus team-state terminal records and Result Paths as completion evidence. |
-| `redispatch_worker` | Invoke a fresh `okstra codex-dispatch` worker attempt for the selected role and record the retry/reverify dispatch kind. |
+| `dispatch_worker` | Dispatch every `runner=native-session` assignment with the current Codex host's native worker/session primitive. Pass only `runner=cli-wrapper` assignments to `okstra codex-dispatch --project-root <root> --run-manifest <path> --workers <ids>`; use `--dry-run` first when the core requires a dispatch preview. |
+| `await_workers` | Await native host workers through the host primitive and CLI workers through synchronous dispatch, then verify team-state terminal records and Result Paths for both. |
+| `redispatch_worker` | Start a fresh native worker or `okstra codex-dispatch` attempt according to the persisted assignment's `runner`, and record the retry/reverify dispatch kind. |
 | `shutdown_workers` | Perform process cleanup when a wrapper remains live; otherwise this operation is a no-op recorded in state. |
 | `record_lead_event` | Append the required structured event to the manifest-provided `leadEventsPath`; emit the matching user-facing `PROGRESS:` line. |
 | `collect_usage` | Collect artifact/rollout-backed usage through the existing Okstra token-usage path; never read Claude session JSONL as a substitute. |
@@ -36,12 +36,12 @@ This adapter maps the neutral Okstra lead operations to the Codex artifact-first
 
 - For convergence reverify, consume the persisted round plan exactly. This adapter may map and transport each returned batch, but it cannot change batch membership and does not classify findings or branch on task type, provider, or model identity.
 - Do not invoke Claude Code team or subagent tools.
-- The prepared run manifest and team-state are the dispatch authority. Unsupported explicitly requested workers fail; an adapter must not silently change the roster.
-- Report-writer execution keeps the existing explicit opt-in policy in this milestone: dispatch requires `--enable-codex-report-writer` and an explicit `--report-writer-codex-model` value.
+- The prepared run manifest and team-state are the dispatch authority. A `runner=native-session` assignment stays in the current Codex host; a `runner=cli-wrapper` assignment uses the registered provider wrapper. Unsupported explicitly requested workers fail; an adapter must not silently change the roster.
+- The report-writer follows its persisted provider, model, and runner assignment exactly. It has no Codex-only provider override or separate opt-in gate.
 - Reverify and critic retries invoke a fresh worker attempt and persist the core-supplied `dispatchKind` (`reverify-r<N>` or `critic`) in the dispatch record; never reuse a prior rollout as a new vote.
 - Report-writer completion requires both the data.json Result Path and the worker-results audit path, even when the synchronous dispatch command exits successfully.
 
 ## Completion, cleanup, and resume
 
-- A successful synchronous dispatch return alone is insufficient; verify terminal state, every required completion path, and the corresponding worker-dispatch audit record before counting the worker as complete.
+- A native host completion or successful synchronous CLI return alone is insufficient; verify terminal state, every required completion path, and the corresponding worker-dispatch audit record before counting the worker as complete.
 - Resume from run artifacts and lead-events checkpoints. Do not invent a Claude session id.

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

@@ -397,7 +397,7 @@ After persistence, reply briefly in the resolved Report Language with: completio
 ## Run-scoped worker-resource lifecycle
 
 - At run start, call the selected adapter's setup required to distinguish lead-owned resources from worker-owned resources.
-- Before every new worker batch, and between worker rounds within a phase, close the prior round's completed teammate resources before the next dispatch — never the lead and never an in-flight worker; call `record_lead_event` for the batch-cleanup checkpoint. The round-boundary teammate reclaim primitive is the selected adapter's.
+- Before every new worker batch, and between worker rounds within a phase, close **every** resource the prior round's completed workers still hold — display surfaces, roster entries, and live execution handles alike — before the next dispatch; never the lead and never an in-flight worker. Call `record_lead_event` for the batch-cleanup checkpoint. Which resources exist and how each one is released is the selected adapter's mapping.
 - After Phase 7 persistence and `collect_usage`, enumerate residual adapter-owned resources. If none remain, skip the question.
 - If resources remain, call `prompt_user` once with a binary keep-or-clean choice. The answer controls the entire residual set; do not ask a second backend-specific cleanup question.
 - On keep, preserve all resources and provide the selected adapter's manual-cleanup instruction.

package/runtime/prompts/lead/report-writer.md

@@ -138,7 +138,7 @@ The remaining numbered-section guide exists only for rendering or diagnosing his
 
 ### Report Header
 
-Milestone 1 keeps the final-report schema unchanged. Read the exact permitted values for `header.reportOwner` and `header.reportAuthor` from the task bundle's `instruction-set/final-report-schema.json` excerpt of `schemas/final-report-v1.0.schema.json`, then write those schema v1 compatibility values according to the actual authorship path. Do not derive either header field from the selected runtime's lead role. Runtime identity remains visible in the execution-status row and team-state audit fields.
+Read the exact permitted values for `header.reportOwner` and `header.reportAuthor` from the task bundle's `instruction-set/final-report-schema.json` excerpt, then write those values according to the actual authorship path. The current v2 contract uses the provider-neutral `Okstra lead`; a legacy v1 excerpt may retain historical compatibility values. Do not derive either header field from the selected runtime's provider-specific lead label. Runtime identity remains visible in the execution-status row and team-state audit fields.
 
 ```markdown
 # <task-key> - Multi-Agent Cross Verification Final Report

package/runtime/prompts/profiles/_coding-conventions-preflight.md

@@ -2,7 +2,7 @@
 Single source for the executor's Coding-conventions preflight gate. Two delivery
 paths converge here (see _implementation-executor.md "Pre-implementation context
 exploration"):
-  - Claude executor reads this file directly before its first Edit / Write.
+  - The native-session executor reads this file directly before its first edit.
   - codex / antigravity executor cannot read this path (it sits outside the CLI
     sandbox and the CLI only sees its stdin prompt), so the lead appends this
     file's body into the persisted executor prompt at dispatch time.

package/runtime/prompts/profiles/_common-contract.md

@@ -5,13 +5,13 @@ Edit here once; every profile picks the change up at next render. Do NOT
 add phase-specific rules to this file — phase rules stay in the per-
 profile document.
 -->
-- Team contract (shared): roster roles, model-assignment rules, dispatch invariants, and required-worker attempt rules are canonical in the team contract (`prompts/lead/team-contract.md`). Two consequences every phase honours: `Claude lead` is synthesis-only (in `implementation`, distinct from the `Executor` and verifiers), and unnamed generic parallel workers never replace or extend the per-profile `Required workers:` roster. Prep-time model recommendations come from the catalog defaults in `okstra_ctl.models` (e.g. `Codex worker` → `gpt-5.6-sol`); at dispatch time the task-manifest's materialized assignment is the only source — there is no dispatch-time fallback.
+- Team contract (shared): roster roles, model-assignment rules, dispatch invariants, and required-worker attempt rules are canonical in the team contract (`prompts/lead/team-contract.md`). Two consequences every phase honours: the host-native Okstra lead is synthesis-only (in `implementation`, distinct from the `Executor` and verifiers), and unnamed generic parallel workers never replace or extend the per-profile `Required workers:` roster. Prep-time model recommendations come from the catalog defaults in `okstra_ctl.models` (for example, `Codex worker` → `gpt-5.6-sol`); at dispatch time the task-manifest's materialized assignment is the only source — there is no dispatch-time fallback.
 - Worker interaction model (shared — read before inferring behaviour from the roster):
   - the per-profile `Required workers:` block is a **roster**, not a behaviour contract. Each role's interaction mode changes across operating phases of the same run.
-  - **Phase 4 / 5 (independent analysis)**: analyser workers (`claude`, `codex`, `antigravity` when opted in) produce findings independently and have no access to one another's outputs. `report-writer` does not analyse.
+  - **Phase 4 / 5 (independent analysis)**: every analyser in the resolved provider assignment roster produces findings independently and has no access to another worker's output. `report-writer` does not analyse.
   - **Phase 5.5 (convergence — peer review by workers)**: workers peer-review each other's findings across up to `effectiveMaxRounds` rounds; the lead mediates but does not vote. See `prompts/lead/convergence.md` for the round protocol (replay of findings, `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts), queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, `implementation-planning`, `project-analysis`, `feature-analysis`, and `change-impact-analysis` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
-  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure). (2) **Sandbox CLI-start failure (non-tmux path):** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted` (e.g. `agy`'s `listen tcp 127.0.0.1:0: bind` under a seatbelt sandbox around a non-tmux subagent's Bash tool). In either case the lead retries that worker in-process without `run_in_background`; if it was an external CLI worker, the lead instead **substitutes** an in-process `claude` analysis. Either way the lead records the substitution as provider unavailable in the run log and the convergence notes. Completed external-CLI worker trace panes are reclaimed automatically by the `SubagentStop` hook, but okstra cannot directly reclaim the teammate panes the harness creates, so this fallback is the last line of defence against pane-budget exhaustion and sandbox-blocked CLI workers. (This is a prompt instruction, not a code-enforced gate.)
+  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure). (2) **Sandbox CLI-start failure (non-tmux path):** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted`. In either case the lead spends the one shared retry budget through the assignment's recorded runner. If the provider is still unavailable, record that terminal status and continue only under the convergence quorum rules; never replace it silently with a fixed provider or count a substitute as the original provider's vote. Completed external-CLI trace panes are reclaimed by the selected runtime adapter's resource lifecycle. (This is a prompt instruction, not a code-enforced gate.)
 - Dual-audience final-report contract (shared):
   - data.json is the sole authored report artifact. AI handoff Markdown and human HTML are independently derived from it; neither derived artifact is the other's source.
   - User-facing information belongs in `humanSummary` and the selected task block's `userNarrative`; it must not exist only in Markdown. The HTML human main body explains the result with those fields plus task facts.
@@ -82,7 +82,7 @@ profile document.
   - `verdictCard.verdictToken` and `.direction` MUST byte-match `finalVerdict`; next-step routing must agree with `recommendedNextSteps[0]`. Schema-v1 Markdown renders the visible `## Verdict Card` / `## 7. Final Verdict` pair. Schema-v2 derives the AI handoff and human summary from the data fields without repeating both visible sections. **Enforced:** `validators/validate-run.py` `_validate_verdict_card_consistency` and `_validate_verdict_card_fields`.
 - Cross-worker traceability (shared — applies to every analysis worker output and to the lead's `## 6.` / `## 2.` tables in the final-report):
   - **Worker-side item IDs (free-form but unique within the worker).** Every row item in sections 1–5 (and any optional section 6) of an analysis worker's output MUST carry an item ID that is unique within that one worker's result file. The ID convention is the worker's choice — `F-001` / `F-002` per the suggested schema, `1.1` / `1.2` / `1.3` as Codex tends to use, or any other shape — but it MUST appear as the leading column of the row (for table-form items) or as a `[<ID>]` prefix (for bullet/numbered items). Workers that emit findings without IDs make cross-worker reconciliation impossible.
-  - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises consensus, difference, or primary-evidence rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. Each `sourceItems` field MUST list every contributing worker:item pair (e.g. `claude:F-001`, `codex:1.1`, `antigravity:F-3`) so an agent can trace the synthesised row to the worker result. Bare worker names are rejected. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.SourceItem` pins each entry to `^[a-z][a-z-]*:[A-Za-z0-9._-]+$`, and `ConsensusRow` / `PrimaryEvidenceRow` require non-empty `sourceItems`.
+  - **Lead-side ID assignment + source preservation.** When the lead (or `report-writer-worker`) synthesises consensus, difference, or primary-evidence rows from worker outputs, the lead assigns a fresh `C-NNN` / `D-NNN` / `E-NNN` row ID. Each `sourceItems` field MUST list every contributing worker:item pair (e.g. `claude:F-001`, `codex:1.1`, `grok:F-3`, `kimi:2.4`) so an agent can trace the synthesised row to the worker result. Bare worker names are rejected. **Enforced:** `schemas/final-report-v2.0.schema.json` `$defs.SourceItem` pins each entry to `^[a-z][a-z-]*:[A-Za-z0-9._-]+$`, and `ConsensusRow` / `PrimaryEvidenceRow` require non-empty `sourceItems`.
 - Audit sidecar (shared): Reading Confirmation placement follows the audience-selected preamble named by `**Worker Preamble Path:**`. Profiles do not restate it; the main worker-results body starts at section 1.
 
 - Markdown authoring (shared — applies to markdown documents not already governed by an okstra template/schema):