okstra 0.168.0 → 0.169.1

package/runtime/python/okstra_ctl/dispatch_core.py

@@ -16,19 +16,22 @@ from .dispatch_state import (
     BACKEND_CMUX_PANE,
     BACKEND_MIXED,
     BACKEND_TMUX_PANE,
+    append_worker_dispatch as _append_worker_dispatch,
     DispatchError,
     WorkerJob,
     dispatch_mode as _dispatch_mode,
-    dispatch_record_matches,
     LIVENESS_AUDIT_HEARTBEAT,
     LIVENESS_WRAPPER_STATUS,
     load_json_object as _load_json_object,
+    link_agent_dispatch_result as _link_agent_dispatch_result,
     missing_completion_paths as _missing_completion_paths,
+    mutate_team_state as _mutate_team_state,
     require_string as _require_string,
     resolve_project_path as _resolve_project_path,
     resolve_required_path as _resolve_required_path,
     record_dispatch_facts as _record_dispatch_facts,
     transition_worker_status as _transition_worker_status,
+    update_worker_dispatch_status as _update_worker_dispatch_status,
     string_list as _string_list,
     string_value as _string_value,
     TEARDOWN_BEFORE_TERMINAL_REASON,
@@ -37,12 +40,12 @@ from .dispatch_state import (
     worker_jobs_from_file as _worker_jobs_from_file,
     worker_state as _worker_state,
     worktree_path as _worktree_path,
-    write_json as _write_json,
 )
 from .final_report_paths import (
     final_report_data_path as _final_report_data_path,
     final_report_markdown_path as _final_report_markdown_path,
 )
+from .error_log_write import append_observed
 from .lead_events import LeadEvent, append_lead_event
 from .initial_prompt_materialization import (
     InitialPromptMaterializationError,
@@ -58,13 +61,27 @@ from .report_finalize import (
     FinalizeError,
     run_finalize,
 )
+from .worker_audit_ledger import (
+    check_worker_results_audit,
+    parse_worker_result_name,
+)
 from .worker_prompt_body import REPORT_WRITER_WORKER_ID
+from .worker_prompt_headers import (
+    WorkerPromptHeaderError,
+    resolve_errors_log_path,
+)
 from .worker_artifact_paths import audit_sidecar_rel
 from .wrapper_status import read_wrapper_status, status_path_for_prompt
 
 
 MAX_WORKER_ATTEMPTS = 2
 TERMINAL_DISPATCH_STATUSES = {"completed", "timeout", "error", "not-run"}
+# What the error log records for a wrapper the dispatcher timed out, matching
+# the value `team-contract` prescribes for a polling-cap termination.
+_WRAPPER_TIMEOUT_EXIT_CODE = 124
+# The excerpt shares one atomic PIPE_BUF append with the rest of the record, so
+# it is capped far below the writer's own 2048-byte stderr limit.
+_WRAPPER_LOG_TAIL_BYTES = 800
 
 
 @dataclass(frozen=True)
@@ -74,6 +91,7 @@ class WorkerHandle:
     completed_process: subprocess.CompletedProcess[str] | None
     status_sidecar_path: Path | None
     degraded_from: str
+    running_process: subprocess.Popen[str] | None = None
 
 
 @dataclass(frozen=True)
@@ -174,7 +192,6 @@ def build_dispatch_plan(
     )
     if jobs_file:
         jobs = _jobs_from_file(project_root, workspace_root, jobs_file, options)
-        _validate_dispatch_prompts(manifest, active_context, jobs)
     else:
         jobs = _jobs_from_roster(
             project_root,
@@ -186,6 +203,7 @@ def build_dispatch_plan(
             requested_workers,
             options,
         )
+    _validate_dispatch_prompts(manifest, active_context, jobs)
     return DispatchPlan(
         project_root=project_root,
         workspace_root=workspace_root.resolve(),
@@ -199,6 +217,7 @@ def build_dispatch_plan(
 
 
 def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
+    _validate_report_writer_isolation(plan.jobs)
     if wait:
         pane_backends = sorted(
             {
@@ -225,6 +244,161 @@ def dispatch_plan(plan: DispatchPlan, *, wait: bool = True) -> int:
     return 0
 
 
+def dispatch_cli_wrapper_plan(plan: DispatchPlan) -> int:
+    """Start one dependency-free CLI batch before collecting any worker."""
+    if any(job.backend != BACKEND_CLI_WRAPPER for job in plan.jobs):
+        raise DispatchError("concurrent CLI dispatch requires cli-wrapper jobs only")
+    _validate_report_writer_isolation(plan.jobs)
+    _record_dispatch_facts(plan.team_state_path, _dispatch_mode(plan.jobs))
+    final_codes = _dispatch_cli_wrapper_batch(plan, plan.jobs)
+    return next((final_codes[job.worker_id] for job in plan.jobs
+                 if final_codes.get(job.worker_id, 0) != 0), 0)
+
+
+def _validate_report_writer_isolation(jobs: Sequence[WorkerJob]) -> None:
+    if (
+        any(job.worker_id == REPORT_WRITER_WORKER_ID for job in jobs)
+        and len(jobs) > 1
+    ):
+        raise DispatchError(
+            "report-writer must run in a separate Phase 6 dispatch after "
+            "analysis and convergence"
+        )
+
+
+def _dispatch_cli_wrapper_batch(
+    plan: DispatchPlan,
+    jobs: Sequence[WorkerJob],
+) -> dict[str, int]:
+    """Run one concurrent batch through all retries before the next dependency."""
+    pending = [(job, 1) for job in jobs]
+    final_codes: dict[str, int] = {}
+    while pending:
+        active: list[tuple[WorkerHandle, int]] = []
+        starting_job: WorkerJob | None = None
+        starting_attempt = 1
+        try:
+            for job, attempt in pending:
+                starting_job = job
+                starting_attempt = attempt
+                active.append((_spawn_cli_job_nonblocking(plan, job, attempt), attempt))
+        except (OSError, DispatchError) as exc:
+            if starting_job is not None:
+                _abort_cli_batch_start(
+                    plan,
+                    active,
+                    starting_job,
+                    starting_attempt,
+                    pending,
+                    exc,
+                )
+            raise
+        outcomes: list[tuple[WorkerHandle, int, WorkerOutcome]] = []
+        for handle, attempt in active:
+            process = handle.running_process
+            if process is None:
+                raise DispatchError("concurrent CLI worker process is missing")
+            returncode = process.wait()
+            completed = subprocess.CompletedProcess(handle.job.command, returncode)
+            settled = replace(handle, completed_process=completed, running_process=None)
+            outcomes.append((settled, attempt, _outcome_from_completed(settled)))
+
+        next_round: list[tuple[WorkerJob, int]] = []
+        for handle, attempt, outcome in outcomes:
+            job = handle.job
+            _finish_attempt(plan, job, attempt, outcome)
+            if _worker_terminal_status(plan.team_state_path, job.worker_id) == "completed":
+                final_codes[job.worker_id] = 0
+                continue
+            if _should_retry(outcome, attempt):
+                _append_event(
+                    plan,
+                    "worker-retry-scheduled",
+                    _retry_details(job, attempt, outcome),
+                )
+                next_round.append((job, attempt + 1))
+                continue
+            final_codes[job.worker_id] = outcome.returncode or 1
+        pending = next_round
+    return final_codes
+
+
+def _abort_cli_batch_start(
+    plan: DispatchPlan,
+    active: Sequence[tuple[WorkerHandle, int]],
+    failed_job: WorkerJob,
+    failed_attempt: int,
+    pending: Sequence[tuple[WorkerJob, int]],
+    error: Exception,
+) -> None:
+    reason = f"concurrent CLI batch launch failed: {error}"
+    for handle, _attempt in active:
+        process = handle.running_process
+        if process is not None and process.poll() is None:
+            process.terminate()
+    for handle, attempt in active:
+        process = handle.running_process
+        if process is not None:
+            process.wait()
+        _transition_worker_status(
+            plan.team_state_path, handle.job.worker_id, "error", reason
+        )
+        _update_dispatch_status(
+            plan.team_state_path, handle.job, attempt, "error", reason
+        )
+    _transition_worker_status(
+        plan.team_state_path, failed_job.worker_id, "error", reason
+    )
+    if not _update_dispatch_status(
+        plan.team_state_path,
+        failed_job,
+        failed_attempt,
+        "error",
+        reason,
+    ):
+        failed_handle = WorkerHandle(
+            failed_job,
+            "",
+            None,
+            status_path_for_prompt(failed_job.prompt_path),
+            "",
+        )
+        _record_dispatch(
+            plan.team_state_path,
+            failed_handle,
+            failed_attempt,
+            "error",
+            reason,
+        )
+    closed = {
+        (handle.job.worker_id, attempt) for handle, attempt in active
+    }
+    closed.add((failed_job.worker_id, failed_attempt))
+    for job, attempt in pending:
+        if (job.worker_id, attempt) in closed:
+            continue
+        _transition_worker_status(
+            plan.team_state_path, job.worker_id, "error", reason
+        )
+        if not _update_dispatch_status(
+            plan.team_state_path, job, attempt, "error", reason
+        ):
+            handle = WorkerHandle(
+                job,
+                "",
+                None,
+                status_path_for_prompt(job.prompt_path),
+                "",
+            )
+            _record_dispatch(
+                plan.team_state_path,
+                handle,
+                attempt,
+                "error",
+                reason,
+            )
+
+
 def await_dispatches(
     plan: DispatchPlan,
     *,
@@ -312,7 +486,15 @@ def _select_workers(
             options,
         )
     supported = set(options.supported_worker_wrappers)
-    selected = list(requested_workers) if requested_workers else [w for w in recommended if w in supported]
+    selected = (
+        list(requested_workers)
+        if requested_workers
+        else [
+            worker
+            for worker in recommended
+            if worker in supported and worker != REPORT_WRITER_WORKER_ID
+        ]
+    )
     unknown = [worker for worker in selected if worker not in recommended]
     if unknown:
         raise DispatchError("requested worker(s) are not in this run roster: " + ", ".join(unknown))
@@ -339,7 +521,11 @@ def _select_cli_wrapper_assignments(
         if _is_cli_wrapper_assignment(team_state, worker_id, options)
     }
     if not requested_workers:
-        selected = [worker for worker in recommended if worker in dispatchable]
+        selected = [
+            worker
+            for worker in recommended
+            if worker in dispatchable and worker != REPORT_WRITER_WORKER_ID
+        ]
         if selected:
             return selected
         raise DispatchError("run roster has no cli-wrapper assignments for codex-dispatch")
@@ -400,6 +586,8 @@ def _job_from_roster_worker(
     options: _BuildOptions,
 ) -> WorkerJob:
     result_path = _resolve_project_path(project_root, fact.result_path)
+    metadata = _agent_metadata(prompt_path)
+    invocation = _invocation_job_fields(metadata, prompt_path)
     return WorkerJob(
         worker_id=fact.worker_id,
         provider=fact.provider,
@@ -419,9 +607,47 @@ def _job_from_roster_worker(
         role=fact.role,
         idle_timeout_seconds=options.idle_timeout_seconds,
         dispatch_kind=options.dispatch_kind,
+        **invocation,
     )
 
 
+def _agent_metadata(prompt_path: Path) -> Mapping[str, Any] | None:
+    metadata_path = prompt_path.with_name(prompt_path.name + ".meta.json")
+    if not metadata_path.is_file():
+        return None
+    return _load_json_object(metadata_path, "agent invocation metadata")
+
+
+def _invocation_job_fields(
+    metadata: Mapping[str, Any] | None,
+    prompt_path: Path,
+) -> dict[str, Any]:
+    if metadata is None:
+        return {}
+    digests = metadata.get("digests")
+    assignment = metadata.get("modelAssignment")
+    if not isinstance(digests, Mapping) or not isinstance(assignment, Mapping):
+        raise DispatchError("agent invocation metadata is incomplete")
+    host_model_value = assignment.get("hostModelValue")
+    if host_model_value is not None and not isinstance(host_model_value, str):
+        raise DispatchError("agent invocation hostModelValue is invalid")
+    return {
+        "invocation_id": _require_string(metadata, "invocationId"),
+        "audience": _require_string(metadata, "audience"),
+        "assignment_ref": _require_string(metadata, "assignmentRef"),
+        "prompt_metadata_path": prompt_path.with_name(
+            prompt_path.name + ".meta.json"
+        ),
+        "catalog_digest": _require_string(digests, "catalogDigest"),
+        "assignment_digest": _require_string(digests, "assignmentDigest"),
+        "duty_digest": _require_string(digests, "dutyDigest"),
+        "instruction_digest": _require_string(digests, "instructionDigest"),
+        "prompt_digest": _require_string(digests, "promptDigest"),
+        "host_model_value": host_model_value,
+        "enforcement_mode": "core-pre-dispatch",
+    }
+
+
 def _materialize_roster_prompts(
     project_root: Path,
     workspace_root: Path,
@@ -510,6 +736,29 @@ def _spawn_job(plan: DispatchPlan, job: WorkerJob, attempt: int) -> WorkerHandle
     return handle
 
 
+def _spawn_cli_job_nonblocking(
+    plan: DispatchPlan, job: WorkerJob, attempt: int,
+) -> WorkerHandle:
+    _transition_worker_status(
+        plan.team_state_path, job.worker_id, "in-progress", "",
+        model_execution_value=job.model_execution_value,
+    )
+    process: subprocess.Popen[str] | None = None
+    try:
+        process = subprocess.Popen(job.command, cwd=plan.project_root, text=True)
+        handle = WorkerHandle(
+            job, "", None, status_path_for_prompt(job.prompt_path), "", process
+        )
+        _record_dispatch(plan.team_state_path, handle, attempt, "running", "")
+        _append_event(plan, "worker-dispatched", _attempt_details(job, attempt, handle))
+        return handle
+    except (OSError, DispatchError):
+        if process is not None and process.poll() is None:
+            process.terminate()
+            process.wait()
+        raise
+
+
 def _dispatch_job_with_retry(plan: DispatchPlan, job: WorkerJob) -> int:
     for attempt in range(1, MAX_WORKER_ATTEMPTS + 1):
         handle = _spawn_job(plan, job, attempt)
@@ -693,13 +942,29 @@ def _retry_from_record(
     worker_id = _require_string(record, "workerId")
     attempt = int(record.get("attempt", 1))
     job = _job_from_record(plan.project_root, record)
-    _update_dispatch_status(plan.team_state_path, job, attempt, "error", "required worker artifact was not produced")
-    _append_event(plan, "worker-retry-scheduled", {"workerId": worker_id, "attempt": attempt})
+    reason = "required worker artifact was not produced"
+    _update_dispatch_status(plan.team_state_path, job, attempt, "error", reason)
+    # `team-contract` counts the first attempt's failure as a recorded
+    # `cli-failure`; a retry that succeeds settles `completed` and would
+    # otherwise leave no trace that anything had to be re-run.
+    details: dict[str, Any] = {"workerId": worker_id, "attempt": attempt}
+    details["errorLogAppend"] = _record_wrapper_failure(
+        plan, job, attempt, outcome, reason
+    )
+    _append_event(plan, "worker-retry-scheduled", details)
     _spawn_job(plan, job, attempt + 1)
 
 
 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:
+    settlement = _settle(plan, job, attempt, outcome)
+    if settlement.completed:
+        if job.invocation_id:
+            _link_agent_dispatch_result(
+                project_root=plan.project_root,
+                run_manifest_path=plan.manifest_path,
+                dispatch_id=f"{job.invocation_id}:attempt-{attempt}",
+                result_path=job.worker_result_path,
+            )
         post_process = _post_process_report_writer_result(plan, job)
         if not post_process["ok"]:
             reason = _require_string(post_process, "reason")
@@ -724,16 +989,23 @@ def _finish_attempt(plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: W
         _transition_worker_status(
             plan.team_state_path, job.worker_id, "completed", ""
         )
-        _update_dispatch_status(plan.team_state_path, job, attempt, "completed", "")
+        _update_dispatch_status(
+            plan.team_state_path, job, attempt, "completed", settlement.note
+        )
         details = _result_details(job, attempt, outcome)
         details["postProcessing"] = post_process["steps"]
+        if settlement.error_log_append is not None:
+            details["errorLogAppend"] = settlement.error_log_append
         _append_event(plan, "worker-result-collected", details)
         return
-    reason = _failure_reason(outcome)
+    reason = settlement.reason
     status = "timeout" if outcome.timeout else "error"
     _transition_worker_status(plan.team_state_path, job.worker_id, status, reason)
     _update_dispatch_status(plan.team_state_path, job, attempt, status, reason)
-    _append_event(plan, "worker-failed", _failure_details(job, attempt, outcome, reason))
+    details = _failure_details(job, attempt, outcome, reason)
+    if settlement.error_log_append is not None:
+        details["errorLogAppend"] = settlement.error_log_append
+    _append_event(plan, "worker-failed", details)
 
 
 def _finish_record(plan: DispatchPlan, record: Mapping[str, Any], outcome: WorkerOutcome) -> None:
@@ -741,6 +1013,191 @@ def _finish_record(plan: DispatchPlan, record: Mapping[str, Any], outcome: Worke
     _finish_attempt(plan, job, int(record.get("attempt", 1)), outcome)
 
 
+@dataclass(frozen=True)
+class _Settlement:
+    """How one attempt's terminal status was decided."""
+
+    completed: bool
+    reason: str
+    note: str
+    error_log_append: dict[str, Any] | None
+
+
+def _settle(
+    plan: DispatchPlan, job: WorkerJob, attempt: int, outcome: WorkerOutcome
+) -> _Settlement:
+    """Judge an attempt by its artifacts, not by the wrapper's exit code alone.
+
+    A wrapper can die after its worker has already written everything — an
+    observed case is a connection dropped at session teardown, long after the
+    result file and its audit sidecar were on disk. Settling that as `error`
+    discards a complete analysis, and not figuratively: `convergence_engine`
+    admits only dispatches that settled `completed`, so the worker's findings
+    never reach re-verification. The lead's own re-dispatch triggers agree —
+    they name a missing, unparseable, or audit-failing result, never an exit
+    code — but the only signal `team await` gave was the status.
+
+    So a non-zero exit with every completion path present is re-judged by the
+    audit-sidecar contract, the same rules `okstra worker-audit-check` runs. It
+    passes and the dispatch settles `completed`; it fails and the dispatch stays
+    `error` exactly as before. Either way the wrapper's failure is written to the
+    run error log, so a `completed` here is never a swallowed failure.
+    """
+    if outcome.returncode == 0 and not outcome.missing_completion_paths and not outcome.timeout:
+        return _Settlement(True, "", "", None)
+    reason = _failure_reason(outcome)
+    completed = False
+    note = ""
+    if not outcome.timeout and not outcome.missing_completion_paths:
+        audit_failures = _audit_sidecar_failures(job)
+        if audit_failures:
+            reason = (
+                f"{reason}; worker artifacts failed the audit-sidecar "
+                f"contract: {audit_failures[0]}"
+            )
+        else:
+            completed = True
+            note = (
+                f"{reason}, but every completion artifact was written and "
+                f"passed the audit-sidecar contract"
+            )
+    append = _record_wrapper_failure(plan, job, attempt, outcome, note or reason)
+    return _Settlement(completed, "" if completed else reason, note, append)
+
+
+def _audit_sidecar_failures(job: WorkerJob) -> tuple[str, ...]:
+    """This worker's audit-sidecar contract failures, if the check can run.
+
+    The check's arguments come from the result filename rather than the manifest
+    so the scan cannot widen past the file this job produced: `worker-results/`
+    accumulates every run's artifacts, and the `worker=` filter matches the
+    `-worker`-suffixed role, not the bare provider id. A non-canonical name
+    leaves nothing to enforce, and an unverifiable artifact must not be promoted
+    to `completed`, so that reports one failure rather than an empty tuple.
+    """
+    parsed = parse_worker_result_name(job.worker_result_path.name)
+    if parsed is None:
+        return (
+            f"worker result `{job.worker_result_path.name}` is not a canonical "
+            f"`<role>-worker-<task-type>-<seq>.md` name, so the audit-sidecar "
+            f"contract could not be checked",
+        )
+    return tuple(
+        check_worker_results_audit(
+            job.worker_result_path.parent.parent,
+            parsed.task_type,
+            parsed.seq,
+            worker=parsed.worker_role,
+        )
+    )
+
+
+def _record_wrapper_failure(
+    plan: DispatchPlan,
+    job: WorkerJob,
+    attempt: int,
+    outcome: WorkerOutcome,
+    message: str,
+) -> dict[str, Any]:
+    """Write the wrapper's own failure to the run-level error log.
+
+    `okstra-lead-contract` tells Lead the deterministic dispatcher records this
+    and that Lead does not need to re-record it. Nothing did: no code path
+    anywhere called the error-log writer, so every wrapper failure vanished, and
+    with it the `instruction-set/prior-run-errors.md` digest the next run reads
+    and the `/okstra-inspect errors` report. The dispatcher is the only component
+    that holds the exit code, so it is the one that writes.
+
+    Never raises. Logging is bookkeeping around a dispatch that has already
+    settled; letting a rejected or unwritable record throw here would turn a
+    recorded outcome into an unrecorded crash. What went wrong travels back in
+    the lead event instead.
+    """
+    result: dict[str, Any] = {"ok": False, "reason": "", "path": ""}
+    try:
+        out_path = resolve_errors_log_path(
+            plan.project_root,
+            plan.manifest,
+            _load_optional_json(
+                plan.project_root, plan.manifest.get("activeRunContextPath")
+            ),
+        )
+        result["path"] = str(out_path)
+        append_observed(
+            out_path=out_path,
+            task_key=_string_value(plan.manifest.get("taskKey")),
+            phase=_workflow_phase(plan.manifest),
+            agent=_error_log_agent(job.worker_id),
+            agent_role=(
+                "report-writer"
+                if job.worker_id == REPORT_WRITER_WORKER_ID
+                else "worker"
+            ),
+            model=job.model_execution_value,
+            error_type="cli-failure",
+            command=" ".join(job.command),
+            command_kind="wrapper",
+            exit_code=_WRAPPER_TIMEOUT_EXIT_CODE if outcome.timeout else outcome.returncode,
+            duration_ms=_wrapper_duration_ms(outcome),
+            message=f"attempt {attempt}: {message}",
+            stderr_excerpt=_wrapper_log_tail(job),
+            context=None,
+        )
+    except (OSError, ValueError, TypeError, WorkerPromptHeaderError) as exc:
+        result["reason"] = f"{type(exc).__name__}: {exc}"
+        return result
+    result["ok"] = True
+    return result
+
+
+def _error_log_agent(worker_id: str) -> str:
+    """The error log's `--agent` enum value for a worker id.
+
+    The log's own allow-list is the authority on what it accepts; a worker whose
+    name is outside it is reported as such by `append_observed` rather than
+    silently rewritten into some other agent's records.
+    """
+    if worker_id == REPORT_WRITER_WORKER_ID:
+        return REPORT_WRITER_WORKER_ID
+    return f"{worker_id}-worker"
+
+
+def _workflow_phase(manifest: Mapping[str, Any]) -> str:
+    workflow = manifest.get("workflow")
+    if isinstance(workflow, Mapping):
+        return _string_value(workflow.get("currentPhase"))
+    return ""
+
+
+def _wrapper_duration_ms(outcome: WorkerOutcome) -> int | None:
+    if outcome.status_sidecar_path is None:
+        return None
+    status = read_wrapper_status(outcome.status_sidecar_path)
+    if status is None:
+        return None
+    value = status.raw.get("duration_ms")
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _wrapper_log_tail(job: WorkerJob) -> str | None:
+    """The tail of the wrapper transcript, which usually names the real failure.
+
+    The observed case put `API Error: Connection lost mid-response.` in the last
+    two lines and nothing anywhere else; without it the record says only that
+    some process exited 1. Capped well under the writer's own excerpt limit
+    because a whole record must stay inside one atomic `PIPE_BUF` append.
+    """
+    log_path = job.prompt_path.with_suffix(job.prompt_path.suffix + ".log")
+    try:
+        with log_path.open("rb") as handle:
+            handle.seek(0, 2)
+            handle.seek(max(0, handle.tell() - _WRAPPER_LOG_TAIL_BYTES))
+            tail = handle.read()
+    except OSError:
+        return None
+    return tail.decode("utf-8", errors="replace").strip() or None
+
+
 def _post_process_report_writer_result(
     plan: DispatchPlan,
     job: WorkerJob,
@@ -779,18 +1236,23 @@ def _worker_terminal_status(team_state_path: Path, worker_id: str) -> str:
 def _record_dispatch(
     team_state_path: Path, handle: WorkerHandle, attempt: int, status: str, reason: str
 ) -> None:
-    payload = _load_json_object(team_state_path, "team-state")
-    dispatches = payload.setdefault("workerDispatches", [])
-    if not isinstance(dispatches, list):
-        raise DispatchError(f"team-state workerDispatches must be an array: {team_state_path}")
-    dispatches.append(_dispatch_record(handle.job, attempt, status, handle.pane_id, handle.degraded_from, reason))
-    _write_json(team_state_path, payload)
+    _append_worker_dispatch(
+        team_state_path,
+        _dispatch_record(
+            handle.job,
+            attempt,
+            status,
+            handle.pane_id,
+            handle.degraded_from,
+            reason,
+        ),
+    )
 
 
 def _dispatch_record(
     job: WorkerJob, attempt: int, status: str, pane_id: str, degraded_from: str, reason: str = ""
 ) -> dict[str, Any]:
-    return {
+    record = {
         "workerId": job.worker_id,
         "role": job.role,
         "kind": job.dispatch_kind,
@@ -814,6 +1276,18 @@ def _dispatch_record(
         "completionPaths": [str(path) for path in job.completion_paths],
         "worktreePath": job.worktree_path,
     }
+    if job.invocation_id:
+        record.update({
+            "dispatchId": f"{job.invocation_id}:attempt-{attempt}",
+            "invocationId": job.invocation_id,
+            "audience": job.audience,
+            "assignmentRef": job.assignment_ref,
+            "promptMetadataPath": str(job.prompt_metadata_path),
+            **job.digests,
+            "hostModelValue": job.host_model_value,
+            "enforcementMode": job.enforcement_mode,
+        })
+    return record
 
 
 def _liveness_mode(backend: str) -> str:
@@ -824,22 +1298,14 @@ def _liveness_mode(backend: str) -> str:
 
 def _update_dispatch_status(
     team_state_path: Path, job: WorkerJob, attempt: int, status: str, reason: str
-) -> None:
-    payload = _load_json_object(team_state_path, "team-state")
-    matches = [
-        record
-        for record in payload.get("workerDispatches", [])
-        if dispatch_record_matches(record, job.prompt_path, attempt)
-    ]
-    if not matches:
-        return
-    # A lead may re-send a round's prompt without advancing `attempt`, which
-    # appends a second row the prompt cannot tell from the first. The newest is
-    # the one still running, so an outcome written to the older row would leave
-    # the live one running for good — the shape that wedged an await loop.
-    matches[-1]["status"] = status
-    matches[-1]["reason"] = reason
-    _write_json(team_state_path, payload)
+) -> bool:
+    return _update_worker_dispatch_status(
+        team_state_path,
+        prompt_path=job.prompt_path,
+        attempt=attempt,
+        status=status,
+        reason=reason,
+    )
 
 
 def _teardown_marked_dispatches(team_state_path: Path) -> list[Mapping[str, Any]]:
@@ -884,15 +1350,23 @@ def _mark_roster_skips(
     if not reasons:
         return
     team_state_path = _resolve_required_path(project_root, manifest, "teamStatePath")
-    current_team_state = _load_json_object(team_state_path, "team-state")
-    for worker_id, reason in reasons.items():
-        worker = _worker_state(current_team_state, worker_id)
-        if (
-            _string_value(worker.get("status")) != "not-run"
-            or _string_value(worker.get("reason"))
-        ):
-            continue
-        _transition_worker_status(team_state_path, worker_id, "not-run", reason)
+
+    def mark_pristine_skips(current_team_state: dict[str, Any]) -> bool:
+        changed = False
+        for worker_id, reason in reasons.items():
+            worker = _worker_state(current_team_state, worker_id)
+            if (
+                _string_value(worker.get("status")) != "not-run"
+                or _string_value(worker.get("reason"))
+            ):
+                continue
+            worker["reason"] = reason
+            worker.pop("startedAt", None)
+            worker.pop("endedAt", None)
+            changed = True
+        return changed
+
+    _mutate_team_state(team_state_path, mark_pristine_skips)
 
 
 def _skip_reasons(
@@ -1004,6 +1478,10 @@ def _result_details(job: WorkerJob, attempt: int, outcome: WorkerOutcome) -> dic
         "attempt": attempt,
         "dispatchMode": BACKEND_CLI_WRAPPER if outcome.degraded_from else job.backend,
         "missingCompletionPaths": [],
+        # A collected result can still come from a wrapper that exited non-zero
+        # (`_settle`). The status says the artifacts are good; this says what the
+        # process did, so the trace never loses one fact to the other.
+        "wrapperExitCode": outcome.returncode,
     }
 
 
@@ -1068,6 +1546,23 @@ def _job_from_record(project_root: Path, record: Mapping[str, Any]) -> WorkerJob
         role=_require_string(record, "role"),
         idle_timeout_seconds=600,
         dispatch_kind=_require_string(record, "kind"),
+        invocation_id=_string_value(record.get("invocationId")),
+        audience=_string_value(record.get("audience")),
+        assignment_ref=_string_value(record.get("assignmentRef")),
+        prompt_metadata_path=Path(
+            _string_value(record.get("promptMetadataPath"))
+        ),
+        catalog_digest=_string_value(record.get("catalogDigest")),
+        assignment_digest=_string_value(record.get("assignmentDigest")),
+        duty_digest=_string_value(record.get("dutyDigest")),
+        instruction_digest=_string_value(record.get("instructionDigest")),
+        prompt_digest=_string_value(record.get("promptDigest")),
+        host_model_value=(
+            record.get("hostModelValue")
+            if isinstance(record.get("hostModelValue"), str)
+            else None
+        ),
+        enforcement_mode=_string_value(record.get("enforcementMode")),
     )