okstra 0.145.0 → 0.146.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/docs/architecture.md +4 -2
  2. package/docs/cli.md +15 -5
  3. package/docs/project-structure-overview.md +3 -5
  4. package/package.json +1 -1
  5. package/runtime/BUILD.json +2 -2
  6. package/runtime/agents/workers/report-writer-worker.md +5 -6
  7. package/runtime/bin/okstra-trace-cleanup.sh +28 -2
  8. package/runtime/prompts/lead/adapters/claude-code.md +3 -3
  9. package/runtime/prompts/lead/convergence.md +20 -3
  10. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  11. package/runtime/prompts/lead/report-writer.md +20 -14
  12. package/runtime/prompts/lead/team-contract.md +3 -3
  13. package/runtime/python/okstra_ctl/analysis_packet.py +4 -10
  14. package/runtime/python/okstra_ctl/codex_dispatch.py +117 -58
  15. package/runtime/python/okstra_ctl/convergence_engine.py +3 -1
  16. package/runtime/python/okstra_ctl/dispatch_core.py +19 -56
  17. package/runtime/python/okstra_ctl/dispatch_state.py +167 -3
  18. package/runtime/python/okstra_ctl/path_hints.py +6 -0
  19. package/runtime/python/okstra_ctl/paths.py +7 -44
  20. package/runtime/python/okstra_ctl/render.py +2 -0
  21. package/runtime/python/okstra_ctl/wizard.py +34 -0
  22. package/runtime/python/okstra_ctl/worker_liveness.py +84 -21
  23. package/runtime/python/okstra_ctl/worker_prompt_body.py +24 -4
  24. package/runtime/python/okstra_ctl/worker_prompt_contract.py +57 -0
  25. package/runtime/python/okstra_ctl/worker_state.py +65 -0
  26. package/runtime/python/okstra_token_usage/antigravity.py +3 -0
  27. package/runtime/python/okstra_token_usage/codex.py +54 -23
  28. package/runtime/python/okstra_token_usage/collect.py +141 -33
  29. package/runtime/python/okstra_token_usage/paths.py +27 -0
  30. package/runtime/python/okstra_vendor/__init__.py +15 -2
  31. package/runtime/schemas/convergence-groups-v1.0.schema.json +0 -1
  32. package/runtime/skills/okstra-run/SKILL.md +14 -4
  33. package/runtime/skills/okstra-setup/references/project-config.md +13 -4
  34. package/runtime/validators/lib/fixtures.sh +1 -1
  35. package/runtime/validators/validate-run.py +52 -1
  36. package/runtime/validators/validate_analysis_report.py +34 -3
  37. package/src/cli-registry.mjs +7 -10
  38. package/src/commands/execute/worker-state.mjs +29 -0
  39. package/src/commands/inspect/worker-liveness.mjs +5 -3
  40. package/src/commands/lifecycle/preflight.mjs +13 -3
  41. package/src/lib/runtime-readiness.mjs +90 -0
  42. package/runtime/python/okstra_ctl/phase_cleanup.py +0 -235
  43. package/src/commands/execute/phase-cleanup.mjs +0 -38
@@ -130,9 +130,9 @@ Each probe matches exactly one dispatch backend. The dispatch record's `liveness
130
130
  | Worker | Backend | Flag | What it reads |
131
131
  |---|---|---|---|
132
132
  | any in-process worker (including `claude-worker` and `report-writer-worker`) | in-process dispatch | `--audit` | its registered audit sidecar's newest `- PROGRESS:` heartbeat |
133
- | `codex-worker` / `antigravity-worker` | CLI wrapper | `--prompt` | `<prompt>.log` / `<prompt>.status.json` |
133
+ | `codex-worker` / `antigravity-worker` | CLI wrapper | `--team-state <path> --worker <id>` | the worker's persisted `promptPath` and `startedAt`, then `<prompt>.log` / `<prompt>.status.json` |
134
134
 
