Skip to content

aiskillstore/marketplace / pending/cagdasyurekli/agy-worker

agy-worker

Unverified

Use when Codex or Claude Code should delegate repository exploration or implementation to Google Antigravity CLI (agy), then review, verify, repair, and deliver the result.

FileKindSize
README.mdmarkdown3.7 KB
SKILL.mdskill md12.5 KB
agents/openai.yamlconfig397 B
references/PROJECT_LIFECYCLE_AND_VERIFICATION.mdmarkdown25.6 KB
references/SECURITY_AND_COMPATIBILITY.mdmarkdown16.9 KB
references/TROUBLESHOOTING.mdmarkdown13.3 KB
runtime/agy-worker.shexecutablescript58.1 KB
runtime/delegation-policy.shexecutablescript293 B
runtime/doctor.shexecutablescript16.5 KB
runtime/evidence-report.shexecutablescript267 B
runtime/ground-truth.shexecutablescript2.9 KB
runtime/job.shexecutablescript266 B
runtime/model-selection.shexecutablescript262 B
runtime/qa-gate.shexecutablescript28.7 KB
runtime/schemas/delegation-policy.schema.jsonconfig2.6 KB
runtime/schemas/evidence-receipt.schema.jsonconfig2.5 KB
runtime/schemas/job-state.schema.jsonconfig3.6 KB
runtime/schemas/model-selection.schema.jsonconfig8.3 KB
runtime/schemas/worker-result.provider.schema.jsonconfig2.1 KB
runtime/schemas/worker-result.schema.jsonconfig3.0 KB
runtime/schemas/workflow-state.schema.jsonconfig3.7 KB
runtime/scripts/agy_dispatch.pyexecutablescript344.5 KB
runtime/scripts/agy_dispatch_containment.pyscript51.4 KB
runtime/scripts/agy_dispatch_verification.pyscript33.9 KB
runtime/scripts/agy_dispatch_worktree.pyscript220.6 KB
runtime/scripts/candidate_state.pyexecutablescript47.4 KB
runtime/scripts/delegation_policy.pyexecutablescript12.8 KB
runtime/scripts/evidence_receipt.pyexecutablescript52.9 KB
runtime/scripts/evidence_report.pyexecutablescript17.7 KB
runtime/scripts/job_lifecycle.pyexecutablescript89.0 KB
runtime/scripts/launch_authority.pyscript27.4 KB
runtime/scripts/model_selection.pyexecutablescript38.8 KB
runtime/scripts/transmission_preview.pyexecutablescript744 B
runtime/scripts/validate-envelope.pyexecutablescript6.5 KB
runtime/scripts/workflow.pyexecutablescript89.2 KB
runtime/verify-job.shexecutablescript261 B
runtime/workflow.shexecutablescript239 B
scripts/resolve-pipeline.shexecutablescript5.9 KB
skill-report.jsonconfig552.7 KB

runtime/scripts/agy_dispatch.py

View on GitHub
#!/usr/bin/env python3
"""Progress-aware local supervisor for one agy worker conversation.

This is a local process lifecycle, not an agy/provider status API.  The controller
owns one agy process group, consumes bounded stream-json incrementally, and publishes
only sanitized control state.  Raw streams and prompts remain in the owner-private
job directory.
"""

from __future__ import annotations

import argparse
import contextlib
from concurrent.futures import ThreadPoolExecutor
import dataclasses
import fcntl
import hashlib
from functools import partial
import json
import math
import os
from pathlib import Path
import re
import selectors
import signal
import shutil
import stat
import subprocess
import sys
import time
from typing import Callable, Mapping, TypedDict, TypeVar, AbstractSet, Any, Iterator, NamedTuple, NoReturn, IO, cast

sys.dont_write_bytecode = True

SCRIPT_DIR = Path(__file__).resolve().parent
if str(SCRIPT_DIR) not in sys.path:
    sys.path.insert(0, str(SCRIPT_DIR))

import agy_dispatch_verification as SELF_VERIFICATION  # noqa: E402 -- sibling imports follow startup isolation/path setup
import agy_dispatch_containment as CONTAINMENT  # noqa: E402 -- sibling imports follow startup isolation/path setup
import agy_dispatch_worktree as WORKTREE  # noqa: E402 -- sibling imports follow startup isolation/path setup
import candidate_state as CANDIDATE_STATE  # noqa: E402 -- shared hardened Git reads


# Compatibility names share the implementation and exception identities owned by WORKTREE.
MODEL_SELECTION = WORKTREE.MODEL_SELECTION
LAUNCH_AUTHORITY = WORKTREE.LAUNCH_AUTHORITY
DispatchError = WORKTREE.DispatchError
WorktreeBaselineError = WORKTREE.WorktreeBaselineError
ResolveUndoPresentError = WORKTREE.ResolveUndoPresentError
canonical = WORKTREE.canonical
digest = WORKTREE.digest
_identity = WORKTREE._identity
_parse_resolve_undo = WORKTREE._parse_resolve_undo
_bound_git_worktree_root = WORKTREE._bound_git_worktree_root
_bounded_git_read = WORKTREE._bounded_git_read
_build_selected_content_manifest = WORKTREE._build_selected_content_manifest
_canonical_digest = WORKTREE._canonical_digest
_cleanup_stage = WORKTREE._cleanup_stage
_compute_transmission_sha256 = WORKTREE._compute_transmission_sha256
_compute_v11_launch_approval_sha256 = WORKTREE._compute_v11_launch_approval_sha256
_confirm_safe_git_executable = WORKTREE._confirm_safe_git_executable
_fixed_git_read_argv = WORKTREE._fixed_git_read_argv
_full_stat_binding = WORKTREE._full_stat_binding
_git_boundary_identity = WORKTREE._git_boundary_identity
_manifest_digest = WORKTREE._manifest_digest
_marker_only_preflight = WORKTREE._marker_only_preflight
_materialize_stage = WORKTREE._materialize_stage
_parse_provider_scope = WORKTREE._parse_provider_scope
_project_boundary = WORKTREE._project_boundary
_read_provider_scope_file = partial(WORKTREE._read_provider_scope_file, error_type=WORKTREE.DispatchError)
_reconcile_stage_to_source = WORKTREE._reconcile_stage_to_source
_recover_reconciliation = WORKTREE._recover_reconciliation
_resolved_path_is_git_administration = WORKTREE._resolved_path_is_git_administration
_safe_git_executable = WORKTREE._safe_git_executable
_safe_git_is_outside_worktree = WORKTREE._safe_git_is_outside_worktree
_safe_git_owner_mode = WORKTREE._safe_git_owner_mode
_scan_readable_worktree = WORKTREE._scan_readable_worktree
_scan_stage_mutations = WORKTREE._scan_stage_mutations
_selected_content_digest = WORKTREE._selected_content_digest
_stable_git_authority = WORKTREE._stable_git_authority
_validate_manifest = WORKTREE._validate_manifest
_validate_scope_against_worktree = WORKTREE._validate_scope_against_worktree
_worktree_git_admin_alias_boundary = WORKTREE._worktree_git_admin_alias_boundary
_worktree_snapshot = WORKTREE._worktree_snapshot
_worktree_symlink_boundary = WORKTREE._worktree_symlink_boundary
whole_worktree_content_manifest = WORKTREE.whole_worktree_content_manifest
_MarkerPreflightLimit = WORKTREE._MarkerPreflightLimit
_FIXED_GIT_READ_ARGV = WORKTREE._FIXED_GIT_READ_ARGV

class _VerificationAPI:
    """Expose dispatcher dependencies to the optional verification adapter."""

    def __getattr__(self, name: str) -> Any:
        return globals()[name]


VERIFICATION_API = _VerificationAPI()

STATE_NAME = "dispatch-state.json"
COMMAND_NAME = "dispatch-command.json"
LOCK_NAME = ".dispatch.lock"
STATE_LOCK_NAME = ".dispatch-state.lock"
MAX_STATE_BYTES = 128 * 1024
MAX_COMMAND_BYTES = 512 * 1024
MAX_VERIFICATION_BYTES = 16 * 1024
MAX_CHECK_ITEMS = 32
MAX_CHECK_LABEL = 160
MAX_CHECK_SUMMARY = 512
MAX_BOUNDARY_ENTRIES = WORKTREE.MAX_BOUNDARY_ENTRIES
MAX_INLINE_PROMPT_BYTES = 100000
MAX_STREAM_BYTES = WORKTREE.MAX_STREAM_BYTES
MAX_EVENT_BYTES = 1024 * 1024
MAX_STATUS_WAIT = 60.0
TERM_GRACE = WORKTREE.TERM_GRACE
CONTROL_POLL = 0.20
CONVERSATION_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}")
JOB_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,79}")
SHA_RE = re.compile(r"[0-9a-f]{64}")
COMMIT_RE = re.compile(r"[0-9a-f]{40}|[0-9a-f]{64}")
CURRENT_COMMAND_FIELDS = {
    'launch_authority',
    'launch_approval_sha256',
    'agy_version',
    'agy_version_observed',
    'allow_scoped_repair',
    'allow_self_verification',
    'approved_transmission_sha256',
    'approved_whole_worktree_sha256',
    'argv',
    'base_commit',
    'child_umask',
    'continue_prompt',
    'hard_seconds',
    'idle_seconds',
    'job_id',
    'kind',
    'max_cycles',
    'max_seconds',
    'native_grant_profile',
    'notice_seconds',
    'provider_env',
    'provider_isolation',
    'provider_scope_identity',
    'provider_scope_path',
    'provider_scope_sha256',
    'repair_authority_sha256',
    'resume_prompt',
    'schema_version',
    'selection_identity',
    'selection_path',
    'selection_sha256',
    'self_verification_manifest_identity',
    'self_verification_manifest_path',
    'self_verification_manifest_sha256',
    'stage_dir',
    'stage_file',
    'whole_worktree_content_sha256',
    'workdir',
    'workflow',
}
SCOPED_REPAIR_POLICY_TEXT = (
    "Scoped repair may transmit only controller-reconciled descendants under the "
    "unchanged initial scope, selection, workflow, provider environment, cycle, and time limits."
)
SCOPED_REPAIR_POLICY_SHA256 = hashlib.sha256(
    SCOPED_REPAIR_POLICY_TEXT.encode("utf-8")
).hexdigest()
CURRENT_STATE_FIELDS = {
    'source_checkout_guard',
    'initial_content_transmission_sha256',
    'agy_returncode',
    'allow_scoped_repair',
    'allow_self_verification',
    'approved_transmission_sha256',
    'assurance',
    'attempt',
    'attempt_base_elapsed',
    'attempt_origin',
    'cancel_requested',
    'candidate_recognized',
    'candidate_source',
    'candidate_worktree_entries',
    'candidate_worktree_path_facts',
    'candidate_worktree_sha256',
    'canonical_schema_identity',
    'canonical_schema_sha256',
    'check_counts',
    'check_summary',
    'command_identity',
    'command_sha256',
    'continue_available',
    'controller_pid',
    'conversation_id',
    'created_epoch',
    'cycle',
    'driver_disposition',
    'elapsed_seconds',
    'exit_code',
    'failure_stage',
    'finished_epoch',
    'hard_seconds',
    'idle_seconds',
    'job_id',
    'kind',
    'last_activity',
    'last_progress_epoch',
    'last_success_identity',
    'last_success_path',
    'last_success_sha256',
    'limit_kind',
    'max_cycles',
    'max_seconds',
    'native_grant_profile',
    'next_action',
    'next_action_command',
    'notice_count',
    'phase',
    'previous_state_sha256',
    'progress_count',
    'project_boundary',
    'provider_isolation',
    'provider_schema_identity',
    'provider_schema_sha256',
    'provider_scope_identity',
    'provider_scope_path',
    'provider_scope_sha256',
    'provider_stage_identity',
    'provider_stage_manifest_sha256',
    'provider_stage_path',
    'provider_terminal_status',
    'reason',
    'reconciliation_manifest_sha256',
    'remote_cancel_unverified',
    'repair_authority_sha256',
    'repair_lineage_attempt',
    'repair_lineage_sha256',
    'repair_parent_result_sha256',
    'repair_parent_worktree_sha256',
    'result_available',
    'result_identity',
    'result_path',
    'result_sha256',
    'resume_available',
    'schema_version',
    'selected_content_sha256',
    'selected_file_count',
    'selected_tree_count',
    'selection_identity',
    'selection_sha256',
    'self_verification_elapsed_seconds',
    'self_verification_return_phase',
    'self_verification_run',
    'self_verification_started_epoch',
    'sequence',
    'stage_identity',
    'stage_sha256',
    'started_epoch',
    'status',
    'stderr_path',
    'stream_path',
    'transmission_sha256',
    'updated_epoch',
    'verification_identity',
    'verification_path',
    'verification_sha256',
    'whole_worktree_content_sha256',
    'workdir',
    'workflow',
    'worktree_baseline',
    'worktree_changed_since_dispatch',
    'worktree_changes_present',
    'worktree_reconciliation',
    'worktree_root_identity',
    'worktree_snapshot_algorithm',
}
PUBLIC_LAUNCHER = '"$PIPELINE/agy-worker.sh"'
CURRENT_STATE_SCHEMA = 21
CURRENT_COMMAND_SCHEMA = 16
LAST_DOCUMENTED_LEGACY_SCHEMA_RELEASE = "v0.22.0"
WORKTREE_SNAPSHOT_SEMANTIC_V1 = "semantic-v1"
CURRENT_WORKTREE_SNAPSHOT_ALGORITHM = WORKTREE_SNAPSHOT_SEMANTIC_V1
FAILURE_STAGES = {
    "framing", "outer_status", "missing_structured_output", "schema_rejection",
    "binding_failure", "selection_preflight",
}
FAILURE_STAGES.update(
    f"launch_authority_changed:{field}" for field in LAUNCH_AUTHORITY.AUTHORITY_FIELDS
)
FAILURE_STAGES.update(f"launch_authority_changed:content.{field}" for field in (
    "manifest_sha256", "policy_sha256", "selected_content_sha256", "content_manifest_sha256",
    "provider_isolation", "native_grant_profile"))
LIFECYCLE_PHASES = {
    "dispatching", "awaiting-verification", "repairing", "completed",
    "blocked", "attempt-failed", "repair-failed", "self-verifying",
}
TERMINAL = {"succeeded", "failed", "cancelled", "orphaned"}
REASONS = {
    "provider_timeout", "idle_timeout", "hard_deadline_exceeded",
    "authentication_failed", "provider_unavailable", "status_unavailable",
    "resume_failed", "cancelled", "agy_failed_unclassified",
    "permission_required", "empty_output", "invalid_envelope",
    "output_oversized", "interrupted",
    "provider_terminal_error", "provider_terminal_cancelled",
    "selection_preflight_failed", "model_selection_rejected", "resolve_undo_present",
    "native_host_sandbox_unavailable",
    "source_checkout_changed", "source_checkout_guard_unavailable",
}
EXIT_BY_REASON = {
    "empty_output": 3,
    "invalid_envelope": 4,
    "agy_failed_unclassified": 5,
    "permission_required": 6,
    "idle_timeout": 9,
    "hard_deadline_exceeded": 16,
    "provider_timeout": 17,
    "authentication_failed": 18,
    "provider_unavailable": 19,
    "status_unavailable": 20, "resolve_undo_present": 20,
    "resume_failed": 21,
    "cancelled": 22,
    "output_oversized": 23,
    "provider_terminal_error": 25,
    "selection_preflight_failed": 26,
    "model_selection_rejected": 26,
    "native_host_sandbox_unavailable": 27,
    "source_checkout_changed": 28, "source_checkout_guard_unavailable": 29,
    "provider_terminal_cancelled": 22,
    "interrupted": 143,
}

MODEL_SELECTION_REJECTED_MESSAGE = (
    "AGY rejected the model/effort selection. Check `agy models` and the "
    "`--model`/`--effort` pair before starting a new job."
)

SOURCE_GUARD_MESSAGES = {
    "source_checkout_changed": (
        "The source checkout changed since the job baseline — by the provider or another process; inspect it and start a new job."
    ),
    "source_checkout_guard_unavailable": (
        "The source checkout guard could not complete within its bounded checks or its source binding is unavailable. "
        "Inspect the source checkout and its Git configuration; reduce large dirty or non-ignored untracked content, "
        "or use a smaller dedicated source checkout, then start a new job."
    ),
}


class SourceGuardError(DispatchError):
    """A deferred source proof failed when its retained candidate was next used."""

    def __init__(self, reason: str) -> None:
        super().__init__(SOURCE_GUARD_MESSAGES[reason])
        self.reason = reason


class SelectionPreflightError(DispatchError):
    """A direct caller selection could not be safely reprobed for one launch."""


class Parser(argparse.ArgumentParser):
    def error(self, message: str) -> NoReturn:
        del message
        self.print_usage(sys.stderr)
        self.exit(64, "agy-dispatch: invalid arguments\n")


def _provider_isolation_for_command(command: dict[str, Any]) -> str:
    """Read the current command's explicit execution mode."""
    _require_supported_schema(command, label="dispatch command", supported=(CURRENT_COMMAND_SCHEMA,))
    mode = command.get("provider_isolation")
    if mode not in {"session", "native"}:
        raise DispatchError("dispatch provider isolation is invalid")
    return mode


def scoped_repair_authority_sha256(
    command: dict[str, Any], *, verification_binding_sha256: str | None = None,
) -> str | None:
    """Derive the immutable opt-in grant; future verification binds at creation."""
    if not command.get("allow_scoped_repair", False):
        return None
    if verification_binding_sha256 is not None and (
        not isinstance(verification_binding_sha256, str)
        or SHA_RE.fullmatch(verification_binding_sha256) is None
    ):
        raise DispatchError("repair verification binding is invalid")
    payload = {
        "kind": "agy-worker-scoped-repair-authority-v1",
        "policy_sha256": SCOPED_REPAIR_POLICY_SHA256,
        "initial_launch_approval_sha256": command.get("launch_approval_sha256"),
        "provider_scope_sha256": command.get("provider_scope_sha256"),
        "selection_sha256": command.get("selection_sha256"),
        "agy_version": command.get("agy_version"),
        "argv_sha256": digest(canonical(command.get("argv"))),
        "provider_env": command.get("provider_env"),
        "workflow": command.get("workflow"),
        "max_cycles": command.get("max_cycles"),
        "idle_seconds": command.get("idle_seconds"),
        "hard_seconds": command.get("hard_seconds"),
        "max_seconds": command.get("max_seconds"),
        "verification_binding_sha256": verification_binding_sha256,
    }
    payload["provider_isolation"] = command.get("provider_isolation")
    payload["native_grant_profile"] = command.get("native_grant_profile")
    return digest(canonical(payload))


def self_verification_binding_sha256(command: dict[str, Any]) -> str | None:
    """Bind the immutable private manifest fields without opening its bytes."""
    if not command.get("allow_self_verification", False):
        return None
    return digest(canonical({
        "kind": "agy-worker-self-verification-binding-v1",
        "manifest_path": command.get("self_verification_manifest_path"),
        "manifest_sha256": command.get("self_verification_manifest_sha256"),
        "manifest_identity": command.get("self_verification_manifest_identity"),
    }))


def _repair_authority_for_command(command: dict[str, Any]) -> str | None:
    """Compute repair authority with the command's optional manifest binding."""
    return scoped_repair_authority_sha256(
        command,
        verification_binding_sha256=self_verification_binding_sha256(command),
    )


def _duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    result: dict[str, Any] = {}
    for key, value in pairs:
        if key in result:
            raise DispatchError("JSON contains duplicate fields")
        result[key] = value
    return result


def _invalid_json_constant(_value: str) -> None:
    raise DispatchError("JSON contains a non-finite number")


def parse_json(raw: bytes, label: str) -> Any:
    try:
        return json.loads(
            raw.decode("utf-8", "strict"), object_pairs_hook=_duplicates,
            parse_constant=_invalid_json_constant,
        )
    except (UnicodeError, json.JSONDecodeError, DispatchError, RecursionError) as exc:
        raise DispatchError(f"{label} is invalid") from exc


def _valid_max_cycles(workflow: str, value: Any) -> bool:
    if type(value) is not int:
        return False
    if workflow == "legacy":
        return value == 1
    if workflow in {"explore", "task"}:
        return 1 <= value <= 2
    return workflow == "project" and 1 <= value <= 5


def canonical_job(path: Path) -> Path:
    if not path.is_absolute() or Path(os.path.realpath(path)) != path:
        raise DispatchError("job directory must be one canonical absolute path")
    try:
        info = path.lstat()
    except OSError as exc:
        raise DispatchError("job directory is unavailable") from exc
    if (
        not stat.S_ISDIR(info.st_mode)
        or stat.S_ISLNK(info.st_mode)
        or info.st_uid != os.getuid()
        or stat.S_IMODE(info.st_mode) != 0o700
    ):
        raise DispatchError("job directory must be owner-private")
    return path


def _job_is_inside_worktree(job: Path, workdir: str | Path) -> bool:
    try:
        job_text = os.fsdecode(job)
        workdir_text = os.fsdecode(workdir)
        if "\0" in job_text or "\0" in workdir_text:
            return True
        resolved_job = Path(os.path.realpath(job_text))
        resolved_workdir = Path(os.path.realpath(workdir_text))
        if resolved_job == resolved_workdir:
            return True
        return os.path.commonpath([resolved_workdir, resolved_job]) == str(resolved_workdir)
    except (TypeError, UnicodeError, ValueError, OSError):
        return True


def read_regular(
    path: Path, maximum: int, label: str, *, allowed_modes: tuple[int, ...] = (0o600,),
) -> tuple[bytes, os.stat_result]:
    try:
        initial = path.lstat()
        descriptor = os.open(
            path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0),
        )
    except OSError as exc:
        raise DispatchError(f"{label} is unavailable") from exc
    try:
        info = os.fstat(descriptor)
        if (
            not stat.S_ISREG(info.st_mode)
            or info.st_uid != os.getuid()
            or stat.S_IMODE(info.st_mode) not in allowed_modes
            or info.st_nlink != 1
        ):
            raise DispatchError(f"{label} must be one owner-private regular file")
        if WORKTREE._manifest_binding(initial) != WORKTREE._manifest_binding(info):
            raise DispatchError(f"{label} identity changed")
        if info.st_size > maximum:
            raise DispatchError(f"{label} is oversized")
        chunks: list[bytes] = []
        remaining = info.st_size
        while remaining:
            chunk = os.read(descriptor, min(65536, remaining))
            if not chunk:
                raise DispatchError(f"{label} identity changed")
            chunks.append(chunk)
            remaining -= len(chunk)
        if os.read(descriptor, 1):
            raise DispatchError(f"{label} identity changed")
        after = os.fstat(descriptor)
    finally:
        os.close(descriptor)
    try:
        named = path.lstat()
    except OSError as exc:
        raise DispatchError(f"{label} identity changed") from exc
    if WORKTREE._manifest_binding(info) != WORKTREE._manifest_binding(after) or (
        WORKTREE._manifest_binding(after) != WORKTREE._manifest_binding(named)
    ):
        raise DispatchError(f"{label} identity changed")
    return b"".join(chunks), named


def _bound_self_verification_manifest(
    command: dict[str, Any], job: Path | None = None,
) -> SELF_VERIFICATION.Manifest | None:
    """Reopen, bind, and parse the exact private manifest in its job."""
    if not command.get("allow_self_verification", False):
        return None
    path = Path(command["self_verification_manifest_path"])
    bound_job = path.parent if job is None else job
    try:
        canonical_path = Path(os.path.realpath(path))
    except OSError as exc:
        raise DispatchError("self-verification manifest is unavailable") from exc
    if (
        canonical_path != path
        or path.parent != bound_job
        or _job_is_inside_worktree(bound_job, command["workdir"])
    ):
        raise DispatchError("self-verification manifest path is invalid")
    raw, info = read_regular(path, MAX_COMMAND_BYTES, "self-verification manifest")
    if (
        digest(raw) != command["self_verification_manifest_sha256"]
        or list(_identity(info)) != command["self_verification_manifest_identity"]
    ):
        raise DispatchError("self-verification manifest binding changed")
    try:
        parsed = SELF_VERIFICATION.parse_manifest(raw)
        SELF_VERIFICATION.validate_runtime(parsed, Path(command["workdir"]))
        return parsed
    except SELF_VERIFICATION.VerificationError as exc:
        raise DispatchError("self-verification manifest is invalid") from exc


def write_atomic(job: Path, name: str, value: Any) -> tuple[bytes, str]:
    raw = canonical(value)
    temporary = job / f".{name}.{os.getpid()}.{time.monotonic_ns()}.tmp"
    descriptor = os.open(
        temporary,
        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
        0o600,
    )
    try:
        os.fchmod(descriptor, 0o600)
        view = memoryview(raw)
        while view:
            written = os.write(descriptor, view)
            if written <= 0:
                raise DispatchError("state write failed")
            view = view[written:]
        os.fsync(descriptor)
    finally:
        os.close(descriptor)
    os.replace(temporary, job / name)
    parent = os.open(job, os.O_RDONLY | getattr(os, "O_DIRECTORY", 0))
    try:
        os.fsync(parent)
    finally:
        os.close(parent)
    return raw, digest(raw)


@contextlib.contextmanager
def lifecycle_lock(job: Path, *, blocking: bool) -> Iterator[int]:
    _check_existing_dispatch_schemas(job)
    path = job / LOCK_NAME
    descriptor = os.open(
        path,
        os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0),
        0o600,
    )
    try:
        os.fchmod(descriptor, 0o600)
        operation = fcntl.LOCK_EX | (0 if blocking else fcntl.LOCK_NB)
        try:
            fcntl.flock(descriptor, operation)
        except BlockingIOError as exc:
            raise DispatchError("dispatch controller is active") from exc
        yield descriptor
    finally:
        os.close(descriptor)


@contextlib.contextmanager
def state_lock(job: Path) -> Iterator[int]:
    """Serialize short state replacements without sharing controller ownership."""

    _check_existing_dispatch_schemas(job)
    path = job / STATE_LOCK_NAME
    descriptor = os.open(
        path,
        os.O_RDWR | os.O_CREAT | getattr(os, "O_NOFOLLOW", 0),
        0o600,
    )
    try:
        os.fchmod(descriptor, 0o600)
        fcntl.flock(descriptor, fcntl.LOCK_EX)
        yield descriptor
    finally:
        os.close(descriptor)


@contextlib.contextmanager
def inherited_lifecycle_lock(job: Path, descriptor: int) -> Iterator[int]:
    """Adopt the spawner's already-held lock without an unlock/relock gap."""

    try:
        info = os.fstat(descriptor)
        named = (job / LOCK_NAME).lstat()
    except OSError as exc:
        raise DispatchError("inherited dispatch ownership is unavailable") from exc
    if (
        not stat.S_ISREG(info.st_mode) or info.st_uid != os.getuid()
        or stat.S_IMODE(info.st_mode) != 0o600
        or _identity(info) != _identity(named)
    ):
        raise DispatchError("inherited dispatch ownership is invalid")
    try:
        yield descriptor
    finally:
        os.close(descriptor)


class UnsupportedSchemaError(DispatchError):
    """A fixed diagnostic for a record outside the supported schema boundary."""


def _require_supported_schema(
    value: Any, *, label: str, supported: tuple[int, ...],
) -> None:
    version = value.get("schema_version") if isinstance(value, dict) else None
    if type(version) is int and version in supported:
        return
    # Only bounded, retired positive integers enter a diagnostic. Never echo
    # arbitrary JSON values, strings, or unbounded/future version numbers.
    found = f"v{version}" if type(version) is int and 0 < version < max(supported) else "invalid or unsupported"
    expected = " or ".join(f"v{item}" for item in supported)
    raise UnsupportedSchemaError(
        f"{label} schema {found} is not supported by this agy-worker release; "
        f"supported: {expected}. Finish or discard the job with the "
        "release that created it."
    )


def _check_existing_command_schema(job: Path) -> None:
    """Reject retired commands before a state reader can recover or project."""
    try:
        raw, _info = read_regular(job / COMMAND_NAME, MAX_COMMAND_BYTES, "dispatch command")
        value = parse_json(raw, "dispatch command")
    except (OSError, DispatchError):
        # Preserve the existing handling of missing/corrupt command artifacts.
        # Their full binding remains owned by the ordinary command binder.
        return
    _require_supported_schema(value, label="dispatch command", supported=(CURRENT_COMMAND_SCHEMA,))


def _check_existing_dispatch_schemas(job: Path) -> None:
    """Reject decoded unsupported records before creating or chmodding locks.

    This bounded read is only an early rejection, never transition authority.
    Callers still reload and fully validate under their existing locks. Missing
    or corrupt bytes retain the ordinary reader's existing error handling.
    """
    try:
        raw, _info = read_regular(job / STATE_NAME, MAX_STATE_BYTES, "dispatch state")
        value = parse_json(raw, "dispatch state")
    except (OSError, DispatchError):
        pass
    else:
        _require_supported_schema(value, label="dispatch state", supported=(CURRENT_STATE_SCHEMA,))
    _check_existing_command_schema(job)


def load_state(job: Path) -> tuple[DispatchState, bytes, str]:
    raw, _info = read_regular(job / STATE_NAME, MAX_STATE_BYTES, "dispatch state")
    value = parse_json(raw, "dispatch state")
    value = validate_state(value)
    _check_existing_command_schema(job)
    return value, raw, digest(raw)


def read_state_snapshot(job: Path) -> tuple[DispatchState, bytes, str]:
    """Read one strict state snapshot without racing an approved replacement."""

    with state_lock(job):
        return load_state(job)


def load_command(job: Path) -> tuple[dict[str, Any], bytes, tuple[int, int, int, int, int]]:
    raw, info = read_regular(job / COMMAND_NAME, MAX_COMMAND_BYTES, "dispatch command")
    value = parse_json(raw, "dispatch command")
    _require_supported_schema(value, label="dispatch command", supported=(CURRENT_COMMAND_SCHEMA,))
    if not isinstance(value, dict):
        raise DispatchError("dispatch command fields are invalid")
    if set(value) != CURRENT_COMMAND_FIELDS:
        raise DispatchError("dispatch command fields are invalid")
    if raw != canonical(value):
        raise DispatchError("dispatch command is not canonical")
    if value["kind"] != "agy-worker-dispatch-command":
        raise DispatchError("dispatch command version is invalid")
    try:
        if (LAUNCH_AUTHORITY.approval_sha256(value["launch_authority"])
                != value["launch_approval_sha256"]
                or value["launch_approval_sha256"] != (
                    value["approved_transmission_sha256"]
                    if value["provider_scope_path"] is not None
                    else value["approved_whole_worktree_sha256"])):
            raise DispatchError("dispatch launch approval binding changed")
    except (LAUNCH_AUTHORITY.LaunchAuthorityError, TypeError, AttributeError) as exc:
        raise DispatchError("dispatch launch authority is invalid") from exc
    version = value["agy_version"]
    if (not isinstance(version, str) or not version or len(version.encode("utf-8")) > 128
            or any(ord(c) < 32 or ord(c) == 127 for c in version)):
        raise DispatchError("dispatch agy diagnostic version is invalid")
    if not isinstance(value["job_id"], str) or JOB_RE.fullmatch(value["job_id"]) is None:
        raise DispatchError("dispatch command job ID is invalid")
    if not isinstance(value["argv"], list) or not value["argv"] or any(
        not isinstance(item, str) or "\x00" in item for item in value["argv"]
    ):
        raise DispatchError("dispatch argv is invalid")
    if value["argv"][0] != "agy" or value["argv"].count("--print") != 1:
        raise DispatchError("dispatch argv contract is invalid")
    arguments = iter(value["argv"][1:])
    for argument in arguments:
        option = argument.partition("=")[0]
        if option in {
            "--agent", "--boost", "--approve-boost-risk-sha", "--persona",
            "--remote-control", "--input-format", "--project", "--new-project",
        }:
            raise DispatchError("dispatch argv contains a retired feature")
        if option in {
            "--dangerously-skip-permissions", "--log-file", "--continue", "-c",
            "--prompt-interactive", "-i", "--settings", "--remote-agent", "--prompt", "-p",
        }:
            raise DispatchError("dispatch argv contains an unapproved execution option")
        if "=" not in argument and option in {
            "--print", "--model", "--mode", "--json-schema", "--add-dir",
            "--conversation", "--print-timeout", "--output-format",
        }:
            next(arguments, None)
    if not isinstance(value["workdir"], str) or not Path(value["workdir"]).is_absolute():
        raise DispatchError("dispatch workdir is invalid")
    for key in ("idle_seconds", "hard_seconds", "max_seconds", "notice_seconds"):
        if type(value[key]) not in (int, float) or not (0 < value[key] <= 7 * 24 * 3600):
            raise DispatchError("dispatch duration is invalid")
    if not (value["idle_seconds"] <= value["hard_seconds"] <= value["max_seconds"]):
        raise DispatchError("dispatch duration order is invalid")
    for key in ("stage_dir", "stage_file"):
        if value[key] is not None and (
            not isinstance(value[key], str) or not Path(value[key]).is_absolute()
        ):
            raise DispatchError("dispatch stage path is invalid")
    if not isinstance(value["child_umask"], str) or re.fullmatch(r"[0-7]{3,4}", value["child_umask"]) is None:
        raise DispatchError("dispatch child umask is invalid")
    if not isinstance(value["resume_prompt"], str) or not value["resume_prompt"]:
        raise DispatchError("dispatch resume prompt is invalid")
    if not isinstance(value["continue_prompt"], str) or not value["continue_prompt"]:
        raise DispatchError("dispatch continue prompt is invalid")
    if not isinstance(value["provider_env"], list) or any(
        not isinstance(item, str) for item in value["provider_env"]
    ):
        raise DispatchError("dispatch provider environment is invalid")
    try:
        if MODEL_SELECTION.validate_child_environment_names(value["provider_env"]) != value["provider_env"]:
            raise DispatchError("dispatch provider environment is not canonical")
    except MODEL_SELECTION.EvidenceUnavailable as exc:
        raise DispatchError("dispatch provider environment is invalid") from exc
    if value["workflow"] not in {"legacy", "explore", "task", "project"}:
        raise DispatchError("dispatch workflow is invalid")
    base_commit = value["base_commit"]
    if base_commit is not None and (
        not isinstance(base_commit, str) or COMMIT_RE.fullmatch(base_commit) is None
    ):
        raise DispatchError("dispatch base commit is invalid")
    if value["provider_scope_path"] is not None and base_commit is not None:
        raise DispatchError("scoped dispatch cannot carry a whole-worktree base")
    if (value["provider_scope_path"] is None
            and value["workflow"] in {"task", "project"} and base_commit is None):
        raise DispatchError("whole-worktree task base is missing")
    if not _valid_max_cycles(value["workflow"], value["max_cycles"]):
        raise DispatchError("dispatch max cycles is invalid for workflow")
    if type(value["agy_version_observed"]) is not bool:
        raise DispatchError("dispatch agy version evidence is invalid")
    selection_path = value["selection_path"]
    selection_sha = value["selection_sha256"]
    selection_identity = value["selection_identity"]
    if (selection_path is None) != (selection_sha is None) or (selection_path is None) != (selection_identity is None):
        raise DispatchError("dispatch selection binding is incomplete")
    if selection_path is not None and (
        not isinstance(selection_path, str) or not Path(selection_path).is_absolute()
        or not isinstance(selection_sha, str) or SHA_RE.fullmatch(selection_sha) is None
        or not isinstance(selection_identity, list) or len(selection_identity) != 5
        or any(type(item) is not int or item < 0 for item in selection_identity)
    ):
        raise DispatchError("dispatch selection binding is invalid")
    scope_path = value.get("provider_scope_path")
    scope_sha = value.get("provider_scope_sha256")
    scope_identity = value.get("provider_scope_identity")
    approved_sha = value.get("approved_transmission_sha256")
    approved_whole_sha = value.get("approved_whole_worktree_sha256")
    if (scope_path is None) != (scope_sha is None) or (scope_path is None) != (scope_identity is None) or (scope_path is None) != (approved_sha is None):
        raise DispatchError("dispatch provider scope binding is incomplete")
    if scope_path is not None and (
        not isinstance(scope_path, str) or not Path(scope_path).is_absolute()
        or not isinstance(scope_sha, str) or SHA_RE.fullmatch(scope_sha) is None
        or not isinstance(scope_identity, list) or len(scope_identity) != 5
        or any(type(item) is not int or item < 0 for item in scope_identity)
        or not isinstance(approved_sha, str) or SHA_RE.fullmatch(approved_sha) is None
    ):
        raise DispatchError("dispatch provider scope binding is invalid")
    if scope_path is None:
        if not isinstance(approved_whole_sha, str) or SHA_RE.fullmatch(approved_whole_sha) is None:
            raise DispatchError("dispatch whole-worktree approval binding is invalid")
    elif approved_whole_sha is not None:
        raise DispatchError("dispatch transmission modes conflict")
    provider_isolation = value["provider_isolation"]
    if provider_isolation not in {"session", "native"}:
        raise DispatchError("dispatch provider isolation is invalid")
    native_grant_profile = value["native_grant_profile"]
    if not isinstance(native_grant_profile, str) or native_grant_profile not in {"baseline", "A", "B", "AB"} or (
        provider_isolation == "session" and native_grant_profile != "baseline"
    ):
        raise DispatchError("dispatch native grant profile is invalid")
    whole_content_sha = value["whole_worktree_content_sha256"]
    if scope_path is None:
        if not isinstance(whole_content_sha, str) or SHA_RE.fullmatch(whole_content_sha) is None:
            raise DispatchError("dispatch whole-worktree content binding is invalid")
    elif whole_content_sha is not None:
        raise DispatchError("scoped dispatch cannot carry whole-worktree content")
    sandbox_count = value["argv"].count("--sandbox")
    if provider_isolation == "session" and sandbox_count != 0:
        raise DispatchError("session dispatch cannot request AGY sandbox")
    if provider_isolation == "native" and (
        scope_path is None or sandbox_count != 1
    ):
        raise DispatchError("native dispatch must be scoped and sandboxed")
    if scope_path is not None and "--add-dir" in value["argv"]:
        raise DispatchError("narrow provider scope cannot grant an additional directory")
    allow_self_verification = value["allow_self_verification"]
    self_verification_fields = (
        value["self_verification_manifest_path"],
        value["self_verification_manifest_sha256"],
        value["self_verification_manifest_identity"],
    )
    if type(allow_self_verification) is not bool:
        raise DispatchError("dispatch self-verification choice is invalid")
    if allow_self_verification and value["workflow"] not in {"task", "project"}:
        raise DispatchError("dispatch self-verification workflow is invalid")
    if not allow_self_verification:
        if any(item is not None for item in self_verification_fields):
            raise DispatchError("disabled self-verification cannot carry a manifest")
    elif (
        value["workflow"] not in {"task", "project"}
        or not isinstance(self_verification_fields[0], str)
        or not Path(self_verification_fields[0]).is_absolute()
        or not isinstance(self_verification_fields[1], str)
        or SHA_RE.fullmatch(self_verification_fields[1]) is None
        or not isinstance(self_verification_fields[2], list)
        or len(self_verification_fields[2]) != 5
        or any(type(item) is not int or item < 0 for item in self_verification_fields[2])
    ):
        raise DispatchError("dispatch self-verification manifest binding is invalid")
    allow_repair = value["allow_scoped_repair"]
    repair_authority = value["repair_authority_sha256"]
    if type(allow_repair) is not bool:
        raise DispatchError("dispatch scoped repair choice is invalid")
    if not allow_repair:
        if repair_authority is not None:
            raise DispatchError("disabled scoped repair cannot carry authority")
    elif (
        scope_path is None
        or value["workflow"] not in {"task", "project"}
        or value["max_cycles"] < 2
        or not isinstance(repair_authority, str)
        or SHA_RE.fullmatch(repair_authority) is None
        or repair_authority != _repair_authority_for_command(value)
    ):
        raise DispatchError("dispatch scoped repair authority is invalid")
    _bound_self_verification_manifest(value, job)
    return value, raw, _identity(info)


