okstra 0.144.0 → 0.146.0

package/runtime/python/okstra_ctl/codex_dispatch.py

@@ -43,10 +43,12 @@ from .dispatch_state import (
     resolve_project_path as _resolve_project_path,
     resolve_required_path as _resolve_required_path,
     set_dispatch_mode as _set_dispatch_mode,
-    set_worker_status as _set_worker_status,
     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,
@@ -120,33 +122,46 @@ def build_dispatch_plan(
     idle_timeout_seconds: int = 600,
     enable_codex_report_writer: bool = False,
     report_writer_codex_model: str = "",
+    dispatch_kind: str = "initial",
+    jobs_file: Path | None = None,
 ) -> DispatchPlan:
     inputs = _load_dispatch_inputs(
         project_root,
         run_manifest_path,
         requested_workers,
         enable_codex_report_writer=enable_codex_report_writer,
+        select_roster=jobs_file is None,
     )
-    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,
-        report_writer_codex_model=report_writer_codex_model,
-    )
-    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,
-    )
+    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,
+            report_writer_codex_model=report_writer_codex_model,
+        )
+        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,
@@ -158,36 +173,68 @@ def build_dispatch_plan(
     )
 
 
+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],
     *,
     enable_codex_report_writer: bool,
+    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)
-    selected_workers = tuple(
-        _select_workers(
-            manifest,
-            requested_workers,
-            enable_codex_report_writer=enable_codex_report_writer,
+    selected_workers = (
+        tuple(
+            _select_workers(
+                manifest,
+                requested_workers,
+                enable_codex_report_writer=enable_codex_report_writer,
+            )
         )
+        if select_roster
+        else ()
     )
     team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
     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,
-        ),
-    )
+    if select_roster:
+        _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"))
     )
@@ -276,13 +323,6 @@ def _build_selected_worker_dispatches(
 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
@@ -292,6 +332,13 @@ def dispatch_plan(plan: DispatchPlan) -> int:
 
 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)
@@ -301,7 +348,9 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
             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)
+                _transition_worker_status(
+                    plan.team_state_path, worker.worker_id, "error", reason
+                )
                 _record_worker_attempt(plan, worker, attempt, "error", reason)
                 details = {
                     **attempt_details,
@@ -312,7 +361,9 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
                 }
                 _append_event(plan, "worker-failed", details)
                 return 1
-            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
+            _transition_worker_status(
+                plan.team_state_path, worker.worker_id, "completed", ""
+            )
             _record_worker_attempt(plan, worker, attempt, "completed")
             details = {
                 **attempt_details,
@@ -338,7 +389,9 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
             continue
 
         reason = _failure_reason(result.returncode, missing_paths)
-        _set_worker_status(plan.team_state_path, worker.worker_id, "error", reason)
+        _transition_worker_status(
+            plan.team_state_path, worker.worker_id, "error", reason
+        )
         _record_worker_attempt(plan, worker, attempt, "error", reason)
         details = {
             **attempt_details,
@@ -378,7 +431,7 @@ def _matches_worker_attempt(
     return (
         isinstance(record, dict)
         and record.get("workerId") == worker.worker_id
-        and record.get("kind") == "initial"
+        and record.get("kind") == worker.dispatch_kind
         and record.get("attempt") == attempt
     )
 
@@ -386,14 +439,13 @@ def _matches_worker_attempt(
 def _worker_dispatch_record(
     worker: WorkerJob, 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",
+        "kind": worker.dispatch_kind,
         "attempt": attempt,
         "backendType": worker.backend,
-        "provider": provider,
+        "provider": worker.provider,
         "status": status,
         "paneId": "",
         "promptPath": str(worker.prompt_path),
@@ -410,6 +462,8 @@ def main(argv: Sequence[str] | None = None) -> int:
     parser = _parser()
     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),
@@ -420,6 +474,8 @@ def main(argv: Sequence[str] | None = None) -> int:
             idle_timeout_seconds=idle_timeout_seconds,
             enable_codex_report_writer=args.enable_codex_report_writer,
             report_writer_codex_model=args.report_writer_codex_model,
+            dispatch_kind=args.dispatch_kind,
+            jobs_file=Path(args.jobs_file) if args.jobs_file else None,
         )
         if args.dry_run:
             _print_json(plan.to_payload(dry_run=True))
@@ -446,6 +502,8 @@ def _parser() -> argparse.ArgumentParser:
     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="")
+    parser.add_argument("--dispatch-kind", default="initial")
+    parser.add_argument("--jobs-file", default="")
     return parser
 
 
@@ -672,7 +730,6 @@ def _mark_skipped_workers(
     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
@@ -683,11 +740,9 @@ def _mark_skipped_workers(
         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))
+            _transition_worker_status(
+                team_state_path, worker_id, "not-run", reason
+            )
 
 
 def _resolve_wrapper(
@@ -695,7 +750,9 @@ def _resolve_wrapper(
     workspace_root: Path,
     okstra_bin: Path | None,
 ) -> Path:
-    script = SUPPORTED_CLI_WORKERS[worker_id]
+    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)
@@ -759,7 +816,9 @@ def _post_process_report_writer_result(
         # validate-run reads team-state; the writer is done by the time its
         # artifacts pass the earlier steps.
         if step_name == STEP_VALIDATE_RUN:
-            _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
+            _transition_worker_status(
+                plan.team_state_path, worker.worker_id, "completed", ""
+            )
 
     return run_finalize(ctx, before_step=settle_before)
 

package/runtime/python/okstra_ctl/convergence_engine.py

@@ -1946,7 +1946,9 @@ def _parse_group(
         "findingId": _required_string(group, "findingId", label),
         "summary": _required_string(group, "summary", label),
         "category": _required_string(group, "category", label),
-        "ticketIds": _string_array(group.get("ticketIds"), f"{label}.ticketIds"),
+        "ticketIds": _string_array_allow_empty(
+            group.get("ticketIds"), f"{label}.ticketIds"
+        ),
         "originWorker": origin,
         "originEvidence": origin_evidence,
         "discoveredBy": discovered_by,

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -24,11 +24,12 @@ from .dispatch_state import (
     resolve_project_path as _resolve_project_path,
     resolve_required_path as _resolve_required_path,
     set_dispatch_mode as _set_dispatch_mode,
-    set_worker_status as _set_worker_status,
+    transition_worker_status as _transition_worker_status,
     string_list as _string_list,
     string_value as _string_value,
     utc_now as _utc_now,
-    validate_initial_prompts as _validate_initial_prompts,
+    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,
@@ -160,7 +161,7 @@ def build_dispatch_plan(
     )
     if jobs_file:
         jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options)
-        _validate_initial_prompts(manifest, jobs)
+        _validate_dispatch_prompts(manifest, active_context, jobs)
     else:
         jobs = _jobs_from_roster(
             project_root,
@@ -389,55 +390,22 @@ def _jobs_from_file(
 ) -> list[WorkerJob]:
     if jobs_file is None:
         return []
-    payload = _load_json_object(_resolve_project_path(project_root, str(jobs_file)), "jobs file")
-    dispatch_kind = _string_value(payload.get("dispatchKind")) or options.dispatch_kind
-    workers = payload.get("workers")
-    if not isinstance(workers, list):
-        raise DispatchError("jobs file workers must be an array")
-    return [
-        _job_from_file_worker(project_root, workspace_root, item, options, dispatch_kind)
-        for item in workers
-        if isinstance(item, dict)
-    ]
-
-
-def _job_from_file_worker(
-    project_root: Path,
-    workspace_root: Path,
-    item: Mapping[str, Any],
-    options: _BuildOptions,
-    dispatch_kind: str,
-) -> WorkerJob:
-    worker_id = _require_string(item, "workerId")
-    provider = _provider_for_job(item, worker_id)
-    prompt_path = _resolve_project_path(project_root, _require_string(item, "promptPath"))
-    result_path = _resolve_project_path(project_root, _require_string(item, "resultPath"))
-    worker_result_path = _resolve_project_path(project_root, _require_string(item, "workerResultPath"))
-    completion_paths = tuple(
-        _resolve_project_path(project_root, path)
-        for path in _string_list(item.get("completionPaths"))
-    ) or (result_path,)
-    return WorkerJob(
-        worker_id=worker_id,
-        provider=provider,
+    return _worker_jobs_from_file(
+        project_root,
+        jobs_file,
         backend=options.default_backend,
-        project_root=project_root,
-        model_execution_value=_require_string(item, "modelExecutionValue"),
-        wrapper_path=_resolve_wrapper(provider, workspace_root, options),
-        prompt_path=prompt_path,
-        result_path=result_path,
-        worker_result_path=worker_result_path,
-        completion_paths=completion_paths,
-        worktree_path=_string_value(item.get("worktreePath")),
-        role=_require_string(item, "role"),
         idle_timeout_seconds=options.idle_timeout_seconds,
-        dispatch_kind=dispatch_kind,
+        default_dispatch_kind=options.dispatch_kind,
+        resolve_wrapper=lambda provider: _resolve_wrapper(
+            provider, workspace_root, options
+        ),
+        default_provider=_provider_for_worker,
     )
 
 
 def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle:
-    _set_worker_status(
-        plan.team_state_path, job.worker_id, "running", "",
+    _transition_worker_status(
+        plan.team_state_path, job.worker_id, "in-progress", "",
         model_execution_value=job.model_execution_value,
     )
     handle = _start_job(plan, job)
@@ -544,13 +512,15 @@ def _retry_from_record(
 
 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:
-        _set_worker_status(plan.team_state_path, job.worker_id, "completed", "")
+        _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))
         return
     reason = _failure_reason(outcome)
     status = "timeout" if outcome.timeout else "error"
-    _set_worker_status(plan.team_state_path, job.worker_id, status, reason)
+    _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)
     _append_event(plan, "worker-failed", _failure_details(job, attempt, outcome, reason))
 
@@ -643,7 +613,7 @@ def _mark_roster_skips(
         return
     team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
     for worker_id, reason in reasons.items():
-        _set_worker_status(team_state_path, worker_id, "not-run", reason)
+        _transition_worker_status(team_state_path, worker_id, "not-run", reason)
 
 
 def _skip_reasons(
@@ -801,13 +771,6 @@ def _provider_for_worker(worker_id: str) -> str:
     return worker_id
 
 
-def _provider_for_job(item: Mapping[str, Any], worker_id: str) -> str:
-    provider = _string_value(item.get("provider"))
-    if provider:
-        return provider
-    return _provider_for_worker(worker_id)
-
-
 def _model_for_worker(worker_id: str, state: Mapping[str, Any], report_writer_model: str) -> str:
     if worker_id == REPORT_WRITER_WORKER_ID and report_writer_model.strip():
         return report_writer_model.strip()

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -22,9 +22,13 @@ import os
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, Mapping, Sequence
+from typing import Any, Callable, Mapping, Sequence
 
-from .worker_prompt_contract import PromptRecord, validate_initial_prompt_records
+from .worker_prompt_contract import (
+    PromptRecord,
+    validate_initial_prompt_records,
+    validate_reverify_prompt,
+)
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
 BACKEND_TMUX_PANE = "tmux-pane"
@@ -35,6 +39,10 @@ BACKEND_MIXED = "mixed"
 # analysis phases write their artifacts under project-root (see the contract in
 # scripts/okstra-codex-exec.sh).
 WORKTREE_TASK_TYPES = frozenset({"implementation", "final-verification"})
+WORKER_STATUSES = frozenset(
+    {"in-progress", "completed", "timeout", "error", "not-run"}
+)
+REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
 
 
 class DispatchError(Exception):
@@ -171,14 +179,24 @@ def worker_state(team_state: Mapping[str, Any], worker_id: str) -> Mapping[str,
     raise DispatchError(f"team-state has no workerId={worker_id}")
 
 
-def set_worker_status(
+def transition_worker_status(
     team_state_path: Path,
     worker_id: str,
     status: str,
     reason: str,
     *,
     model_execution_value: str = "",
+    at: str | datetime | None = None,
 ) -> None:
+    if status not in WORKER_STATUSES:
+        allowed = ", ".join(sorted(WORKER_STATUSES))
+        raise DispatchError(
+            f"unsupported worker status `{status}`; expected one of: {allowed}"
+        )
+    reason = reason.strip()
+    if status in REASON_REQUIRED_STATUSES and not reason:
+        raise DispatchError(f"worker status `{status}` requires a non-empty reason")
+    timestamp = _utc_timestamp(at)
     payload = load_json_object(team_state_path, "team-state")
     workers = payload.get("workers")
     if not isinstance(workers, list):
@@ -187,6 +205,14 @@ def set_worker_status(
         if isinstance(worker, dict) and worker.get("workerId") == worker_id:
             worker["status"] = status
             worker["reason"] = reason
+            if status == "in-progress":
+                worker["startedAt"] = timestamp
+                worker.pop("endedAt", None)
+            elif status == "not-run":
+                worker.pop("startedAt", None)
+                worker.pop("endedAt", None)
+            else:
+                worker["endedAt"] = timestamp
             if model_execution_value:
                 worker["model"] = model_execution_value
                 worker["modelExecutionValue"] = model_execution_value
@@ -195,6 +221,23 @@ def set_worker_status(
     raise DispatchError(f"team-state has no workerId={worker_id}: {team_state_path}")
 
 
+def _utc_timestamp(value: str | datetime | None) -> str:
+    if value is None:
+        instant = datetime.now(timezone.utc)
+    elif isinstance(value, datetime):
+        instant = value
+    elif isinstance(value, str):
+        try:
+            instant = datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except ValueError as exc:
+            raise DispatchError(f"invalid UTC timestamp `{value}`") from exc
+    else:
+        raise DispatchError(f"invalid UTC timestamp `{value}`")
+    if instant.tzinfo is None or instant.utcoffset() != timezone.utc.utcoffset(instant):
+        raise DispatchError(f"invalid UTC timestamp `{value}`")
+    return instant.astimezone(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
 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
@@ -227,5 +270,126 @@ def validate_initial_prompts(
         raise DispatchError(f"{task_type} prompt contract: " + "; ".join(errors))
 
 
+def validate_dispatch_prompts(
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    jobs: Sequence[WorkerJob],
+) -> None:
+    initial_jobs = [
+        job for job in jobs if not job.dispatch_kind.startswith("reverify-r")
+    ]
+    if initial_jobs:
+        validate_initial_prompts(manifest, initial_jobs)
+
+    reverify_jobs = [
+        job for job in jobs if job.dispatch_kind.startswith("reverify-r")
+    ]
+    if not reverify_jobs:
+        return
+    task_type = require_string(manifest, "taskType")
+    workflow = active_context.get("workflow")
+    if not isinstance(workflow, Mapping):
+        raise DispatchError("reverify prompt contract: active run workflow is missing")
+    forbidden_actions = string_value(workflow.get("forbiddenActions"))
+    if not forbidden_actions:
+        raise DispatchError(
+            "reverify prompt contract: workflow.forbiddenActions is missing"
+        )
+
+    errors: list[str] = []
+    for job in reverify_jobs:
+        try:
+            text = job.prompt_path.read_text(encoding="utf-8")
+        except OSError as exc:
+            errors.append(f"{job.worker_id}: cannot read prompt {job.prompt_path}: {exc}")
+            continue
+        errors.extend(
+            f"{job.worker_id}: {error}"
+            for error in validate_reverify_prompt(
+                text,
+                task_type=task_type,
+                forbidden_actions=forbidden_actions,
+            )
+        )
+    if errors:
+        raise DispatchError("reverify prompt contract: " + "; ".join(errors))
+
+
+def worker_jobs_from_file(
+    project_root: Path,
+    jobs_file: Path,
+    *,
+    backend: str,
+    idle_timeout_seconds: int,
+    default_dispatch_kind: str,
+    resolve_wrapper: Callable[[str], Path],
+    default_provider: Callable[[str], str],
+) -> list[WorkerJob]:
+    payload = load_json_object(
+        resolve_project_path(project_root, str(jobs_file)),
+        "jobs file",
+    )
+    dispatch_kind = string_value(payload.get("dispatchKind")) or default_dispatch_kind
+    workers = payload.get("workers")
+    if not isinstance(workers, list):
+        raise DispatchError("jobs file workers must be an array")
+    return [
+        _worker_job_from_file(
+            project_root,
+            item,
+            backend=backend,
+            idle_timeout_seconds=idle_timeout_seconds,
+            dispatch_kind=dispatch_kind,
+            resolve_wrapper=resolve_wrapper,
+            default_provider=default_provider,
+        )
+        for item in workers
+        if isinstance(item, Mapping)
+    ]
+
+
+def _worker_job_from_file(
+    project_root: Path,
+    item: Mapping[str, Any],
+    *,
+    backend: str,
+    idle_timeout_seconds: int,
+    dispatch_kind: str,
+    resolve_wrapper: Callable[[str], Path],
+    default_provider: Callable[[str], str],
+) -> WorkerJob:
+    worker_id = require_string(item, "workerId")
+    provider = string_value(item.get("provider")) or default_provider(worker_id)
+    prompt_path = resolve_project_path(
+        project_root, require_string(item, "promptPath")
+    )
+    result_path = resolve_project_path(
+        project_root, require_string(item, "resultPath")
+    )
+    worker_result_path = resolve_project_path(
+        project_root, require_string(item, "workerResultPath")
+    )
+    completion_paths = tuple(
+        resolve_project_path(project_root, path)
+        for path in string_list(item.get("completionPaths"))
+    ) or (result_path,)
+    return WorkerJob(
+        worker_id=worker_id,
+        provider=provider,
+        backend=backend,
+        project_root=project_root,
+        model_execution_value=require_string(item, "modelExecutionValue"),
+        wrapper_path=resolve_wrapper(provider),
+        prompt_path=prompt_path,
+        result_path=result_path,
+        worker_result_path=worker_result_path,
+        completion_paths=completion_paths,
+        worktree_path=string_value(item.get("worktreePath")),
+        role=require_string(item, "role"),
+        idle_timeout_seconds=idle_timeout_seconds,
+        dispatch_kind=dispatch_kind,
+    )
+
+
 def utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")