okstra 0.163.2 → 0.165.0

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

@@ -1,121 +1,184 @@
 #!/usr/bin/env python3
-"""Run an external LLM CLI with the shared okstra wrapper contract."""
+"""Run an external LLM CLI with the shared okstra wrapper contract.
+
+Argument parsing and provider lookup only — the run itself belongs to
+``okstra_ctl.worker_runner``, which every provider shares. What stays here is
+the request the provider strategies then take on trust: resolved paths, the
+write scope in the order the CLIs are told it, and the role's idle budget.
+"""
 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
+from typing import Any, Mapping
+
+_HERE = Path(__file__).resolve().parent
+# ``okstra_ctl`` sits beside this file in the repo (``scripts/``) but under
+# ``~/.okstra/lib/python/`` once installed, and the four-line shell entrypoints
+# that exec this script set no PYTHONPATH. Offer both, repo first.
+_HOME_LIB = (
+    Path(os.environ.get("OKSTRA_HOME", str(Path.home() / ".okstra"))) / "lib" / "python"
+)
+sys.path.insert(0, str(_HERE))
+if _HOME_LIB.is_dir() and str(_HOME_LIB) not in sys.path:
+    sys.path.append(str(_HOME_LIB))
+
+from okstra_ctl.domain.provider import ProviderSpec, UnknownProviderError  # noqa: E402
+from okstra_ctl.domain.worker_exec import (  # noqa: E402
+    ExecutionStrategy,
+    WorkerExecRequest,
+)
+from okstra_ctl.registry.provider_registry import (  # noqa: E402
+    default_provider_registry,
+)
+from okstra_ctl.worker_request import build_request, idle_timeout  # noqa: E402
+from okstra_ctl.worker_runner import LIVE, QUIET, run_worker  # noqa: E402
+
+_USAGE = (
+    "usage: okstra-provider-exec.py <provider> <project-root> "
+    "<model-execution-value> <prompt-path> [worktree-path] [role] "
+    "[idle-timeout-seconds] [--presentation live|quiet]"
+)
+
+_PRESENTATION_FLAG = "--presentation"
+_PRESENTATIONS = (LIVE, QUIET)
+
+
+class PreflightError(Exception):
+    def __init__(self, exit_code: int, message: str) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
 
 
 @dataclass(frozen=True)
-class ProviderCommand:
-    binary: str
-    wrapper: str
-    build_args: Callable[[str, str, str], list[str]]
+class Invocation:
+    strategy: ExecutionStrategy
+    request: WorkerExecRequest
+    presentation: str
+    log_path: Path
+    status_path: Path
+    status_extra: Mapping[str, Any]
+
+
+def parse_invocation(argv: list[str]) -> Invocation:
+    """Resolve the wrapper's positional contract into one runnable dispatch."""
+    positional, presentation = _take_presentation(argv)
+    if not 4 <= len(positional) <= 7:
+        raise PreflightError(64, _USAGE)
+    provider_id, project_root_raw, model, prompt_raw = positional[:4]
+    worktree_raw = positional[4] if len(positional) >= 5 else ""
+    role = positional[5] if len(positional) >= 6 and positional[5] else "worker"
+    timeout_raw = positional[6] if len(positional) >= 7 and positional[6] else ""
+
+    spec = _provider_spec(provider_id)
+    project_root = _existing_dir(project_root_raw, 65, "project-root")
+    if not model:
+        raise PreflightError(66, "model-execution-value is empty")
+    prompt_path = _existing_file(prompt_raw, 67, "prompt-path")
+    idle_timeout_seconds = _idle_timeout(timeout_raw, role)
+    worktree = (
+        _existing_dir(worktree_raw, 68, "worktree-path") if worktree_raw else None
+    )
 
+    request = build_request(
+        prompt_text=prompt_path.read_text(encoding="utf-8"),
+        model=model,
+        project_root=project_root,
+        worktree_path=worktree,
+        role=role,
+        idle_timeout_seconds=idle_timeout_seconds,
+    )
+    strategy = spec.exec_strategy
+    _check_command(strategy, request)
+    return Invocation(
+        strategy=strategy,
+        request=request,
+        presentation=presentation,
+        log_path=_log_path(prompt_path),
+        status_path=Path(f"{prompt_path}.status.json"),
+        status_extra={"wrapper": spec.wrapper, "role": role},
+    )
 
-def _grok_args(prompt: str, model: str, cwd: str) -> list[str]:
-    return [
-        "grok",
-        "-p",
-        prompt,
-        "-m",
-        model,
-        "--output-format",
-        "streaming-json",
-        "--cwd",
-        cwd,
-    ]
 