def _require_initial_transmission_choice(command: dict[str, Any], origin: str) -> None:
    """Reject a fresh broad launch unless its exact manifest was approved."""
    if (
        origin == "initial"
        and command.get("provider_scope_path") is None
        and command.get("approved_whole_worktree_sha256") is None
    ):
        raise DispatchError("initial whole-worktree dispatch lacks explicit approval")


class FileAuthority(TypedDict):
    dev: int
    ino: int
    type: int
    mode: int
    uid: int
    gid: int


class RootIdentity(TypedDict):
    realpath: str
    dev: int
    ino: int


class GitMarkerIdentity(TypedDict):
    kind: str
    authority: FileAuthority
    content_sha256: str | None


class GitDirectoryIdentity(TypedDict):
    realpath: str
    authority: FileAuthority


class WorktreeRootIdentity(TypedDict):
    root: RootIdentity
    git_marker: GitMarkerIdentity
    git_dir: GitDirectoryIdentity
    common_dir: GitDirectoryIdentity
    object_format: str
    show_toplevel: str


class WorktreeBaseline(TypedDict):
    sha256: str
    entries: int


class CheckCounts(TypedDict):
    passed: int
    failed: int
    advisory: int
    missing: int


class ProjectBoundary(TypedDict):
    kind: str
    # Validation guarantees the list's length, but does not constrain its elements.
    identity: list[object]
    sha256: str


class DispatchState(TypedDict):
    source_checkout_guard: dict[str, Any]
    initial_content_transmission_sha256: str | None
    """Fields proven by validate_state; optional values remain explicitly nullable."""
    schema_version: int
    kind: str
    sequence: int
    previous_state_sha256: str | None
    job_id: str
    status: str
    attempt: int
    attempt_origin: str
    reason: str | None
    exit_code: int | None
    controller_pid: int | None
    workdir: str | None
    created_epoch: float
    started_epoch: float | None
    updated_epoch: float
    finished_epoch: float | None
    elapsed_seconds: float
    progress_count: int
    last_progress_epoch: float | None
    notice_count: int
    hard_seconds: float
    max_seconds: float
    idle_seconds: float
    attempt_base_elapsed: float
    cancel_requested: bool
    conversation_id: str | None
    resume_available: bool
    remote_cancel_unverified: bool
    result_path: str | None
    stream_path: str | None
    stderr_path: str | None
    agy_returncode: int | None
    limit_kind: str | None
    command_sha256: str | None
    command_identity: list[int] | None
    stage_sha256: str | None
    stage_identity: list[int] | None
    result_sha256: str | None
    result_identity: list[int] | None
    workflow: str
    max_cycles: int
    cycle: int
    phase: str
    assurance: str
    check_summary: str | None
    check_counts: CheckCounts
    verification_path: str | None
    verification_sha256: str | None
    verification_identity: list[int] | None
    continue_available: bool
    last_success_path: str | None
    last_success_sha256: str | None
    last_success_identity: list[int] | None
    project_boundary: ProjectBoundary | None
    candidate_recognized: bool
    candidate_source: str
    result_available: bool
    worktree_reconciliation: str
    worktree_changes_present: bool | None
    worktree_changed_since_dispatch: bool | None
    driver_disposition: str
    failure_stage: str | None
    last_activity: str | None
    next_action: str
    next_action_command: str | None
    worktree_baseline: WorktreeBaseline | None
    provider_schema_sha256: str | None
    provider_schema_identity: list[int] | None
    canonical_schema_sha256: str | None
    canonical_schema_identity: list[int] | None
    candidate_worktree_sha256: str | None
    candidate_worktree_entries: int | None
    candidate_worktree_path_facts: dict[str, Any] | None
    selection_sha256: str | None
    selection_identity: list[int] | None
    worktree_snapshot_algorithm: str
    worktree_root_identity: WorktreeRootIdentity
    provider_terminal_status: str
    allow_scoped_repair: bool
    repair_authority_sha256: str | None
    repair_lineage_sha256: str | None
    repair_parent_result_sha256: str | None
    repair_parent_worktree_sha256: str | None
    repair_lineage_attempt: int | None
    allow_self_verification: bool
    self_verification_elapsed_seconds: float
    self_verification_run: int
    self_verification_started_epoch: float | None
    self_verification_return_phase: str | None
    provider_isolation: str
    provider_scope_path: str | None
    provider_scope_sha256: str | None
    provider_scope_identity: list[int] | None
    approved_transmission_sha256: str | None
    transmission_sha256: str | None
    selected_content_sha256: str | None
    selected_file_count: int | None
    selected_tree_count: int | None
    provider_stage_path: str | None
    provider_stage_identity: list[int] | None
    provider_stage_manifest_sha256: str | None
    reconciliation_manifest_sha256: str | None
    whole_worktree_content_sha256: str | None
    native_grant_profile: str


def _invalid_if(invalid: bool, message: str) -> None:
    if invalid:
        raise DispatchError(message)


def _validate_worktree_observation(item: Any) -> None:
    if item is not None and type(item) is not bool:
        raise DispatchError("dispatch worktree observation is invalid")


def _validate_boolean(item: Any) -> None:
    if type(item) is not bool:
        raise DispatchError("dispatch boolean is invalid")


def _validate_counter(item: Any) -> None:
    if type(item) is not int or item < 0:
        raise DispatchError("dispatch counter is invalid")


def _validate_time(item: Any) -> None:
    if type(item) not in (int, float) or item < 0:
        raise DispatchError("dispatch time is invalid")


def _validate_optional_time(item: Any) -> None:
    if item is not None and (type(item) not in (int, float) or item < 0):
        raise DispatchError("dispatch optional time is invalid")


def _validate_optional_integer(item: Any) -> None:
    if item is not None and type(item) is not int:
        raise DispatchError("dispatch integer is invalid")


def _validate_optional_path(item: Any) -> None:
    if item is not None and not isinstance(item, str):
        raise DispatchError("dispatch path is invalid")


def _validate_optional_digest(item: Any) -> None:
    if item is not None and (
        not isinstance(item, str) or SHA_RE.fullmatch(item) is None
    ):
        raise DispatchError("dispatch digest is invalid")


def _validate_optional_identity(item: Any) -> None:
    identity = item
    if identity is not None and (
        not isinstance(identity, list) or len(identity) != 5
        or any(type(item) is not int or item < 0 for item in identity)
    ):
        raise DispatchError("dispatch identity is invalid")


def _validate_fields(value: Mapping[str, Any], validators: dict[str, Callable[[Any], None]]) -> None:
    """Run one phase's field checks in their declared first-error order."""
    for key, validate in validators.items():
        validate(value[key])


def _validate_root_identity(value: Mapping[str, Any]) -> None:
    root_identity = value.get("worktree_root_identity")
    def valid_authority(authority: Any, *, directory: bool | None = None) -> bool:
        if not isinstance(authority, dict) or set(authority) != {
            "dev", "ino", "type", "mode", "uid", "gid",
        }:
            return False
        if any(type(authority[key]) is not int or authority[key] < 0 for key in authority):
            return False
        if authority["type"] not in {stat.S_IFDIR, stat.S_IFREG}:
            return False
        return directory is None or (authority["type"] == stat.S_IFDIR) == directory

    if (
        not isinstance(root_identity, dict)
        or set(root_identity) != {
            "root", "git_marker", "git_dir", "common_dir", "object_format", "show_toplevel",
        }
        or not isinstance(root_identity["root"], dict)
        or set(root_identity["root"]) != {"realpath", "dev", "ino"}
        or not isinstance(root_identity["root"]["realpath"], str)
        or not os.path.isabs(root_identity["root"]["realpath"])
        or type(root_identity["root"]["dev"]) is not int or root_identity["root"]["dev"] < 0
        or type(root_identity["root"]["ino"]) is not int or root_identity["root"]["ino"] < 0
        or root_identity["show_toplevel"] != root_identity["root"]["realpath"]
        or root_identity["object_format"] not in {"sha1", "sha256"}
        or not isinstance(root_identity["git_marker"], dict)
        or set(root_identity["git_marker"]) != {"kind", "authority", "content_sha256"}
        or root_identity["git_marker"]["kind"] not in {"directory", "file"}
        or not valid_authority(
            root_identity["git_marker"]["authority"],
            directory=root_identity["git_marker"]["kind"] == "directory",
        )
        or (
            root_identity["git_marker"]["content_sha256"] is not None
            if root_identity["git_marker"]["kind"] == "directory" else
            not isinstance(root_identity["git_marker"]["content_sha256"], str)
            or SHA_RE.fullmatch(root_identity["git_marker"]["content_sha256"]) is None
        )
        or any(
            not isinstance(root_identity[key], dict)
            or set(root_identity[key]) != {"realpath", "authority"}
            or not isinstance(root_identity[key]["realpath"], str)
            or not os.path.isabs(root_identity[key]["realpath"])
            or not valid_authority(root_identity[key]["authority"], directory=True)
            for key in ("git_dir", "common_dir")
        )
    ):
        raise DispatchError("dispatch worktree root identity is invalid")


def _validate_scope_state(value: Mapping[str, Any]) -> None:
    candidate_worktree_sha = value["candidate_worktree_sha256"]
    scope_path = value.get("provider_scope_path")
    scope_sha = value.get("provider_scope_sha256")
    scope_identity = value.get("provider_scope_identity")
    approved_sha = value.get("approved_transmission_sha256")
    initial_content_sha = value.get("initial_content_transmission_sha256")
    if (scope_path is None) != (initial_content_sha is None) or (
            initial_content_sha is not None and (not isinstance(initial_content_sha, str)
                                                or SHA_RE.fullmatch(initial_content_sha) is None)):
        raise DispatchError("dispatch initial content transmission binding is invalid")
    transmission_sha = value.get("transmission_sha256")
    selected_content_sha = value.get("selected_content_sha256")
    selected_file_count = value.get("selected_file_count")
    selected_tree_count = value.get("selected_tree_count")
    stage_path = value.get("provider_stage_path")
    stage_identity = value.get("provider_stage_identity")
    stage_manifest_sha = value.get("provider_stage_manifest_sha256")
    reconciliation_manifest_sha = value.get("reconciliation_manifest_sha256")
    if (scope_path is None) != (scope_sha is None) or (scope_path is None) != (scope_identity is None) or (scope_path is None) != (approved_sha is None) or (scope_path is None) != (transmission_sha is None) or (scope_path is None) != (selected_content_sha is None) or (scope_path is None) != (selected_file_count is None) or (scope_path is None) != (selected_tree_count is None):
        raise DispatchError("dispatch provider scope state fields are incomplete")
    stage_fields = (stage_path, stage_identity, stage_manifest_sha)
    if any(item is None for item in stage_fields) != all(item is None for item in stage_fields):
        raise DispatchError("dispatch provider stage state fields are incomplete")
    if scope_path is None and (
        any(item is not None for item in stage_fields)
        or reconciliation_manifest_sha is not None
    ):
        raise DispatchError("whole-worktree state cannot carry narrow provider evidence")
    if scope_path is not None:
        if (
            not isinstance(scope_path, str) or not Path(scope_path).is_absolute()
            or not isinstance(scope_sha, str) or SHA_RE.fullmatch(scope_sha) is None
            or not isinstance(scope_identity, list) or len(scope_identity) != 5
            or any(type(item) is not int or item < 0 for item in scope_identity)
            or not isinstance(approved_sha, str) or SHA_RE.fullmatch(approved_sha) is None
            or not isinstance(transmission_sha, str) or SHA_RE.fullmatch(transmission_sha) is None
            or not isinstance(selected_content_sha, str) or SHA_RE.fullmatch(selected_content_sha) is None
            or type(selected_file_count) is not int or selected_file_count < 0
            or type(selected_tree_count) is not int or selected_tree_count < 0
            or (stage_path is not None and (not isinstance(stage_path, str) or not Path(stage_path).is_absolute()))
            or (stage_identity is not None and (not isinstance(stage_identity, list) or len(stage_identity) != 5 or any(type(item) is not int or item < 0 for item in stage_identity)))
            or (stage_manifest_sha is not None and (not isinstance(stage_manifest_sha, str) or SHA_RE.fullmatch(stage_manifest_sha) is None))
            or (reconciliation_manifest_sha is not None and (not isinstance(reconciliation_manifest_sha, str) or SHA_RE.fullmatch(reconciliation_manifest_sha) is None))
        ):
            raise DispatchError("dispatch provider scope state fields are invalid")
    allow_repair = value["allow_scoped_repair"]
    repair_authority = value["repair_authority_sha256"]
    lineage_sha = value["repair_lineage_sha256"]
    parent_result_sha = value["repair_parent_result_sha256"]
    parent_worktree_sha = value["repair_parent_worktree_sha256"]
    lineage_attempt = value["repair_lineage_attempt"]
    if type(allow_repair) is not bool:
        raise DispatchError("dispatch scoped repair choice is invalid")
    if not allow_repair:
        if any(item is not None for item in (
            repair_authority, lineage_sha, parent_result_sha,
            parent_worktree_sha, lineage_attempt,
        )):
            raise DispatchError("disabled scoped repair has authority")
    elif (
        scope_path is None
        or value["workflow"] not in {"task", "project"}
        or value["max_cycles"] < 2
        or not isinstance(repair_authority, str)
        or SHA_RE.fullmatch(repair_authority) is None
    ):
        raise DispatchError("dispatch scoped repair authority is invalid")
    if lineage_sha is None:
        if any(item is not None for item in (
            parent_result_sha, parent_worktree_sha, lineage_attempt,
        )):
            raise DispatchError("dispatch repair lineage is incomplete")
    elif (
        not allow_repair
        or not isinstance(lineage_sha, str) or SHA_RE.fullmatch(lineage_sha) is None
        or parent_result_sha is not None and (
            not isinstance(parent_result_sha, str) or SHA_RE.fullmatch(parent_result_sha) is None
        )
        or parent_worktree_sha is not None and (
            not isinstance(parent_worktree_sha, str) or SHA_RE.fullmatch(parent_worktree_sha) is None
        )
        or type(lineage_attempt) is not int
        or not (1 <= lineage_attempt <= value["attempt"])
        or reconciliation_manifest_sha is None
        or candidate_worktree_sha is None
        or value["result_sha256"] is None
        or lineage_sha != _compute_repair_lineage_sha256(
            authority_sha256=repair_authority,
            attempt=lineage_attempt,
            parent_result_sha256=parent_result_sha,
            parent_worktree_sha256=parent_worktree_sha,
            reconciliation_sha256=reconciliation_manifest_sha,
            result_sha256=value["result_sha256"],
            candidate_worktree_sha256=candidate_worktree_sha,
            selected_content_sha256=cast(str, selected_content_sha),
            transmission_sha256=cast(str, transmission_sha),
        )
    ):
        raise DispatchError("dispatch repair lineage is invalid")


def _validate_self_verification_state(value: Mapping[str, Any]) -> None:
    allow_self_verification = value["allow_self_verification"]
    self_verification_elapsed = value["self_verification_elapsed_seconds"]
    self_verification_run = value["self_verification_run"]
    self_verification_started = value["self_verification_started_epoch"]
    self_verification_return = value["self_verification_return_phase"]
    if type(allow_self_verification) is not bool:
        raise DispatchError("dispatch self-verification choice is invalid")
    _validate_fields(value, {
        "workflow": lambda item: _invalid_if(allow_self_verification and item not in {'task', 'project'}, 'dispatch self-verification workflow is invalid'),
        "attempt": lambda item: _invalid_if(type(self_verification_elapsed) not in (int, float) or not math.isfinite(self_verification_elapsed) or self_verification_elapsed < 0 or (type(self_verification_run) is not int) or (not 0 <= self_verification_run <= item), 'dispatch self-verification accounting is invalid'),
    })
    if self_verification_started is not None and (
        type(self_verification_started) not in (int, float)
        or not math.isfinite(self_verification_started)
        or self_verification_started < 0
    ):
        raise DispatchError("dispatch self-verification start is invalid")
    if not allow_self_verification and (
        self_verification_elapsed != 0.0
        or self_verification_run != 0
        or self_verification_started is not None
        or self_verification_return is not None
    ):
        raise DispatchError("disabled self-verification has runtime state")
    if value["phase"] == "self-verifying":
        if (
            not allow_self_verification
            or value["continue_available"]
            or value["status"] not in {"succeeded", "failed"}
            or not value["candidate_recognized"] or not value["result_available"]
            or value["driver_disposition"] != "unreviewed" or value["assurance"] != "pending"
            or self_verification_run != value["attempt"]
            or self_verification_started is None
            or self_verification_return not in {
                "awaiting-verification", "repair-failed",
            }
        ):
            raise DispatchError("active self-verification state is invalid")
    elif self_verification_started is not None or self_verification_return is not None:
        raise DispatchError("inactive self-verification has active state")


def _validate_candidate_lifecycle(value: Mapping[str, Any]) -> None:
    current_result = [value["result_path"], value["result_sha256"], value["result_identity"]]
    if any(item is None for item in current_result) != all(item is None for item in current_result):
        raise DispatchError("dispatch result binding is incomplete")
    if value["candidate_recognized"] != all(item is not None for item in current_result):
        raise DispatchError("dispatch candidate result binding is inconsistent")
    inaccessible_candidate = bool(
        value["candidate_recognized"] and not value["result_available"]
    )
    if value["candidate_recognized"] and value["failure_stage"] == "binding_failure" and value["result_available"]:
        raise DispatchError("dispatch binding failure cannot advertise a result")
    if inaccessible_candidate and not (
        value["failure_stage"] == "binding_failure"
        and value["status"] == "failed"
        and value["reason"] == "status_unavailable"
        and not value["resume_available"]
        and not value["continue_available"]
        and value["driver_disposition"] == "unreviewed"
        and value["next_action"] in {"blocked", "none"}
        and value["next_action_command"] is None
    ):
        raise DispatchError("dispatch inaccessible candidate state is inconsistent")
    if value["status"] in TERMINAL:
        if value["finished_epoch"] is None or value["exit_code"] is None:
            raise DispatchError("terminal dispatch state is incomplete")
    _validate_fields(value, {
        "phase": lambda item: _invalid_if(item not in LIFECYCLE_PHASES, 'dispatch lifecycle phase is invalid'),
        "assurance": lambda item: _invalid_if(item not in {'pending', 'verified', 'partially_verified', 'rejected', 'blocked'}, 'dispatch lifecycle assurance is invalid'),
    })
    if inaccessible_candidate and (
        value["phase"] != "blocked" or value["assurance"] != "blocked"
    ):
        raise DispatchError("dispatch inaccessible candidate lifecycle is invalid")
    if value["continue_available"] and not (
        value["assurance"] == "pending"
        and value["candidate_recognized"]
        and value["candidate_source"] != "provider_cancelled"
        and value["cycle"] < value["max_cycles"]
        and value["status"] in {"succeeded", "failed"}
        and value["phase"] in {"awaiting-verification", "repair-failed"}
    ):
        raise DispatchError("dispatch continuation availability is invalid")
    if value["assurance"] != "pending" and value["phase"] not in {"completed", "blocked"}:
        raise DispatchError("terminal dispatch assurance has an invalid phase")
    if value["status"] == "orphaned" and (
        value["assurance"] != "pending"
        or value["phase"] in {"completed", "blocked"}
        or value["resume_available"] or value["continue_available"]
    ):
        raise DispatchError("orphaned dispatch state must remain preserve-only")
    if value["workflow"] == "legacy":
        active = value["status"] in {"queued", "running", "cancel-requested"}
        if value["continue_available"]:
            raise DispatchError("legacy lifecycle cannot continue as repair")
        if active and (
            value["phase"] != "dispatching"
            or value["assurance"] != "pending"
            or value["driver_disposition"] != "not_applicable"
        ):
            raise DispatchError("active legacy lifecycle is invalid")
        if not active and inaccessible_candidate and (
            value["phase"] != "blocked" or value["assurance"] != "blocked"
        ):
            raise DispatchError("blocked legacy candidate lifecycle is invalid")
        if not active and value["candidate_recognized"] and not inaccessible_candidate and (
            value["phase"] != "awaiting-verification"
            or value["assurance"] != "pending"
            or value["driver_disposition"] != "unreviewed"
        ):
            raise DispatchError("legacy candidate lifecycle is invalid")
        if not active and not value["candidate_recognized"] and (
            (value["phase"] != "attempt-failed" or value["assurance"] != "pending")
            and _source_guard_reason(value) is None
        ):
            raise DispatchError("failed legacy lifecycle is invalid")


def _validate_verification_state(value: Mapping[str, Any]) -> None:
    summary = value["check_summary"]
    if summary is not None and (
        not isinstance(summary, str) or not (1 <= len(summary) <= MAX_CHECK_SUMMARY)
        or any(ch in summary for ch in "\x00\r\n")
    ):
        raise DispatchError("dispatch check summary is invalid")
    counts = value["check_counts"]
    if not isinstance(counts, dict) or set(counts) != {"passed", "failed", "advisory", "missing"} or any(
        type(item) is not int or not (0 <= item <= MAX_CHECK_ITEMS) for item in counts.values()
    ):
        raise DispatchError("dispatch check counts are invalid")
    present = [value["verification_path"], value["verification_sha256"], value["verification_identity"]]
    if any(item is None for item in present) != all(item is None for item in present):
        raise DispatchError("dispatch verification binding is incomplete")
    prior = [value["last_success_path"], value["last_success_sha256"], value["last_success_identity"]]
    if any(item is None for item in prior) != all(item is None for item in prior):
        raise DispatchError("dispatch prior result binding is incomplete")
    boundary = value["project_boundary"]
    if value["workflow"] == "project":
        if not isinstance(boundary, dict) or set(boundary) != {"kind", "identity", "sha256"}:
            raise DispatchError("project boundary binding is invalid")
        if boundary["kind"] != "file" or not isinstance(boundary["identity"], list) or len(boundary["identity"]) != 5:
            raise DispatchError("project boundary identity is invalid")
        if not isinstance(boundary["sha256"], str) or SHA_RE.fullmatch(boundary["sha256"]) is None:
            raise DispatchError("project boundary marker digest is invalid")
    elif boundary is not None:
        raise DispatchError("non-project state has a boundary binding")


def _validate_worktree_state(value: Mapping[str, Any]) -> None:
    if value["worktree_reconciliation"] not in {"available", "unavailable", "not_applicable"}:
        raise DispatchError("dispatch worktree reconciliation is invalid")
    _validate_fields(value, dict.fromkeys(('worktree_changes_present', 'worktree_changed_since_dispatch'), _validate_worktree_observation))
    if value["worktree_reconciliation"] == "available" and (
        value["worktree_changes_present"] is None or value["worktree_changed_since_dispatch"] is None
    ):
        raise DispatchError("dispatch worktree reconciliation is incomplete")
    if value["worktree_reconciliation"] != "available" and (
        value["worktree_changes_present"] is not None or value["worktree_changed_since_dispatch"] is not None
    ):
        raise DispatchError("dispatch unavailable worktree reconciliation has observations")
    _validate_fields(value, {
        "driver_disposition": lambda item: _invalid_if(item not in {'not_applicable', 'unreviewed', 'verified', 'partially_verified', 'rejected', 'blocked'}, 'dispatch driver disposition is invalid'),
        "failure_stage": lambda item: _invalid_if(item not in {None, *FAILURE_STAGES}, 'dispatch failure stage is invalid'),
        "last_activity": lambda item: _invalid_if(item not in {None, 'provider_initialized', 'progress_signal', 'terminal_received'}, 'dispatch activity is invalid'),
        "next_action": lambda item: _invalid_if(item not in {'none', 'wait', 'resume', 'restart', 'driver_review', 'driver_finalize', 'blocked'}, 'dispatch next action is invalid'),
        "next_action_command": lambda item: _invalid_if(item is not None and (not isinstance(item, str) or not item), 'dispatch next action command is invalid'),
    })
    baseline = value["worktree_baseline"]
    if baseline is not None and (
        not isinstance(baseline, dict) or set(baseline) != {"sha256", "entries"}
        or not isinstance(baseline["sha256"], str) or SHA_RE.fullmatch(baseline["sha256"]) is None
        or type(baseline["entries"]) is not int or not (0 <= baseline["entries"] <= MAX_BOUNDARY_ENTRIES)
    ):
        raise DispatchError("dispatch worktree baseline is invalid")
    candidate_worktree_sha = value["candidate_worktree_sha256"]
    candidate_worktree_entries = value["candidate_worktree_entries"]
    path_facts = value["candidate_worktree_path_facts"]
    if (candidate_worktree_sha is None) != (candidate_worktree_entries is None):
        raise DispatchError("dispatch candidate worktree binding is incomplete")
    if candidate_worktree_sha is not None and (
        not isinstance(candidate_worktree_sha, str)
        or SHA_RE.fullmatch(candidate_worktree_sha) is None
        or type(candidate_worktree_entries) is not int
        or not (0 <= candidate_worktree_entries <= MAX_BOUNDARY_ENTRIES)
    ):
        raise DispatchError("dispatch candidate worktree binding is invalid")
    if path_facts is not None:
        if (
            candidate_worktree_sha is None or not isinstance(path_facts, dict)
            or set(path_facts) != {"complete", "items"}
            or type(path_facts["complete"]) is not bool
            or not isinstance(path_facts["items"], list)
            or len(path_facts["items"]) > WORKTREE.DIAGNOSTIC_MAX_PATHS
        ):
            raise DispatchError("dispatch candidate path facts are invalid")
        path_bytes = 0
        seen_paths: set[str] = set()
        for item in path_facts["items"]:
            if not isinstance(item, list) or len(item) != 4:
                raise DispatchError("dispatch candidate path fact is invalid")
            path, kind, mode, fingerprint = item
            if (
                not isinstance(path, str) or not path or "\x00" in path
                or path.startswith("/") or any(part in {"", ".", ".."} for part in path.split("/"))
                or path in seen_paths or not isinstance(kind, str)
                or kind not in {"missing", "file", "symlink", "special"}
                or ((kind == "missing") != (mode is None))
                or (mode is not None and (type(mode) is not int or not 0 <= mode <= 0o7777))
                or not isinstance(fingerprint, str) or SHA_RE.fullmatch(fingerprint) is None
            ):
                raise DispatchError("dispatch candidate path fact is invalid")
            try:
                path_bytes += len(os.fsencode(path))
            except UnicodeError as exc:
                raise DispatchError("dispatch candidate path fact is invalid") from exc
            seen_paths.add(path)
        if path_bytes > WORKTREE.DIAGNOSTIC_MAX_PATH_BYTES:
            raise DispatchError("dispatch candidate path facts exceed limit")
    for digest_key, identity_key in (
        ("provider_schema_sha256", "provider_schema_identity"),
        ("canonical_schema_sha256", "canonical_schema_identity"),
    ):
        bound_digest, bound_identity = value[digest_key], value[identity_key]
        if (bound_digest is None) != (bound_identity is None):
            raise DispatchError("dispatch schema binding is incomplete")
        if bound_digest is not None and (
            not isinstance(bound_digest, str) or SHA_RE.fullmatch(bound_digest) is None
            or not isinstance(bound_identity, list) or len(bound_identity) != 5
            or any(type(item) is not int or item < 0 for item in bound_identity)
        ):
            raise DispatchError("dispatch schema binding is invalid")


def _validate_attempt_state(value: Mapping[str, Any]) -> None:
    _validate_fields(value, {
        "attempt_origin": lambda item: _invalid_if(item not in {'initial', 'conversation-resume', 'fresh-restart', 'conversation-continue'}, 'dispatch attempt origin is invalid'),
        "attempt": lambda item: _invalid_if(type(item) is not int or item < 1, 'dispatch attempt is invalid'),
        "workflow": lambda item: _invalid_if(item not in {'legacy', 'explore', 'task', 'project'}, 'dispatch workflow state is invalid'),
    })
    if not _valid_max_cycles(value["workflow"], value["max_cycles"]):
        raise DispatchError("dispatch max cycles state is invalid")
    if type(value["cycle"]) is not int or value["cycle"] != value["attempt"] or (
        value["workflow"] != "legacy" and value["cycle"] > value["max_cycles"]
    ):
        raise DispatchError("dispatch cycle state is invalid")
    if not isinstance(value["job_id"], str) or JOB_RE.fullmatch(value["job_id"]) is None:
        raise DispatchError("dispatch job ID is invalid")
    conversation = value["conversation_id"]
    if conversation is not None and (
        not isinstance(conversation, str) or CONVERSATION_RE.fullmatch(conversation) is None
    ):
        raise DispatchError("dispatch conversation ID is invalid")
    _validate_fields(value, dict.fromkeys(('cancel_requested', 'resume_available', 'continue_available', 'remote_cancel_unverified'), _validate_boolean))
    _validate_fields(value, dict.fromkeys(('progress_count', 'notice_count'), _validate_counter))
    _validate_fields(value, dict.fromkeys(('created_epoch', 'updated_epoch', 'elapsed_seconds', 'hard_seconds', 'max_seconds', 'idle_seconds', 'attempt_base_elapsed'), _validate_time))
    _validate_fields(value, dict.fromkeys(('started_epoch', 'finished_epoch', 'last_progress_epoch'), _validate_optional_time))
    _validate_fields(value, dict.fromkeys(('exit_code', 'controller_pid', 'agy_returncode'), _validate_optional_integer))
    _validate_fields(value, dict.fromkeys(('workdir', 'result_path', 'stream_path', 'stderr_path', 'verification_path', 'last_success_path'), _validate_optional_path))
    if value["limit_kind"] not in {None, "idle", "hard", "max-runtime"}:
        raise DispatchError("dispatch limit kind is invalid")
    _validate_fields(value, dict.fromkeys(('command_sha256', 'stage_sha256', 'result_sha256', 'verification_sha256', 'last_success_sha256'), _validate_optional_digest))
    _validate_fields(value, dict.fromkeys(('command_identity', 'stage_identity', 'result_identity', 'verification_identity', 'last_success_identity'), _validate_optional_identity))
    selection_sha = value["selection_sha256"]
    selection_identity = value["selection_identity"]
    if (selection_sha is None) != (selection_identity is None):
        raise DispatchError("dispatch selection state binding is incomplete")
    if selection_sha is not None and (
        not isinstance(selection_sha, str) or SHA_RE.fullmatch(selection_sha) is None
        or not isinstance(selection_identity, list) or len(selection_identity) != 5
        or any(type(item) is not int or item < 0 for item in selection_identity)
    ):
        raise DispatchError("dispatch selection state binding is invalid")



_SOURCE_BINDING_KEYS = ("source_path", "source_identity", "common_dir", "common_identity")


def _pending_source_guard(attempt: int) -> dict[str, Any]:
    return {"algorithm": CANDIDATE_STATE.SOURCE_CHECKOUT_ALGORITHM,
            "attempt": attempt, "status": "pending", "before_sha256": None,
            "after_sha256": None, **dict.fromkeys(_SOURCE_BINDING_KEYS)}


def _source_guard_reason(value: Mapping[str, Any]) -> str | None:
    status = value.get("source_checkout_guard", {}).get("status")
    if status == "changed" or value.get("reason") == "source_checkout_changed":
        return "source_checkout_changed"
    if status == "unavailable" or value.get("reason") == "source_checkout_guard_unavailable":
        return "source_checkout_guard_unavailable"
    return None


def _source_guard_veto(value: Mapping[str, Any]) -> dict[str, Any]:
    """One terminal projection clears current and inherited candidate authority."""
    reason = _source_guard_reason(value)
    if reason is None:
        return {}
    return {
        "status": "failed", "reason": reason, "exit_code": EXIT_BY_REASON[reason],
        "controller_pid": None, "finished_epoch": time.time(),
        "phase": "blocked", "assurance": "blocked", "candidate_recognized": False,
        "candidate_source": "none", "result_available": False,
        "resume_available": False, "continue_available": False,
        "driver_disposition": "not_applicable", "failure_stage": None,
        "next_action": "none", "next_action_command": None,
        "worktree_reconciliation": "unavailable", "worktree_changes_present": None,
        "worktree_changed_since_dispatch": None, "limit_kind": None,
        "check_summary": None, "check_counts": dict.fromkeys(("passed", "failed", "advisory", "missing"), 0),
        "self_verification_started_epoch": None, "self_verification_return_phase": None,
        **dict.fromkeys((
            "result_path", "result_sha256", "result_identity", "candidate_worktree_sha256",
            "candidate_worktree_entries", "candidate_worktree_path_facts", "verification_path",
            "verification_sha256", "verification_identity", "last_success_path", "last_success_sha256",
            "last_success_identity", "repair_lineage_sha256", "repair_parent_result_sha256",
            "repair_parent_worktree_sha256", "repair_lineage_attempt", "reconciliation_manifest_sha256",
        )),
    }


def _validate_source_guard(value: Mapping[str, Any]) -> None:
    guard = value["source_checkout_guard"]
    if (not isinstance(guard, dict)
            or set(guard) != {"algorithm", "attempt", "status", "before_sha256", "after_sha256", *_SOURCE_BINDING_KEYS}
            or guard["algorithm"] != CANDIDATE_STATE.SOURCE_CHECKOUT_ALGORITHM
            or type(guard["attempt"]) is not int or guard["attempt"] != value["attempt"]
            or guard["status"] not in {"pending", "skipped_main_worktree", "armed", "deferred", "unchanged", "changed", "unavailable"}):
        raise DispatchError("source checkout guard is invalid")
    bound = [guard[key] is not None for key in _SOURCE_BINDING_KEYS]
    if any(bound) != all(bound):
        raise DispatchError("source checkout guard authority is incomplete")
    if all(bound):
        for key in ("source_path", "common_dir"):
            path = guard[key]
            if type(path) is not str or not path or not os.path.isabs(path) or "\0" in path or os.path.normpath(path) != path:
                raise DispatchError("source checkout guard path is invalid")
        for key in ("source_identity", "common_identity"):
            identity = guard[key]
            if (type(identity) is not list or len(identity) != 4
                    or any(type(item) is not int or item < 0 for item in identity)
                    or identity[2] != stat.S_IFDIR):
                raise DispatchError("source checkout guard identity is invalid")
    before, after = guard["before_sha256"], guard["after_sha256"]
    for sha in (before, after):
        if sha is not None and (type(sha) is not str or SHA_RE.fullmatch(sha) is None):
            raise DispatchError("source checkout guard digest is invalid")
    status = guard["status"]
    if (status == "pending" and (any(bound) or before is not None or after is not None)
            or status == "skipped_main_worktree" and (not all(bound) or guard["source_path"] != value["workdir"] or before is not None or after is not None)
            or status in {"armed", "deferred", "unchanged", "changed"} and (not all(bound) or before is None)
            or status in {"armed", "deferred"} and after is not None
            or status == "unchanged" and (after is None or before != after)
            or status == "changed" and after is not None and before == after
            or status == "unavailable" and after is not None
            or not all(bound) and (before is not None or after is not None)):
        raise DispatchError("source checkout guard observations are inconsistent")
    if status == "deferred" and any(value[key] for key in (
        "candidate_recognized", "result_available", "result_path", "result_sha256",
        "result_identity", "candidate_worktree_sha256", "candidate_worktree_entries",
        "candidate_worktree_path_facts", "last_success_path",
        "last_success_sha256", "last_success_identity",
    )) and not (value["status"] in TERMINAL and _cancelled_repair(value)):
        # The cancelled repair's inherited candidate is unusable until a
        # command settles this proof (`_bound_current_candidate`).
        raise DispatchError("deferred source checkout guard cannot authorize a candidate")
    reason = _source_guard_reason(value)
    if status == "armed" and value["status"] in TERMINAL:
        raise DispatchError("source checkout guard has no terminal observation")
    if reason is not None and value["status"] in TERMINAL:
        required = _source_guard_veto(value)
        # Time is refreshed by projection; validation only requires terminal completeness.
        required.pop("finished_epoch")
        if any(value[key] != item for key, item in required.items()):
            raise DispatchError("source checkout guard failure cannot authorize a candidate or recovery")
    if value["reason"] in SOURCE_GUARD_MESSAGES and value["reason"] != (
        "source_checkout_changed" if status == "changed" else
        "source_checkout_guard_unavailable" if status == "unavailable" else None
    ):
        raise DispatchError("source checkout guard reason is inconsistent")


