okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/dispatch_state.py

@@ -32,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,
@@ -45,6 +55,15 @@ 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_CMUX_PANE = "cmux-pane"
@@ -104,6 +123,10 @@ 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
@@ -137,6 +160,12 @@ class WorkerJob:
     # 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]:
@@ -152,6 +181,11 @@ 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
@@ -164,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,
@@ -178,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,
@@ -190,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 {
@@ -438,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,
@@ -450,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))
@@ -478,12 +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")
-    # One verified record per invocation: the conflict guard below refuses a
-    # second write under this id, so this path never numbers a retry.
-    dispatch_id = build_dispatch_id(invocation_id, 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,
@@ -496,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", [])
@@ -515,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(
@@ -538,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 = [
@@ -554,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")
@@ -591,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,
@@ -1045,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,
@@ -1064,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,
@@ -1078,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(
@@ -1091,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")
     )
@@ -1148,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")