okstra 0.173.0 → 0.175.1

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -1,8 +1,8 @@
 """Worker dispatch plumbing shared by both lead dispatchers.
 
 `dispatch_core` (claude / external lead) and `codex_dispatch` (codex lead) differ
-in capability — only the former has tmux panes, blocking waits, and retry from a
-persisted record. What they do *not* differ in is the job value object and the
+in capability — only the former has cmux surfaces, blocking waits, and retry from
+a persisted record. What they do *not* differ in is the job value object and the
 run's state files: the same run-manifest keys, the same team-state document, the
 same wrapper argv.
 
@@ -22,6 +22,7 @@ import fcntl
 import json
 import os
 import tempfile
+import uuid
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
@@ -31,8 +32,18 @@ from . import cmux
 from .agent_invocation import (
     AgentInvocationError,
     agent_model_assignment_from_payload,
+    invocation_metadata_identity,
+    v2_role_assignment_authority_errors,
     verify_agent_invocation,
 )
+from .domain.role import RoleCatalogError, role_for_duty
+from .execution_identity import Attempt, Invocation
+from .execution_manifest import (
+    finish_attempt_mutation,
+    read_execution_manifest,
+    record_invocation_attempt,
+)
+from .execution_mutation_audit import ExecutionMutationAudit, MutationSnapshot
 from .final_report_paths import (
     final_report_data_path,
     final_report_markdown_path,
@@ -44,25 +55,33 @@ from .worker_prompt_contract import (
     validate_reverify_prompt,
 )
 from .worker_runner import LIVE, QUIET
+from .worker_request import verifier_extra_dirs
+from .worker_artifact_paths import audit_sidecar_rel
+from .wrapper_status import status_path_for_prompt
+from .write_policy import (
+    build_invocation_write_contract,
+    planned_paths_from_run_manifest,
+    write_policy_from_payload,
+)
+from .convergence_store import write_json_atomic
 
 BACKEND_CLI_WRAPPER = "cli-wrapper"
-BACKEND_TMUX_PANE = "tmux-pane"
 BACKEND_CMUX_PANE = "cmux-pane"
 BACKEND_MIXED = "mixed"
 
 
 def detect_terminal_backend() -> str:
-    """Which pane backend this run gets. Called once, by prepare.
+    """Which backend this run's workers get. Called once, by prepare.
 
-    cmux wins wherever it is usable: the only thing a tmux session buys a lead
-    is Claude Code's AgentTeam, and the cmux path deliberately does not use it.
-    Everywhere else this answers `tmux-pane`, which is what every run got before
-    cmux existed. The answer is written to the run manifest and read back from
-    there — consumers must not re-detect, or two phases of one run can disagree.
+    cmux is the only backend that gives a worker a surface of its own. Without
+    it a worker runs as a cli-wrapper subprocess, which owns no pane and is read
+    through its status sidecar instead. The answer is written to the run manifest
+    and read back from there — consumers must not re-detect, or two phases of one
+    run can disagree.
     """
     if cmux.cmux_available():
         return BACKEND_CMUX_PANE
-    return BACKEND_TMUX_PANE
+    return BACKEND_CLI_WRAPPER
 
 # `livenessMode` picks which artifact answers "is this worker still alive": the
 # in-process worker's audit sidecar heartbeat, or the CLI wrapper's status