def _observe_source_checkout(workdir: str) -> dict[str, object]:
    deadline = time.monotonic() + CANDIDATE_STATE.SOURCE_CHECKOUT_SECONDS
    executable = WORKTREE._safe_git_executable("/usr/bin/git")
    if executable is None:
        raise CANDIDATE_STATE.CandidateStateError("source Git authority unavailable")
    inspected: set[Path] = set()

    def bounded(root: Path, arguments: tuple[str, ...], allowed: tuple[int, ...] = (0,)) -> tuple[int, bytes]:
        result = WORKTREE._bounded_git_read(
            *executable, str(root), list(arguments), deadline=deadline,
            allowed=allowed, stdout_limit=CANDIDATE_STATE.SOURCE_CHECKOUT_LIST_LIMIT,
            fixed_executable=True,
        )
        if result is None:
            raise CANDIDATE_STATE.CandidateStateLimitError("source Git proof unavailable")
        return result

    filter_arguments = ("config", "--includes", "--name-only", "--get-regexp",
                        r"^filter\..*\.(clean|process|required)$")

    def accept_filters(root: Path, result: tuple[int, bytes]) -> None:
        if result[0] != 1:
            raise CANDIDATE_STATE.CandidateStateError("source filters unsupported")
        inspected.add(root)

    def inspect_filters(root: Path) -> None:
        if root not in inspected:
            accept_filters(root, bounded(root, filter_arguments, (0, 1)))

    def reader(root: Path, *arguments: str) -> bytes:
        inspect_filters(root)
        return bounded(root, arguments)[1]

    # Independent fixed reads share the deadline, never the sample. The executor
    # drains every sibling (whose supervisor reaps its group) even on failure.
    with ThreadPoolExecutor(max_workers=6) as executor:
        def batch(root: Path, arguments: tuple[tuple[str, ...], ...]) -> list[bytes]:
            paths = ("rev-parse", "--show-toplevel", "--absolute-git-dir", "--git-common-dir")
            discovery = arguments in {(paths,), (paths, ("worktree", "list", "--porcelain", "-z"))}
            # Only fixed metadata discovery can overlap filter inspection.
            # No returned authority or content sample precedes its verdict.
            filter_future = None
            if root not in inspected and discovery:
                filter_future = executor.submit(bounded, root, filter_arguments, (0, 1))
            else:
                inspect_filters(root)
            futures = [executor.submit(bounded, root, item) for item in arguments]
            if filter_future is not None:
                accept_filters(root, filter_future.result())
            return [future.result()[1] for future in futures]

        return CANDIDATE_STATE.source_checkout_observation(
            Path(workdir), git_reader=reader, git_batch_reader=batch, deadline=deadline,
        )


def _prepare_controller_source(binding: _ControllerBinding, execution: _ProviderExecution) -> dict[str, Any]:
    # Snapshot the exact approved predecessor before scanning outside the lock.
    prior = dict(binding.state["source_checkout_guard"])
    execution.source_guard_expected = prior
    guard = {**prior, "after_sha256": None}
    try:
        observed = _observe_source_checkout(binding.command["workdir"])
        if prior["status"] == "pending":
            guard.update({key: observed[key] for key in _SOURCE_BINDING_KEYS})
            guard.update(status=("skipped_main_worktree" if observed["status"] == "skipped_main_worktree" else "armed"),
                         before_sha256=observed["sha256"])
        elif any(observed[key] != prior[key] for key in _SOURCE_BINDING_KEYS):
            guard["status"] = "changed"
        elif observed["sha256"] != prior["before_sha256"]:
            guard.update(status="changed", after_sha256=observed["sha256"])
        else:
            guard["status"] = "skipped_main_worktree" if observed["status"] == "skipped_main_worktree" else "armed"
    except (OSError, ValueError, UnicodeError):
        guard["status"] = "unavailable"
    execution.source_guard_baseline = guard.copy()
    return guard


def _has_source_candidate(state: Mapping[str, Any]) -> bool:
    # Include inherited bindings even when an exceptional projection may recover them.
    return any(state.get(key) for key in (
        "candidate_recognized", "result_available", "result_path", "last_success_path",
    ))


def _cancelled_repair(state: Mapping[str, Any]) -> bool:
    """A locally cancelled repair can retain only the candidate it inherited."""
    return bool(state["attempt_origin"] == "conversation-continue" and state["cancel_requested"])


def _finish_controller_source(binding: _ControllerBinding, execution: _ProviderExecution, *, report: bool = False) -> None:
    baseline = execution.source_guard_baseline
    if (baseline is not None and baseline["status"] == "armed"
            and execution.started_mono is not None and execution.runtime_end_mono is not None
            and execution.process is None and not report
            and (not _has_source_candidate(binding.state) or _cancelled_repair(binding.state))):
        # Reap is proven and no current report can be admitted. Without a
        # candidate, the next launch compares this immutable baseline. A cancelled
        # repair keeps only its inherited candidate, which every later use settles
        # against the same baseline first. This is not an unchanged observation.
        if execution.source_guard_result is None:
            execution.source_guard_result = {**baseline, "status": "deferred", "after_sha256": None}
    else:
        _check_controller_source(binding, execution)


def _check_controller_source(binding: _ControllerBinding, execution: _ProviderExecution) -> None:
    """Idempotent after-reap proof; a failed completed proof is never replaced."""
    if execution.source_guard_result is not None:
        return
    baseline = execution.source_guard_baseline
    if baseline is None:
        return
    result = baseline.copy()
    if baseline["status"] == "armed" and execution.started_mono is None and execution.process is None:
        execution.source_guard_result = dict(execution.source_guard_expected or _pending_source_guard(binding.state["attempt"]))
        return
    if baseline["status"] == "armed":
        result["status"] = "unavailable"
        if execution.started_mono is not None and execution.runtime_end_mono is not None and execution.process is None:
            result = _compare_source_baseline(baseline, binding.command["workdir"])
    execution.source_guard_result = result


def _compare_source_baseline(baseline: Mapping[str, Any], workdir: str) -> dict[str, Any]:
    """Compare the current source checkout with one bound immutable baseline."""
    result = {**baseline, "status": "unavailable", "after_sha256": None}
    try:
        for path_key, identity_key in (("source_path", "source_identity"), ("common_dir", "common_identity")):
            path = Path(baseline[path_key])
            try:
                info = path.lstat()
                identity = [info.st_dev, info.st_ino, stat.S_IFMT(info.st_mode), info.st_uid]
            except FileNotFoundError:
                result["status"] = "changed"
                return result
            if identity != baseline[identity_key] or Path(os.path.realpath(path)) != path:
                result["status"] = "changed"
                return result
        observed = _observe_source_checkout(workdir)
        if any(observed[key] != baseline[key] for key in _SOURCE_BINDING_KEYS):
            result["status"] = "changed"
        else:
            result["after_sha256"] = observed["sha256"]
            result["status"] = "unchanged" if observed["sha256"] == baseline["before_sha256"] else "changed"
    except (OSError, ValueError, UnicodeError):
        pass
    return result


def _deferred_candidate_proof(state: Mapping[str, Any]) -> dict[str, Any] | None:
    """Return the current proof for a retained candidate whose proof was deferred."""
    guard = state["source_checkout_guard"]
    if guard["status"] != "deferred" or not _has_source_candidate(state):
        return None
    return _compare_source_baseline(guard, state["workdir"])


def _settle_deferred_source(
    job: Path, state: DispatchState, raw: bytes, sha: str,
) -> tuple[DispatchState, bytes, str]:
    """Persist a deferred candidate proof under the caller's state lock.

    A changed or unavailable source vetoes the retained candidate and every
    recovery exactly as the controller would have; an unchanged proof is
    recorded so later reads do not rescan.
    """
    guard = _deferred_candidate_proof(state)
    if guard is None:
        return state, raw, sha
    updates: dict[str, Any] = {"source_checkout_guard": guard}
    updates.update(_source_guard_veto({**state, **updates}))
    state, raw, sha = _transition_locked(job, state, raw, updates)
    reason = _source_guard_reason(state)
    if reason is not None:
        raise SourceGuardError(reason)
    return state, raw, sha


def _checked_controller_source(current: Mapping[str, Any], execution: _ProviderExecution) -> dict[str, Any]:
    guard = execution.source_guard_result or execution.source_guard_baseline
    if guard is None:
        return dict(current["source_checkout_guard"])
    if current["source_checkout_guard"] != execution.source_guard_baseline:
        # The in-memory baseline belongs to this attempt; never trust a
        # valid-looking transplanted persisted digest. Positive change wins.
        guard = {**guard, "status": "changed" if guard["status"] == "changed" else "unavailable", "after_sha256": None}
    return guard

def validate_state(value: Any) -> DispatchState:
    _require_supported_schema(value, label="dispatch state", supported=(CURRENT_STATE_SCHEMA,))
    if not isinstance(value, dict) or set(value) != CURRENT_STATE_FIELDS:
        raise DispatchError("dispatch state fields are invalid")
    _validate_fields(value, {
        "kind": lambda item: _invalid_if(item != 'agy-worker-dispatch-state', 'dispatch state version is invalid'),
        "provider_isolation": lambda item: _invalid_if(item not in {'session', 'native'}, 'dispatch provider isolation state is invalid'),
    })
    if not isinstance(value.get("native_grant_profile"), str) or value.get("native_grant_profile") not in {"baseline", "A", "B", "AB"} or (
        value["provider_isolation"] == "session" and value.get("native_grant_profile") != "baseline"
    ):
        raise DispatchError("dispatch native grant profile state is invalid")
    whole_content_sha = value.get("whole_worktree_content_sha256")
    if whole_content_sha is not None and (
        not isinstance(whole_content_sha, str) or SHA_RE.fullmatch(whole_content_sha) is None
    ):
        raise DispatchError("dispatch whole-worktree content state is invalid")
    if (value["worktree_snapshot_algorithm"] != CURRENT_WORKTREE_SNAPSHOT_ALGORITHM):
        raise DispatchError("dispatch worktree snapshot algorithm is invalid")
    if (value.get("provider_terminal_status") not in {"unknown", "success", "error", "cancelled"}):
        raise DispatchError("dispatch provider terminal status is invalid")
    _validate_root_identity(value)
    if type(value["sequence"]) is not int or value["sequence"] < 1:
        raise DispatchError("dispatch sequence is invalid")
    previous = value["previous_state_sha256"]
    if previous is not None and (not isinstance(previous, str) or SHA_RE.fullmatch(previous) is None):
        raise DispatchError("dispatch history is invalid")
    _validate_fields(value, {
        "sequence": lambda item: _invalid_if((item == 1) != (previous is None), 'dispatch history is inconsistent'),
        "status": lambda item: _invalid_if(item not in {'queued', 'running', 'cancel-requested', *TERMINAL}, 'dispatch status is invalid'),
        "reason": lambda item: _invalid_if(item is not None and item not in REASONS, 'dispatch reason is invalid'),
    })
    if type(value["candidate_recognized"]) is not bool or type(value["result_available"]) is not bool:
        raise DispatchError("dispatch candidate flags are invalid")
    if value["candidate_source"] not in {"none", "provider_success", "provider_error", "provider_cancelled"}:
        raise DispatchError("dispatch candidate source is invalid")
    if (
        value["candidate_recognized"] != (value["candidate_source"] != "none")
        or (value["result_available"] and not value["candidate_recognized"])
    ):
        raise DispatchError("dispatch candidate state is inconsistent")
    _validate_worktree_state(value)
    _validate_attempt_state(value)
    _validate_scope_state(value)
    _validate_self_verification_state(value)
    _validate_source_guard(value)
    _validate_candidate_lifecycle(value)
    _validate_verification_state(value)
    # Exact shape and every field/cross-field rule have passed; preserve input identity.
    return cast(DispatchState, value)


def initial_state(
    command: dict[str, Any], origin: str, attempt: int, *, command_sha: str,
    command_identity: tuple[int, int, int, int, int], stage_sha: str | None,
    stage_identity: tuple[int, int, int, int, int] | None,
    project_boundary: Mapping[str, Any] | None = None,
    schema_bindings: dict[str, Any] | None = None,
    explain_worktree_rejection: bool = False,
    repair_authority_state: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
    now = time.time()
    workflow = command.get("workflow", "legacy")
    max_cycles = command.get("max_cycles", 1)
    try:
        worktree_baseline = WORKTREE._worktree_snapshot(
            command["workdir"], explain_unsupported=explain_worktree_rejection)
    except ResolveUndoPresentError:
        worktree_baseline = None
    if worktree_baseline is not None:
        worktree_baseline = {key: worktree_baseline[key] for key in ("sha256", "entries")}
    state = {
        "schema_version": CURRENT_STATE_SCHEMA,
        "kind": "agy-worker-dispatch-state",
        "sequence": 1,
        "previous_state_sha256": None,
        "job_id": command["job_id"],
        "status": "queued",
        "attempt": attempt,
        "attempt_origin": origin,
        "source_checkout_guard": _pending_source_guard(attempt),
        "reason": None,
        "exit_code": None,
        "controller_pid": None,
        "workdir": command["workdir"],
        "created_epoch": now,
        "started_epoch": None,
        "updated_epoch": now,
        "finished_epoch": None,
        "elapsed_seconds": 0.0,
        "progress_count": 0,
        "last_progress_epoch": None,
        "notice_count": 0,
        "hard_seconds": float(command["hard_seconds"]),
        "max_seconds": float(command["max_seconds"]),
        "idle_seconds": float(command["idle_seconds"]),
        "attempt_base_elapsed": 0.0,
        "cancel_requested": False,
        "conversation_id": None,
        "resume_available": False,
        "remote_cancel_unverified": False,
        "result_path": None,
        "stream_path": None,
        "stderr_path": None,
        "agy_returncode": None,
        "limit_kind": None,
        "command_sha256": command_sha,
        "command_identity": list(command_identity),
        "stage_sha256": stage_sha,
        "stage_identity": None if stage_identity is None else list(stage_identity),
        "result_sha256": None,
        "result_identity": None,
        "workflow": workflow,
        "max_cycles": max_cycles,
        "cycle": attempt,
        "phase": "dispatching",
        "assurance": "pending",
        "check_summary": None,
        "check_counts": {"passed": 0, "failed": 0, "advisory": 0, "missing": 0},
        "verification_path": None,
        "verification_sha256": None,
        "verification_identity": None,
        "continue_available": False,
        "last_success_path": None,
        "last_success_sha256": None,
        "last_success_identity": None,
        "project_boundary": (
            project_boundary if project_boundary is not None
            else WORKTREE._project_boundary(command["workdir"]) if workflow == "project"
            else None
        ),
        "candidate_recognized": False,
        "candidate_source": "none",
        "result_available": False,
        "worktree_reconciliation": "not_applicable",
        "worktree_changes_present": None,
        "worktree_changed_since_dispatch": None,
        "driver_disposition": "not_applicable",
        "failure_stage": None,
        "last_activity": None,
        # Deprecated v5 storage only.  V7 never writes a semantic controller
        # recommendation; public aliases are derived at read time.
        "next_action": "none",
        "next_action_command": None,
        "worktree_baseline": worktree_baseline,
        "provider_schema_sha256": None if schema_bindings is None else schema_bindings["provider_schema_sha256"],
        "provider_schema_identity": None if schema_bindings is None else schema_bindings["provider_schema_identity"],
        "canonical_schema_sha256": None if schema_bindings is None else schema_bindings["canonical_schema_sha256"],
        "canonical_schema_identity": None if schema_bindings is None else schema_bindings["canonical_schema_identity"],
        "candidate_worktree_sha256": None,
        "candidate_worktree_entries": None,
        "candidate_worktree_path_facts": None,
        "selection_sha256": command.get("selection_sha256"),
        "selection_identity": command.get("selection_identity"),
    }
    state["worktree_snapshot_algorithm"] = CURRENT_WORKTREE_SNAPSHOT_ALGORITHM
    root_identity = _dispatch_root_identity(command["workdir"])
    if root_identity is None:
        raise DispatchError("dispatch worktree root cannot be bound")
    state["worktree_root_identity"] = root_identity
    state["provider_terminal_status"] = "unknown"
    state.update({
        "allow_scoped_repair": command.get("allow_scoped_repair", False),
        "repair_authority_sha256": command.get("repair_authority_sha256"),
        "repair_lineage_sha256": None,
        "repair_parent_result_sha256": None,
        "repair_parent_worktree_sha256": None,
        "repair_lineage_attempt": None,
        "allow_self_verification": command.get("allow_self_verification", False),
        "self_verification_elapsed_seconds": 0.0,
        "self_verification_run": 0,
        "self_verification_started_epoch": None,
        "self_verification_return_phase": None,
    })
    state["provider_isolation"] = _provider_isolation_for_command(command)
    if command.get("provider_scope_path") is not None:
        _scope_path, raw_scope, scope_info = _read_provider_scope_file(
            command["provider_scope_path"], MAX_COMMAND_BYTES,
        )
        if digest(raw_scope) != command["provider_scope_sha256"]:
            raise DispatchError("provider scope file changed since dispatch")
        if list(_identity(scope_info)) != command["provider_scope_identity"]:
            raise DispatchError("provider scope file identity changed since dispatch")
        try:
            scope = WORKTREE._parse_provider_scope(raw_scope)
        except ValueError as exc:
            raise DispatchError(f"invalid provider scope: {exc}") from exc
        readable_manifest = WORKTREE._scan_readable_worktree(command["workdir"])
        manifest_sha = WORKTREE._manifest_digest(readable_manifest)
        WORKTREE._validate_scope_against_worktree(scope, command["workdir"], readable_manifest)
        selected_manifest = WORKTREE._build_selected_content_manifest(command["workdir"], scope)
        selected_sha = WORKTREE._selected_content_digest(selected_manifest)
        policy_sha = WORKTREE._canonical_digest(scope)
        transmission_sha = _bound_transmission_sha256(
            command, policy_sha, manifest_sha, selected_sha,
        )
        _require_scoped_transmission_authority(
            command,
            state if repair_authority_state is None else repair_authority_state,
            selected_content_sha256=selected_sha,
            transmission_sha256=transmission_sha,
            provider_origin=origin,
        )
        state.update({
            "provider_scope_path": command["provider_scope_path"],
            "provider_scope_sha256": command["provider_scope_sha256"],
            "provider_scope_identity": command["provider_scope_identity"],
            "approved_transmission_sha256": command["approved_transmission_sha256"],
            "transmission_sha256": transmission_sha,
            "initial_content_transmission_sha256": _initial_content_transmission(command),
            "selected_content_sha256": selected_sha,
            "selected_file_count": sum(1 for e in selected_manifest if e["kind"] == "file"),
            "selected_tree_count": sum(1 for e in selected_manifest if e["kind"] == "directory"),
            "provider_stage_path": None,
            "provider_stage_identity": None,
            "provider_stage_manifest_sha256": None,
            "reconciliation_manifest_sha256": None,
        })
    else:
        approved_whole_sha = command.get("approved_whole_worktree_sha256")
        if approved_whole_sha is not None and origin == "initial":
            content = WORKTREE.whole_worktree_content_manifest(command["workdir"])
            content_sha = content["manifest_sha256"]
            readable_manifest = WORKTREE._scan_readable_worktree(command["workdir"])
            if content_sha != command["whole_worktree_content_sha256"]:
                raise DispatchError("whole-worktree content binding changed")
            if WORKTREE._manifest_digest(readable_manifest) != command["launch_authority"]["content"]["manifest_sha256"]:
                raise DispatchError(
                    "approved whole-worktree manifest does not match current worktree"
                )
        state.update({
            "provider_scope_path": None,
            "provider_scope_sha256": None,
            "provider_scope_identity": None,
            "approved_transmission_sha256": None,
            "initial_content_transmission_sha256": None,
            "transmission_sha256": None,
            "selected_content_sha256": None,
            "selected_file_count": None,
            "selected_tree_count": None,
            "provider_stage_path": None,
            "provider_stage_identity": None,
            "provider_stage_manifest_sha256": None,
            "reconciliation_manifest_sha256": None,
        })
    state["whole_worktree_content_sha256"] = command.get("whole_worktree_content_sha256")
    state["native_grant_profile"] = command.get("native_grant_profile", "baseline")
    return state


def _transition_locked(
    job: Path, state: Mapping[str, Any], prior_raw: bytes, updates: dict[str, Any],
) -> tuple[DispatchState, bytes, str]:
    current, _info = read_regular(job / STATE_NAME, MAX_STATE_BYTES, "dispatch state")
    if current != prior_raw:
        raise DispatchError("dispatch state changed before transition")
    value = dict(state)
    value.update(updates)
    value["next_action"] = "none"
    value["next_action_command"] = None
    value["sequence"] = state["sequence"] + 1
    value["previous_state_sha256"] = digest(prior_raw)
    value["updated_epoch"] = time.time()
    validate_state(value)
    raw, sha = write_atomic(job, STATE_NAME, value)
    return validate_state(value), raw, sha


def transition(job: Path, state: Mapping[str, Any], prior_raw: bytes, updates: dict[str, Any]) -> tuple[DispatchState, bytes, str]:
    with state_lock(job):
        return _transition_locked(job, state, prior_raw, updates)


def _live_elapsed(value: Mapping[str, Any], now: float) -> float:
    elapsed = float(value["elapsed_seconds"])
    if value["status"] in {"running", "cancel-requested"} and value["started_epoch"] is not None:
        elapsed = max(
            elapsed,
            float(value["attempt_base_elapsed"]) + max(0.0, now - float(value["started_epoch"])),
        )
    return elapsed


def _verification_live_elapsed(value: Mapping[str, Any], now: float) -> float:
    elapsed = float(value.get("self_verification_elapsed_seconds", 0.0))
    started = value.get("self_verification_started_epoch")
    if value.get("phase") == "self-verifying" and started is not None:
        elapsed += max(0.0, now - float(started))
    return elapsed


def _total_live_elapsed(value: Mapping[str, Any], now: float) -> float:
    return _live_elapsed(value, now) + _verification_live_elapsed(value, now)


def _provider_max_seconds(value: Mapping[str, Any]) -> float:
    """Keep provider hard/idle clocks separate from the shared job allowance."""
    return max(0.0, float(value["max_seconds"])
               - float(value.get("self_verification_elapsed_seconds", 0.0)))


def _freeze_reaped_runtime(
    job: Path, attempt: int, controller_pid: int, elapsed: float,
) -> tuple[DispatchState, bytes, str, str | None]:
    """Atomically stop the provider clock and classify its locked deadline.

    Reaping is the last provider-owned operation.  Everything after this
    point—envelope extraction, schema validation, and candidate worktree
    reconciliation—must observe the exact persisted value rather than accrue
    controller-local time.  Reload under the lock instead of applying a stale
    controller snapshot so a just-approved extension is included, while a
    prior freeze makes the same extension predicate ineligible.
    """
    with state_lock(job):
        current, raw, _sha = load_state(job)
        if (
            current["attempt"] != attempt
            or current["controller_pid"] != controller_pid
            or current["status"] not in {"running", "cancel-requested"}
        ):
            raise DispatchError("dispatch changed before runtime freeze")
        frozen_elapsed = max(float(elapsed), float(current["elapsed_seconds"]))
        current, raw, sha = _transition_locked(job, current, raw, {
            "elapsed_seconds": frozen_elapsed,
            "started_epoch": None,
        })
        deadline: str | None = None
        # Cancellation is an approved state fact and has priority over a
        # post-reap deadline classification.  The terminal projection still
        # handles it with the existing remote-cancel semantics.
        if not current["cancel_requested"]:
            if frozen_elapsed >= _provider_max_seconds(current):
                deadline = "max-runtime"
            elif frozen_elapsed >= float(current["hard_seconds"]):
                deadline = "hard"
        return current, raw, sha, deadline


def _is_active(value: Mapping[str, Any]) -> bool:
    return value["status"] in {"queued", "running", "cancel-requested"}


def _extend_is_eligible(value: Mapping[str, Any], now: float) -> bool:
    """One cheap state/time predicate shared by status and the lock guard."""
    elapsed = _live_elapsed(value, now)
    return bool(
        _is_active(value)
        # The lease is a provider-runtime control, never a way to extend
        # queued preflight or post-reap controller reconciliation.
        and value["started_epoch"] is not None
        and not value["cancel_requested"]
        and value["progress_count"] > 0
        and value["last_progress_epoch"] is not None
        and now - float(value["last_progress_epoch"]) < float(value["idle_seconds"])
        # ``--by`` has one-second precision.  Advertising extend with less
        # than one second before either limit would name an operation the lock
        # guard must reject.
        and elapsed + 1.0 <= float(value["hard_seconds"])
        and float(value["hard_seconds"]) + 1.0 <= _provider_max_seconds(value)
    )


def _resume_is_eligible(value: Mapping[str, Any], now: float) -> bool:
    """Mirror the strict same-conversation resume guard used before staging."""
    return bool(
        value["status"] == "failed"
        and not value["candidate_recognized"]
        and _source_guard_reason(value) is None
        and value.get("reason") not in {"selection_preflight_failed", "model_selection_rejected", "permission_required"}
        and value["resume_available"]
        and isinstance(value["conversation_id"], str)
        and _restart_guard_accepts(value, elapsed_seconds=_live_elapsed(value, now))
    )


def _continue_is_eligible(value: Mapping[str, Any], now: float) -> bool:
    """Return the state-only half of the exact continuation guard."""
    return bool(value["continue_available"] and _continue_from_facts(value, now))


def _continue_from_facts(value: Mapping[str, Any], now: float) -> bool:
    """Recompute eligibility after verification without a circular stored flag."""
    return bool(
        value["workflow"] != "legacy"
        # A failed final direct-selection proof invalidates provider launch
        # authority for this frozen job.  Keep its bound candidate available
        # for result review/finalization, but never reuse the selection through
        # another same-conversation continuation.
        # A provider-reported permission denial likewise preserves the candidate
        # for review, but is not authority for an automatic continuation.
        and _source_guard_reason(value) is None
        and value["reason"] not in {"selection_preflight_failed", "model_selection_rejected", "permission_required"}
        and value["candidate_recognized"]
        and value["result_available"]
        and value["candidate_source"] != "provider_cancelled"
        and value["status"] in {"succeeded", "failed"}
        and _controller_phase(value) in {"awaiting-verification", "repair-failed"}
        and isinstance(value["conversation_id"], str)
        and value["cycle"] < value["max_cycles"]
        and _total_live_elapsed(value, now) < float(value["max_seconds"])
        and (
            value.get("provider_scope_path") is None
            or value.get("transmission_sha256") == value.get("initial_content_transmission_sha256")
            or (
                value.get("allow_scoped_repair", False)
                and value.get("repair_lineage_sha256") is not None
                and value.get("repair_lineage_attempt") == value["attempt"]
            )
        )
    )


def _finalize_is_eligible(value: Mapping[str, Any]) -> bool:
    """Return the state-only half of the exact finalization guard."""
    return bool(
        value["candidate_recognized"] and value["result_available"]
        and value["result_path"] and value["workflow"] != "legacy"
        and value["driver_disposition"] == "unreviewed"
        and (value["assurance"] == "pending")
        and _controller_phase(value) in {"awaiting-verification", "repair-failed"}
    )


def _verification_copy_is_eligible(value: Mapping[str, Any]) -> bool:
    """Return the exact state predicate for the current candidate copy helper."""
    return bool(
        _finalize_is_eligible(value)
    )


def _controller_phase(value: Mapping[str, Any]) -> str | None:
    """Project controller-owned mechanics from the current bound state."""
    if _source_guard_reason(value) is not None:
        return "blocked"
    if value.get("phase") == "self-verifying":
        return "self-verifying"
    if value["driver_disposition"] in {"verified", "partially_verified", "rejected"}:
        return "completed"
    if value["driver_disposition"] == "blocked" or (
        value["candidate_recognized"] and not value["result_available"]
    ):
        return "blocked"
    if _is_active(value):
        return "repairing" if value["attempt_origin"] == "conversation-continue" else "dispatching"
    if value["candidate_recognized"]:
        if value["status"] == "failed" and value["attempt_origin"] == "conversation-continue":
            return "repair-failed"
        return "awaiting-verification"
    if value["status"] in TERMINAL:
        return "repair-failed" if value["attempt_origin"] == "conversation-continue" else "attempt-failed"
    return None


def _candidate_actions_are_bound(job: Path | None, value: Mapping[str, Any]) -> bool:
    """Keep public candidate actions as strict as their mutating commands."""
    return _candidate_binding_error(job, value) is None


def _candidate_binding_error(job: Path | None, value: Mapping[str, Any]) -> Exception | None:
    """Return why the current candidate cannot be bound, or None when it can."""
    if job is None:
        return DispatchError("job directory is unavailable")
    try:
        _bound_current_candidate(job, value)
    except UnsupportedSchemaError:
        raise
    except (OSError, DispatchError) as exc:
        return exc
    return None


def _post_candidate_selection_binding_drift(job: Path | None, value: Mapping[str, Any]) -> bool:
    """Identify a frozen direct-selection failure without publishing its bytes.

    The candidate action binder uses the same selection record, but can also
    reject a result/schema/worktree drift. Text recovery guidance must only
    name a fresh-job handoff for selection drift, so bind the command first and
    then probe its selection record in isolation.
    """
    if job is None or not (
        value["candidate_recognized"] and value["result_available"]
    ):
        return False
    try:
        bound_job = canonical_job(Path(job).resolve(strict=True))
        command = _load_bound_command(bound_job, value, stage_readonly=False)
    except UnsupportedSchemaError:
        raise
    except (OSError, DispatchError):
        return False
    if command.get("selection_path") is None:
        return False
    try:
        _load_bound_selection(command, value)
    except UnsupportedSchemaError:
        raise
    except (OSError, DispatchError):
        return True
    return False


def _lifecycle_mutation_bindings(
    job: Path | None, value: Mapping[str, Any],
) -> tuple[bool, bool]:
    """Return driver-write and provider-launch binding availability.

    Finalization records an exact driver decision without launching a provider.
    Recovery actions additionally require a selection record that is current
    launch authority.  Keep those facts separate so status advertises exactly
    the operations their command guards accept.
    """
    if job is None:
        return False, False
    try:
        bound_job = canonical_job(Path(job).resolve(strict=True))
        command = _load_bound_command(bound_job, value, stage_readonly=False)
    except UnsupportedSchemaError:
        raise
    except (OSError, DispatchError):
        return False, False
    try:
        _bound_lifecycle_inputs(bound_job, value, command)
        provider_launch_bound = (
            not _job_is_inside_worktree(bound_job, command["workdir"])
            and _selection_launch_is_authorized(
                _load_bound_selection(command, value)
            )
        )
    except UnsupportedSchemaError:
        raise
    except (OSError, DispatchError):
        # A changed current scoped candidate is valid driver evidence, but
        # transmitting those new bytes again requires a fresh exact approval
        # that the continuation interface cannot collect. Keep result/finalize
        # available while declining to advertise provider continuation.
        if not (
            value['candidate_recognized'] and value['status'] in TERMINAL
        ):
            return False, False
        try:
            _bound_current_candidate(bound_job, value)
        except UnsupportedSchemaError:
            raise
        except (OSError, DispatchError):
            return False, False
        return True, False
    return True, provider_launch_bound


def _selection_launch_is_authorized(record: dict[str, Any] | None) -> bool:
    return record is None or (
        record.get("schema_version") == MODEL_SELECTION.SELECTION_SCHEMA
        and MODEL_SELECTION.has_current_probed_executable_binding(record.get("probed_executable"))
    )


def _available_actions(
    value: Mapping[str, Any], sha: str, now: float, *, job: Path | None = None,
    candidate_bound: bool | None = None,
    lifecycle_mutation_bound: bool | None = None,
    provider_launch_bound: bool | None = None,
) -> list[dict[str, Any]]:
    """Return only state/time-applicable mechanical controller operations.

    Cancel and extend remain cheap state/time controls.  A terminal candidate is
    revalidated only when it could make a result, continue, or finalize action
    visible, and uses the same binder the command paths require.
    """
    if _source_guard_reason(value) is not None:
        return []
    job_id = value["job_id"]
    actions: list[dict[str, Any]] = []
    if value.get("phase") == "self-verifying":
        return [{
            "action": "wait",
            "command": f"{PUBLIC_LAUNCHER} wait --job-id {job_id} --after-state-sha {sha} --format text",
        }]
    active = _is_active(value)
    if active:
        actions.append({
            "action": "wait",
            "command": f"{PUBLIC_LAUNCHER} wait --job-id {job_id} --after-state-sha {sha} --format text",
        })
    if active and not value["cancel_requested"]:
        actions.append({
            "action": "cancel",
            "command": f"{PUBLIC_LAUNCHER} cancel --job-id {job_id} --approve-state-sha {sha}",
        })
    # A terminal report with an unavailable candidate worktree is forensic
    # state only.  It must not be presented as a route to another provider
    # action, result delivery, continuation, or finalization.
    if (
        not active and value["status"] in TERMINAL
        and value["candidate_recognized"] and not value["result_available"]
        and value["worktree_reconciliation"] == "unavailable"
    ):
        return actions
    if _extend_is_eligible(value, now):
        # The state cannot choose a duration on the caller's behalf.  Keep
        # this guidance deliberately commandless: a copied command with a
        # made-up duration would not share the mutation guard's contract.
        actions.append({
            "action": "extend",
            "requires": ["--by caller-provided DURATION"],
            "guidance": "choose a positive duration that remains within the current maximum runtime",
        })
    terminal_candidate = bool(
        not active and value["status"] in TERMINAL
        and value["candidate_recognized"] and value["result_available"]
    )
    if terminal_candidate and candidate_bound is None:
        candidate_bound = _candidate_actions_are_bound(job, value)
    if terminal_candidate and candidate_bound:
        try:
            CONTAINMENT.require_supported_host()
            self_verification_host_supported = True
        except CONTAINMENT.ContainmentError:
            self_verification_host_supported = False
        if (
            value.get("allow_self_verification")
            and self_verification_host_supported
            and value.get("self_verification_run", 0) < value["attempt"]
            and value.get("phase") in {"awaiting-verification", "repair-failed"}
            and _total_live_elapsed(value, now) < value["max_seconds"]
            and job is not None
            and not _job_is_inside_worktree(job, value["workdir"])
            and lifecycle_mutation_bound is True
        ):
            actions.append({
                "action": "self-verify",
                "command": f"{PUBLIC_LAUNCHER} self-verify --job-id {job_id} --approve-state-sha {sha} --format text",
            })
        actions.append({
            "action": "result",
            "command": f"{PUBLIC_LAUNCHER} result --job-id {job_id} --format json",
        })
        if (
            _verification_copy_is_eligible(value)
            and job is not None
            and not _job_is_inside_worktree(job, value["workdir"])
        ):
            actions.append({
                "action": "verification-copy",
                "command": (
                    f"{PUBLIC_LAUNCHER} verification-copy --job-id {job_id} "
                    "--destination NEW_DIRECTORY_IN_0700_PARENT --format text"
                ),
                "requires": ["new owner-private destination outside the candidate"],
            })
    # A public recovery operation is useful only when the same frozen command,
    # schemas, worktree root/boundary, and selector the command will use are
    # still present.  ``None`` keeps pure in-memory compatibility callers from
    # claiming a failed local probe; CLI status always supplies a concrete bool.
    lifecycle_mutation_available = bool(
        lifecycle_mutation_bound is not False
    )
    provider_mutation_available = bool(
        lifecycle_mutation_available and provider_launch_bound is not False
    )
    if _resume_is_eligible(value, now) and provider_mutation_available:
        actions.append({
            "action": "resume",
            "command": (
                f"{PUBLIC_LAUNCHER} resume --job-id {job_id} --approve-state-sha {sha}"
                + " --format text"
            ),
        })
    if (
        _restart_guard_accepts(value, elapsed_seconds=_live_elapsed(value, now))
        and provider_mutation_available
    ):
        actions.append({
            "action": "restart",
            "command": (
                f"{PUBLIC_LAUNCHER} restart --job-id {job_id} --approve-state-sha {sha}"
                + " --format text"
            ),
        })
    if (
        terminal_candidate and candidate_bound and _continue_is_eligible(value, now)
        and provider_mutation_available
    ):
        stored_feedback = False
        if job is not None and value.get("allow_self_verification"):
            try:
                _bound_self_verification_feedback(job, value)
                stored_feedback = True
            except UnsupportedSchemaError:
                raise
            except (DispatchError, OSError):
                pass
        actions.append({
            "action": "continue",
            "command": (
                f"{PUBLIC_LAUNCHER} continue --job-id {job_id} --approve-state-sha {sha} "
                + ("--use-self-verification" if stored_feedback else "< DRIVER_VERIFICATION_JSON")
            ),
            "requires": [] if stored_feedback else ["verification JSON"],
        })
    if (
        terminal_candidate and candidate_bound and _finalize_is_eligible(value)
        and lifecycle_mutation_available
    ):
        actions.append({
            "action": "finalize",
            "command": (
                f"{PUBLIC_LAUNCHER} finalize --job-id {job_id} --approve-state-sha {sha} "
                + "--assurance ASSURANCE < DRIVER_VERIFICATION_JSON"
            ),
            "requires": ["--assurance", "verification JSON"],
        })
    return actions


def _public_next_action(actions: list[dict[str, Any]]) -> tuple[str, str | None]:
    if not actions:
        return "none", None
    # `resume` and `restart` are distinct caller-owned recovery policies.  The
    # deprecated scalar alias must not turn their deterministic display order
    # into a controller recommendation.
    if {"resume", "restart"} <= {str(item.get("action")) for item in actions}:
        return "none", None
    first = actions[0]
    return str(first["action"]), first.get("command") if isinstance(first.get("command"), str) else None


def _cycle_budget_explanation(value: Mapping[str, Any]) -> str | None:
    if value["status"] == "cancelled" and value["reason"] == "interrupted" and not value["candidate_recognized"]:
        return "The interrupted attempt consumed one cycle even though it produced no candidate; a fresh restart consumes another cycle."
    return None


def _provider_execution_from_bound_command(command: dict[str, Any]) -> dict[str, Any]:
    """Describe the current bound launch mechanics."""

    provider_isolation = _provider_isolation_for_command(command)
    scoped = command.get("provider_scope_path") is not None
    sandboxed = "--sandbox" in command["argv"]
    return {
        "legacy": False,
        "scope": "provider-scope" if scoped else "whole-worktree",
        "agy_sandbox": sandboxed,
        "native_containment": provider_isolation == "native",
    }


def bound_provider_execution(job: Path, state: Mapping[str, Any]) -> dict[str, Any]:
    """Bind execution facts to the command, not the state projection."""

    command = _load_bound_command(job, state, stage_readonly=False)
    return _provider_execution_from_bound_command(command)


def public_status(value: Mapping[str, Any], sha: str, *, job: Path | None = None) -> dict[str, Any]:
    _require_supported_schema(value, label="dispatch state", supported=(CURRENT_STATE_SCHEMA,))
    if job is not None:
        _check_existing_command_schema(job)
    now = time.time()
    elapsed = _live_elapsed(value, now)
    last_age = None
    if value["last_progress_epoch"] is not None:
        last_age = max(0.0, now - value["last_progress_epoch"])
    candidate_bound: bool | None = None
    lifecycle_mutation_bound: bool | None = None
    provider_launch_bound: bool | None = None
    terminal_candidate = bool(
        not _is_active(value) and value.get("phase") != "self-verifying" and value["status"] in TERMINAL
        and value["candidate_recognized"] and value["result_available"]
    )
    # A read-only status never persists a deferred source veto; it only names it.
    detected_source_reason: str | None = None
    if terminal_candidate:
        binding_error = _candidate_binding_error(job, value)
        candidate_bound = binding_error is None
        if isinstance(binding_error, SourceGuardError):
            detected_source_reason = binding_error.reason
        # Candidate reconciliation can take meaningful bounded time.  Resample
        # the clocks so an extension that expired during that scan is omitted.
        now = time.time()
        elapsed = _live_elapsed(value, now)
    if job is not None and (
        _resume_is_eligible(value, now)
        or _restart_guard_accepts(value, elapsed_seconds=_live_elapsed(value, now))
        or _continue_is_eligible(value, now)
        or _finalize_is_eligible(value)
    ):
        lifecycle_mutation_bound, provider_launch_bound = _lifecycle_mutation_bindings(
            job, value
        )
    available_actions = _available_actions(
        value, sha, now, job=job, candidate_bound=candidate_bound,
        lifecycle_mutation_bound=lifecycle_mutation_bound,
        provider_launch_bound=provider_launch_bound,
    )
    action_names = {item["action"] for item in available_actions}
    public_result_available = bool(
        value["candidate_recognized"] and "result" in action_names
    )
    # This is the canonical digest of the bound result bytes, never a worker
    # claim, path, or prose.  Do not expose it for a merely remembered or stale
    # candidate: consumers can safely use it as Verification v2 input only when
    # the same public surface makes `result` available.
    public_candidate_sha256 = (
        value["result_sha256"] if public_result_available else None
    )
    public_continue_available = "continue" in action_names
    public_failure_stage = (
        "binding_failure"
        if terminal_candidate and candidate_bound is False
        else value["failure_stage"]
    )
    next_action, next_action_command = _public_next_action(available_actions)
    public_assurance = (
        "blocked" if _source_guard_reason(value) is not None else
        value["driver_disposition"]
        if value["driver_disposition"] in {"verified", "partially_verified", "rejected", "blocked"}
        else None
    )
    provider_execution = None
    if job is not None:
        try:
            provider_execution = bound_provider_execution(job, value)
        except UnsupportedSchemaError:
            raise
        except (OSError, DispatchError):
            provider_execution = None
    public_provider_isolation = (
        value["provider_isolation"]
        if job is None else
        None
        if provider_execution is None or provider_execution["legacy"] else
        value["provider_isolation"]
    )
    return {
        "attempt": value["attempt"],
        "attempt_origin": value["attempt_origin"],
        # Only a bound finalize records a Codex/driver decision.  Pending is
        # local lifecycle plumbing, never an assurance claim.
        "assurance": public_assurance,
        "check_counts": value["check_counts"],
        "check_summary": value["check_summary"],
        "cycle": value["cycle"],
        "elapsed_seconds": round(elapsed, 3),
        "self_verification_elapsed_seconds": round(_verification_live_elapsed(value, now), 3),
        "total_elapsed_seconds": round(_total_live_elapsed(value, now), 3),
        "exit_code": value["exit_code"],
        "hard_seconds": value["hard_seconds"],
        # Kept as a deprecated compatibility hint.  It says nothing about a clean
        # worktree and must not be used as an acceptance decision.
        "has_prior_candidate": bool(value["result_path"] or value["last_success_path"]),
        "candidate_recognized": value["candidate_recognized"],
        "candidate_source": value["candidate_source"],
        "candidate_sha256": public_candidate_sha256,
        "result_available": public_result_available,
        "worktree_reconciliation": value["worktree_reconciliation"],
        "worktree_changes_present": value["worktree_changes_present"],
        "worktree_changed_since_dispatch": value["worktree_changed_since_dispatch"],
        "driver_disposition": value["driver_disposition"],
        "failure_stage": public_failure_stage,
        "last_activity": value["last_activity"],
        "available_actions": available_actions,
        # Deprecated mechanical aliases retained for additive consumers.  They
        # are derived from the same live predicates as available_actions, never
        # from a controller recommendation stored in state.
        "next_action": next_action,
        "next_action_command": next_action_command,
        "job_id": value["job_id"],
        "last_progress_age_seconds": None if last_age is None else round(last_age, 3),
        "limit_kind": value["limit_kind"],
        "max_seconds": value["max_seconds"],
        "max_cycles": value["max_cycles"],
        "cycle_budget_explanation": _cycle_budget_explanation(value),
        "notice_count": value["notice_count"],
        "progress_count": value["progress_count"],
        "provider_isolation": public_provider_isolation,
        "provider_execution": provider_execution,
        "controller_phase": _controller_phase(value),
        "phase": value["phase"],
        "legacy_result_provenance": (
            "none"
        ),
        "migration_binding_sha256": None,
        "reason": value["reason"],
        "source_checkout_guard": value["source_checkout_guard"],
        "reason_message": (
            MODEL_SELECTION_REJECTED_MESSAGE
            if value["reason"] == "model_selection_rejected"
            else SOURCE_GUARD_MESSAGES.get(detected_source_reason or value["reason"])
        ),
        "remote_cancel_unverified": value["remote_cancel_unverified"],
        "resume_available": "resume" in action_names,
        "continue_available": public_continue_available,
        "state_sha256": sha,
        "status": value["status"],
        "workflow": value["workflow"],
    }


def print_json(value: Any) -> None:
    sys.stdout.buffer.write(canonical(value))
    sys.stdout.buffer.flush()


def print_text_status(value: Mapping[str, Any], sha: str, *, job: Path | None = None) -> None:
    """Print exactly three private-data-free lines for the human CLI surface."""
    counts = value["check_counts"]
    public = public_status(value, sha, job=job)
    actions = public["available_actions"]
    action_names = {item["action"] for item in actions}
    next_command = public["next_action_command"]
    result_command = next((
        item.get("command") for item in actions
        if item["action"] == "result" and isinstance(item.get("command"), str)
    ), None)
    resume_command = next((
        item.get("command") for item in actions
        if item["action"] == "resume" and isinstance(item.get("command"), str)
    ), None)
    restart_command = next((
        item.get("command") for item in actions
        if item["action"] == "restart" and isinstance(item.get("command"), str)
    ), None)
    finalized_result = bool(
        result_command is not None
        and value["driver_disposition"] in {
            "verified", "partially_verified", "rejected", "blocked",
        }
    )
    candidate_decision = (
        "then the driver chooses an eligible continue or finalize."
        if {"continue", "finalize"} <= action_names else
        "then the driver may choose the eligible continue action."
        if "continue" in action_names else
        "then the driver may choose the eligible finalize action."
        if "finalize" in action_names else
        "then no further driver decision is currently listed."
    )
    if next_command is None:
        # Continue/finalize need driver-owned bounded JSON.  This is still an
        # exact mechanical invocation, not a controller recommendation.
        action = next((item["action"] for item in actions if item["action"] in {"continue", "finalize"}), None)
        if action == "continue":
            next_command = (
                f"{PUBLIC_LAUNCHER} continue --job-id {value['job_id']} --approve-state-sha {sha} "
                "< DRIVER_VERIFICATION_JSON"
            )
        elif action == "finalize":
            next_command = (
                f"{PUBLIC_LAUNCHER} finalize --job-id {value['job_id']} --approve-state-sha {sha} "
                "--assurance ASSURANCE < DRIVER_VERIFICATION_JSON"
            )
    reason = public["reason"] if public["reason"] is not None else "none"
    failure_stage = public["failure_stage"] if public["failure_stage"] is not None else "none"
    selection_preflight_recovery_blocked = bool(
        public["reason"] == "selection_preflight_failed"
        or _post_candidate_selection_binding_drift(job, value)
    )
    cancelled_unreviewed_restart_guidance = (
        f" Available fresh restart command: {restart_command}."
        if (
            value["status"] == "cancelled"
            and value["driver_disposition"] == "unreviewed"
            and restart_command is not None
        ) else ""
    )
    ambiguous_recovery_options = {"resume", "restart"} <= action_names
    candidate_free_no_actions = bool(
        not actions
        and not value["candidate_recognized"]
    )
    candidate_free_runtime_budget_exhausted = bool(
        candidate_free_no_actions and value["limit_kind"] == "max-runtime"
    )
    candidate_free_attempt_budget_exhausted = bool(
        candidate_free_no_actions
        and not candidate_free_runtime_budget_exhausted
        and value["attempt"] >= value["max_cycles"]
    )
    lines = (
        f"Provider attempt: {value['status']}; reason: {reason}; failure stage: {failure_stage}; bound result available: {'yes' if public['result_available'] else 'no'}; driver disposition: {value['driver_disposition']}."
        + (f" {public['reason_message']}" if public["reason_message"] else "")
        + (" Native host prerequisite unavailable: macOS denied sandbox_apply (this can occur when the driver host is already sandboxed; use a compatible driver host with the same approved native mode) or the dedicated agy keychain is missing or locked (see the job stderr and the native setup section of references/TROUBLESHOOTING.md)." if reason == "native_host_sandbox_unavailable" else ""),
        f"Driver evidence: {counts['passed']} passed, {counts['failed']} failed, {counts['advisory']} advisory, {counts['missing']} missing; cycle: {public['cycle']}/{public['max_cycles']}."
        + (f" {public['cycle_budget_explanation']}" if public['cycle_budget_explanation'] else ""),
        (
            (
                f"Next safe action: retrieve current bound result JSON with {result_command}; review it and run driver checks, then the driver may finalize after review. No provider-launching same-job recovery is available."
                if result_command is not None and "finalize" in action_names else
                f"Next safe action: retrieve current bound result JSON with {result_command}; no provider-launching same-job recovery is available."
                if result_command is not None else
                "Next safe action: create a fresh job using the unchanged caller selection after reviewing the current sanitized agy interface evidence. No same-job action is available."
            )
            if selection_preflight_recovery_blocked else
            (
                f"Next safe action: optional finalized result JSON readback with {result_command}; driver disposition is already recorded; do not construct Verification v2, continue, or finalize. Available fresh restart command: {restart_command}."
                if restart_command is not None else
                f"Next safe action: optional finalized result JSON readback with {result_command}; driver disposition is already recorded; do not construct Verification v2, continue, or finalize."
            )
            if finalized_result else
            f"Next safe action: retrieve current bound result JSON with {result_command}; review it and run driver checks, construct Verification v2, {candidate_decision}{cancelled_unreviewed_restart_guidance}"
            if result_command is not None else
            f"Next safe actions: exact-conversation resume: {resume_command}; fresh-attempt restart: {restart_command}."
            if ambiguous_recovery_options and resume_command is not None and restart_command is not None else
            f"Next safe action: exact-conversation resume: {resume_command}."
            if resume_command is not None and "resume" in action_names else
            f"Next safe action: fresh-attempt restart: {restart_command}."
            if restart_command is not None and "restart" in action_names else
            "Next safe action: none; the current runtime budget is exhausted."
            if candidate_free_runtime_budget_exhausted else
            "Next safe action: none; the current attempt budget is exhausted."
            if candidate_free_attempt_budget_exhausted else
            f"Next safe action: {next_command}." if next_command is not None else "Next safe action: none."
        ),
    )
    sys.stdout.buffer.write(("\n".join(lines) + "\n").encode("utf-8"))
    sys.stdout.buffer.flush()


def print_control_status(
    value: Mapping[str, Any], sha: str, output_format: str, *, job: Path | None = None,
) -> None:
    if output_format == "text":
        print_text_status(value, sha, job=job)
    else:
        print_json(public_status(value, sha, job=job))


def _state_approval_error(state: Mapping[str, Any], sha: str, action: str) -> DispatchError:
    """Keep stale approval recovery useful without exposing private controller data."""
    suffix = {
        "continue": " < DRIVER_VERIFICATION_JSON",
        "finalize": " --assurance ASSURANCE < DRIVER_VERIFICATION_JSON",
        # Duration is caller-owned input.  A placeholder is deliberately not
        # an executable-looking exact duration, and never invents a value.
        "extend": " --by DURATION",
    }.get(action, "")
    return DispatchError(
        "state approval is missing or stale; rerun: "
        f"{PUBLIC_LAUNCHER} {action} --job-id {state['job_id']} --approve-state-sha {sha}{suffix}"
    )


def _missing_state_approval(job: Path, action: str) -> DispatchError:
    state, _raw, sha = read_state_snapshot(job)
    return _state_approval_error(state, sha, action)


def _attempt_paths(job: Path, attempt: int) -> tuple[Path, Path, Path]:
    if attempt == 1:
        return job / "stream.ndjson", job / "stderr.txt", job / "envelope.json"
    prefix = f"attempt-{attempt:03d}"
    return job / f"{prefix}.stream.ndjson", job / f"{prefix}.stderr.txt", job / f"{prefix}.envelope.json"


def _bound_whole_worktree_base(workdir: str, expected: str | None, workflow: str) -> str | None:
    """Bind the gate's Git reference to HEAD before the first worker launch."""
    if expected is not None and COMMIT_RE.fullmatch(expected) is None:
        raise DispatchError("base commit is invalid")
    try:
        actual = CANDIDATE_STATE._git(
            Path(workdir), "rev-parse", "--verify", "HEAD^{commit}",
        ).decode("ascii", "strict").strip()
    except (CANDIDATE_STATE.CandidateStateError, UnicodeError):
        if expected is not None or workflow in {"task", "project"}:
            raise DispatchError("Git base is unavailable") from None
        return None
    if COMMIT_RE.fullmatch(actual) is None or (expected is not None and expected != actual):
        raise DispatchError("Git HEAD differs from the immutable base commit")
    return actual


def _whole_worktree_change_hint(workdir: Path, base: str) -> str:
    """Show preexisting and prior-cycle changes without making worker claims evidence."""
    try:
        raw = CANDIDATE_STATE._git(
            workdir, "diff", "--name-status", "--no-renames", "-z", base, "--",
        )
        parts = [part for part in raw.split(b"\0") if part]
        if len(parts) % 2:
            raise DispatchError("Git change summary is invalid")
        changes = [
            {"path": parts[index + 1].decode("utf-8", "surrogateescape"),
             "change": {b"A": "created", b"D": "deleted"}.get(parts[index], "modified")}
            for index in range(0, len(parts), 2)
        ]
        untracked = CANDIDATE_STATE._git(
            workdir, "ls-files", "--others", "--exclude-standard", "-z", "--",
        )
        changes.extend(
            {"path": path.decode("utf-8", "surrogateescape"), "change": "created"}
            for path in untracked.split(b"\0") if path
        )
        ignored = CANDIDATE_STATE._git(
            workdir, "ls-files", "--others", "--ignored", "--exclude-standard", "-z", "--",
        )
        changes.extend(
            {"path": path.decode("utf-8", "surrogateescape"), "change": "created"}
            for path in ignored.split(b"\0") if path
        )
    except CANDIDATE_STATE.CandidateStateError as exc:
        raise DispatchError("Git change summary is unavailable") from exc
    if len(changes) > 64:
        return (f"Driver currently observes {len(changes)} changed paths against the base; "
                "the list is too long for this prompt. Report all net changes you can establish; "
                "the gate will reject omissions.")
    changes.sort(key=lambda item: item["path"])
    encoded = json.dumps(changes, ensure_ascii=True, separators=(",", ":"))
    if len(encoded.encode("utf-8")) > 8192:
        return (f"Driver currently observes {len(changes)} changed paths against the base; "
                "the list is too long for this prompt. Report all net changes you can establish; "
                "the gate will reject omissions.")
    return "Driver currently observes these net changes against the base: " + encoded


def _bind_workspace_prompt(
    argv: list[str], workspace_root: Path, *, scoped: bool,
    provider_isolation: str, base_commit: str | None = None,
) -> str:
    """Bind every worker's file tools to the exact provider launch cwd."""
    if argv.count("--print") != 1:
        raise DispatchError("dispatch argv contract is invalid")
    print_index = argv.index("--print")
    if print_index + 1 >= len(argv):
        raise DispatchError("dispatch argv contract is invalid")
    prompt = argv[print_index + 1]
    if provider_isolation not in {"session", "native"}:
        raise DispatchError("dispatch provider isolation is invalid")
    hint = _whole_worktree_change_hint(workspace_root, base_commit) if not scoped and base_commit else ""
    prefix = LAUNCH_AUTHORITY.workspace_prefix(
        workspace_root, scoped=scoped, provider_isolation=provider_isolation,
        base_commit=base_commit, change_hint=hint)
    expected = prefix + prompt
    argv[print_index + 1] = expected
    return expected


def _init_cwd_matches_launch(init_value: dict[str, Any], launch_cwd: str) -> bool:
    """Bind a provider-reported cwd only when the stream protocol supplies one."""
    reported = init_value.get("cwd")
    if reported is None:
        return True
    if not isinstance(reported, str) or not reported or "\x00" in reported:
        return False
    try:
        return (
            os.path.isabs(reported)
            and reported == os.path.realpath(reported)
            and reported == os.path.realpath(launch_cwd)
        )
    except OSError:
        return False


def _provider_environment(command: dict[str, Any]) -> dict[str, str]:
    """Use the existing curated child environment for both launch modes."""

    if _provider_isolation_for_command(command) in {"session", "native"}:
        return MODEL_SELECTION.child_environment(command["provider_env"])
    raise DispatchError("dispatch provider isolation is invalid")


def _stage_relative_declared_path(path: str, stage_dir: Path) -> str | None:
    """Accept a canonical absolute report only when it names this exact stage."""
    if not path or "\x00" in path:
        return None
    if os.path.isabs(path):
        root = str(stage_dir)
        if (
            not os.path.isabs(root)
            or os.path.normpath(root) != root
            or not path.startswith(root + os.sep)
        ):
            return None
        path = path[len(root) + 1:]
    if (
        not path
        or os.path.normpath(path) != path
        or any(part in {"", ".", ".."} for part in path.split(os.sep))
    ):
        return None
    return path


def _canonicalize_scoped_report_paths(value: dict[str, Any], stage_dir: Path) -> dict[str, Any]:
    """Canonicalize only exact stage-child claims before envelope binding."""
    declared = value.get("files_changed")
    if not isinstance(declared, list):
        return value
    normalized: list[Any] = []
    for item in declared:
        if not isinstance(item, dict):
            normalized.append(item)
            continue
        rewritten = dict(item)
        path = rewritten.get("path")
        if isinstance(path, str) and os.path.isabs(path):
            relative_path = _stage_relative_declared_path(path, stage_dir)
            if relative_path is not None:
                rewritten["path"] = relative_path
        normalized.append(rewritten)
    return {**value, "files_changed": normalized}


def _declared_scoped_mutations_match(
    envelope: Path, binding: tuple[str, tuple[int, int, int, int, int]],
    operations: list[dict[str, Any]], stage_dir: Path,
) -> bool:
    """Require an envelope to declare exactly the staged operations to reconcile."""
    try:
        raw, info = read_regular(envelope, 1024 * 1024, "dispatch result")
        if digest(raw) != binding[0] or _identity(info) != binding[1]:
            return False
        value = parse_json(raw, "dispatch result")
        declared = value.get("files_changed") if isinstance(value, dict) else None
    except (DispatchError, OSError):
        return False
    if not isinstance(declared, list):
        return False
    mapping = {"create": "created", "replace": "modified", "delete": "deleted"}
    expected: set[tuple[str, str]] = set()
    for operation in operations:
        # The public envelope contract declares files, while reconciliation
        # carries directory scaffolding so nested file operations can be
        # applied descriptor-safely. Directory operations are not reportable
        # through ``files_changed`` and therefore cannot be part of this exact
        # file declaration comparison.
        if operation.get("kind") != "file":
            continue
        path, op = operation.get("path"), operation.get("op")
        change = mapping.get(op) if isinstance(op, str) else None
        if not isinstance(path, str) or change is None:
            return False
        item = (path, change)
        if item in expected:
            return False
        expected.add(item)
    observed: set[tuple[str, str]] = set()
    for item in declared:
        if not isinstance(item, dict):
            return False
        path, change = item.get("path"), item.get("change")
        if not isinstance(path, str) or not isinstance(change, str):
            return False
        relative_path = _stage_relative_declared_path(path, stage_dir)
        if relative_path is None:
            return False
        key = (relative_path, change)
        if key in observed:
            return False
        observed.add(key)
    return observed == expected


def _ensure_new_private(path: Path) -> int:
    return os.open(
        path,
        os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0),
        0o600,
    )


