okstra 0.145.0 → 0.146.0

package/runtime/python/okstra_ctl/worker_prompt_contract.py

@@ -19,6 +19,8 @@ MAX_FINAL_VERIFICATION_BODY_LINES = 96
 PROMPT_DELIVERY_MODE_HEADER = "**Prompt Delivery Mode:**"
 PROMPT_DELIVERY_MODES = frozenset({"eager-include", "lazy-path-reference"})
 MODEL_HEADER = "**Model:**"
+TASK_TYPE_HEADER = "**Task Type:**"
+FORBIDDEN_ACTIONS_HEADER = "**Forbidden actions:**"
 
 _DIRECTIVE_HEADING = "## Run-specific directive"
 _WORKER_ERROR_CONTRACT_HEADER = "**Worker Error Contract Path:**"
@@ -177,6 +179,61 @@ def validate_analysis_prompt_set(prompts: Mapping[str, str]) -> list[str]:
     return [f"normalized initial analysis prompts differ across workers: {workers}"]
 
 
+def validate_reverify_prompt(
+    text: str,
+    *,
+    task_type: str,
+    forbidden_actions: str,
+) -> list[str]:
+    """Require the active phase boundary in a lightweight reverify prompt."""
+    normalized = text.replace("\r\n", "\n").replace("\r", "\n")
+    errors: list[str] = []
+    task_values = _header_values(normalized, TASK_TYPE_HEADER)
+    if task_values != [task_type]:
+        errors.append(
+            f"exactly one {TASK_TYPE_HEADER} {task_type} header is required"
+        )
+    action_blocks = _section_values(normalized, FORBIDDEN_ACTIONS_HEADER)
+    if len(action_blocks) != 1:
+        errors.append("exactly one **Forbidden actions:** block is required")
+    elif action_blocks[0] != forbidden_actions.strip():
+        errors.append(
+            "Forbidden actions block must exactly match active-run-context "
+            "workflow.forbiddenActions"
+        )
+
+    expected_task_header = f"{TASK_TYPE_HEADER} {task_type}"
+    boundary_position = normalized.find(expected_task_header)
+    read_scope_position = normalized.find("**Read scope:**")
+    if boundary_position >= 0 and (
+        read_scope_position < 0 or read_scope_position > boundary_position
+    ):
+        errors.append("phase boundary block must follow the reverify anchor headers")
+    first_heading = re.search(r"(?m)^##\s+", normalized)
+    if (
+        boundary_position >= 0
+        and first_heading is not None
+        and boundary_position > first_heading.start()
+    ):
+        errors.append("phase boundary block must precede reverify instructions")
+    return errors
+
+
+def _section_values(text: str, header: str) -> list[str]:
+    lines = text.splitlines()
+    values: list[str] = []
+    for index, line in enumerate(lines):
+        if line.strip() != header:
+            continue
+        body: list[str] = []
+        for candidate in lines[index + 1:]:
+            stripped = candidate.strip()
+            if stripped.startswith("## ") or re.match(r"^\*\*[^*]+:\*\*", stripped):
+                break
+            body.append(candidate)
+        values.append("\n".join(body).strip())
+    return values
+
 
 def validate_initial_prompt_records(
     *,

package/runtime/python/okstra_ctl/worker_state.py

@@ -0,0 +1,65 @@
+"""Authoritative worker status transitions for one persisted team-state."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .dispatch_state import DispatchError, WORKER_STATUSES, transition_worker_status
+
+
+def _validated_team_state_path(value: str) -> Path:
+    path = Path(value).resolve()
+    if not any(parent.name == ".okstra" for parent in (path.parent, *path.parents)):
+        raise DispatchError(
+            f"team-state is outside a project .okstra directory: {path}"
+        )
+    return path
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="okstra worker-state")
+    commands = parser.add_subparsers(dest="command", required=True)
+    transition = commands.add_parser(
+        "transition", help="atomically transition one worker status"
+    )
+    transition.add_argument("--team-state", required=True)
+    transition.add_argument("--worker", required=True)
+    transition.add_argument("--status", required=True, choices=sorted(WORKER_STATUSES))
+    transition.add_argument("--reason", default="")
+    transition.add_argument("--model", default="")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        team_state_path = _validated_team_state_path(args.team_state)
+        transition_worker_status(
+            team_state_path,
+            args.worker,
+            args.status,
+            args.reason,
+            model_execution_value=args.model,
+        )
+    except DispatchError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(
+        json.dumps(
+            {
+                "ok": True,
+                "teamStatePath": str(team_state_path),
+                "workerId": args.worker,
+                "status": args.status,
+            },
+            ensure_ascii=False,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_token_usage/antigravity.py

@@ -14,6 +14,9 @@ from __future__ import annotations
 from pathlib import Path
 
 
+PRINT_MODE_USAGE_NOTE = "N/A — print mode exposes no transcript"
+
+
 def antigravity_session_total(json_path: Path) -> dict:
     return {"totalTokens": 0, "available": False}
 

package/runtime/python/okstra_token_usage/codex.py

@@ -2,9 +2,13 @@
 from __future__ import annotations
 
 import json
+import os
 from pathlib import Path
 from .jsonl_io import iter_jsonl
-from .paths import CODEX_SESSIONS, ts_in_window
+from .paths import CODEX_SESSIONS, codex_session_roots, ts_in_window
+
+
+_DEFAULT_CODEX_SESSIONS = CODEX_SESSIONS
 
 
 def codex_session_total(jsonl_path: Path) -> dict:
@@ -52,33 +56,60 @@ def find_codex_session(cwd: Path, started_at: str, ended_at: str) -> Path | None
     return sessions[-1] if sessions else None
 
 
-def find_codex_sessions(cwd: Path, started_at: str, ended_at: str) -> list[Path]:
+def _session_metadata(path: Path) -> tuple[str, str] | None:
+    try:
+        with path.open() as fh:
+            first = fh.readline()
+    except OSError:
+        return None
+    if not first:
+        return None
+    try:
+        record = json.loads(first)
+    except json.JSONDecodeError:
+        return None
+    if record.get("type") != "session_meta":
+        return None
+    payload = record.get("payload") or {}
+    timestamp = payload.get("timestamp") or record.get("timestamp") or ""
+    return str(payload.get("cwd") or ""), timestamp
+
+
+def find_codex_sessions(
+    cwd: Path,
+    started_at: str,
+    ended_at: str,
+    *,
+    session_roots: tuple[Path, ...] | None = None,
+) -> list[Path]:
     """Find codex rollout jsonls whose meta.cwd matches the window."""
-    if not CODEX_SESSIONS.is_dir() or not started_at or not ended_at:
+    if not started_at or not ended_at:
         return []
+    if session_roots is None:
+        if CODEX_SESSIONS != _DEFAULT_CODEX_SESSIONS:
+            session_roots = (CODEX_SESSIONS,)
+        else:
+            session_roots = codex_session_roots(Path.home(), os.environ)
     target_cwd = str(cwd)
     candidates: list[tuple[str, Path]] = []
-    for p in CODEX_SESSIONS.rglob("rollout-*.jsonl"):
-        try:
-            with p.open() as fh:
-                first = fh.readline()
-        except OSError:
-            continue
-        if not first:
-            continue
-        try:
-            rec = json.loads(first)
-        except json.JSONDecodeError:
-            continue
-        if rec.get("type") != "session_meta":
-            continue
-        payload = rec.get("payload") or {}
-        if payload.get("cwd") != target_cwd:
-            continue
-        ts = payload.get("timestamp") or rec.get("timestamp") or ""
-        if not ts_in_window(ts, started_at, ended_at):
+    seen: set[Path] = set()
+    for root in session_roots:
+        if not root.is_dir():
             continue
-        candidates.append((ts, p))
+        for p in root.rglob("rollout-*.jsonl"):
+            identity = p.resolve()
+            if identity in seen:
+                continue
+            seen.add(identity)
+            metadata = _session_metadata(p)
+            if metadata is None:
+                continue
+            session_cwd, ts = metadata
+            if session_cwd != target_cwd:
+                continue
+            if not ts_in_window(ts, started_at, ended_at):
+                continue
+            candidates.append((ts, p))
     if not candidates:
         return []
     candidates.sort()

package/runtime/python/okstra_token_usage/collect.py

@@ -15,11 +15,13 @@ from .claude import (
 )
 from .codex import codex_session_total, find_codex_sessions
 from .antigravity import (
+    PRINT_MODE_USAGE_NOTE,
     antigravity_session_total,
     find_antigravity_sessions,
 )
 from .paths import claude_project_dir, utc_now
 from .pricing import codex_cost_usd, antigravity_cost_usd
+from okstra_ctl.wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
 def match_prefixes(worker_id: str) -> list[str]:
@@ -434,7 +436,7 @@ def _codex_worker_windows(project_root: Path, state: dict) -> dict[str, list[tup
     running_workers = {
         str(worker.get("workerId") or "").strip()
         for worker in state.get("workers", [])
-        if isinstance(worker, dict) and worker.get("status") == "running"
+        if isinstance(worker, dict) and worker.get("status") in {"running", "in-progress"}
     }
     if running_workers:
         open_until = utc_now()
@@ -512,12 +514,116 @@ def _cli_usage_block(provider: str, totals: dict, session_paths: list[Path]) ->
     return block
 
 
+def _epoch_iso(value: object) -> str | None:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return None
+    return datetime.fromtimestamp(value, timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def wrapper_execution(status_path: Path | None) -> dict:
+    """Read wrapper execution evidence without inferring token availability."""
+    if status_path is None or not status_path.is_file():
+        return {"status": "not-started"}
+    status = read_wrapper_status(status_path)
+    if status is None:
+        return {"status": "failed", "statusPath": str(status_path)}
+
+    if status.timeout:
+        execution_status = "timeout"
+    elif status.stage == "started":
+        execution_status = "started"
+    elif status.stage == "exited" and status.exit_code == 0:
+        execution_status = "exited"
+    else:
+        execution_status = "failed"
+
+    execution = {
+        "status": execution_status,
+        "statusPath": str(status_path),
+        "startedAt": _epoch_iso(status.raw.get("started_ts")),
+        "endedAt": _epoch_iso(status.raw.get("ended_ts")),
+    }
+    if status.exit_code is not None:
+        execution["exitCode"] = status.exit_code
+    return execution
+
+
+def _execution_note(execution: dict) -> str:
+    status = execution["status"]
+    if status == "exited":
+        return f"wrapper exited {execution.get('exitCode', 0)}"
+    if status == "timeout":
+        return "wrapper timed out"
+    if status == "failed":
+        exit_code = execution.get("exitCode")
+        if exit_code is not None:
+            return f"wrapper failed with exit code {exit_code}"
+        return "wrapper status is invalid"
+    if status == "started":
+        return "wrapper started and has not recorded an exit"
+    return "wrapper status sidecar is unavailable"
+
+
+def collect_cli_usage(
+    *,
+    provider: str,
+    status_path: Path | None,
+    sessions: list[Path],
+    fallback_window_used: bool = False,
+) -> dict:
+    """Collect attributable CLI usage while retaining execution evidence."""
+    execution = wrapper_execution(status_path)
+    execution_note = _execution_note(execution)
+
+    if provider == "antigravity":
+        block = na_block(f"{PRINT_MODE_USAGE_NOTE}; {execution_note}")
+        block["cliNote"] = block["note"]
+    else:
+        totals = _cli_session_totals(provider, sessions)
+        if not sessions:
+            block = na_block(
+                f"{execution_note}; CLI usage attribution unavailable because no transcript was found"
+            )
+            block["cliNote"] = block["note"]
+        elif not totals:
+            block = na_block(
+                f"{execution_note}; transcript found but no final token snapshot was recorded"
+            )
+            block["cliNote"] = block["note"]
+            block["cliSessionPaths"] = [str(path) for path in sessions]
+        else:
+            block = _cli_usage_block(provider, _aggregate_totals(totals), sessions)
+
+    block["cliExecutionStatus"] = execution["status"]
+    if fallback_window_used:
+        fallback_note = "wrapper status sidecar unavailable; used aggregate wrapper window fallback"
+        prior_note = block.get("cliNote")
+        block["cliNote"] = f"{prior_note}; {fallback_note}" if prior_note else fallback_note
+    return block
+
+
+def _worker_cli_windows(
+    project_root: Path,
+    worker: dict,
+    fallback_windows: list[tuple[str, str]],
+) -> tuple[list[tuple[str, str]], Path | None, bool]:
+    prompt_path = _resolve_project_path(project_root, str(worker.get("promptPath") or ""))
+    status_path = status_path_for_prompt(prompt_path) if prompt_path is not None else None
+    execution = wrapper_execution(status_path)
+    started_at = execution.get("startedAt")
+    ended_at = execution.get("endedAt")
+    if started_at:
+        return [(started_at, ended_at or utc_now())], status_path, False
+    return fallback_windows, status_path, True
+
+
 def _attach_cli_usage(
     block: dict,
     provider: str,
     project_root: Path,
-    wrapper_start: str,
-    wrapper_end: str,
+    windows: list[tuple[str, str]],
+    status_path: Path | None,
+    fallback_window_used: bool,
 ) -> None:
     """Layer aggregated CLI token/cost onto a Claude-side worker ``block``.
 
@@ -528,19 +634,21 @@ def _attach_cli_usage(
     CLI spend is fully reported. (agy print mode leaves no transcript, so the
     antigravity path still resolves to "session not found" → na cost.)
     """
-    session_paths = _cli_sessions_for_windows(
-        provider, project_root, [(wrapper_start, wrapper_end)]
+    session_paths = _cli_sessions_for_windows(provider, project_root, windows)
+    cli = collect_cli_usage(
+        provider=provider,
+        status_path=status_path,
+        sessions=session_paths,
+        fallback_window_used=fallback_window_used,
     )
-    if not session_paths:
-        block["cliNote"] = f"{provider} CLI session not found in wrapper window (fallback or never invoked)"
-        return
-    block["cliSessionPaths"] = [str(path) for path in session_paths]
-    totals = _cli_session_totals(provider, session_paths)
-    if not totals:
-        block["cliNote"] = f"{provider} CLI session found but no usage recorded (likely errored before completion)"
-        return
-    cli = _cli_usage_block(provider, _aggregate_totals(totals), session_paths)
-    for key in ("cliTotalTokens", "cliEstimatedCostUsd", "cliModel"):
+    for key in (
+        "cliTotalTokens",
+        "cliEstimatedCostUsd",
+        "cliModel",
+        "cliSessionPaths",
+        "cliNote",
+        "cliExecutionStatus",
+    ):
         if key in cli:
             block[key] = cli[key]
 
@@ -560,23 +668,17 @@ def _collect_codex_runtime_usage(state: dict, project_root: Path) -> dict:
             )
             continue
         worker_id = str(worker.get("workerId") or "").strip()
-        windows = windows_by_worker.get(worker_id, [])
-        if not windows:
-            worker["usage"] = na_block(
-                f"no lead-events dispatch window found for workerId={worker_id}"
-            )
-            continue
+        windows, status_path, used_fallback = _worker_cli_windows(
+            project_root,
+            worker,
+            windows_by_worker.get(worker_id, []),
+        )
         session_paths = _cli_sessions_for_windows(provider, project_root, windows)
-        totals = _cli_session_totals(provider, session_paths)
-        if not totals:
-            worker["usage"] = na_block(
-                f"no {provider} CLI session found in lead-events dispatch window"
-            )
-            continue
-        worker["usage"] = _cli_usage_block(
-            provider,
-            _aggregate_totals(totals),
-            session_paths,
+        worker["usage"] = collect_cli_usage(
+            provider=provider,
+            status_path=status_path,
+            sessions=session_paths,
+            fallback_window_used=used_fallback,
         )
     _populate_usage_summary(state, team_name=resolve_team_name(state),
                             sessions_found=0, needle_source="none")
@@ -779,12 +881,18 @@ def collect(team_state_path: Path, project_root: Path | None = None, *,
         # For codex/antigravity workers, sum every CLI session that fell inside
         # the aggregated wrapper window (re-dispatches leave one rollout each).
         if agent in ("codex", "antigravity"):
+            windows, status_path, used_fallback = _worker_cli_windows(
+                cwd,
+                worker,
+                [(aggregate.get("startedAt") or "", aggregate.get("endedAt") or "")],
+            )
             _attach_cli_usage(
                 block,
                 agent,
                 cwd,
-                aggregate.get("startedAt") or "",
-                aggregate.get("endedAt") or "",
+                windows,
+                status_path,
+                used_fallback,
             )
         worker["usage"] = block
 

package/runtime/python/okstra_token_usage/paths.py

@@ -1,8 +1,10 @@
 """Filesystem locations for agent session transcripts and time helpers."""
 from __future__ import annotations
 
+import os
 from datetime import datetime, timezone
 from pathlib import Path
+from typing import Mapping
 
 
 HOME = Path.home()
@@ -10,6 +12,31 @@ CLAUDE_PROJECTS = HOME / ".claude" / "projects"
 CODEX_SESSIONS = HOME / ".agent" / "sessions"
 
 
+def codex_session_roots(
+    home: Path,
+    env: Mapping[str, str],
+) -> tuple[Path, ...]:
+    """Return Codex transcript roots in configuration precedence order."""
+    candidates: list[Path] = []
+    configured_home = env.get("CODEX_HOME", "").strip()
+    if configured_home:
+        candidates.append(Path(configured_home).expanduser() / "sessions")
+    candidates.extend((
+        home / ".codex" / "sessions",
+        home / ".agent" / "sessions",
+    ))
+
+    roots: list[Path] = []
+    seen: set[Path] = set()
+    for candidate in candidates:
+        normalized = Path(os.path.abspath(candidate))
+        if normalized in seen:
+            continue
+        seen.add(normalized)
+        roots.append(candidate)
+    return tuple(roots)
+
+
 def utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 

package/runtime/python/okstra_vendor/__init__.py

@@ -26,12 +26,25 @@ imports find them deterministically.
 
 import sys as _sys
 
+
+def _alias_loaded_submodules(package: object, canonical_name: str) -> None:
+    """Expose one vendored package tree under its canonical import name."""
+    vendored_name = package.__name__
+    _sys.modules[canonical_name] = package
+    vendored_prefix = f"{vendored_name}."
+    for module_name, module in tuple(_sys.modules.items()):
+        if module is None or not module_name.startswith(vendored_prefix):
+            continue
+        suffix = module_name[len(vendored_name):]
+        _sys.modules[f"{canonical_name}{suffix}"] = module
+
+
 # Register markupsafe alias BEFORE importing jinja2 — jinja2's __init__
 # evaluates `from .environment import ...`, which does `from markupsafe
 # import Markup` at module-load time. Reversing the order would crash
 # the import chain before the alias was registered.
 from . import markupsafe as _markupsafe
-_sys.modules.setdefault("markupsafe", _markupsafe)
+_alias_loaded_submodules(_markupsafe, "markupsafe")
 
 from . import jinja2 as _jinja2  # noqa: E402
-_sys.modules.setdefault("jinja2", _jinja2)
+_alias_loaded_submodules(_jinja2, "jinja2")

package/runtime/schemas/convergence-groups-v1.0.schema.json

@@ -51,7 +51,6 @@
         "category": { "type": "string", "pattern": "\\S" },
         "ticketIds": {
           "type": "array",
-          "minItems": 1,
           "items": { "type": "string", "pattern": "\\S" }
         },
         "originWorker": { "type": "string", "pattern": "\\S" },

package/runtime/skills/okstra-run/SKILL.md

@@ -43,6 +43,7 @@ On `ok: false`, re-prompt with the same `current.step` using the error message.
 
 The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag on `pick`):
 
+- `kind: "pick"` + `presentation: "numbered-text"` → do not call `AskUserQuestion`. Render every option as a numbered Markdown list in its original order, then consume the user's next message as the answer. Submit that message unchanged with `--answer`; the wizard accepts a 1-based number, an exact option value, or an exact option label and resolves it to the canonical value. An invalid, out-of-range, or ambiguous answer returns `ok: false` and must re-prompt the same complete list.
 - `kind: "pick"` + `multi: false` (default) → render `AskUserQuestion` with `label`, `options[].label`, and `multiSelect: false`. Use the chosen `options[].value` (single string) as the answer.
 - `kind: "pick"` + `multi: true` → render `AskUserQuestion` with `label`, `options[].label`, and `multiSelect: true`. Join the chosen `options[].value` entries with `,` into a single CSV string and submit that as `--answer "csv,values"`. If the user selects nothing, still submit `--answer ""` — the wizard will reply `ok: false` and re-prompt the same step (do not skip the call).
 - `kind: "pick_group"` → render a SINGLE `AskUserQuestion` whose questions array maps 1:1 to the wizard's `questions[]`. For each entry use `questions[].label`, `questions[].options[].label`, and `multiSelect: questions[].multi`. Collect the user's chosen `options[].value` per tab, build a JSON object keyed by each `questions[].step`, and submit it as a single literal `--answer '{"lead_model":"opus","claude_model":"default",...}'`. A tab the user leaves at its default still gets its `"default"`/`""` value in the JSON. Never split a `pick_group` into multiple `AskUserQuestion` calls — the wizard already capped it at 4 tabs and emits any remainder as the next prompt.
@@ -52,7 +53,7 @@ The wizard tells you *which UI to use* via `kind` (and the optional `multi` flag
 
 The final `confirm` step is a normal `pick` step with three options — `Proceed` / `Edit` / `Abort`(abort) — and is rendered the same way (no special handling). `Edit` rewinds to any earlier step (including `base-ref`); `Abort` terminally cancels the wizard. The branch/worktree decision the run will actually use (for `implementation`, the **stage worktree** — not the task-key directory) is folded into the Step 4 confirmation summary block as a `worktree` line, so there is no separate branch-confirm prompt.
 
-Never invent additional questions. Never reorder. **Never drop, hide, or merge a `pick` / `pick_group` option** — render every `options[]` entry as its own selectable `AskUserQuestion` choice, including entries that carry a `(default)` / `(recommended)` suffix. Do NOT collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist: the wizard's `options[]` array IS the complete, authoritative choice set. Example: if a pick's `options[]` carries N entries, render all N as selectable choices — never abbreviate a multi-option step down to one recommended value. The run-prompt recommendation rule (1–2 recommendations + Enter directly) applies ONLY to prompts this skill authors itself (e.g. the conformance-waiver picker), never to wizard-provided `options[]`. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
+Never invent additional questions. Never reorder. **Never drop, hide, or merge a `pick` / `pick_group` option** — render every `options[]` entry, including entries that carry a `(default)` / `(recommended)` suffix. Use an `AskUserQuestion` choice unless the wizard explicitly sets `presentation: "numbered-text"`; that presentation preserves overflow choices as a numbered Markdown list. Do NOT collapse a multi-option pick into a "recommended + Enter directly / Other" shortlist: the wizard's `options[]` array IS the complete, authoritative choice set. Example: if a pick's `options[]` carries N entries, render all N — never abbreviate a multi-option step down to one recommended value. The run-prompt recommendation rule (1–2 recommendations + Enter directly) applies ONLY to prompts this skill authors itself (e.g. the conformance-waiver picker), never to wizard-provided `options[]`. Never use `AskUserQuestion` for `text` prompts — the wizard explicitly chose `text` to avoid the picker-Other re-render lag.
 
 ## Step 1: Preflight
 
@@ -62,7 +63,15 @@ Run one Bash tool call (Bash invocation rule from the top of this file applies):
 okstra preflight --runtime claude-code --json
 ```
 
-Parse the stdout JSON. `ok: true` → carry `projectRoot` and `projectId` as literal strings into Step 2. `ok: false` (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — run `/okstra-setup` first." Then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
+Parse the stdout JSON. `ok: false` (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — run `/okstra-setup` first." Then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try to invoke `npx -y okstra@latest ...` as a fallback — `npx` is not on the literal-token allow-list and will force a confirmation prompt on every wizard call afterward. Every subsequent `okstra <subcmd>` call self-bootstraps its Python path, so never `export PYTHONPATH=...`.
+
+On `ok: true`, inspect `runtimeReadiness.checks` for the check whose `id` is `workspace-trust`. This is a Claude Code host-runtime check, independent of whether the worker providers are Claude, Codex, or Antigravity.
+
+- `status: required` with `action: restart-and-trust` → tell the user: "Claude Code must trust `<projectRoot>` before Okstra can dispatch workers. Close this session, reopen that project in Claude Code, choose `Yes, I trust this folder`, then run `/okstra-run` again." Then stop before Step 2. Never start the wizard or dispatch a worker from this session.
+- `status: unavailable` → tell the user that Claude Code workspace trust could not be verified, ask them to open `<projectRoot>` directly in Claude Code and complete any trust prompt, then run `/okstra-run` again. Then stop before Step 2.
+- `status: accepted` or `status: not-applicable` → carry `projectRoot` and `projectId` as literal strings into Step 2.
+- If `runtimeReadiness` is absent, preserve compatibility with an older preflight response: carry `projectRoot` and `projectId` into Step 2. The existing `unknown command: preflight` branch remains the authoritative stale-CLI failure.
+- Any other `workspace-trust` status is unrecognized runtime output: show the status and stop before Step 2 instead of guessing that trust exists.
 
 ## Step 2: Initialize the wizard
 
@@ -90,6 +99,7 @@ Output: the same `{ok, next}` JSON described above. The first `next` is always `
 Repeat until `next.kind == "done"` (or `"aborted"` — terminal cancel, see "How the wizard talks to you"):
 
 1. **Render** the prompt according to `kind` (and `multi` for pick). **Always append the progress marker to the rendered question label** (the `AskUserQuestion` question text, or the `text`-prompt message): suffix it with ` (<next.progress.label>)` — render `progress.label` exactly as the wizard sent it, never recompute it. Example: label `Step 8/11 · 3 steps remaining` → `Select a model (Step 8/11 · 3 steps remaining)`. Re-prompts after `ok: false` reuse `current.progress.label` the same way. The progress marker is presentation-only — never send it back to the wizard as part of an answer.
+   - `pick` + `presentation: "numbered-text"` → plain text containing `label`, followed by every option as a numbered Markdown list. Consume the user's next message verbatim as the answer string.
    - `pick` + `multi: false` → `AskUserQuestion` with `multiSelect: false`, `label`, and `options`. The user's chosen option's `value` is the answer string.
    - `pick` + `multi: true` → `AskUserQuestion` with `multiSelect: true`, `label`, and `options`. Join the selected `value`s with `,` into a single literal CSV string (e.g. `"claude,codex,antigravity"`) and submit it as a single `--answer "claude,codex,antigravity"`. Empty selection submits `--answer ""` and the wizard re-prompts.
    - `pick_group` → one `AskUserQuestion` with one question per `questions[]` entry (tab). Map each tab's selected `value` back by `questions[].step`, assemble a JSON object, and submit it as a single literal `--answer '<json>'`.
@@ -171,7 +181,7 @@ okstra config set pr-template-path "<value>" --scope global
 
 If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
 
-Before rendering the next phase's bundle, reclaim the prior phase's residual resources: run `okstra phase-cleanup --task-key <args.project-id>:<args.task-group>:<args.task-id> --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"`, then send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each `dismissible-teammates` name — only to teammates you have confirmed complete, never the lead and never an in-flight worker. `--fallback-team` takes the same `session-<lead.sessionId-prefix>` label the lead recorded in team-state, and must always be passed: after a resume or compaction the session id is re-issued, and without the label the reconcile finds no live roster and prints no teammate to dismiss. Assemble `--task-key` as the 3-token `project-id:task-group:task-id` literal from `outcome.renderArgs`; any other shape (a `<task-group>/<task-id>` pair, a bare task-id) is rejected and the whole cleanup — teammate reconcile included — is silently skipped. **This applies only when advancing to a different analysis phase.** The implementation stage chain (Step 7) does its own per-stage reclaim in its step 3 and does NOT run this `--task-key` form. `--run-dir` is unnecessary — the command auto-discovers the newest completed run across phases, including staged (implementation stage / single-stage final-verification) `runs/<type>/stage-N/` runs; pass `--run-dir` only to override that discovery with a specific prior run. A cleanup failure never blocks the next phase (the Python worker returns 0); only a malformed invocation exits non-zero.
+Before rendering the next phase's bundle — and between worker rounds within a phase (reverify/critic/gapverify batches), after you have collected that round's results and token usage and before you dispatch the next round — reclaim the prior round's completed teammate panes so they do not accumulate, in two passes and adding `--keep report-writer-worker` to **both** whenever the report writer is still 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 run the same command **without** `--list` to perform the reclaim, and emit `PROGRESS: phase-batch-cleanup panes=<n>` with that count at the batch boundary. Call both passes after collecting results and before the next dispatch so no in-flight worker pane is caught. This `tmux kill-pane`s the harness teammate panes; `shutdown_request` alone only idles the agent and never frees the pane, so it stays part of the run-end sequence for roster/token hygiene. `<RUN_DIR>` is the current (or just-finished) run's directory; its recorded `state/lead-pane.id` scopes the lead's session and the lead pane is never killed. In a non-tmux session there are no panes and the script is a silent no-op.
 
 Build the `okstra render-bundle` invocation from `outcome.renderArgs`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
@@ -272,7 +282,7 @@ Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`
 
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become Claude lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
-3. After confirming that `done` row was written, run `okstra phase-cleanup --run-dir "<the run dir of the stage you just completed>" --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"`; for each `dismissible-teammates` name, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` — only to teammates you have confirmed complete, never the lead and never an in-flight worker. Then move to the next stage.
+3. After confirming that `done` row was written, reclaim the completed teammate panes of the stage you just finished: run `$HOME/.okstra/bin/okstra-trace-cleanup.sh --run-dir "<the run dir of the stage you just completed>"` (add `--keep report-writer-worker` if the report writer is still in flight). Then move to the next stage.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.