okstra 0.145.0 → 0.146.1

package/runtime/prompts/lead/report-writer.md

@@ -4,7 +4,7 @@
 
 The final-report data.json is authored by `Report writer worker` when that role is in the roster. The lead reviews both rendered artifacts but does not write them. Lead-authored fallback is legal only after a real `dispatch_worker` attempt records `error`, `timeout`, or `not-run` with a concrete reason. `release-handoff` remains the intentional single-lead exception.
 
-The JSON SSOT path is `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json`. The user-facing markdown at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md` is produced by `scripts/okstra-render-final-report.py` from the data.json so both files land on disk before the worker returns.
+The JSON SSOT path is `runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json`. The user-facing markdown at `runs/<task-type>/reports/final-report-<task-type>-<seq>.md` is produced by `scripts/okstra-render-final-report.py` from the data.json. The worker-result pointer at `**Worker Result Path:**` records those two paths and the reconciled convergence input. These three completion artifacts land on disk before the worker returns; the heartbeat audit sidecar remains a separate required audit artifact.
 
 The data.json schema is `schemas/final-report-v1.0.schema.json`. The renderer + the run-validator both consume that schema, so a data.json that validates is guaranteed to render into a markdown that passes the contract checks.
 
@@ -12,7 +12,7 @@ Two `frontmatter` approval fields are always emitted with their unset default
 
 **As the report-writer worker:** YOU write the data.json and invoke the renderer; the files on disk are the canonical record, so do not return either artifact inline.
 
-**As the lead:** prepare the report-writer prompt, dispatch the Report writer worker per the Phase 6 dispatch template in okstra-lead-contract.md, and review both files in Phase 7. Do not call `write_artifact` against either report path yourself when Report writer worker is in the roster.
+**As the lead:** prepare the report-writer prompt, dispatch the Report writer worker per the Phase 6 dispatch template in okstra-lead-contract.md, and review the three completion artifacts plus the separate audit sidecar in Phase 7. Do not call `write_artifact` against the report paths or worker-result pointer yourself when Report writer worker is in the roster.
 
 ## When to Use
 
@@ -26,7 +26,7 @@ Two `frontmatter` approval fields are always emitted with their unset default
 2. Persist the exact prompt history with the required anchor headers and audience-specific reading list.
 3. Emit the Phase 6 checkpoint.
 4. Call `dispatch_worker(report_writer_assignment, prompt)` through the selected adapter.
-5. Call `await_workers([handle])` and verify both the data.json Result Path and worker-results audit path.
+5. Call `await_workers([handle])` and verify the data.json Result Path, rendered Markdown sibling, and worker-result pointer at Worker Result Path. Verify the separate heartbeat audit sidecar before accepting the run. **Enforced:** both dispatch adapters keep the three completion paths in `WorkerJob.completion_paths`, and `validators/validate_session_conformance.py` validates the audit sidecar.
 
 The assignment's `modelExecutionValue` feeds both adapter dispatch and the prompt header in item 9 below, so the execution model and recorded `**Model:**` header always agree. Missing or unsupported model resolution is a pre-dispatch contract failure; the common contract does not choose a runtime fallback.
 
@@ -35,8 +35,8 @@ The prompt MUST include, in this order at the top:
 1. `**Project Root:** <absolute-path>`
 2. `**Prompt History Path:** <project-relative-path>` (under current run `prompts/`)
 3. `**Result Path:** runs/<task-type>/reports/final-report-<task-type>-<seq>.data.json` — canonical JSON SSOT. The renderer produces the sibling `.md` automatically.
-4. `**Audit sidecar path:** <absolute-path>` — the generated report-writer audit destination derived from the Markdown `**Worker Result Path:**`, never from Result Path.
-5. `**Worker Result Path:** runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` — canonical Markdown worker-result source for the audit-path derivation.
+4. `**Worker Result Path:** runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md` — canonical three-path worker-result pointer and source for the audit-path derivation.
+5. `**Audit sidecar path:** <absolute-path>` — the generated report-writer heartbeat/read-confirmation destination derived from the Markdown `**Worker Result Path:**`, never from Result Path.
 6. `Assigned worker prompt history path: <absolute-path>`
 7. The four BLOCKING dispatch anchor headers generated from the report-writer audience (the worker cannot synthesize any of these paths):
    - `**Worker Preamble Path:** <absolute-path>` — selects `templates/report-writer-prompt-preamble.md`.
@@ -49,18 +49,18 @@ The prompt MUST include, in this order at the top:
    - `<instruction-set>/final-report-schema.json` — a task-type excerpt of the data.json schema (the other task-types' deliverable blocks and their unreachable `$defs` are stripped; ~38% of the full schema is `$defs` alone). This is your authoring aid for the data.json shape — the installed schema, not the excerpt, is what the run is judged against. Do **NOT** pull the full `schemas/final-report-v1.0.schema.json` — it carries all task-types and its `schemas/...` path is not part of the task bundle. (Validation still runs against the full schema post-hoc via the renderer, so the excerpt never relaxes the contract.)
    - `<instruction-set>/final-report-template.md` — the **phase-stripped** template (every other task-type's §5.x deliverable block removed by `render.py`'s `_strip_phase_blocks`, leaving only your run's §5.x). Do **NOT** also pull the full `templates/reports/final-report.template.md` source (it re-adds ~330 lines of other phases' deliverables and is not in the task bundle).
 11. A one-line MCP pointer instead of the verbatim block (redundant — the brief is already in the report-writer's Required reading, item 10): `**MCP servers:** follow the task brief's "## Available MCP Servers" section (already in your Required reading).`