def _stage(command: dict[str, Any], readonly: bool) -> None:
    if command["stage_dir"] is None:
        return
    directory = Path(command["stage_dir"])
    source = Path(command["stage_file"])
    directory.chmod(0o555 if readonly else 0o700)
    source.chmod(0o444 if readonly else 0o600)


def _bound_stage(
    command: dict[str, Any], *, readonly: bool,
) -> tuple[str | None, tuple[int, int, int, int, int] | None]:
    if command["stage_file"] is None:
        return None, None
    path = Path(command["stage_file"])
    expected_mode = 0o444 if readonly else 0o600
    raw, info = read_regular(
        path, MAX_COMMAND_BYTES, "staged prompt", allowed_modes=(expected_mode,)
    )
    if stat.S_IMODE(info.st_mode) != expected_mode:
        raise DispatchError("staged prompt mode is invalid")
    directory = Path(command["stage_dir"])
    directory_info = directory.lstat()
    expected_directory_mode = 0o555 if readonly else 0o700
    if (
        not stat.S_ISDIR(directory_info.st_mode)
        or stat.S_ISLNK(directory_info.st_mode)
        or directory_info.st_uid != os.getuid()
        or stat.S_IMODE(directory_info.st_mode) != expected_directory_mode
    ):
        raise DispatchError("staged prompt directory is invalid")
    return digest(raw), _identity(info)


def _validate_verification(value: Any) -> dict[str, Any]:
    v1_fields = {"schema_version", "summary", "passed_checks", "failed_checks", "advisory_checks", "missing_checks"}
    v2_fields = v1_fields | {
        "candidate_sha256", "coverage", "verified_findings", "unresolved_gaps",
        "diff_review_complete",
    }
    if not isinstance(value, dict) or set(value) not in (v1_fields, v2_fields):
        raise DispatchError("verification feedback fields are invalid")
    if value["schema_version"] not in {1, 2} or (value["schema_version"] == 1) != (set(value) == v1_fields):
        raise DispatchError("verification feedback version is invalid")
    summary = value["summary"]
    if not isinstance(summary, str) or not (1 <= len(summary) <= MAX_CHECK_SUMMARY) or any(
        item in summary for item in ("\x00", "\r", "\n")
    ):
        raise DispatchError("verification feedback summary is invalid")
    for key in ("passed_checks", "failed_checks"):
        checks = value[key]
        if not isinstance(checks, list) or len(checks) > MAX_CHECK_ITEMS or any(
            not isinstance(item, str) or not (1 <= len(item) <= MAX_CHECK_LABEL)
            or any(control in item for control in ("\x00", "\r", "\n"))
            for item in checks
        ):
            raise DispatchError("verification feedback checks are invalid")
    for key in ("advisory_checks", "missing_checks"):
        if type(value[key]) is not int or not (0 <= value[key] <= MAX_CHECK_ITEMS):
            raise DispatchError("verification feedback counts are invalid")
    if value["schema_version"] == 2:
        if not isinstance(value["candidate_sha256"], str) or SHA_RE.fullmatch(value["candidate_sha256"]) is None:
            raise DispatchError("verification feedback candidate binding is invalid")
        if value["coverage"] not in {"complete", "partial", "not_assessed", "not_applicable"}:
            raise DispatchError("verification feedback coverage is invalid")
        for key in ("verified_findings", "unresolved_gaps"):
            if type(value[key]) is not int or not (0 <= value[key] <= MAX_CHECK_ITEMS):
                raise DispatchError("verification feedback evidence counts are invalid")
        if type(value["diff_review_complete"]) is not bool:
            raise DispatchError("verification feedback diff review is invalid")
    if len(canonical(value)) > MAX_VERIFICATION_BYTES:
        raise DispatchError("verification feedback canonical bytes are oversized")
    return value


def _verification_from_stdin() -> dict[str, Any]:
    raw = sys.stdin.buffer.read(MAX_VERIFICATION_BYTES + 1)
    if len(raw) > MAX_VERIFICATION_BYTES:
        raise DispatchError("verification feedback is oversized")
    return _validate_verification(parse_json(raw, "verification feedback"))


def _verification_counts(value: dict[str, Any]) -> dict[str, int]:
    return {
        "passed": len(value["passed_checks"]),
        "failed": len(value["failed_checks"]),
        "advisory": value["advisory_checks"],
        "missing": value["missing_checks"],
    }


def _verification_is_verified(value: dict[str, Any], workflow: str) -> bool:
    counts = _verification_counts(value)
    if value["schema_version"] != 2 or counts["failed"] or counts["missing"]:
        return False
    if workflow == "explore":
        return value["coverage"] == "complete" and value["unresolved_gaps"] == 0
    return counts["passed"] >= 1 and value["diff_review_complete"]


def _require_current_candidate_verification(value: Mapping[str, Any], state: Mapping[str, Any]) -> None:
    """V1 is readable for compatibility, but never authorizes a lifecycle write."""
    if value["schema_version"] != 2:
        raise DispatchError("verification v2 is required for candidate disposition")
    if (
        not state["candidate_recognized"] or not state["result_available"]
        or state["result_sha256"] is None
    ):
        raise DispatchError("verification has no current recognized candidate")
    if value["candidate_sha256"] != state["result_sha256"]:
        raise DispatchError("verification candidate binding is stale")


def _write_verification(job: Path, label: str, value: dict[str, Any]) -> tuple[Path, str, tuple[int, int, int, int, int]]:
    directory = job / "continue-staged"
    if directory.exists() or directory.is_symlink():
        info = directory.lstat()
        if (
            not stat.S_ISDIR(info.st_mode) or stat.S_ISLNK(info.st_mode)
            or info.st_uid != os.getuid() or stat.S_IMODE(info.st_mode) not in {0o700, 0o555}
        ):
            raise DispatchError("verification staging directory is invalid")
        directory.chmod(0o700)
    else:
        directory.mkdir(mode=0o700)
    path = directory / f"{label}.json"
    raw = canonical(value)
    if len(raw) > MAX_VERIFICATION_BYTES:
        raise DispatchError("verification feedback canonical bytes are oversized")
    descriptor = -1
    created_identity: tuple[int, int, int, int, int] | None = None
    try:
        descriptor = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), 0o600)
        created_info = os.fstat(descriptor)
        if not stat.S_ISREG(created_info.st_mode) or created_info.st_nlink != 1:
            raise DispatchError("verification feedback staging identity is invalid")
        created_identity = _identity(created_info)
    except DispatchError:
        raise
    except OSError as exc:
        raise DispatchError("verification staging path is unavailable") from exc
    try:
        os.fchmod(descriptor, 0o600)
        offset = 0
        while offset < len(raw):
            written = os.write(descriptor, raw[offset:])
            if written <= 0:
                raise DispatchError("verification feedback staging write failed")
            offset += written
        os.fsync(descriptor)
        os.close(descriptor)
        descriptor = -1
        path.chmod(0o400)
        directory.chmod(0o700)
        bound, info = read_regular(path, MAX_VERIFICATION_BYTES, "verification feedback", allowed_modes=(0o400,))
        if bound != raw:
            raise DispatchError("verification feedback changed during staging")
        return path, digest(bound), _identity(info)
    except (OSError, DispatchError):
        if descriptor >= 0:
            with contextlib.suppress(OSError):
                os.close(descriptor)
        if created_identity is None:
            with contextlib.suppress(OSError):
                fallback_info = path.lstat()
                if stat.S_ISREG(fallback_info.st_mode) and fallback_info.st_nlink == 1:
                    created_identity = _identity(fallback_info)
        _discard_new_verification(path, created_identity)
        raise


def _discard_new_verification(path: Path | None, identity: tuple[int, int, int, int, int] | None) -> None:
    if path is None or identity is None:
        return
    try:
        parent = path.parent
        parent_info = parent.lstat()
        if (
            not stat.S_ISDIR(parent_info.st_mode) or stat.S_ISLNK(parent_info.st_mode)
            or parent_info.st_uid != os.getuid() or stat.S_IMODE(parent_info.st_mode) not in {0o700, 0o555}
        ):
            return
        # A prior runtime used 0555 for this directory.  Recover that exact
        # owner-private directory, but publish new staging in cleanup-friendly
        # 0700 mode.
        parent.chmod(0o700)
        info = path.lstat()
        if stat.S_ISREG(info.st_mode) and _identity(info) == identity and info.st_nlink == 1:
            path.unlink()
            descriptor = os.open(parent, os.O_RDONLY)
            try:
                os.fsync(descriptor)
            finally:
                os.close(descriptor)
    except OSError:
        pass


def _bound_verification(job: Path, state: Mapping[str, Any]) -> Path | None:
    path_text = state["verification_path"]
    if path_text is None:
        return None
    path = Path(path_text)
    expected = job / "continue-staged" / f"cycle-{state['cycle']:03d}.json"
    if state["attempt_origin"] != "conversation-continue" or path != expected:
        raise DispatchError("verification feedback path is not bound to this continuation")
    raw, info = read_regular(path, MAX_VERIFICATION_BYTES, "verification feedback", allowed_modes=(0o400,))
    if digest(raw) != state["verification_sha256"] or list(_identity(info)) != state["verification_identity"]:
        raise DispatchError("verification feedback binding changed")
    _require_current_candidate_verification(
        _validate_verification(parse_json(raw, "verification feedback")), state,
    )
    parent = path.parent.lstat()
    if (
        not stat.S_ISDIR(parent.st_mode) or stat.S_ISLNK(parent.st_mode)
        or parent.st_uid != os.getuid() or stat.S_IMODE(parent.st_mode) != 0o700
    ):
        raise DispatchError("verification staging directory changed")
    return path


def _bound_transmission_sha256(
    command: dict[str, Any], policy_sha256: str,
    readable_manifest_sha256: str, selected_content_sha256: str,
) -> str:
    """Bind current mode and content authority without changing approval bytes."""

    base = WORKTREE._compute_transmission_sha256(
        policy_sha256, readable_manifest_sha256, selected_content_sha256,
    )
    return WORKTREE._compute_v11_launch_approval_sha256(
        _provider_isolation_for_command(command), command["native_grant_profile"],
        transmission_sha256=base,
    )


def _compute_repair_lineage_sha256(
    *, authority_sha256: str, attempt: int,
    parent_result_sha256: str | None, parent_worktree_sha256: str | None,
    reconciliation_sha256: str, result_sha256: str,
    candidate_worktree_sha256: str, selected_content_sha256: str,
    transmission_sha256: str,
) -> str:
    return digest(canonical({
        "kind": "agy-worker-scoped-repair-lineage-v1",
        "authority_sha256": authority_sha256,
        "attempt": attempt,
        "parent_result_sha256": parent_result_sha256,
        "parent_worktree_sha256": parent_worktree_sha256,
        "reconciliation_sha256": reconciliation_sha256,
        "result_sha256": result_sha256,
        "candidate_worktree_sha256": candidate_worktree_sha256,
        "selected_content_sha256": selected_content_sha256,
        "transmission_sha256": transmission_sha256,
    }))


def _initial_content_transmission(command: dict[str, Any]) -> str:
    content = command["launch_authority"]["content"]
    return _bound_transmission_sha256(
        command, content["policy_sha256"], content["manifest_sha256"],
        content["selected_content_sha256"])


def _require_scoped_transmission_authority(
    command: dict[str, Any], state: Mapping[str, Any], *,
    selected_content_sha256: str, transmission_sha256: str,
    provider_origin: str | None = None,
) -> None:
    """Apply the one exact rule used at every scoped transmission check."""
    initial_transmission_sha = _initial_content_transmission(command)
    if transmission_sha256 == initial_transmission_sha:
        if state.get("transmission_sha256") not in {None, transmission_sha256} or (
            state.get("selected_content_sha256") not in {None, selected_content_sha256}
        ):
            raise DispatchError("worktree scope transmission binding changed")
        return
    if provider_origin not in {None, "conversation-continue"}:
        raise DispatchError("approved transmission SHA does not match current worktree scope")
    if (
        not command.get("allow_scoped_repair", False)
        or not state.get("allow_scoped_repair", False)
        or command.get("repair_authority_sha256") != state.get("repair_authority_sha256")
        or command.get("repair_authority_sha256") != _repair_authority_for_command(command)
        or state.get("repair_lineage_sha256") is None
        or state.get("repair_lineage_attempt") not in {
            state.get("attempt"), state.get("attempt", 0) - 1,
        }
        or not state.get("candidate_recognized", False)
        or not state.get("result_available", False)
        or state.get("worktree_reconciliation") != "available"
        or state.get("reconciliation_manifest_sha256") is None
        or state.get("candidate_worktree_sha256") is None
        or state.get("selected_content_sha256") != selected_content_sha256
        or state.get("transmission_sha256") != transmission_sha256
    ):
        raise DispatchError("scoped repair transmission lineage is unavailable")


def _dispatch_root_identity(workdir: str) -> dict[str, Any] | None:
    """Return V9's stable root/Git-administration authority record.

    Unlike the semantic candidate snapshot, this extractor is intentionally
    unchanged by ordinary tracked/untracked worktree edits, index refreshes,
    HEAD/ref moves, and object maintenance.  Those remain candidate-binding
    facts; this record detects a substituted repository boundary.
    """
    return WORKTREE._git_boundary_identity(workdir)


def _state_worktree_snapshot(state: Mapping[str, Any], workdir: str) -> dict[str, Any] | None:
    """Use the one persisted semantic algorithm without changing its digest."""
    if state.get("schema_version") is not None:
        _require_supported_schema(state, label="dispatch state", supported=(CURRENT_STATE_SCHEMA,))
        if state.get("worktree_snapshot_algorithm") != CURRENT_WORKTREE_SNAPSHOT_ALGORITHM:
            raise DispatchError("dispatch worktree snapshot algorithm is unavailable")
    return WORKTREE._worktree_snapshot(workdir)


def _reconciliation_from_snapshot(
    current: dict[str, Any] | None, baseline: dict[str, Any] | None,
) -> dict[str, Any]:
    """Project reconciliation from one already-linearized worktree fact."""
    if current is None or baseline is None:
        return {
            "worktree_reconciliation": "unavailable",
            "worktree_changes_present": None,
            "worktree_changed_since_dispatch": None,
        }
    return {
        "worktree_reconciliation": "available",
        "worktree_changes_present": current["entries"] > 0,
        "worktree_changed_since_dispatch": current["sha256"] != baseline["sha256"],
    }


def _reconcile_worktree(
    workdir: str, baseline: dict[str, Any] | None, *, state: Mapping[str, Any] | None = None,
) -> dict[str, Any]:
    current = WORKTREE._worktree_snapshot(workdir) if state is None else _state_worktree_snapshot(state, workdir)
    return _reconciliation_from_snapshot(current, baseline)


def _schema_binding(path: Path) -> tuple[str, tuple[int, int, int, int, int]]:
    """Bind a schema as dispatch input without accepting a symlink swap."""
    try:
        descriptor = os.open(path, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0))
    except OSError as exc:
        raise DispatchError("dispatch schema is unavailable") from exc
    try:
        before = os.fstat(descriptor)
        if not stat.S_ISREG(before.st_mode) or stat.S_ISLNK(before.st_mode) or before.st_size > 1024 * 1024:
            raise DispatchError("dispatch schema is invalid")
        raw = b""
        while len(raw) <= 1024 * 1024:
            piece = os.read(descriptor, 65536)
            if not piece:
                break
            raw += piece
        after = os.fstat(descriptor)
    finally:
        os.close(descriptor)
    try:
        named = path.lstat()
    except OSError as exc:
        raise DispatchError("dispatch schema identity changed") from exc
    if len(raw) > 1024 * 1024 or _identity(before) != _identity(after) or _identity(after) != _identity(named):
        raise DispatchError("dispatch schema identity changed")
    return digest(raw), _identity(after)


def _schema_paths(command: dict[str, Any]) -> tuple[Path, Path] | None:
    argv = command["argv"]
    if "--json-schema" not in argv:
        return None
    if argv.count("--json-schema") != 1:
        raise DispatchError("dispatch schema argument is invalid")
    index = argv.index("--json-schema")
    if index + 1 >= len(argv):
        raise DispatchError("dispatch schema argument is invalid")
    return Path(argv[index + 1]), Path(__file__).parent.parent / "schemas" / "worker-result.schema.json"


def _schema_bindings(command: dict[str, Any]) -> dict[str, Any]:
    paths = _schema_paths(command)
    if paths is None:
        return {
            "provider_schema_sha256": None, "provider_schema_identity": None,
            "canonical_schema_sha256": None, "canonical_schema_identity": None,
        }
    provider_sha, provider_identity = _schema_binding(paths[0])
    canonical_sha, canonical_identity = _schema_binding(paths[1])
    return {
        "provider_schema_sha256": provider_sha, "provider_schema_identity": list(provider_identity),
        "canonical_schema_sha256": canonical_sha, "canonical_schema_identity": list(canonical_identity),
    }


def _bound_schemas(command: dict[str, Any], state: Mapping[str, Any]) -> tuple[Path, Path]:
    paths = _schema_paths(command)
    if paths is None:
        raise DispatchError("dispatch schema argument is unavailable")
    expected = _schema_bindings(command)
    for key, value in expected.items():
        if state[key] != value:
            raise DispatchError("dispatch schema binding changed")
    return paths


def _bound_candidate_worktree(state: Mapping[str, Any], command: dict[str, Any]) -> None:
    """Reject post-review worktree drift before a continuation or final disposition."""
    quiescent = (
        state["status"] in TERMINAL and state["controller_pid"] is None
    ) or (
        state["status"] == "queued"
        and state["attempt_origin"] == "conversation-continue"
        # The owning controller publishes its PID while provider-free local
        # preflight is in progress.  No other process may treat that active
        # queued candidate as quiescent.
        and state["controller_pid"] in {None, os.getpid()}
    )
    if not quiescent:
        raise DispatchError("candidate worktree is not quiescent")
    # Candidate content and repository authority are separate checks.  The
    # same V9 extractor used by lifecycle recovery is repeated here so a
    # direct candidate-binding caller cannot turn a substituted Git boundary
    # into a content-only comparison.
    if (WORKTREE._git_boundary_identity(command["workdir"])
        != state.get("worktree_root_identity")):
        raise DispatchError("dispatch worktree root binding changed")
    expected_sha = state["candidate_worktree_sha256"]
    expected_entries = state["candidate_worktree_entries"]
    current = _state_worktree_snapshot(state, command["workdir"])
    if current is None or expected_sha is None or expected_entries is None:
        raise DispatchError("candidate worktree reconciliation is unavailable")
    if current["sha256"] != expected_sha or current["entries"] != expected_entries:
        drift = "entry count and snapshot digest" if current["entries"] != expected_entries else "snapshot digest"
        details = WORKTREE._snapshot_drift_details(
            state["candidate_worktree_path_facts"], current.get("path_facts"),
        )
        raise DispatchError(
            f"candidate worktree binding changed ({drift})"
            + (f": {details}" if details else "")
            + "; inspect candidate drift and request repair in the same worker "
            "conversation; do not edit the bound candidate by hand"
        )


