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/evidence_receipt.py

View on GitHub
#!/usr/bin/env python3
"""Create and validate one private, unsigned Evidence Receipt.

The gate remains the sole authority for its outcome.  This module binds the gate's
structured handoff to caller-owned input hashes and publishes the resulting record;
it does not reproduce acceptance logic or inspect gate prose.
"""
from __future__ import annotations

import argparse
from contextlib import contextmanager
import hashlib
import json
import os
from pathlib import Path
import re
import secrets
import signal
import stat
import subprocess
import sys
from typing import Any, NoReturn, Sequence, Iterator

sys.dont_write_bytecode = True
RUNTIME_SCRIPTS = str(Path(__file__).resolve(strict=True).parent)
if RUNTIME_SCRIPTS not in sys.path:
    sys.path.insert(0, RUNTIME_SCRIPTS)

from model_selection import (  # noqa: E402
    CallerError as SelectionError,
    EvidenceUnavailable,
    child_environment,
    validate_child_environment_names,
    validate_selection_record,
    validate_selection_record_shape,
)


MAX_JSON_BYTES = 1024 * 1024
MAX_HANDOFF_BYTES = 4096
MAX_VERIFY_ENV_PAYLOAD = 256 * 1024
MAX_VERIFY_ARGV_ELEMENTS = 256
MAX_VERIFY_ARGV_ELEMENT_BYTES = 64 * 1024
MAX_VERIFY_ARGV_BYTES = 256 * 1024
SHA256_RE = re.compile(r"[0-9a-f]{64}\Z")
COMMIT_RE = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
LABEL_RE = re.compile(r"verify-[0-9]{3}\Z")
GATE_OUTCOMES = {
    0: "gate-passed",
    10: "scope-violation",
    11: "untrusted-worker-claim",
    12: "invalid-envelope",
    13: "expected-edits-missing",
    14: "driver-verification-failed",
    15: "worker-escalation",
}
VERDICTS = {
    0: "gate-passed",
    10: "rejected",
    11: "rejected",
    12: "rejected",
    13: "rejected",
    14: "rejected",
    15: "routed",
}
INTEGRITY_STATEMENT = (
    "Unsigned local record; schema-valid content can be rewritten and is not "
    "self-authenticating."
)


class UsageFailure(ValueError):
    pass


class ProtocolFailure(ValueError):
    pass


class SignalInterruption(ProtocolFailure):
    pass


class PublicationFailure(OSError):
    pass


class ValidationFailure(ValueError):
    pass


HANDLED_SIGNALS = (signal.SIGHUP, signal.SIGINT, signal.SIGTERM)


class SignalController:
    def __init__(self) -> None:
        self.previous: dict[int, Any] = {}
        self.active_group: int | None = None
        self.interrupted = False
        self.signal_number: int | None = None
        self.published_target: Path | None = None
        self.published_identity: tuple[int, int] | None = None
        self.published_descriptor = -1
        self.private_paths: set[Path] = set()

    def __enter__(self) -> "SignalController":
        for signum in HANDLED_SIGNALS:
            self.previous[signum] = signal.signal(signum, self._handle)
        return self

    def __exit__(self, _kind: Any, _value: Any, _traceback: Any) -> None:
        for signum, handler in self.previous.items():
            signal.signal(signum, handler)

    def _handle(self, signum: int, _frame: Any) -> None:
        if self.interrupted:
            return
        self.interrupted = True
        self.signal_number = signum
        if self.active_group is not None:
            try:
                os.killpg(self.active_group, signum)
            except ProcessLookupError:
                pass
        raise SignalInterruption("receipt operation interrupted")

    @contextmanager
    def blocked(self) -> Iterator[None]:
        previous_mask = signal.pthread_sigmask(signal.SIG_BLOCK, HANDLED_SIGNALS)
        try:
            yield
        finally:
            signal.pthread_sigmask(signal.SIG_SETMASK, previous_mask)

    def set_group(self, group: int | None) -> None:
        self.active_group = group

    def register_publication(
        self, target: Path, identity: tuple[int, int], descriptor: int
    ) -> None:
        self.published_target = target
        self.published_identity = identity
        self.published_descriptor = descriptor

    def clear_publication(self) -> None:
        if self.published_descriptor >= 0:
            os.close(self.published_descriptor)
            self.published_descriptor = -1
        self.published_target = None
        self.published_identity = None

    def register_private(self, path: Path) -> None:
        self.private_paths.add(path)

    def clear_private(self, path: Path) -> None:
        self.private_paths.discard(path)

    def remove_registered_publication(self) -> None:
        target = self.published_target
        identity = self.published_identity
        if target is None or identity is None:
            self.clear_publication()
            return
        try:
            metadata = target.lstat()
            if (metadata.st_dev, metadata.st_ino) == identity:
                target.unlink()
        except OSError:
            pass
        self.clear_publication()

    def cleanup_all(self) -> None:
        parents: set[Path] = set()
        if self.published_target is not None:
            parents.add(self.published_target.parent)
        self.remove_registered_publication()
        for path in tuple(self.private_paths):
            parents.add(path.parent)
            try:
                path.unlink()
            except OSError:
                pass
            self.clear_private(path)
        for parent in parents:
            try:
                descriptor = os.open(parent, os.O_RDONLY)
                try:
                    os.fsync(descriptor)
                finally:
                    os.close(descriptor)
            except OSError:
                pass


def interruption_checkpoint(_name: str) -> None:
    """No-op production hook monkeypatched by deterministic offline tests."""


def canonical_bytes(value: Any) -> bytes:
    return json.dumps(
        value, ensure_ascii=True, sort_keys=True, separators=(",", ":")
    ).encode("utf-8")


def published_bytes(value: Any) -> bytes:
    return canonical_bytes(value) + b"\n"


def sha256_bytes(value: bytes) -> str:
    return hashlib.sha256(value).hexdigest()


