okstra 0.175.1 → 0.176.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -9,7 +9,6 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
-from . import cmux
 from .dispatch_state import (
     BACKEND_CLI_WRAPPER,
     BACKEND_CMUX_PANE,
@@ -51,9 +50,19 @@ from .assignment_resolver import (
     RoleInstance,
     resolve_model_assignment,
 )
+from .application.open_worker import open_worker
 from .domain.host import HostSessionContext
 from .domain.provider import HostModelBinding, ServedModelAttestation
 from .domain.worker_exec import SERVED_MODEL_MISMATCH_EXIT_CODE
+from .domain.worker_runtime import (
+    SURFACE_CMUX_PANE,
+    EnvironmentBlocked,
+    ProgressEvent,
+    RuntimeHandle,
+    SurfaceUnavailable,
+    WorkerSpawnRequest,
+)
+from .ports.worker_runtime import WorkerRuntimePort
 from .execution_identity import Attempt, Invocation, RoleExecution, model_spec_digest
 from .execution_manifest import (
     finish_attempt_mutation,
@@ -229,6 +238,7 @@ class WorkerHandle:
     mutation_retry_allowed: bool = True
     write_policy_digest: str = ""
     write_enforcement: WriteEnforcement | None = None
+    runtime_handle: RuntimeHandle | None = None
 
 
 @dataclass(frozen=True)
@@ -252,6 +262,7 @@ class DispatchPlan:
     manifest: Mapping[str, Any]
     jobs: tuple[WorkerJob, ...]
     default_backend: str
+    runtime_chain: tuple[WorkerRuntimePort, ...] = ()
 
     def to_payload(self, dry_run: bool) -> dict[str, Any]:
         payload = {
@@ -358,6 +369,7 @@ def build_dispatch_plan(
 
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
+    plan = _ensure_runtime_chain(plan)
     _validate_report_writer_isolation(plan.jobs)
     _validate_implementation_phase_order(plan.jobs)
     _revalidate_plan_role_executions(plan)
@@ -391,6 +403,7 @@ def dispatch_cli_wrapper_plan(plan: DispatchPlan) -> int:
     """Start one dependency-free CLI batch before collecting any worker."""
     if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
         raise DispatchError("concurrent CLI dispatch requires cli-wrapper jobs only")
+    plan = _ensure_runtime_chain(plan)
     _validate_report_writer_isolation(plan.jobs)
     _validate_implementation_phase_order(plan.jobs)
     _revalidate_plan_role_executions(plan)
@@ -564,14 +577,17 @@ def _dispatch_cli_wrapper_batch(
                     exc,
                 )
             raise
+        from .adapters.runtime.assembly import port_for
+
         outcomes: list[tuple[WorkerHandle, int, WorkerOutcome]] = []
         for handle, attempt in active:
-            process = handle.running_process
-            if process is None:
+            runtime = handle.runtime_handle
+            if runtime is None or not runtime.waitable:
                 raise DispatchError("concurrent CLI worker process is missing")
-            returncode = process.wait()
+            port = port_for(plan.runtime_chain, runtime.surface)
+            returncode = port.wait(runtime)
             completed = subprocess.CompletedProcess(handle.job.command, returncode)
-            settled = replace(handle, completed_process=completed, running_process=None)
+            settled = replace(handle, completed_process=completed)
             outcomes.append((settled, attempt, _outcome_from_completed(settled)))
 
         next_round: list[tuple[WorkerJob, int]] = []
@@ -611,15 +627,18 @@ def _abort_cli_batch_start(
     policies: Sequence[WritePolicy],
     error: Exception,
 ) -> None:
+    from .adapters.runtime.assembly import port_for
+
     reason = f"concurrent CLI batch launch failed: {error}"
     for handle, _attempt in active:
-        process = handle.running_process
-        if process is not None and process.poll() is None:
-            process.terminate()
+        runtime = handle.runtime_handle
+        if runtime is None:
+            continue
+        port_for(plan.runtime_chain, runtime.surface).terminate(runtime)
     for handle, attempt in active:
-        process = handle.running_process
-        if process is not None:
-            process.wait()
+        runtime = handle.runtime_handle
+        if runtime is not None:
+            port_for(plan.runtime_chain, runtime.surface).wait(runtime)
         _transition_job_status(plan, handle.job, "error", reason)
         _update_dispatch_status(
             plan.team_state_path, handle.job, attempt, "error", reason
@@ -1283,18 +1302,24 @@ def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle
 def _spawn_cli_job_nonblocking(
     plan: DispatchPlan, job: WorkerJob, attempt: int,
 ) -> WorkerHandle:
-    process: subprocess.Popen[str] | None = None
+    plan = _ensure_runtime_chain(plan)
     try:
-        process = subprocess.Popen(job.command, cwd=plan.project_root, text=True)
-        handle = WorkerHandle(
-            job, "", None, status_path_for_prompt(job.prompt_path), "", process
+        runtime = open_worker(
+            _chain_starting_at(plan.runtime_chain, job.backend),
+            lambda surface: _spawn_request(plan, job, surface),
         )
-        return handle
-    except (OSError, DispatchError):
-        if process is not None and process.poll() is None:
-            process.terminate()
-            process.wait()
-        raise
+    except EnvironmentBlocked as exc:
+        raise DispatchError(str(exc)) from exc
+    except (SurfaceUnavailable, OSError) as exc:
+        raise DispatchError(str(exc)) from exc
+    return WorkerHandle(
+        job,
+        "",
+        None,
+        status_path_for_prompt(job.prompt_path),
+        "",
+        runtime_handle=runtime,
+    )
 
 
 def _prepare_job_attempt(
@@ -1515,35 +1540,66 @@ def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
     return 1
 
 
+def _ensure_runtime_chain(plan: DispatchPlan) -> DispatchPlan:
+    if plan.runtime_chain:
+        return plan
+    from .adapters.runtime.assembly import runtime_chain as build_chain
+    return replace(plan, runtime_chain=build_chain(plan.default_backend))
+
+
+def _spawn_request(
+    plan: DispatchPlan, job: WorkerJob, surface: str
+) -> WorkerSpawnRequest:
+    targeted = replace(job, backend=surface)
+    title = (
+        targeted.execution_label
+        if targeted.has_execution_identity
+        else f"{targeted.worker_id}-worker"
+    )
+    return WorkerSpawnRequest(
+        command=tuple(targeted.command),
+        cwd=plan.project_root,
+        title=title,
+        owned_surface_ids=_opened_cmux_surfaces(plan.team_state_path),
+    )
+
+
+def _chain_starting_at(
+    chain: tuple[WorkerRuntimePort, ...], surface: str
+) -> tuple[WorkerRuntimePort, ...]:
+    # A retry job is already cli-wrapper; do not walk back up to cmux-pane.
+    for index, port in enumerate(chain):
+        if port.surface == surface:
+            return chain[index:]
+    raise DispatchError(f"unsupported worker backend: {surface}")
+
+
 def _start_job(plan: DispatchPlan, job: WorkerJob) -> WorkerHandle:
-    if job.backend == BACKEND_CLI_WRAPPER:
-        return _run_cli_wrapper(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)
+    plan = _ensure_runtime_chain(plan)
     try:
-        surface_id = cmux.spawn_worker_surface(
-            workspace=workspace,
-            cwd=plan.project_root,
-            command=job.command,
-            title=(
-                job.execution_label
-                if job.has_execution_identity
-                else f"{job.worker_id}-worker"
-            ),
-            owned_surface_ids=_opened_cmux_surfaces(plan.team_state_path),
+        runtime = open_worker(
+            _chain_starting_at(plan.runtime_chain, job.backend),
+            lambda surface: _spawn_request(plan, job, surface),
         )
-    except (RuntimeError, OSError, subprocess.SubprocessError):
-        return _run_cli_wrapper(plan, job, BACKEND_CMUX_PANE)
+    except EnvironmentBlocked as exc:
+        raise DispatchError(str(exc)) from exc
+    except SurfaceUnavailable as exc:
+        raise DispatchError(str(exc)) from exc
+    degraded_from = job.backend if runtime.surface != job.backend else ""
+    settled = replace(job, backend=runtime.surface) if degraded_from else job
+    completed = None
+    if runtime.waitable:
+        from .adapters.runtime.assembly import port_for
+        returncode = port_for(plan.runtime_chain, runtime.surface).wait(runtime)
+        completed = subprocess.CompletedProcess(list(settled.command), returncode)
+    pane_id = runtime.identifier if runtime.surface == SURFACE_CMUX_PANE else ""
     return WorkerHandle(
-        job, surface_id, None, status_path_for_prompt(job.prompt_path), ""
+        settled,
+        pane_id,
+        completed,
+        status_path_for_prompt(settled.prompt_path),
+        degraded_from,
+        runtime_handle=runtime,
     )
 
 
@@ -1569,42 +1625,6 @@ def _opened_cmux_surfaces(team_state_path: Path) -> tuple[str, ...]:
     return tuple(opened)
 
 
-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:
-    # Whatever the job was planned as, this is a cli-wrapper dispatch: no pane
-    # took it, so the worker's stdout is read by whoever called the lead. The
-    # record already says so (`_dispatch_record`), and the command must agree.
-    job = replace(job, backend=BACKEND_CLI_WRAPPER)
-    completed = subprocess.run(job.command, cwd=plan.project_root, text=True)
-    return WorkerHandle(job, "", completed, status_path_for_prompt(job.prompt_path), degraded_from)
-
-
 def _outcome_from_completed(handle: WorkerHandle) -> WorkerOutcome:
     completed = handle.completed_process
     if completed is None:
@@ -2494,33 +2514,33 @@ _SIDEBAR_LEVELS = {
 
 
 def _relay_to_sidebar(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:
-    """Mirror a dispatch event onto the cmux sidebar.
+    """Mirror a dispatch event onto the lead surface.
 
-    A long run is mostly silence, and the sidebar is the one surface still
+    A long run is mostly silence, and the lead surface is the one 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.
+    grows the longer it goes unnoticed. The lead port is `runtime_chain[0]`,
+    so a worker that degraded to the wrapper still lands on a cmux run's
+    sidebar. A cli-wrapper lead is a no-op.
     """
-    # 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()
+    plan = _ensure_runtime_chain(plan)
+    lead = plan.runtime_chain[0]
     worker_id = str(
         details.get("executionLabel") or details.get("workerId") or "worker"
     )
-    cmux.sidebar_log(
-        workspace,
-        f"{worker_id}: {event_type.removeprefix('worker-')}",
-        level=_SIDEBAR_LEVELS.get(event_type, "info"),
-    )
+    notify_title = None
+    notify_body = None
     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')}",
+        notify_title = f"okstra — {_require_string(plan.manifest, 'taskType')}"
+        notify_body = f"{worker_id} failed: {details.get('reason', 'no reason recorded')}"
+    lead.notify(
+        ProgressEvent(
+            message=f"{worker_id}: {event_type.removeprefix('worker-')}",
+            level=_SIDEBAR_LEVELS.get(event_type, "info"),
+            notify_title=notify_title,
+            notify_body=notify_body,
         )
+    )
 
 
 def _append_event(plan: DispatchPlan, event_type: str, details: Mapping[str, Any]) -> None:

package/runtime/python/okstra_ctl/domain/host.py

@@ -20,6 +20,8 @@ class CurrentSessionModelAttestation:
         "cli-handoff",
         "unavailable",
     ]
+    # 호스트가 알려 줄 때만 채운다. 스크레이핑하지 않는다.
+    effort: str | None = None
 
     @classmethod
     def unknown(
@@ -27,7 +29,7 @@ class CurrentSessionModelAttestation:
         provider_id: str,
         source: Literal["unavailable"] = "unavailable",
     ) -> CurrentSessionModelAttestation:
-        return cls(provider_id, None, None, "unknown", source)
+        return cls(provider_id, None, None, "unknown", source, None)
 
 
 def _unavailable_current_model() -> CurrentSessionModelAttestation:

package/runtime/python/okstra_ctl/domain/wizard/interaction.py

@@ -71,7 +71,12 @@ def _normalize_numbered_item(prompt: WizardPrompt, answer: str) -> str:
         number = int(candidate)
         if 1 <= number <= len(prompt.options):
             return prompt.options[number - 1].value
+        # 옵션 값 자체가 숫자인 role-count 는 목록 밖 번호를 값으로도 허용한다
+        # (예: 옵션 [3,4,5] 에서 "4" → 수량 4). 목록에 없으면 범위 오류.
         if prompt.step.startswith("role-count:"):
+            exact_count = _exact_value_match(prompt, candidate)
+            if exact_count is not None:
+                return exact_count
             role = prompt.step.split(":", 1)[1]
             minimum = prompt.options[0].value if prompt.options else "?"
             maximum = prompt.options[-1].value if prompt.options else "?"

package/runtime/python/okstra_ctl/domain/worker_runtime.py

@@ -0,0 +1,44 @@
+"""Execution-surface value objects.
+
+The surface is where a worker process starts and where its output lands.
+It is not a host, a provider, or a role.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+SURFACE_CMUX_PANE = "cmux-pane"
+SURFACE_CLI_WRAPPER = "cli-wrapper"
+
+
+class SurfaceUnavailable(Exception):
+    """The surface could not be opened. The application may try the next one."""
+
+
+class EnvironmentBlocked(Exception):
+    """A sandbox hid the surface and the worker CLI config. Do not degrade."""
+
+
+@dataclass(frozen=True)
+class WorkerSpawnRequest:
+    command: tuple[str, ...]
+    cwd: Path
+    title: str
+    owned_surface_ids: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class RuntimeHandle:
+    surface: str
+    identifier: str
+    waitable: bool
+
+
+@dataclass(frozen=True)
+class ProgressEvent:
+    message: str
+    level: str = "info"
+    notify_title: str | None = None
+    notify_body: str | None = None

package/runtime/python/okstra_ctl/implementation_outcome.py

@@ -11,9 +11,10 @@ from .consumers import (
     carry_head_commit,
     read_stage_consumer_state,
 )
+from . import next_phase
 from .paths import RunRef, task_manifest_file
 from .stage_map import StageMapError, load_task_stage_map
-from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
+from .workflow import PHASE_SEQUENCE
 
 
 @dataclass(frozen=True)
@@ -22,7 +23,6 @@ class ImplementationOutcome:
     stages: list[int] = field(default_factory=list)
     head_commit: str = ""
     report_path: str = ""
-    next_recommended_phase: str = ""
     reason: str = ""
 
 
@@ -66,7 +66,6 @@ def derive_implementation_outcome(task_root: Path) -> ImplementationOutcome:
         stages=sorted(required_stages),
         head_commit=str(latest_done.get("head_commit") or "") or carry_head_commit(latest_carry),
         report_path=_latest_implementation_report(task_root),
-        next_recommended_phase=DEFAULT_NEXT_PHASE["implementation"],
         reason="all implementation stages have pass-grade carry and done rows",
     )
 
@@ -174,7 +173,22 @@ def _promote_workflow(workflow: dict[str, Any], outcome: ImplementationOutcome)
     workflow["currentPhaseState"] = "completed"
     phase_states["implementation"] = "completed"
     workflow["lastCompletedPhase"] = "implementation"
-    workflow["nextRecommendedPhase"] = outcome.next_recommended_phase
+    # 재조정기의 사실은 "모든 stage 가 끝났다"는 상태다. 대상 phase 는 마지막
+    # stage 검증이 이미 정했으므로 건드리지 않는다 (ADR-0004).
+    #
+    # 대상 phase 가 비어 있으면 status 도 올리지 않는다. `ready` 는 "지금 이
+    # phase 를 시작할 수 있다"는 뜻인데 가리킬 phase 가 없으면 시작할 대상이
+    # 없다. 마지막 stage 리포트에 라우팅 대상이 없으면 이 자리에 빈 phase 의
+    # pending 포인터가 들어오므로, 그때는 그대로 둔다.
+    pointer = next_phase.promote(workflow.get("nextRecommendedPhase"))
+    if pointer["phase"]:
+        workflow["nextRecommendedPhase"] = next_phase.make(
+            phase=pointer["phase"],
+            status=next_phase.STATUS_READY,
+            rationale=pointer["rationale"],
+        )
+    else:
+        workflow["nextRecommendedPhase"] = pointer
     after = json.dumps(workflow, sort_keys=True, ensure_ascii=False)
     return before != after
 
@@ -195,7 +209,9 @@ def _update_task_catalog(project_root: Path, manifest: dict[str, Any]) -> bool:
         entry["currentPhase"] = workflow.get("currentPhase", "")
         entry["currentPhaseState"] = workflow.get("currentPhaseState", "")
         entry["lastCompletedPhase"] = workflow.get("lastCompletedPhase", "")
-        entry["nextRecommendedPhase"] = workflow.get("nextRecommendedPhase", "")
+        entry["nextRecommendedPhase"] = next_phase.promote(
+            workflow.get("nextRecommendedPhase")
+        )
         entry["latestReportPath"] = manifest.get("latestReportPath", "")
         entry["latestRunStatus"] = manifest.get("latestRunStatus", entry.get("latestRunStatus", ""))
         entry["currentStatus"] = manifest.get("currentStatus", entry.get("currentStatus", ""))