def _bound_current_candidate(job: Path, state: Mapping[str, Any]) -> tuple[dict[str, Any], bytes]:
    """Reopen every current-candidate authority before exposing or mutating it.

    This is intentionally one bounded no-follow binding sequence, reused by
    status action projection, continuation staging/launch, result delivery, and
    finalization.  It binds the private command, state worktree/root, both
    schemas, current canonical artifact, and post-provider worktree fact set.
    """

    if not (
        state["candidate_recognized"] and state["result_available"]
        and isinstance(state["result_path"], str)
        and isinstance(state["result_sha256"], str)
        and isinstance(state["result_identity"], list)
    ):
        raise DispatchError("dispatch has no current recognized candidate")
    try:
        bound_job = canonical_job(Path(job).resolve(strict=True))
    except OSError as exc:
        raise DispatchError("job directory is unavailable") from exc
    result_path = Path(state["result_path"])
    try:
        result_parent = result_path.parent.resolve(strict=True)
    except OSError as exc:
        raise DispatchError("dispatch result path is unavailable") from exc
    if not result_path.is_absolute() or result_parent != bound_job:
        raise DispatchError("dispatch result path is outside this job")
    command = _load_bound_command(bound_job, state, stage_readonly=False)
    command, state = _bound_lifecycle_inputs(
        bound_job, state, command,
        bind_terminal_candidate=True,
    )
    proof = _deferred_candidate_proof(state)
    if proof is not None and proof["status"] != "unchanged":
        raise SourceGuardError(cast(str, _source_guard_reason({"source_checkout_guard": proof})))
    schema_paths = _schema_paths(command)
    if schema_paths is None:
        raise DispatchError("dispatch schema argument is unavailable")
    raw, info = read_regular(result_path, 1024 * 1024, "dispatch result")
    if digest(raw) != state["result_sha256"] or list(_identity(info)) != state["result_identity"]:
        raise DispatchError("dispatch result binding changed")
    validator = Path(__file__).with_name("validate-envelope.py")
    checked = [
        subprocess.run(
            [sys.executable, "-I", "-S", "-B", str(validator), str(schema), str(result_path)],
            stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            check=False,
        )
        for schema in schema_paths
    ]
    if any(item.returncode != 0 for item in checked):
        raise DispatchError("dispatch result is no longer valid")
    rebound, rebound_info = read_regular(result_path, 1024 * 1024, "dispatch result")
    if rebound != raw or _identity(rebound_info) != _identity(info):
        raise DispatchError("dispatch result binding changed")
    # The validator opened both schema pathnames; bind them and the project
    # marker again before accepting its answer.
    _bound_lifecycle_inputs(
        bound_job, state, command,
        bind_terminal_candidate=True,
    )
    # Project jobs created before the external-log-root boundary can place their
    # own controller state inside the candidate worktree. Every state write then
    # changes the semantic snapshot, so that stored snapshot is self-invalidating.
    # Keep exact command/schema/root/result bindings for readback and a driver-only
    # final disposition; provider recovery is denied by the inside-worktree guard.
    if not _job_is_inside_worktree(bound_job, command["workdir"]):
        _bound_candidate_worktree(state, command)
    return command, raw


def _verification_copy_destination(destination: Path, worktree: Path) -> tuple[Path, tuple[int, int, int, int, int]]:
    """Accept one new private directory outside the bound candidate.

    The copy is a driver convenience, not controller state or acceptance evidence.
    Keeping the destination caller-selected avoids exposing a local path through the
    public status surface, while the private-parent rule keeps accidental sharing and
    symlink traversal out of the helper's scope.
    """
    if not destination.is_absolute() or destination.name in {"", ".", ".."}:
        raise DispatchError("verification copy destination is invalid")
    parent = destination.parent
    if Path(os.path.realpath(parent)) != parent:
        raise DispatchError("verification copy destination parent is not canonical")
    try:
        metadata = parent.lstat()
    except OSError as exc:
        raise DispatchError("verification copy destination parent is unavailable") from exc
    if (
        not stat.S_ISDIR(metadata.st_mode)
        or stat.S_ISLNK(metadata.st_mode)
        or metadata.st_uid != os.getuid()
        or stat.S_IMODE(metadata.st_mode) != 0o700
    ):
        raise DispatchError("verification copy destination immediate parent must be current-user mode 0700")
    if destination.exists() or destination.is_symlink():
        raise DispatchError("verification copy destination must be new")
    try:
        if os.path.commonpath((str(worktree), str(destination))) == str(worktree):
            raise DispatchError("verification copy destination is inside the candidate")
    except ValueError as exc:
        raise DispatchError("verification copy destination is invalid") from exc
    return destination, _identity(metadata)


def _discard_verification_copy(destination: Path) -> None:
    """Best-effort removal of a failed new verifier workspace without following links."""
    try:
        info = destination.lstat()
    except FileNotFoundError:
        return
    except OSError:
        return
    try:
        if stat.S_ISDIR(info.st_mode) and not stat.S_ISLNK(info.st_mode):
            # Copied source metadata may make nested directories read-only.
            # Restore write/search permission only on lstat-proven directories
            # below this disposable copy; link nodes are never traversed or
            # chmodded before rmtree unlinks them.
            pending = [destination]
            while pending:
                current = pending.pop()
                current_info = current.lstat()
                if not stat.S_ISDIR(current_info.st_mode) or stat.S_ISLNK(current_info.st_mode):
                    continue
                os.chmod(current, 0o700)
                with os.scandir(current) as entries:
                    for entry in entries:
                        child = Path(entry.path)
                        child_info = child.lstat()
                        if stat.S_ISDIR(child_info.st_mode) and not stat.S_ISLNK(child_info.st_mode):
                            pending.append(child)
            shutil.rmtree(destination)
        elif stat.S_ISLNK(info.st_mode):
            destination.unlink()
    except OSError:
        # The owner-private parent and the current local user are in the
        # documented TCB.  A same-UID replacement can still make cleanup
        # uncertain; never turn that into a successful copy result.
        pass


def _copy_bound_candidate(worktree: Path, destination: Path) -> None:
    """Copy a candidate without following source links or copying Git metadata.

    Every contained source link becomes a relative link to the corresponding
    object under ``destination``.  Preserving either an absolute target or a
    location-dependent relative spelling can resolve back into the candidate
    after relocation, so ``copytree(symlinks=True)`` cannot provide this
    isolation.
    """
    root = Path(os.path.realpath(worktree))

    def require_contained_link(source: Path, target: Path) -> str:
        before = source.lstat()
        if not stat.S_ISLNK(before.st_mode):
            raise DispatchError("verification copy source link changed")
        try:
            # Validate that the source still supports reading its symlink target.
            os.readlink(source)
            resolved = os.path.realpath(source)
            after = source.lstat()
        except OSError as exc:
            raise DispatchError("verification copy source link is unavailable") from exc
        if _identity(before) != _identity(after):
            raise DispatchError("verification copy source link changed")
        try:
            contained = os.path.commonpath([str(root), resolved]) == str(root)
        except ValueError:
            contained = False
        if (
            not contained or not os.path.exists(resolved)
            or WORKTREE._resolved_path_is_git_administration(str(root), resolved)
        ):
            raise DispatchError("verification copy source link is unsafe")
        # A relative source spelling can still escape a sibling copy (for
        # example ``../source/target``).  Rebase every contained link from its
        # resolved source object to the mirrored destination object instead of
        # preserving raw target text.
        mirrored = destination / os.path.relpath(resolved, root)
        return os.path.relpath(mirrored, target.parent)

    def copy_entry(source: Path, target: Path, *, is_root: bool = False) -> None:
        try:
            before = source.lstat()
        except OSError as exc:
            raise DispatchError("verification copy source is unavailable") from exc
        if stat.S_ISLNK(before.st_mode):
            target_text = require_contained_link(source, target)
            try:
                os.symlink(target_text, target)
                shutil.copystat(source, target, follow_symlinks=False)
            except OSError as exc:
                raise DispatchError("verification copy failed") from exc
            return
        if stat.S_ISREG(before.st_mode):
            try:
                shutil.copy2(source, target, follow_symlinks=False)
                copied = target.lstat()
                after = source.lstat()
            except OSError as exc:
                raise DispatchError("verification copy failed") from exc
            if (
                _identity(before) != _identity(after)
                or not stat.S_ISREG(copied.st_mode)
            ):
                raise DispatchError("verification copy source changed")
            return
        if not stat.S_ISDIR(before.st_mode):
            raise DispatchError("verification copy source has unsupported entry")
        try:
            # Child entries must be created before source metadata is restored:
            # an otherwise valid read-only source directory would reject them.
            os.mkdir(target, 0o700)
            entries = list(os.scandir(source))
        except OSError as exc:
            raise DispatchError("verification copy failed") from exc
        markers = [entry.name for entry in entries if entry.name.lower() == ".git"]
        if is_root:
            if any(name != ".git" for name in markers):
                raise DispatchError("verification copy source has ambiguous Git administration")
        elif markers:
            raise DispatchError("verification copy source has nested Git administration")
        for entry in entries:
            if is_root and entry.name == ".git":
                continue
            copy_entry(Path(entry.path), target / entry.name)
        try:
            after = source.lstat()
            if _identity(before) != _identity(after):
                raise DispatchError("verification copy source changed")
            shutil.copystat(source, target, follow_symlinks=False)
        except OSError as exc:
            raise DispatchError("verification copy failed") from exc

    try:
        copy_entry(root, destination, is_root=True)
        os.chmod(destination, 0o700)
        copied = destination.lstat()
    except (OSError, shutil.Error, DispatchError):
        _discard_verification_copy(destination)
        raise
    if (
        not stat.S_ISDIR(copied.st_mode)
        or stat.S_ISLNK(copied.st_mode)
        or copied.st_uid != os.getuid()
        or stat.S_IMODE(copied.st_mode) != 0o700
        or (destination / ".git").exists()
        or (destination / ".git").is_symlink()
    ):
        _discard_verification_copy(destination)
        raise DispatchError("verification copy binding changed")


def command_verification_copy(job: Path, destination: Path, output_format: str) -> int:
    """Create an isolated verifier workspace after exact candidate revalidation."""
    with state_lock(job):
        state, _raw, _sha = load_state(job)
        if not _verification_copy_is_eligible(state):
            raise DispatchError("verification copy is unavailable")
        command = _load_bound_command(job, state, stage_readonly=False)
        command, state = _bound_lifecycle_inputs(
            job, state, command, bind_terminal_candidate=True,
        )
        if _job_is_inside_worktree(job, command["workdir"]):
            raise DispatchError("verification copy is unavailable for jobs inside the worktree")
        command, _candidate_raw = _bound_current_candidate(job, state)
        worktree = Path(command["workdir"])
        destination, parent_identity = _verification_copy_destination(destination, worktree)
        _copy_bound_candidate(worktree, destination)
        try:
            if _identity(destination.parent.lstat()) != parent_identity:
                raise DispatchError("verification copy destination parent changed")
            # The source candidate is still the final authority.  A verifier
            # copy never reconciles ignored drift into that candidate.
            _bound_current_candidate(job, state)
        except SourceGuardError:
            _discard_verification_copy(destination)
            raise
        except (OSError, DispatchError):
            _discard_verification_copy(destination)
            raise DispatchError("candidate changed while creating verification copy") from None
    result = {
        "candidate_sha256": state["result_sha256"],
        "verification_copy": "created",
    }
    if output_format == "text":
        sys.stdout.buffer.write(
            b"Driver verification copy created; no candidate acceptance was recorded.\n"
        )
        sys.stdout.buffer.flush()
    else:
        print_json(result)
    return 0


def _bound_worktree_baseline(state: Mapping[str, Any], command: dict[str, Any]) -> None:
    """Require the queued worktree fact set immediately before provider launch."""
    expected = state["worktree_baseline"]
    current = _state_worktree_snapshot(state, command["workdir"])
    if expected is None or current is None:
        WORKTREE._worktree_snapshot(command["workdir"], explain_unsupported=True)
        raise WorktreeBaselineError("queued worktree baseline is unavailable")
    if (
        current["sha256"] != expected["sha256"]
        or current["entries"] != expected["entries"]
    ):
        raise WorktreeBaselineError("queued worktree baseline changed")


def _restart_guard_accepts(
    state: Mapping[str, Any], *, status: str | None = None,
    elapsed_seconds: float | None = None,
) -> bool:
    """Share the state-only fresh-restart guard with public recovery projection."""
    current_status = state["status"] if status is None else status
    elapsed = float(state["elapsed_seconds"]) if elapsed_seconds is None else elapsed_seconds
    return bool(
        current_status in TERMINAL
        and current_status != "orphaned"
        # A frozen direct-selection record which just failed its final
        # executable/version/help proof cannot become launch authority by
        # creating another attempt.  Keep that local evidence for Codex, but
        # reject recovery before it can stage or mutate the job.
        and _source_guard_reason(state) is None
        and state["reason"] != "selection_preflight_failed"
        and elapsed < _provider_max_seconds(state)
        and state.get("phase") != "self-verifying"
        and (
            state["workflow"] == "legacy"
            or state["attempt"] < state["max_cycles"]
        )
    )


def _load_bound_command(
    job: Path, state: Mapping[str, Any], *, stage_readonly: bool,
) -> dict[str, Any]:
    command, raw, identity = load_command(job)
    if digest(raw) != state["command_sha256"] or list(identity) != state["command_identity"]:
        raise DispatchError("dispatch command binding changed")
    expected_content = _initial_content_transmission(command) if command["provider_scope_path"] else None
    if state["initial_content_transmission_sha256"] != expected_content:
        raise DispatchError("dispatch initial content transmission binding changed")
    stage_sha, stage_identity = _bound_stage(command, readonly=stage_readonly)
    if stage_sha != state["stage_sha256"] or (
        stage_identity is not None and list(stage_identity[:4]) != state["stage_identity"][:4]
    ) or (stage_identity is None) != (state["stage_identity"] is None):
        raise DispatchError("staged prompt binding changed")
    return command


def _load_bound_selection(
    command: dict[str, Any], state: Mapping[str, Any],
) -> dict[str, Any] | None:
    """Read the frozen selection bytes and bind them to command and state.

    The record is private job state.  Its public JSON contains no executable
    pathname, and a controller never turns it back into an argv[0] string.
    """

    path_value = command["selection_path"]
    if path_value is None:
        if state["selection_sha256"] is not None or state["selection_identity"] is not None:
            raise DispatchError("dispatch selection state binding changed")
        return None
    if (state["selection_sha256"] != command["selection_sha256"]
        or state["selection_identity"] != command["selection_identity"]):
        raise DispatchError("dispatch selection state binding changed")
    try:
        raw, info = read_regular(Path(path_value), MAX_COMMAND_BYTES, "dispatch selection")
    except DispatchError:
        raise
    if digest(raw) != command["selection_sha256"] or list(_identity(info)) != command["selection_identity"]:
        raise DispatchError("dispatch selection binding changed")
    try:
        # A direct selection is an immutable dispatch input.  Its raw bytes and
        # identity have just been compared to the command/state bindings; do
        # not reopen or substitute the caller selection here.
        record = MODEL_SELECTION.decode_selection_record(raw, frozen=True)
    except (MODEL_SELECTION.CallerError, MODEL_SELECTION.EvidenceUnavailable) as exc:
        raise DispatchError("dispatch selection is invalid") from exc
    return record


StateMapping = TypeVar("StateMapping", bound=Mapping[str, Any])


def _bound_lifecycle_inputs(
    job: Path, state: StateMapping, command: dict[str, Any] | None = None,
    *, bind_terminal_candidate: bool = False,
) -> tuple[dict[str, Any], StateMapping]:
    """Bind non-provider recovery/finalization inputs before any state write.

    This never writes state or launches a provider, but it does perform the
    bounded local root, selection, schema, and boundary probes shared by status
    projection and the mutating create/finalize/result paths.  Provider launch
    still repeats its final executable and worktree probes.
    """
    if command is None:
        command = _load_bound_command(job, state, stage_readonly=False)
    checked = state
    if checked["workdir"] != command["workdir"]:
        raise DispatchError("dispatch worktree root binding changed")
    if (checked["provider_isolation"] != _provider_isolation_for_command(command)):
        raise DispatchError("dispatch provider isolation binding changed")
    if (checked["native_grant_profile"]
        != command.get("native_grant_profile", "baseline")
        or checked["whole_worktree_content_sha256"]
        != command.get("whole_worktree_content_sha256")):
        raise DispatchError("dispatch authority binding changed")
    root = Path(command["workdir"])
    try:
        root_info = root.lstat()
    except OSError as exc:
        raise DispatchError("dispatch worktree root is unavailable") from exc
    root_identity = _dispatch_root_identity(command["workdir"])
    if (
        root_identity is None
        or root_identity != checked["worktree_root_identity"]
    ):
        raise DispatchError("dispatch worktree root binding changed")
    if not stat.S_ISDIR(root_info.st_mode) or stat.S_ISLNK(root_info.st_mode):
        raise DispatchError("dispatch worktree root binding changed")
    try:
        # macOS exposes /var through its documented /private/var alias.  A
        # no-symlink root can legitimately stringify through that alias; all
        # other resolution changes remain a fail-closed boundary drift.
        if MODEL_SELECTION._canonical_executable_path(os.path.realpath(root)) != (
            MODEL_SELECTION._canonical_executable_path(command["workdir"])
        ):
            raise DispatchError("dispatch worktree root binding changed")
    except OSError as exc:
        raise DispatchError("dispatch worktree root is unavailable") from exc
    if not WORKTREE._worktree_symlink_boundary(command["workdir"]):
        raise DispatchError("dispatch worktree symlink boundary changed")
    _load_bound_selection(
        command, checked,
    )
    _bound_schemas(command, checked)
    if checked["workflow"] == "project" and (
        WORKTREE._project_boundary(command["workdir"]) != checked["project_boundary"]
    ):
        raise DispatchError("project worktree boundary changed")
    if (checked["allow_scoped_repair"] != command.get("allow_scoped_repair", False)
        or checked["repair_authority_sha256"] != command.get("repair_authority_sha256")
        or command.get("repair_authority_sha256") != _repair_authority_for_command(command)):
        raise DispatchError("dispatch scoped repair authority changed")
    if checked["allow_self_verification"] != command.get(
        "allow_self_verification", False
    ):
        raise DispatchError("dispatch self-verification authority changed")
    _bound_self_verification_manifest(command, job)
    if checked.get("provider_scope_path") is not None:
        _scope_path, raw_scope, scope_info = _read_provider_scope_file(
            checked["provider_scope_path"], MAX_COMMAND_BYTES,
        )
        if digest(raw_scope) != checked["provider_scope_sha256"]:
            raise DispatchError("provider scope file changed since dispatch")
        if list(_identity(scope_info)) != checked["provider_scope_identity"]:
            raise DispatchError("provider scope file identity changed since dispatch")
        try:
            scope = WORKTREE._parse_provider_scope(raw_scope)
        except ValueError as exc:
            raise DispatchError(f"invalid provider scope: {exc}") from exc
        if bind_terminal_candidate:
            if not (
                checked["candidate_recognized"]
                and (
                    checked["status"] in TERMINAL
                    or (
                        checked["status"] == "queued"
                        and checked["attempt_origin"] == "conversation-continue"
                        and checked["controller_pid"] in {None, os.getpid()}
                    )
                )
            ):
                raise DispatchError("terminal candidate binding is unavailable")
        else:
            readable_manifest = WORKTREE._scan_readable_worktree(command["workdir"])
            manifest_sha = WORKTREE._manifest_digest(readable_manifest)
            WORKTREE._validate_scope_against_worktree(scope, command["workdir"], readable_manifest)
            selected_manifest = WORKTREE._build_selected_content_manifest(command["workdir"], scope)
            selected_sha = WORKTREE._selected_content_digest(selected_manifest)
            policy_sha = WORKTREE._canonical_digest(scope)
            transmission_sha = _bound_transmission_sha256(
                command, policy_sha, manifest_sha, selected_sha,
            )
            _require_scoped_transmission_authority(
                command, checked,
                selected_content_sha256=selected_sha,
                transmission_sha256=transmission_sha,
                provider_origin=(
                    checked["attempt_origin"]
                    if checked["status"] in {"queued", "running", "cancel-requested"}
                    else None
                ),
            )
    return command, checked


def _reprobe_direct_selection(
    command: dict[str, Any], state: Mapping[str, Any], argv: list[str],
) -> tuple[str, dict[str, Any]]:
    """Probe every provider launch and bind exact caller model/effort arguments."""
    record = _load_bound_selection(command, state)
    if record is not None:
        if not _selection_launch_is_authorized(record):
            raise DispatchError("dispatch selection has no current executable binding")
        for flag, key in (("--model", "resolved_agy_model"), ("--effort", "user_effort")):
            expected = record.get(key)
            if expected is None:
                if flag in argv:
                    raise DispatchError("dispatch selection argument drifted: " + flag)
            elif argv.count(flag) != 1 or argv.index(flag) + 1 >= len(argv) or argv[argv.index(flag) + 1] != expected:
                raise DispatchError("dispatch selection argument drifted: " + flag)
    try:
        provider_isolation = _provider_isolation_for_command(command)
        conversation = "--conversation" in argv
        if record is not None:
            return MODEL_SELECTION.reprobe_selection_record(
                record, provider_isolation=provider_isolation, conversation=conversation,
            )
        executable, binding, _version = MODEL_SELECTION.probe_capabilities(
            provider_isolation=provider_isolation, conversation=conversation,
            effort="--effort" in argv,
        )
        return executable, binding
    except (MODEL_SELECTION.CallerError, MODEL_SELECTION.EvidenceUnavailable) as exc:
        raise SelectionPreflightError("dispatch capability preflight failed") from exc


def _terminate(process: subprocess.Popen[bytes]) -> int:
    # The leader can exit while a descendant still owns the stream or performs a
    # late side effect.  Signal the recorded session even in that case.
    signalled = False
    try:
        os.killpg(process.pid, signal.SIGTERM)
        signalled = True
    except (ProcessLookupError, PermissionError):
        pass
    if signalled:
        deadline = time.monotonic() + TERM_GRACE
        while time.monotonic() < deadline:
            try:
                os.killpg(process.pid, 0)
            except ProcessLookupError:
                break
            except PermissionError:
                pass
            time.sleep(0.02)
    try:
        os.killpg(process.pid, signal.SIGKILL)
    except (ProcessLookupError, PermissionError):
        pass
    try:
        process.wait(timeout=1.0)
    except subprocess.TimeoutExpired:
        process.kill()
        process.wait()
    return process.returncode


def _revalidate_scoped_provider_stage(
    stage_dir: Path,
    scope: dict[str, Any],
    selected_manifest: list[dict[str, Any]],
    stage_identity: tuple[int, int, int, int, int],
    stage_manifest_sha: str,
) -> None:
    """Rebind the complete fresh stage immediately before native launch."""
    try:
        current = stage_dir.lstat()
    except OSError as exc:
        raise DispatchError("provider stage is unavailable before launch") from exc
    identity = (
        current.st_dev, current.st_ino, current.st_uid,
        current.st_gid, current.st_mode,
    )
    if (
        identity != stage_identity
        or not stat.S_ISDIR(current.st_mode)
        or stat.S_ISLNK(current.st_mode)
        or current.st_uid != os.getuid()
        or stat.S_IMODE(current.st_mode) != 0o700
        or WORKTREE._selected_content_digest(selected_manifest) != stage_manifest_sha
    ):
        raise DispatchError("provider stage binding changed before launch")
    mutations, _operation_sha = WORKTREE._scan_stage_mutations(
        stage_dir, scope, selected_manifest, provider_configuration=True,
    )
    if mutations:
        raise DispatchError("provider stage changed before launch")


def _terminate_provider_process(
    process: subprocess.Popen[bytes],
    contained_root: CONTAINMENT.ProcessIdentity | None,
    *,
    contained: bool,
) -> int:
    """Reap a provider group, using kernel-bound identity when contained."""
    if not contained:
        return _terminate(process)
    if contained_root is None:
        raise DispatchError("contained provider process identity is unavailable")
    try:
        # Reap an already-exited leader before libproc enumeration. Darwin can
        # report the zombie PID in its group while proc_pidinfo no longer has
        # a bindable identity for it. The recorded start identity still makes
        # a subsequently reused leader PID a hard failure.
        process.poll()
        CONTAINMENT.terminate_bound_process_group(contained_root, signal.SIGTERM)
        with contextlib.suppress(subprocess.TimeoutExpired):
            process.wait(timeout=TERM_GRACE)
        deadline = time.monotonic() + TERM_GRACE
        while (
            not CONTAINMENT.process_group_is_quiescent(contained_root)
            and time.monotonic() < deadline
        ):
            time.sleep(0.02)
        if not CONTAINMENT.process_group_is_quiescent(contained_root):
            CONTAINMENT.terminate_bound_process_group(contained_root, signal.SIGKILL)
        if process.poll() is None:
            process.wait(timeout=1.0)
        deadline = time.monotonic() + 1.0
        while (
            not CONTAINMENT.process_group_is_quiescent(contained_root)
            and time.monotonic() < deadline
        ):
            time.sleep(0.02)
        if not CONTAINMENT.process_group_is_quiescent(contained_root):
            raise DispatchError("contained provider process group cleanup is uncertain")
        return int(process.returncode)
    except (CONTAINMENT.ContainmentError, OSError, subprocess.SubprocessError) as exc:
        raise DispatchError("contained provider process group cleanup is uncertain") from exc


def _event(line: bytes) -> tuple[bool, str | None, str | None]:
    if not line or len(line) > MAX_EVENT_BYTES:
        return False, None, None
    try:
        value = json.loads(
            line.decode("utf-8", "strict"), object_pairs_hook=_duplicates,
            parse_constant=_invalid_json_constant,
        )
    except (UnicodeError, json.JSONDecodeError, ValueError, OverflowError, DispatchError, RecursionError):
        return False, None, None
    if not isinstance(value, dict):
        return False, None, None
    event = value.get("event")
    if event not in {"init", "step_update", "result"}:
        return False, None, None
    if event == "init" and not isinstance(value.get("init"), dict):
        return False, None, None
    if event == "step_update" and not isinstance(value.get("step_update"), dict):
        return False, None, None
    if event == "result" and not isinstance(value.get("result"), dict):
        return False, None, None
    conversation = value.get("conversation_id")
    if conversation is None and event == "result":
        conversation = value["result"].get("conversation_id")
    if conversation is not None and (
        not isinstance(conversation, str) or CONVERSATION_RE.fullmatch(conversation) is None
    ):
        conversation = None
    return True, conversation, event


def _reviewed_provider_timeout_lines(version: str, seconds: object) -> set[bytes]:
    """Build only the exact 1.2.2/1.2.6/1.2.7 timeout lines bound to this job's limit.

    The installed binary exposes a ``%s`` duration slot but its unavailable
    source does not establish whether that slot retains the integer-seconds
    flag spelling or uses Go's canonical whole-second duration spelling.  The
    wrapper always supplies a positive integer number of seconds.  Accept only
    those two equivalent spellings for that exact bound value.
    """
    if type(seconds) not in (int, float):
        return set()
    # The exact-type guard above excludes bool and all non-numeric objects.
    seconds = cast("int | float", seconds)
    if not math.isfinite(seconds) or seconds <= 0 or seconds != int(seconds):
        return set()
    total = int(seconds)
    if total > 7 * 24 * 3600:
        return set()
    raw = f"{total}s"
    if total < 60:
        canonical = raw
    elif total < 3600:
        minutes, remainder = divmod(total, 60)
        canonical = f"{minutes}m{remainder}s"
    else:
        hours, remainder = divmod(total, 3600)
        minutes, remainder = divmod(remainder, 60)
        canonical = f"{hours}h{minutes}m{remainder}s"
    prefix = "[agy] print timeout after "
    suffix = " with turn in progress; returning partial output"
    return {
        f"{prefix}{duration}{suffix}".encode("ascii")
        for duration in {raw, canonical}
    }


def _has_reviewed_provider_timeout(
    path: Path, version: str, seconds: object,
) -> bool:
    expected = _reviewed_provider_timeout_lines(version, seconds)
    if not expected:
        return False
    try:
        raw = path.read_bytes()
    except OSError:
        return False
    return bool(expected.intersection(raw.splitlines()))


def _classify_stderr(
    path: Path, version: str, returncode: int, provider_timeout_seconds: object = None,
    *, native: bool = False,
) -> str:
    try:
        raw = path.read_bytes()
    except OSError:
        return "agy_failed_unclassified"

    raw_lines = raw.splitlines()

    # 1. Any AGY_ERROR marker lines must be evaluated strictly
    agy_lines = [line for line in raw_lines if b"AGY_ERROR" in line]
    if agy_lines:
        if len(agy_lines) != 1:
            return "agy_failed_unclassified"
        m_line = agy_lines[0]
        if len(m_line) > MAX_EVENT_BYTES:
            return "agy_failed_unclassified"
        if not m_line.startswith(b"AGY_ERROR: "):
            return "agy_failed_unclassified"
        if returncode != 3:
            return "agy_failed_unclassified"
        payload = parse_agy_error(m_line)
        if payload is None:
            return "agy_failed_unclassified"
        expected_timeout = _reviewed_provider_timeout_lines(version, provider_timeout_seconds)
        if expected_timeout and bool(expected_timeout.intersection(raw_lines)):
            return "agy_failed_unclassified"
        if any(b"permission that headless mode cannot prompt for" in line for line in raw_lines):
            return "agy_failed_unclassified"
        return "provider_terminal_error"

    # 2. No AGY_ERROR marker: reviewed timeout wins first
    expected_timeout = _reviewed_provider_timeout_lines(version, provider_timeout_seconds)
    if expected_timeout and bool(expected_timeout.intersection(raw_lines)):
        return "provider_timeout"

    # 3. rc0 returns empty_output
    if returncode == 0:
        return "empty_output"

    native_host_denials = {
        b"sandbox_apply: Operation not permitted",
        b"sandbox-exec: sandbox_apply: Operation not permitted",
    }
    if native and any(line.strip() in native_host_denials for line in raw_lines):
        return "native_host_sandbox_unavailable"

    # Preserve the existing nonzero headless-permission restriction.
    if any(b"permission that headless mode cannot prompt for" in line for line in raw_lines):
        return "permission_required"

    return "agy_failed_unclassified"


def _selection_rejection_result(line: bytes) -> bool:
    """Recognize only a strict diagnostic frame, never a worker envelope."""
    if not line or len(line) > MAX_EVENT_BYTES:
        return False
    try:
        frame = json.loads(
            line.decode("utf-8", "strict"), object_pairs_hook=_duplicates,
            parse_constant=_invalid_json_constant,
        )
    except (UnicodeError, ValueError, OverflowError, DispatchError, RecursionError):
        return False
    result = frame.get("result") if isinstance(frame, dict) else None
    return bool(
        isinstance(frame, dict) and frame.get("event") == "result"
        and isinstance(result, dict) and result.get("status") == "ERROR"
        and type(result.get("num_turns")) is int and result["num_turns"] == 0
    )


def _model_selection_rejected(
    stream: Path, stderr: Path, returncode: int, version: str,
    provider_timeout_seconds: object, *, native: bool,
) -> bool:
    """Require the complete bounded evidence and actual reaped exit code."""
    if returncode != 1:
        return False
    try:
        with stderr.open("rb") as handle:
            diagnostic = handle.read(MAX_STREAM_BYTES + 1)
        with stream.open("rb") as handle:
            output = handle.read(MAX_EVENT_BYTES + 2)
    except OSError:
        return False
    lines = diagnostic.splitlines()
    if (
        len(diagnostic) > MAX_STREAM_BYTES
        or b"AGY_ERROR" in diagnostic
        or sum(line.startswith(b"error: invalid model selection (") for line in lines) != 1
        or any(line.strip() in {
            b"sandbox_apply: Operation not permitted",
            b"sandbox-exec: sandbox_apply: Operation not permitted",
        } for line in lines)
        or _classify_stderr(stderr, version, returncode, provider_timeout_seconds, native=native)
        != "agy_failed_unclassified"
    ):
        return False
    return not output or bool(
        output.endswith(b"\n") and output.count(b"\n") == 1
        and _selection_rejection_result(output[:-1])
    )


def _terminal_result(stream: Path, *, strict: bool = False) -> dict[str, Any] | None:
    result: dict[str, Any] | None = None
    init_conversation: str | None = None
    saw_init = False
    saw_terminal = False
    try:
        with stream.open("rb") as handle:
            for raw in handle:
                if len(raw) > MAX_EVENT_BYTES or not raw.endswith(b"\n"):
                    return None
                try:
                    event = json.loads(
                        raw.decode("utf-8", "strict"), object_pairs_hook=_duplicates,
                        parse_constant=_invalid_json_constant,
                    )
                except (UnicodeError, json.JSONDecodeError, ValueError, OverflowError, DispatchError, RecursionError):
                    if strict:
                        return None
                    continue
                if not isinstance(event, dict):
                    if strict:
                        return None
                    continue
                kind = event.get("event")
                structurally_valid = (
                    (kind == "init" and isinstance(event.get("init"), dict))
                    or (kind == "step_update" and isinstance(event.get("step_update"), dict))
                    or (kind == "result" and isinstance(event.get("result"), dict))
                )
                if not structurally_valid:
                    if strict:
                        return None
                    continue
                if saw_terminal:
                    return None
                if kind == "init":
                    if saw_init:
                        return None
                    init_conversation = event.get("conversation_id")
                    if strict and init_conversation is not None and (
                        not isinstance(init_conversation, str)
                        or CONVERSATION_RE.fullmatch(init_conversation) is None
                    ):
                        return None
                    saw_init = True
                elif not saw_init:
                    return None
                if kind == "result":
                    result_conversation = event["result"].get("conversation_id")
                    if strict and result_conversation is not None and (
                        not isinstance(result_conversation, str)
                        or CONVERSATION_RE.fullmatch(result_conversation) is None
                    ):
                        return None
                    if strict and init_conversation is not None and result_conversation is not None and result_conversation != init_conversation:
                        return None
                    saw_terminal = True
                    result = event["result"]
    except OSError:
        return None
    if not saw_terminal or not isinstance(result, dict):
        return None
    return result


def _has_denied_actions(stream: Path) -> bool:
    """Opaque denial-key presence restricts reuse only after strict framing."""
    result = _terminal_result(stream, strict=True)
    return isinstance(result, dict) and isinstance(result.get("status"), str) and result["status"] in {"SUCCESS", "ERROR", "CANCELLED", "CANCELED"} and "denied_actions" in result


AGY_ERROR_PAYLOAD_FIELDS = {
    "short_error", "status", "error_code", "code_kind", "retryable", "error_id",
}


class AgyErrorPayload(NamedTuple):
    short_error: str | None
    status: str | None = None
    error_code: int | None = None
    code_kind: str | None = None
    retryable: bool | None = None
    error_id: str | None = None


def parse_agy_error(raw: str | bytes) -> AgyErrorPayload | None:
    """Closed offline parser for static printmode.agentErrorPayload metadata.

    Static analysis of the approved 1.2.6/1.2.7 Go binary recovered:
      short_error *string (no omitempty)
      status *string omitempty
      error_code *uint32 omitempty
      code_kind *string omitempty
      retryable *bool (no omitempty)
      error_id *string omitempty
      Exact fallback literal: {"short_error":%q}

    Accepts only a single column-zero line starting with exact "AGY_ERROR: ".
    Raw JSON, leading whitespace, missing space after colon, duplicate keys,
    invalid constants, numeric overflow, or schema mismatch fail closed (return None).
    """
    if isinstance(raw, bytes):
        if len(raw) > MAX_EVENT_BYTES:
            return None
        try:
            text = raw.decode("utf-8", "strict")
        except UnicodeDecodeError:
            return None
    elif isinstance(raw, str):
        if len(raw) > MAX_EVENT_BYTES:
            return None
        text = raw
    else:
        return None

    if text.endswith("\r\n"):
        line = text[:-2]
    elif text.endswith("\n"):
        line = text[:-1]
    else:
        line = text
    if "\r" in line or "\n" in line:
        return None
    prefix = "AGY_ERROR: "
    if not line.startswith(prefix):
        return None
    json_part = line[len(prefix):].strip()
    if not (json_part.startswith("{") and json_part.endswith("}")):
        return None

    try:
        data = json.loads(
            json_part,
            object_pairs_hook=_duplicates,
            parse_constant=_invalid_json_constant,
        )
    except (json.JSONDecodeError, ValueError, OverflowError, DispatchError, RecursionError):
        return None

    if not isinstance(data, dict):
        return None

    # Fallback literal shape: exact field set {"short_error"}, string value (empty string allowed)
    if set(data.keys()) == {"short_error"}:
        short_error = data["short_error"]
        if not isinstance(short_error, str):
            return None
        return AgyErrorPayload(
            short_error=short_error,
            status=None,
            error_code=None,
            code_kind=None,
            retryable=None,
            error_id=None,
        )

    # Normal shape: requires short_error and retryable
    # short_error can be str | None (string or null, empty allowed)
    # retryable can be bool | None (bool or null)
    # Optional keys: status, error_code, code_kind, error_id only.
    # Optional string-pointer fields are strings (empty allowed).
    # error_code must be non-bool uint32 (0 <= error_code <= 0xFFFFFFFF, type(val) is int).
    if "short_error" not in data or "retryable" not in data:
        return None
    if not set(data.keys()).issubset(AGY_ERROR_PAYLOAD_FIELDS):
        return None

    short_error = data["short_error"]
    if short_error is not None and not isinstance(short_error, str):
        return None

    retryable = data["retryable"]
    if retryable is not None and type(retryable) is not bool:
        return None

    status = data.get("status")
    if "status" in data and not isinstance(status, str):
        return None

    code_kind = data.get("code_kind")
    if "code_kind" in data and not isinstance(code_kind, str):
        return None

    error_id = data.get("error_id")
    if "error_id" in data and not isinstance(error_id, str):
        return None

    error_code = data.get("error_code")
    if "error_code" in data and (type(error_code) is not int or isinstance(error_code, bool) or not (0 <= error_code <= 0xFFFFFFFF)):
        return None

    return AgyErrorPayload(
        short_error=short_error,
        status=status,
        error_code=error_code,
        code_kind=code_kind,
        retryable=retryable,
        error_id=error_id,
    )