@@ -88,10 +107,26 @@ WORKER_STATUSES = frozenset(
 REASON_REQUIRED_STATUSES = frozenset({"timeout", "error", "not-run"})
 
 
+def generate_claude_session_id() -> str:
+    """A UUIDv4 for `claude --session-id`.
+
+    The lead mints one for its own session (`run`) and dispatch mints one per
+    worker (`dispatch_session_id`); they are the same kind of value, so one
+    generator serves both. It sits here rather than in `session` because
+    `session` imports this module, so a worker-side call the other way would
+    close an import cycle.
+    """
+    return str(uuid.uuid4())
+
+
 class DispatchError(Exception):
     """Raised when a worker dispatch request cannot be executed."""
 
 
+class IncompletePromptWriteArtifacts(DispatchError):
+    """Raised when a worker prompt omits the standard artifact headers."""
+
+
 @dataclass(frozen=True)
 class WorkerJob:
     worker_id: str
@@ -119,11 +154,23 @@ class WorkerJob:
     prompt_digest: str = ""
     host_model_value: str | None = None
     enforcement_mode: str = ""
+    # The session id dispatch mints and carries through to the provider CLI, so
+    # token collection can find the worker's jsonl by this value rather than by
+    # guessing at `agentName`. A worker started in a cmux pane is a separate CLI
+    # process and leaves no `agentName` behind, so without this its usage cannot
+    # be attributed at all.
+    session_id: str = ""
+    participant_ref: str = ""
+    role_execution_ref: str = ""
+    execution_label: str = ""
+    duty_id: str = ""
+    invocation_ref: str = ""
+    attempt: int = 0
 
     @property
     def command(self) -> list[str]:
         # The flag trails the positional contract the entrypoint reads by index.
-        return [
+        argv = [
             str(self.wrapper_path),
             str(self.project_root),
             self.model_execution_value,
@@ -134,6 +181,14 @@ class WorkerJob:
             "--presentation",
             self._presentation(),
         ]
+        if self.has_execution_identity:
+            argv.extend([
+                "--invocation-metadata",
+                str(self.prompt_metadata_path),
+            ])
+        if self.session_id:
+            argv += ["--session-id", self.session_id]
+        return argv
 
     def _presentation(self) -> str:
         # A pane is a screen a person watches; a cli-wrapper dispatch's stdout is
@@ -143,7 +198,6 @@ class WorkerJob:
 
     def to_payload(self) -> dict[str, Any]:
         payload = {
-            "workerId": self.worker_id,
             "provider": self.provider,
             "backend": self.backend,
             "modelExecutionValue": self.model_execution_value,
@@ -157,6 +211,19 @@ class WorkerJob:
             "dispatchKind": self.dispatch_kind,
             "command": self.command,
         }
+        if self.has_execution_identity:
+            payload.update({
+                "schemaVersion": "2.0",
+                "executionIdentityVersion": 2,
+                "participantRef": self.participant_ref,
+                "roleExecutionRef": self.role_execution_ref,
+                "executionLabel": self.execution_label,
+                "dutyId": self.duty_id,
+                "invocationRef": self.invocation_ref,
+                "attempt": self.attempt,
+            })
+        else:
+            payload.update({"schemaVersion": 1, "workerId": self.worker_id})
         if self.invocation_id:
             payload.update({
                 "invocationId": self.invocation_id,
@@ -169,6 +236,22 @@ class WorkerJob:
             })
         return payload
 
+    @property
+    def has_execution_identity(self) -> bool:
+        values = (
+            self.participant_ref,
+            self.role_execution_ref,
+            self.execution_label,
+            self.duty_id,
+            self.invocation_ref,
+        )
+        present = tuple(bool(value) for value in values)
+        if any(present) and not all(present):
+            raise DispatchError("worker job has partial v2 execution identity")
+        if all(present) and self.attempt < 1:
+            raise DispatchError("worker job v2 attempt must be positive")
+        return all(present)
+
     @property
     def digests(self) -> dict[str, str]:
         return {
@@ -298,7 +381,23 @@ def append_worker_dispatch(
     team_state_path: Path,
     record: Mapping[str, Any],
 ) -> None:
-    """Append one worker dispatch without losing another state writer's update."""
+    """Record one worker dispatch without losing another state writer's update.
+
+    A row carrying a dispatch id replaces the row that already holds it rather
+    than stacking beside it: an observed lead re-sent `okstra team dispatch` for
+    a prompt and attempt it had already sent, team-state kept both copies, and
+    `validate-run` failed that run with `agent dispatch ID is duplicated`.
+
+    The replaced row takes its `paneId` with it, and recorded ids are the only
+    reclaim candidates `team._reclaimable_panes` has, so that pane is left on
+    screen for the session. That is the price of the trade: before this, the
+    same re-send cost the whole run its report.
+
+    A job with no invocation carries no dispatch id, so it has no key to
+    collapse on and folding those rows would merge two unrelated dispatches into
+    one. They still stack, and `update_worker_dispatch_status` settles the
+    newest of them.
+    """
     with _team_state_lock(team_state_path):
         payload = load_json_object(team_state_path, "team-state")
         dispatches = payload.setdefault("workerDispatches", [])
@@ -306,7 +405,20 @@ def append_worker_dispatch(
             raise DispatchError(
                 f"team-state workerDispatches must be an array: {team_state_path}"
             )
-        dispatches.append(dict(record))
+        new_record = dict(record)
+        new_id = str(new_record.get("dispatchId") or "")
+        replaced = False
+        if new_id:
+            for index, existing in enumerate(dispatches):
+                if (
+                    isinstance(existing, Mapping)
+                    and existing.get("dispatchId") == new_id
+                ):
+                    dispatches[index] = new_record
+                    replaced = True
+                    break
+        if not replaced:
+            dispatches.append(new_record)
         write_json(team_state_path, payload)
 
 
@@ -388,9 +500,22 @@ def record_verified_agent_dispatch(
         assignment = agent_model_assignment_from_payload(assignments.get(assignment_ref))
     except AgentInvocationError as exc:
         raise DispatchError(str(exc)) from exc
-    worker_id = require_string(metadata, "workerId")
+    try:
+        execution_identity = invocation_metadata_identity(metadata)
+    except AgentInvocationError as exc:
+        raise DispatchError(str(exc)) from exc
+    worker_id = (
+        require_string(metadata, "workerId")
+        if execution_identity is None
+        else None
+    )
     audience = require_string(metadata, "audience")
     invocation_id = require_string(metadata, "invocationId")
+    if (
+        execution_identity is not None
+        and execution_identity.invocation_ref != invocation_id
+    ):
+        raise DispatchError("v2 invocation reference does not match invocation ID")
     errors = verify_agent_invocation(
         metadata_path,
         project_root=project_root,
@@ -400,6 +525,15 @@ def record_verified_agent_dispatch(
         expected_worker_id=worker_id,
         expected_assignment_ref=assignment_ref,
         expected_audience=audience,
+        expected_participant_ref=(
+            execution_identity.participant_ref if execution_identity else None
+        ),
+        expected_role_execution_ref=(
+            execution_identity.role_execution_ref if execution_identity else None
+        ),
+        expected_invocation_ref=(
+            execution_identity.invocation_ref if execution_identity else None
+        ),
     )
     if errors:
         raise DispatchError("agent invocation verification failed: " + "; ".join(errors))
@@ -428,10 +562,15 @@ def record_verified_agent_dispatch(
     if not isinstance(prompt, Mapping):
         raise DispatchError("agent invocation prompt is missing")
     prompt_path = require_string(prompt, "path")
-    dispatch_id = f"{invocation_id}:attempt-1"
+    # Identity-bearing records carry the stored attempt. A path without
+    # identity still records the first attempt; the conflict guard below
+    # refuses a second write under that id.
+    dispatch_id = build_dispatch_id(
+        invocation_id,
+        execution_identity.attempt if execution_identity else 1,
+    )
     record = {
         "dispatchId": dispatch_id,
-        "workerId": worker_id,
         "audience": audience,
         "invocationId": invocation_id,
         "assignmentRef": assignment_ref,
@@ -444,7 +583,99 @@ def record_verified_agent_dispatch(
         "promptDeliveryVerified": False,
         "status": "dispatched",
     }
+    if execution_identity is None:
+        record["workerId"] = worker_id
+    else:
+        record.update({
+            "schemaVersion": "2.0",
+            "executionIdentityVersion": 2,
+            "invocationRef": execution_identity.invocation_ref,
+            "participantRef": execution_identity.participant_ref,
+            "roleExecutionRef": execution_identity.role_execution_ref,
+            "executionLabel": execution_identity.execution_label,
+            "dutyId": execution_identity.duty_id,
+            "attempt": execution_identity.attempt,
+            "dispatchKind": require_string(metadata, "dispatchKind"),
+        })
     team_state_path = resolve_required_path(project_root, manifest, "teamStatePath")
+    write_policy = None
+    write_enforcement = None
+    mutation_snapshot_path = metadata_path.with_suffix(
+        metadata_path.suffix + ".mutation-audit.json"
+    )
+    if execution_identity is not None:
+        write_policy, write_enforcement = _agent_write_contract(
+            project_root,
+            run_manifest_path,
+            manifest,
+            execution_identity.role_execution_ref,
+            resolve_project_path(project_root, prompt_path),
+            assignment_ref,
+        )
+        record.update({
+            "writePolicyDigest": write_policy.digest,
+            "writeEnforcement": write_enforcement.to_payload(),
+            "mutationAuditSnapshotPath": (
+                _relative_project_path(project_root, mutation_snapshot_path)
+                if write_enforcement.mutation_audit == "batch"
+                else ""
+            ),
+        })
+    existing_state = load_json_object(team_state_path, "team-state")
+    existing = [
+        item
+        for item in existing_state.get("agentDispatches") or []
+        if isinstance(item, Mapping) and item.get("dispatchId") == dispatch_id
+    ]
+    if existing:
+        if len(existing) != 1 or dict(existing[0]) != record:
+            raise DispatchError(f"agent dispatch ID conflicts: {dispatch_id}")
+        return record
+    if execution_identity is not None:
+        dispatch_kind = require_string(metadata, "dispatchKind")
+        prompt_digest = require_string(digests, "promptDigest")
+        if write_policy is None or write_enforcement is None:
+            raise DispatchError("agent write contract was not prepared")
+        record_invocation_attempt(
+            run_manifest_path,
+            Invocation(
+                invocation_ref=execution_identity.invocation_ref,
+                participant_ref=execution_identity.participant_ref,
+                role_execution_ref=execution_identity.role_execution_ref,
+                source_invocation_ref=None,
+                recovery_ref=None,
+                duty_id=execution_identity.duty_id,
+                dispatch_kind=dispatch_kind,
+                round=_execution_dispatch_round(dispatch_kind),
+                input_digest=prompt_digest,
+                write_policy=write_policy.to_payload(),
+                write_policy_digest=write_policy.digest,
+                write_enforcement=write_enforcement.to_payload(),
+            ),
+            Attempt(
+                invocation_ref=execution_identity.invocation_ref,
+                attempt=execution_identity.attempt,
+                started_at=utc_now(),
+                finished_at=None,
+                status="started",
+                result_path=None,
+                error_path=None,
+                change_summary={},
+                evidence_seal_ref=None,
+            ),
+            task_key=require_string(manifest, "taskKey"),
+        )
+        if write_enforcement.mutation_audit == "batch":
+            snapshot = ExecutionMutationAudit().snapshot(
+                (write_policy,),
+                orchestrator_paths=(
+                    run_manifest_path,
+                    team_state_path,
+                    Path(f"{team_state_path}.lock"),
+                    mutation_snapshot_path,
+                ),
+            )
+            write_json_atomic(mutation_snapshot_path, snapshot.to_payload())
     with _team_state_lock(team_state_path):
         team_state = load_json_object(team_state_path, "team-state")
         dispatches = team_state.setdefault("agentDispatches", [])
@@ -463,13 +694,191 @@ def record_verified_agent_dispatch(
     return record
 
 
+def _agent_write_contract(
+    project_root: Path,
+    manifest_path: Path,
+    authority: Mapping[str, Any],
+    role_execution_ref: str,
+    prompt_path: Path,
+    assignment_ref: str,
+):
+    execution_manifest = read_execution_manifest(manifest_path)
+    execution = next(
+        (
+            row for row in execution_manifest.role_executions
+            if row.role_execution_ref == role_execution_ref
+        ),
+        None,
+    )
+    capability = (
+        execution.binding.worker_write_capability
+        if execution is not None and execution.binding is not None
+        else None
+    )
+    if execution is None:
+        raise DispatchError("agent write policy has no role execution")
+    if execution.role == "leader":
+        artifacts = _leader_artifact_paths(project_root, authority)
+        worktree = None
+        maximum_precision = "none"
+    elif capability is not None:
+        try:
+            artifacts, worktree = _prompt_write_paths(project_root, prompt_path)
+        except IncompletePromptWriteArtifacts:
+            artifacts, worktree = _manifest_worker_write_paths(
+                project_root, authority, assignment_ref, prompt_path
+            )
+        maximum_precision = capability.max_boundary_precision
+    else:
+        raise DispatchError("agent write policy has no runner capability")
+    try:
+        return build_invocation_write_contract(
+            role=execution.role,
+            project_root=project_root,
+            worktree=worktree,
+            artifact_paths=artifacts,
+            maximum_precision=maximum_precision,
+            planned_paths=(
+                planned_paths_from_run_manifest(project_root, authority)
+                if execution.role == "implementer"
+                else ()
+            ),
+            auxiliary_roots=verifier_extra_dirs(execution.role),
+            validated_auxiliary_roots=verifier_extra_dirs(execution.role),
+        )
+    except (OSError, ValueError) as exc:
+        raise DispatchError(f"agent write policy is invalid: {exc}") from exc
+
+
+def _leader_artifact_paths(
+    project_root: Path, authority: Mapping[str, Any]
+) -> tuple[Path, ...]:
+    value = authority.get("taskRootPath") or authority.get("runDirectoryPath")
+    if not isinstance(value, str) or not value.strip():
+        raise DispatchError("leader write policy has no artifact root")
+    artifact_home = project_root / ".okstra"
+    if not artifact_home.is_dir():
+        raise DispatchError("leader write policy artifact home does not exist")
+    return (artifact_home,)
+
+
+def _manifest_worker_write_paths(
+    project_root: Path,
+    authority: Mapping[str, Any],
+    assignment_ref: str,
+    prompt_path: Path,
+) -> tuple[tuple[Path, ...], Path | None]:
+    prefix = "initial/"
+    if not assignment_ref.startswith(prefix):
+        raise DispatchError("agent prompt write artifact headers are incomplete")
+    worker_id = assignment_ref.removeprefix(prefix)
+    team_state_path = resolve_required_path(
+        project_root, authority, "teamStatePath"
+    )
+    team_state = load_json_object(team_state_path, "team-state")
+    matches = [
+        row for row in team_state.get("workers") or []
+        if isinstance(row, Mapping) and row.get("workerId") == worker_id
+    ]
+    if len(matches) != 1:
+        raise DispatchError("agent prompt has no unique worker artifact authority")
+    result = resolve_project_path(
+        project_root, require_string(matches[0], "resultPath")
+    )
+    paths = {
+        *dispatch_completion_paths(worker_id, result, authority, project_root),
+        result,
+        Path(audit_sidecar_rel(str(result))),
+        status_path_for_prompt(prompt_path),
+        prompt_path.with_suffix(prompt_path.suffix + ".log"),
+    }
+    active_value = authority.get("activeRunContextPath")
+    active = (
+        load_json_object(
+            resolve_project_path(project_root, active_value),
+            "active run context",
+        )
+        if isinstance(active_value, str) and active_value
+        else {}
+    )
+    error_logs = active.get("errorLogs")
+    sidecars = (
+        error_logs.get("sidecarsByWorkerId")
+        if isinstance(error_logs, Mapping)
+        else None
+    )
+    error_value = sidecars.get(worker_id) if isinstance(sidecars, Mapping) else None
+    if isinstance(error_value, str) and error_value:
+        paths.add(resolve_project_path(project_root, error_value))
+    worktree_value = worktree_path(authority, active)
+    worktree = Path(worktree_value) if worktree_value else None
+    return tuple(sorted(paths, key=str)), worktree
+
+
+def _prompt_write_paths(
+    project_root: Path, prompt_path: Path
+) -> tuple[tuple[Path, ...], Path | None]:
+    try:
+        lines = prompt_path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeError) as exc:
+        raise DispatchError("agent prompt cannot be read for write policy") from exc
+    values: dict[str, str] = {}
+    labels = {
+        "Result Path",
+        "Worker Result Path",
+        "Audit sidecar path",
+        "Errors sidecar path",
+        "Worktree",
+    }
+    for line in lines:
+        for label in labels:
+            prefix = f"**{label}:** "
+            if line.startswith(prefix):
+                values[label] = line.removeprefix(prefix).strip()
+    required = {"Result Path", "Audit sidecar path", "Errors sidecar path"}
+    if not required <= values.keys():
+        raise IncompletePromptWriteArtifacts(
+            "agent prompt write artifact headers are incomplete"
+        )
+    artifact_values = [values[label] for label in sorted(required)]
+    if "Worker Result Path" in values:
+        artifact_values.append(values["Worker Result Path"])
+    artifacts = {
+        _project_or_absolute(project_root, value) for value in artifact_values
+    }
+    artifacts.add(status_path_for_prompt(prompt_path))
+    artifacts.add(prompt_path.with_suffix(prompt_path.suffix + ".log"))
+    worktree_value = values.get("Worktree")
+    worktree = (
+        _project_or_absolute(project_root, worktree_value)
+        if worktree_value
+        else None
+    )
+    return tuple(sorted(artifacts, key=str)), worktree
+
+
+def _project_or_absolute(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _execution_dispatch_round(dispatch_kind: str) -> int:
+    prefix = "reverify-r"
+    if not dispatch_kind.startswith(prefix):
+        return 1
+    suffix = dispatch_kind[len(prefix):]
+    if not suffix.isdigit() or int(suffix) < 1:
+        raise DispatchError(f"invalid reverify dispatch kind: {dispatch_kind}")
+    return int(suffix)
+
+
 def link_agent_dispatch_result(
     *,
     project_root: Path,
     run_manifest_path: Path,
     dispatch_id: str,
     result_path: Path,
-) -> dict[str, str]:
+) -> dict[str, Any]:
     """Link an existing result artifact to exactly one verified dispatch."""
     project_root = project_root.resolve()
     manifest_path = resolve_project_path(
@@ -486,7 +895,20 @@ def link_agent_dispatch_result(
         raise DispatchError("agent result link must stay inside the current run")
     result_relative = _relative_project_path(project_root, resolved_result)
     team_state_path = resolve_required_path(project_root, manifest, "teamStatePath")
-    link = {"dispatchId": dispatch_id, "resultPath": result_relative}
+    preview = load_json_object(team_state_path, "team-state")
+    native_dispatches = [
+        item for item in preview.get("agentDispatches") or []
+        if isinstance(item, Mapping) and item.get("dispatchId") == dispatch_id
+    ]
+    if len(native_dispatches) == 1:
+        _finish_native_agent_attempt(
+            project_root=project_root,
+            manifest_path=manifest_path,
+            manifest=manifest,
+            dispatch=native_dispatches[0],
+            result_path=resolved_result,
+            result_relative=result_relative,
+        )
     with _team_state_lock(team_state_path):
         team_state = load_json_object(team_state_path, "team-state")
         dispatches = [
@@ -502,6 +924,21 @@ def link_agent_dispatch_result(
             raise DispatchError(
                 f"agent result link requires exactly one dispatch record: {dispatch_id}"
             )
+        dispatch = dispatches[0]
+        link: dict[str, Any] = {
+            "dispatchId": dispatch_id,
+            "resultPath": result_relative,
+        }
+        identity = worker_execution_identity(dispatch)
+        if identity is not None:
+            link.update({
+                "participantRef": identity["participant_ref"],
+                "roleExecutionRef": identity["role_execution_ref"],
+                "executionLabel": identity["execution_label"],
+                "dutyId": identity["duty_id"],
+                "invocationRef": identity["invocation_ref"],
+                "attempt": identity["attempt"],
+            })
         links = team_state.setdefault("agentResultLinks", [])
         if not isinstance(links, list):
             raise DispatchError("team-state agentResultLinks must be an array")
@@ -539,6 +976,137 @@ def link_agent_dispatch_result(
     return link
 
 
+def _finish_native_agent_attempt(
+    *,
+    project_root: Path,
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    dispatch: Mapping[str, Any],
+    result_path: Path,
+    result_relative: str,
+) -> None:
+    identity = worker_execution_identity(dispatch)
+    if identity is None:
+        return
+    execution = read_execution_manifest(manifest_path)
+    invocation = next(
+        (
+            row for row in execution.invocations
+            if row.invocation_ref == identity["invocation_ref"]
+        ),
+        None,
+    )
+    if invocation is None:
+        raise DispatchError("agent result has no canonical invocation policy")
+    if dispatch.get("writePolicyDigest") != invocation.write_policy_digest:
+        raise DispatchError("agent dispatch write policy digest changed")
+    if dispatch.get("writeEnforcement") != invocation.write_enforcement:
+        raise DispatchError("agent dispatch write enforcement changed")
+    policy = write_policy_from_payload(invocation.write_policy)
+    snapshot_value = string_value(dispatch.get("mutationAuditSnapshotPath"))
+    if snapshot_value:
+        snapshot_payload = load_json_object(
+            resolve_project_path(project_root, snapshot_value),
+            "mutation audit snapshot",
+        )
+        try:
+            snapshot = MutationSnapshot.from_payload(snapshot_payload)
+        except (KeyError, TypeError, ValueError) as exc:
+            raise DispatchError("mutation audit snapshot is invalid") from exc
+        result = ExecutionMutationAudit().compare(
+            snapshot,
+            (policy,),
+            out_of_plan_edits=_native_out_of_plan_paths(result_path),
+            attempt_succeeded=True,
+            result_present=True,
+        )
+        summary = result.change_summary()
+        status = result.status
+    else:
+        status = "ok"
+        summary = {
+            "mutationStatus": "ok",
+            "changedPaths": [],
+            "sourceChanged": False,
+            "gitChanged": False,
+            "attribution": "call",
+            "retryAllowed": False,
+            "violations": [],
+            "beforeDigest": "",
+            "afterDigest": "",
+        }
+    _close_native_attempt(
+        manifest_path,
+        manifest,
+        identity,
+        status,
+        result_relative,
+        summary,
+    )
+    if status != "ok":
+        violations = summary.get("violations")
+        detail = "; ".join(violations) if isinstance(violations, list) else status
+        raise DispatchError(f"agent mutation audit failed: {detail or status}")
+
+
+def _close_native_attempt(
+    manifest_path: Path,
+    manifest: Mapping[str, Any],
+    identity: Mapping[str, Any],
+    status: str,
+    result_path: str,
+    summary: Mapping[str, Any],
+) -> None:
+    execution = read_execution_manifest(manifest_path)
+    existing = next(
+        (
+            row for row in execution.attempts
+            if row.invocation_ref == identity["invocation_ref"]
+            and row.attempt == identity["attempt"]
+        ),
+        None,
+    )
+    if existing is not None and existing.finished_at is not None:
+        if (
+            existing.status == status
+            and existing.result_path == result_path
+            and dict(existing.change_summary) == dict(summary)
+        ):
+            return
+        raise DispatchError("agent attempt terminal mutation result drift")
+    finish_attempt_mutation(
+        manifest_path,
+        invocation_ref=identity["invocation_ref"],
+        attempt=identity["attempt"],
+        finished_at=utc_now(),
+        status=status,
+        result_path=result_path,
+        error_path=None,
+        change_summary=summary,
+        task_key=require_string(manifest, "taskKey"),
+    )
+
+
+def _native_out_of_plan_paths(result_path: Path) -> tuple[str, ...]:
+    if result_path.suffix != ".json":
+        return ()
+    try:
+        payload = json.loads(result_path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return ()
+    implementation = payload.get("implementation") if isinstance(payload, Mapping) else None
+    rows = implementation.get("outOfPlanEdits") if isinstance(implementation, Mapping) else None
+    if not isinstance(rows, list):
+        return ()
+    return tuple(
+        str(row["file"])
+        for row in rows
+        if isinstance(row, Mapping)
+        and isinstance(row.get("file"), str)
+        and row["file"]
+    )
+
+
 def reject_agent_dispatch_result(
     *,
     project_root: Path,
@@ -712,6 +1280,25 @@ def _has_recorded_team_create(team_state: Mapping[str, Any]) -> bool:
 
 # --- job facts ----------------------------------------------------------------
 
+def build_dispatch_id(invocation_id: str, attempt: int) -> str:
+    """The only place Python assembles a dispatch id.
+
+    Two generators drifted: this module pinned the attempt to 1 while
+    `dispatch_core` used the real one, so a re-dispatch took the first attempt's
+    id, team-state kept the same row twice, and `validate-run` failed that run
+    with `agent dispatch ID is duplicated`.
+
+    Prose mirrors of this shape live outside Python, where no guard reaches
+    them: `prompts/lead/convergence.md`, `prompts/lead/report-writer.md`,
+    `prompts/lead/plan-body-verification.md` and the five
+    `adapters/hosts/*/relay.md` each spell an `--dispatch-id` argument out for
+    the lead. They agree with this function only because
+    `record_verified_agent_dispatch` records the first attempt and no other;
+    changing that convention has to change them too.
+    """
+    return f"{invocation_id}:attempt-{attempt}"
+
+
 def dispatch_mode(jobs: Sequence[WorkerJob]) -> str:
     backends = {job.backend for job in jobs}
     if len(backends) == 1:
@@ -723,6 +1310,59 @@ def missing_completion_paths(job: WorkerJob) -> tuple[Path, ...]:
     return tuple(path for path in job.completion_paths if not path.is_file())
 
 
+def dispatch_session_id(provider: str) -> str:
+    """The session this dispatch mints for *provider*, or '' for one that has no
+    such flag.
+
+    Only the claude CLI reads `--session-id`; handing the value to another
+    wrapper would start it with an argument it does not know. An empty value is
+    the same as not issuing one — `WorkerJob.command` appends the flag only when
+    it is set.
+
+    This lives beside `worker_jobs_from_file` for the same reason
+    `dispatch_result_path` does: both job constructors apply it, and a rule
+    written twice is a rule that drifts.
+    """
+    return generate_claude_session_id() if provider == "claude" else ""
+
+
+def worker_session_ids(
+    team_state: Mapping[str, Any], worker_id: str | None = None
+) -> list[str]:
+    """The claude sessions this run's dispatches issued, in the order recorded.
+
+    A worker started in a cmux pane is its own `claude -p` process and tags its
+    session jsonl with neither `agentName` nor `teamName`, so nothing in the
+    transcript says which worker wrote it. The id `dispatch_session_id` minted
+    and `_dispatch_record` wrote is the only handle on it.
+
+    Every id, not one: a retry opens a new session, so one worker legitimately
+    owns several rows with different `sessionId` values, and taking only the
+    first or last bills a single attempt of a retried worker.
+
+    Pass ``worker_id`` for one worker's sessions, or omit it for the run's.
+    This reads a `workerDispatches[]` row shape, so it belongs beside the code
+    that writes that shape rather than in each of the two modules that read it.
+
+    A non-list log yields nothing rather than raising: `session.observe_lead_session`
+    calls this for its exclusion set and catches only OSError, so a `TypeError`
+    from iterating a number here would take down `team dispatch` / `team await` /
+    `report-finalize`. Observation not breaking its caller is a contract kept
+    here, the same way `add_observed_session` keeps it for the keys it appends to.
+    """
+    session_ids: list[str] = []
+    dispatches = team_state.get("workerDispatches")
+    for record in dispatches if isinstance(dispatches, list) else []:
+        if not isinstance(record, Mapping):
+            continue
+        if worker_id is not None and record.get("workerId") != worker_id:
+            continue
+        session_id = str(record.get("sessionId") or "").strip()
+        if session_id and session_id not in session_ids:
+            session_ids.append(session_id)
+    return session_ids
+
+
 def dispatch_result_path(
     worker_id: str,
     worker_result_path: Path,
@@ -921,6 +1561,121 @@ def _validate_agent_invocations(
         raise DispatchError("agent invocation contract: " + "; ".join(errors))
 
 
+def _v2_job_authority_errors(
+    job: WorkerJob,
+    metadata: Mapping[str, Any],
+    manifest: Mapping[str, Any],
+) -> list[str]:
+    try:
+        identity = invocation_metadata_identity(metadata)
+    except AgentInvocationError as exc:
+        return [str(exc)]
+    if identity is None:
+        return ["jobs file v2 identity has v1 invocation metadata"]
+    errors: list[str] = []
+    if job.invocation_ref != identity.invocation_ref:
+        errors.append("jobs file invocationRef does not match invocation metadata")
+    if (
+        job.participant_ref != identity.participant_ref
+        or job.role_execution_ref != identity.role_execution_ref
+        or job.execution_label != identity.execution_label
+        or job.duty_id != identity.duty_id
+        or job.attempt != identity.attempt
+    ):
+        errors.append("jobs file v2 identity does not match invocation metadata")
+    prompt = metadata.get("prompt")
+    metadata_prompt_value = (
+        string_value(prompt.get("path")) if isinstance(prompt, Mapping) else ""
+    )
+    metadata_prompt_path = resolve_project_path(
+        job.project_root, metadata_prompt_value
+    )
+    if (
+        not metadata_prompt_value
+        or job.prompt_path.resolve() != metadata_prompt_path.resolve()
+    ):
+        errors.append("jobs file promptPath does not match invocation metadata")
+    role_executions = manifest.get("roleExecutions")
+    execution = next((
+        row for row in role_executions
+        if isinstance(row, Mapping)
+        and row.get("roleExecutionRef") == identity.role_execution_ref
+    ), None) if isinstance(role_executions, list) else None
+    participants = manifest.get("participantAssignments")
+    participant = next((
+        row for row in participants
+        if isinstance(row, Mapping)
+        and row.get("participantRef") == identity.participant_ref
+    ), None) if isinstance(participants, list) else None
+    assignment = metadata.get("modelAssignment")
+    try:
+        duty_role = role_for_duty(job.duty_id)
+    except RoleCatalogError:
+        duty_role = ""
+    if isinstance(assignment, Mapping):
+        try:
+            parsed_assignment = agent_model_assignment_from_payload(assignment)
+        except AgentInvocationError as exc:
+            errors.append(str(exc))
+        else:
+            errors.extend(
+                "jobs file " + error
+                for error in v2_role_assignment_authority_errors(
+                    manifest,
+                    role_execution_ref=identity.role_execution_ref,
+                    participant_ref=identity.participant_ref,
+                    assignment=parsed_assignment,
+                )
+            )
+    if (
+        not isinstance(execution, Mapping)
+        or not isinstance(participant, Mapping)
+        or not isinstance(assignment, Mapping)
+        or execution.get("participantRef") != job.participant_ref
+        or execution.get("executionLabel") != job.execution_label
+        or execution.get("role") != job.role
+        or execution.get("role") != duty_role
+        or execution.get("provider") != job.provider
+        or assignment.get("modelExecutionValue") != job.model_execution_value
+        or metadata.get("dispatchKind") != job.dispatch_kind
+    ):
+        errors.append("jobs file v2 identity does not match role execution authority")
+    return errors
+
+
+def _validate_v2_jobs_file_authority(
+    manifest: Mapping[str, Any], jobs: Sequence[WorkerJob]
+) -> None:
+    if (
+        manifest.get("schemaVersion") != "2.0"
+        or manifest.get("executionIdentityVersion") != 2
+    ):
+        return
+    _validate_agent_invocations(manifest, jobs)
+    errors: list[str] = []
+    for job in jobs:
+        metadata = load_json_object(job.prompt_metadata_path, "agent metadata")
+        errors.extend(
+            f"{job.worker_id}: {error}"
+            for error in _v2_job_authority_errors(job, metadata, manifest)
+        )
+    if errors:
+        raise DispatchError("jobs file v2 authority: " + "; ".join(errors))
+    role_executions = {
+        string_value(row.get("roleExecutionRef")): row
+        for row in manifest.get("roleExecutions") or []
+        if isinstance(row, Mapping)
+    }
+    if any(
+        isinstance(role_executions.get(job.role_execution_ref), Mapping)
+        and role_executions[job.role_execution_ref].get("role") == "translator"
+        for job in jobs
+    ):
+        raise DispatchError(
+            "jobs file translator must use canonical reservation dispatch"
+        )
+
+
 def worker_jobs_from_file(
     project_root: Path,
     jobs_file: Path,
@@ -940,7 +1695,7 @@ def worker_jobs_from_file(
     workers = payload.get("workers")
     if not isinstance(workers, list):
         raise DispatchError("jobs file workers must be an array")
-    return [
+    jobs = [
         _worker_job_from_file(
             project_root,
             item,
@@ -954,6 +1709,8 @@ def worker_jobs_from_file(
         for item in workers
         if isinstance(item, Mapping)
     ]
+    _validate_v2_jobs_file_authority(manifest, jobs)
+    return jobs
 
 
 def _worker_job_from_file(
@@ -967,8 +1724,17 @@ def _worker_job_from_file(
     resolve_wrapper: Callable[[str], Path],
     default_provider: Callable[[str], str],
 ) -> WorkerJob:
-    worker_id = require_string(item, "workerId")
-    provider = string_value(item.get("provider")) or default_provider(worker_id)
+    identity = worker_execution_identity(item)
+    worker_id = (
+        require_string(item, "workerId")
+        if identity is None
+        else v2_worker_state_key(item)
+    )
+    provider = (
+        string_value(item.get("provider")) or default_provider(worker_id)
+        if identity is None
+        else require_string(item, "provider")
+    )
     prompt_path = resolve_project_path(
         project_root, require_string(item, "promptPath")
     )
@@ -1006,6 +1772,10 @@ def _worker_job_from_file(
         role=require_string(item, "role"),
         idle_timeout_seconds=idle_timeout_seconds,
         dispatch_kind=dispatch_kind,
+        # Minted here, not read from the file: the lead writes this file by
+        # hand, and a session id it typed would be unfalsifiable — nothing can
+        # tell an id that names no session from one that names the wrong one.
+        session_id=dispatch_session_id(provider),
         invocation_id=string_value(item.get("invocationId")),
         audience=string_value(item.get("audience")),
         assignment_ref=string_value(item.get("assignmentRef")),
@@ -1020,9 +1790,52 @@ def _worker_job_from_file(
         prompt_digest=string_value(digest_values.get("promptDigest")),
         host_model_value=host_model_value,
         enforcement_mode=string_value(item.get("enforcementMode")),
+        **(identity or {}),
     )
 
 
+def worker_execution_identity(
+    item: Mapping[str, Any],
+) -> dict[str, Any] | None:
+    identity_keys = {
+        "executionIdentityVersion",
+        "participantRef",
+        "roleExecutionRef",
+        "executionLabel",
+        "dutyId",
+        "invocationRef",
+    }
+    schema = item.get("schemaVersion")
+    has_v2_fields = bool(identity_keys.intersection(item))
+    if schema in (None, 1, "1", "1.0"):
+        if has_v2_fields:
+            raise DispatchError("jobs file worker mixes v1 and v2 identity")
+        return None
+    if schema != "2.0" or item.get("executionIdentityVersion") != 2:
+        raise DispatchError("jobs file worker has unsupported identity version")
+    if "workerId" in item:
+        raise DispatchError("jobs file worker mixes v1 and v2 identity")
+    attempt = item.get("attempt")
+    if not isinstance(attempt, int) or isinstance(attempt, bool) or attempt < 1:
+        raise DispatchError("jobs file v2 attempt must be positive")
+    return {
+        "participant_ref": require_string(item, "participantRef"),
+        "role_execution_ref": require_string(item, "roleExecutionRef"),
+        "execution_label": require_string(item, "executionLabel"),
+        "duty_id": require_string(item, "dutyId"),
+        "invocation_ref": require_string(item, "invocationRef"),
+        "attempt": attempt,
+    }
+
+
+def v2_worker_state_key(item: Mapping[str, Any]) -> str:
+    assignment_ref = require_string(item, "assignmentRef")
+    worker_id = assignment_ref.rsplit("/", 1)[-1]
+    if not worker_id:
+        raise DispatchError("jobs file v2 assignmentRef has no worker projection")
+    return worker_id
+
+
 def utc_now() -> str:
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")