okstra 0.76.0 → 0.78.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -0,0 +1,1552 @@
+"""Codex lead CLI-worker dispatcher.
+
+This module is intentionally narrower than the Claude Code team dispatcher. It
+reads an already-prepared Codex run manifest and dispatches only workers that
+have a CLI wrapper path. `report-writer` is supported only through explicit
+Codex opt-in because the prepared manifest still records a Claude-side model by
+default.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+from .lead_events import LeadEvent, append_lead_event
+from .wrapper_status import status_path_for_prompt
+from .paths import task_dir
+
+
+SUPPORTED_CLI_WORKERS = {
+    "codex": "okstra-codex-exec.sh",
+    "gemini": "okstra-gemini-exec.sh",
+}
+BACKEND_CLI_WRAPPER = "cli-wrapper"
+BACKEND_MIXED = "mixed"
+MAX_WORKER_ATTEMPTS = 2
+REPORT_WRITER_WORKER_ID = "report-writer"
+REPORT_LANGUAGE_VALUES = {"en", "ko", "auto"}
+WORKER_PREAMBLE_PATH = Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
+ANALYSIS_WORKER_LABELS = {
+    "codex": "Codex worker",
+    "gemini": "Gemini worker",
+}
+
+
+class DispatchError(Exception):
+    """Raised when a Codex dispatch request cannot be executed."""
+
+
+@dataclass(frozen=True)
+class WorkerDispatch:
+    worker_id: str
+    backend: str
+    project_root: Path
+    model_execution_value: str
+    wrapper_path: Path
+    prompt_path: Path
+    result_path: Path
+    worker_result_path: Path
+    completion_paths: tuple[Path, ...]
+    worktree_path: str
+    role: str
+    idle_timeout_seconds: int
+
+    @property
+    def command(self) -> list[str]:
+        return [
+            str(self.wrapper_path),
+            str(self.project_root),
+            self.model_execution_value,
+            str(self.prompt_path),
+            self.worktree_path,
+            self.role,
+            str(self.idle_timeout_seconds),
+        ]
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "workerId": self.worker_id,
+            "backend": self.backend,
+            "modelExecutionValue": self.model_execution_value,
+            "wrapperPath": str(self.wrapper_path),
+            "promptPath": str(self.prompt_path),
+            "resultPath": str(self.result_path),
+            "workerResultPath": str(self.worker_result_path),
+            "completionPaths": [str(path) for path in self.completion_paths],
+            "worktreePath": self.worktree_path,
+            "role": self.role,
+            "command": self.command,
+        }
+
+
+@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[WorkerDispatch, ...]
+
+    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],
+        }
+
+
+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,
+    enable_codex_report_writer: bool = False,
+    report_writer_codex_model: str = "",
+) -> DispatchPlan:
+    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)
+
+    selected_workers = _select_workers(
+        manifest,
+        requested_workers,
+        enable_codex_report_writer=enable_codex_report_writer,
+    )
+    team_state_path = _resolve_required_path(
+        project_root, manifest, "teamStatePath", "team-state"
+    )
+    team_state = _load_json_object(team_state_path, "team-state")
+    _mark_skipped_workers(
+        team_state_path,
+        team_state,
+        _skipped_worker_reasons(
+            manifest,
+            selected_workers,
+            requested_workers,
+            enable_codex_report_writer=enable_codex_report_writer,
+        ),
+    )
+    active_context = _load_optional_json_object(
+        _resolve_optional_path(project_root, manifest.get("activeRunContextPath"))
+    )
+    lead_events_path = _resolve_required_path(
+        project_root, manifest, "leadEventsPath", "lead events"
+    )
+    _materialize_missing_worker_prompts(
+        project_root=project_root,
+        manifest=manifest,
+        team_state=team_state,
+        active_context=active_context,
+        selected_workers=selected_workers,
+        workspace_root=workspace_root,
+        report_writer_codex_model=report_writer_codex_model,
+    )
+    workers = 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,
+            report_writer_codex_model=report_writer_codex_model,
+        )
+        for worker_id in selected_workers
+    )
+    return DispatchPlan(
+        project_root=project_root,
+        workspace_root=workspace_root,
+        manifest_path=manifest_path,
+        team_state_path=team_state_path,
+        lead_events_path=lead_events_path,
+        manifest=manifest,
+        workers=workers,
+    )
+
+
+def dispatch_plan(plan: DispatchPlan) -> int:
+    _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.workers))
+    for worker in plan.workers:
+        _set_worker_status(
+            plan.team_state_path,
+            worker.worker_id,
+            "running",
+            "",
+            model_execution_value=worker.model_execution_value,
+        )
+        completed = _dispatch_worker_with_retry(plan, worker)
+        if completed == 0:
+            continue
+        return completed
+    return 0
+
+
+def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerDispatch) -> int:
+    for attempt in range(1, MAX_WORKER_ATTEMPTS + 1):
+        _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")
+                _set_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
+            _set_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)
+        _set_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: WorkerDispatch,
+    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: WorkerDispatch, attempt: int
+) -> bool:
+    return (
+        isinstance(record, dict)
+        and record.get("workerId") == worker.worker_id
+        and record.get("kind") == "initial"
+        and record.get("attempt") == attempt
+    )
+
+
+def _worker_dispatch_record(
+    worker: WorkerDispatch, attempt: int, status: str, reason: str
+) -> dict[str, Any]:
+    provider = "codex" if worker.worker_id == REPORT_WRITER_WORKER_ID else worker.worker_id
+    return {
+        "workerId": worker.worker_id,
+        "role": worker.role,
+        "kind": "initial",
+        "attempt": attempt,
+        "backendType": worker.backend,
+        "provider": provider,
+        "status": status,
+        "paneId": "",
+        "promptPath": str(worker.prompt_path),
+        "resultPath": str(worker.result_path),
+        "workerResultPath": str(worker.worker_result_path),
+        "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)
+    try:
+        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,
+            enable_codex_report_writer=args.enable_codex_report_writer,
+            report_writer_codex_model=args.report_writer_codex_model,
+        )
+        if args.dry_run:
+            _print_json(plan.to_payload(dry_run=True))
+            return 0
+        code = dispatch_plan(plan)
+        _print_json({**plan.to_payload(dry_run=False), "exitCode": code})
+        return code
+    except DispatchError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra codex-dispatch",
+        description="Dispatch CLI-backed workers for a prepared Codex lead run.",
+    )
+    parser.add_argument("--project-root", required=True)
+    parser.add_argument("--run-manifest", required=True)
+    parser.add_argument("--workspace-root", required=True)
+    parser.add_argument("--okstra-bin", default="")
+    parser.add_argument("--workers", default="")
+    parser.add_argument("--dry-run", action="store_true")
+    parser.add_argument("--idle-timeout-seconds", default="600")
+    parser.add_argument("--enable-codex-report-writer", action="store_true")
+    parser.add_argument("--report-writer-codex-model", default="")
+    return parser
+
+
+def _materialize_missing_worker_prompts(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    selected_workers: Sequence[str],
+    workspace_root: Path,
+    report_writer_codex_model: str,
+) -> None:
+    for worker_id in selected_workers:
+        prompt_path = _resolve_project_path(
+            project_root, _worker_prompt_path(manifest, worker_id)
+        )
+        if prompt_path.is_file():
+            continue
+        prompt = _render_missing_worker_prompt(
+            project_root=project_root,
+            manifest=manifest,
+            team_state=team_state,
+            active_context=active_context,
+            worker_id=worker_id,
+            workspace_root=workspace_root,
+            report_writer_codex_model=report_writer_codex_model,
+        )
+        prompt_path.parent.mkdir(parents=True, exist_ok=True)
+        prompt_path.write_text(prompt, encoding="utf-8")
+
+
+def _render_missing_worker_prompt(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+    workspace_root: Path,
+    report_writer_codex_model: str,
+) -> str:
+    if worker_id == REPORT_WRITER_WORKER_ID:
+        return _render_missing_report_writer_prompt(
+            project_root=project_root,
+            manifest=manifest,
+            team_state=team_state,
+            active_context=active_context,
+            report_writer_codex_model=report_writer_codex_model,
+        )
+    return _render_missing_analysis_worker_prompt(
+        project_root=project_root,
+        manifest=manifest,
+        team_state=team_state,
+        active_context=active_context,
+        worker_id=worker_id,
+        workspace_root=workspace_root,
+    )
+
+
+def _render_missing_analysis_worker_prompt(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+    workspace_root: Path,
+) -> str:
+    worker_state = _worker_state(team_state, worker_id)
+    result_rel = _require_string(worker_state, "resultPath")
+    prompt_rel = _worker_prompt_path(manifest, worker_id)
+    model = _require_string(worker_state, "modelExecutionValue")
+    role = _analysis_pane_role(manifest, active_context, worker_id)
+    lines = _base_prompt_headers(
+        project_root=project_root,
+        manifest=manifest,
+        active_context=active_context,
+        worker_id=worker_id,
+        prompt_rel=prompt_rel,
+        result_rel=result_rel,
+    )
+    lines.extend(_worktree_headers(manifest, active_context, role))
+    lines.extend(_analysis_prompt_body(manifest, active_context, worker_id, model, role))
+    executor_tail = _implementation_executor_tail(
+        manifest, workspace_root, role
+    )
+    if executor_tail:
+        lines.extend(["", executor_tail.rstrip()])
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def _render_missing_report_writer_prompt(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    report_writer_codex_model: str,
+) -> str:
+    worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
+    markdown_path = _resolve_required_path(
+        project_root, manifest, "expectedReportPath", "report"
+    )
+    data_json_path = _final_report_data_path(markdown_path)
+    result_rel = _project_relative_path(project_root, data_json_path)
+    worker_result_rel = _require_string(worker_state, "resultPath")
+    model = (report_writer_codex_model or "").strip()
+    if not model:
+        raise DispatchError(
+            "Codex report-writer dispatch requires --report-writer-codex-model"
+        )
+    lines = _base_prompt_headers(
+        project_root=project_root,
+        manifest=manifest,
+        active_context=active_context,
+        worker_id=REPORT_WRITER_WORKER_ID,
+        prompt_rel=_worker_prompt_path(manifest, REPORT_WRITER_WORKER_ID),
+        result_rel=result_rel,
+    )
+    lines.extend([
+        f"**Worker Result Path:** {worker_result_rel}",
+        f"**Model:** Report writer worker, {model}",
+        f"**Report Language:** {_resolve_report_language(project_root, manifest, active_context)}",
+    ])
+    lines.extend(_report_writer_prompt_body(manifest, active_context, team_state))
+    return "\n".join(lines).rstrip() + "\n"
+
+
+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,
+    report_writer_codex_model: str,
+) -> WorkerDispatch:
+    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,
+            report_writer_codex_model=report_writer_codex_model,
+        )
+    worker_state = _worker_state(team_state, worker_id)
+    prompt_rel = _worker_prompt_path(manifest, worker_id)
+    prompt_path = _resolve_project_path(project_root, prompt_rel)
+    result_path = _resolve_project_path(
+        project_root, _require_string(worker_state, "resultPath")
+    )
+    model_execution_value = _require_string(worker_state, "modelExecutionValue")
+    wrapper = _resolve_wrapper(worker_id, workspace_root, okstra_bin)
+    worktree_path = _worktree_path(manifest, active_context)
+    role = _pane_role(prompt_path)
+    return WorkerDispatch(
+        worker_id=worker_id,
+        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,
+    )
+
+
+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,
+    report_writer_codex_model: str,
+) -> WorkerDispatch:
+    model_execution_value = (report_writer_codex_model or "").strip()
+    if not model_execution_value:
+        raise DispatchError(
+            "Codex report-writer dispatch requires --report-writer-codex-model"
+        )
+    worker_state = _worker_state(team_state, REPORT_WRITER_WORKER_ID)
+    prompt_path = _resolve_project_path(
+        project_root, _worker_prompt_path(manifest, REPORT_WRITER_WORKER_ID)
+    )
+    data_json_path = _final_report_data_path(
+        _resolve_required_path(project_root, manifest, "expectedReportPath", "report")
+    )
+    markdown_path = _final_report_markdown_path(data_json_path)
+    worker_result_path = _resolve_project_path(
+        project_root, _require_string(worker_state, "resultPath")
+    )
+    _replace_report_writer_model_line(prompt_path, model_execution_value)
+    return WorkerDispatch(
+        worker_id=REPORT_WRITER_WORKER_ID,
+        backend=BACKEND_CLI_WRAPPER,
+        project_root=project_root,
+        model_execution_value=model_execution_value,
+        wrapper_path=_resolve_wrapper("codex", 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,
+    )
+
+
+def _analysis_prompt_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+    model: str,
+    role: str,
+) -> list[str]:
+    label = ANALYSIS_WORKER_LABELS[worker_id]
+    return [
+        f"**Model:** {label}, {model}",
+        f"**Pane role:** {role}",
+        "",
+        f"# {label} Dispatch",
+        "",
+        "## Role",
+        (
+            f"You are the {label} for okstra cross-verification. "
+            "Produce an independent worker result."
+        ),
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *_analysis_input_lines(manifest, active_context),
+        "",
+        _mcp_pointer_line(),
+        "",
+        "## Output Contract",
+        "- Read the Worker Preamble Path end-to-end before analysis.",
+        "- Write the worker result to Result Path and no other canonical result path.",
+        "- Write the audit sidecar and any tool-failure entries as the preamble requires.",
+        "- Cite evidence with file paths and line numbers whenever you make a claim.",
+    ]
+
+
+def _report_writer_prompt_body(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+) -> list[str]:
+    return [
+        "",
+        "# Report Writer Worker Dispatch",
+        "",
+        "## Role",
+        (
+            "You are the Report writer worker. Author the final-report data.json "
+            "and the worker-results audit file."
+        ),
+        "",
+        "## Task",
+        f"- Task key: `{_require_string(manifest, 'taskKey')}`",
+        f"- Task type: `{_require_string(manifest, 'taskType')}`",
+        "",
+        "## Inputs",
+        *_report_writer_input_lines(manifest, active_context, team_state),
+        "",
+        _mcp_pointer_line(),
+        "",
+        "## Output Contract",
+        "You are the author of TWO files:",
+        "- The final-report data.json at Result Path.",
+        "- The worker-results audit file at Worker Result Path.",
+        (
+            'After writing the data.json, invoke "okstra render-final-report '
+            '<Result Path>" so the markdown sibling is rendered before you return.'
+        ),
+        "Do not return the report inline.",
+        "Copy Report Language verbatim into data.json.meta.reportLanguage.",
+    ]
+
+
+def _mcp_pointer_line() -> str:
+    return (
+        '**MCP servers:** follow the task brief\'s "## Available MCP Servers" '
+        "section (already in your Required reading)."
+    )
+
+
+def _base_prompt_headers(
+    *,
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+    prompt_rel: str,
+    result_rel: str,
+) -> list[str]:
+    prompt_path = _resolve_project_path(project_root, prompt_rel)
+    return [
+        f"**Project Root:** {project_root}",
+        f"**Prompt History Path:** {prompt_rel}",
+        f"**Result Path:** {result_rel}",
+        f"Assigned worker prompt history path: {prompt_path}",
+        f"**Worker Preamble Path:** {WORKER_PREAMBLE_PATH}",
+        f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
+        (
+            f"**Errors sidecar path:** "
+            f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
+        ),
+    ]
+
+
+def _analysis_input_lines(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> list[str]:
+    inputs = [
+        ("Primary analysis packet", _instruction_path(manifest, active_context, "analysisPacketPath")),
+        ("Task brief", _instruction_path(manifest, active_context, "taskBriefPath")),
+        ("Analysis profile", _instruction_path(manifest, active_context, "analysisProfilePath")),
+        ("Analysis material", _instruction_path(manifest, active_context, "analysisMaterialPath")),
+        ("Reference expectations", _instruction_path(manifest, active_context, "referenceExpectationsPath")),
+        ("Clarification response", _instruction_path(manifest, active_context, "clarificationResponsePath")),
+    ]
+    return _existing_input_lines(inputs)
+
+
+def _report_writer_input_lines(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    team_state: Mapping[str, Any],
+) -> list[str]:
+    inputs = [
+        ("Task brief", _instruction_path(manifest, active_context, "taskBriefPath")),
+        ("Analysis profile", _instruction_path(manifest, active_context, "analysisProfilePath")),
+        ("Analysis material", _instruction_path(manifest, active_context, "analysisMaterialPath")),
+        ("Reference expectations", _instruction_path(manifest, active_context, "referenceExpectationsPath")),
+        ("Clarification response", _instruction_path(manifest, active_context, "clarificationResponsePath")),
+        ("Final report template", _instruction_path(manifest, active_context, "finalReportTemplatePath")),
+        ("Final report schema", _instruction_path(manifest, active_context, "finalReportSchemaPath")),
+        ("Worker results directory", _string_value(manifest.get("workerResultsDirectoryPath"))),
+    ]
+    lines = _existing_input_lines(inputs)
+    lines.extend(_analysis_worker_result_lines(team_state))
+    return lines or ["- No report-writer inputs were recorded in active-run-context."]
+
+
+def _existing_input_lines(inputs: Sequence[tuple[str, str]]) -> list[str]:
+    lines = [f"- {label}: `{path}`" for label, path in inputs if path]
+    return lines or ["- No input paths were recorded in active-run-context."]
+
+
+def _analysis_worker_result_lines(team_state: Mapping[str, Any]) -> list[str]:
+    lines = []
+    workers = team_state.get("workers")
+    if not isinstance(workers, list):
+        return lines
+    for worker in workers:
+        if not isinstance(worker, Mapping):
+            continue
+        worker_id = worker.get("workerId")
+        if worker_id == REPORT_WRITER_WORKER_ID:
+            continue
+        result_path = _string_value(worker.get("resultPath"))
+        if result_path:
+            lines.append(f"- Analysis result ({worker_id}): `{result_path}`")
+    return lines
+
+
+def _instruction_path(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    key: str,
+) -> str:
+    instruction_set = active_context.get("instructionSet")
+    if isinstance(instruction_set, Mapping):
+        value = _string_value(instruction_set.get(key))
+        if value:
+            return value
+    return _string_value(manifest.get(key))
+
+
+def _analysis_pane_role(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+) -> str:
+    if _require_string(manifest, "taskType") != "implementation":
+        return "worker"
+    if _executor_provider(manifest) != worker_id:
+        return "worker"
+    worktree = _worktree_path(manifest, active_context)
+    if not worktree:
+        raise DispatchError("implementation executor prompt generation requires a worktree path")
+    return "executor"
+
+
+def _executor_provider(manifest: Mapping[str, Any]) -> str:
+    team_contract = manifest.get("teamContract")
+    if not isinstance(team_contract, Mapping):
+        return ""
+    executor = team_contract.get("executor")
+    if not isinstance(executor, Mapping):
+        return ""
+    return _string_value(executor.get("provider"))
+
+
+def _worktree_headers(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    role: str,
+) -> list[str]:
+    task_type = _require_string(manifest, "taskType")
+    worktree = _worktree_path(manifest, active_context)
+    if task_type not in {"implementation", "final-verification"} or not worktree:
+        return []
+    headers = [f"**Worktree:** {worktree}"]
+    if role == "executor":
+        headers.append(f"cwd for every mutating command: {worktree}")
+    return headers
+
+
+def _implementation_executor_tail(
+    manifest: Mapping[str, Any],
+    workspace_root: Path,
+    role: str,
+) -> str:
+    if role != "executor" or _require_string(manifest, "taskType") != "implementation":
+        return ""
+    preflight_path = workspace_root / "prompts" / "profiles" / "_coding-conventions-preflight.md"
+    if not preflight_path.is_file():
+        return "# Coding-conventions preflight\n\nApply project-local conventions before editing."
+    return preflight_path.read_text(encoding="utf-8")
+
+
+def _errors_log_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        value = _string_value(error_logs.get("runErrorsLogPath"))
+        if value:
+            return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    return run_dir / "logs" / f"errors-{_require_string(manifest, 'taskType')}-{_sequence(manifest, 'state')}.jsonl"
+
+
+def _worker_errors_sidecar_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        sidecars = error_logs.get("sidecarsByWorkerId")
+        if isinstance(sidecars, Mapping):
+            value = _string_value(sidecars.get(worker_id))
+            if value:
+                return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "workerResults")
+    return run_dir / "worker-results" / f"{worker_id}-worker-errors-{task_type}-{seq}.json"
+
+
+def _run_directory_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    value = _string_value(manifest.get("runDirectoryPath"))
+    if value:
+        return _resolve_project_path(project_root, value)
+    return _resolve_required_path(project_root, manifest, "teamStatePath", "team-state").parent.parent
+
+
+def _sequence(manifest: Mapping[str, Any], key: str) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        return _run_seq(manifest)
+    return _string_value(seqs.get(key)) or _run_seq(manifest)
+
+
+def _project_relative_path(project_root: Path, path: Path) -> str:
+    try:
+        return path.relative_to(project_root).as_posix()
+    except ValueError:
+        return str(path)
+
+
+def _resolve_report_language(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> str:
+    for value in _report_language_candidates(project_root):
+        if value == "auto":
+            return _infer_report_language(project_root, manifest, active_context)
+        if value:
+            return value
+    return _infer_report_language(project_root, manifest, active_context)
+
+
+def _report_language_candidates(project_root: Path) -> list[str]:
+    okstra_home = Path(os.environ.get("OKSTRA_HOME") or Path.home() / ".okstra")
+    return [
+        _read_report_language(project_root / ".okstra" / "project.json", "project"),
+        _read_report_language(okstra_home / "config.json", "global"),
+    ]
+
+
+def _read_report_language(path: Path, label: str) -> str:
+    if not path.is_file():
+        return ""
+    value = _load_json_object(path, f"{label} config").get("reportLanguage")
+    if value in (None, ""):
+        return ""
+    if isinstance(value, str) and value in REPORT_LANGUAGE_VALUES:
+        return value
+    raise DispatchError(f"{label} config reportLanguage must be en, ko, or auto: {path}")
+
+
+def _infer_report_language(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> str:
+    task_brief = _instruction_path(manifest, active_context, "taskBriefPath")
+    if not task_brief:
+        return "en"
+    path = _resolve_project_path(project_root, task_brief)
+    if not path.is_file():
+        return "en"
+    text = path.read_text(encoding="utf-8", errors="replace")[:16000]
+    hangul_count = sum(1 for char in text if "\uac00" <= char <= "\ud7a3")
+    return "ko" if hangul_count >= 10 else "en"
+
+
+def _string_value(value: Any) -> str:
+    if not isinstance(value, str):
+        return ""
+    return value.strip()
+
+
+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 _select_workers(
+    manifest: Mapping[str, Any],
+    requested_workers: Sequence[str],
+    *,
+    enable_codex_report_writer: bool,
+) -> list[str]:
+    recommended = _string_list(manifest.get("recommendedWorkers"))
+    if not recommended:
+        raise DispatchError("run manifest has no recommendedWorkers entries")
+    supported_workers = _supported_codex_dispatch_workers(
+        enable_codex_report_writer=enable_codex_report_writer
+    )
+    if not requested_workers:
+        selected = [worker for worker in recommended if worker in supported_workers]
+        if selected:
+            return selected
+        if REPORT_WRITER_WORKER_ID in recommended and not enable_codex_report_writer:
+            raise DispatchError(
+                "report-writer requires --enable-codex-report-writer because it "
+                "runs through the Codex wrapper instead of Claude Agent"
+            )
+        supported = ", ".join(sorted(supported_workers))
+        raise DispatchError(
+            "run roster has no Codex-dispatch supported worker(s) "
+            f"(CLI dispatcher supports: {supported})"
+        )
+
+    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)
+        )
+    if REPORT_WRITER_WORKER_ID in selected and not enable_codex_report_writer:
+        raise DispatchError(
+            "report-writer requires --enable-codex-report-writer because it "
+            "runs through the Codex wrapper instead of Claude Agent"
+        )
+    unsupported = [
+        worker for worker in selected
+        if worker not in supported_workers
+    ]
+    if unsupported:
+        supported = ", ".join(sorted(supported_workers))
+        raise DispatchError(
+            "unsupported Codex lead worker(s): "
+            + ", ".join(unsupported)
+            + f" (CLI dispatcher supports: {supported})"
+        )
+    return selected
+
+
+def _supported_codex_dispatch_workers(*, enable_codex_report_writer: bool) -> set[str]:
+    supported = set(SUPPORTED_CLI_WORKERS)
+    if enable_codex_report_writer:
+        supported.add(REPORT_WRITER_WORKER_ID)
+    return supported
+
+
+def _skipped_worker_reasons(
+    manifest: Mapping[str, Any],
+    selected_workers: Sequence[str],
+    requested_workers: Sequence[str],
+    *,
+    enable_codex_report_writer: bool,
+) -> 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
+        }
+
+    supported = _supported_codex_dispatch_workers(
+        enable_codex_report_writer=enable_codex_report_writer
+    )
+    reasons = {}
+    for worker_id in recommended:
+        if worker_id in selected:
+            continue
+        if worker_id == REPORT_WRITER_WORKER_ID and not enable_codex_report_writer:
+            reasons[worker_id] = (
+                "skipped by Codex dispatch default: report-writer requires "
+                "--enable-codex-report-writer and --report-writer-codex-model"
+            )
+        elif worker_id not in supported:
+            reasons[worker_id] = (
+                "skipped by Codex dispatch default: worker is not supported by "
+                "the Codex CLI dispatcher"
+            )
+        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}")
+    changed = False
+    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:
+            worker["status"] = "not-run"
+            worker["reason"] = reason
+            changed = True
+    if changed:
+        _write_json(team_state_path, dict(team_state))
+
+
+def _resolve_wrapper(
+    worker_id: str,
+    workspace_root: Path,
+    okstra_bin: Path | None,
+) -> Path:
+    script = SUPPORTED_CLI_WORKERS[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: WorkerDispatch,
+) -> 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: WorkerDispatch,
+) -> subprocess.CompletedProcess[str]:
+    env = {
+        **os.environ,
+        "OKSTRA_WORKER_ID": worker.worker_id,
+        "OKSTRA_WORKER_RESULT_PATH": str(worker.result_path),
+        "OKSTRA_WORKER_AUDIT_PATH": str(worker.worker_result_path),
+        "OKSTRA_RUN_MANIFEST_PATH": str(plan.manifest_path),
+    }
+    if worker.worker_id == REPORT_WRITER_WORKER_ID:
+        env["OKSTRA_REPORT_WRITER_MARKDOWN_PATH"] = str(
+            _final_report_markdown_path(worker.result_path)
+        )
+    return subprocess.run(worker.command, cwd=plan.project_root, env=env, text=True)
+
+
+def _post_process_report_writer_result(
+    plan: DispatchPlan,
+    worker: WorkerDispatch,
+) -> dict[str, Any]:
+    if worker.worker_id != REPORT_WRITER_WORKER_ID:
+        return {"ok": True, "reason": "", "steps": []}
+    steps = []
+    try:
+        commands = _report_post_process_commands(plan, worker)
+    except DispatchError as exc:
+        return {"ok": False, "reason": str(exc), "steps": steps}
+    for name, command in commands:
+        if name == "validate-run":
+            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
+        result = subprocess.run(
+            command,
+            cwd=plan.project_root,
+            text=True,
+            capture_output=True,
+        )
+        step = _post_process_step_payload(name, command, result)
+        steps.append(step)
+        if result.returncode != 0:
+            return {
+                "ok": False,
+                "reason": f"{name} failed with exit code {result.returncode}",
+                "steps": steps,
+            }
+    return {"ok": True, "reason": "", "steps": steps}
+
+
+def _report_post_process_commands(
+    plan: DispatchPlan,
+    worker: WorkerDispatch,
+) -> list[tuple[str, list[str]]]:
+    markdown_path = _final_report_markdown_path(worker.result_path)
+    commands = [
+        (
+            "token-usage",
+            [
+                sys.executable,
+                str(_resolve_workspace_script(plan.workspace_root, "okstra-token-usage.py")),
+                str(plan.team_state_path),
+                "--project-root",
+                str(plan.project_root),
+                "--write",
+                "--substitute-data",
+                str(worker.result_path),
+            ],
+        ),
+        (
+            "render-views",
+            [
+                sys.executable,
+                str(_resolve_workspace_script(plan.workspace_root, "okstra-render-report-views.py")),
+                str(markdown_path),
+                "--task-key",
+                _require_string(plan.manifest, "taskKey"),
+                "--task-type",
+                _require_string(plan.manifest, "taskType"),
+                "--seq",
+                _run_seq(plan.manifest),
+                "--source-report",
+                _project_relative_path(plan.project_root, markdown_path),
+            ],
+        ),
+        (
+            "spawn-followups",
+            [
+                sys.executable,
+                str(_resolve_workspace_script(plan.workspace_root, "okstra-spawn-followups.py")),
+                str(worker.result_path),
+                "--project-root",
+                str(plan.project_root),
+                "--task-group",
+                _task_group(plan.manifest),
+                "--parent-task-key",
+                _require_string(plan.manifest, "taskKey"),
+            ],
+        ),
+    ]
+    commands.append(("validate-run", _validate_run_command(plan, markdown_path)))
+    return commands
+
+
+def _validate_run_command(plan: DispatchPlan, markdown_path: Path) -> list[str]:
+    task_manifest_path = _task_manifest_path(plan.project_root, plan.manifest)
+    command = [
+        sys.executable,
+        str(_resolve_workspace_validator(plan.workspace_root, "validate-run.py")),
+        "--team-state",
+        str(plan.team_state_path),
+        "--report",
+        str(markdown_path),
+        "--run-manifest",
+        str(plan.manifest_path),
+        "--task-manifest",
+        str(task_manifest_path),
+    ]
+    final_status_path = _resolve_optional_path(
+        plan.project_root, plan.manifest.get("finalStatusPath")
+    )
+    if final_status_path is not None:
+        command.extend(["--final-status", str(final_status_path)])
+    return command
+
+
+def _task_manifest_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    value = _string_value(manifest.get("taskManifestPath"))
+    if value:
+        return _resolve_project_path(project_root, value)
+    task_root = _string_value(manifest.get("taskRootPath"))
+    if task_root:
+        return _resolve_project_path(project_root, task_root) / "task-manifest.json"
+    return (
+        task_dir(project_root, _task_group(manifest), _task_id(manifest))
+        / "task-manifest.json"
+    )
+
+
+def _post_process_step_payload(
+    name: str,
+    command: Sequence[str],
+    result: subprocess.CompletedProcess[str],
+) -> dict[str, Any]:
+    return {
+        "name": name,
+        "command": list(command),
+        "exitCode": result.returncode,
+        "stdoutTail": _tail(result.stdout),
+        "stderrTail": _tail(result.stderr),
+    }
+
+
+def _resolve_workspace_script(workspace_root: Path, script_name: str) -> Path:
+    candidates = [
+        workspace_root / "scripts" / script_name,
+        workspace_root / script_name,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.resolve()
+    searched = ", ".join(str(candidate) for candidate in candidates)
+    raise DispatchError(f"{script_name} not found (searched: {searched})")
+
+
+def _resolve_workspace_validator(workspace_root: Path, validator_name: str) -> Path:
+    candidates = [
+        workspace_root / "validators" / validator_name,
+        workspace_root / validator_name,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate.resolve()
+    searched = ", ".join(str(candidate) for candidate in candidates)
+    raise DispatchError(f"{validator_name} not found (searched: {searched})")
+
+
+def _task_group(manifest: Mapping[str, Any]) -> str:
+    value = _string_value(manifest.get("taskGroup"))
+    if value:
+        return value
+    task_key = _require_string(manifest, "taskKey")
+    colon_parts = task_key.split(":")
+    if len(colon_parts) >= 3 and colon_parts[-2].strip():
+        return colon_parts[-2].strip()
+    slash_parts = task_key.split("/")
+    if len(slash_parts) >= 2 and slash_parts[0].strip():
+        return slash_parts[0].strip()
+    raise DispatchError(f"cannot infer task group from taskKey: {task_key}")
+
+
+def _task_id(manifest: Mapping[str, Any]) -> str:
+    value = _string_value(manifest.get("taskId"))
+    if value:
+        return value
+    task_key = _require_string(manifest, "taskKey")
+    colon_parts = task_key.split(":")
+    if len(colon_parts) >= 3 and colon_parts[-1].strip():
+        return colon_parts[-1].strip()
+    slash_parts = task_key.split("/")
+    if len(slash_parts) >= 2 and slash_parts[-1].strip():
+        return slash_parts[-1].strip()
+    raise DispatchError(f"cannot infer task id from taskKey: {task_key}")
+
+
+def _tail(text: str, *, limit: int = 4000) -> str:
+    if len(text) <= limit:
+        return text
+    return text[-limit:]
+
+
+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 _dispatch_mode(workers: Sequence[WorkerDispatch]) -> str:
+    backends = {worker.backend for worker in workers}
+    if len(backends) == 1:
+        return next(iter(backends))
+    return BACKEND_MIXED
+
+
+def _event_details(worker: WorkerDispatch) -> 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: WorkerDispatch, 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 _missing_completion_paths(worker: WorkerDispatch) -> list[Path]:
+    return [path for path in worker.completion_paths if not path.is_file()]
+
+
+def _set_worker_status(
+    team_state_path: Path,
+    worker_id: str,
+    status: str,
+    reason: str,
+    *,
+    model_execution_value: str = "",
+) -> None:
+    payload = _load_json_object(team_state_path, "team-state")
+    workers = payload.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 isinstance(worker, dict) and worker.get("workerId") == worker_id:
+            worker["status"] = status
+            worker["reason"] = reason
+            if model_execution_value:
+                worker["model"] = model_execution_value
+                worker["modelExecutionValue"] = model_execution_value
+            _write_json(team_state_path, payload)
+            return
+    raise DispatchError(f"team-state has no workerId={worker_id}: {team_state_path}")
+
+
+def _set_dispatch_mode(team_state_path: Path, dispatch_mode: str) -> None:
+    payload = _load_json_object(team_state_path, "team-state")
+    payload["dispatchMode"] = dispatch_mode
+    _write_json(team_state_path, payload)
+
+
+def _worker_state(team_state: Mapping[str, Any], worker_id: str) -> Mapping[str, Any]:
+    workers = team_state.get("workers")
+    if not isinstance(workers, list):
+        raise DispatchError("team-state workers must be an array")
+    for worker in workers:
+        if isinstance(worker, Mapping) and worker.get("workerId") == worker_id:
+            return worker
+    raise DispatchError(f"team-state has no workerId={worker_id}")
+
+
+def _worker_prompt_path(manifest: Mapping[str, Any], worker_id: str) -> str:
+    paths = manifest.get("workerPromptPathByWorkerId")
+    if not isinstance(paths, Mapping):
+        raise DispatchError("run manifest has no workerPromptPathByWorkerId object")
+    return _require_string(paths, worker_id)
+
+
+def _worktree_path(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> str:
+    if manifest.get("taskType") not in {"implementation", "final-verification"}:
+        return ""
+    worktree = active_context.get("executorWorktree")
+    if not isinstance(worktree, Mapping):
+        return ""
+    return str(worktree.get("path") or "")
+
+
+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_json_object(path: Path, label: str) -> dict[str, Any]:
+    if not path.is_file():
+        raise DispatchError(f"{label} not found: {path}")
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise DispatchError(f"{label} is invalid JSON: {path}: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise DispatchError(f"{label} must be a JSON object: {path}")
+    return payload
+
+
+def _load_optional_json_object(path: Path | None) -> dict[str, Any]:
+    if path is None or not path.is_file():
+        return {}
+    return _load_json_object(path, "active-run-context")
+
+
+def _resolve_required_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    key: str,
+    label: str,
+) -> Path:
+    return _resolve_project_path(project_root, _require_string(manifest, key))
+
+
+def _resolve_optional_path(project_root: Path, value: Any) -> Path | None:
+    if not isinstance(value, str) or not value.strip():
+        return None
+    return _resolve_project_path(project_root, value)
+
+
+def _resolve_project_path(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise DispatchError(f"missing required string field: {key}")
+    return value
+
+
+def _string_list(value: Any) -> list[str]:
+    if not isinstance(value, list):
+        return []
+    return [str(item).strip() for item in value if str(item).strip()]
+
+
+def _run_seq(manifest: Mapping[str, Any]) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise DispatchError("run manifest has no runSequencesByCategory object")
+    return _require_string(seqs, "manifests")
+
+
+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 _final_report_data_path(markdown_path: Path) -> Path:
+    if markdown_path.name.endswith(".md"):
+        return markdown_path.with_name(markdown_path.name[:-3] + ".data.json")
+    return markdown_path.with_suffix(".data.json")
+
+
+def _final_report_markdown_path(data_json_path: Path) -> Path:
+    if data_json_path.name.endswith(".data.json"):
+        return data_json_path.with_name(data_json_path.name[:-10] + ".md")
+    return data_json_path.with_suffix(".md")
+
+
+def _replace_report_writer_model_line(
+    prompt_path: Path,
+    model_execution_value: str,
+) -> None:
+    if not prompt_path.is_file():
+        raise DispatchError(f"report-writer prompt not found: {prompt_path}")
+    lines = prompt_path.read_text(encoding="utf-8").splitlines()
+    marker = "**Model:** Report writer worker,"
+    replacement = f"{marker} {model_execution_value}"
+    updated = [
+        replacement if line.startswith(marker) else line
+        for line in lines
+    ]
+    if updated != lines:
+        prompt_path.write_text("\n".join(updated) + "\n", encoding="utf-8")
+
+
+def _parse_workers(raw: str) -> list[str]:
+    return [item.strip() for item in raw.split(",") if item.strip()]
+
+
+def _parse_idle_timeout(raw: str) -> int:
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise DispatchError("--idle-timeout-seconds must be an integer") from exc
+    if value < 0:
+        raise DispatchError("--idle-timeout-seconds must be non-negative")
+    return value
+
+
+def _utc_now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _write_json(path: Path, payload: Mapping[str, Any]) -> None:
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8")
+
+
+def _print_json(payload: Mapping[str, Any]) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))