135
- The mismatch is not intermittent, it is guaranteed: only the `okstra-*-exec.sh` wrappers ever write `<prompt>.log` / `<prompt>.status.json`, so an in-process worker produces neither by construction. Probing an in-process worker with `--prompt` therefore reports `did-not-launch` for a worker that is running normally, every time, as soon as the 60s launch grace passes. Probe in-process workers with `--audit`.
135
+ The mismatch is not intermittent, it is guaranteed: only the `okstra-*-exec.sh` wrappers ever write `<prompt>.log` / `<prompt>.status.json`, so an in-process worker produces neither by construction. Probe in-process workers with `--audit`; use the paired `--team-state` / `--worker` selector only for a wrapper assignment. Its launch grace begins at the atomic `in-progress` transition's `startedAt`, never at prompt-materialization time.
136
136
 
137
137
  This is a transport-adapter liveness choice only. It does not change the reducer's worker identity or its verification responsibility: both remain bound to the registered worker instance and canonical artifacts.
138
138
 
@@ -147,7 +147,7 @@ After each worker subagent returns (regardless of role), Lead MUST verify the ca
147
147
  - The wrapper subagent returned an explicit `*_RESULT_MISSING` sentinel (codex-worker / antigravity-worker step 8c — `CODEX_RESULT_MISSING` / `ANTIGRAVITY_RESULT_MISSING`).
148
148
  - The result file is absent at the resolved absolute path even though the worker returned without a `*_RESULT_MISSING` sentinel — for example, claude-worker returned its final assistant message but never persisted the artifact, or the wrapper exited 0 and the codex/antigravity sub-agent forwarded raw stdout despite the contract.
149
149
  - The result file exists but cannot be parsed (frontmatter unreadable, sections 1–5 entirely missing). A truncated file in the middle of section 5 is NOT covered here — it goes to the validator's regular `error` path, not the retry path.
150
- - `okstra worker-liveness --prompt` reports a **CLI-wrapper** worker (`codex` / `antigravity`) `did-not-launch` — neither `<prompt-path>.log` nor `<prompt-path>.status.json` exists past the launch grace (default 60s). The wrapper writes its status sidecar before invoking the CLI and hard-fails loudly with a distinct exit code on every argument check before that, so the absence of BOTH artifacts means the dispatch itself never reached the script. Without this trigger the only evidence was a lead noticing two missing files by eye, and the run paid the full polling cap for a worker that never started.
150
+ - `okstra worker-liveness --team-state <path> --worker <id>` reports a **CLI-wrapper** worker (`codex` / `antigravity`) `did-not-launch` — neither `<prompt-path>.log` nor `<prompt-path>.status.json` exists after the persisted `startedAt` plus the launch grace (default 60s). The wrapper writes its status sidecar before invoking the CLI and hard-fails loudly with a distinct exit code on every argument check before that, so the absence of BOTH artifacts means the dispatch itself never reached the script. Without this trigger the only evidence was a lead noticing two missing files by eye, and the run paid the full polling cap for a worker that never started.
151
151
  - `okstra worker-liveness --audit` reports an **in-process** worker `stalled` — its registered audit sidecar's newest `- PROGRESS:` heartbeat is older than the cadence budget, or the sidecar carries no heartbeat at all. This is the in-process equivalent of the CLI wrappers' idle watchdog: the wrapper reaps a silent CLI itself, but nothing reaped a silent in-process worker until its deadline.
152
152
  - The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
153
153
 
@@ -20,7 +20,7 @@ BRIEF_SECTIONS = (
20
20
  "Task Continuity Notes",
21
21
  "Available MCP Servers",
22
22
  )
