okstra 0.160.0 → 0.162.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -2,7 +2,6 @@
 from __future__ import annotations
 
 import json
-import os
 import subprocess
 import time
 from dataclasses import dataclass
@@ -10,9 +9,11 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
+from . import cmux
 from . import tmux
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
+    BACKEND_CMUX_PANE,
     BACKEND_MIXED,
     BACKEND_TMUX_PANE,
     DispatchError,
@@ -185,11 +186,19 @@ def build_dispatch_plan(
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     if wait:
-        if any(job.backend == BACKEND_TMUX_PANE for job in plan.jobs):
+        pane_backends = sorted(
+            {
+                job.backend
+                for job in plan.jobs
+                if job.backend in (BACKEND_TMUX_PANE, BACKEND_CMUX_PANE)
+            }
+        )
+        if pane_backends:
             raise DispatchError(
-                "wait=True dispatch does not support tmux-pane workers: "
-                "the per-job blocking loop would serialize panes instead of "
-                "running them concurrently; dispatch tmux panes with wait=False"
+                f"wait=True dispatch does not support {'/'.join(pane_backends)} "
+                "workers: the per-job blocking loop would serialize panes "
+                "instead of running them concurrently; dispatch panes with "
+                "wait=False"
             )
         _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.jobs))
         for job in plan.jobs:
@@ -427,9 +436,30 @@ def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
         return _run_cli_wrapper(plan, job, "")
     if job.backend == BACKEND_TMUX_PANE:
         return _start_tmux_or_degrade(plan, job)
+    if job.backend == BACKEND_CMUX_PANE:
+        return _start_cmux_or_degrade(plan, job)
     raise DispatchError(f"unsupported worker backend: {job.backend}")
 
 
+def _start_cmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
+    workspace = cmux.resolve_lead_workspace()
+    if not workspace:
+        _refuse_when_cmux_is_walled_off()
+        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    try:
+        surface_id = cmux.spawn_worker_surface(
+            workspace=workspace,
+            cwd=plan.project_root,
+            command=job.command,
+            title=f"{job.worker_id}-worker",
+        )
+    except (RuntimeError, OSError, subprocess.SubprocessError):
+        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    return WorkerHandle(
+        job, surface_id, None, status_path_for_prompt(job.prompt_path), ""
+    )
+
+
 def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     lead_pane = tmux.resolve_caller_pane()
     if not lead_pane:
@@ -447,17 +477,35 @@ def _start_tmux_or_degrade(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
     return WorkerHandle(job, pane_id, None, status_path_for_prompt(job.prompt_path), "")
 
 
+def _refuse_when_cmux_is_walled_off() -> None:
+    """Stop rather than degrade when a sandbox stands between okstra and cmux.
+
+    prepare records `cmux-pane` only after reaching cmux, so losing it by
+    dispatch time means something came between. When the socket is present but
+    connecting is denied, that something is a sandbox around the lead — and the
+    same sandbox hides the worker CLIs' own config, so the fallback this would
+    otherwise take is already dead. Degrading here spends every worker's retry
+    budget on the same wall and leaves the user with three failures and no
+    explanation, which is exactly what it looks like when nothing happens.
+    """
+    reason = cmux.unreachable_reason()
+    if reason not in (cmux.LOST_ENVIRONMENT, cmux.LOST_DENIED):
+        return
+    observed = (
+        "this process has no cmux environment left — a sandbox sanitized it"
+        if reason == cmux.LOST_ENVIRONMENT
+        else "cmux is running but this process may not connect to its socket"
+    )
+    raise DispatchError(
+        f"this run was prepared for cmux panes, but {observed}. The same "
+        "sandbox blocks worker CLIs from their own config, so falling back to "
+        "blocking workers would fail too. Relaunch the lead outside a sandbox "
+        "(codex: `codex -s danger-full-access`)."
+    )
+
+
 def _run_cli_wrapper(plan: DispatchPlan, job: WorkerJob, degraded_from: str) -> WorkerHandle:
-    env = {
-        **os.environ,
-        "OKSTRA_WORKER_ID": job.worker_id,
-        "OKSTRA_WORKER_RESULT_PATH": str(job.result_path),
-        "OKSTRA_WORKER_AUDIT_PATH": str(job.worker_result_path),
-        "OKSTRA_RUN_MANIFEST_PATH": str(plan.manifest_path),
-    }
-    if job.worker_id == REPORT_WRITER_WORKER_ID:
-        env["OKSTRA_REPORT_WRITER_MARKDOWN_PATH"] = str(_final_report_markdown_path(job.result_path))
-    completed = subprocess.run(job.command, cwd=plan.project_root, env=env, text=True)
+    completed = subprocess.run(job.command, cwd=plan.project_root, text=True)
     return WorkerHandle(job, "", completed, status_path_for_prompt(job.prompt_path), degraded_from)
 
 
@@ -561,7 +609,7 @@ def _dispatch_record(
 
 
 def _liveness_mode(backend: str) -> str:
-    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE):
+    if backend in (BACKEND_CLI_WRAPPER, BACKEND_TMUX_PANE, BACKEND_CMUX_PANE):
         return LIVENESS_WRAPPER_STATUS
     return LIVENESS_AUDIT_HEARTBEAT
 
@@ -615,7 +663,44 @@ def _skip_reasons(
     return {w: "skipped by worker dispatch default: worker is not supported by this dispatcher" for w in _string_list(manifest.get("recommendedWorkers")) if w not in set(selected) and w not in supported}
 
 
+_SIDEBAR_LEVELS = {
+    "worker-dispatched": "progress",
+    "worker-result-collected": "success",
+    "worker-retry-scheduled": "warning",
+    "worker-failed": "error",
+}
+
+
+def _relay_to_sidebar(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
+    """Mirror a dispatch event onto the cmux sidebar.
+
+    A long run is mostly silence, and the sidebar is the one surface still
+    visible after the user scrolls away or switches workspaces. A failed worker
+    additionally raises a notification, because that is the event whose cost
+    grows the longer it goes unnoticed.
+    """
+    # The plan's backend, not the manifest field it was resolved from: a job
+    # that degraded to the blocking wrapper is still part of a cmux run, and
+    # that degradation is exactly what the sidebar should keep showing.
+    if plan.default_backend != BACKEND_CMUX_PANE:
+        return
+    workspace = cmux.resolve_lead_workspace()
+    worker_id = str(details.get("workerId", "") or "worker")
+    cmux.sidebar_log(
+        workspace,
+        f"{worker_id}: {event_type.removeprefix('worker-')}",
+        level=_SIDEBAR_LEVELS.get(event_type, "info"),
+    )
+    if event_type == "worker-failed":
+        cmux.sidebar_notify(
+            workspace,
+            title=f"okstra — {_require_string(plan.manifest, 'taskType')}",
+            body=f"{worker_id} failed: {details.get('reason', 'no reason recorded')}",
+        )
+
+
 def _append_event(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
+    _relay_to_sidebar(plan, event_type, details)
     append_lead_event(
         plan.lead_events_path,
         LeadEvent(

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -24,6 +24,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Mapping, Sequence
 
+from . import cmux
 from .worker_prompt_contract import (
     PromptRecord,
     validate_initial_prompt_records,
@@ -32,8 +33,23 @@ from .worker_prompt_contract import (
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
+BACKEND_CMUX_PANE = "cmux-pane"
 BACKEND_MIXED = "mixed"
 
+
+def detect_terminal_backend() -> str:
+    """Which pane backend this run gets. Called once, by prepare.
+
+    cmux wins wherever it is usable: the only thing a tmux session buys a lead
+    is Claude Code's AgentTeam, and the cmux path deliberately does not use it.
+    Everywhere else this answers `tmux-pane`, which is what every run got before
+    cmux existed. The answer is written to the run manifest and read back from
+    there — consumers must not re-detect, or two phases of one run can disagree.
+    """
+    if cmux.cmux_available():
+        return BACKEND_CMUX_PANE
+    return BACKEND_TMUX_PANE
+
 # `livenessMode` picks which artifact answers "is this worker still alive": the
 # in-process worker's audit sidecar heartbeat, or the CLI wrapper's status
 # sidecar. Both dispatchers write it and `worker_liveness` reads it, so the

package/runtime/python/okstra_ctl/incremental_scope.py

@@ -42,6 +42,43 @@ class IncrementalDecision:
     reason: str
 
 
+@dataclass(frozen=True)
+class UserReverifyScope:
+    """What the user answered at the wizard's re-verification-scope step.
+
+    The lead still runs `okstra incremental-scope`; this only says which of the
+    CLI's inputs the user pinned. `auto` pins nothing.
+    """
+    mode: str  # "auto" | "full" | "stages"
+    stages: list[int]
+
+
+class ReverifyScopeError(ValueError):
+    """The `--reverify-scope` value is not one of the three accepted forms."""
+
+
+def parse_user_reverify_scope(raw: str) -> UserReverifyScope:
+    """`--reverify-scope` → the user's pinned scope.
+
+    Accepts exactly `""` / `auto`, `full`, or a comma-separated stage list.
+    Anything else raises rather than degrading to `auto`: a typo silently read
+    as "let the lead decide" would drop a full-re-verification request the user
+    made on purpose, and the run would look like it honoured it.
+    """
+    value = (raw or "").strip()
+    if not value or value == "auto":
+        return UserReverifyScope("auto", [])
+    if value == "full":
+        return UserReverifyScope("full", [])
+    tokens = [token.strip() for token in value.split(",") if token.strip()]
+    if not tokens or not all(token.isdigit() for token in tokens):
+        raise ReverifyScopeError(
+            f"--reverify-scope must be 'auto', 'full', or a stage-number list "
+            f"(e.g. '2,3'); got {raw!r}"
+        )
+    return UserReverifyScope("stages", sorted({int(token) for token in tokens}))
+
+
 def _parse_depends_on(cell: str) -> list[int]:
     text = (cell or "").strip()
     if not text or text == "(none)":

package/runtime/python/okstra_ctl/lead_runtime.py

@@ -1,7 +1,7 @@
 """Lead runtime metadata shared by render and prepare paths."""
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 
 
 @dataclass(frozen=True)
@@ -24,9 +24,14 @@ class LeadRuntimeInfo:
         }
 
 
-ALLOWED_LEAD_RUNTIMES = ("claude-code", "codex", "antigravity", "external")
 ARTIFACT_ONLY_LEAD_RUNTIMES = frozenset({"codex", "antigravity", "external"})
 
+# Not a lead runtime — an adapter selected by the environment, so it is absent
+# from ALLOWED_LEAD_RUNTIMES and from _LEAD_RUNTIMES on purpose. `--lead-runtime
+# cmux` is not a thing a user can ask for; see `with_cmux_dispatch`.
+CMUX_ADAPTER_NAME = "cmux"
+CMUX_ADAPTER_RELATIVE_PATH = "lead/adapters/cmux.md"
+
 _LEAD_RUNTIMES = {
     "claude-code": LeadRuntimeInfo(
         runtime="claude-code",
@@ -75,6 +80,11 @@ _LEAD_RUNTIMES = {
 }
 
 
+# Derived rather than restated: a hand-written copy of the registry's own keys
+# is a list that can disagree with the thing it describes.
+ALLOWED_LEAD_RUNTIMES = tuple(_LEAD_RUNTIMES)
+
+
 def lead_runtime_info(runtime: str) -> LeadRuntimeInfo:
     try:
         return _LEAD_RUNTIMES[runtime]
@@ -85,3 +95,21 @@ def lead_runtime_info(runtime: str) -> LeadRuntimeInfo:
 
 def is_artifact_only_runtime(runtime: str) -> bool:
     return runtime in ARTIFACT_ONLY_LEAD_RUNTIMES
+
+
+def with_cmux_dispatch(info: LeadRuntimeInfo) -> LeadRuntimeInfo:
+    """The same lead, minus the two fields cmux takes over.
+
+    On the cmux path okstra owns the worker panes rather than the host, so
+    "which adapter" and "does this lead dispatch or only render" stop depending
+    on who the lead is — they are the same for every runtime. Overriding the two
+    fields keeps that answer in one adapter file rather than repeating it in
+    four. Everything else (agent, label, role, session accounting) still
+    describes the lead itself and is left untouched.
+    """
+    return replace(
+        info,
+        adapter_name=CMUX_ADAPTER_NAME,
+        adapter_dispatch_mode="team",
+        adapter_contract_relative_path=CMUX_ADAPTER_RELATIVE_PATH,
+    )

package/runtime/python/okstra_ctl/models.py

@@ -94,6 +94,26 @@ ANALYSIS_ROLES = frozenset({"analyser", "critic"})
 IMPLEMENTATION_ROLES = frozenset({"executor", "verifier"})
 
 
+@dataclass(frozen=True)
+class LeadLaunchSpec:
+    """How to start this provider's CLI as an interactive lead session.
+
+    The worker wrappers cannot serve here: they run one non-interactive turn and
+    exit, while a lead owns the session the user talks to. Empty `prompt_flag`
+    means the CLI takes the prompt positionally; empty `session_id_flag` means it
+    has no resumable session id and resumes from artifacts instead.
+    """
+
+    executable: str
+    model_flag: str
+    prompt_flag: str = ""
+    session_id_flag: str = ""
+    # Flags that lift the CLI's own sandbox, and what the user is agreeing to by
+    # accepting them. Empty when the CLI does not sandbox itself by default.
+    sandbox_waiver: tuple[str, ...] = ()
+    sandbox_waiver_note: str = ""
+
+
 @dataclass(frozen=True)
 class ProviderSpec:
     provider: str
@@ -102,6 +122,7 @@ class ProviderSpec:
     default_models: Mapping[str, str]
     wrapper: str
     supported_roles: frozenset[str]
+    lead_launch: Optional[LeadLaunchSpec] = None
 
 
 PROVIDERS = {
@@ -121,6 +142,11 @@ PROVIDERS = {
         supported_roles=frozenset(
             {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
         ),
+        lead_launch=LeadLaunchSpec(
+            executable="claude",
+            model_flag="--model",
+            session_id_flag="--session-id",
+        ),
     ),
     "antigravity": ProviderSpec(
         provider="antigravity",
@@ -133,6 +159,13 @@ PROVIDERS = {
         supported_roles=frozenset(
             {"lead", "analyser", "critic", "executor", "verifier"}
         ),
+        lead_launch=LeadLaunchSpec(
+            executable="agy",
+            model_flag="--model",
+            # Without this the prompt runs once and the session ends; okstra
+            # needs the lead to stay and drive the remaining phases.
+            prompt_flag="--prompt-interactive",
+        ),
     ),
     "codex": ProviderSpec(
         provider="codex",
@@ -145,6 +178,20 @@ PROVIDERS = {
         supported_roles=frozenset(
             {"lead", "analyser", "critic", "executor", "verifier", "report-writer"}
         ),
+        lead_launch=LeadLaunchSpec(
+            executable="codex",
+            model_flag="-m",
+            # A codex session sandboxes itself, and everything it spawns inherits
+            # that — okstra's dispatch and every worker CLI with it. Measured:
+            # the cmux socket returns EPERM and each worker dies unable to write
+            # its own config. A sandboxed lead cannot run okstra at all.
+            sandbox_waiver=("-s", "danger-full-access"),
+            sandbox_waiver_note=(
+                "codex will start without its filesystem and network sandbox, "
+                "which okstra needs so the lead can reach cmux and start worker "
+                "CLIs."
+            ),
+        ),
     ),
     "grok": ProviderSpec(
         provider="grok",
@@ -190,6 +237,46 @@ class UnknownProviderError(ValueError):
     """Raised when a requested provider is absent from the registry."""
 
 
+def lead_launch_spec(provider: str) -> LeadLaunchSpec:
+    """The launch spec for a provider that can lead, or an error naming why not."""
+    spec = provider_spec(provider)
+    if spec.lead_launch is None:
+        raise UnknownProviderError(
+            f"provider {provider!r} cannot act as a lead: no launch spec"
+        )
+    return spec.lead_launch
+
+
+def lead_launch_argv(
+    provider: str,
+    *,
+    model: str,
+    prompt: str,
+    session_id: str = "",
+    waive_sandbox: bool = True,
+) -> list[str]:
+    """The argv that starts this provider's CLI as the lead for one run.
+
+    The sandbox waiver is applied by default because a sandboxed lead cannot run
+    okstra at all — it reaches neither cmux nor the worker CLIs' own config. The
+    caller still owns telling the user and collecting their answer; passing
+    False produces the un-waived argv so a declined confirmation can show what
+    would otherwise have run.
+    """
+    launch = lead_launch_spec(provider)
+    argv = [launch.executable]
+    if waive_sandbox:
+        argv.extend(launch.sandbox_waiver)
+    if model:
+        argv.extend([launch.model_flag, model])
+    if session_id and launch.session_id_flag:
+        argv.extend([launch.session_id_flag, session_id])
+    if launch.prompt_flag:
+        argv.append(launch.prompt_flag)
+    argv.append(prompt)
+    return argv
+
+
 def provider_spec(provider: str) -> ProviderSpec:
     """Return one registered provider or fail before assignment/dispatch."""
     normalized = (provider or "").strip().lower()

package/runtime/python/okstra_ctl/render.py

@@ -31,7 +31,8 @@ from okstra_project.dirs import TASK_MANIFEST_FILENAME, OKSTRA_DIR_NAME, project
 from . import fix_cycles
 from .analysis_inputs import ANALYSIS_TASK_TYPES
 from .paths import okstra_home
-from .lead_runtime import lead_runtime_info
+from .dispatch_state import BACKEND_CMUX_PANE
+from .lead_runtime import lead_runtime_info, with_cmux_dispatch
 from .models import UnknownProviderError, provider_ids, provider_spec
 from .runner_resolution import native_provider_for_host
 from .path_hints import compact_active_run_context, hydrate_run_context
@@ -80,7 +81,10 @@ def _lead_runtime(ctx: dict) -> str:
 
 
 def _lead_info(ctx: dict):
-    return lead_runtime_info(_lead_runtime(ctx))
+    info = lead_runtime_info(_lead_runtime(ctx))
+    if ctx.get("TERMINAL_BACKEND") == BACKEND_CMUX_PANE:
+        return with_cmux_dispatch(info)
+    return info
 
 
 def _lead_agent(ctx: dict) -> str:
@@ -1444,6 +1448,7 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
         "hostRuntime": ctx.get("HOST_RUNTIME", "") or _lead_runtime(ctx),
         "leadRuntime": _lead_runtime(ctx),
         "leadRuntimeRequest": ctx.get("LEAD_RUNTIME_REQUEST", "") or _lead_runtime(ctx),
+        "terminalBackend": ctx.get("TERMINAL_BACKEND", ""),
         "runtimeResolution": _runtime_resolution(ctx),
         "leadAssignment": _lead_assignment(ctx),
         "workerAssignments": _worker_assignments(ctx),

package/runtime/python/okstra_ctl/run.py

@@ -46,6 +46,7 @@ from .clarification_items import (
     scan_approval_gate,
 )
 from .error_report import prior_run_error_digest
+from .incremental_scope import ReverifyScopeError, parse_user_reverify_scope
 from .qa_commands import format_errors as _format_qa_errors, validate_qa_commands
 from .material import (
     build_analysis_material,
@@ -65,6 +66,8 @@ from .model_discovery import normalize_execution_for_dispatch
 from .models import (
     ModelAssignment,
     default_model,
+    lead_launch_argv,
+    lead_launch_spec,
     provider_default_model,
     provider_ids,
     provider_spec,
@@ -96,6 +99,7 @@ from .render import (
 )
 from okstra_project.dirs import okstra_home
 
+from .dispatch_state import BACKEND_CMUX_PANE, detect_terminal_backend
 from .run_context import (
     compute_and_write_run_context,
     refresh_run_context_snapshot,
@@ -372,6 +376,10 @@ class PrepareInputs:
     # 별개 채널이다.
     stages: str = ""
     clarification_response_path: str = ""  # absolute or empty
+    # implementation-planning 전용: 사용자가 고른 이번 재실행의 재검증 범위.
+    # "" / "auto" = 리드의 `okstra incremental-scope` 판정에 맡김, "full" =
+    # 전체 재검증 강제, "<stage csv>" = 그 stage 들을 impacted 로 지정.
+    reverify_scope: str = ""
     # release-handoff 전용: PR 본문 템플릿 1회성 override. 빈 문자열이면
     # project.json → global config → 스킬 디폴트 순으로 해석된다.
     pr_template_path: str = ""
@@ -1015,9 +1023,35 @@ def _validate_prepare_inputs(project_root: Path, inp: PrepareInputs) -> list:
         raise PrepareError(
             f"clarification response file not found: {inp.clarification_response_path}"
         )
+    _validate_reverify_scope(inp)
     return ctx_stage_map
 
 
+def _validate_reverify_scope(inp: PrepareInputs) -> None:
+    """A pinned re-verification scope is only actionable on a planning re-run.
+
+    Every other phase renders the tokens too (the template always reads them),
+    but nothing consumes them there — so a value outside the one phase that
+    acts on it is a caller mistake, not a preference to honour silently.
+    """
+    if not (inp.reverify_scope or "").strip():
+        return
+    if inp.task_type != "implementation-planning":
+        raise PrepareError(
+            "--reverify-scope is only meaningful with --task-type "
+            f"implementation-planning; got {inp.task_type}"
+        )
+    if not inp.clarification_response_path:
+        raise PrepareError(
+            "--reverify-scope needs --clarification-response: there is no prior "
+            "report to narrow re-verification against"
+        )
+    try:
+        parse_user_reverify_scope(inp.reverify_scope)
+    except ReverifyScopeError as exc:
+        raise PrepareError(str(exc)) from exc
+
+
 def _prepare_implementation_approved_plan(inp: PrepareInputs) -> list:
     """Apply approved-plan inputs only after canonical brief preflight succeeds."""
     if inp.approve_plan_ack or inp.implementation_option:
@@ -2275,6 +2309,21 @@ def _related_tasks_ctx(ctx: dict, inp: PrepareInputs) -> dict[str, str]:
     }
 
 
+def _reverify_scope_ctx(raw: str) -> dict[str, str]:
+    """Render tokens for the re-verification scope the user pinned.
+
+    Always emitted: the lead prompt reads both tokens unconditionally, and an
+    absent one is a render failure rather than a silent `auto`.
+    """
+    scope = parse_user_reverify_scope(raw)
+    return {
+        "REVERIFY_SCOPE_MODE": scope.mode,
+        "REVERIFY_SCOPE_STAGES": (
+            ",".join(str(num) for num in scope.stages) or "(none)"
+        ),
+    }
+
+
 def _model_ctx(models: "_ModelBindings") -> dict[str, str]:
     """Render tokens for every model binding this run resolved."""
     return {
@@ -2394,7 +2443,17 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         json.loads(runtime_resolution_json or "{}")
     except json.JSONDecodeError as exc:
         raise PrepareError(f"invalid --runtime-resolution-json: {exc}") from exc
-    if lead_runtime != "claude-code" and not inp.render_only:
+    # Probed once here and reused below, so the gate and the manifest cannot
+    # disagree about which backend this run is on.
+    terminal_backend = detect_terminal_backend()
+    # Outside cmux only claude-code has a dispatch backend of its own. Under
+    # cmux okstra owns the panes for every lead, so the render-only restriction
+    # no longer applies to any runtime.
+    if (
+        lead_runtime != "claude-code"
+        and terminal_backend != BACKEND_CMUX_PANE
+        and not inp.render_only
+    ):
         raise PrepareError(
             f"lead runtime `{lead_runtime}` is currently render-only; "
             "use --render-only until a dispatch backend is enabled for this lead runtime."
@@ -2495,6 +2554,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
     )
 
     ctx.update({
+        "TERMINAL_BACKEND": terminal_backend,
         "EXECUTOR_WORKTREE_PATH": worktree.path,
         "EXECUTOR_WORKTREE_BRANCH": worktree.branch,
         "EXECUTOR_WORKTREE_BASE_REF": worktree.base_ref,
@@ -2565,6 +2625,7 @@ def prepare_task_bundle(inp: PrepareInputs) -> PrepareOutputs:
         "CLAUDE_SESSION_ID": claude_session_id,
         "CLARIFICATION_RESPONSE_PATH": inp.clarification_response_path,
         "CLARIFICATION_RESPONSE_RELATIVE_PATH": clarification_relative,
+        **_reverify_scope_ctx(inp.reverify_scope),
         "BRIEF_FILE_PATH": str(inp.brief_path),
         "BRIEF_RELATIVE_PATH": brief_relative,
         **_model_ctx(models),
@@ -2749,6 +2810,17 @@ def main(argv: list[str]) -> int:
         ),
     )
     p.add_argument("--clarification-response", default="", dest="clarification_response_path")
+    p.add_argument(
+        "--reverify-scope",
+        default="",
+        dest="reverify_scope",
+        help=(
+            "implementation-planning 재실행 전용. 사용자가 고른 재검증 범위. "
+            "'' / 'auto' = 리드의 incremental-scope 판정에 맡김(기본), "
+            "'full' = 전체 재검증 강제, '<stage csv>' (예: '2,3') = 그 stage 를 "
+            "impacted 로 지정."
+        ),
+    )
     p.add_argument(
         "--pr-template-path",
         default="",
@@ -2858,6 +2930,7 @@ def main(argv: list[str]) -> int:
         stage=args.stage,
         stages=args.stages,
         clarification_response_path=clarification_abs,
+        reverify_scope=args.reverify_scope,
         pr_template_path=args.pr_template_path,
         render_only=args.render_only,
         approve_plan_ack=args.approve_plan_ack,
@@ -2891,19 +2964,38 @@ def main(argv: list[str]) -> int:
     else:
         print(f"okstra current run dir: {ctx['RUN_DIR']}")
         print(f"final report path: {ctx['FINAL_REPORT_PATH']}")
+        lead_runtime_name = ctx.get("LEAD_RUNTIME", "claude-code")
+        lead_provider = lead_runtime_info(lead_runtime_name).agent
+        launch = lead_launch_spec(lead_provider)
         print(f"lead model: {ctx['LEAD_MODEL']}")
         print(f"claude session id: {ctx['CLAUDE_SESSION_ID']}")
         print(f"resume command file: {ctx['CLAUDE_RESUME_COMMAND_PATH']}")
-        print("launch mode: interactive Claude handoff")
-        print(f"claude working directory: {ctx['PROJECT_ROOT']}")
+        print(f"launch mode: interactive {launch.executable} handoff")
+        print(f"lead working directory: {ctx['PROJECT_ROOT']}")
         print()
-        # In non-render-only mode emit a small JSON the bash wrapper can parse
-        # to build the `claude` exec command. Wrapper exec's; we don't.
+        # In non-render-only mode emit the JSON a front end needs to exec the
+        # lead. The argv is assembled here rather than in the caller so provider
+        # launch knowledge stays in the catalog and every front end — the bash
+        # wrapper and the Node CLI — starts the lead identically.
+        prompt_file = Path(ctx["INSTRUCTION_SET_PATH"]) / "lead-execution-prompt.md"
         machine = {
-            "claudeSessionId": ctx["CLAUDE_SESSION_ID"],
+            "leadRuntime": lead_runtime_name,
+            "leadProvider": lead_provider,
+            "leadExecutable": launch.executable,
+            "leadSessionId": ctx["CLAUDE_SESSION_ID"],
             "leadModelExecutionValue": ctx["LEAD_MODEL_EXECUTION_VALUE"],
             "projectRoot": ctx["PROJECT_ROOT"],
-            "promptFile": str(Path(ctx["INSTRUCTION_SET_PATH"]) / "lead-execution-prompt.md"),
+            "promptFile": str(prompt_file),
+            # Non-empty only when starting this lead lowers a protection the
+            # user should agree to first. The front end asks; okstra does not
+            # waive it silently.
+            "sandboxWaiverNote": launch.sandbox_waiver_note,
+            "launchArgv": lead_launch_argv(
+                lead_provider,
+                model=ctx["LEAD_MODEL_EXECUTION_VALUE"],
+                session_id=ctx["CLAUDE_SESSION_ID"],
+                prompt=prompt_file.read_text(encoding="utf-8"),
+            ),
         }
         print(f"__OKSTRA_LAUNCH__ {json.dumps(machine)}")
     return 0