-12. The convergence classifications (Full/Partial/Contested/Worker-Unique), the round history data (`roundHistory[]`), the `round2SkippedReason` value, and pointers to all worker result files under `worker-results/`. The report-writer worker populates `crossVerification.roundHistory` in the data.json so Section 6 can show which rounds executed, queue sizes, and why Round 2 was (or was not) skipped. The renderer prints the full per-round table only when more than one round ran; single-round or zero-round histories are auto-collapsed to a one-line summary.
+12. `Convergence state: runs/<task-type>/state/convergence-<task-type>-<seq>.json`, followed by pointers to all analysis-worker result files under `worker-results/`. The convergence path is deterministic and is listed even before Phase 5.5 creates the file. Read its classifications (Full/Partial/Contested/Worker-Unique), `roundHistory[]`, `round2SkippedReason`, and `finalClassificationCounts`; populate `crossVerification.roundHistory` in data.json so Section 6 can show which rounds executed, queue sizes, and why Round 2 was (or was not) skipped. The renderer prints the full per-round table only when more than one round ran; single-round or zero-round histories are auto-collapsed to a one-line summary.
 13. `**Report Language:** <en|ko>` — must be either `en` or `ko`; `auto`
     has been resolved by the lead from project.json / global config
     before the dispatch is constructed. The worker copies this verbatim
     into `data.json.meta.reportLanguage`.
 14. For implementation-planning runs: a literal block listing the 12 required English section headings — `Option Candidates`, `Trade-off`, `Recommended Option`, `Stage Map`, `Stepwise Execution Order`, `Dependency`, `Validation Checklist`, `Rollback`, `Requirement Coverage`, `Plan Body Verification`, `Cross-Project Dependencies`, `Decision Drafts`. This list is `PLANNING_REQUIRED_SECTIONS` in `validators/validate-run.py`; that tuple is the SSOT and this block must match it exactly. The writer uses these exact substrings as section headings (Korean translation in parentheses is allowed), and the `Plan Body Verification` section carries its required `Gate result:` line.
