okstra 0.163.2 → 0.165.0

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 import json
 import subprocess
 import time
-from dataclasses import dataclass
+from dataclasses import dataclass, field, replace
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
@@ -19,6 +19,7 @@ from .dispatch_state import (
     DispatchError,
     WorkerJob,
     dispatch_mode as _dispatch_mode,
+    dispatch_record_matches,
     LIVENESS_AUDIT_HEARTBEAT,
     LIVENESS_WRAPPER_STATUS,
     load_json_object as _load_json_object,
@@ -50,6 +51,12 @@ from .initial_prompt_materialization import (
     materialize_initial_prompts,
 )
 from .path_hints import hydrate_active_run_context
+from .report_finalize import (
+    STEP_VALIDATE_RUN,
+    FinalizeContext,
+    FinalizeError,
+    run_finalize,
+)
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
 from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
@@ -117,6 +124,8 @@ class _BuildOptions:
     supported_worker_wrappers: Mapping[str, str]
     unsupported_worker_label: str
     dispatch_kind: str
+    cli_wrapper_assignments_only: bool = False
+    default_provider_by_worker_id: Mapping[str, str] = field(default_factory=dict)
 
 
 @dataclass(frozen=True)
@@ -142,6 +151,8 @@ def build_dispatch_plan(
     unsupported_worker_label: str,
     dispatch_kind: str = "initial",
     jobs_file: Path | None = None,
+    cli_wrapper_assignments_only: bool = False,
+    default_provider_by_worker_id: Mapping[str, str] | None = None,
 ) -> DispatchPlan:
     project_root = project_root.resolve()
     manifest_path = _resolve_project_path(project_root, str(run_manifest_path))
@@ -157,6 +168,8 @@ def build_dispatch_plan(
         supported_worker_wrappers=supported_worker_wrappers,
         unsupported_worker_label=unsupported_worker_label,
         dispatch_kind=dispatch_kind,
+        cli_wrapper_assignments_only=cli_wrapper_assignments_only,
+        default_provider_by_worker_id=dict(default_provider_by_worker_id or {}),
     )
     if jobs_file:
         jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options)
@@ -247,7 +260,12 @@ def _jobs_from_roster(
     requested_workers: Sequence[str],
     options: _BuildOptions,
 ) -> list[WorkerJob]:
-    selected = _select_workers(manifest, requested_workers, options)
+    selected = _select_workers(
+        manifest,
+        requested_workers,
+        options,
+        team_state=team_state,
+    )
     _mark_roster_skips(project_root, manifest, team_state, selected, requested_workers, options)
     worker_facts, prompt_paths = _materialize_roster_prompts(
         project_root,
@@ -278,10 +296,19 @@ def _select_workers(
     manifest: Mapping[str, Any],
     requested_workers: Sequence[str],
     options: _BuildOptions,
+    *,
+    team_state: Mapping[str, Any] | None = None,
 ) -> list[str]:
     recommended = _string_list(manifest.get("recommendedWorkers"))
     if not recommended:
         raise DispatchError("run manifest has no recommendedWorkers entries")
+    if options.cli_wrapper_assignments_only:
+        return _select_cli_wrapper_assignments(
+            recommended,
+            requested_workers,
+            team_state or {},
+            options,
+        )
     supported = set(options.supported_worker_wrappers)
     selected = list(requested_workers) if requested_workers else [w for w in recommended if w in supported]
     unknown = [worker for worker in selected if worker not in recommended]
@@ -298,6 +325,69 @@ def _select_workers(
     return selected
 
 
+def _select_cli_wrapper_assignments(
+    recommended: Sequence[str],
+    requested_workers: Sequence[str],
+    team_state: Mapping[str, Any],
+    options: _BuildOptions,
+) -> list[str]:
+    dispatchable = {
+        worker_id
+        for worker_id in recommended
+        if _is_cli_wrapper_assignment(team_state, worker_id, options)
+    }
+    if not requested_workers:
+        selected = [worker for worker in recommended if worker in dispatchable]
+        if selected:
+            return selected
+        raise DispatchError("run roster has no cli-wrapper assignments for codex-dispatch")
+    selected = list(requested_workers)
+    unknown = [worker for worker in selected if worker not in recommended]
+    if unknown:
+        raise DispatchError(
+            "requested worker(s) are not in this run roster: " + ", ".join(unknown)
+        )
+    native = [
+        worker
+        for worker in selected
+        if _runner_for_worker(team_state, worker) == "native-session"
+    ]
+    if native:
+        raise DispatchError(
+            "requested worker(s) use runner=native-session and must be dispatched "
+            "by the current Codex host: " + ", ".join(native)
+        )
+    unsupported = [worker for worker in selected if worker not in dispatchable]
+    if unsupported:
+        supported = ", ".join(sorted(dispatchable))
+        raise DispatchError(
+            "unsupported Codex lead worker(s): "
+            + ", ".join(unsupported)
+            + f" (CLI dispatcher supports: {supported})"
+        )
+    return selected
+
+
+def _is_cli_wrapper_assignment(
+    team_state: Mapping[str, Any],
+    worker_id: str,
+    options: _BuildOptions,
+) -> bool:
+    state = _worker_state(team_state, worker_id)
+    provider = _string_value(state.get("provider")) or _provider_for_worker(
+        worker_id,
+        options,
+    )
+    return (
+        _string_value(state.get("runner")) or BACKEND_CLI_WRAPPER
+    ) == BACKEND_CLI_WRAPPER and provider in options.supported_worker_wrappers
+
+
+def _runner_for_worker(team_state: Mapping[str, Any], worker_id: str) -> str:
+    state = _worker_state(team_state, worker_id)
+    return _string_value(state.get("runner")) or BACKEND_CLI_WRAPPER
+
+
 def _job_from_roster_worker(
     project_root: Path,
     workspace_root: Path,
@@ -340,7 +430,7 @@ def _materialize_roster_prompts(
     options: _BuildOptions,
 ) -> tuple[tuple[_RosterWorkerFacts, ...], dict[str, Path]]:
     worker_facts = tuple(
-        _roster_worker_facts(team_state, worker_id)
+        _roster_worker_facts(team_state, worker_id, options)
         for worker_id in selected
     )
     try:
@@ -364,12 +454,14 @@ def _materialize_roster_prompts(
 def _roster_worker_facts(
     team_state: Mapping[str, Any],
     worker_id: str,
+    options: _BuildOptions | None = None,
 ) -> _RosterWorkerFacts:
     state = _worker_state(team_state, worker_id)
     return _RosterWorkerFacts(
         worker_id=worker_id,
         model=_require_string(state, "modelExecutionValue"),
-        provider=_string_value(state.get("provider")) or _provider_for_worker(worker_id),
+        provider=_string_value(state.get("provider"))
+        or _provider_for_worker(worker_id, options),
         result_path=_require_string(state, "resultPath"),
         role=_string_value(state.get("role")) or "worker",
     )
@@ -398,7 +490,7 @@ def _jobs_from_file(
         resolve_wrapper=lambda provider: _resolve_wrapper(
             provider, workspace_root, options
         ),
-        default_provider=_provider_for_worker,
+        default_provider=lambda worker_id: _provider_for_worker(worker_id, options),
     )
 
 
@@ -422,7 +514,7 @@ def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
         if handle.completed_process is None:
             return await_dispatches(plan, timeout_seconds=None)
         outcome = _outcome_from_completed(handle)
-        if outcome.returncode == 0 and not outcome.missing_completion_paths:
+        if _worker_terminal_status(plan.team_state_path, job.worker_id) == "completed":
             return 0
         if _should_retry(outcome, attempt):
             _append_event(plan, "worker-retry-scheduled", _retry_details(job, attempt, outcome))
@@ -528,6 +620,10 @@ def _refuse_when_cmux_is_walled_off() -> None:
 
 
 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)
 
@@ -565,24 +661,47 @@ def _retry_from_record(
 ) -> None:
     worker_id = _require_string(record, "workerId")
     attempt = int(record.get("attempt", 1))
-    _update_dispatch_status(plan.team_state_path, worker_id, _require_string(record, "kind"), attempt, "error", "required worker artifact was not produced")
-    _append_event(plan, "worker-retry-scheduled", {"workerId": worker_id, "attempt": attempt})
     job = _job_from_record(plan.project_root, record)
+    _update_dispatch_status(plan.team_state_path, job, attempt, "error", "required worker artifact was not produced")
+    _append_event(plan, "worker-retry-scheduled", {"workerId": worker_id, "attempt": attempt})
     _spawn_job(plan, job, attempt + 1)
 
 
 def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> None:
     if outcome.returncode == 0 and not outcome.missing_completion_paths and not outcome.timeout:
+        post_process = _post_process_report_writer_result(plan, job)
+        if not post_process["ok"]:
+            reason = _require_string(post_process, "reason")
+            _transition_worker_status(plan.team_state_path, job.worker_id, "error", reason)
+            _update_dispatch_status(
+                plan.team_state_path,
+                job,
+                attempt,
+                "error",
+                reason,
+            )
+            details = _failure_details(
+                job,
+                attempt,
+                outcome,
+                reason,
+                exit_code=1,
+            )
+            details["postProcessing"] = post_process["steps"]
+            _append_event(plan, "worker-failed", details)
+            return
         _transition_worker_status(
             plan.team_state_path, job.worker_id, "completed", ""
         )
-        _update_dispatch_status(plan.team_state_path, job.worker_id, job.dispatch_kind, attempt, "completed", "")
-        _append_event(plan, "worker-result-collected", _result_details(job, attempt, outcome))
+        _update_dispatch_status(plan.team_state_path, job, attempt, "completed", "")
+        details = _result_details(job, attempt, outcome)
+        details["postProcessing"] = post_process["steps"]
+        _append_event(plan, "worker-result-collected", details)
         return
     reason = _failure_reason(outcome)
     status = "timeout" if outcome.timeout else "error"
     _transition_worker_status(plan.team_state_path, job.worker_id, status, reason)
-    _update_dispatch_status(plan.team_state_path, job.worker_id, job.dispatch_kind, attempt, status, reason)
+    _update_dispatch_status(plan.team_state_path, job, attempt, status, reason)
     _append_event(plan, "worker-failed", _failure_details(job, attempt, outcome, reason))
 
 
@@ -591,6 +710,41 @@ def _finish_record(plan: DispatchPlan, record: Mapping[str, Any], outcome: Worke
     _finish_attempt(plan, job, int(record.get("attempt", 1)), outcome)
 
 
+def _post_process_report_writer_result(
+    plan: DispatchPlan,
+    job: WorkerJob,
+) -> dict[str, Any]:
+    if job.worker_id != REPORT_WRITER_WORKER_ID:
+        return {"ok": True, "reason": "", "steps": []}
+    try:
+        context = FinalizeContext.from_manifest(
+            project_root=plan.project_root,
+            workspace_root=plan.workspace_root,
+            manifest_path=plan.manifest_path,
+            team_state_path=plan.team_state_path,
+            data_path=job.result_path,
+            manifest=plan.manifest,
+        )
+
+        def settle_before(step_name: str) -> None:
+            if step_name == STEP_VALIDATE_RUN:
+                _transition_worker_status(
+                    plan.team_state_path,
+                    job.worker_id,
+                    "completed",
+                    "",
+                )
+
+        return run_finalize(context, before_step=settle_before)
+    except FinalizeError as exc:
+        return {"ok": False, "reason": str(exc), "steps": []}
+
+
+def _worker_terminal_status(team_state_path: Path, worker_id: str) -> str:
+    team_state = _load_json_object(team_state_path, "team-state")
+    return _string_value(_worker_state(team_state, worker_id).get("status"))
+
+
 def _record_dispatch(
     team_state_path: Path, handle: WorkerHandle, attempt: int, status: str, reason: str
 ) -> None:
@@ -638,19 +792,23 @@ def _liveness_mode(backend: str) -> str:
 
 
 def _update_dispatch_status(
-    team_state_path: Path, worker_id: str, kind: str, attempt: int, status: str, reason: str
+    team_state_path: Path, job: WorkerJob, attempt: int, status: str, reason: str
 ) -> None:
     payload = _load_json_object(team_state_path, "team-state")
-    for record in payload.get("workerDispatches", []):
-        if _record_matches(record, worker_id, kind, attempt):
-            record["status"] = status
-            record["reason"] = reason
-            _write_json(team_state_path, payload)
-            return
-
-
-def _record_matches(record: object, worker_id: str, kind: str, attempt: int) -> bool:
-    return isinstance(record, dict) and record.get("workerId") == worker_id and record.get("kind") == kind and record.get("attempt") == attempt
+    matches = [
+        record
+        for record in payload.get("workerDispatches", [])
+        if dispatch_record_matches(record, job.prompt_path, attempt)
+    ]
+    if not matches:
+        return
+    # A lead may re-send a round's prompt without advancing `attempt`, which
+    # appends a second row the prompt cannot tell from the first. The newest is
+    # the one still running, so an outcome written to the older row would leave
+    # the live one running for good — the shape that wedged an await loop.
+    matches[-1]["status"] = status
+    matches[-1]["reason"] = reason
+    _write_json(team_state_path, payload)
 
 
 def _running_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
@@ -669,21 +827,58 @@ def _mark_roster_skips(
     requested: Sequence[str],
     options: _BuildOptions,
 ) -> None:
-    reasons = _skip_reasons(manifest, selected, requested, options)
+    reasons = _skip_reasons(
+        manifest,
+        selected,
+        requested,
+        options,
+        team_state=team_state,
+    )
     if not reasons:
         return
     team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
+    current_team_state = _load_json_object(team_state_path, "team-state")
     for worker_id, reason in reasons.items():
+        worker = _worker_state(current_team_state, worker_id)
+        if (
+            _string_value(worker.get("status")) != "not-run"
+            or _string_value(worker.get("reason"))
+        ):
+            continue
         _transition_worker_status(team_state_path, worker_id, "not-run", reason)
 
 
 def _skip_reasons(
-    manifest: Mapping[str, Any], selected: Sequence[str], requested: Sequence[str], options: _BuildOptions
+    manifest: Mapping[str, Any],
+    selected: Sequence[str],
+    requested: Sequence[str],
+    options: _BuildOptions,
+    *,
+    team_state: Mapping[str, Any] | None = None,
 ) -> dict[str, str]:
+    recommended = _string_list(manifest.get("recommendedWorkers"))
+    if options.cli_wrapper_assignments_only:
+        recommended = [
+            worker_id
+            for worker_id in recommended
+            if _runner_for_worker(team_state or {}, worker_id) != "native-session"
+        ]
     if requested:
-        return {w: "skipped by worker dispatch: worker was not requested in this invocation" for w in _string_list(manifest.get("recommendedWorkers")) if w not in set(selected)}
+        return {
+            worker_id: (
+                "skipped by worker dispatch: worker was not requested in this invocation"
+            )
+            for worker_id in recommended
+            if worker_id not in set(selected)
+        }
     supported = set(options.supported_worker_wrappers)
-    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}
+    return {
+        worker_id: (
+            "skipped by worker dispatch default: worker is not supported by this dispatcher"
+        )
+        for worker_id in recommended
+        if worker_id not in set(selected) and worker_id not in supported
+    }
 
 
 _SIDEBAR_LEVELS = {
@@ -765,14 +960,27 @@ def _result_details(job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> dic
     }
 
 
-def _failure_details(job: WorkerJob, attempt: int, outcome: WorkerOutcome, reason: str) -> dict[str, Any]:
+def _failure_details(
+    job: WorkerJob,
+    attempt: int,
+    outcome: WorkerOutcome,
+    reason: str,
+    *,
+    exit_code: int | None = None,
+) -> dict[str, Any]:
     return {
         "workerId": job.worker_id,
         "attempt": attempt,
+        "maxAttempts": MAX_WORKER_ATTEMPTS,
         "dispatchMode": BACKEND_CLI_WRAPPER if outcome.degraded_from else job.backend,
-        "exitCode": outcome.returncode,
+        "exitCode": outcome.returncode if exit_code is None else exit_code,
         "missingCompletionPaths": [str(path) for path in outcome.missing_completion_paths],
         "reason": reason,
+        "promptPath": str(job.prompt_path),
+        "resultPath": str(job.result_path),
+        "workerResultPath": str(job.worker_result_path),
+        "wrapperPath": str(job.wrapper_path),
+        "role": job.role,
     }
 
 
@@ -863,7 +1071,14 @@ def _resolve_wrapper(provider: str, workspace_root: Path, options: _BuildOptions
     raise DispatchError(f"{script} not found (searched: {', '.join(str(c) for c in candidates)})")
 
 
-def _provider_for_worker(worker_id: str) -> str:
+def _provider_for_worker(
+    worker_id: str,
+    options: _BuildOptions | None = None,
+) -> str:
+    if options is not None:
+        configured = options.default_provider_by_worker_id.get(worker_id)
+        if configured:
+            return configured
     if worker_id == REPORT_WRITER_WORKER_ID:
         return "claude"
     return worker_id

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -30,6 +30,7 @@ from .worker_prompt_contract import (
     validate_initial_prompt_records,
     validate_reverify_prompt,
 )
+from .worker_runner import LIVE, QUIET
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
@@ -91,6 +92,7 @@ class WorkerJob:
 
     @property
     def command(self) -> list[str]:
+        # The flag trails the positional contract the entrypoint reads by index.
         return [
             str(self.wrapper_path),
             str(self.project_root),
@@ -99,8 +101,16 @@ class WorkerJob:
             self.worktree_path,
             self.role,
             str(self.idle_timeout_seconds),
+            "--presentation",
+            self._presentation(),
         ]
 
+    def _presentation(self) -> str:
+        # A pane is a screen a person watches; a cli-wrapper dispatch's stdout is
+        # a subagent's context window. Progress belongs in the first and not the
+        # second.
+        return QUIET if self.backend == BACKEND_CLI_WRAPPER else LIVE
+
     def to_payload(self) -> dict[str, Any]:
         return {
             "workerId": self.worker_id,
@@ -430,3 +440,20 @@ def _worker_job_from_file(
 
 def utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def dispatch_record_matches(record: object, prompt_path: Path, attempt: int) -> bool:
+    """Whether this team-state row is the dispatch handed `prompt_path`.
+
+    The prompt file identifies a dispatch: each round writes its own, and a
+    second run of the same one is a retry, which `attempt` separates. Worker id
+    and dispatch kind cannot carry that — `--dispatch-kind` is the lead's to
+    pick and it has reused one across two rounds, which put the finished
+    round's completion on the older namesake row and left the row that actually
+    ran marked running, so an await re-collected that worker forever.
+    """
+    return (
+        isinstance(record, dict)
+        and record.get("promptPath") == str(prompt_path)
+        and record.get("attempt") == attempt
+    )

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

@@ -0,0 +1,34 @@
+"""Domain value objects for provider selection and model resolution."""
+
+import importlib
+import sys
+
+
+_provider_module_name = f"{__name__}.provider"
+if __name__.startswith("scripts."):
+    _alternate_provider_module_name = f"{__name__.removeprefix('scripts.')}.provider"
+else:
+    _alternate_provider_module_name = f"scripts.{__name__}.provider"
+
+# Repository tests support both import paths. Sharing one module preserves the
+# exact class identity that the adapter factory contract validates.
+if _alternate_provider_module_name in sys.modules:
+    sys.modules[_provider_module_name] = sys.modules[_alternate_provider_module_name]
+
+_provider = importlib.import_module(_provider_module_name)
+
+LeadLaunchSpec = _provider.LeadLaunchSpec
+ModelAssignment = _provider.ModelAssignment
+ModelSpec = _provider.ModelSpec
+ProviderSpec = _provider.ProviderSpec
+UnknownModelError = _provider.UnknownModelError
+UnknownProviderError = _provider.UnknownProviderError
+
+__all__ = (
+    "LeadLaunchSpec",
+    "ModelAssignment",
+    "ModelSpec",
+    "ProviderSpec",
+    "UnknownModelError",
+    "UnknownProviderError",
+)

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

@@ -0,0 +1,100 @@
+"""Host selection and session value objects."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, Mapping
+
+
+@dataclass(frozen=True)
+class HostDescriptor:
+    id: str
+    aliases: tuple[str, ...]
+    native_provider_id: str
+    required_executables: tuple[str, ...]
+    launch_mode: Literal["lead", "team"]
+    install_targets: frozenset[str]
+    agent_id: str
+    agent_label: str
+    role: str
+    dispatch_mode: str
+    session_accounting: str
+    has_claude_session: bool
+    relay_contract: str
+
+
+@dataclass(frozen=True)
+class HostSessionContext:
+    host_id: str
+    entry_mode: Literal["spawn-process", "current-session"]
+    available_functions: frozenset[str]
+    interaction_surface: str
+
+
+@dataclass(frozen=True)
+class HostResolutionContext:
+    explicit_env_host: str
+    signals: frozenset[str]
+
+
+@dataclass(frozen=True)
+class HostClaim:
+    host_id: str
+    priority: int
+    reason: str
+
+
+@dataclass(frozen=True)
+class HostReadiness:
+    ok: bool
+    effective_functions: frozenset[str]
+    missing_executables: tuple[str, ...]
+    checks: tuple[Mapping[str, object], ...]
+    reason: str
+
+
+@dataclass(frozen=True)
+class LeadStartRequest:
+    project_root: Path
+    task_type: str
+    argv: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class LeadResumeRequest:
+    project_root: Path
+    task_type: str
+    session_id: str
+    argv: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class LeadSessionPlan:
+    mode: Literal["spawn-process", "current-session"]
+    argv: tuple[str, ...]
+    env: Mapping[str, str]
+    sandbox_note: str
+
+
+class HostNotRegistered(ValueError):
+    """Raised when no registered host matches an explicit request."""
+
+
+class HostUnavailable(RuntimeError):
+    """Raised when no single host can serve an automatic request."""
+
+
+class HostCapabilityMismatch(ValueError):
+    """Raised when a selected host lacks a required semantic capability."""
+
+
+class HostAdapterContractError(ValueError):
+    """Raised when a host manifest or factory violates the adapter contract."""
+
+
+class ProviderNotRegistered(ValueError):
+    """Raised when a host references an unknown native provider."""
+
+
+class ProviderUnavailable(RuntimeError):
+    """Raised when a registered provider cannot serve a request."""