def reject_duplicates(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
    result: dict[str, Any] = {}
    for key, value in pairs:
        if key in result:
            raise ValidationFailure(f"duplicate key {key!r}")
        result[key] = value
    return result


def parse_json_bytes(payload: bytes, label: str) -> Any:
    if not payload or len(payload) > MAX_JSON_BYTES:
        raise ValidationFailure(f"{label} is empty or oversized")
    try:
        return json.loads(payload.decode("utf-8"), object_pairs_hook=reject_duplicates)
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise ValidationFailure(f"{label} is not valid unique-key UTF-8 JSON") from exc


def read_real_file(path: Path, label: str, maximum: int = MAX_JSON_BYTES) -> bytes:
    descriptor = -1
    try:
        descriptor = os.open(
            path,
            os.O_RDONLY
            | getattr(os, "O_NOFOLLOW", 0)
            | getattr(os, "O_NONBLOCK", 0),
        )
        metadata = os.fstat(descriptor)
    except (OSError, ValueError) as exc:
        if descriptor >= 0:
            os.close(descriptor)
        raise UsageFailure(f"{label} must be one existing real file") from exc
    if not stat.S_ISREG(metadata.st_mode):
        os.close(descriptor)
        raise UsageFailure(f"{label} must be one existing real file")
    if metadata.st_size > maximum:
        os.close(descriptor)
        raise UsageFailure(f"{label} exceeds the {maximum}-byte limit")
    try:
        chunks: list[bytes] = []
        total = 0
        while True:
            chunk = os.read(descriptor, min(1024 * 1024, maximum + 1 - total))
            if not chunk:
                break
            chunks.append(chunk)
            total += len(chunk)
            if total > maximum:
                raise UsageFailure(f"{label} exceeds the {maximum}-byte limit")
        payload = b"".join(chunks)
    except OSError as exc:
        raise UsageFailure(f"{label} could not be read") from exc
    finally:
        os.close(descriptor)
    return payload


def require_exact_fields(value: dict[str, Any], expected: set[str], label: str) -> None:
    if set(value) != expected:
        raise ValidationFailure(f"{label} fields are inconsistent")


def require_sha(value: Any, label: str) -> str:
    if not isinstance(value, str) or SHA256_RE.fullmatch(value) is None:
        raise ValidationFailure(f"{label} must be one lowercase SHA-256")
    return value


def require_unpadded_string(value: Any, label: str, maximum: int = 4096) -> str:
    if (
        not isinstance(value, str)
        or not value
        or value.strip() != value
        or len(value) > maximum
    ):
        raise ValidationFailure(f"{label} must be one bounded unpadded string")
    return value


SCHEMA_KEYS = {
    "$schema",
    "title",
    "type",
    "additionalProperties",
    "required",
    "properties",
    "items",
    "enum",
    "minLength",
    "maxLength",
    "minimum",
    "maximum",
    "minItems",
    "maxItems",
    "pattern",
    "oneOf",
}


def preflight_schema(schema: Any, location: str = "$") -> None:
    if not isinstance(schema, dict):
        raise ValidationFailure(f"schema node at {location} is not an object")
    unknown = set(schema) - SCHEMA_KEYS
    if unknown:
        raise ValidationFailure(f"schema has unsupported keys at {location}")
    properties = schema.get("properties", {})
    if not isinstance(properties, dict):
        raise ValidationFailure(f"schema properties at {location} are invalid")
    for key, child in properties.items():
        preflight_schema(child, f"{location}.{key}")
    if "items" in schema:
        preflight_schema(schema["items"], f"{location}[]")
    if "oneOf" in schema:
        alternatives = schema["oneOf"]
        if not isinstance(alternatives, list) or not alternatives:
            raise ValidationFailure(f"schema oneOf at {location} is invalid")
        for index, alternative in enumerate(alternatives):
            preflight_schema(alternative, f"{location}.oneOf[{index}]")


def schema_type_matches(value: Any, expected: str) -> bool:
    if expected == "object":
        return isinstance(value, dict)
    if expected == "array":
        return isinstance(value, list)
    if expected == "string":
        return isinstance(value, str)
    if expected == "boolean":
        return type(value) is bool
    if expected == "number":
        return type(value) in (int, float)
    if expected == "integer":
        return type(value) is int
    if expected == "null":
        return value is None
    raise ValidationFailure("schema contains an unknown type")


def validate_schema(value: Any, schema: dict[str, Any], location: str = "$") -> None:
    if "oneOf" in schema:
        accepted = 0
        for alternative in schema["oneOf"]:
            try:
                validate_schema(value, alternative, location)
            except ValidationFailure:
                continue
            accepted += 1
        if accepted != 1:
            raise ValidationFailure(f"{location} does not match exactly one schema alternative")
    expected_type = schema.get("type")
    if expected_type is not None and not schema_type_matches(value, expected_type):
        raise ValidationFailure(f"{location} has the wrong type")
    if "enum" in schema and value not in schema["enum"]:
        raise ValidationFailure(f"{location} has a forbidden value")
    if isinstance(value, str):
        if len(value) < schema.get("minLength", 0):
            raise ValidationFailure(f"{location} is too short")
        if len(value) > schema.get("maxLength", len(value)):
            raise ValidationFailure(f"{location} is too long")
        pattern = schema.get("pattern")
        if pattern is not None:
            if not isinstance(pattern, str):
                raise ValidationFailure("schema pattern is invalid")
            try:
                matched = re.search(pattern, value)
            except re.error as exc:
                raise ValidationFailure("schema pattern is invalid") from exc
            if matched is None:
                raise ValidationFailure(f"{location} does not match its pattern")
    if type(value) in (int, float):
        if value < schema.get("minimum", value):
            raise ValidationFailure(f"{location} is below minimum")
        if value > schema.get("maximum", value):
            raise ValidationFailure(f"{location} is above maximum")
    if isinstance(value, list) and "items" in schema:
        if len(value) < schema.get("minItems", 0):
            raise ValidationFailure(f"{location} has too few items")
        if len(value) > schema.get("maxItems", len(value)):
            raise ValidationFailure(f"{location} has too many items")
        for index, item in enumerate(value):
            validate_schema(item, schema["items"], f"{location}[{index}]")
    if isinstance(value, dict):
        required = set(schema.get("required", []))
        if required - set(value):
            raise ValidationFailure(f"{location} is missing required fields")
        properties = schema.get("properties", {})
        if schema.get("additionalProperties") is False and set(value) - set(properties):
            raise ValidationFailure(f"{location} has unexpected fields")
        for key, child in properties.items():
            if key in value:
                validate_schema(value[key], child, f"{location}.{key}")


def load_schema(schema_path: Path) -> dict[str, Any]:
    schema = parse_json_bytes(read_real_file(schema_path, "receipt schema"), "receipt schema")
    if not isinstance(schema, dict):
        raise ValidationFailure("receipt schema root must be an object")
    preflight_schema(schema)
    return schema


def validate_integrity(value: Any) -> None:
    if not isinstance(value, dict):
        raise ValidationFailure("integrity must be an object")
    require_exact_fields(value, {"signed", "tamper_evident", "statement"}, "integrity")
    if value != {
        "signed": False,
        "tamper_evident": False,
        "statement": INTEGRITY_STATEMENT,
    }:
        raise ValidationFailure("integrity must state the fixed unsigned limitation")


def validate_receipt(
    value: Any,
    schema: dict[str, Any],
) -> dict[str, Any]:
    validate_schema(value, schema)
    if not isinstance(value, dict):
        raise ValidationFailure("receipt must be one object")
    if type(value.get("schema_version")) is not int or value["schema_version"] != 2:
        raise ValidationFailure("schema_version must be integer 2")
    resolved_base = value.get("resolved_base")
    if not isinstance(resolved_base, str) or COMMIT_RE.fullmatch(resolved_base) is None:
        raise ValidationFailure("resolved_base is invalid")
    for key in (
        "envelope_sha256",
        "path_policy_sha256",
        "initial_candidate_state_sha256",
        "final_candidate_state_sha256",
    ):
        require_sha(value.get(key), key)
    gate_exit = value.get("gate_exit")
    if type(gate_exit) is not int or gate_exit not in GATE_OUTCOMES:
        raise ValidationFailure("gate_exit is not a receiptable gate result")
    if value.get("gate_outcome") != GATE_OUTCOMES[gate_exit]:
        raise ValidationFailure("gate outcome and exit are inconsistent")
    if value.get("verdict") != VERDICTS[gate_exit]:
        raise ValidationFailure("receipt verdict and exit are inconsistent")
    if value.get("gate_authority") != "qa-gate":
        raise ValidationFailure("gate authority is invalid")
    validate_integrity(value.get("integrity"))
    verifiers = value.get("verifiers")
    if not isinstance(verifiers, list) or not verifiers:
        raise ValidationFailure("receipt needs at least one verifier hash")
    for index, verifier in enumerate(verifiers, 1):
        if not isinstance(verifier, dict):
            raise ValidationFailure("verifier entry must be an object")
        require_exact_fields(verifier, {"label", "command_sha256"}, "verifier")
        if verifier.get("label") != f"verify-{index:03d}" or LABEL_RE.fullmatch(
            verifier.get("label", "")
        ) is None:
            raise ValidationFailure("verifier labels are not deterministic")
        require_sha(verifier.get("command_sha256"), "verifier command hash")
    selection = value.get("caller_selection")
    if selection is not None:
        try:
            # Semantic validation against the active G1 contract is performed on
            # publication input.  Receipt-only validation still enforces exact
            # selector shape below without re-probing agy.
            if not isinstance(selection, dict):
                raise SelectionError("selection record must be one object")
            validate_selection_record_shape(selection)
        except (SelectionError, EvidenceUnavailable) as exc:
            raise ValidationFailure("caller selection is not a valid G1 record") from exc
    return value


def load_selection(path: Path) -> dict[str, Any]:
    try:
        value = parse_json_bytes(
            read_real_file(path, "selection input"), "selection input"
        )
        if not isinstance(value, dict):
            raise SelectionError("selection record must be one object")
        validate_selection_record(value)
        return value
    except (
        SelectionError,
            EvidenceUnavailable,
        ValidationFailure,
    ) as exc:
        raise UsageFailure("selection input is not a current valid G1 record") from exc


def validate_target(target: Path, repo: Path) -> tuple[Path, str]:
    if not target.is_absolute() or "\n" in str(target) or "\r" in str(target):
        raise UsageFailure("--receipt must be one canonical absolute path")
    if target.exists() or target.is_symlink():
        raise UsageFailure("--receipt must name a new path and never overwrites")
    try:
        parent_text = os.path.abspath(str(target.parent))
        parent = target.parent.resolve(strict=True)
        repo_resolved = repo.resolve(strict=True)
        metadata = parent.lstat()
    except OSError as exc:
        raise UsageFailure("receipt parent and repository must exist") from exc
    if str(parent) != parent_text:
        raise UsageFailure("receipt parent must be a canonical real directory")
    if (
        not stat.S_ISDIR(metadata.st_mode)
        or stat.S_ISLNK(metadata.st_mode)
        or metadata.st_uid != os.geteuid()
        or stat.S_IMODE(metadata.st_mode) & 0o077
        or stat.S_IMODE(metadata.st_mode) & 0o700 != 0o700
    ):
        raise UsageFailure("receipt parent must be an owner-private real directory")
    try:
        if os.path.commonpath((str(parent / target.name), str(repo_resolved))) == str(
            repo_resolved
        ):
            raise UsageFailure("receipt must be outside the audited repository")
    except ValueError as exc:
        raise UsageFailure("receipt and repository paths are incompatible") from exc
    return parent, target.name


def require_private_parent(parent: Path) -> None:
    try:
        metadata = parent.lstat()
        canonical = parent.resolve(strict=True)
    except OSError as exc:
        raise PublicationFailure("receipt parent became unavailable") from exc
    if (
        canonical != parent
        or not stat.S_ISDIR(metadata.st_mode)
        or stat.S_ISLNK(metadata.st_mode)
        or metadata.st_uid != os.geteuid()
        or stat.S_IMODE(metadata.st_mode) & 0o077
        or stat.S_IMODE(metadata.st_mode) & 0o700 != 0o700
    ):
        raise PublicationFailure("receipt parent is no longer owner-private")


def private_file(
    parent: Path,
    stem: str,
    payload: bytes = b"",
    controller: SignalController | None = None,
    checkpoint: str | None = None,
) -> tuple[Path, int]:
    for counter in range(100):
        path = parent / f".{stem}.{os.getpid()}.{counter}"
        descriptor = -1
        try:
            if controller is None:
                descriptor = os.open(
                    path,
                    os.O_WRONLY
                    | os.O_CREAT
                    | os.O_EXCL
                    | getattr(os, "O_NOFOLLOW", 0),
                    0o600,
                )
                os.fchmod(descriptor, 0o600)
            else:
                with controller.blocked():
                    descriptor = os.open(
                        path,
                        os.O_WRONLY
                        | os.O_CREAT
                        | os.O_EXCL
                        | getattr(os, "O_NOFOLLOW", 0),
                        0o600,
                    )
                    os.fchmod(descriptor, 0o600)
                    controller.register_private(path)
        except FileExistsError:
            continue
        except SignalInterruption:
            if descriptor >= 0:
                os.close(descriptor)
            try:
                path.unlink()
            except OSError:
                pass
            if controller is not None:
                controller.clear_private(path)
            raise
        except OSError as exc:
            if descriptor >= 0:
                os.close(descriptor)
            try:
                path.unlink()
            except OSError:
                pass
            if controller is not None:
                controller.clear_private(path)
            raise PublicationFailure("could not create a private temporary file") from exc
        try:
            if checkpoint is not None:
                interruption_checkpoint(checkpoint)
            if payload:
                view = memoryview(payload)
                while view:
                    written = os.write(descriptor, view)
                    if written <= 0:
                        raise OSError("short private-file write")
                    view = view[written:]
            return path, descriptor
        except BaseException:
            os.close(descriptor)
            try:
                path.unlink()
            except OSError:
                pass
            if controller is not None:
                controller.clear_private(path)
            raise
    raise PublicationFailure("could not create a private temporary file")


def snapshot_file(
    source: Path, parent: Path, controller: SignalController
) -> tuple[Path, str]:
    try:
        metadata = source.lstat()
    except OSError as exc:
        raise UsageFailure("envelope must be one existing real file") from exc
    if stat.S_ISLNK(metadata.st_mode) or not stat.S_ISREG(metadata.st_mode):
        raise UsageFailure("envelope must be one existing real file")
    path, descriptor = private_file(
        parent,
        "agy-receipt-envelope",
        controller=controller,
        checkpoint="snapshot-created",
    )
    source_descriptor = -1
    digest = hashlib.sha256()
    try:
        source_descriptor = os.open(
            source,
            os.O_RDONLY
            | getattr(os, "O_NOFOLLOW", 0)
            | getattr(os, "O_NONBLOCK", 0),
        )
        if not stat.S_ISREG(os.fstat(source_descriptor).st_mode):
            raise OSError("envelope snapshot source is not regular")
        while True:
            chunk = os.read(source_descriptor, 1024 * 1024)
            if not chunk:
                break
            digest.update(chunk)
            view = memoryview(chunk)
            while view:
                written = os.write(descriptor, view)
                if written <= 0:
                    raise OSError("short envelope snapshot write")
                view = view[written:]
        interruption_checkpoint("snapshot-before-fsync")
        os.fsync(descriptor)
    except (OSError, SignalInterruption) as exc:
        try:
            path.unlink()
        except OSError:
            pass
        controller.clear_private(path)
        if isinstance(exc, SignalInterruption):
            raise
        raise UsageFailure("could not snapshot envelope") from exc
    finally:
        if source_descriptor >= 0:
            os.close(source_descriptor)
        os.close(descriptor)
    return path, digest.hexdigest()


def parse_handoff(payload: bytes) -> dict[str, Any]:
    if not payload or len(payload) > MAX_HANDOFF_BYTES:
        raise ProtocolFailure("gate evidence is missing or oversized")
    if not payload.endswith(b"\n") or payload.count(b"\n") != 1:
        raise ProtocolFailure("gate evidence must be exactly one JSON line")
    try:
        value = parse_json_bytes(payload[:-1], "gate evidence")
    except ValidationFailure as exc:
        raise ProtocolFailure("gate evidence is malformed") from exc
    fields = {
        "schema_version",
        "kind",
        "resolved_base",
        "envelope_sha256",
        "initial_candidate_state_sha256",
        "final_candidate_state_sha256",
        "gate_exit",
        "gate_outcome",
    }
    if not isinstance(value, dict) or set(value) != fields:
        raise ProtocolFailure("gate evidence fields are inconsistent")
    if type(value.get("schema_version")) is not int or value["schema_version"] != 1:
        raise ProtocolFailure("gate evidence version is invalid")
    if value.get("kind") != "agy-worker-gate-evidence":
        raise ProtocolFailure("gate evidence kind is invalid")
    if not isinstance(value.get("resolved_base"), str) or COMMIT_RE.fullmatch(
        value["resolved_base"]
    ) is None:
        raise ProtocolFailure("gate evidence base is invalid")
    for key in (
        "envelope_sha256",
        "initial_candidate_state_sha256",
        "final_candidate_state_sha256",
    ):
        try:
            require_sha(value.get(key), key)
        except ValidationFailure as exc:
            raise ProtocolFailure("gate evidence digest is invalid") from exc
    gate_exit = value.get("gate_exit")
    if type(gate_exit) is not int or gate_exit not in GATE_OUTCOMES:
        raise ProtocolFailure("gate evidence exit is unknown")
    if value.get("gate_outcome") != GATE_OUTCOMES[gate_exit]:
        raise ProtocolFailure("gate evidence outcome is inconsistent")
    return value


def publish_receipt(
    target: Path,
    parent: Path,
    value: dict[str, Any],
    schema: dict[str, Any],
    controller: SignalController | None = None,
) -> None:
    owns_controller = controller is None
    controller = controller or SignalController()
    require_private_parent(parent)
    payload = published_bytes(value)
    temporary, descriptor = private_file(
        parent,
        f"{target.name}.receipt",
        payload,
        controller=controller,
        checkpoint="publication-temp-created",
    )
    directory_fd = -1
    try:
        interruption_checkpoint("publication-before-file-fsync")
        os.fsync(descriptor)
        candidate_payload = read_real_file(temporary, "temporary receipt")
        candidate = parse_json_bytes(candidate_payload, "temporary receipt")
        validate_receipt(candidate, schema)
        if candidate != value or candidate_payload != payload:
            raise PublicationFailure("temporary receipt bytes changed")
        require_private_parent(parent)
        temporary_metadata = os.fstat(descriptor)
        published_identity = (
            temporary_metadata.st_dev,
            temporary_metadata.st_ino,
        )
        controller.register_publication(target, published_identity, descriptor)
        descriptor = -1
        interruption_checkpoint("publication-before-link")
        with controller.blocked():
            os.link(temporary, target, follow_symlinks=False)
            interruption_checkpoint("publication-after-link")
        with controller.blocked():
            directory_fd = os.open(parent, os.O_RDONLY)
        interruption_checkpoint("publication-before-first-parent-fsync")
        os.fsync(directory_fd)
        temporary.unlink()
        controller.clear_private(temporary)
        interruption_checkpoint("publication-before-second-parent-fsync")
        os.fsync(directory_fd)
        os.close(directory_fd)
        directory_fd = -1
    except (
        OSError,
        ValidationFailure,
        PublicationFailure,
        SignalInterruption,
    ) as exc:
        controller.remove_registered_publication()
        if directory_fd >= 0:
            os.close(directory_fd)
        if descriptor >= 0:
            os.close(descriptor)
        try:
            temporary.unlink()
        except OSError:
            pass
        controller.clear_private(temporary)
        try:
            cleanup_fd = os.open(parent, os.O_RDONLY)
            try:
                os.fsync(cleanup_fd)
            finally:
                os.close(cleanup_fd)
        except OSError:
            pass
        if isinstance(exc, SignalInterruption):
            raise
        raise PublicationFailure("receipt publication failed") from exc
    if owns_controller:
        controller.clear_publication()


class UsageParser(argparse.ArgumentParser):
    def error(self, message: str) -> NoReturn:
        self.print_usage(sys.stderr)
        self.exit(64, f"verify-job: {message}\n")


class VerifierAction(argparse.Action):
    """Preserve the caller's exact verifier ordering across public modes."""

    def __call__(
        self,
        parser: argparse.ArgumentParser,
        namespace: argparse.Namespace,
        values: str | Sequence[Any] | None,
        option_string: str | None = None,
    ) -> None:
        del parser, option_string
        verifiers = getattr(namespace, self.dest, None)
        if verifiers is None:
            verifiers = []
            setattr(namespace, self.dest, verifiers)
        verifiers.append((self.const, values))


SHELL_EXECUTABLES = frozenset({"sh", "bash", "zsh", "dash", "ksh", "fish"})
CREDENTIAL_ENV_RE = re.compile(
    r"(?:^|_)(?:AUTH|COOKIE|CREDENTIALS?|HOME|KEY|PASS(?:WORD|WD)?|SESSION|SECRET|TOKEN)(?:_|$)",
    re.IGNORECASE,
)
CREDENTIAL_ENV_EXACT = frozenset(
    {"DATABASE_URL", "GH_PAT", "MYSQL_PWD", "PGPASSWORD"}
)


def is_credential_environment_name(name: str) -> bool:
    normalized = name.upper()
    return (
        normalized == "HOME"
        or normalized in CREDENTIAL_ENV_EXACT
        or CREDENTIAL_ENV_RE.search(name) is not None
    )


def validate_verifier_argv(raw: str) -> list[str]:
    """Validate one strict canonical argv JSON value without shell interpretation."""

    try:
        encoded = raw.encode("utf-8")
        value = json.loads(raw)
    except (UnicodeEncodeError, json.JSONDecodeError) as exc:
        raise UsageFailure("--verify-argv requires a canonical JSON string array") from exc
    if canonical_bytes(value) != encoded:
        raise UsageFailure("--verify-argv requires canonical JSON")
    if not isinstance(value, list) or not (1 <= len(value) <= MAX_VERIFY_ARGV_ELEMENTS):
        raise UsageFailure("--verify-argv requires 1..256 string elements")
    total = 0
    for item in value:
        if not isinstance(item, str) or "\0" in item:
            raise UsageFailure("--verify-argv elements must be NUL-free strings")
        try:
            size = len(item.encode("utf-8"))
        except UnicodeEncodeError as exc:
            raise UsageFailure("--verify-argv elements must be UTF-8 strings") from exc
        if size > MAX_VERIFY_ARGV_ELEMENT_BYTES:
            raise UsageFailure("--verify-argv element is too large")
        total += size
    if not value[0]:
        raise UsageFailure("--verify-argv executable must be non-empty")
    if total > MAX_VERIFY_ARGV_BYTES:
        raise UsageFailure("--verify-argv aggregate is too large")

    executable = os.path.basename(value[0]).casefold()
    if executable in SHELL_EXECUTABLES:
        raise UsageFailure("--verify-argv cannot invoke a shell interpreter")
    if executable == "env":
        command: str | None = None
        options_done = False
        index = 1
        while index < len(value):
            item = value[index]
            if not options_done and item == "--":
                options_done = True
                index += 1
                continue
            if (
                not options_done
                and (
                    item == "--split-string"
                    or item.startswith("--split-string=")
                    or (
                        item.startswith("-")
                        and not item.startswith("--")
                        and "S" in item[1:]
                    )
                )
            ):
                raise UsageFailure("--verify-argv cannot use env split-string options")
            if not options_done and item in ("-i", "--ignore-environment", "-0", "--null", "--debug"):
                index += 1
                continue
            if not options_done and item in ("-u", "--unset", "-C", "--chdir"):
                index += 2
                if index > len(value):
                    raise UsageFailure("--verify-argv env option is incomplete")
                continue
            if not options_done and (
                item.startswith("--unset=")
                or item.startswith("--chdir=")
                or (item.startswith("-u") and len(item) > 2)
                or (item.startswith("-C") and len(item) > 2)
            ):
                index += 1
                continue
            if not options_done and item.startswith("-"):
                raise UsageFailure("--verify-argv env option is unsupported")
            if re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*=.*", item, re.DOTALL):
                index += 1
                continue
            command = item
            break
        if command is None:
            raise UsageFailure("--verify-argv env invocation has no executable")
        if os.path.basename(command).casefold() in SHELL_EXECUTABLES:
            raise UsageFailure("--verify-argv cannot invoke a shell interpreter through env")
    return value


def verifier_spec_hash(mode: str, value: str) -> str:
    spec: Any = validate_verifier_argv(value) if mode == "argv" else value
    return sha256_bytes(canonical_bytes({
        "domain": "agy-worker-verifier-spec-v1",
        "mode": mode,
        "spec": spec,
    }))


def one(parser: UsageParser, values: list[str] | None, flag: str, required: bool) -> str | None:
    if not values:
        if required:
            parser.error(f"{flag} is required")
        return None
    if len(values) != 1:
        parser.error(f"{flag} must be provided at most once")
    return values[0]


def build_parser() -> UsageParser:
    parser = UsageParser(prog="verify-job.sh", add_help=True)
    parser.add_argument("--receipt", action="append")
    parser.add_argument("--envelope", action="append")
    parser.add_argument("--repo", action="append")
    parser.add_argument("--base", action="append")
    parser.add_argument("--allow", action="append", default=[])
    parser.add_argument("--only", action="append", default=[])
    parser.set_defaults(verifier_specs=[])
    parser.add_argument(
        "--verify-argv", dest="verifier_specs", action=VerifierAction, const="argv"
    )
    parser.add_argument(
        "--verify-shell", dest="verifier_specs", action=VerifierAction, const="shell"
    )
    parser.add_argument(
        "--verify", dest="verifier_specs", action=VerifierAction, const="legacy"
    )
    parser.add_argument("--legacy-shell-verification", action="count", default=0)
    parser.add_argument("--acknowledge-verifier-network", action="count", default=0)
    parser.add_argument(
        "--acknowledge-verifier-credential-access", action="count", default=0
    )
    parser.add_argument("--verify-env", action="append", default=[])
    parser.add_argument("--verify-credential-env", action="append", default=[])
    parser.add_argument("--expect-edits", action="count", default=0)
    parser.add_argument("--selection", action="append")
    return parser


def sanitized_gate_environment() -> dict[str, str]:
    """Build the gate baseline without verifier-only opt-in values."""

    environment = child_environment([])
    environment.pop("HOME", None)
    return environment


def verifier_environment_payload(explicit_names: list[str]) -> bytes:
    """Encode present verifier-only values for the gate's private pipe."""

    records: list[bytes] = []
    for name in explicit_names:
        if name in os.environ:
            records.extend(
                (os.fsencode(name), b"\0", os.fsencode(os.environ[name]), b"\0")
            )
    payload = b"".join(records)
    if len(payload) > MAX_VERIFY_ENV_PAYLOAD:
        raise ProtocolFailure("verifier environment payload is too large")
    return payload


def run_gate(
    gate: Path,
    args: list[str],
    verify_environment: list[str],
    evidence_fd: int,
    controller: SignalController,
) -> int:
    child: subprocess.Popen[bytes] | None = None
    verify_read_fd = -1
    verify_write_fd = -1
    try:
        gate_environment = sanitized_gate_environment()
        evidence_token = secrets.token_hex(32)
        gate_environment["AGY_WORKER_INTERNAL_EVIDENCE_TOKEN"] = evidence_token
        gate_environment["AGY_WORKER_INTERNAL_PYTHON"] = str(
            Path(sys.executable).resolve(strict=True)
        )
        payload = verifier_environment_payload(verify_environment)
        verify_read_fd, verify_write_fd = os.pipe()
        child = subprocess.Popen(
            [
                "/bin/bash",
                str(gate),
                *args,
                "--evidence-fd",
                str(evidence_fd),
                "--evidence-token",
                evidence_token,
                "--verify-env-fd",
                str(verify_read_fd),
            ],
            stdin=subprocess.DEVNULL,
            pass_fds=(evidence_fd, verify_read_fd),
            start_new_session=True,
            env=gate_environment,
        )
        controller.set_group(child.pid)
        os.close(verify_read_fd)
        verify_read_fd = -1
        early_close = False
        try:
            while payload:
                written = os.write(verify_write_fd, payload)
                if written <= 0:
                    raise ProtocolFailure("gate environment write made no progress")
                payload = payload[written:]
        except BrokenPipeError:
            early_close = True
        os.close(verify_write_fd)
        verify_write_fd = -1
        if early_close:
            try:
                with controller.blocked():
                    gate_exit = child.wait(timeout=5)
                    controller.set_group(None)
            except subprocess.TimeoutExpired as exc:
                raise ProtocolFailure("gate closed environment input without exiting") from exc
        else:
            gate_exit = child.wait()
        return gate_exit
    except (SignalInterruption, OSError, ProtocolFailure) as exc:
        with controller.blocked():
            if child is not None:
                if controller.active_group == child.pid and child.returncode is None:
                    try:
                        os.killpg(child.pid, signal.SIGKILL)
                    except ProcessLookupError:
                        pass
                try:
                    child.wait(timeout=5)
                except (subprocess.TimeoutExpired, OSError):
                    pass
            controller.set_group(None)
        if isinstance(exc, OSError):
            raise ProtocolFailure("gate could not start") from exc
        raise
    finally:
        with controller.blocked():
            for descriptor in (verify_read_fd, verify_write_fd):
                if descriptor >= 0:
                    try:
                        os.close(descriptor)
                    except OSError:
                        pass
            controller.set_group(None)


def verify_main(
    argv: list[str], runtime_root: Path, controller: SignalController
) -> int:
    parser = build_parser()
    args = parser.parse_args(argv)
    receipt_text = one(parser, args.receipt, "--receipt", True)
    envelope_text = one(parser, args.envelope, "--envelope", True)
    repo_text = one(parser, args.repo, "--repo", True)
    base = one(parser, args.base, "--base", True)
    selection_text = one(parser, args.selection, "--selection", False)
    if args.expect_edits > 1:
        parser.error("--expect-edits must be provided at most once")
    for flag, count in (
        ("--legacy-shell-verification", args.legacy_shell_verification),
        ("--acknowledge-verifier-network", args.acknowledge_verifier_network),
        (
            "--acknowledge-verifier-credential-access",
            args.acknowledge_verifier_credential_access,
        ),
    ):
        if count > 1:
            parser.error(f"{flag} must be provided at most once")
    verifier_specs: list[tuple[str, str]] = args.verifier_specs
    if not verifier_specs:
        parser.error("at least one --verify-argv or explicitly acknowledged shell verifier is required")
    if len(verifier_specs) > 999:
        parser.error("at most 999 verifier commands are supported")
    if any(mode == "legacy" for mode, _value in verifier_specs) and not args.legacy_shell_verification:
        parser.error(
            "--verify is legacy shell verification; migrate to --verify-argv or add --legacy-shell-verification"
        )
    if args.legacy_shell_verification and not any(
        mode == "legacy" for mode, _value in verifier_specs
    ):
        parser.error("--legacy-shell-verification requires --verify")
    normalized_verifiers: list[tuple[str, str]] = []
    for mode, value in verifier_specs:
        public_mode = "shell" if mode == "legacy" else mode
        if public_mode == "argv":
            validate_verifier_argv(value)
        elif not value.strip():
            parser.error("shell verifier must be non-empty")
        normalized_verifiers.append((public_mode, value))
    shell_requested = any(mode == "shell" for mode, _value in normalized_verifiers)
    if shell_requested and not (
        args.acknowledge_verifier_network
        and args.acknowledge_verifier_credential_access
    ):
        parser.error(
            "shell verification requires --acknowledge-verifier-network and --acknowledge-verifier-credential-access"
        )
    try:
        verify_environment = validate_child_environment_names(args.verify_env)
        verify_credential_environment = validate_child_environment_names(
            args.verify_credential_env
        )
    except EvidenceUnavailable as exc:
        parser.error(str(exc))
    if any(is_credential_environment_name(name) for name in verify_environment):
        parser.error("credential-like names require --verify-credential-env")
    if any(
        not is_credential_environment_name(name)
        for name in verify_credential_environment
    ):
        parser.error("--verify-credential-env requires a credential-like name")
    if set(verify_environment) & set(verify_credential_environment):
        parser.error("verifier environment names must be unique across both classes")
    if verify_credential_environment and not args.acknowledge_verifier_credential_access:
        parser.error(
            "--verify-credential-env requires --acknowledge-verifier-credential-access"
        )
    all_verify_environment = sorted(
        verify_environment + verify_credential_environment
    )
    assert receipt_text and envelope_text and repo_text and base

    target = Path(receipt_text)
    repo = Path(repo_text)
    parent, _name = validate_target(target, repo)
    schema_path = runtime_root / "schemas/evidence-receipt.schema.json"
    schema = load_schema(schema_path)
    selection = load_selection(Path(selection_text)) if selection_text else None
    envelope_snapshot: Path | None = None
    handoff_path: Path | None = None
    write_fd = -1
    result: int | None = None
    try:
        envelope_snapshot, envelope_sha256 = snapshot_file(
            Path(envelope_text), parent, controller
        )
        handoff_path, write_fd = private_file(
            parent,
            "agy-receipt-handoff",
            controller=controller,
            checkpoint="handoff-created",
        )
        gate_args = [
            "--envelope",
            str(envelope_snapshot),
            "--repo",
            repo_text,
            "--base",
            base,
        ]
        for value in args.allow:
            gate_args += ["--allow", value]
        for value in args.only:
            gate_args += ["--only", value]
        if args.expect_edits:
            gate_args.append("--expect-edits")
        for mode, value in verifier_specs:
            gate_args += ["--verify" if mode == "legacy" else f"--verify-{mode}", value]
        if args.legacy_shell_verification:
            gate_args.append("--legacy-shell-verification")
        if args.acknowledge_verifier_network:
            gate_args.append("--acknowledge-verifier-network")
        if args.acknowledge_verifier_credential_access:
            gate_args.append("--acknowledge-verifier-credential-access")
        for value in verify_environment:
            gate_args += ["--verify-env", value]
        for value in verify_credential_environment:
            gate_args += ["--verify-credential-env", value]

        try:
            gate_rc = run_gate(
                runtime_root / "qa-gate.sh", gate_args, all_verify_environment,
                write_fd, controller
            )
        finally:
            if write_fd >= 0:
                os.close(write_fd)
                write_fd = -1
        if gate_rc == 64:
            result = 64
            return result
        if gate_rc not in GATE_OUTCOMES:
            raise ProtocolFailure("gate returned an internal or interrupted result")
        try:
            handoff_payload = read_real_file(
                handoff_path, "gate evidence", MAX_HANDOFF_BYTES
            )
        except UsageFailure as exc:
            raise ProtocolFailure("gate evidence is unavailable") from exc
        handoff = parse_handoff(handoff_payload)
        if handoff["gate_exit"] != gate_rc:
            raise ProtocolFailure("gate process exit and evidence exit differ")
        if handoff["resolved_base"] != base:
            raise ProtocolFailure("gate resolved a different base")
        if handoff["envelope_sha256"] != envelope_sha256:
            raise ProtocolFailure("gate validated a different envelope snapshot")

        policy = {
            "allow": args.allow,
            "only": args.only,
            "expect_edits": bool(args.expect_edits),
            "verify_environment": verify_environment,
            "verify_credential_environment": verify_credential_environment,
            "verifier_modes": [mode for mode, _value in normalized_verifiers],
            "acknowledgements": {
                "network": bool(args.acknowledge_verifier_network),
                "credential_access": bool(
                    args.acknowledge_verifier_credential_access
                ),
                "legacy_shell": bool(args.legacy_shell_verification),
            },
        }
        receipt: dict[str, Any] = {
            "schema_version": 2,
            "kind": "agy-worker-evidence-receipt",
            "gate_authority": "qa-gate",
            "resolved_base": handoff["resolved_base"],
            "envelope_sha256": handoff["envelope_sha256"],
            "path_policy_sha256": sha256_bytes(canonical_bytes(policy)),
            "verifiers": [
                {
                    "label": f"verify-{index:03d}",
                    "command_sha256": verifier_spec_hash(mode, value),
                }
                for index, (mode, value) in enumerate(normalized_verifiers, 1)
            ],
            "initial_candidate_state_sha256": handoff[
                "initial_candidate_state_sha256"
            ],
            "final_candidate_state_sha256": handoff[
                "final_candidate_state_sha256"
            ],
            "gate_exit": gate_rc,
            "gate_outcome": handoff["gate_outcome"],
            "verdict": VERDICTS[gate_rc],
            "integrity": {
                "signed": False,
                "tamper_evident": False,
                "statement": INTEGRITY_STATEMENT,
            },
        }
        if selection is not None:
            receipt["caller_selection"] = selection
        validate_receipt(receipt, schema)
        publish_receipt(
            target,
            parent,
            receipt,
            schema,
            controller,
        )
        result = gate_rc
    except SignalInterruption:
        controller.remove_registered_publication()
        raise
    finally:
        interruption_checkpoint("wrapper-cleanup-start")
        if write_fd >= 0:
            os.close(write_fd)
        for private_path in (envelope_snapshot, handoff_path):
            if private_path is not None:
                try:
                    private_path.unlink(missing_ok=True)
                except OSError:
                    pass
                controller.clear_private(private_path)
        try:
            cleanup_fd = os.open(parent, os.O_RDONLY)
            try:
                interruption_checkpoint("wrapper-cleanup-parent-fsync")
                os.fsync(cleanup_fd)
            finally:
                os.close(cleanup_fd)
        except OSError:
            pass
    if result is None:
        raise ProtocolFailure("gate result was not established")
    controller.clear_publication()
    return result


def validate_main(argv: list[str], runtime_root: Path) -> int:
    parser = UsageParser(prog="evidence-receipt-validator")
    parser.add_argument("--receipt", action="append")
    parser.add_argument("--envelope", action="append")
    parser.add_argument("--selection", action="append")
    parser.add_argument("--initial-state-digest", action="append")
    parser.add_argument("--final-state-digest", action="append")
    parsed = parser.parse_args(argv)
    receipt_text = one(parser, parsed.receipt, "--receipt", True)
    envelope_text = one(parser, parsed.envelope, "--envelope", False)
    selection_text = one(parser, parsed.selection, "--selection", False)
    initial_digest = one(
        parser, parsed.initial_state_digest, "--initial-state-digest", False
    )
    final_digest = one(
        parser, parsed.final_state_digest, "--final-state-digest", False
    )
    assert receipt_text
    schema = load_schema(runtime_root / "schemas/evidence-receipt.schema.json")
    value = parse_json_bytes(
        read_real_file(Path(receipt_text), "receipt"), "receipt"
    )
    receipt = validate_receipt(value, schema)
    if envelope_text:
        payload = read_real_file(Path(envelope_text), "bound envelope")
        if sha256_bytes(payload) != receipt["envelope_sha256"]:
            raise ValidationFailure("bound envelope digest does not match receipt")
    if selection_text:
        selection = load_selection(Path(selection_text))
        if receipt.get("caller_selection") != selection:
            raise ValidationFailure("bound selection does not match receipt")
    if initial_digest:
        require_sha(initial_digest, "bound initial state digest")
        if receipt["initial_candidate_state_sha256"] != initial_digest:
            raise ValidationFailure("bound initial state digest does not match receipt")
    if final_digest:
        require_sha(final_digest, "bound final state digest")
        if receipt["final_candidate_state_sha256"] != final_digest:
            raise ValidationFailure("bound final state digest does not match receipt")
    return 0


def execute_verifier_main(argv: list[str]) -> int:
    """Internal no-shell executor used by qa-gate's sanitized child."""

    if argv != ["argv"]:
        return 64
    payload = sys.stdin.buffer.read(MAX_VERIFY_ARGV_BYTES * 2 + 1)
    if len(payload) > MAX_VERIFY_ARGV_BYTES * 2:
        return 64
    try:
        raw = payload.decode("utf-8")
        command = validate_verifier_argv(raw)
    except (UnicodeDecodeError, UsageFailure):
        return 64
    try:
        os.execvpe(command[0], command, dict(os.environ))
    except OSError:
        return 126
    return 126


def validate_verifier_main(argv: list[str]) -> int:
    if argv != ["argv"]:
        return 64
    payload = sys.stdin.buffer.read(MAX_VERIFY_ARGV_BYTES * 2 + 1)
    if len(payload) > MAX_VERIFY_ARGV_BYTES * 2:
        return 64
    try:
        validate_verifier_argv(payload.decode("utf-8"))
    except (UnicodeDecodeError, UsageFailure):
        return 64
    return 0


def main(argv: list[str] | None = None) -> int:
    arguments = list(sys.argv[1:] if argv is None else argv)
    runtime_root = Path(__file__).resolve().parent.parent
    if not arguments or arguments[0] not in (
        "verify", "validate", "execute-verifier", "validate-verifier"
    ):
        print(
            "usage: evidence_receipt.py verify|validate|execute-verifier|validate-verifier ...",
            file=sys.stderr,
        )
        return 64
    command = arguments.pop(0)
    if command == "execute-verifier":
        return execute_verifier_main(arguments)
    if command == "validate-verifier":
        return validate_verifier_main(arguments)
    try:
        if command == "verify":
            with SignalController() as controller:
                try:
                    return verify_main(arguments, runtime_root, controller)
                except SignalInterruption:
                    controller.cleanup_all()
                    raise
        return validate_main(arguments, runtime_root)
    except UsageFailure as exc:
        print(f"verify-job: invalid input - {exc}", file=sys.stderr)
        return 64
    except ProtocolFailure:
        print("verify-job: gate evidence protocol failed", file=sys.stderr)
        return 70
    except ValidationFailure as exc:
        if command == "validate":
            print(f"evidence receipt invalid: {exc}", file=sys.stderr)
            return 1
        print("verify-job: receipt publication failed", file=sys.stderr)
        return 74
    except PublicationFailure:
        print("verify-job: receipt publication failed", file=sys.stderr)
        return 74


if __name__ == "__main__":
    raise SystemExit(main())
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