-15. An explicit instruction: `You are the author of TWO files: (a) the final-report data.json at <Result Path>, (b) the worker-results audit file at <Audit sidecar path>. After writing the data.json, invoke "okstra render-final-report <Result Path>" through the available execution interface so the markdown sibling is rendered before you return. Do not return the report inline. The validator fails the run when (a)'s schema validation fails, when the rendered markdown is absent, or when (b) is missing.`
+15. An explicit instruction: `You are the author of THREE files: (a) the final-report data.json at <Result Path>, (b) its rendered Markdown sibling produced through "okstra render-final-report <Result Path>", and (c) the worker-result pointer at <Worker Result Path>. Maintain the separate heartbeat audit sidecar at <Audit sidecar path>. Do not return the report inline. The dispatch fails when any of the three completion artifacts is missing, and session conformance fails when the audit sidecar is missing or invalid.`
 16. The prose budget (dedup contract): `verdictCard.finalConclusion` is the conclusion SSOT — at most 3 sentences. `rationale.*` fields stay within 2 sentences each and reference the verdict card / row IDs instead of restating their prose; `readerSummary` fields are one line each; `summary` stays at 3-5 rows unless the run covers multiple tickets. The schema field descriptions carry the same budgets (`tests/contract/test_report_prose_budget.py` guards both surfaces). Generation time scales with output volume, so exceeding the budget is a cost bug, not extra diligence.
 
 **Fix-run incremental authoring (applies when the run's profile carries a "Fix-Run Carry" block).** Do not author the data.json from scratch. Start by copying the previous run's data.json (the `Previous report` path in the Fix-Run Carry block) to this run's Result Path, then update ONLY the blocks the fix run changed: `meta`/`header` (run seq, dates), `executionStatus`, `implementation.verifierResults`, `implementation.validationEvidence`, `implementation.commitList` / `diffSummary`, `crossVerification`, `verdictCard`, `finalVerdict`, and any `evidence` rows the fix touched. Deliverable prose for unchanged sections is carried forward verbatim — do not re-generate it. Then invoke the renderer exactly as in a full run. The schema validation and renderer contract are unchanged, so an incrementally-authored data.json passes the same post-hoc gates. The lead's dispatch prompt MUST include the previous data.json path when the carry block is present.
 
-**Completion detection after dispatch (BLOCKING).** A dispatch acknowledgement is NOT completion — detect completion via the SSOT protocol in [team-contract](./team-contract.md) "Worker-completion detection", with a one-entry pending set covering the data.json (Result Path) and the worker-results audit file (Audit sidecar path). Do NOT end the turn with a prose "waiting for the report" statement.
+**Completion detection after dispatch (BLOCKING).** A dispatch acknowledgement is NOT completion — detect completion via the SSOT protocol in [team-contract](./team-contract.md) "Worker-completion detection", with a pending set covering the data.json (Result Path), rendered Markdown sibling, and worker-result pointer (Worker Result Path). Check the separate audit sidecar before accepting conformance. Do NOT end the turn with a prose "waiting for the report" statement. **Enforced:** the adapters reject a completed transition while any `completionPaths` entry is absent; `validators/validate_session_conformance.py` owns the audit check.
 
 ### Resume-safe dispatch
 
@@ -273,19 +273,25 @@ When the run's `task-type` is `release-handoff`, the final report MUST include S
 
 The final-report template `templates/reports/final-report.template.md` Section 5.6 already encodes this contract — copy that block verbatim and fill in. For non-`release-handoff` runs, omit Section 5.6 entirely.
 
-### Mandatory worker-results audit file (BLOCKING)
+### Mandatory worker-result pointer and audit sidecar (BLOCKING)
 
-You (the report-writer worker) MUST also write a worker-results audit file at the absolute path the lead provides as `**Audit sidecar path:**`, derived from `**Worker Result Path:**` and defaulting to:
+You (the report-writer worker) MUST write the worker-result pointer at `**Worker Result Path:**`, defaulting to:
 
 ```
-runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md
+runs/<task-type>/worker-results/report-writer-worker-<task-type>-<seq>.md
 ```
 
-This file is checked by the validator whenever the role's terminal status is `completed`. Without it the run fails with `report-writer is completed but worker result file is missing`.
+Its body contains exactly the project-relative data.json path, rendered Markdown path, and convergence-state input path. Analysis-worker result files stay in `## Inputs`; do not copy their list into the pointer. **Enforced:** both dispatch adapters include this pointer in `WorkerJob.completion_paths` and refuse `completed` while it is absent.
+
+The pointer's frontmatter and header follow `team-contract` "Result Frontmatter" and the standard worker-result header sections. Use `workerId: "report-writer"` and copy the remaining canonical values from `analysis-material.md`; do not duplicate the final-report body.
+
+You MUST also write the separate heartbeat/read-confirmation audit file at `**Audit sidecar path:**`, derived from Worker Result Path and defaulting to:
 
-**Frontmatter + header schema** — both the worker-results audit file AND the final-report file are governed by `team-contract` ("Result Frontmatter" and the standard worker-result header sections). That document is the single source of truth; do NOT restate the field list here. Use `workerId: "report-writer"` for both files and copy every other frontmatter value verbatim from `analysis-material.md`. The body of this audit file is short: name the canonical final-report path you wrote, list the input artifacts you reconciled, and record any structural deviations from `final-report.template.md`. Do NOT duplicate the full final-report body here — it's an audit pointer, not a second copy.
+```
+runs/<task-type>/worker-results/report-writer-worker-audit-<task-type>-<seq>.md
+```
 
-Skipping this file because "the real report is in `reports/`" is wrong. Both files are required.
+The selected report-writer preamble defines that audit shape. **Enforced:** `validators/validate_session_conformance.py` checks its reading confirmation, progress stages, timestamps, and cadence whenever the role completes.
 
 ### Main Body Section
 

package/runtime/prompts/lead/team-contract.md

@@ -130,9 +130,9 @@ Each probe matches exactly one dispatch backend. The dispatch record's `liveness
 | Worker | Backend | Flag | What it reads |
 |---|---|---|---|
 | any in-process worker (including `claude-worker` and `report-writer-worker`) | in-process dispatch | `--audit` | its registered audit sidecar's newest `- PROGRESS:` heartbeat |
-| `codex-worker` / `antigravity-worker` | CLI wrapper | `--prompt` | `<prompt>.log` / `<prompt>.status.json` |
+| `codex-worker` / `antigravity-worker` | CLI wrapper | `--team-state <path> --worker <id>` | the worker's persisted `promptPath` and `startedAt`, then `<prompt>.log` / `<prompt>.status.json` |
 
-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`.
+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.
 
 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.
 
@@ -147,7 +147,7 @@ After each worker subagent returns (regardless of role), Lead MUST verify the ca
 - The wrapper subagent returned an explicit `*_RESULT_MISSING` sentinel (codex-worker / antigravity-worker step 8c — `CODEX_RESULT_MISSING` / `ANTIGRAVITY_RESULT_MISSING`).
 - 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.
 - 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.
-- `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.
+- `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.
 - `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.
 - 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.
 

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -20,7 +20,7 @@ BRIEF_SECTIONS = (
     "Task Continuity Notes",
     "Available MCP Servers",
 )
-ERROR_ANALYSIS_BRIEF_SECTIONS = (
+CANONICAL_BRIEF_SECTIONS = (
     "Source Material",
     "Context",
     "Problem / Symptom",
@@ -38,9 +38,6 @@ ERROR_ANALYSIS_BRIEF_SECTIONS = (
     "Reporter Confirmations",
     "Augmentation",
 ) + BRIEF_SECTIONS
-BRIEF_SECTIONS_BY_TASK_TYPE = {
-    "error-analysis": ERROR_ANALYSIS_BRIEF_SECTIONS,
-}
 PROFILE_SECTIONS = (
     "Primary focus areas",
     "Expected output emphasis",
@@ -101,7 +98,7 @@ def build_analysis_packet(
             bool(clarification_response_path),
         )
     )
-    parts.extend(_brief_block(task_type, brief_text))
+    parts.extend(_brief_block(brief_text))
     parts.extend(_profile_block(task_type, profile_text))
     parts.extend(_reference_block(reference_text))
     parts.extend(_fix_history_block(fix_history_text))
@@ -160,15 +157,12 @@ def _intro_block(
     return lines
 
 
-def _brief_block(task_type: str, brief_text: str) -> list[str]:
+def _brief_block(brief_text: str) -> list[str]:
     return [
         "",
         "## Task-Specific Brief Extract",
         "",
-        _extract_sections(
-            brief_text,
-            BRIEF_SECTIONS_BY_TASK_TYPE.get(task_type, BRIEF_SECTIONS),
-        ),
+        _extract_sections(brief_text, CANONICAL_BRIEF_SECTIONS),
     ]
 
 

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()