def _validate_terminal_envelope(
    stream: Path, envelope: Path, provider_schema: Path, canonical_schema: Path, *,
    stage_dir: Path | None = None,
) -> tuple[tuple[str, tuple[int, int, int, int, int]] | None, str | None, str | None]:
    """Keep framing, provider status, extraction, and canonical validation distinct."""
    result = _terminal_result(stream, strict=True)
    if result is None:
        return None, None, "framing"
    outer_status = result.get("status")
    if not isinstance(outer_status, str) or outer_status not in {"SUCCESS", "ERROR", "CANCELED", "CANCELLED"}:
        return None, None, "outer_status"
    outer_status = "CANCELLED" if outer_status in {"CANCELED", "CANCELLED"} else outer_status
    value = result.get("structured_output")
    if not isinstance(value, dict):
        return None, outer_status, "missing_structured_output"
    # The provider may omit exactly these ergonomic report-only arrays.  Every
    # other required field and every extra field remain schema failures.
    value = dict(value)
    for field in ("commands_run", "tests_run"):
        value.setdefault(field, [])
    if stage_dir is not None:
        value = _canonicalize_scoped_report_paths(value, stage_dir)
    raw = json.dumps(value, ensure_ascii=True, indent=2).encode("ascii") + b"\n"
    if len(raw) > 1024 * 1024:
        return None, outer_status, "schema_rejection"
    descriptor = _ensure_new_private(envelope)
    try:
        view = memoryview(raw)
        while view:
            written = os.write(descriptor, view)
            if written <= 0:
                raise DispatchError("structured output write failed")
            view = view[written:]
        os.fsync(descriptor)
    finally:
        os.close(descriptor)
    validator = Path(__file__).with_name("validate-envelope.py")
    provider_checked = subprocess.run(
        [sys.executable, "-I", "-S", "-B", str(validator), str(provider_schema), str(envelope)],
        stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
        check=False,
    )
    canonical_checked = subprocess.run(
        [sys.executable, "-I", "-S", "-B", str(validator), str(canonical_schema), str(envelope)],
        stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
        check=False,
    )
    if provider_checked.returncode != 0 or canonical_checked.returncode != 0:
        with contextlib.suppress(OSError):
            envelope.unlink()
        return None, outer_status, "schema_rejection"
    try:
        rebound, info = read_regular(envelope, 1024 * 1024, "dispatch result")
    except DispatchError:
        return None, outer_status, "binding_failure"
    if rebound != raw:
        return None, outer_status, "binding_failure"
    return (digest(raw), _identity(info)), outer_status, None


@dataclasses.dataclass
class _ControllerBinding:
    state: Mapping[str, Any] = dataclasses.field(default_factory=dict)
    prior_raw: bytes = b""
    command: dict[str, Any] = dataclasses.field(default_factory=dict)
    feedback: Path | None = None
    schema_paths: tuple[Path, Path] | None = None


@dataclasses.dataclass
class _ProviderExecution:
    stop_signal: int | None = None
    process: subprocess.Popen[bytes] | None = None
    started_mono: float | None = None
    runtime_end_mono: float | None = None
    runtime_frozen: bool = False
    source_guard_expected: dict[str, Any] | None = None
    source_guard_baseline: dict[str, Any] | None = None
    source_guard_result: dict[str, Any] | None = None
    idle_timeout_with_exited_provider: bool = False
    elapsed: float = 0.0
    heartbeat_mono: float = 0.0
    next_notice: float = 0.0
    returncode: int = 0


@dataclasses.dataclass
class _ControllerStreams:
    stream_path: Path
    stderr_path: Path
    envelope_path: Path
    stdout_fd: int = -1
    stderr_fd: int = -1
    selector: selectors.BaseSelector | None = None
    buffers: dict[str, bytearray] = dataclasses.field(
        default_factory=lambda: {"stdout": bytearray(), "stderr": bytearray()},
    )
    sizes: dict[str, int] = dataclasses.field(
        default_factory=lambda: {"stdout": 0, "stderr": 0},
    )


@dataclasses.dataclass
class _ScopedLaunch:
    argv: list[str] = dataclasses.field(default_factory=list)
    expected_print: str | None = None
    provider_config_paths: dict[str, str] = dataclasses.field(default_factory=dict)
    launch_cwd: str = ""
    executable_binding: tuple[str, dict[str, Any]] | None = None
    stage_dir: Path | None = None
    scope: dict[str, Any] | None = None
    selected_manifest: list[dict[str, Any]] | None = None
    stage_manifest_sha: str | None = None
    stage_identity: tuple[int, int, int, int, int] | None = None
    narrow_source_snapshot: dict[str, Any] | None = None
    scoped_executable: str | None = None
    prepared_containment: CONTAINMENT.PreparedContainedLaunch | None = None
    contained_root: CONTAINMENT.ProcessIdentity | None = None


@dataclasses.dataclass
class _ControllerOutcome:
    reason: str | None = None
    limit_kind: str | None = None
    failure_stage: str | None = None
    saw_init: bool = False
    saw_terminal: bool = False
    provisional_orphan_result: bool = False
    result_binding: tuple[str, tuple[int, int, int, int, int]] | None = None
    outer_status: str | None = None
    source_guard_failed: bool = False
    boundary_failed: bool = False
    cleanup_failed: bool = False
    final_status: str = "failed"
    exit_code: int = 0
    result_path: str | None = None


@dataclasses.dataclass
class _CandidateReconciliation:
    candidate_worktree: dict[str, Any] | None = None
    reconciliation: dict[str, Any] = dataclasses.field(default_factory=dict)
    reconciliation_manifest_sha: str | None = None
    derived_selected_sha: str | None = None
    derived_selected_files: int | None = None
    derived_selected_trees: int | None = None
    derived_transmission_sha: str | None = None


def _controller_monitor_limit(
    state: Mapping[str, Any], stop_signal: int | None, elapsed: float,
    now_mono: float, heartbeat_mono: float, *, float_hard: bool,
) -> tuple[str, str | None] | None:
    """Classify a sample without evaluating limits after a winning control."""
    if state["cancel_requested"] or stop_signal is not None:
        return ("cancelled" if stop_signal is None else "interrupted"), None
    if elapsed >= _provider_max_seconds(state):
        return "hard_deadline_exceeded", "max-runtime"
    hard_seconds = float(state["hard_seconds"]) if float_hard else state["hard_seconds"]
    if elapsed >= hard_seconds:
        return "hard_deadline_exceeded", "hard"
    if now_mono - heartbeat_mono >= float(state["idle_seconds"]):
        return "idle_timeout", "idle"
    return None


def _controller_wait_seconds(
    state: Mapping[str, Any], started_mono: float, heartbeat_mono: float,
    next_notice: float, now_mono: float,
) -> float:
    """Bound a selector wait by the first controller-owned clock."""
    wait_until = min(
        started_mono + max(0.0, _provider_max_seconds(state) - float(state["attempt_base_elapsed"])),
        started_mono + max(0.0, float(state["hard_seconds"]) - float(state["attempt_base_elapsed"])),
        heartbeat_mono + float(state["idle_seconds"]),
        next_notice,
    )
    return min(CONTROL_POLL, max(0.0, wait_until - now_mono))


def _controller_terminal_status(
    reason: str | None, stop_signal: int | None,
) -> tuple[str, int]:
    if reason is None:
        return "succeeded", 0
    status = "cancelled" if reason in {
        "cancelled", "interrupted", "provider_terminal_cancelled",
    } else "failed"
    return status, 128 + stop_signal if stop_signal is not None else EXIT_BY_REASON[reason]


def _controller_completion_signal(
    watched: tuple[int, ...], pending: AbstractSet[int], stop_signal: int | None,
) -> int | None:
    for candidate in watched:
        if candidate in pending or candidate == stop_signal:
            return candidate
    return stop_signal


def _latch_controller_signal(execution: _ProviderExecution, number: int) -> None:
    if execution.stop_signal is None:
        execution.stop_signal = number


@dataclasses.dataclass
class _CandidateDisposition:
    preserve_candidate_forensics: bool = False
    terminal_snapshot_unavailable: bool = False
    candidate_recognized: bool = False
    candidate_unavailable: bool = False
    candidate_source: str = "none"
    provider_terminal_status: str = "unknown"
    preserved_path: str | None = None
    preserved_sha: str | None = None
    preserved_identity: list[int] | None = None


def _claim_controller_attempt(
    job: Path,
    binding: _ControllerBinding,
) -> int | None:
    # Claim the queued attempt under one state lock.  A cancel can land
    # between process spawn and this point, but never between this exact
    # queued observation and controller ownership publication.
    cancelled_before_claim = False
    with state_lock(job):
        binding.state, binding.prior_raw, _sha = load_state(job)
        if binding.state["status"] == "cancel-requested" and binding.state["cancel_requested"]:
            cancelled_before_claim = True
        elif binding.state["status"] != "queued" or binding.state["cancel_requested"]:
            raise DispatchError("dispatch is not queued")
        else:
            # A queued state with this exact PID is the startup handshake; it
            # means the private controller is alive, not that a provider
            # process exists or that provider runtime has started.
            binding.state, binding.prior_raw, _sha = _transition_locked(job, binding.state, binding.prior_raw, {
                "controller_pid": os.getpid(),
            })
    if cancelled_before_claim:
        _terminalize_owned(
            job, binding.state, status="cancelled", reason="cancelled",
            exit_code=EXIT_BY_REASON["cancelled"], expected_controller_pid=None,
        )
        return EXIT_BY_REASON["cancelled"]
    return None


def _bind_controller_inputs(
    job: Path,
    binding: _ControllerBinding,
) -> int | None:
    binding.feedback = None
    binding.schema_paths = None
    try:
        binding.command = _load_bound_command(job, binding.state, stage_readonly=False)
        MODEL_SELECTION.ACTIVE_CHILD_ENV = list(binding.command["provider_env"])
        _load_bound_selection(binding.command, binding.state)
        binding.schema_paths = _bound_schemas(binding.command, binding.state)
        if not WORKTREE._worktree_symlink_boundary(binding.command["workdir"]):
            raise DispatchError("dispatch worktree symlink boundary changed")
        if binding.state["workflow"] == "project":
            if WORKTREE._project_boundary(binding.command["workdir"]) != binding.state["project_boundary"]:
                raise DispatchError("project worktree boundary changed")
        if binding.state["attempt_origin"] == "conversation-continue":
            binding.feedback = _bound_verification(job, binding.state)
            if binding.feedback is None:
                raise DispatchError("project continuation has no verification feedback")
            binding.command, _candidate_raw = _bound_current_candidate(job, binding.state)
    except (OSError, DispatchError):
        terminal, _raw, _sha = _terminalize_owned(
            job, binding.state, status="failed", reason="status_unavailable",
            exit_code=EXIT_BY_REASON["status_unavailable"],
            failure_stage="binding_failure", expected_controller_pid=os.getpid(),
        )
        # Terminal validation guarantees an integer exit code.
        assert terminal["exit_code"] is not None
        return int(terminal["exit_code"])
    return None


def _open_controller_artifacts(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
) -> int | None:
    # ``elapsed_seconds`` is provider execution time.  The strict local
    # command/root/schema/worktree proofs below happen before a provider
    # process exists, so they cannot consume the provider hard, maximum,
    # or idle budgets.  This is especially important when a safe platform
    # Git fallback makes those bounded probes materially slower.
    execution.elapsed = float(binding.state["attempt_base_elapsed"])
    try:
        streams.stdout_fd = _ensure_new_private(streams.stream_path)
        streams.stderr_fd = _ensure_new_private(streams.stderr_path)
        _stage(binding.command, True)
        _load_bound_command(job, binding.state, stage_readonly=True)
        _load_bound_selection(binding.command, binding.state)
        binding.schema_paths = _bound_schemas(binding.command, binding.state)
    except (OSError, DispatchError):
        if streams.stdout_fd >= 0: os.close(streams.stdout_fd)
        if streams.stderr_fd >= 0: os.close(streams.stderr_fd)
        with contextlib.suppress(OSError): _stage(binding.command, False)
        terminal, _raw, _sha = _terminalize_owned(
            job, binding.state, status="failed", reason="status_unavailable",
            exit_code=EXIT_BY_REASON["status_unavailable"],
            failure_stage="binding_failure", expected_controller_pid=os.getpid(),
        )
        # Terminal validation guarantees an integer exit code.
        assert terminal["exit_code"] is not None
        return int(terminal["exit_code"])
    return None


def _build_controller_argv(
    binding: _ControllerBinding,
    launch: _ScopedLaunch,
) -> None:
    launch.argv = list(binding.command["argv"])
    if binding.state["attempt_origin"] in {"conversation-resume", "conversation-continue"}:
        conversation = binding.state["conversation_id"]
        if not isinstance(conversation, str):
            raise DispatchError("resume has no conversation")
        print_index = launch.argv.index("--print")
        prefix = ["--conversation", conversation]
        prompt = binding.command["resume_prompt"]
        if binding.state["attempt_origin"] == "conversation-continue":
            if binding.feedback is None:
                raise DispatchError("project continuation feedback was not prevalidated")
            if binding.state.get("provider_scope_path") is None:
                prefix.extend(["--add-dir", str(binding.feedback.parent)])
                prompt = binding.command["continue_prompt"] + f" Feedback file: '{binding.feedback}'."
            else:
                feedback_raw, _feedback_info = read_regular(
                    binding.feedback, MAX_VERIFICATION_BYTES, "verification feedback",
                    allowed_modes=(0o400,),
                )
                prompt = (
                    binding.command["continue_prompt"]
                    + " Driver verification JSON follows inline:\n"
                    + feedback_raw.decode("utf-8", "strict")
                )
        launch.argv[print_index + 1] = prompt
        launch.argv[print_index:print_index] = prefix


def _controller_transition(
    job: Path,
    binding: _ControllerBinding,
    updates: dict[str, Any],
) -> bool:
    """Do not turn a concurrent approved control into a controller crash."""
    try:
        binding.state, binding.prior_raw, _sha = transition(job, binding.state, binding.prior_raw, updates)
        return True
    except DispatchError as exc:
        if str(exc) != "dispatch state changed before transition":
            raise
        current, current_raw, _current_sha = read_state_snapshot(job)
        if current["attempt"] != binding.state["attempt"]:
            raise DispatchError("dispatch attempt changed during control")  # noqa: B904 -- preserve existing exception context and public diagnostics
        binding.state, binding.prior_raw = current, current_raw
        return False


def _refresh_control_snapshot(
    job: Path,
    binding: _ControllerBinding,
) -> None:
    """Reload an approved control transition before using live limits."""
    current, current_raw, _current_sha = read_state_snapshot(job)
    if current_raw == binding.prior_raw:
        return
    if (
        current["previous_state_sha256"] != digest(binding.prior_raw)
        or current["sequence"] != binding.state["sequence"] + 1
        or current["attempt"] != binding.state["attempt"]
    ):
        raise DispatchError("dispatch changed during provider control")
    binding.state, binding.prior_raw = current, current_raw


def _drain_reaped_streams(
    streams: _ControllerStreams,
    outcome: _ControllerOutcome,
) -> None:
    """Bind bytes emitted before reap without treating them as activity."""
    for key in list(cast(selectors.BaseSelector, streams.selector).get_map().values()):
        name = key.data
        while True:
            try:
                chunk = os.read(key.fd, 65536)
            except BlockingIOError:
                break
            except OSError:
                outcome.reason = "status_unavailable"
                outcome.failure_stage = "binding_failure"
                return
            if not chunk:
                try:
                    cast(selectors.BaseSelector, streams.selector).unregister(key.fileobj)
                    cast(IO[bytes], key.fileobj).close()
                except OSError:
                    outcome.reason = "status_unavailable"
                    outcome.failure_stage = "binding_failure"
                break
            streams.sizes[name] += len(chunk)
            if streams.sizes[name] > MAX_STREAM_BYTES:
                outcome.reason = "output_oversized"
                return
            try:
                os.write(streams.stdout_fd if name == "stdout" else streams.stderr_fd, chunk)
            except OSError:
                outcome.reason = "status_unavailable"
                outcome.failure_stage = "binding_failure"
                return


def _prepare_scoped_controller_launch(
    job: Path,
    binding: _ControllerBinding,
    launch: _ScopedLaunch,
) -> None:
    _scope_path, raw_scope, scope_info = _read_provider_scope_file(
        binding.state["provider_scope_path"], MAX_COMMAND_BYTES,
    )
    if digest(raw_scope) != binding.state["provider_scope_sha256"]:
        raise DispatchError("provider scope file changed since dispatch")
    if list(_identity(scope_info)) != binding.state["provider_scope_identity"]:
        raise DispatchError("provider scope file identity changed since dispatch")
    launch.scope = WORKTREE._parse_provider_scope(raw_scope)
    readable_manifest = WORKTREE._scan_readable_worktree(binding.command["workdir"])
    manifest_sha = WORKTREE._manifest_digest(readable_manifest)
    WORKTREE._check_provider_config_entries(readable_manifest, scope=launch.scope)
    WORKTREE._validate_scope_against_worktree(launch.scope, binding.command["workdir"], readable_manifest)
    launch.selected_manifest = WORKTREE._build_selected_content_manifest(
        binding.command["workdir"], launch.scope, provider_configuration=True)
    launch.provider_config_paths = WORKTREE._check_provider_config_entries(launch.selected_manifest)
    selected_sha = WORKTREE._selected_content_digest(launch.selected_manifest)
    policy_sha = WORKTREE._canonical_digest(launch.scope)
    transmission_sha = _bound_transmission_sha256(
        binding.command, policy_sha, manifest_sha, selected_sha,
    )
    _require_scoped_transmission_authority(
        binding.command, binding.state,
        selected_content_sha256=selected_sha,
        transmission_sha256=transmission_sha,
        provider_origin=binding.state["attempt_origin"],
    )
    launch.narrow_source_snapshot = WORKTREE._worktree_snapshot(binding.command["workdir"])
    launch.stage_dir = job / f"stage-{binding.state['attempt']:03d}"
    launch.stage_identity, launch.stage_manifest_sha = WORKTREE._materialize_stage(
        binding.command["workdir"], launch.stage_dir, launch.scope, launch.selected_manifest,
        provider_configuration=True,
    )
    launch.launch_cwd = str(launch.stage_dir)
    if launch.executable_binding is None:
        try:
            launch.executable_binding = MODEL_SELECTION.resolve_safe_executable()
        except MODEL_SELECTION.EvidenceUnavailable as exc:
            raise SelectionPreflightError(
                "scoped dispatch executable binding is unavailable",
            ) from exc
    launch.scoped_executable = launch.executable_binding[0]


def _confirm_whole_controller_approval(
    binding: _ControllerBinding,
) -> None:
    approved_whole_sha = binding.command.get("approved_whole_worktree_sha256")
    if (
        approved_whole_sha is not None
        and (
            binding.state["attempt_origin"] == "initial"
            or (
                binding.state.get("conversation_id") is None
            )
        )
    ):
        readable_manifest = WORKTREE._scan_readable_worktree(binding.command["workdir"])
        content = WORKTREE.whole_worktree_content_manifest(binding.command["workdir"])
        content_sha = content["manifest_sha256"]
        if content_sha != binding.command["whole_worktree_content_sha256"]:
            raise DispatchError("whole-worktree content binding changed")
        if WORKTREE._manifest_digest(readable_manifest) != binding.command["launch_authority"]["content"]["manifest_sha256"]:
            raise DispatchError("whole-worktree transmission binding changed")


def _prepare_native_controller_launch(
    job: Path,
    binding: _ControllerBinding,
    launch: _ScopedLaunch,
) -> None:
    if launch.stage_dir is None:
        raise DispatchError("scoped provider stage is unavailable")
    contained_argv = [cast(str, launch.scoped_executable), *launch.argv[1:]]
    if contained_argv.count("--json-schema") != 1:
        raise DispatchError("scoped provider schema argument is invalid")
    schema_index = contained_argv.index("--json-schema") + 1
    if schema_index >= len(contained_argv):
        raise DispatchError("scoped provider schema argument is invalid")
    # The native binder canonicalizes the exact file. Use the
    # same spelling in argv so /var -> /private/var aliases do
    # not make the provider's approved schema unreadable.
    contained_argv[schema_index] = os.path.realpath(cast(tuple[Path, Path], binding.schema_paths)[0])
    launch.prepared_containment = CONTAINMENT.prepare_contained_launch(
        role=CONTAINMENT.ROLE_PROVIDER,
        network_policy=CONTAINMENT.NETWORK_PROVIDER_TLS,
        job_dir=job,
        attempt=binding.state['attempt'],
        stage_dir=launch.stage_dir,
        target_executable=cast(str, launch.scoped_executable),
        target_argv=contained_argv,
        child_environment=MODEL_SELECTION.child_environment(
            binding.command["provider_env"],
        ),
        allow_keychain=True,
        read_only_inputs=(contained_argv[schema_index],),
        provider_max_cycles=binding.command["max_cycles"],
        provider_write_selectors=cast(dict[str, Any], launch.scope)["write"],
        grant_profile=binding.command["native_grant_profile"],
    )


def _spawn_controller_provider(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
) -> None:
    # The prior attempt budget is still a hard stop, but bounded
    # controller-local proofs do not become a provider timeout.
    # Commit the running state/CAS boundary after slow preflight.
    # The provider hard/runtime lease starts at the invocation
    # boundary, immediately before Popen.  The value is committed
    # only after Popen succeeds, so failed local creation still
    # has no provider runtime.  This leaves no post-Popen window
    # in which a child can schedule work beyond the hard limit.
    # The final executable confirmation remains immediately
    # adjacent to the provider-causing call.
    source_guard = _prepare_controller_source(binding, execution)
    # Linearize cancellation against the provider-causing
    # operation.  The final executable confirmation and Popen
    # stay in this same short critical section: cancellation
    # before it wins without a provider; cancellation after
    # it is necessarily a post-launch request.
    with state_lock(job):
        current, current_raw, _current_sha = load_state(job)
        if (
            current["attempt"] != binding.state["attempt"]
            or current["controller_pid"] != os.getpid()
            or current["status"] in TERMINAL
        ):
            raise DispatchError("dispatch changed before provider launch")
        binding.state, binding.prior_raw = current, current_raw
        if current["source_checkout_guard"] != execution.source_guard_expected:
            source_guard = {**source_guard, "status": "changed" if source_guard["status"] == "changed" else "unavailable", "after_sha256": None}
            execution.source_guard_baseline = source_guard.copy()
        # A completed failed proof wins over every ordinary prelaunch stop.
        # Publish it after the same authority/transplant check even when a
        # signal or deadline arrived while the observation was in progress.
        if source_guard["status"] in {"changed", "unavailable"}:
            binding.state, binding.prior_raw, _sha = _transition_locked(
                job, current, current_raw, {"source_checkout_guard": source_guard},
            )
            outcome.reason = cast(str, _source_guard_reason({"source_checkout_guard": source_guard}))
            execution.returncode = EXIT_BY_REASON[outcome.reason]
        elif execution.stop_signal is not None:
            execution.source_guard_baseline = None
            outcome.reason = "interrupted"
            execution.returncode = 128 + execution.stop_signal
        elif binding.state["cancel_requested"]:
            outcome.reason = "cancelled"
            execution.returncode = EXIT_BY_REASON[outcome.reason]
            execution.source_guard_baseline = None
        elif execution.elapsed >= _provider_max_seconds(binding.state):
            execution.source_guard_baseline = None
            outcome.reason, outcome.limit_kind = "hard_deadline_exceeded", "max-runtime"
            execution.returncode = EXIT_BY_REASON[outcome.reason]
        elif execution.elapsed >= float(binding.state["hard_seconds"]):
            execution.source_guard_baseline = None
            outcome.reason, outcome.limit_kind = "hard_deadline_exceeded", "hard"
            execution.returncode = EXIT_BY_REASON[outcome.reason]
        else:
            running_updates = {"source_checkout_guard": source_guard,
                "status": "running", "controller_pid": os.getpid(),
                "started_epoch": None, "last_progress_epoch": None,
                "stream_path": str(streams.stream_path), "stderr_path": str(streams.stderr_path),
                "next_action": "wait",
            }
            if launch.stage_dir is not None:
                running_updates.update({
                    "provider_stage_path": str(launch.stage_dir),
                    "provider_stage_identity": list(launch.stage_identity) if launch.stage_identity is not None else None,
                    "provider_stage_manifest_sha256": launch.stage_manifest_sha,
                })
            binding.state, binding.prior_raw, _sha = _transition_locked(job, binding.state, binding.prior_raw, running_updates)
            exact_executable = None
            if launch.executable_binding is not None:
                try:
                    exact_executable = MODEL_SELECTION.confirm_executable_binding(
                        *launch.executable_binding,
                    )
                except MODEL_SELECTION.EvidenceUnavailable as exc:
                    raise SelectionPreflightError(
                        "dispatch direct selection launch binding changed",
                    ) from exc
            provider_argv: list[str] | tuple[str, ...] = launch.argv
            provider_cwd = launch.launch_cwd
            provider_environment = _provider_environment(binding.command)
            if launch.prepared_containment is not None:
                if (
                    launch.stage_dir is None
                    or launch.scope is None
                    or launch.selected_manifest is None
                    or launch.stage_identity is None
                    or launch.stage_manifest_sha is None
                ):
                    raise DispatchError("scoped provider launch binding is incomplete")
                _revalidate_scoped_provider_stage(
                    launch.stage_dir, launch.scope, launch.selected_manifest,
                    launch.stage_identity, launch.stage_manifest_sha,
                )
                confirmed_containment = CONTAINMENT.confirm_contained_launch(
                    launch.prepared_containment,
                )
                provider_argv = confirmed_containment.argv
                exact_executable = confirmed_containment.executable
                provider_cwd = confirmed_containment.cwd
                provider_environment = confirmed_containment.environment
            if (launch.expected_print is None or provider_argv.count("--print") != 1
                    or provider_argv[provider_argv.index("--print") + 1] != launch.expected_print):
                raise DispatchError("dispatch final transport prompt changed")
            WORKTREE._recheck_provider_configuration(
                provider_cwd, launch.provider_config_paths, ambient_home=os.environ.get("HOME"),
                controlled_roots=(str(job), binding.command["workdir"]),
            )
            launch_mono = time.monotonic()
            execution.process = subprocess.Popen(
                provider_argv,
                executable=exact_executable,
                cwd=provider_cwd,
                stdin=subprocess.DEVNULL,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
                env=provider_environment,
                start_new_session=True,
                close_fds=True,
                preexec_fn=lambda: os.umask(int(binding.command["child_umask"], 8)),
            )
            execution.started_mono = launch_mono
            execution.heartbeat_mono = execution.started_mono
            execution.next_notice = execution.started_mono + float(binding.command["notice_seconds"])
            if launch.prepared_containment is not None:
                launch.contained_root = CONTAINMENT.bind_new_process_group(
                    execution.process.pid,
                )
            binding.state, binding.prior_raw, _sha = _transition_locked(
                job, binding.state, binding.prior_raw, {"started_epoch": time.time()},
            )


def _confirm_launch_authority(job: Path, command: dict[str, Any], state: Mapping[str, Any]) -> None:
    """Recompute caller authority from actual immutable inputs before spawning."""
    try:
        task_raw = LAUNCH_AUTHORITY.read_bound_file(
            job / "task.txt", LAUNCH_AUTHORITY.MAX_TASK_BYTES, private=True, label="initial task")
        task, _text = LAUNCH_AUTHORITY.normalize_task(task_raw)
        if digest(task) != command["launch_authority"]["task_sha256"]:
            raise DispatchError("launch authority changed: task_sha256")
        argv = command["argv"]

        def option(name: str) -> str | None:
            positions = [index for index, item in enumerate(argv) if item == name]
            if len(positions) > 1 or (positions and positions[0] + 1 >= len(argv)):
                raise DispatchError("dispatch launch argument is invalid")
            return argv[positions[0] + 1] if positions else None

        if option("--print-timeout") != f'{command["max_seconds"]}s':
            raise DispatchError("launch authority changed: max_seconds")
        if option("--output-format") != "stream-json":
            raise DispatchError("dispatch launch output format is invalid")
        _load_bound_selection(command, state)
        mode = option("--mode")
        if mode not in {"plan", "accept-edits"}:
            raise DispatchError("dispatch launch mode is invalid")
        if mode != command["launch_authority"]["mode"]:
            raise DispatchError("launch authority changed: mode")
        block = ""
        manifest_sha = None
        if command["self_verification_manifest_path"] is not None:
            raw = LAUNCH_AUTHORITY.read_bound_file(
                Path(command["self_verification_manifest_path"]), SELF_VERIFICATION.MAX_MANIFEST_BYTES,
                private=True, label="verification manifest")
            manifest = SELF_VERIFICATION.parse_manifest(raw)
            block = LAUNCH_AUTHORITY.verification_request_block(
                [check.identifier for check in manifest.checks if check.required],
                [check.identifier for check in manifest.checks if not check.required])
            manifest_sha = digest(raw)
        prompt = LAUNCH_AUTHORITY.full_prompt(
            task, mode=mode, provider_isolation=command["provider_isolation"], verification_block=block)
        retained_prompt = LAUNCH_AUTHORITY.read_bound_file(
            job / "full-prompt.txt", LAUNCH_AUTHORITY.MAX_TASK_BYTES + 65536,
            private=True, label="initial prompt")
        if prompt != retained_prompt:
            raise DispatchError("launch authority changed: full_prompt_sha256")
        initial_prompt = option("--print")
        if command["stage_file"] is not None:
            initial_expected = LAUNCH_AUTHORITY.STAGED_INSTRUCTION.format(stage_file=command["stage_file"])
            staged, _info = read_regular(Path(command["stage_file"]), MAX_COMMAND_BYTES,
                                        "staged prompt", allowed_modes=(0o600, 0o444))
            if staged != prompt:
                raise DispatchError("launch authority changed: full_prompt_sha256")
        else:
            initial_expected = prompt.decode("utf-8")
        if initial_prompt != initial_expected:
            raise DispatchError("launch authority changed: full_prompt_sha256")
        schema = option("--json-schema")
        if schema is None:
            raise DispatchError("dispatch launch schema is missing")
        schema_raw = LAUNCH_AUTHORITY.read_bound_file(Path(schema), 512 * 1024,
                                                     private=False, label="provider schema")
        root = Path(command["workdir"]).resolve()
        add_dirs = []
        for index, argument in enumerate(argv):
            if argument == "--add-dir":
                path = Path(argv[index + 1]).resolve(strict=True)
                if command["stage_dir"] is not None and path == Path(command["stage_dir"]).resolve():
                    continue
                add_dirs.append(path.relative_to(root).as_posix())
        actual = LAUNCH_AUTHORITY.build_authority(
            content=command["launch_authority"]["content"], task=task, prompt=prompt,
            workflow=command["workflow"], mode=mode, max_cycles=command["max_cycles"],
            idle_seconds=command["idle_seconds"], hard_seconds=command["hard_seconds"],
            max_seconds=command["max_seconds"], notice_seconds=command["notice_seconds"],
            model=option("--model"), effort=option("--effort"),
            allow_scoped_repair=command["allow_scoped_repair"],
            self_verification_manifest_sha256=manifest_sha,
            provider_env_names=command["provider_env"],
            allow_slash_commands=mode == "accept-edits" and "--disable-slash-commands" not in argv,
            add_dirs=sorted(set(add_dirs)), provider_schema_sha256=digest(schema_raw),
            base_commit=command["base_commit"], workdir=str(root))
        field = LAUNCH_AUTHORITY.changed_field(command["launch_authority"], actual)
        if field:
            raise DispatchError(f"launch authority changed: {field}")
        if LAUNCH_AUTHORITY.approval_sha256(actual) != command["launch_approval_sha256"]:
            raise DispatchError("dispatch launch approval digest changed")
    except DispatchError:
        raise
    except (LAUNCH_AUTHORITY.LaunchAuthorityError, ValueError, IndexError) as exc:
        raise DispatchError("dispatch launch authority is unavailable") from exc


def _launch_controller_provider(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
) -> None:
    try:
        # Re-read the frozen record and re-probe *after* all controller
        # mutations and immediately before the provider-causing launch.
        # argv[0] stays the portable public spelling while executable=
        # pins the safe, freshly-probed target for this one process.
        launch.executable_binding = _reprobe_direct_selection(binding.command, binding.state, launch.argv)
        _bound_worktree_baseline(binding.state, binding.command)
        if not WORKTREE._worktree_symlink_boundary(
            binding.command["workdir"],
            provider_config_paths=(launch.provider_config_paths
                if binding.state.get("provider_scope_path") is None else None),
        ):
            raise DispatchError("dispatch worktree symlink boundary changed")
        launch.launch_cwd = binding.command["workdir"]
        if binding.state.get("provider_scope_path") is not None:
            _prepare_scoped_controller_launch(job, binding, launch)
        else:
            _confirm_whole_controller_approval(binding)
            if binding.command["base_commit"] is not None:
                _bound_whole_worktree_base(
                    binding.command["workdir"], binding.command["base_commit"],
                    binding.command["workflow"],
                )
        _confirm_launch_authority(job, binding.command, binding.state)
        launch.expected_print = _bind_workspace_prompt(
            launch.argv, Path(os.path.realpath(launch.launch_cwd)),
            scoped=launch.scope is not None,
            provider_isolation=_provider_isolation_for_command(binding.command),
            base_commit=binding.command["base_commit"],
        )
        if launch.scoped_executable is not None and _provider_isolation_for_command(binding.command) == "native":
            _prepare_native_controller_launch(job, binding, launch)
        _spawn_controller_provider(job, binding, execution, streams, launch, outcome)
    except MODEL_SELECTION.ProbeInterrupted as exc:
        # model_selection owns and reaps its short-lived probe group;
        # the controller owns the terminal dispatch projection.
        execution.stop_signal = exc.signal_number
        outcome.reason = "interrupted"
        execution.returncode = 128 + exc.signal_number
    except SelectionPreflightError as exc:
        outcome.reason = "selection_preflight_failed"
        outcome.failure_stage = "selection_preflight"
        cause = exc.__cause__
        if isinstance(cause, MODEL_SELECTION.MissingCapabilities):
            diagnostic = (cause.diagnostic() + "\n").encode("ascii")
            try:
                if os.write(streams.stderr_fd, diagnostic) != len(diagnostic):
                    raise OSError("short capability diagnostic write")
            except OSError:
                outcome.reason = "status_unavailable"
                outcome.failure_stage = "binding_failure"
        execution.returncode = EXIT_BY_REASON[outcome.reason]
    except WorktreeBaselineError as exc:
        outcome.reason = "resolve_undo_present" if isinstance(exc, ResolveUndoPresentError) else "status_unavailable"
        outcome.failure_stage = "binding_failure"
        execution.returncode = EXIT_BY_REASON[outcome.reason]
    except WORKTREE.ExecutableProviderConfigurationError as exc:
        with contextlib.suppress(OSError):
            os.write(streams.stderr_fd, (str(exc) + "\n").encode("ascii"))
        outcome.reason = "status_unavailable"
        execution.returncode = EXIT_BY_REASON["status_unavailable"]
    except CONTAINMENT.KeychainUnavailableError as exc:
        with contextlib.suppress(OSError):
            os.write(streams.stderr_fd, (f"agy-worker: {exc}\n").encode("ascii", "backslashreplace"))
        outcome.reason = "native_host_sandbox_unavailable"
        execution.returncode = EXIT_BY_REASON[outcome.reason]
    except (DispatchError, CONTAINMENT.ContainmentError) as exc:
        message = str(exc)
        if re.fullmatch(r"launch authority changed: [a-z0-9_]+(?:\.[a-z0-9_]+)?", message):
            outcome.failure_stage = "launch_authority_changed:" + message.removeprefix("launch authority changed: ")
            with contextlib.suppress(OSError):
                os.write(streams.stderr_fd, (message + "\n").encode("ascii"))
        outcome.reason = "status_unavailable"
        execution.returncode = EXIT_BY_REASON["status_unavailable"]
    except OSError:
        # A selection reaches this point even when agy is
        # absent.  Publish a terminal, sanitized dispatch failure rather
        # than leaking an interpreter traceback or leaving a queued job.
        outcome.reason = "agy_failed_unclassified"
        execution.returncode = 127
    else:
        if execution.process is not None:
            try:
                assert execution.process.stdout is not None and execution.process.stderr is not None
                for name, pipe in (("stdout", execution.process.stdout), ("stderr", execution.process.stderr)):
                    os.set_blocking(pipe.fileno(), False)
                    cast(selectors.BaseSelector, streams.selector).register(pipe, selectors.EVENT_READ, name)
            except (OSError, DispatchError):
                outcome.reason = "status_unavailable"
                outcome.failure_stage = "binding_failure"


