okstra 0.163.2 → 0.164.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -1,477 +1,81 @@
 """CLI-wrapper dispatcher for a Codex-hosted Okstra lead.
 
 The prepared assignment's ``runner`` field is authoritative. Native Codex
-assignments stay in the host session; this module runs only ``cli-wrapper``
-assignments through their registered provider wrappers.
+assignments stay in the host session; this entrypoint executes only the backend
+plan returned by the worker-dispatch application use case.
 """
 from __future__ import annotations
 
 import argparse
 import json
-import subprocess
 import sys
-from dataclasses import dataclass
-from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Mapping, Sequence
 
-from .final_report_paths import (
-    final_report_data_path as _final_report_data_path,
-    final_report_markdown_path as _final_report_markdown_path,
-)
-from .initial_prompt_materialization import (
-    InitialPromptMaterializationError,
-    InitialPromptMaterializationRequest,
-    InitialPromptWorkerRequest,
-    PromptDeliveryMode,
-    materialize_initial_prompts,
-)
-from .lead_events import LeadEvent, append_lead_event
-from .dispatch_state import (
-    BACKEND_CLI_WRAPPER,
-    BACKEND_MIXED,
-    BACKEND_TMUX_PANE,
-    DispatchError,
-    WorkerJob,
-    dispatch_mode as _dispatch_mode,
-    load_json_object as _load_json_object,
-    missing_completion_paths as _missing_completion_paths,
-    LIVENESS_WRAPPER_STATUS,
-    require_string as _require_string,
-    resolve_project_path as _resolve_project_path,
-    resolve_required_path as _resolve_required_path,
-    set_dispatch_mode as _set_dispatch_mode,
-    string_list as _string_list,
-    string_value as _string_value,
-    transition_worker_status as _transition_worker_status,
-    utc_now as _utc_now,
-    validate_dispatch_prompts as _validate_dispatch_prompts,
-    worker_jobs_from_file as _worker_jobs_from_file,
-    worker_state as _worker_state,
-    worktree_path as _worktree_path,
-    write_json as _write_json,
-)
-from .path_hints import hydrate_active_run_context
-from .report_finalize import (
-    STEP_VALIDATE_RUN,
-    FinalizeContext,
-    FinalizeError,
-    resolve_optional_path as _resolve_optional_path,
-    run_finalize,
-    run_seq as _run_seq,
-)
-from .wrapper_status import status_path_for_prompt
-from .worker_prompt_body import REPORT_WRITER_WORKER_ID
+from . import dispatch_core
+from .adapters.dispatch import with_worker_dispatch
+from .adapters.dispatch.cli_wrapper import CliWrapperDispatchPort
+from .application.dispatch_assignments import dispatch_assignments
+from .dispatch_state import DispatchError
 from .models import provider_wrappers
+from .ports.worker_dispatch import WorkerDispatchRequest
+from .registry.host_registry import default_host_registry
 
 
 SUPPORTED_CLI_WORKERS = provider_wrappers("analyser")