+def _take_presentation(argv: list[str]) -> tuple[list[str], str]:
+    """Split the one flag out of an otherwise positional argv.
+
+    Defaults to ``quiet``. ``live`` is only ever right where a screen was
+    declared, and the only callers that can declare one are the pane backends —
+    which pass the flag explicitly. Defaulting the other way assumed a screen
+    that a subagent dispatch does not have, and sent every worker's progress
+    into its caller's context window instead.
+    """
+    positional: list[str] = []
+    presentation = QUIET
+    index = 0
+    while index < len(argv):
+        if argv[index] != _PRESENTATION_FLAG:
+            positional.append(argv[index])
+            index += 1
+            continue
+        if index + 1 >= len(argv):
+            raise PreflightError(64, f"{_PRESENTATION_FLAG} needs a value: {_USAGE}")
+        presentation = argv[index + 1]
+        index += 2
+    if presentation not in _PRESENTATIONS:
+        allowed = " | ".join(_PRESENTATIONS)
+        raise PreflightError(
+            64, f"unsupported presentation {presentation!r}. Allowed values: {allowed}"
+        )
+    return positional, presentation
 
-def _kimi_args(prompt: str, model: str, _cwd: str) -> list[str]:
-    return ["kimi", "-p", prompt, "-m", model, "--output-format", "stream-json"]
 
+def _provider_spec(provider_id: str) -> ProviderSpec:
+    try:
+        spec = default_provider_registry().resolve(provider_id)
+    except UnknownProviderError as exc:
+        raise PreflightError(64, str(exc)) from exc
+    if spec.exec_strategy is None:
+        raise PreflightError(
+            64, f"provider {provider_id!r} has no execution strategy to run"
+        )
+    return spec
 
-PROVIDERS = {
-    "grok": ProviderCommand("grok", "okstra-grok-exec.sh", _grok_args),
-    "kimi": ProviderCommand("kimi", "okstra-kimi-exec.sh", _kimi_args),
-}
 
+def _existing_dir(raw: str, exit_code: int, label: str) -> Path:
+    """Existence only — `build_request` owns the resolving."""
+    path = Path(raw) if raw else None
+    if path is None or not path.is_dir():
+        raise PreflightError(
+            exit_code, f"{label} is missing or not a directory: {raw!r}"
+        )
+    return path
 
-@dataclass(frozen=True)
-class Invocation:
-    provider: ProviderCommand
-    project_root: Path
-    model: str
-    prompt_path: Path
-    execution_root: Path
-    role: str
-    idle_timeout_seconds: int
 
+def _existing_file(raw: str, exit_code: int, label: str) -> Path:
+    path = Path(raw) if raw else None
+    if path is None or not path.is_file():
+        raise PreflightError(exit_code, f"{label} is missing or not a file: {raw!r}")
+    return path.resolve()
 
-class PreflightError(Exception):
-    def __init__(self, exit_code: int, message: str) -> None:
-        super().__init__(message)
-        self.exit_code = exit_code
 
+def _idle_timeout(raw: str, role: str) -> int:
+    try:
+        return idle_timeout(raw, role)
+    except ValueError as exc:
+        raise PreflightError(69, str(exc)) from exc
 
-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 _check_command(strategy: ExecutionStrategy, request: WorkerExecRequest) -> None:
+    """Refuse a missing CLI before the run leaves any artifact behind.
 
-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),
-    )
+    Building the command is the only truthful way to learn which binary this
+    provider runs, and it is a pure call. The check stays out of the runner so a
+    refused dispatch leaves no `started` status sidecar for the liveness probe to
+    read as a worker that launched.
+    """
+    binary = strategy.build_command(request).argv[0]
+    if shutil.which(binary) is None:
+        raise PreflightError(127, f"{binary} CLI is not installed on PATH")
 
 
 def _log_path(prompt_path: Path) -> Path:
@@ -124,105 +187,17 @@ def _log_path(prompt_path: Path) -> Path:
     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)
+        invocation = parse_invocation(argv[1:])
+        return run_worker(
+            invocation.strategy,
+            invocation.request,
+            presentation=invocation.presentation,
+            log_path=invocation.log_path,
+            status_path=invocation.status_path,
+            status_extra=invocation.status_extra,
+        )
     except PreflightError as exc:
         print(f"okstra-provider-exec: {exc}", file=sys.stderr)
         return exc.exit_code

package/runtime/bin/okstra-trace-cleanup.sh

@@ -2,13 +2,20 @@
 #
 # okstra-trace-cleanup.sh — close tmux panes created during okstra runs.
 #
-# Trace panes are `tail -F` siblings spawned by the codex/antigravity wrappers
-# (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`). Worker-compute panes are
-# tmux-pane backend siblings. Each wrapper/dispatcher tags the pane it owns with
-# a pane-level user option (`@okstra_trace_run=<RUN_DIR>` or
-# `@okstra_worker_run=<RUN_DIR>`), so panes are found server-wide by tag — no
-# tmux env var or pane-id registry is needed, and the run-scoped tag keeps
-# concurrent okstra runs from closing each other's panes.
+# Worker-compute panes are tmux-pane backend siblings. Their dispatcher tags
+# each pane it owns with a pane-level user option (`@okstra_worker_run=<RUN_DIR>`),
+# so panes are found server-wide by tag — no tmux env var or pane-id registry is
+# needed, and the run-scoped tag keeps concurrent okstra runs from closing each
+# other's panes.
+#
+# Trace panes were `tail -F` siblings the provider wrappers split, tagged
+# `@okstra_trace_run` / `@okstra_status`. Those wrappers are now four-line
+# entrypoints and worker progress renders into the worker's own pane, so
+# NOTHING SPAWNS A TRACE PANE and neither tag has a writer left. The trace
+# paths below still run and simply match nothing; `--reclaim-completed`, which
+# keys on `@okstra_status`, is inert for the same reason. Kept rather than
+# deleted because the hooks that call this script are already seeded on user
+# machines — retiring the trace machinery is a deliberate follow-up.
 #
 # Two invocation shapes:
 #

package/runtime/bin/okstra-wrapper-status.py

@@ -1,27 +1,34 @@
 #!/usr/bin/env python3
-"""okstra-wrapper-status.py — heartbeat sidecar writer for codex/antigravity wrappers.
-
-The codex/antigravity wrappers (`okstra-codex-exec.sh`, `okstra-antigravity-exec.sh`)
-dispatch a long-running CLI under `Bash(run_in_background: true)` and rely on
-`BashOutput` polling for liveness. That polling stream only carries stdout
-plus a binary `running`/`completed` state. Several recovery decisions need
-more — specifically, "did this wrapper start at all, when, and how did it
-finish?" — so the wrappers write a small JSON sidecar at
-`<prompt-path>.status.json` that survives independent of the polling channel.
-
-Consumers:
-
-* `codex-worker` / `antigravity-worker` step 8c: read `log_path` to capture a
-  diagnostic tail when `exit_code == 0` but the canonical Result file is
-  absent.
-* Lead: cross-check `started_ts` / `ended_ts` to distinguish "wrapper hung
+"""okstra-wrapper-status.py — standalone CLI for the worker status sidecar.
+
+A CLI worker dispatch runs a long-running CLI in the background, and the
+polling channel that watches it carries only stdout plus a binary
+`running`/`completed` state. Several recovery decisions need more —
+specifically, "did this worker start at all, when, and how did it finish?" — so
+a small JSON sidecar is written at `<prompt-path>.status.json` that survives
+independent of the polling channel.
+
+**Nothing calls this script.** Every provider entrypoint now runs through
+`scripts/okstra_ctl/worker_runner.py`, which writes the same document
+in-process; the shell wrappers that shelled out to this file were its only
+callers and they are gone. It is kept for now rather than deleted because
+removing it also means touching the build sync list, the install payload, its
+own test module and the docs that name it — a deliberate follow-up, not a side
+effect of the wrapper migration. `scripts/okstra_ctl/wrapper_status.py` is the
+reader, and what it reads is what the runner writes.
+
+Consumers of the sidecar:
+
+* A CLI worker's diagnostic step: read `log_path` to capture a tail when
+  `exit_code == 0` but the canonical Result file is absent.
+* Lead: cross-check `started_ts` / `ended_ts` to distinguish "worker hung
   before CLI launched" from "CLI finished but never wrote artifact" when
   applying the redispatch policy (see team-contract "Lead Redispatch
   Policy on Result-Missing").
 
-Failures are deliberately non-fatal for the caller — the wrapper's main
-job is to run the underlying CLI; a missing sidecar must not break that.
-On any error the script prints a one-line diagnostic to stderr and exits 0.
+Failures are deliberately non-fatal for the caller — the caller's main job is
+to run the underlying CLI; a missing sidecar must not break that. On any error
+the script prints a one-line diagnostic to stderr and exits 0.
 
 Schema (schemaVersion 1):
 

package/runtime/bin/okstra.sh

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