def _consume_controller_events(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
    events: list[tuple[selectors.SelectorKey, int]],
) -> None:
    for key, _mask in events:
        name = key.data
        try:
            chunk = os.read(key.fd, 65536)
        except BlockingIOError:
            continue
        except OSError:
            outcome.reason = "status_unavailable"
            outcome.failure_stage = "binding_failure"
            break
        if not chunk:
            try:
                cast(selectors.BaseSelector, streams.selector).unregister(key.fileobj)
                cast(IO[bytes], key.fileobj).close()
            except OSError:
                outcome.reason = "status_unavailable"
                outcome.failure_stage = "binding_failure"
                break
            continue
        streams.sizes[name] += len(chunk)
        if streams.sizes[name] > MAX_STREAM_BYTES:
            outcome.reason = "output_oversized"
            break
        try:
            os.write(streams.stdout_fd if name == "stdout" else streams.stderr_fd, chunk)
        except OSError:
            outcome.reason = "status_unavailable"
            outcome.failure_stage = "binding_failure"
            break
        if name == "stdout" and outcome.reason is None:
            streams.buffers[name].extend(chunk)
            while b"\n" in streams.buffers[name]:
                line, _, remainder = streams.buffers[name].partition(b"\n")
                streams.buffers[name] = bytearray(remainder)
                if len(line) > MAX_EVENT_BYTES:
                    outcome.reason = "output_oversized"
                    break
                if outcome.provisional_orphan_result:
                    # Keep subsequent bytes as evidence only. No progress,
                    # conversation binding, or heartbeat credit is authorized.
                    continue
                valid, conversation, event_kind = _event(line)
                if valid:
                    if outcome.saw_terminal or (event_kind == "init" and outcome.saw_init) or (
                        event_kind != "init" and not outcome.saw_init
                    ):
                        if (
                            not outcome.saw_init and not outcome.saw_terminal
                            and streams.sizes[name] - len(remainder) == len(line) + 1
                            and _selection_rejection_result(line)
                        ):
                            # Preserve framing as a provisional fallback while
                            # the existing bounded monitor observes EOF/reap.
                            outcome.provisional_orphan_result = True
                            continue
                        outcome.reason = "invalid_envelope"
                        outcome.failure_stage = "framing"
                        break
                    if event_kind == "init":
                        try:
                            init_frame = json.loads(
                                line.decode("utf-8", "strict"),
                                object_pairs_hook=_duplicates,
                            )
                        except (UnicodeError, json.JSONDecodeError, ValueError, OverflowError, DispatchError):
                            init_frame = None
                        init_value = init_frame.get("init") if isinstance(init_frame, dict) else None
                        if not isinstance(init_value, dict) or not _init_cwd_matches_launch(init_value, launch.launch_cwd):
                            outcome.reason = "status_unavailable"
                            outcome.failure_stage = "binding_failure"
                            break
                        outcome.saw_init = True
                    elif event_kind == "result":
                        outcome.saw_terminal = True
                    execution.heartbeat_mono = time.monotonic()
                    updates: dict[str, Any] = {
                        "progress_count": binding.state["progress_count"] + 1,
                        "last_progress_epoch": time.time(),
                        "elapsed_seconds": float(binding.state["attempt_base_elapsed"]) + execution.heartbeat_mono - cast(float, execution.started_mono),
                        "last_activity": (
                            "provider_initialized" if event_kind == "init"
                            else "progress_signal" if event_kind == "step_update"
                            else "terminal_received"
                        ),
                    }
                    if conversation is not None:
                        if binding.state["conversation_id"] not in {None, conversation}:
                            outcome.reason = "status_unavailable"
                            break
                        updates["conversation_id"] = conversation
                        updates["resume_available"] = True
                    try:
                        _controller_transition(job, binding, updates)
                    except DispatchError:
                        outcome.reason = "status_unavailable"
                        outcome.failure_stage = "binding_failure"
                        break
            if len(streams.buffers[name]) > MAX_EVENT_BYTES:
                # A newline-free oversized frame cannot be safely
                # resynchronized.  It is neither a heartbeat nor a
                # candidate terminal result.
                outcome.reason = "output_oversized"
        if outcome.reason is not None:
            break


def _monitor_controller_provider(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
) -> None:
    # Pipe EOF is the completion observation.  Do not poll/reap the leader
    # before process-group closure; its PID reserves the group identifier.
    while execution.process is not None and cast(selectors.BaseSelector, streams.selector).get_map() and outcome.reason is None:
        now_mono = time.monotonic()
        execution.elapsed = float(binding.state["attempt_base_elapsed"]) + now_mono - cast(float, execution.started_mono)
        try:
            _refresh_control_snapshot(job, binding)
        except DispatchError:
            outcome.reason = "status_unavailable"
            break
        decision = _controller_monitor_limit(binding.state, execution.stop_signal, execution.elapsed, now_mono, execution.heartbeat_mono, float_hard=False)
        if decision is not None:
            outcome.reason, outcome.limit_kind = decision
            break
        if now_mono >= execution.next_notice:
            try:
                _controller_transition(job, binding, {
                    "notice_count": binding.state["notice_count"] + 1,
                    "elapsed_seconds": execution.elapsed,
                })
            except DispatchError:
                outcome.reason = "status_unavailable"
                outcome.failure_stage = "binding_failure"
                break
            execution.next_notice += float(binding.command["notice_seconds"])
            if sys.stderr.isatty():
                print(
                    f"agy-worker: still running; elapsed={int(execution.elapsed)}s "
                    f"progress={binding.state['progress_count']}", file=sys.stderr, flush=True,
                )
        try:
            # A fixed poll can return after a nearer hard, maximum,
            # idle, or notice boundary.  Bound the kernel wait to the
            # first controller-owned clock, then reload any extension
            # and classify the resampled time before consuming ready
            # bytes as semantic progress.
            wait_seconds = _controller_wait_seconds(binding.state, cast(float, execution.started_mono), execution.heartbeat_mono, execution.next_notice, now_mono)
            events = cast(selectors.BaseSelector, streams.selector).select(wait_seconds)
        except OSError:
            outcome.reason = "status_unavailable"
            outcome.failure_stage = "binding_failure"
            break
        post_wait_mono = time.monotonic()
        try:
            _refresh_control_snapshot(job, binding)
        except DispatchError:
            outcome.reason = "status_unavailable"
            outcome.failure_stage = "binding_failure"
            break
        execution.elapsed = (
            float(binding.state["attempt_base_elapsed"])
            + post_wait_mono - cast(float, execution.started_mono)
        )
        decision = _controller_monitor_limit(binding.state, execution.stop_signal, execution.elapsed, post_wait_mono, execution.heartbeat_mono, float_hard=True)
        if decision is not None:
            outcome.reason, outcome.limit_kind = decision
            break
        _consume_controller_events(job, binding, execution, streams, launch, outcome, events)
        if outcome.reason is not None:
            break


def _reap_controller_provider(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
) -> None:
    if execution.process is not None:
        # The candidate worktree binding below is taken only after the
        # provider process group has been terminated and reaped.  The
        # controller-owned stream artifacts are flushed afterward.
        # Freeze first: fsync, envelope parsing, and reconciliation
        # are controller-local work and must not keep the provider
        # clock or extension window alive.
        execution.returncode = _terminate_provider_process(
            execution.process, launch.contained_root,
            contained=launch.prepared_containment is not None,
        )
        execution.idle_timeout_with_exited_provider = bool(
            outcome.reason == "idle_timeout" and execution.returncode == 0
        )
        execution.process = None
        execution.runtime_end_mono = time.monotonic()
        # A hard/max boundary stops semantic event processing, but a
        # complete terminal frame already present in the reaped pipes
        # remains bounded provider evidence.  Drain it without
        # incrementing progress or moving the heartbeat.
        _drain_reaped_streams(streams, outcome)
        assert execution.started_mono is not None
        execution.elapsed = float(binding.state["attempt_base_elapsed"]) + max(
            0.0, execution.runtime_end_mono - execution.started_mono,
        )
        binding.state, binding.prior_raw, _sha, frozen_limit = _freeze_reaped_runtime(
            job, binding.state["attempt"], os.getpid(), execution.elapsed,
        )
        execution.runtime_frozen = True
        if outcome.reason == "hard_deadline_exceeded":
            # A valid extension may have landed after this controller
            # observed its old limit but before the reaped-runtime CAS.
            # The frozen locked limit is authoritative in either
            # direction; do not retain a stale timeout projection.
            if frozen_limit is None:
                outcome.reason, outcome.limit_kind = None, None
            else:
                outcome.reason, outcome.limit_kind = "hard_deadline_exceeded", frozen_limit
        elif outcome.reason is None and frozen_limit is not None:
            outcome.reason, outcome.limit_kind = "hard_deadline_exceeded", frozen_limit


def _observe_controller_terminal(
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
) -> None:
    # A flush failure must not reopen parsing for an already-observed cancel.
    cancelled_before_terminal = outcome.reason == "cancelled"
    try:
        os.fsync(streams.stdout_fd)
        os.fsync(streams.stderr_fd)
    except OSError:
        outcome.reason = "status_unavailable"
        outcome.failure_stage = "binding_failure"
    outcome.result_binding = None
    outcome.outer_status = None
    if not cancelled_before_terminal and outcome.provisional_orphan_result and outcome.reason in {
        None, "idle_timeout", "hard_deadline_exceeded",
    }:
        # These limits still stopped and reaped the child. Deferral alone
        # exposed them; retain the orphan's original framing diagnosis.
        if outcome.reason is None and _model_selection_rejected(
            streams.stream_path, streams.stderr_path, execution.returncode,
            binding.command["agy_version"] if binding.command["agy_version_observed"] else "",
            binding.command["max_seconds"],
            native=binding.command["provider_isolation"] == "native",
        ):
            outcome.reason = "model_selection_rejected"
            outcome.failure_stage = None
        else:
            outcome.reason = "invalid_envelope"
            outcome.failure_stage = "framing"
    if not cancelled_before_terminal and outcome.reason is None and streams.sizes["stdout"] == 0 and _model_selection_rejected(
        streams.stream_path, streams.stderr_path, execution.returncode,
        binding.command["agy_version"] if binding.command["agy_version_observed"] else "",
        binding.command["max_seconds"],
        native=binding.command["provider_isolation"] == "native",
    ):
        outcome.reason = "model_selection_rejected"
    reviewed_idle_partial = bool(
        not cancelled_before_terminal
        and not outcome.provisional_orphan_result
        and execution.idle_timeout_with_exited_provider
        and _has_reviewed_provider_timeout(
            streams.stderr_path,
            binding.command["agy_version"] if binding.command["agy_version_observed"] else "",
            binding.command["max_seconds"],
        )
    )
    # A deadline is a controller fact, not a reason to discard a
    # terminal report already emitted by the bounded provider.  Parse
    # that report for candidate/provenance evidence, but never let its
    # outer SUCCESS/ERROR/CANCELLED disposition publish past the
    # frozen deadline.  Cancellation and binding failures retain their
    # existing fail-closed precedence and do not enter this path.
    if not cancelled_before_terminal and (outcome.reason in {None, "hard_deadline_exceeded"} or reviewed_idle_partial):
        if outcome.reason in {None, "hard_deadline_exceeded"} and streams.sizes["stdout"] == 0:
            if outcome.reason is None:
                outcome.reason = (
                    _classify_stderr(
                        streams.stderr_path,
                        binding.command["agy_version"] if binding.command["agy_version_observed"] else "",
                        execution.returncode,
                        binding.command["max_seconds"],
                        native=binding.command["provider_isolation"] == "native",
                    )
                )
        elif outcome.reason in {None, "hard_deadline_exceeded"} or reviewed_idle_partial:
            try:
                if binding.schema_paths is None:
                    raise DispatchError("dispatch schema binding is unavailable")
                binding.schema_paths = _bound_schemas(binding.command, binding.state)
                outcome.result_binding, outcome.outer_status, outcome.failure_stage = _validate_terminal_envelope(
                    streams.stream_path, streams.envelope_path, binding.schema_paths[0], binding.schema_paths[1],
                    stage_dir=launch.stage_dir,
                )
                if outcome.failure_stage == "binding_failure":
                    outcome.reason = "status_unavailable"
                    outcome.result_binding = None
                elif _has_denied_actions(streams.stream_path):
                    # Keep hard-limit diagnostics and persist the reuse prohibition.
                    outcome.reason = "permission_required"
                    if outcome.limit_kind not in {"hard", "max-runtime"}:
                        outcome.limit_kind = None
                elif (
                    outcome.result_binding is None
                    and outcome.reason is None
                    and outcome.outer_status == "ERROR"
                    and outcome.failure_stage == "missing_structured_output"
                    and (terminal := _terminal_result(streams.stream_path, strict=True)) is not None
                    and terminal.get("finished_reason") == "print_timeout"
                    and _has_reviewed_provider_timeout(
                        streams.stderr_path, binding.command["agy_version"], binding.command["max_seconds"],
                    )
                ):
                    # AGY 1.5 reports its own print timeout as an ERROR result without a report.
                    outcome.reason, outcome.limit_kind, outcome.failure_stage = "provider_timeout", None, None
                elif outcome.result_binding is None and outcome.reason is None:
                    outcome.reason = "invalid_envelope"
                elif (
                    outcome.result_binding is not None
                    and outcome.reason != "hard_deadline_exceeded"
                    and _has_reviewed_provider_timeout(
                        streams.stderr_path, binding.command["agy_version"], binding.command["max_seconds"],
                    )
                ):
                    outcome.reason, outcome.limit_kind = "provider_timeout", None
                elif outcome.reason is None and outcome.outer_status == "ERROR":
                    outcome.reason = "provider_terminal_error"
                elif outcome.reason is None and outcome.outer_status == "CANCELLED":
                    outcome.reason = "provider_terminal_cancelled"
                elif outcome.reason is None and execution.returncode != 0:
                    outcome.reason = "agy_failed_unclassified"
            except DispatchError:
                # A binding/schema failure is security-relevant even
                # when a deadline was observed.  Do not preserve a
                # candidate whose terminal bytes could not be bound.
                outcome.reason = "status_unavailable"
                outcome.result_binding = None
                outcome.failure_stage = "binding_failure"
    outcome.boundary_failed = False
    if binding.command["workflow"] == "project":
        try:
            if WORKTREE._project_boundary(binding.command["workdir"]) != binding.state["project_boundary"]:
                raise DispatchError("project worktree boundary changed")
        except DispatchError:
            outcome.boundary_failed = True
            outcome.reason = "status_unavailable"
            outcome.result_binding = None
            outcome.failure_stage = "binding_failure"


def _begin_controller_completion(
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
    prior_handlers: dict[signal.Signals, Any],
) -> None:
    # One blocked completion snapshot linearizes terminal state against
    # late HUP/INT/TERM just as the foreground result publisher does.
    watched = tuple(prior_handlers)
    signal.pthread_sigmask(signal.SIG_BLOCK, watched)
    pending = signal.sigpending()
    completion_signal = _controller_completion_signal(watched, pending, execution.stop_signal)
    if completion_signal is not None:
        execution.stop_signal = completion_signal
        outcome.reason = "interrupted"
        outcome.result_binding = None
        outcome.failure_stage = None
    outcome.final_status, outcome.exit_code = _controller_terminal_status(outcome.reason, execution.stop_signal)
    outcome.result_path = str(streams.envelope_path) if outcome.reason is None or outcome.result_binding is not None else None
    outcome.cleanup_failed = False
    candidate_data.reconciliation_manifest_sha = None
    candidate_data.derived_selected_sha = None
    candidate_data.derived_selected_files = None
    candidate_data.derived_selected_trees = None
    candidate_data.derived_transmission_sha = None


def _cleanup_controller_stage(
    job: Path,
    binding: _ControllerBinding,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
) -> None:
    if launch.stage_dir is not None and launch.stage_dir.exists():
        try:
            if not outcome.source_guard_failed:
                if (
                    launch.narrow_source_snapshot is None
                    or WORKTREE._worktree_snapshot(binding.command["workdir"]) != launch.narrow_source_snapshot
                ):
                    raise DispatchError(
                        "source worktree changed while the narrow provider stage was active"
                    )
                mutations, op_manifest = WORKTREE._scan_stage_mutations(launch.stage_dir, cast(dict[str, Any], launch.scope), cast(list[dict[str, Any]], launch.selected_manifest))
                if outcome.result_binding is not None and not _declared_scoped_mutations_match(
                    streams.envelope_path, outcome.result_binding, mutations, launch.stage_dir,
                ):
                    raise DispatchError(
                        "worker files_changed does not match scoped stage mutations"
                    )
                if outcome.result_binding is not None and outcome.outer_status in {
                    "SUCCESS", "ERROR", "CANCELLED",
                }:
                    candidate_data.reconciliation_manifest_sha = WORKTREE._reconcile_stage_to_source(
                        binding.command["workdir"], launch.stage_dir, mutations, job,
                    )
                    if WORKTREE._build_selected_content_manifest(
                        binding.command["workdir"], cast(dict[str, Any], launch.scope),
                    ) != WORKTREE._build_selected_content_manifest(
                        launch.stage_dir, cast(dict[str, Any], launch.scope), is_stage=True,
                    ):
                        raise DispatchError(
                            "source reconciliation does not match the provider stage"
                        )
                else:
                    candidate_data.reconciliation_manifest_sha = WORKTREE._selected_content_digest([])
        except Exception:
            outcome.cleanup_failed = True
        finally:
            try:
                if launch.stage_identity is None:
                    raise DispatchError("stage cleanup identity is unavailable")
                WORKTREE._cleanup_stage(launch.stage_dir, launch.stage_identity)
            except (OSError, DispatchError):
                outcome.cleanup_failed = True
    try:
        cast(selectors.BaseSelector, streams.selector).close()
        os.close(streams.stdout_fd); streams.stdout_fd = -1
        os.close(streams.stderr_fd); streams.stderr_fd = -1
        _stage(binding.command, False)
        _load_bound_command(job, binding.state, stage_readonly=False)
        _bound_schemas(binding.command, binding.state)
        if binding.state["attempt_origin"] == "conversation-continue":
            _bound_verification(job, binding.state)
    except (OSError, DispatchError):
        outcome.cleanup_failed = True
    if outcome.cleanup_failed:
        outcome.reason, outcome.final_status = "status_unavailable", "failed"
        outcome.exit_code = EXIT_BY_REASON["status_unavailable"]
        outcome.result_path = None
        outcome.result_binding = None
        outcome.failure_stage = "binding_failure"


def _observe_controller_cancel(
    job: Path,
    binding: _ControllerBinding,
    outcome: _ControllerOutcome,
) -> None:
    # A SHA-approved cancellation may arrive after the last pipe-loop
    # observation (or after reaping) and before source or candidate work.
    # Observe it under the short ownership lock before selecting an
    # after-source proof or expensive reconciliation. The final transition reloads
    # again, but that later check is too late to keep a cheap cancel
    # from being delayed by a repository-controlled Git probe.
    with state_lock(job):
        current, current_raw, _current_sha = load_state(job)
        if (
            current["attempt"] != binding.state["attempt"]
            or current["controller_pid"] != os.getpid()
            or current["status"] in TERMINAL
        ):
            raise DispatchError("dispatch changed before terminal reconciliation")
        binding.state, binding.prior_raw = current, current_raw
        if current["cancel_requested"]:
            outcome.reason, outcome.final_status = "cancelled", "cancelled"
            outcome.exit_code = EXIT_BY_REASON["cancelled"]
            outcome.result_path = None
            outcome.result_binding = None
            outcome.failure_stage = None


def _reconcile_controller_candidate(
    binding: _ControllerBinding,
    launch: _ScopedLaunch,
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
) -> None:
    # This may use a bounded Git fallback.  The provider clock was
    # already frozen above, so keep this outside the final short state
    # lock: status/control readers can observe the frozen record and
    # reject stale extensions while reconciliation is in progress.
    # A local cancellation/interruption with no current terminal
    # report has no new worktree fact to reconcile.  Do not make the
    # cheap control wait for a candidate/worktree Git scan after the
    # provider group is already reaped.  A continuation's prior
    # candidate remains exact-bound and unreviewed; result/finalize
    # rebind it before use.  A provider-CANCELLED report still has a
    # current result_binding and retains the reconciliation path.
    skip_cancel_reconciliation = bool(
        outcome.source_guard_failed or outcome.reason in {"cancelled", "interrupted"}
        and outcome.result_binding is None
    )
    if skip_cancel_reconciliation:
        candidate_data.candidate_worktree = None
        candidate_data.reconciliation = {
            "worktree_reconciliation": "unavailable",
            "worktree_changes_present": None,
            "worktree_changed_since_dispatch": None,
        }
    else:
        candidate_data.candidate_worktree = (
            _state_worktree_snapshot(binding.state, binding.command["workdir"])
            if outcome.result_binding is not None else None
        )
        candidate_data.reconciliation = (
            _reconciliation_from_snapshot(
                candidate_data.candidate_worktree, binding.state["worktree_baseline"],
            )
            if outcome.result_binding is not None else _reconcile_worktree(
                binding.command["workdir"], binding.state["worktree_baseline"], state=binding.state,
            )
        )
    if (
        outcome.result_binding is not None
        and candidate_data.candidate_worktree is not None
        and candidate_data.reconciliation_manifest_sha is not None
        and launch.scope is not None
    ):
        try:
            derived_readable = WORKTREE._scan_readable_worktree(binding.command["workdir"])
            WORKTREE._validate_scope_against_worktree(
                launch.scope, binding.command["workdir"], derived_readable,
            )
            derived_selected = WORKTREE._build_selected_content_manifest(
                binding.command["workdir"], launch.scope,
            )
            candidate_data.derived_selected_sha = WORKTREE._selected_content_digest(derived_selected)
            candidate_data.derived_selected_files = sum(
                1 for item in derived_selected if item["kind"] == "file"
            )
            candidate_data.derived_selected_trees = sum(
                1 for item in derived_selected if item["kind"] == "directory"
            )
            candidate_data.derived_transmission_sha = _bound_transmission_sha256(
                binding.command, WORKTREE._canonical_digest(launch.scope),
                WORKTREE._manifest_digest(derived_readable), candidate_data.derived_selected_sha,
            )
        except Exception:
            candidate_data.derived_selected_sha = None
            candidate_data.derived_selected_files = None
            candidate_data.derived_selected_trees = None
            candidate_data.derived_transmission_sha = None


def _classify_controller_candidate(
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
    current: Mapping[str, Any],
) -> tuple[_ControllerOutcome, _CandidateDisposition]:
    outcome = dataclasses.replace(outcome)
    disposition = _CandidateDisposition()
    if current["cancel_requested"]:
        outcome.reason, outcome.final_status, outcome.exit_code = "cancelled", "cancelled", EXIT_BY_REASON["cancelled"]
        outcome.result_path = None
        outcome.result_binding = None
        outcome.failure_stage = None
    prior_candidate_exists = bool(
        current["attempt_origin"] == "conversation-continue"
        and current["candidate_recognized"]
    )
    prior_candidate_is_bound = bool(
        prior_candidate_exists
        and current["candidate_source"] != "none"
        and current["result_available"]
        and current["failure_stage"] is None
        and all(current[key] is not None for key in (
            "result_path", "result_sha256", "result_identity",
            "candidate_worktree_sha256", "candidate_worktree_entries",
        ))
    )
    # An old continuation candidate remains readable only when all
    # of its exact report/worktree bindings are still complete.
    # Keep an incomplete one as inaccessible forensic state and
    # fail closed; do not let a concurrent local cancel convert it
    # into an apparently usable candidate.
    disposition.preserve_candidate_forensics = bool(
        outcome.result_binding is None and prior_candidate_exists
    )
    disposition.terminal_snapshot_unavailable = bool(
        outcome.result_binding is not None
        and outcome.outer_status in {"SUCCESS", "ERROR", "CANCELLED"}
        and candidate_data.candidate_worktree is None
    )
    if disposition.terminal_snapshot_unavailable:
        # Keep the exact terminal report binding and its outer
        # provenance for forensics, but it is not a reviewable
        # candidate without a worktree binding.
        outcome.reason, outcome.final_status = "status_unavailable", "failed"
        outcome.exit_code = EXIT_BY_REASON["status_unavailable"]
        outcome.failure_stage = "binding_failure"
    if disposition.preserve_candidate_forensics and not prior_candidate_is_bound:
        outcome.reason, outcome.final_status = "status_unavailable", "failed"
        outcome.exit_code = EXIT_BY_REASON["status_unavailable"]
        outcome.failure_stage = "binding_failure"
    disposition.candidate_recognized = outcome.result_binding is not None or disposition.preserve_candidate_forensics
    disposition.candidate_unavailable = bool(
        disposition.candidate_recognized and outcome.failure_stage == "binding_failure"
    )
    disposition.candidate_source = (
        "provider_success" if outcome.result_binding is not None and outcome.outer_status == "SUCCESS"
        else "provider_error" if outcome.result_binding is not None and outcome.outer_status == "ERROR"
        else "provider_cancelled" if outcome.result_binding is not None and outcome.outer_status == "CANCELLED"
        else current["candidate_source"] if disposition.preserve_candidate_forensics
        else "none"
    )
    if outcome.failure_stage in {"schema_rejection", "binding_failure", "framing", "outer_status", "invalid_envelope"}:
        disposition.provider_terminal_status = "unknown"
    else:
        disposition.provider_terminal_status = (
            "success" if outcome.outer_status == "SUCCESS"
            else "error" if outcome.outer_status == "ERROR"
            else "cancelled" if outcome.outer_status in {"CANCELLED", "CANCELED"}
            else "unknown"
        )
    disposition.preserved_path = current["result_path"] if disposition.preserve_candidate_forensics else None
    disposition.preserved_sha = current["result_sha256"] if disposition.preserve_candidate_forensics else None
    disposition.preserved_identity = current["result_identity"] if disposition.preserve_candidate_forensics else None
    return outcome, disposition


def _controller_repair_lineage(
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
    current: Mapping[str, Any],
) -> dict[str, Any]:
    repair_lineage_updates: dict[str, Any] = {}
    if (outcome.result_binding is not None):
        repair_lineage_updates = {
            "repair_lineage_sha256": None,
            "repair_parent_result_sha256": None,
            "repair_parent_worktree_sha256": None,
            "repair_lineage_attempt": None,
        }
        if (
            candidate_data.derived_selected_sha is not None
            and candidate_data.derived_selected_files is not None
            and candidate_data.derived_selected_trees is not None
            and candidate_data.derived_transmission_sha is not None
        ):
            repair_lineage_updates.update({
                "selected_content_sha256": candidate_data.derived_selected_sha,
                "selected_file_count": candidate_data.derived_selected_files,
                "selected_tree_count": candidate_data.derived_selected_trees,
                "transmission_sha256": candidate_data.derived_transmission_sha,
            })
        if (
            current["allow_scoped_repair"]
            and candidate_data.candidate_worktree is not None
            and candidate_data.reconciliation_manifest_sha is not None
            and candidate_data.derived_selected_sha is not None
            and candidate_data.derived_selected_files is not None
            and candidate_data.derived_selected_trees is not None
            and candidate_data.derived_transmission_sha is not None
        ):
            parent_result_sha = (
                current["result_sha256"]
                if current["attempt_origin"] == "conversation-continue"
                else None
            )
            parent_worktree_sha = (
                current["candidate_worktree_sha256"]
                if current["attempt_origin"] == "conversation-continue"
                else current["worktree_baseline"]["sha256"]
            )
            repair_lineage_updates = {
                **repair_lineage_updates,
                "repair_parent_result_sha256": parent_result_sha,
                "repair_parent_worktree_sha256": parent_worktree_sha,
                "repair_lineage_attempt": current["attempt"],
                "repair_lineage_sha256": _compute_repair_lineage_sha256(
                    authority_sha256=current["repair_authority_sha256"],
                    attempt=current["attempt"],
                    parent_result_sha256=parent_result_sha,
                    parent_worktree_sha256=parent_worktree_sha,
                    reconciliation_sha256=candidate_data.reconciliation_manifest_sha,
                    result_sha256=outcome.result_binding[0],
                    candidate_worktree_sha256=candidate_data.candidate_worktree["sha256"],
                    selected_content_sha256=candidate_data.derived_selected_sha,
                    transmission_sha256=candidate_data.derived_transmission_sha,
                ),
            }
    return repair_lineage_updates


def _controller_terminal_updates(
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
    disposition: _CandidateDisposition,
    current: Mapping[str, Any],
    repair_lineage_updates: dict[str, Any],
) -> dict[str, Any]:
    updates = {
        "status": outcome.final_status,
        "reason": outcome.reason,
        "exit_code": outcome.exit_code,
        "controller_pid": None,
        "finished_epoch": time.time(),
        "elapsed_seconds": execution.elapsed,
        "agy_returncode": execution.returncode,
        "result_path": str(streams.envelope_path) if outcome.result_binding is not None else disposition.preserved_path,
        "result_sha256": outcome.result_binding[0] if outcome.result_binding is not None else disposition.preserved_sha,
        "result_identity": list(outcome.result_binding[1]) if outcome.result_binding is not None else disposition.preserved_identity,
        "candidate_recognized": disposition.candidate_recognized,
        "candidate_source": disposition.candidate_source,
        "provider_terminal_status": disposition.provider_terminal_status,
        # Preserve an exact old candidate after a binding failure for
        # forensics, but never claim it can still be read or reviewed.
        "result_available": disposition.candidate_recognized and not disposition.candidate_unavailable,
        "candidate_worktree_sha256": (
            candidate_data.candidate_worktree["sha256"] if candidate_data.candidate_worktree is not None
            else current["candidate_worktree_sha256"] if disposition.preserve_candidate_forensics else None
        ),
        "candidate_worktree_entries": (
            candidate_data.candidate_worktree["entries"] if candidate_data.candidate_worktree is not None
            else current["candidate_worktree_entries"] if disposition.preserve_candidate_forensics else None
        ),
        "candidate_worktree_path_facts": (
            candidate_data.candidate_worktree.get("path_facts") if candidate_data.candidate_worktree is not None
            else current["candidate_worktree_path_facts"] if disposition.preserve_candidate_forensics else None
        ),
        "driver_disposition": "unreviewed" if disposition.candidate_recognized else "not_applicable",
        "failure_stage": outcome.failure_stage,
        "last_activity": "terminal_received" if outcome.saw_terminal else current["last_activity"],
        "next_action": (
            "blocked" if disposition.candidate_unavailable else "driver_review"
        ) if disposition.candidate_recognized else (
            "none" if outcome.reason in {"selection_preflight_failed", "model_selection_rejected", "permission_required"} else
            "resume" if current["conversation_id"] else "blocked"
        ),
        "next_action_command": None,
        **(
            {
                "worktree_reconciliation": "unavailable",
                "worktree_changes_present": None,
                "worktree_changed_since_dispatch": None,
            }
            if disposition.terminal_snapshot_unavailable else candidate_data.reconciliation
        ),
        "resume_available": bool(
            current["conversation_id"] and not disposition.candidate_recognized
            and outcome.final_status == "failed"
            and outcome.reason not in {"selection_preflight_failed", "model_selection_rejected", "permission_required"}
        ),
        "continue_available": False,
        "remote_cancel_unverified": outcome.reason in {"cancelled", "interrupted"},
        "limit_kind": outcome.limit_kind,
        **repair_lineage_updates,
    }
    if current.get("provider_scope_path") is not None:
        updates["reconciliation_manifest_sha256"] = (
            current["reconciliation_manifest_sha256"] if disposition.preserve_candidate_forensics
            else candidate_data.reconciliation_manifest_sha
        )
    if outcome.result_binding is not None:
        # Continuation feedback remains bound audit evidence for
        # the prior candidate. A newly returned candidate starts
        # unreviewed, so it cannot inherit prior check evidence.
        updates.update({
            "check_summary": None,
            "check_counts": {
                "passed": 0, "failed": 0,
                "advisory": 0, "missing": 0,
            },
        })
    if outcome.boundary_failed or disposition.candidate_unavailable:
        updates.update({"phase": "blocked", "assurance": "blocked"})
    elif disposition.candidate_recognized:
        updates.update({
            "phase": (
                "repair-failed"
                if outcome.final_status == "failed" and current["attempt_origin"] == "conversation-continue"
                else "awaiting-verification"
            ),
            "assurance": "pending",
            "continue_available": bool(
                outcome.final_status in {"succeeded", "failed"}
                and outcome.reason not in {"selection_preflight_failed", "model_selection_rejected", "permission_required"}
                and disposition.candidate_source != "provider_cancelled"
                and current["conversation_id"]
                and current["attempt"] < current["max_cycles"]
                and execution.elapsed < _provider_max_seconds(current)
                and (
                    current.get("provider_scope_path") is None
                    or candidate_data.derived_transmission_sha
                    == current.get("initial_content_transmission_sha256")
                    or repair_lineage_updates.get(
                        "repair_lineage_sha256"
                    ) is not None
                    or (
                        outcome.result_binding is None
                        and (
                            current.get("transmission_sha256")
                            == current.get("initial_content_transmission_sha256")
                            or current.get("repair_lineage_sha256") is not None
                        )
                    )
                )
            ),
        })
    else:
        updates.update({
            "phase": (
                "repair-failed"
                if outcome.final_status == "failed" and current["attempt_origin"] == "conversation-continue"
                else "attempt-failed"
            ),
            "assurance": "pending",
            "continue_available": False,
        })
    return updates


def _publish_controller_terminal(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    outcome: _ControllerOutcome,
    candidate_data: _CandidateReconciliation,
) -> int:
    # An approved control may land after the last loop observation.  Bind
    # finalization to the current state under the same short transition lock.
    with state_lock(job):
        current, current_raw, _current_sha = load_state(job)
        if (
            current["attempt"] != binding.state["attempt"]
            or current["controller_pid"] != os.getpid()
            or current["status"] in TERMINAL
        ):
            raise DispatchError("dispatch changed before terminalization")
        # Persist the provider runtime measured before local terminal
        # parsing/reconciliation.  Those controller-local checks must
        # not silently consume a later repair/recovery budget.
        execution.elapsed = max(
            execution.elapsed,
            float(current["elapsed_seconds"]),
        )
        outcome, disposition = _classify_controller_candidate(outcome, candidate_data, current)
        repair_lineage_updates = _controller_repair_lineage(outcome, candidate_data, current)
        updates = _controller_terminal_updates(execution, streams, outcome, candidate_data, disposition, current, repair_lineage_updates)
        updates["source_checkout_guard"] = _checked_controller_source(current, execution)
        updates.update(_source_guard_veto({**current, **updates}))
        outcome.exit_code = updates["exit_code"]
        binding.state, binding.prior_raw, _sha = _transition_locked(job, current, current_raw, updates)
    return outcome.exit_code


def _cleanup_controller_resources(
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    streams: _ControllerStreams,
    launch: _ScopedLaunch,
) -> None:
    if execution.process is not None:
        # If an exception is leaving the provider loop, transfer
        # ownership to the outer recovery only after this exact group
        # termination/reap has succeeded.  It then freezes elapsed
        # time from this reap boundary.  If termination itself raises,
        # keep ``process`` live so the outer recovery retains the one
        # retry opportunity instead of assuming the group is gone.
        execution.returncode = _terminate_provider_process(
            execution.process, launch.contained_root,
            contained=launch.prepared_containment is not None,
        )
        execution.runtime_end_mono = time.monotonic()
        execution.process = None
    with contextlib.suppress(Exception):
        cast(selectors.BaseSelector, streams.selector).close()
    if streams.stdout_fd >= 0:
        os.close(streams.stdout_fd)
    if streams.stderr_fd >= 0:
        os.close(streams.stderr_fd)
    with contextlib.suppress(OSError):
        _stage(binding.command, False)


def _recover_controller_failure(
    job: Path,
    binding: _ControllerBinding,
    execution: _ProviderExecution,
    launch: _ScopedLaunch,
) -> int:
    # Once Popen succeeds, no ordinary controller exception may be left to
    # the cleanup-only finally path.  Reap first, freeze if the state still
    # belongs to this controller, then publish one fail-closed terminal
    # projection.  Pre-launch errors retain their narrower existing paths.
    if execution.process is not None:
        try:
            execution.returncode = _terminate_provider_process(
                execution.process, launch.contained_root,
                contained=launch.prepared_containment is not None,
            )
        except Exception:
            pass
        else:
            execution.process = None
            execution.runtime_end_mono = time.monotonic()
    frozen_elapsed = float(binding.state["elapsed_seconds"])
    if not execution.runtime_frozen:
        frozen_elapsed = float(binding.state["attempt_base_elapsed"])
        if execution.started_mono is not None:
            end = execution.runtime_end_mono if execution.runtime_end_mono is not None else time.monotonic()
            frozen_elapsed += max(0.0, end - execution.started_mono)
        try:
            binding.state, binding.prior_raw, _sha, _limit = _freeze_reaped_runtime(
                job, binding.state["attempt"], os.getpid(), frozen_elapsed,
            )
            execution.runtime_frozen = True
        except Exception:
            # The final state write below still clears an active controller
            # record; preserve the largest local elapsed observation if the
            # dedicated freeze CAS itself could not complete.
            pass
    _finish_controller_source(binding, execution)
    if (
        execution.process is None and execution.runtime_end_mono is not None
        and (
            _source_guard_reason({"source_checkout_guard": execution.source_guard_result or {}})
            or (execution.source_guard_result or {}).get("status") == "deferred"
        )
        and launch.stage_dir is not None and launch.stage_identity is not None
    ):
        # A failed source proof authorizes only disposal of the exact owned
        # stage after reap; never reconcile or remove a replacement path.
        with contextlib.suppress(OSError, DispatchError):
            WORKTREE._cleanup_stage(launch.stage_dir, launch.stage_identity)
    try:
        terminal, _raw, _sha = _terminalize_owned(
            job, binding.state, status="failed", reason="status_unavailable",
            exit_code=EXIT_BY_REASON["status_unavailable"],
            failure_stage="binding_failure", expected_controller_pid=os.getpid(),
            elapsed_seconds=frozen_elapsed, postlaunch_cancel=True, source_execution=execution,
        )
        # Terminal validation guarantees an integer exit code.
        assert terminal["exit_code"] is not None
        return int(terminal["exit_code"])
    except Exception:
        # A failed final write is still not allowed to disguise the
        # controller exception; the strict helper has already attempted
        # its unavailable fallback without holding a scan under the lock.
        return EXIT_BY_REASON["status_unavailable"]


def controller(job: Path, ownership_fd: int) -> int:
    binding = _ControllerBinding()
    execution = _ProviderExecution()
    launch = _ScopedLaunch()

    def interrupted(number: int, _frame: Any) -> None:
        _latch_controller_signal(execution, number)

    prior_handlers = {
        number: signal.getsignal(number)
        for number in (signal.SIGHUP, signal.SIGINT, signal.SIGTERM)
    }
    for number in prior_handlers:
        signal.signal(number, interrupted)
    # spawn() protects the fresh interpreter's import/handler interval. Deliver
    # pending lifecycle signals only after their controller owner exists; the
    # provider and local proof children must inherit these signals unblocked.
    signal.pthread_sigmask(signal.SIG_UNBLOCK, tuple(prior_handlers))
    try:
        with inherited_lifecycle_lock(job, ownership_fd):
            early_exit = _claim_controller_attempt(job, binding)
            if early_exit is not None:
                return early_exit
            early_exit = _bind_controller_inputs(job, binding)
            if early_exit is not None:
                return early_exit
            streams = _ControllerStreams(*_attempt_paths(job, binding.state["attempt"]))
            early_exit = _open_controller_artifacts(job, binding, execution, streams)
            if early_exit is not None:
                return early_exit
            _build_controller_argv(binding, launch)
            streams.selector = selectors.DefaultSelector()
            outcome = _ControllerOutcome()
            candidate_data = _CandidateReconciliation()
            try:
                _launch_controller_provider(job, binding, execution, streams, launch, outcome)
                _monitor_controller_provider(job, binding, execution, streams, launch, outcome)
                _reap_controller_provider(job, binding, execution, streams, launch, outcome)
                _observe_controller_cancel(job, binding, outcome)
                _observe_controller_terminal(binding, execution, streams, launch, outcome)
                _begin_controller_completion(execution, streams, outcome, candidate_data, prior_handlers)
                _observe_controller_cancel(job, binding, outcome)
                _finish_controller_source(binding, execution, report=outcome.result_binding is not None)
                source_reason = _source_guard_reason({"source_checkout_guard": execution.source_guard_result or {}})
                if source_reason is not None:
                    outcome.reason = source_reason
                    outcome.result_binding = None
                    outcome.result_path = None
                    outcome.final_status, outcome.exit_code = _controller_terminal_status(source_reason, execution.stop_signal)
                outcome.source_guard_failed = _source_guard_reason({"source_checkout_guard": execution.source_guard_result or {}}) is not None
                _cleanup_controller_stage(job, binding, streams, launch, outcome, candidate_data)
                _observe_controller_cancel(job, binding, outcome)
                _reconcile_controller_candidate(binding, launch, outcome, candidate_data)
                return _publish_controller_terminal(job, binding, execution, streams, outcome, candidate_data)
            finally:
                _cleanup_controller_resources(binding, execution, streams, launch)
    except Exception:
        if execution.process is None and execution.started_mono is None:
            raise
        return _recover_controller_failure(job, binding, execution, launch)
    finally:
        for number, handler in prior_handlers.items():
            signal.signal(number, handler)