-MAX_WORKER_ATTEMPTS = 2
-
-
-@dataclass(frozen=True)
-class DispatchPlan:
-    project_root: Path
-    workspace_root: Path
-    manifest_path: Path
-    team_state_path: Path
-    lead_events_path: Path
-    manifest: Mapping[str, Any]
-    workers: tuple[WorkerJob, ...]
-
-    def to_payload(self, *, dry_run: bool) -> dict[str, Any]:
-        return {
-            "ok": True,
-            "dryRun": dry_run,
-            "dispatchMode": _dispatch_mode(self.workers),
-            "workerBackends": {
-                worker.worker_id: worker.backend
-                for worker in self.workers
-            },
-            "runManifestPath": str(self.manifest_path),
-            "teamStatePath": str(self.team_state_path),
-            "leadEventsPath": str(self.lead_events_path),
-            "workspaceRoot": str(self.workspace_root),
-            "workers": [worker.to_payload() for worker in self.workers],
-        }
-
-
-@dataclass(frozen=True)
-class _DispatchInputs:
-    project_root: Path
-    manifest_path: Path
-    manifest: Mapping[str, Any]
-    selected_workers: tuple[str, ...]
-    team_state_path: Path
-    team_state: Mapping[str, Any]
-    active_context: Mapping[str, Any]
-    lead_events_path: Path
-
-
-def build_dispatch_plan(
-    *,
-    project_root: Path,
-    run_manifest_path: Path,
-    workspace_root: Path,
-    okstra_bin: Path | None = None,
-    requested_workers: Sequence[str] = (),
-    idle_timeout_seconds: int = 600,
-    dispatch_kind: str = "initial",
-    jobs_file: Path | None = None,
-) -> DispatchPlan:
-    inputs = _load_dispatch_inputs(
-        project_root,
-        run_manifest_path,
-        requested_workers,
-        select_roster=jobs_file is None,
-    )
-    if jobs_file is not None:
-        workers = _codex_jobs_from_file(
-            inputs,
-            jobs_file,
-            workspace_root=workspace_root,
-            okstra_bin=okstra_bin,
-            idle_timeout_seconds=idle_timeout_seconds,
-            dispatch_kind=dispatch_kind,
-        )
-    else:
-        worker_requests, prompt_paths = _materialize_selected_worker_prompts(
-            project_root=inputs.project_root,
-            manifest_path=inputs.manifest_path,
-            workspace_root=workspace_root,
-            team_state=inputs.team_state,
-            selected_workers=inputs.selected_workers,
-        )
-        workers = _build_selected_worker_dispatches(
-            project_root=inputs.project_root,
-            manifest=inputs.manifest,
-            team_state=inputs.team_state,
-            active_context=inputs.active_context,
-            workspace_root=workspace_root,
-            okstra_bin=okstra_bin,
-            idle_timeout_seconds=idle_timeout_seconds,
-            selected_workers=inputs.selected_workers,
-            worker_requests=worker_requests,
-            prompt_paths=prompt_paths,
-        )
-    return DispatchPlan(
-        project_root=inputs.project_root,
-        workspace_root=workspace_root,
-        manifest_path=inputs.manifest_path,
-        team_state_path=inputs.team_state_path,
-        lead_events_path=inputs.lead_events_path,
-        manifest=inputs.manifest,
-        workers=workers,
-    )
-
-
-def _codex_jobs_from_file(
-    inputs: _DispatchInputs,
-    jobs_file: Path,
-    *,
-    workspace_root: Path,
-    okstra_bin: Path | None,
-    idle_timeout_seconds: int,
-    dispatch_kind: str,
-) -> list[WorkerJob]:
-    workers = _worker_jobs_from_file(
-        inputs.project_root,
-        jobs_file,
-        backend=BACKEND_CLI_WRAPPER,
-        idle_timeout_seconds=idle_timeout_seconds,
-        default_dispatch_kind=dispatch_kind,
-        resolve_wrapper=lambda provider: _resolve_wrapper(
-            provider, workspace_root, okstra_bin
-        ),
-        default_provider=lambda worker_id: (
-            "codex" if worker_id == REPORT_WRITER_WORKER_ID else worker_id
-        ),
-    )
-    _validate_dispatch_prompts(inputs.manifest, inputs.active_context, workers)
-    return workers
-
-
-def _load_dispatch_inputs(
-    project_root: Path,
-    run_manifest_path: Path,
-    requested_workers: Sequence[str],
-    *,
-    select_roster: bool = True,
-) -> _DispatchInputs:
-    project_root = project_root.resolve()
-    manifest_path = _resolve_project_path(project_root, str(run_manifest_path))
-    manifest = _load_json_object(manifest_path, "run manifest")
-    _validate_codex_manifest(manifest, manifest_path)
-    team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
-    team_state = _load_json_object(team_state_path, "team-state")
-    selected_workers = (
-        tuple(
-            _select_workers(
-                manifest,
-                team_state,
-                requested_workers,
-            )
-        )
-        if select_roster
-        else ()
-    )
-    if select_roster:
-        _mark_skipped_workers(
-            team_state_path,
-            team_state,
-            _skipped_worker_reasons(
-                manifest,
-                team_state,
-                selected_workers,
-                requested_workers,
-            ),
-        )
-    active_context = _load_optional_json_object(
-        _resolve_optional_path(project_root, manifest.get("activeRunContextPath"))
-    )
-    return _DispatchInputs(
-        project_root=project_root,
-        manifest_path=manifest_path,
-        manifest=manifest,
-        selected_workers=selected_workers,
-        team_state_path=team_state_path,
-        team_state=team_state,
-        active_context=active_context,
-        lead_events_path=_resolve_required_path(project_root, manifest, "leadEventsPath"),
-    )
-
-
-def _materialize_selected_worker_prompts(
-    *,
-    project_root: Path,
-    manifest_path: Path,
-    workspace_root: Path,
-    team_state: Mapping[str, Any],
-    selected_workers: Sequence[str],
-) -> tuple[tuple[InitialPromptWorkerRequest, ...], tuple[Path, ...]]:
-    worker_requests = tuple(
-        InitialPromptWorkerRequest(
-            worker_id=worker_id,
-            model=_requested_worker_model(worker_id, team_state),
-        )
-        for worker_id in selected_workers
-    )
-    try:
-        prompt_paths = materialize_initial_prompts(
-            InitialPromptMaterializationRequest(
-                project_root=project_root,
-                run_manifest_path=manifest_path,
-                runtime_root=workspace_root,
-                delivery_mode=PromptDeliveryMode.EAGER_INCLUDE,
-                workers=worker_requests,
-            )
-        )
-    except InitialPromptMaterializationError as exc:
-        raise DispatchError(f"{exc.reason}: {exc}") from exc
-    return worker_requests, prompt_paths
-
-
-def _build_selected_worker_dispatches(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    workspace_root: Path,
-    okstra_bin: Path | None,
-    idle_timeout_seconds: int,
-    selected_workers: Sequence[str],
-    worker_requests: Sequence[InitialPromptWorkerRequest],
-    prompt_paths: Mapping[str, Path],
-) -> tuple[WorkerJob, ...]:
-    return tuple(
-        _build_worker_dispatch(
-            worker_id=worker_id,
-            project_root=project_root,
-            manifest=manifest,
-            team_state=team_state,
-            active_context=active_context,
-            workspace_root=workspace_root,
-            okstra_bin=okstra_bin,
-            idle_timeout_seconds=idle_timeout_seconds,
-            model_execution_value=worker_request.model,
-            prompt_path=prompt_path,
-        )
-        for worker_id, worker_request, prompt_path in (
-            (worker_id, worker_request, prompt_paths[worker_id])
-            for worker_id, worker_request in zip(
-                selected_workers, worker_requests, strict=True
-            )
-        )
-    )
-
-
-def dispatch_plan(plan: DispatchPlan) -> int:
-    _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.workers))
-    for worker in plan.workers:
-        completed = _dispatch_worker_with_retry(plan, worker)
-        if completed == 0:
-            continue
-        return completed
-    return 0
-
-
-def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
-    for attempt in range(1, MAX_WORKER_ATTEMPTS + 1):
-        _transition_worker_status(
-            plan.team_state_path,
-            worker.worker_id,
-            "in-progress",
-            "",
-            model_execution_value=worker.model_execution_value,
-        )
-        _record_worker_attempt(plan, worker, attempt, "running")
-        attempt_details = _attempt_event_details(worker, attempt)
-        _append_event(plan, "worker-dispatched", attempt_details)
-        result = _run_worker(plan, worker)
-        missing_paths = _missing_completion_paths(worker)
-        if result.returncode == 0 and not missing_paths:
-            post_process = _post_process_report_writer_result(plan, worker)
-            if not post_process["ok"]:
-                reason = _require_string(post_process, "reason")
-                _transition_worker_status(
-                    plan.team_state_path, worker.worker_id, "error", reason
-                )
-                _record_worker_attempt(plan, worker, attempt, "error", reason)
-                details = {
-                    **attempt_details,
-                    "exitCode": 1,
-                    "missingCompletionPaths": [],
-                    "reason": reason,
-                    "postProcessing": post_process["steps"],
-                }
-                _append_event(plan, "worker-failed", details)
-                return 1
-            _transition_worker_status(
-                plan.team_state_path, worker.worker_id, "completed", ""
-            )
-            _record_worker_attempt(plan, worker, attempt, "completed")
-            details = {
-                **attempt_details,
-                "missingCompletionPaths": [],
-                "postProcessing": post_process["steps"],
-            }
-            _append_event(plan, "worker-result-collected", details)
-            return 0
-        if _should_retry_missing_result(result, missing_paths, attempt):
-            retry_details = {
-                **attempt_details,
-                "missingCompletionPaths": [str(path) for path in missing_paths],
-                "reason": "required worker artifact was not produced",
-            }
-            _record_worker_attempt(
-                plan,
-                worker,
-                attempt,
-                "error",
-                "required worker artifact was not produced",
-            )
-            _append_event(plan, "worker-retry-scheduled", retry_details)
-            continue
-
-        reason = _failure_reason(result.returncode, missing_paths)
-        _transition_worker_status(
-            plan.team_state_path, worker.worker_id, "error", reason
-        )
-        _record_worker_attempt(plan, worker, attempt, "error", reason)
-        details = {
-            **attempt_details,
-            "exitCode": result.returncode,
-            "missingCompletionPaths": [str(path) for path in missing_paths],
-            "reason": reason,
-        }
-        _append_event(plan, "worker-failed", details)
-        return result.returncode if result.returncode else 1
-    return 1
-def _record_worker_attempt(
-    plan: DispatchPlan,
-    worker: WorkerJob,
-    attempt: int,
-    status: str,
-    reason: str = "",
-) -> None:
-    payload = _load_json_object(plan.team_state_path, "team-state")
-    dispatches = payload.setdefault("workerDispatches", [])
-    if not isinstance(dispatches, list):
-        raise DispatchError(
-            f"team-state workerDispatches must be an array: {plan.team_state_path}"
-        )
-    for record in dispatches:
-        if _matches_worker_attempt(record, worker, attempt):
-            record["status"] = status
-            record["reason"] = reason
-            _write_json(plan.team_state_path, payload)
-            return
-    dispatches.append(_worker_dispatch_record(worker, attempt, status, reason))
-    _write_json(plan.team_state_path, payload)
-
-
-def _matches_worker_attempt(
-    record: object, worker: WorkerJob, attempt: int
-) -> bool:
-    return (
-        isinstance(record, dict)
-        and record.get("workerId") == worker.worker_id
-        and record.get("kind") == worker.dispatch_kind
-        and record.get("attempt") == attempt
-    )
-
-
-def _worker_dispatch_record(
-    worker: WorkerJob, attempt: int, status: str, reason: str
-) -> dict[str, Any]:
-    return {
-        "workerId": worker.worker_id,
-        "role": worker.role,
-        "kind": worker.dispatch_kind,
-        "attempt": attempt,
-        "backendType": worker.backend,
-        "provider": worker.provider,
-        "status": status,
-        "paneId": "",
-        "promptPath": str(worker.prompt_path),
-        "resultPath": str(worker.result_path),
-        "workerResultPath": str(worker.worker_result_path),
-        "livenessMode": LIVENESS_WRAPPER_STATUS,
-        "statusSidecarPath": str(status_path_for_prompt(worker.prompt_path)),
-        "degradedFrom": "",
-        "reason": reason,
-    }
 
 
 def main(argv: Sequence[str] | None = None) -> int:
-    parser = _parser()
-    args = parser.parse_args(argv)
+    args = _parser().parse_args(argv)
     try:
         if args.jobs_file and args.workers:
             raise DispatchError("--jobs-file and --workers cannot be combined")
-        idle_timeout_seconds = _parse_idle_timeout(args.idle_timeout_seconds)
-        plan = build_dispatch_plan(
-            project_root=Path(args.project_root),
-            run_manifest_path=Path(args.run_manifest),
-            workspace_root=Path(args.workspace_root),
-            okstra_bin=Path(args.okstra_bin) if args.okstra_bin else None,
-            requested_workers=_parse_workers(args.workers),
-            idle_timeout_seconds=idle_timeout_seconds,
-            dispatch_kind=args.dispatch_kind,
-            jobs_file=Path(args.jobs_file) if args.jobs_file else None,
-        )
+        request = _dispatch_request(args)
+        port = CliWrapperDispatchPort(
+            supported_worker_wrappers=SUPPORTED_CLI_WORKERS,
+            unsupported_worker_label="Codex lead",
+            required_lead_runtime="codex",
+            cli_wrapper_assignments_only=True,
+            default_provider_by_worker_id={"report-writer": "codex"},
+        )
+        host_adapter = with_worker_dispatch(
+            default_host_registry().resolve("codex"),
+            port,
+        )
+        plan = dispatch_assignments(request, host_adapter.worker_dispatch())
+        backend_plan = plan.backend_plan
+        if backend_plan is None:
+            raise DispatchError("CLI wrapper dispatch did not produce a backend plan")
         if args.dry_run:
-            _print_json(plan.to_payload(dry_run=True))
+            _print_json(_backend_payload(backend_plan, dry_run=True))
             return 0
-        code = dispatch_plan(plan)
-        _print_json({**plan.to_payload(dry_run=False), "exitCode": code})
+        code = dispatch_core.dispatch_plan(backend_plan)
+        _print_json({**_backend_payload(backend_plan, dry_run=False), "exitCode": code})
         return code
-    except (DispatchError, FinalizeError) as exc:
+    except DispatchError as exc:
         print(f"error: {exc}", file=sys.stderr)
         return 2
 
 
+def _dispatch_request(args: argparse.Namespace) -> WorkerDispatchRequest:
+    return WorkerDispatchRequest(
+        project_root=Path(args.project_root),
+        run_manifest=Path(args.run_manifest),
+        workspace_root=Path(args.workspace_root),
+        okstra_bin=Path(args.okstra_bin) if args.okstra_bin else None,
+        requested_workers=tuple(_parse_workers(args.workers)),
+        idle_timeout_seconds=_parse_idle_timeout(args.idle_timeout_seconds),
+        dispatch_kind=args.dispatch_kind,
+        jobs_file=Path(args.jobs_file) if args.jobs_file else None,
+    )
+
+
+def _backend_payload(backend_plan, *, dry_run: bool) -> dict[str, Any]:
+    payload = backend_plan.to_payload(dry_run=dry_run)
+    payload.pop("workerDispatches", None)
+    return payload
+
+
 def _parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="okstra codex-dispatch",
@@ -489,387 +93,6 @@ def _parser() -> argparse.ArgumentParser:
     return parser
 
 
-def _build_worker_dispatch(
-    *,
-    worker_id: str,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    active_context: Mapping[str, Any],
-    workspace_root: Path,
-    okstra_bin: Path | None,
-    idle_timeout_seconds: int,
-    model_execution_value: str,
-    prompt_path: Path,
-) -> WorkerJob:
-    worker_state = _worker_state(team_state, worker_id)
-    provider = _assigned_provider(worker_state, worker_id)
-    if worker_id == REPORT_WRITER_WORKER_ID:
-        return _build_report_writer_dispatch(
-            project_root=project_root,
-            manifest=manifest,
-            team_state=team_state,
-            workspace_root=workspace_root,
-            okstra_bin=okstra_bin,
-            idle_timeout_seconds=idle_timeout_seconds,
-            model_execution_value=model_execution_value,
-            prompt_path=prompt_path,
-            provider=provider,
-        )
-    result_path = _resolve_project_path(
-        project_root, _require_string(worker_state, "resultPath")
-    )
-    wrapper = _resolve_wrapper(provider, workspace_root, okstra_bin)
-    worktree_path = _worktree_path(manifest, active_context)
-    role = _pane_role(prompt_path)
-    return WorkerJob(
-        worker_id=worker_id,
-        provider=provider,
-        backend=BACKEND_CLI_WRAPPER,
-        project_root=project_root,
-        model_execution_value=model_execution_value,
-        wrapper_path=wrapper,
-        prompt_path=prompt_path,
-        result_path=result_path,
-        worker_result_path=result_path,
-        completion_paths=(result_path,),
-        worktree_path=worktree_path,
-        role=role,
-        idle_timeout_seconds=idle_timeout_seconds,
-        dispatch_kind="initial",
-    )
-
-
-def _build_report_writer_dispatch(
-    *,
-    project_root: Path,
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    workspace_root: Path,
-    okstra_bin: Path | None,
-    idle_timeout_seconds: int,
-    model_execution_value: str,
-    prompt_path: Path,
-    provider: str,
-) -> WorkerJob:
-    worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
-    data_json_path = _final_report_data_path(
-        _resolve_required_path(project_root, manifest, "expectedReportPath")
-    )
-    markdown_path = _final_report_markdown_path(data_json_path)
-    worker_result_path = _resolve_project_path(
-        project_root, _require_string(worker_state, "resultPath")
-    )
-    return WorkerJob(
-        worker_id=REPORT_WRITER_WORKER_ID,
-        provider=provider,
-        backend=BACKEND_CLI_WRAPPER,
-        project_root=project_root,
-        model_execution_value=model_execution_value,
-        wrapper_path=_resolve_wrapper(provider, workspace_root, okstra_bin),
-        prompt_path=prompt_path,
-        result_path=data_json_path,
-        worker_result_path=worker_result_path,
-        completion_paths=(
-            data_json_path,
-            markdown_path,
-            worker_result_path,
-        ),
-        worktree_path="",
-        role=REPORT_WRITER_WORKER_ID,
-        idle_timeout_seconds=idle_timeout_seconds,
-        dispatch_kind="initial",
-    )
-
-
-def _validate_codex_manifest(manifest: Mapping[str, Any], path: Path) -> None:
-    if manifest.get("leadRuntime") != "codex":
-        raise DispatchError(f"run manifest is not a Codex lead run: {path}")
-    if not isinstance(manifest.get("leadEventsPath"), str):
-        raise DispatchError(f"run manifest has no leadEventsPath: {path}")
-
-
-def _requested_worker_model(
-    worker_id: str,
-    team_state: Mapping[str, Any],
-) -> str:
-    state = _worker_state(team_state, worker_id)
-    return _require_string(state, "modelExecutionValue")
-
-
-def _select_workers(
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    requested_workers: Sequence[str],
-) -> list[str]:
-    recommended = _string_list(manifest.get("recommendedWorkers"))
-    if not recommended:
-        raise DispatchError("run manifest has no recommendedWorkers entries")
-    dispatchable = _dispatchable_workers(recommended, team_state)
-    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 _assigned_runner(_worker_state(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 _assigned_provider(worker_state: Mapping[str, Any], worker_id: str) -> str:
-    provider = _string_value(worker_state.get("provider"))
-    if provider:
-        return provider
-    return "codex" if worker_id == REPORT_WRITER_WORKER_ID else worker_id
-
-
-def _assigned_runner(worker_state: Mapping[str, Any]) -> str:
-    return _string_value(worker_state.get("runner")) or BACKEND_CLI_WRAPPER
-
-
-def _dispatchable_workers(
-    recommended: Sequence[str], team_state: Mapping[str, Any],
-) -> set[str]:
-    dispatchable = set()
-    for worker_id in recommended:
-        state = _worker_state(team_state, worker_id)
-        provider = _assigned_provider(state, worker_id)
-        if (
-            _assigned_runner(state) == BACKEND_CLI_WRAPPER
-            and provider in SUPPORTED_CLI_WORKERS
-        ):
-            dispatchable.add(worker_id)
-    return dispatchable
-
-
-def _skipped_worker_reasons(
-    manifest: Mapping[str, Any],
-    team_state: Mapping[str, Any],
-    selected_workers: Sequence[str],
-    requested_workers: Sequence[str],
-) -> dict[str, str]:
-    recommended = _string_list(manifest.get("recommendedWorkers"))
-    selected = set(selected_workers)
-    if requested_workers:
-        return {
-            worker_id: "skipped by Codex dispatch: worker was not requested in this invocation"
-            for worker_id in recommended
-            if worker_id not in selected
-            and _assigned_runner(_worker_state(team_state, worker_id))
-            == BACKEND_CLI_WRAPPER
-        }
-
-    supported = _dispatchable_workers(recommended, team_state)
-    reasons = {}
-    for worker_id in recommended:
-        if worker_id in selected:
-            continue
-        state = _worker_state(team_state, worker_id)
-        if _assigned_runner(state) == "native-session":
-            continue
-        if worker_id not in supported:
-            reasons[worker_id] = (
-                "skipped by Codex dispatch default: assigned provider has no "
-                "registered CLI wrapper"
-            )
-        else:
-            reasons[worker_id] = "skipped by Codex dispatch default"
-    return reasons
-
-
-def _mark_skipped_workers(
-    team_state_path: Path,
-    team_state: Mapping[str, Any],
-    reasons_by_worker_id: Mapping[str, str],
-) -> None:
-    if not reasons_by_worker_id:
-        return
-    workers = team_state.get("workers")
-    if not isinstance(workers, list):
-        raise DispatchError(f"team-state workers must be an array: {team_state_path}")
-    for worker in workers:
-        if not isinstance(worker, dict):
-            continue
-        worker_id = _string_value(worker.get("workerId"))
-        reason = reasons_by_worker_id.get(worker_id)
-        if not reason:
-            continue
-        status = _string_value(worker.get("status")) or "not-run"
-        current_reason = _string_value(worker.get("reason"))
-        if status == "not-run" and not current_reason:
-            _transition_worker_status(
-                team_state_path, worker_id, "not-run", reason
-            )
-
-
-def _resolve_wrapper(
-    worker_id: str,
-    workspace_root: Path,
-    okstra_bin: Path | None,
-) -> Path:
-    script = SUPPORTED_CLI_WORKERS.get(worker_id)
-    if script is None:
-        raise DispatchError(f"unsupported worker provider: {worker_id}")
-    candidates = []
-    if okstra_bin is not None:
-        candidates.append(okstra_bin / script)
-    candidates.extend([
-        workspace_root / "bin" / script,
-        workspace_root / "scripts" / script,
-    ])
-    for candidate in candidates:
-        if candidate.is_file():
-            return candidate.resolve()
-    searched = ", ".join(str(candidate) for candidate in candidates)
-    raise DispatchError(f"{script} not found (searched: {searched})")
-
-
-def _run_worker(
-    plan: DispatchPlan,
-    worker: WorkerJob,
-) -> subprocess.CompletedProcess[str]:
-    if worker.backend == BACKEND_CLI_WRAPPER:
-        return _run_cli_wrapper_worker(plan, worker)
-    raise DispatchError(f"unsupported Codex worker backend: {worker.backend}")
-
-
-def _run_cli_wrapper_worker(
-    plan: DispatchPlan,
-    worker: WorkerJob,
-) -> subprocess.CompletedProcess[str]:
-    return subprocess.run(worker.command, cwd=plan.project_root, text=True)
-
-
-def _post_process_report_writer_result(
-    plan: DispatchPlan,
-    worker: WorkerJob,
-) -> dict[str, Any]:
-    if worker.worker_id != REPORT_WRITER_WORKER_ID:
-        return {"ok": True, "reason": "", "steps": []}
-    try:
-        ctx = 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=worker.result_path,
-            manifest=plan.manifest,
-        )
-    except FinalizeError as exc:
-        return {"ok": False, "reason": str(exc), "steps": []}
-
-    def settle_before(step_name: str) -> None:
-        # validate-run reads team-state; the writer is done by the time its
-        # artifacts pass the earlier steps.
-        if step_name == STEP_VALIDATE_RUN:
-            _transition_worker_status(
-                plan.team_state_path, worker.worker_id, "completed", ""
-            )
-
-    return run_finalize(ctx, before_step=settle_before)
-
-
-def _append_event(
-    plan: DispatchPlan,
-    event_type: str,
-    details: Mapping[str, Any],
-) -> None:
-    append_lead_event(
-        plan.lead_events_path,
-        LeadEvent(
-            event_type=event_type,
-            lead_runtime="codex",
-            task_key=_require_string(plan.manifest, "taskKey"),
-            task_type=_require_string(plan.manifest, "taskType"),
-            run_seq=_run_seq(plan.manifest),
-            timestamp=_utc_now(),
-            details=details,
-        ),
-    )
-
-
-def _event_details(worker: WorkerJob) -> dict[str, Any]:
-    return {
-        "dispatchMode": worker.backend,
-        "workerId": worker.worker_id,
-        "promptPath": str(worker.prompt_path),
-        "resultPath": str(worker.result_path),
-        "workerResultPath": str(worker.worker_result_path),
-        "wrapperPath": str(worker.wrapper_path),
-        "role": worker.role,
-    }
-
-
-def _attempt_event_details(worker: WorkerJob, attempt: int) -> dict[str, Any]:
-    return {
-        **_event_details(worker),
-        "attempt": attempt,
-        "maxAttempts": MAX_WORKER_ATTEMPTS,
-    }
-
-
-def _should_retry_missing_result(
-    result: subprocess.CompletedProcess[str],
-    missing_paths: Sequence[Path],
-    attempt: int,
-) -> bool:
-    return (
-        result.returncode == 0
-        and bool(missing_paths)
-        and attempt < MAX_WORKER_ATTEMPTS
-    )
-
-
-def _pane_role(prompt_path: Path) -> str:
-    if not prompt_path.is_file():
-        raise DispatchError(f"worker prompt not found: {prompt_path}")
-    marker = "**Pane role:**"
-    for line in prompt_path.read_text(encoding="utf-8", errors="replace").splitlines():
-        if line.startswith(marker):
-            role = line[len(marker):].strip()
-            return role or "worker"
-    return "worker"
-
-
-def _load_optional_json_object(path: Path | None) -> dict[str, Any]:
-    if path is None or not path.is_file():
-        return {}
-    return hydrate_active_run_context(_load_json_object(path, "active-run-context"))
-
-
-def _failure_reason(exit_code: int, missing_paths: Sequence[Path]) -> str:
-    if exit_code != 0:
-        return f"wrapper exited with code {exit_code}"
-    if missing_paths:
-        missing = ", ".join(str(path) for path in missing_paths)
-        return f"required worker artifact was not produced: {missing}"
-    return "worker dispatch failed"
-
-
 def _parse_workers(raw: str) -> list[str]:
     return [item.strip() for item in raw.split(",") if item.strip()]