23
- ERROR_ANALYSIS_BRIEF_SECTIONS = (
23
+ CANONICAL_BRIEF_SECTIONS = (
24
24
  "Source Material",
25
25
  "Context",
26
26
  "Problem / Symptom",
@@ -38,9 +38,6 @@ ERROR_ANALYSIS_BRIEF_SECTIONS = (
38
38
  "Reporter Confirmations",
39
39
  "Augmentation",
40
40
  ) + BRIEF_SECTIONS
41
- BRIEF_SECTIONS_BY_TASK_TYPE = {
42
- "error-analysis": ERROR_ANALYSIS_BRIEF_SECTIONS,
43
- }
44
41
  PROFILE_SECTIONS = (
45
42
  "Primary focus areas",
46
43
  "Expected output emphasis",
@@ -101,7 +98,7 @@ def build_analysis_packet(
101
98
  bool(clarification_response_path),
102
99
  )
103
100
  )
104
- parts.extend(_brief_block(task_type, brief_text))
101
+ parts.extend(_brief_block(brief_text))
105
102
  parts.extend(_profile_block(task_type, profile_text))
106
103
  parts.extend(_reference_block(reference_text))
107
104
  parts.extend(_fix_history_block(fix_history_text))
@@ -160,15 +157,12 @@ def _intro_block(
160
157
  return lines
161
158
 
162
159
 
163
- def _brief_block(task_type: str, brief_text: str) -> list[str]:
160
+ def _brief_block(brief_text: str) -> list[str]:
164
161
  return [
165
162
  "",
166
163
  "## Task-Specific Brief Extract",
167
164
  "",
168
- _extract_sections(
169
- brief_text,
170
- BRIEF_SECTIONS_BY_TASK_TYPE.get(task_type, BRIEF_SECTIONS),
171
- ),
165
+ _extract_sections(brief_text, CANONICAL_BRIEF_SECTIONS),
172
166
  ]
173
167
 
174
168
 
@@ -43,10 +43,12 @@ from .dispatch_state import (
43
43
  resolve_project_path as _resolve_project_path,
44
44
  resolve_required_path as _resolve_required_path,
45
45
  set_dispatch_mode as _set_dispatch_mode,
46
- set_worker_status as _set_worker_status,
47
46
  string_list as _string_list,
48
47
  string_value as _string_value,
48
+ transition_worker_status as _transition_worker_status,
49
49
  utc_now as _utc_now,
50
+ validate_dispatch_prompts as _validate_dispatch_prompts,
51
+ worker_jobs_from_file as _worker_jobs_from_file,
50
52
  worker_state as _worker_state,
51
53
  worktree_path as _worktree_path,
52
54
  write_json as _write_json,
@@ -120,33 +122,46 @@ def build_dispatch_plan(
120
122
  idle_timeout_seconds: int = 600,
121
123
  enable_codex_report_writer: bool = False,
122
124
  report_writer_codex_model: str = "",
125
+ dispatch_kind: str = "initial",
126
+ jobs_file: Path | None = None,
123
127
  ) -> DispatchPlan:
124
128
  inputs = _load_dispatch_inputs(
125
129
  project_root,
126
130
  run_manifest_path,
127
131
  requested_workers,
128
132
  enable_codex_report_writer=enable_codex_report_writer,
133
+ select_roster=jobs_file is None,
129
134
  )
130
- worker_requests, prompt_paths = _materialize_selected_worker_prompts(
131
- project_root=inputs.project_root,
132
- manifest_path=inputs.manifest_path,
133
- workspace_root=workspace_root,
134
- team_state=inputs.team_state,
135
- selected_workers=inputs.selected_workers,
136
- report_writer_codex_model=report_writer_codex_model,
137
- )
138
- workers = _build_selected_worker_dispatches(
139
- project_root=inputs.project_root,
140
- manifest=inputs.manifest,
141
- team_state=inputs.team_state,
142
- active_context=inputs.active_context,
143
- workspace_root=workspace_root,
144
- okstra_bin=okstra_bin,
145
- idle_timeout_seconds=idle_timeout_seconds,
146
- selected_workers=inputs.selected_workers,
147
- worker_requests=worker_requests,
148
- prompt_paths=prompt_paths,
149
- )
135
+ if jobs_file is not None:
136
+ workers = _codex_jobs_from_file(
137
+ inputs,
138
+ jobs_file,
139
+ workspace_root=workspace_root,
140
+ okstra_bin=okstra_bin,
141
+ idle_timeout_seconds=idle_timeout_seconds,
142
+ dispatch_kind=dispatch_kind,
143
+ )
144
+ else:
145
+ worker_requests, prompt_paths = _materialize_selected_worker_prompts(
146
+ project_root=inputs.project_root,
147
+ manifest_path=inputs.manifest_path,
148
+ workspace_root=workspace_root,
149
+ team_state=inputs.team_state,
150
+ selected_workers=inputs.selected_workers,
151
+ report_writer_codex_model=report_writer_codex_model,
152
+ )
153
+ workers = _build_selected_worker_dispatches(
154
+ project_root=inputs.project_root,
155
+ manifest=inputs.manifest,
156
+ team_state=inputs.team_state,
157
+ active_context=inputs.active_context,
158
+ workspace_root=workspace_root,
159
+ okstra_bin=okstra_bin,
160
+ idle_timeout_seconds=idle_timeout_seconds,
161
+ selected_workers=inputs.selected_workers,
162
+ worker_requests=worker_requests,
163
+ prompt_paths=prompt_paths,
164
+ )
150
165
  return DispatchPlan(
151
166
  project_root=inputs.project_root,
152
167
  workspace_root=workspace_root,
@@ -158,36 +173,68 @@ def build_dispatch_plan(
158
173
  )
159
174
 
160
175
 
176
+ def _codex_jobs_from_file(
177
+ inputs: _DispatchInputs,
178
+ jobs_file: Path,
179
+ *,
180
+ workspace_root: Path,
181
+ okstra_bin: Path | None,
182
+ idle_timeout_seconds: int,
183
+ dispatch_kind: str,
184
+ ) -> list[WorkerJob]:
185
+ workers = _worker_jobs_from_file(
186
+ inputs.project_root,
187
+ jobs_file,
188
+ backend=BACKEND_CLI_WRAPPER,
189
+ idle_timeout_seconds=idle_timeout_seconds,
190
+ default_dispatch_kind=dispatch_kind,
191
+ resolve_wrapper=lambda provider: _resolve_wrapper(
192
+ provider, workspace_root, okstra_bin
193
+ ),
194
+ default_provider=lambda worker_id: (
195
+ "codex" if worker_id == REPORT_WRITER_WORKER_ID else worker_id
196
+ ),
197
+ )
198
+ _validate_dispatch_prompts(inputs.manifest, inputs.active_context, workers)
199
+ return workers
200
+
201
+
161
202
  def _load_dispatch_inputs(
162
203
  project_root: Path,
163
204
  run_manifest_path: Path,
164
205
  requested_workers: Sequence[str],
165
206
  *,
166
207
  enable_codex_report_writer: bool,
208
+ select_roster: bool = True,
167
209
  ) -> _DispatchInputs:
168
210
  project_root = project_root.resolve()
169
211
  manifest_path = _resolve_project_path(project_root, str(run_manifest_path))
170
212
  manifest = _load_json_object(manifest_path, "run manifest")
171
213
  _validate_codex_manifest(manifest, manifest_path)
172
- selected_workers = tuple(
173
- _select_workers(
174
- manifest,
175
- requested_workers,
176
- enable_codex_report_writer=enable_codex_report_writer,
214
+ selected_workers = (
215
+ tuple(
216
+ _select_workers(
217
+ manifest,
218
+ requested_workers,
219
+ enable_codex_report_writer=enable_codex_report_writer,
220
+ )
177
221
  )
222
+ if select_roster
223
+ else ()
178
224
  )
179
225
  team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
180
226
  team_state = _load_json_object(team_state_path, "team-state")
181
- _mark_skipped_workers(
182
- team_state_path,
183
- team_state,
184
- _skipped_worker_reasons(
185
- manifest,
186
- selected_workers,
187
- requested_workers,
188
- enable_codex_report_writer=enable_codex_report_writer,
189
- ),
190
- )
227
+ if select_roster:
228
+ _mark_skipped_workers(
229
+ team_state_path,
230
+ team_state,
231
+ _skipped_worker_reasons(
232
+ manifest,
233
+ selected_workers,
234
+ requested_workers,
235
+ enable_codex_report_writer=enable_codex_report_writer,
236
+ ),
237
+ )
191
238
  active_context = _load_optional_json_object(
192
239
  _resolve_optional_path(project_root, manifest.get("activeRunContextPath"))
193
240
  )
@@ -276,13 +323,6 @@ def _build_selected_worker_dispatches(
276
323
  def dispatch_plan(plan: DispatchPlan) -> int:
277
324
  _set_dispatch_mode(plan.team_state_path, _dispatch_mode(plan.workers))
278
325
  for worker in plan.workers:
279
- _set_worker_status(
280
- plan.team_state_path,
281
- worker.worker_id,
282
- "running",
283
- "",
284
- model_execution_value=worker.model_execution_value,
285
- )
286
326
  completed = _dispatch_worker_with_retry(plan, worker)
287
327
  if completed == 0:
288
328
  continue
@@ -292,6 +332,13 @@ def dispatch_plan(plan: DispatchPlan) -> int:
292
332
 
293
333
  def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
294
334
  for attempt in range(1, MAX_WORKER_ATTEMPTS + 1):
335
+ _transition_worker_status(
336
+ plan.team_state_path,
337
+ worker.worker_id,
338
+ "in-progress",
339
+ "",
340
+ model_execution_value=worker.model_execution_value,
341
+ )
295
342
  _record_worker_attempt(plan, worker, attempt, "running")
296
343
  attempt_details = _attempt_event_details(worker, attempt)
297
344
  _append_event(plan, "worker-dispatched", attempt_details)
@@ -301,7 +348,9 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
301
348
  post_process = _post_process_report_writer_result(plan, worker)
302
349
  if not post_process["ok"]:
303
350
  reason = _require_string(post_process, "reason")
304
- _set_worker_status(plan.team_state_path, worker.worker_id, "error", reason)
351
+ _transition_worker_status(
352
+ plan.team_state_path, worker.worker_id, "error", reason
353
+ )
305
354
  _record_worker_attempt(plan, worker, attempt, "error", reason)
306
355
  details = {
307
356
  **attempt_details,
@@ -312,7 +361,9 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
312
361
  }
313
362
  _append_event(plan, "worker-failed", details)
314
363
  return 1
315
- _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
364
+ _transition_worker_status(
365
+ plan.team_state_path, worker.worker_id, "completed", ""
366
+ )
316
367
  _record_worker_attempt(plan, worker, attempt, "completed")
317
368
  details = {
318
369
  **attempt_details,
@@ -338,7 +389,9 @@ def _dispatch_worker_with_retry(plan: DispatchPlan, worker: WorkerJob) -> int:
338
389
  continue
339
390
 
340
391
  reason = _failure_reason(result.returncode, missing_paths)
341
- _set_worker_status(plan.team_state_path, worker.worker_id, "error", reason)
392
+ _transition_worker_status(
393
+ plan.team_state_path, worker.worker_id, "error", reason
394
+ )
342
395
  _record_worker_attempt(plan, worker, attempt, "error", reason)
343
396
  details = {
344
397
  **attempt_details,
@@ -378,7 +431,7 @@ def _matches_worker_attempt(
378
431
  return (
379
432
  isinstance(record, dict)
380
433
  and record.get("workerId") == worker.worker_id
381
- and record.get("kind") == "initial"
434
+ and record.get("kind") == worker.dispatch_kind
382
435
  and record.get("attempt") == attempt
383
436
  )
384
437
 
@@ -386,14 +439,13 @@ def _matches_worker_attempt(
386
439
  def _worker_dispatch_record(
387
440
  worker: WorkerJob, attempt: int, status: str, reason: str
388
441
  ) -> dict[str, Any]:
389
- provider = "codex" if worker.worker_id == REPORT_WRITER_WORKER_ID else worker.worker_id
390
442
  return {
391
443
  "workerId": worker.worker_id,
392
444
  "role": worker.role,
393
- "kind": "initial",
445
+ "kind": worker.dispatch_kind,
394
446
  "attempt": attempt,
395
447
  "backendType": worker.backend,
396
- "provider": provider,
448
+ "provider": worker.provider,
397
449
  "status": status,
398
450
  "paneId": "",
399
451
  "promptPath": str(worker.prompt_path),
@@ -410,6 +462,8 @@ def main(argv: Sequence[str] | None = None) -> int:
410
462
  parser = _parser()
411
463
  args = parser.parse_args(argv)
412
464
  try:
465
+ if args.jobs_file and args.workers:
466
+ raise DispatchError("--jobs-file and --workers cannot be combined")
413
467
  idle_timeout_seconds = _parse_idle_timeout(args.idle_timeout_seconds)
414
468
  plan = build_dispatch_plan(
415
469
  project_root=Path(args.project_root),
@@ -420,6 +474,8 @@ def main(argv: Sequence[str] | None = None) -> int:
420
474
  idle_timeout_seconds=idle_timeout_seconds,
421
475
  enable_codex_report_writer=args.enable_codex_report_writer,
422
476
  report_writer_codex_model=args.report_writer_codex_model,
477
+ dispatch_kind=args.dispatch_kind,
478
+ jobs_file=Path(args.jobs_file) if args.jobs_file else None,
423
479
  )
424
480
  if args.dry_run:
425
481
  _print_json(plan.to_payload(dry_run=True))
@@ -446,6 +502,8 @@ def _parser() -> argparse.ArgumentParser:
446
502
  parser.add_argument("--idle-timeout-seconds", default="600")
447
503
  parser.add_argument("--enable-codex-report-writer", action="store_true")
448
504
  parser.add_argument("--report-writer-codex-model", default="")
505
+ parser.add_argument("--dispatch-kind", default="initial")
506
+ parser.add_argument("--jobs-file", default="")
449
507
  return parser
450
508
 
451
509
 
@@ -672,7 +730,6 @@ def _mark_skipped_workers(
672
730
  workers = team_state.get("workers")
673
731
  if not isinstance(workers, list):
674
732
  raise DispatchError(f"team-state workers must be an array: {team_state_path}")
675
- changed = False
676
733
  for worker in workers:
677
734
  if not isinstance(worker, dict):
678
735
  continue
@@ -683,11 +740,9 @@ def _mark_skipped_workers(
683
740
  status = _string_value(worker.get("status")) or "not-run"
684
741
  current_reason = _string_value(worker.get("reason"))
685
742
  if status == "not-run" and not current_reason:
686
- worker["status"] = "not-run"
687
- worker["reason"] = reason
688
- changed = True
689
- if changed:
690
- _write_json(team_state_path, dict(team_state))
743
+ _transition_worker_status(
744
+ team_state_path, worker_id, "not-run", reason
745
+ )
691
746
 
692
747
 
693
748
  def _resolve_wrapper(
@@ -695,7 +750,9 @@ def _resolve_wrapper(
695
750
  workspace_root: Path,
696
751
  okstra_bin: Path | None,
697
752
  ) -> Path:
698
- script = SUPPORTED_CLI_WORKERS[worker_id]
753
+ script = SUPPORTED_CLI_WORKERS.get(worker_id)
754
+ if script is None:
755
+ raise DispatchError(f"unsupported worker provider: {worker_id}")
699
756
  candidates = []
700
757
  if okstra_bin is not None:
701
758
  candidates.append(okstra_bin / script)
@@ -759,7 +816,9 @@ def _post_process_report_writer_result(
759
816
  # validate-run reads team-state; the writer is done by the time its
760
817
  # artifacts pass the earlier steps.
761
818
  if step_name == STEP_VALIDATE_RUN:
762
- _set_worker_status(plan.team_state_path, worker.worker_id, "completed", "")
819
+ _transition_worker_status(
820
+ plan.team_state_path, worker.worker_id, "completed", ""
821
+ )
763
822
 
764
823
  return run_finalize(ctx, before_step=settle_before)
765
824
 
@@ -1946,7 +1946,9 @@ def _parse_group(
1946
1946
  "findingId": _required_string(group, "findingId", label),
1947
1947
  "summary": _required_string(group, "summary", label),
1948
1948
  "category": _required_string(group, "category", label),
1949
- "ticketIds": _string_array(group.get("ticketIds"), f"{label}.ticketIds"),
1949
+ "ticketIds": _string_array_allow_empty(
1950
+ group.get("ticketIds"), f"{label}.ticketIds"
1951
+ ),
1950
1952
  "originWorker": origin,
1951
1953
  "originEvidence": origin_evidence,
1952
1954
  "discoveredBy": discovered_by,
@@ -24,11 +24,12 @@ from .dispatch_state import (
24
24
  resolve_project_path as _resolve_project_path,
25
25
  resolve_required_path as _resolve_required_path,
26
26
  set_dispatch_mode as _set_dispatch_mode,
27
- set_worker_status as _set_worker_status,
27
+ transition_worker_status as _transition_worker_status,
28
28
  string_list as _string_list,
29
29
  string_value as _string_value,
30
30
  utc_now as _utc_now,
31
- validate_initial_prompts as _validate_initial_prompts,
31
+ validate_dispatch_prompts as _validate_dispatch_prompts,
32
+ worker_jobs_from_file as _worker_jobs_from_file,
32
33
  worker_state as _worker_state,
33
34
  worktree_path as _worktree_path,
34
35
  write_json as _write_json,
@@ -160,7 +161,7 @@ def build_dispatch_plan(
160
161
  )
161
162
  if jobs_file:
162
163
  jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options)
163
- _validate_initial_prompts(manifest, jobs)
164
+ _validate_dispatch_prompts(manifest, active_context, jobs)
164
165
  else:
165
166
  jobs = _jobs_from_roster(
166
167
  project_root,
@@ -389,55 +390,22 @@ def _jobs_from_file(
389
390
  ) -> list[WorkerJob]:
390
391
  if jobs_file is None:
391
392
  return []
392
- payload = _load_json_object(_resolve_project_path(project_root, str(jobs_file)), "jobs file")
393
- dispatch_kind = _string_value(payload.get("dispatchKind")) or options.dispatch_kind
394
- workers = payload.get("workers")
395
- if not isinstance(workers, list):
396
- raise DispatchError("jobs file workers must be an array")
397
- return [
398
- _job_from_file_worker(project_root, workspace_root, item, options, dispatch_kind)
399
- for item in workers
400
- if isinstance(item, dict)
401
- ]
402
-
403
-
404
- def _job_from_file_worker(
405
- project_root: Path,
406
- workspace_root: Path,
407
- item: Mapping[str, Any],
408
- options: _BuildOptions,
409
- dispatch_kind: str,
410
- ) -> WorkerJob:
411
- worker_id = _require_string(item, "workerId")
412
- provider = _provider_for_job(item, worker_id)
413
- prompt_path = _resolve_project_path(project_root, _require_string(item, "promptPath"))
414
- result_path = _resolve_project_path(project_root, _require_string(item, "resultPath"))
415
- worker_result_path = _resolve_project_path(project_root, _require_string(item, "workerResultPath"))
416
- completion_paths = tuple(
417
- _resolve_project_path(project_root, path)
418
- for path in _string_list(item.get("completionPaths"))
419
- ) or (result_path,)
420
- return WorkerJob(
421
- worker_id=worker_id,
422
- provider=provider,
393
+ return _worker_jobs_from_file(
394
+ project_root,
395
+ jobs_file,
423
396
  backend=options.default_backend,
424
- project_root=project_root,
425
- model_execution_value=_require_string(item, "modelExecutionValue"),
426
- wrapper_path=_resolve_wrapper(provider, workspace_root, options),
427
- prompt_path=prompt_path,
428
- result_path=result_path,
429
- worker_result_path=worker_result_path,
430
- completion_paths=completion_paths,
431
- worktree_path=_string_value(item.get("worktreePath")),
432
- role=_require_string(item, "role"),
433
397
  idle_timeout_seconds=options.idle_timeout_seconds,
434
- dispatch_kind=dispatch_kind,
398
+ default_dispatch_kind=options.dispatch_kind,
399
+ resolve_wrapper=lambda provider: _resolve_wrapper(
400
+ provider, workspace_root, options
401
+ ),
402
+ default_provider=_provider_for_worker,
435
403
  )
436
404
 
437
405
 
438
406
  def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle:
439
- _set_worker_status(
440
- plan.team_state_path, job.worker_id, "running", "",
407
+ _transition_worker_status(
408
+ plan.team_state_path, job.worker_id, "in-progress", "",
441
409
  model_execution_value=job.model_execution_value,
442
410
  )
443
411
  handle = _start_job(plan, job)
@@ -544,13 +512,15 @@ def _retry_from_record(
544
512
 
545
513
  def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> None:
546
514
  if outcome.returncode == 0 and not outcome.missing_completion_paths and not outcome.timeout:
547
- _set_worker_status(plan.team_state_path, job.worker_id, "completed", "")
515
+ _transition_worker_status(
516
+ plan.team_state_path, job.worker_id, "completed", ""
517
+ )
548
518
  _update_dispatch_status(plan.team_state_path, job.worker_id, job.dispatch_kind, attempt, "completed", "")
549
519
  _append_event(plan, "worker-result-collected", _result_details(job, attempt, outcome))
550
520
  return
551
521
  reason = _failure_reason(outcome)
552
522
  status = "timeout" if outcome.timeout else "error"
553
- _set_worker_status(plan.team_state_path, job.worker_id, status, reason)
523
+ _transition_worker_status(plan.team_state_path, job.worker_id, status, reason)
554
524
  _update_dispatch_status(plan.team_state_path, job.worker_id, job.dispatch_kind, attempt, status, reason)
555
525
  _append_event(plan, "worker-failed", _failure_details(job, attempt, outcome, reason))
556
526
 
@@ -643,7 +613,7 @@ def _mark_roster_skips(
643
613
  return
644
614
  team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
645
615
  for worker_id, reason in reasons.items():
646
- _set_worker_status(team_state_path, worker_id, "not-run", reason)
616
+ _transition_worker_status(team_state_path, worker_id, "not-run", reason)
647
617
 
648
618
 
649
619
  def _skip_reasons(
@@ -801,13 +771,6 @@ def _provider_for_worker(worker_id: str) -> str:
801
771
  return worker_id
802
772
 
803
773
 
804
- def _provider_for_job(item: Mapping[str, Any], worker_id: str) -> str:
805
- provider = _string_value(item.get("provider"))
806
- if provider:
807
- return provider
808
- return _provider_for_worker(worker_id)
809
-
810
-
811
774
  def _model_for_worker(worker_id: str, state: Mapping[str, Any], report_writer_model: str) -> str:
812
775
  if worker_id == REPORT_WRITER_WORKER_ID and report_writer_model.strip():
813
776
  return report_writer_model.strip()