def create_state(
    job: Path, origin: str, *, resume: bool, approve_sha: str | None = None,
    verification: dict[str, Any] | None = None,
    require_initial_choice: bool = False,
) -> tuple[DispatchState, str]:
    command, command_raw, command_info = load_command(job)
    if require_initial_choice:
        _require_initial_transmission_choice(command, origin)
    stage_sha, stage_info = _bound_stage(command, readonly=False)
    schema_bindings = _schema_bindings(command)
    path = job / STATE_NAME
    with state_lock(job):
        if resume:
            state, raw, sha = load_state(job)
            if approve_sha != sha:
                action = {
                    "conversation-resume": "resume",
                    "fresh-restart": "restart",
                    "conversation-continue": "continue",
                }[origin]
                raise _state_approval_error(state, sha, action)
            # Only an eligible relaunch settles a deferred candidate proof; a
            # rejected request neither scans nor writes. A cancelled repair is
            # never continue- or resume-eligible.
            if origin == "fresh-restart" and _restart_guard_accepts(state):
                state, raw, sha = _settle_deferred_source(job, state, raw, sha)
            # Reject a semantically unavailable recovery before probing its
            # launch inputs.  This keeps an approved stale-state diagnostic
            # actionable without treating the diagnostic itself as authority
            # to rebind a root for a recovery that cannot run.
            if origin != "conversation-continue":
                if state["status"] not in TERMINAL or state["status"] == "orphaned":
                    raise DispatchError("only a terminal unsuccessful dispatch can continue")
                if origin == "fresh-restart" and not _restart_guard_accepts(state):
                    raise DispatchError("dispatch fresh restart is unavailable")
                if origin == "conversation-resume" and not _resume_is_eligible(state, time.time()):
                    raise DispatchError("dispatch is not resume-eligible")
            command = _load_bound_command(job, state, stage_readonly=False)
            if _job_is_inside_worktree(job, command["workdir"]):
                raise DispatchError("dispatch job directory cannot be inside the target workdir")
            command, state = _bound_lifecycle_inputs(job, state, command)
            if not _selection_launch_is_authorized(_load_bound_selection(command, state)):
                raise DispatchError("dispatch selection has no current executable binding")
            if origin == "conversation-continue":
                if (
                    verification is None
                    or not _continue_is_eligible(state, time.time())
                ):
                    raise DispatchError("dispatch continuation is unavailable")
                _require_current_candidate_verification(verification, state)
                command, _candidate_raw = _bound_current_candidate(job, state)
            else:
                # The terminal/recovery predicates were checked above before
                # any launch-input probe; preserve that linearization here.
                pass
            if float(state["elapsed_seconds"]) >= _provider_max_seconds(state):
                raise DispatchError("dispatch max runtime is exhausted")
            if state["workflow"] != "legacy" and state["attempt"] >= state["max_cycles"]:
                raise DispatchError("dispatch max cycles is exhausted")
            conversation = state["conversation_id"] if origin == "conversation-resume" else None
            if origin == "conversation-continue":
                conversation = state["conversation_id"]
            verification_path: Path | None = None
            verification_sha: str | None = None
            verification_identity: tuple[int, int, int, int, int] | None = None
            if verification is not None:
                verification_path, verification_sha, verification_identity = _write_verification(
                    job, f"cycle-{state['attempt'] + 1:03d}", verification,
                )
            try:
                next_state = initial_state(
                    command, origin, state["attempt"] + 1,
                    command_sha=digest(command_raw), command_identity=command_info,
                    stage_sha=stage_sha, stage_identity=stage_info,
                    project_boundary=state["project_boundary"],
                    schema_bindings=schema_bindings,
                    explain_worktree_rejection=True,
                    repair_authority_state=(
                        state if origin == "conversation-continue" else None
                    ),
                )
                next_state["source_checkout_guard"] = {**state["source_checkout_guard"], "attempt": next_state["attempt"]}
                next_state["sequence"] = state["sequence"] + 1
                next_state["previous_state_sha256"] = sha
                next_state["conversation_id"] = conversation
                next_state["resume_available"] = conversation is not None
                next_state["attempt_base_elapsed"] = float(state["elapsed_seconds"])
                next_state["elapsed_seconds"] = float(state["elapsed_seconds"])
                next_state["hard_seconds"] = min(
                    _provider_max_seconds(state),
                    float(state["elapsed_seconds"]) + float(command["hard_seconds"]),
                )
                next_state["max_seconds"] = float(state["max_seconds"])
                next_state["self_verification_elapsed_seconds"] = float(
                    state["self_verification_elapsed_seconds"]
                )
                next_state["self_verification_run"] = state[
                    "self_verification_run"
                ]
                if state["workflow"] != "legacy":
                    next_state["phase"] = "repairing" if origin == "conversation-continue" else "dispatching"
                    next_state["check_summary"] = state["check_summary"]
                    next_state["check_counts"] = state["check_counts"]
                    next_state["last_success_path"] = state["result_path"] or state["last_success_path"]
                    next_state["last_success_sha256"] = state["result_sha256"] or state["last_success_sha256"]
                    next_state["last_success_identity"] = state["result_identity"] or state["last_success_identity"]
                    if origin == "conversation-continue":
                        state_fields: Mapping[str, object] = state
                        for key in (
                            "result_path", "result_sha256", "result_identity",
                            "candidate_recognized", "candidate_source", "result_available",
                            "candidate_worktree_sha256", "candidate_worktree_entries",
                            "candidate_worktree_path_facts",
                            "driver_disposition", "worktree_reconciliation",
                            "worktree_changes_present",
                            "worktree_changed_since_dispatch",
                        ):
                            next_state[key] = state_fields[key]
                        for key in (
                            "repair_lineage_sha256",
                            "repair_parent_result_sha256",
                            "repair_parent_worktree_sha256",
                            "repair_lineage_attempt",
                            "reconciliation_manifest_sha256",
                        ):
                            next_state[key] = state_fields[key]
                if verification_path is not None:
                    next_state.update({
                        "verification_path": str(verification_path),
                        "verification_sha256": verification_sha,
                        "verification_identity": list(cast(tuple[int, int, int, int, int], verification_identity)),
                        "check_summary": cast(dict[str, Any], verification)["summary"],
                        "check_counts": _verification_counts(cast(dict[str, Any], verification)),
                    })
                validated_next = validate_state(next_state)
                current, _info = read_regular(path, MAX_STATE_BYTES, "dispatch state")
                if current != raw:
                    raise DispatchError("dispatch state changed before continuation")
                _new_raw, new_sha = write_atomic(job, STATE_NAME, next_state)
                return validated_next, new_sha
            except Exception:
                _discard_new_verification(verification_path, verification_identity)
                raise
        if path.exists() or path.is_symlink():
            raise DispatchError("dispatch state already exists")
        if command.get("workflow") == "project" and _job_is_inside_worktree(job, command["workdir"]):
            raise DispatchError("dispatch job directory cannot be inside the target workdir")
        initial = initial_state(
            command, origin, 1, command_sha=digest(command_raw),
            command_identity=command_info, stage_sha=stage_sha, stage_identity=stage_info,
            schema_bindings=schema_bindings,
            explain_worktree_rejection=True,
        )
        state = validate_state(initial)
        _raw, sha = write_atomic(job, STATE_NAME, state)
        return state, sha


def spawn(
    job: Path, origin: str, *, resume: bool, foreground: bool,
    approve_sha: str | None = None, verification: dict[str, Any] | None = None,
    output_format: str = "json",
) -> int:
    parent_signal: int | None = None
    completion_blocked = False

    def latch(number: int, _frame: Any) -> None:
        nonlocal parent_signal
        if parent_signal is None:
            parent_signal = number

    watched = (signal.SIGHUP, signal.SIGINT, signal.SIGTERM)
    previous = {number: signal.getsignal(number) for number in watched}
    for number in watched:
        signal.signal(number, latch)
    controller_process: subprocess.Popen[bytes] | None = None
    try:
        with lifecycle_lock(job, blocking=False) as ownership_fd:
            state, _sha = create_state(
                job, origin, resume=resume, approve_sha=approve_sha,
                verification=verification,
                require_initial_choice=True,
            )
            if parent_signal is not None:
                _terminalize_queued_signal(job, parent_signal)
                return 128 + parent_signal
            bound_command = _load_bound_command(job, state, stage_readonly=False)
            controller_environment = _provider_environment(bound_command)
            controller_argv = [
                sys.executable, "-I", "-S", "-B", str(Path(__file__).resolve()),
                "controller", "--job-dir", str(job), "--ownership-fd", str(ownership_fd),
            ]
            # The child inherits the blocked mask across exec and installs its
            # handlers before unblocking. Restore the caller's exact mask even
            # if process creation fails; its pending signals then reach latch.
            spawn_mask = signal.pthread_sigmask(signal.SIG_BLOCK, watched)
            try:
                controller_process = subprocess.Popen(
                    controller_argv, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
                    stderr=subprocess.DEVNULL, start_new_session=True, close_fds=True,
                    pass_fds=(ownership_fd,),
                    env=controller_environment,
                )
            finally:
                signal.pthread_sigmask(signal.SIG_SETMASK, spawn_mask)
        deadline = time.monotonic() + 5.0
        forwarded = False
        while time.monotonic() < deadline:
            current, _raw, sha = read_state_snapshot(job)
            if parent_signal is not None and not forwarded:
                with contextlib.suppress(ProcessLookupError, PermissionError):
                    os.killpg(controller_process.pid, parent_signal)
                forwarded = True
            if current["status"] in TERMINAL:
                break
            if controller_process.poll() is not None:
                _terminalize_start_failure(job)
                raise DispatchError("controller exited before startup handshake")
            if (
                current["status"] in {"queued", "running", "cancel-requested"}
                and current["controller_pid"] == controller_process.pid
            ):
                break
            time.sleep(0.02)
        else:
            _terminate(controller_process)
            controller_process = None
            _terminalize_start_failure(job)
            raise DispatchError("controller startup handshake timed out")
        if parent_signal is not None and not foreground:
            try:
                controller_process.wait(timeout=5.0)
            except subprocess.TimeoutExpired:
                _terminate(controller_process)
            _recover_reaped_startup_signal(job, state, controller_process, parent_signal)
            return 128 + parent_signal
        if not foreground:
            print_control_status(current, sha, output_format, job=job)
            return 0
        while controller_process.poll() is None:
            if parent_signal is not None and not forwarded:
                with contextlib.suppress(ProcessLookupError, PermissionError):
                    os.killpg(controller_process.pid, parent_signal)
                forwarded = True
            time.sleep(0.02)
        result_code = controller_process.returncode
        # Linearize foreground completion: after this snapshot lifecycle signals stay
        # blocked until process exit, so success bytes cannot race a late cancellation.
        signal.pthread_sigmask(signal.SIG_BLOCK, watched)
        completion_blocked = True
        pending = signal.sigpending()
        completion_signal = parent_signal
        for candidate in watched:
            if candidate in pending or candidate == parent_signal:
                completion_signal = candidate
                break
        if completion_signal is not None:
            result_code = 128 + completion_signal
        final, _raw, sha = read_state_snapshot(job)
        if completion_signal is None and final["status"] == "succeeded" and final["result_path"] is not None:
            command_result(job)
        else:
            sys.stderr.buffer.write(canonical(public_status(final, sha, job=job)))
            sys.stderr.buffer.flush()
        return result_code
    finally:
        if not completion_blocked:
            for number, handler in previous.items():
                signal.signal(number, handler)


def _terminal_projection(
    state: Mapping[str, Any], *, status: str, reason: str, exit_code: int,
    failure_stage: str | None = None, remote_cancel_unverified: bool = False,
    allow_continue: bool = True,
) -> dict[str, Any]:
    """Project a local terminal side path without dropping a bound candidate.

    These paths run before normal provider terminalization, so they must not leave
    the transient dispatching/repairing UI fields behind.  A queued continuation
    already contains an exact, driver-owned candidate binding; returning that
    candidate to review is safer than treating a local controller failure as a
    provider repair result.
    """
    guard = dict(state["source_checkout_guard"])
    if guard["status"] == "armed":
        guard.update(status="unavailable", after_sha256=None)
    veto = _source_guard_veto({**state, "source_checkout_guard": guard})
    if veto:
        return {**veto, "source_checkout_guard": guard}
    candidate = bool(state["candidate_recognized"])
    candidate_unavailable = bool(candidate and failure_stage == "binding_failure")
    continuation = candidate and state["attempt_origin"] == "conversation-continue"
    can_continue = bool(
        continuation
        and state["candidate_source"] != "provider_cancelled"
        and state["conversation_id"]
        and state["attempt"] < state["max_cycles"]
        and float(state["elapsed_seconds"]) < _provider_max_seconds(state)
        and status == "failed"
        and reason not in {"permission_required", "selection_preflight_failed", "model_selection_rejected"}
        and allow_continue
        and not candidate_unavailable
    )
    updates: dict[str, Any] = {
        "status": status,
        "reason": reason,
        "exit_code": exit_code,
        "controller_pid": None,
        "finished_epoch": time.time(),
        "failure_stage": failure_stage,
        "provider_terminal_status": state.get("provider_terminal_status", "unknown"),
        # A local process signal is not evidence that the provider observed a
        # cancellation.  Startup/binding failures make no remote-cancel claim.
        "remote_cancel_unverified": remote_cancel_unverified,
        "continue_available": can_continue,
        "result_available": candidate and not candidate_unavailable,
        **_reconcile_worktree(state["workdir"], state["worktree_baseline"], state=state),
    }
    if candidate:
        updates.update({
            "resume_available": False,
            "driver_disposition": "unreviewed",
            "next_action": "blocked" if candidate_unavailable else "driver_review",
            "next_action_command": None,
        })
    else:
        resume_eligible = bool(
            status == "failed" and state["conversation_id"]
            and reason not in {"permission_required", "selection_preflight_failed", "model_selection_rejected"}
            and state["attempt_origin"] != "conversation-continue"
        )
        updates.update({
            "resume_available": resume_eligible,
            "driver_disposition": "not_applicable",
            "next_action": "resume" if resume_eligible else "blocked",
            "next_action_command": None,
        })
    updates.update({
        "phase": "blocked" if candidate_unavailable else ("awaiting-verification" if candidate else "attempt-failed"),
        "assurance": "blocked" if candidate_unavailable else "pending",
    })
    return updates


def _terminalize_owned(
    job: Path, state: Mapping[str, Any], *, status: str, reason: str, exit_code: int,
    failure_stage: str | None = None, expected_controller_pid: int | None = None,
    elapsed_seconds: float | None = None, postlaunch_cancel: bool = False,
    source_execution: _ProviderExecution | None = None,
) -> tuple[DispatchState, bytes, str]:
    """Publish one owned terminal state without holding a lock across scans."""
    projection_unavailable = False
    projection_state = state if source_execution is None else {
        **state, "source_checkout_guard": _checked_controller_source(state, source_execution),
    }
    try:
        primary = _terminal_projection(
            projection_state, status=status, reason=reason, exit_code=exit_code,
            failure_stage=failure_stage, allow_continue=False,
        )
        cancelled = _terminal_projection(
            projection_state, status="cancelled", reason="cancelled",
            exit_code=EXIT_BY_REASON["cancelled"],
            remote_cancel_unverified=postlaunch_cancel,
        )
    except Exception:
        # The no-scan fallback is deliberately built under the final state
        # lock below.  A continuation can have a previously bound candidate;
        # a failed reconciliation of this new attempt is not evidence that
        # the old binding disappeared.  Conversely, an incomplete/unavailable
        # prior binding must fail closed as status_unavailable rather than
        # combine ``cancelled`` with a schema-invalid inaccessible candidate.
        projection_unavailable = True
    with state_lock(job):
        current, raw, _sha = load_state(job)
        if current["status"] in TERMINAL:
            return current, raw, digest(raw)
        if (
            current["attempt"] != state["attempt"]
            or current["controller_pid"] != expected_controller_pid
        ):
            raise DispatchError("dispatch changed before terminalization")
        if projection_unavailable:
            # Do not re-run any candidate/worktree probe here: this is the
            # recovery path for a probe that has already failed.  The exact
            # old candidate is safe to preserve only when its stored bindings
            # are internally complete and still advertised as available.  Its
            # command paths will independently bind it again before result,
            # continue, or finalize is allowed.
            current_fields: Mapping[str, object] = current
            prior_candidate_is_bound = bool(
                current["attempt_origin"] == "conversation-continue"
                and current["candidate_recognized"]
                and current["candidate_source"] != "none"
                and current["result_available"]
                and current["failure_stage"] is None
                and all(current_fields[key] is not None for key in (
                    "result_path", "result_sha256", "result_identity",
                    "candidate_worktree_sha256", "candidate_worktree_entries",
                ))
            )
            candidate = bool(current["candidate_recognized"])
            # An ordinary post-launch cancellation has no candidate to
            # protect, so it remains cancelled.  Only an *incomplete* prior
            # candidate takes fail-closed precedence over cancellation: that
            # combination cannot truthfully expose a readable result.
            was_cancelled = bool(
                current["cancel_requested"]
                and (not candidate or prior_candidate_is_bound)
            )
            candidate_unavailable = bool(candidate and not prior_candidate_is_bound)
            updates: dict[str, Any] = {
                "status": "cancelled" if was_cancelled else "failed",
                "reason": "cancelled" if was_cancelled else "status_unavailable",
                "exit_code": (
                    EXIT_BY_REASON["cancelled"] if was_cancelled
                    else EXIT_BY_REASON["status_unavailable"]
                ),
                "controller_pid": None,
                "finished_epoch": time.time(),
                "continue_available": False,
                "result_available": bool(prior_candidate_is_bound),
                "worktree_reconciliation": "unavailable",
                "worktree_changes_present": None,
                "worktree_changed_since_dispatch": None,
                "next_action": "blocked" if candidate_unavailable else "none",
                "next_action_command": None,
                "resume_available": False,
                "driver_disposition": "unreviewed" if candidate else "not_applicable",
                # A successful local cancellation has no failed binding to
                # report.  An unbound/incomplete prior candidate is the one
                # case that must retain binding_failure fail-closed.
                "failure_stage": None if (was_cancelled or prior_candidate_is_bound) else "binding_failure",
                "remote_cancel_unverified": bool(was_cancelled and postlaunch_cancel),
                "provider_terminal_status": current.get("provider_terminal_status", "unknown"),
            }
            updates.update({
                "phase": "blocked" if candidate_unavailable else (
                    "awaiting-verification" if candidate else "attempt-failed"
                ),
                "assurance": "blocked" if candidate_unavailable else "pending",
            })
        else:
            updates = dict(cancelled if current["cancel_requested"] else primary)
        if elapsed_seconds is not None:
            updates.update({
                "elapsed_seconds": max(elapsed_seconds, float(current["elapsed_seconds"])),
                "started_epoch": None,
            })
        if source_execution is not None:
            updates["source_checkout_guard"] = _checked_controller_source(current, source_execution)
            updates["agy_returncode"] = source_execution.returncode
        updates.update(_source_guard_veto({**current, **updates}))
        return _transition_locked(job, current, raw, updates)


def _terminalize_start_failure(job: Path) -> None:
    with lifecycle_lock(job, blocking=True):
        with state_lock(job):
            state, raw, _sha = load_state(job)
            if state["status"] in TERMINAL:
                return
            _transition_locked(job, state, raw, _terminal_projection(
                state, status="failed", reason="status_unavailable",
                exit_code=EXIT_BY_REASON["status_unavailable"],
            ))


def _recover_reaped_startup_signal(
    job: Path, state: Mapping[str, Any], process: subprocess.Popen[bytes], number: int,
) -> None:
    """Finish only the reaped child's still-owned, unpublished provider attempt."""
    if process.returncode is None:
        raise DispatchError("controller has not been reaped")
    with lifecycle_lock(job, blocking=False):
        with state_lock(job):
            current, _raw, _sha = load_state(job)
            if current["attempt"] != state["attempt"]:
                raise DispatchError("dispatch changed before startup signal recovery")
            if current["status"] in TERMINAL:
                return
            current_fields: Mapping[str, object] = current
            if (
                current["controller_pid"] != process.pid
                or not (
                    current["status"] == "queued"
                    or (current["status"] == "cancel-requested" and current["cancel_requested"])
                )
                or any(current_fields[key] is not None for key in (
                    "started_epoch", "stream_path", "stderr_path", "provider_stage_path",
                    "provider_stage_identity", "provider_stage_manifest_sha256",
                ))
                or current["elapsed_seconds"] != current["attempt_base_elapsed"]
            ):
                raise DispatchError("dispatch has no owned prelaunch signal recovery")
        # Running/stream publication precedes provider Popen under the state
        # lock. The child is reaped and lifecycle ownership excludes a relaunch;
        # reconcile outside the state lock, retaining the terminalizer's CAS/veto.
        _terminalize_owned(
            job, current, status="cancelled", reason="interrupted", exit_code=128 + number,
            expected_controller_pid=process.pid,
        )


def _terminalize_queued_signal(job: Path, number: int) -> None:
    with state_lock(job):
        state, raw, _sha = load_state(job)
        if state["status"] != "queued":
            raise DispatchError("dispatch changed before queued cancellation")
        # A signal before a continuation controller starts must preserve the
        # prior candidate and send it back to driver review.  Its local terminal
        # state is failed (not provider-CANCELED), so a strict same-conversation
        # continue remains possible when its original budget still permits it.
        continuation = bool(
            state["candidate_recognized"]
            and state["attempt_origin"] == "conversation-continue"
        )
        _transition_locked(job, state, raw, _terminal_projection(
            state,
            status="failed" if continuation else "cancelled",
            reason="interrupted",
            exit_code=128 + number,
            remote_cancel_unverified=True,
        ))


def _recover_interrupted_self_verification(job: Path) -> tuple[DispatchState, bytes, str]:
    """Recover only while holding the lifecycle lock; never rerun a check."""
    with state_lock(job):
        state, raw, sha = load_state(job)
        if state.get("phase") != "self-verifying":
            return state, raw, sha
        remaining = SELF_VERIFICATION.remaining_seconds(
            state["max_seconds"], state["elapsed_seconds"],
            state["self_verification_elapsed_seconds"],
        )
        started = state["self_verification_started_epoch"]
        result_sha = state["result_sha256"]
        # validate_state proves both bindings for the self-verifying phase above.
        assert started is not None and result_sha is not None
        charge = min(remaining, max(0.0, time.time() - started))
        updates = {
            "phase": state["self_verification_return_phase"],
            "self_verification_started_epoch": None,
            "self_verification_return_phase": None,
            "self_verification_elapsed_seconds": state["self_verification_elapsed_seconds"] + charge,
            "verification_path": None, "verification_sha256": None,
            "verification_identity": None,
            "check_counts": _verification_counts(SELF_VERIFICATION.advisory_feedback(result_sha, [])),
            "check_summary": "Self-verification was interrupted; wall-clock time was conservatively charged.",
        }
        updates["continue_available"] = _continue_from_facts({**state, **updates}, time.time())
        return _transition_locked(job, state, raw, updates)


def command_status(job: Path, output_format: str = "json") -> int:
    state, _raw, sha = read_state_snapshot(job)
    if state.get("phase") == "self-verifying":
        try:
            with lifecycle_lock(job, blocking=False):
                state, _raw, sha = _recover_interrupted_self_verification(job)
        except DispatchError as exc:
            if str(exc) != "dispatch controller is active":
                raise
    if state["status"] in {"queued", "running", "cancel-requested"}:
        try:
            with lifecycle_lock(job, blocking=False):
                state, raw, sha = read_state_snapshot(job)
                if state["status"] in {"queued", "running", "cancel-requested"}:
                    state, raw, sha = transition(job, state, raw, _terminal_projection(
                        state, status="orphaned", reason="status_unavailable",
                        exit_code=EXIT_BY_REASON["status_unavailable"],
                    ))
        except DispatchError as exc:
            if str(exc) != "dispatch controller is active":
                raise
    print_control_status(state, sha, output_format, job=job)
    return 0


def command_wait(job: Path, after: str, timeout: float, output_format: str = "json") -> int:
    if SHA_RE.fullmatch(after) is None or not (0 <= timeout <= MAX_STATUS_WAIT):
        raise DispatchError("wait arguments are invalid")
    deadline = time.monotonic() + timeout
    while True:
        state, _raw, sha = read_state_snapshot(job)
        if state.get("phase") == "self-verifying":
            try:
                with lifecycle_lock(job, blocking=False):
                    state, _raw, sha = _recover_interrupted_self_verification(job)
            except DispatchError as exc:
                if str(exc) != "dispatch controller is active":
                    raise
        if sha != after or (state["status"] in TERMINAL and state.get("phase") != "self-verifying"):
            print_control_status(state, sha, output_format, job=job)
            return 0
        if time.monotonic() >= deadline:
            print_control_status(state, sha, output_format, job=job)
            return 0
        time.sleep(min(0.20, max(0.0, deadline - time.monotonic())))


def command_result(job: Path, output_format: str = "json") -> int:
    state, _raw, sha = read_state_snapshot(job)
    if state["candidate_recognized"]:
        if _is_active(state) or state.get("phase") == "self-verifying":
            raise DispatchError("dispatch result is unavailable while a repair is active")
        _command, candidate_raw = _bound_current_candidate(job, state)
        if output_format == "text":
            print_text_status(state, sha, job=job)
        else:
            sys.stdout.buffer.write(candidate_raw)
            sys.stdout.buffer.flush()
        return 0
    result_path = state["result_path"]
    result_sha = state["result_sha256"]
    result_identity = state["result_identity"]
    if (
        state["workflow"] == "project" and state["status"] in {"failed", "cancelled"}
        and state["phase"] == "completed" and state["assurance"] == "partially_verified"
        and result_path is None
    ):
        if state["source_checkout_guard"]["status"] == "deferred":
            raise DispatchError("dispatch result is unavailable until its source proof is settled")
        result_path = state["last_success_path"]
        result_sha = state["last_success_sha256"]
        result_identity = state["last_success_identity"]
    elif not state["result_available"]:
        raise DispatchError("dispatch result is unavailable")
    if result_path is None:
        raise DispatchError("dispatch has no preserved result")
    raw, info = read_regular(Path(result_path), 1024 * 1024, "dispatch result")
    if digest(raw) != result_sha or list(_identity(info)) != result_identity:
        raise DispatchError("dispatch result binding changed")
    command = _load_bound_command(job, state, stage_readonly=False)
    schema_paths = _schema_paths(command)
    if schema_paths is None:
        raise DispatchError("dispatch result schema is unavailable")
    schema_paths = _bound_schemas(command, state)
    validator = Path(__file__).with_name("validate-envelope.py")
    checked = [
        subprocess.run(
            [sys.executable, "-I", "-S", "-B", str(validator), str(schema), str(result_path)],
            stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
            check=False,
        )
        for schema in schema_paths
    ]
    if any(item.returncode != 0 for item in checked):
        raise DispatchError("dispatch result is no longer valid")
    if output_format == "text":
        print_text_status(state, sha, job=job)
    else:
        sys.stdout.buffer.write(raw)
        sys.stdout.buffer.flush()
    return 0


def _bound_self_verification_feedback(job: Path, state: Mapping[str, Any]) -> dict[str, Any]:
    """Read only the advisory artifact published for this candidate attempt."""
    expected = job / "continue-staged" / f"self-verify-{state['attempt']:03d}.json"
    if (
        not state.get("allow_self_verification")
        or state.get("self_verification_run") != state["attempt"]
        or state.get("phase") not in {"awaiting-verification", "repair-failed"}
        or state["verification_path"] != str(expected)
    ):
        raise DispatchError("current self-verification feedback is unavailable")
    raw, info = read_regular(expected, MAX_VERIFICATION_BYTES, "self-verification feedback", allowed_modes=(0o400,))
    if digest(raw) != state["verification_sha256"] or list(_identity(info)) != state["verification_identity"]:
        raise DispatchError("self-verification feedback binding changed")
    parent = expected.parent.lstat()
    if (not stat.S_ISDIR(parent.st_mode) or stat.S_ISLNK(parent.st_mode)
            or parent.st_uid != os.getuid() or stat.S_IMODE(parent.st_mode) != 0o700):
        raise DispatchError("verification staging directory changed")
    feedback = _validate_verification(parse_json(raw, "self-verification feedback"))
    _require_current_candidate_verification(feedback, state)
    if feedback["coverage"] != "partial" or feedback["diff_review_complete"]:
        raise DispatchError("self-verification feedback is not advisory")
    return feedback


def command_continue(
    job: Path, approve_sha: str,
    output_format: str = "json",
    use_self_verification: bool = False,
) -> int:
    if use_self_verification:
        with state_lock(job):
            state, _raw, sha = load_state(job)
            if sha != approve_sha:
                raise _state_approval_error(state, sha, "continue")
            verification = _bound_self_verification_feedback(job, state)
    else:
        verification = _verification_from_stdin()
    return spawn(
        job, "conversation-continue", resume=True, foreground=False,
        approve_sha=approve_sha,
        verification=verification, output_format=output_format,
    )


def command_finalize(
    job: Path, approve_sha: str,
    assurance: str, output_format: str = "json",
) -> int:
    if assurance not in {"verified", "partially_verified", "rejected", "blocked"}:
        raise DispatchError("project assurance is invalid")
    verification = _verification_from_stdin()
    with state_lock(job):
        state, raw, sha = load_state(job)
        if sha != approve_sha:
            raise _state_approval_error(state, sha, "finalize")
        if _finalize_is_eligible(state):
            state, raw, sha = _settle_deferred_source(job, state, raw, sha)
        command = _load_bound_command(job, state, stage_readonly=False)
        command, state = _bound_lifecycle_inputs(
            job, state, command, bind_terminal_candidate=True,
        )
        if not _finalize_is_eligible(state):
            raise DispatchError("dispatch finalization is stale or unavailable")
        if assurance == "verified" and _job_is_inside_worktree(job, command["workdir"]):
            raise DispatchError("verified finalization is unavailable for jobs inside the worktree")
        _require_current_candidate_verification(verification, state)
        if assurance == "verified" and not _verification_is_verified(verification, state["workflow"]):
            raise DispatchError("verified finalization requires complete driver evidence")
        command, _candidate_raw = _bound_current_candidate(job, state)
        counts = _verification_counts(verification)
        path: Path | None = None
        identity: tuple[int, int, int, int, int] | None = None
        try:
            path, verification_sha, identity = _write_verification(
                job, f"final-{state['cycle']:03d}", verification,
            )
            phase = "blocked" if assurance == "blocked" else "completed"
            state, _raw, sha = _transition_locked(job, state, raw, {
                "phase": phase,
                "assurance": assurance,
                "continue_available": False,
                "check_summary": verification["summary"],
                "check_counts": counts,
                "verification_path": str(path),
                "verification_sha256": verification_sha,
                "verification_identity": list(identity),
                "driver_disposition": assurance,
                "next_action": "none",
                "next_action_command": None,
            })
        except Exception:
            _discard_new_verification(path, identity)
            raise
    print_control_status(state, sha, output_format, job=job)
    return 0


def command_control(job: Path, action: str, approve_sha: str, seconds: float | None) -> int:
    if SHA_RE.fullmatch(approve_sha) is None:
        raise DispatchError("state approval is invalid")
    with state_lock(job):
        state, raw, sha = load_state(job)
        if sha != approve_sha:
            raise _state_approval_error(state, sha, action)
        now = time.time()
        if state["status"] not in {"queued", "running", "cancel-requested"}:
            raise DispatchError("state approval is stale or dispatch is terminal")
        if action == "cancel":
            if state["cancel_requested"]:
                raise DispatchError("cancel is already requested")
            updates = {"cancel_requested": True, "status": "cancel-requested"}
        else:
            assert seconds is not None
            if not _extend_is_eligible(state, now):
                raise DispatchError("deadline extension requires fresh progress before the hard deadline")
            if seconds <= 0 or state["hard_seconds"] + seconds > _provider_max_seconds(state):
                raise DispatchError("deadline extension exceeds max runtime")
            updates = {"hard_seconds": state["hard_seconds"] + seconds}
        state, _raw, sha = _transition_locked(
            job, state, raw, updates,
        )
    print_json(public_status(state, sha, job=job))
    return 0


def duration(text: str) -> float:
    match = re.fullmatch(r"([1-9][0-9]*)(s|m|h)", text)
    if match is None:
        raise argparse.ArgumentTypeError("duration must be a positive integer plus s, m, or h")
    factor = {"s": 1, "m": 60, "h": 3600}[match.group(2)]
    value = int(match.group(1)) * factor
    if value > 7 * 24 * 3600:
        raise argparse.ArgumentTypeError("duration is too large")
    return float(value)


def parser() -> Parser:
    result = Parser(prog="agy-dispatch")
    commands = result.add_subparsers(dest="command", required=True, parser_class=Parser)
    for name in ("run", "start", "resume", "restart", "continue", "status", "result", "verification-copy", "self-verify", "controller"):
        item = commands.add_parser(name)
        item.add_argument("--job-dir", required=True)
        if name == "controller":
            item.add_argument("--ownership-fd", required=True, type=int)
        if name in {"resume", "restart", "continue"}:
            item.add_argument("--approve-state-sha", required=name != "resume")
        if name in {"resume", "restart", "continue", "status", "result", "verification-copy"}:
            item.add_argument("--format", choices=("json", "text"), default="json")
        if name == "verification-copy":
            item.add_argument("--destination", required=True)
        if name == "continue":
            item.add_argument("--use-self-verification", action="store_true")
        if name == "self-verify":
            item.add_argument("--approve-state-sha", required=True)
            item.add_argument("--format", choices=("json", "text"), default="json")
    finalize = commands.add_parser("finalize")
    finalize.add_argument("--job-dir", required=True)
    finalize.add_argument("--approve-state-sha", required=True)
    finalize.add_argument("--assurance", required=True)
    finalize.add_argument("--format", choices=("json", "text"), default="json")
    wait = commands.add_parser("wait")
    wait.add_argument("--job-dir", required=True)
    wait.add_argument("--after-state-sha", required=True)
    wait.add_argument("--timeout", type=duration, default=60.0)
    wait.add_argument("--format", choices=("json", "text"), default="json")
    for name in ("cancel", "extend"):
        item = commands.add_parser(name)
        item.add_argument("--job-dir", required=True)
        item.add_argument("--approve-state-sha", required=True)
        if name == "extend":
            item.add_argument("--by", type=duration, required=True)
    return result


def main(argv: list[str] | None = None) -> int:
    arguments = list(sys.argv[1:] if argv is None else argv)
    if any(arg.partition("=")[0] == "--approve-migration-sha" for arg in arguments):
        raise DispatchError(
            f"--approve-migration-sha was removed after {LAST_DOCUMENTED_LEGACY_SCHEMA_RELEASE}; "
            "finish or discard the old job with the release that created it."
        )
    args = parser().parse_args(arguments)
    job = canonical_job(Path(args.job_dir))
    if args.command == "controller":
        if args.ownership_fd < 3:
            raise DispatchError("controller ownership descriptor is invalid")
        return controller(job, args.ownership_fd)
    if args.command == "run":
        return spawn(job, "initial", resume=False, foreground=True)
    if args.command == "start":
        return spawn(job, "initial", resume=False, foreground=False)
    if args.command == "resume":
        if args.approve_state_sha is None:
            raise _missing_state_approval(job, "resume")
        return spawn(
            job, "conversation-resume", resume=True, foreground=False,
            approve_sha=args.approve_state_sha,
            output_format=args.format,
        )
    if args.command == "restart":
        return spawn(
            job, "fresh-restart", resume=True, foreground=False,
            approve_sha=args.approve_state_sha,
            output_format=args.format,
        )
    if args.command == "continue":
        return command_continue(
            job, args.approve_state_sha, args.format,
            use_self_verification=args.use_self_verification,
        )
    if args.command == "status":
        return command_status(job, args.format)
    if args.command == "wait":
        return command_wait(job, args.after_state_sha, args.timeout, args.format)
    if args.command == "result":
        return command_result(job, args.format)
    if args.command == "verification-copy":
        return command_verification_copy(job, Path(args.destination), args.format)
    if args.command == "self-verify":
        try:
            return SELF_VERIFICATION.command_self_verify(
                VERIFICATION_API, job, args.approve_state_sha, args.format, containment=CONTAINMENT,
            )
        except (SELF_VERIFICATION.VerificationError, OSError) as exc:
            raise DispatchError("self-verification could not bind or execute the approved checks") from exc
    if args.command == "finalize":
        return command_finalize(
            job, args.approve_state_sha,
            args.assurance, args.format,
        )
    if args.command in {"cancel", "extend"}:
        return command_control(
            job, args.command, args.approve_state_sha,
            getattr(args, "by", None),
        )
    raise DispatchError("unknown command")


if __name__ == "__main__":
    try:
        raise SystemExit(main())
    except DispatchError as exc:
        print(f"agy-dispatch: {exc}", file=sys.stderr)
        if isinstance(exc, SourceGuardError):
            raise SystemExit(EXIT_BY_REASON[exc.reason])  # noqa: B904 -- preserve existing exception context and public diagnostics
        command_name = sys.argv[1] if len(sys.argv) > 1 else ""
        if command_name == "resume":
            raise SystemExit(EXIT_BY_REASON["resume_failed"])  # noqa: B904 -- preserve existing exception context and public diagnostics
        if command_name in {"status", "wait", "result", "verification-copy", "self-verify"}:
            raise SystemExit(EXIT_BY_REASON["status_unavailable"])  # noqa: B904 -- preserve existing exception context and public diagnostics
        raise SystemExit(64)  # noqa: B904 -- preserve existing exception context and public diagnostics
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall