engineering-platform 2.2.0__py3-none-any.whl

engineering_platform/pr_check_repair.py

@@ -0,0 +1,276 @@
+"""One-shot, evidence-gated repair for a human-authored pull request.
+
+This is deliberately separate from the managed execution lifecycle.  It never
+claims an Inbox item, resumes a transaction, merges a pull request, or creates
+a pull request.  It may only add one host-owned commit to the exact current
+head of an eligible same-repository pull request.
+"""
+
+from __future__ import annotations
+
+import argparse
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import re
+import tempfile
+
+from .central_database import capacity_reserve_from_environment
+from .worktree_tooling import WorktreeToolingError, prepare as prepare_worktree_tooling
+from .codex_capacity import read_remaining_percent
+from .provider_readiness import failures as provider_readiness_failures
+from .providers import CodexCliProvider, GitHubProvider, GitProvider
+
+
+FAILED_CONCLUSIONS = frozenset({"ACTION_REQUIRED", "CANCELLED", "FAILURE", "STARTUP_FAILURE", "TIMED_OUT"})
+SUCCESSFUL_CONCLUSIONS = frozenset({"NEUTRAL", "SKIPPED", "SUCCESS"})
+STATE_DIRECTORY = Path(".engineering") / "status" / "pr-check-repairs"
+
+
+class PullRequestCheckRepairError(RuntimeError):
+    """The request is unsafe, stale, or cannot be admitted."""
+
+
+def _repository(root: Path) -> str:
+    remote = GitProvider().execute(root, "git", "remote", "get-url", "origin")
+    match = re.search(r"github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?$", remote.stdout.strip()) if remote.returncode == 0 else None
+    if not match:
+        raise PullRequestCheckRepairError("pr_check_repair_unavailable")
+    return f"{match.group(1)}/{match.group(2)}"
+
+
+def _state_path(root: Path, number: int, sha: str) -> Path:
+    return root / STATE_DIRECTORY / f"{number}-{sha}.json"
+
+
+def _read_state(root: Path, number: int, sha: str) -> dict[str, object] | None:
+    try:
+        value = json.loads(_state_path(root, number, sha).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def attempted(root: Path, number: int, sha: object) -> bool:
+    """Whether this exact remote head already consumed its one repair action."""
+    return isinstance(sha, str) and bool(re.fullmatch(r"[0-9a-f]{40}", sha)) and _read_state(root, number, sha) is not None
+
+
+def failed_check_names(checks: object) -> list[str]:
+    """Return bounded terminal failures from GitHub's check-rollup shape."""
+    if not isinstance(checks, list):
+        return []
+    return [
+        str(check.get("name") or check.get("context") or "required check").strip()[:160]
+        for check in checks if isinstance(check, dict)
+        and str(check.get("conclusion") or check.get("state") or "").upper() in FAILED_CONCLUSIONS
+    ]
+
+
+def _write_state(root: Path, number: int, sha: str, payload: dict[str, object]) -> None:
+    path = _state_path(root, number, sha)
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(prefix=".pr-check-repair-", suffix=".json", dir=path.parent)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(payload, handle, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        Path(temporary).unlink(missing_ok=True)
+
+
+def check_summary(checks: object) -> tuple[list[str], bool]:
+    """Return failed names and whether the GitHub check projection is stable."""
+    if not isinstance(checks, list) or not checks:
+        return [], False
+    failed = failed_check_names(checks)
+    terminal = True
+    for check in checks:
+        if not isinstance(check, dict):
+            return [], False
+        conclusion = str(check.get("conclusion") or check.get("state") or "").upper()
+        status = str(check.get("status") or "").upper()
+        if conclusion not in FAILED_CONCLUSIONS | SUCCESSFUL_CONCLUSIONS or (status and status != "COMPLETED"):
+            terminal = False
+    return failed, terminal
+
+
+def repair_state(root: Path, number: int, sha: object) -> str | None:
+    """Return the durable repair state for this head, including its repair commit."""
+    if not isinstance(sha, str) or not re.fullmatch(r"[0-9a-f]{40}", sha):
+        return None
+    direct = _read_state(root, number, sha)
+    if direct is not None:
+        status = direct.get("status")
+        return str(status) if isinstance(status, str) else None
+    try:
+        candidates = (root / STATE_DIRECTORY).glob(f"{number}-*.json")
+    except OSError:
+        return None
+    for candidate in candidates:
+        try:
+            value = json.loads(candidate.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(value, dict) and value.get("commit_sha") == sha:
+            status = value.get("status")
+            return str(status) if isinstance(status, str) else None
+    return None
+
+
+def current_evidence(root: Path, number: int) -> dict[str, object]:
+    """Read the exact mutable PR evidence used for admission and projection."""
+    if isinstance(number, bool) or number < 1:
+        raise PullRequestCheckRepairError("pr_check_repair_invalid_request")
+    repository = _repository(root)
+    try:
+        payload = GitHubProvider().github(
+            "pr", "view", str(number), "--repo", repository,
+            "--json", "number,state,isDraft,headRefOid,headRefName,baseRefName,headRepository,statusCheckRollup",
+        )
+        pull_request = json.loads(payload)
+    except (RuntimeError, OSError, json.JSONDecodeError) as error:
+        raise PullRequestCheckRepairError("pr_check_repair_unavailable") from error
+    if not isinstance(pull_request, dict) or pull_request.get("number") != number:
+        raise PullRequestCheckRepairError("pr_check_repair_unavailable")
+    sha, branch = pull_request.get("headRefOid"), pull_request.get("headRefName")
+    head_repository = pull_request.get("headRepository")
+    head_repository_name = head_repository.get("nameWithOwner") if isinstance(head_repository, dict) else None
+    failed_checks, terminal = check_summary(pull_request.get("statusCheckRollup"))
+    eligible = (
+        str(pull_request.get("state") or "").upper() == "OPEN"
+        and pull_request.get("isDraft") is not True
+        and isinstance(sha, str) and bool(re.fullmatch(r"[0-9a-f]{40}", sha))
+        and isinstance(branch, str) and bool(branch)
+        and head_repository_name == repository
+        and terminal and bool(failed_checks)
+    )
+    state = _read_state(root, number, sha) if isinstance(sha, str) else None
+    attempted = state is not None
+    return {
+        "number": number, "repository": repository, "head_sha": sha, "branch": branch,
+        "failed_checks": failed_checks, "checks_terminal": terminal,
+        "eligible": eligible and not attempted,
+        "repair_state": str(state.get("status")) if state else None,
+    }
+
+
+def admit(root: Path, number: int) -> dict[str, object]:
+    """Atomically reserve exactly one repair attempt for the current PR SHA."""
+    evidence = current_evidence(root, number)
+    if not evidence["eligible"]:
+        raise PullRequestCheckRepairError("pr_check_repair_not_eligible")
+    missing = provider_readiness_failures(root, require_github=True)
+    if missing:
+        raise PullRequestCheckRepairError("pr_check_repair_provider_not_ready")
+    remaining = read_remaining_percent()
+    reserve = capacity_reserve_from_environment()
+    if remaining is None or remaining <= reserve:
+        raise PullRequestCheckRepairError("pr_check_repair_capacity_unavailable")
+    sha = str(evidence["head_sha"])
+    payload = {
+        "status": "QUEUED", "number": number, "head_sha": sha,
+        "branch": evidence["branch"], "failed_checks": evidence["failed_checks"],
+        "created_at": datetime.now(timezone.utc).isoformat(),
+    }
+    _write_state(root, number, sha, payload)
+    return evidence
+
+
+def mark_dispatch_failed(root: Path, number: int, sha: str) -> None:
+    state = _read_state(root, number, sha)
+    if state and state.get("status") == "QUEUED":
+        _write_state(root, number, sha, {**state, "status": "FAILED", "error": "pr_check_repair_dispatch_failed", "completed_at": datetime.now(timezone.utc).isoformat()})
+
+
+def _command(root: Path, *arguments: str) -> str:
+    completed = GitProvider().execute(root, "git", *arguments)
+    if completed.returncode:
+        raise PullRequestCheckRepairError("pr_check_repair_failed")
+    return completed.stdout.strip()
+
+
+def _prepare_worktree_tooling(worktree: Path) -> None:
+    """Install locked Playwright tooling before an EP-created worktree is used.
+
+    A linked worktree does not share ``node_modules`` with its source checkout.
+    When this repository declares the browser suite, ``npm ci`` is therefore a
+    required local preparation step, not a best-effort validation fallback.
+    """
+    try:
+        prepare_worktree_tooling(worktree)
+    except WorktreeToolingError:
+        raise PullRequestCheckRepairError("pr_check_repair_worktree_tooling_unavailable")
+
+
+def run(root: Path, number: int, sha: str) -> None:
+    """Execute the already-admitted repair in an isolated, disposable worktree."""
+    state = _read_state(root, number, sha)
+    if not state or state.get("status") != "QUEUED":
+        raise PullRequestCheckRepairError("pr_check_repair_not_eligible")
+    evidence = current_evidence(root, number)
+    # The durable reservation intentionally makes ``eligible`` false. Fresh
+    # remote evidence must nevertheless still identify this exact failed head.
+    if (
+        evidence.get("head_sha") != sha
+        or evidence.get("branch") != state.get("branch")
+        or not evidence.get("checks_terminal")
+        or not evidence.get("failed_checks")
+    ):
+        raise PullRequestCheckRepairError("pr_check_repair_stale")
+    branch = str(state["branch"])
+    _write_state(root, number, sha, {**state, "status": "RUNNING", "started_at": datetime.now(timezone.utc).isoformat()})
+    worktree = Path(tempfile.mkdtemp(prefix=f"ep-pr-{number}-", dir=root / ".engineering"))
+    worktree.rmdir()
+    try:
+        _command(root, "fetch", "origin", branch)
+        _command(root, "worktree", "add", "--detach", str(worktree), sha)
+        _prepare_worktree_tooling(worktree)
+        prompt = (
+            f"Repair only the failed GitHub checks for pull request #{number}.\n"
+            f"Current head SHA: {sha}. Failed checks: {', '.join(str(item) for item in state['failed_checks'])}.\n"
+            "Work only in this isolated worktree. Inspect the failed-check evidence and make the smallest focused source or test correction. "
+            "Do not change the pull request scope. Do not create commits, push, open or merge a pull request, alter GitHub settings, or use destructive Git commands. "
+            "Run focused verification where practical. Finish with the working tree containing only the proposed repair."
+        )
+        result = CodexCliProvider().invoke(
+            worktree, ("codex", "exec", "--sandbox", "workspace-write", "-C", str(worktree), prompt),
+        )
+        if result.returncode:
+            raise PullRequestCheckRepairError("pr_check_repair_agent_failed")
+        if _command(worktree, "rev-parse", "HEAD") != sha:
+            raise PullRequestCheckRepairError("pr_check_repair_scope_conflict")
+        if not _command(worktree, "status", "--porcelain", "--untracked-files=all"):
+            raise PullRequestCheckRepairError("pr_check_repair_no_change")
+        _command(worktree, "diff", "--check")
+        _command(worktree, "add", "--all")
+        _command(worktree, "commit", "-m", f"fix(ci): repair failed checks for PR #{number}")
+        commit = _command(worktree, "rev-parse", "HEAD")
+        _command(worktree, "push", "--force-with-lease=refs/heads/" + branch + ":" + sha, "origin", "HEAD:refs/heads/" + branch)
+        _write_state(root, number, sha, {**state, "status": "SUBMITTED", "commit_sha": commit, "submitted_at": datetime.now(timezone.utc).isoformat()})
+    except PullRequestCheckRepairError as error:
+        _write_state(root, number, sha, {**state, "status": "FAILED", "error": str(error), "completed_at": datetime.now(timezone.utc).isoformat()})
+    finally:
+        try:
+            if worktree.exists() and not _command(worktree, "status", "--porcelain", "--untracked-files=all"):
+                _command(root, "worktree", "remove", "--", str(worktree))
+        except PullRequestCheckRepairError:
+            pass
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", required=True, type=Path)
+    parser.add_argument("--pull-request", required=True, type=int)
+    parser.add_argument("--head-sha", required=True)
+    arguments = parser.parse_args()
+    run(arguments.root.resolve(), arguments.pull_request, arguments.head_sha)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

engineering_platform/pr_evidence_backfill.py

@@ -0,0 +1,278 @@
+"""Fail-closed recovery of missing historical Managed pull-request evidence.
+
+This tool is intentionally operator-invoked and dry-run by default.  It never
+creates, edits, merges, or closes a pull request.  It can only link a missing
+checkpoint field after the live GitHub record exactly matches the checkpointed
+branch and merge commit for that role.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass, replace
+from datetime import datetime, timezone
+import json
+import os
+from pathlib import Path
+import tempfile
+from typing import Callable, Iterable
+
+from .agent_state import StateError, TransactionState
+from .execution_models import PullRequestEvidence
+from .execution_repository import GhCliClient, GitHubClient
+from .providers import GitProvider
+from .storage import EngineeringStorageError, open_storage
+
+
+ROLES = ("IMPLEMENTATION", "FINALIZATION")
+ACTOR = "operator_pr_evidence_backfill"
+
+
+@dataclass(frozen=True)
+class BackfillDecision:
+    run_id: str
+    role: str
+    outcome: str
+    reason: str
+    pull_request: int | None = None
+    expected_branch: str | None = None
+    expected_merge_commit: str | None = None
+
+    def report(self) -> dict[str, object]:
+        return {
+            "run_id": self.run_id,
+            "role": self.role.lower(),
+            "outcome": self.outcome.lower(),
+            "reason": self.reason,
+            "pull_request": self.pull_request,
+            "expected_branch": self.expected_branch,
+            "expected_merge_commit": self.expected_merge_commit,
+        }
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _role_evidence(state: TransactionState, role: str) -> tuple[int | None, str | None, str | None]:
+    if role == "IMPLEMENTATION":
+        return state.implementation_pull_request, state.implementation_branch, state.implementation_merge_commit
+    return state.finalization_pull_request, state.finalization_branch, state.finalization_merge_commit
+
+
+def _candidate_decision(
+    state: TransactionState, role: str, github: GitHubClient, repository: str | None,
+    main_contains: Callable[[str], bool | None],
+) -> BackfillDecision:
+    recorded_pr, branch, merge_commit = _role_evidence(state, role)
+    base = dict(run_id=state.run_id, role=role, expected_branch=branch, expected_merge_commit=merge_commit)
+    if state.execution_mode != "MANAGED":
+        return BackfillDecision(outcome="SKIPPED", reason="not_managed_execution", **base)
+    if repository is None or state.repository != repository:
+        return BackfillDecision(outcome="SKIPPED", reason="repository_evidence_unavailable_or_mismatched", **base)
+    if not state.terminal:
+        return BackfillDecision(outcome="SKIPPED", reason="run_not_terminal", **base)
+    if recorded_pr is not None:
+        return BackfillDecision(outcome="SKIPPED", reason="pull_request_already_recorded", pull_request=recorded_pr, **base)
+    if not branch or not merge_commit:
+        return BackfillDecision(outcome="SKIPPED", reason="checkpoint_evidence_incomplete", **base)
+    try:
+        evidence = github.pull_request_for_head_branch(branch)
+    except Exception:
+        return BackfillDecision(outcome="SKIPPED", reason="github_evidence_unavailable", **base)
+    if evidence is None:
+        return BackfillDecision(outcome="SKIPPED", reason="pull_request_not_found_for_checkpoint_branch", **base)
+    if not _exact_match(evidence, branch, merge_commit):
+        return BackfillDecision(outcome="SKIPPED", reason="github_evidence_does_not_exactly_match_checkpoint", **base)
+    contained = main_contains(merge_commit)
+    if contained is None:
+        return BackfillDecision(outcome="SKIPPED", reason="repository_merge_evidence_unavailable", **base)
+    if not contained:
+        return BackfillDecision(outcome="SKIPPED", reason="merge_commit_not_in_origin_main", **base)
+    return BackfillDecision(outcome="APPLIED", reason="exact_github_branch_and_merge_evidence", pull_request=evidence.number, **base)
+
+
+def _exact_match(evidence: PullRequestEvidence, branch: str, merge_commit: str) -> bool:
+    return (
+        evidence.state == "MERGED"
+        and evidence.head_branch == branch
+        and evidence.base_branch == "main"
+        and evidence.merge_commit == merge_commit
+    )
+
+
+def _load_states(root: Path, run_id: str | None) -> Iterable[TransactionState]:
+    connection = open_storage(root, create=False)
+    try:
+        if run_id:
+            rows = connection.execute("SELECT payload FROM engineering_transactions WHERE run_id=?", (run_id,)).fetchall()
+        else:
+            rows = connection.execute("SELECT payload FROM engineering_transactions ORDER BY run_id").fetchall()
+    finally:
+        connection.close()
+    for (payload,) in rows:
+        try:
+            yield TransactionState.from_dict(json.loads(payload))
+        except (StateError, TypeError, json.JSONDecodeError):
+            # A malformed checkpoint is never eligible for recovery. There is
+            # no safe run id to write against, so it remains database evidence.
+            continue
+
+
+def _current_repository(root: Path) -> str | None:
+    result = GitProvider().execute(root, "git", "remote", "get-url", "origin")
+    if result.returncode:
+        return None
+    value = result.stdout.strip().removesuffix(".git")
+    if value.startswith("git@github.com:"):
+        value = value.removeprefix("git@github.com:")
+    elif value.startswith("https://github.com/"):
+        value = value.removeprefix("https://github.com/")
+    return value if value.count("/") == 1 else None
+
+
+def _origin_main_contains(root: Path, commit: str) -> bool | None:
+    """Refresh only the remote-tracking ref; never change the checkout or branch."""
+    provider = GitProvider()
+    if provider.execute(root, "git", "fetch", "origin", "main").returncode:
+        return None
+    result = provider.execute(root, "git", "merge-base", "--is-ancestor", commit, "origin/main")
+    return result.returncode == 0
+
+
+def _updated_state(state: TransactionState, decision: BackfillDecision) -> TransactionState:
+    if decision.role == "IMPLEMENTATION":
+        return replace(state, implementation_pull_request=decision.pull_request)
+    return replace(state, finalization_pull_request=decision.pull_request)
+
+
+def _record_skip(root: Path, decision: BackfillDecision, *, observed_at: str) -> None:
+    connection = open_storage(root)
+    try:
+        connection.execute(
+            "INSERT INTO execution_pr_evidence_backfills(run_id,pr_role,outcome,reason,pr_number,expected_branch,expected_merge_commit,observed_at,actor) VALUES(?,?,?,?,?,?,?,?,?)",
+            (decision.run_id, decision.role, decision.outcome, decision.reason, decision.pull_request,
+             decision.expected_branch, decision.expected_merge_commit, observed_at, ACTOR),
+        )
+    finally:
+        connection.close()
+
+
+def _write_projection(directory: Path, state: TransactionState) -> None:
+    """Refresh the compatibility JSON only after the canonical commit succeeds."""
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    target = directory / f"{state.run_id}.json"
+    descriptor, temporary = tempfile.mkstemp(prefix=f".{state.run_id}.", suffix=".tmp", dir=directory)
+    try:
+        os.fchmod(descriptor, 0o600)
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            json.dump(state.to_dict(), handle, indent=2, sort_keys=True)
+            handle.write("\n")
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, target)
+        os.chmod(target, 0o600)
+    except OSError:
+        try:
+            os.unlink(temporary)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _apply(root: Path, state: TransactionState, decision: BackfillDecision, *, observed_at: str) -> BackfillDecision:
+    """Atomically persist the exact verified link and its audit record."""
+    connection = open_storage(root)
+    updated: TransactionState | None = None
+    try:
+        connection.execute("BEGIN IMMEDIATE")
+        row = connection.execute("SELECT payload FROM engineering_transactions WHERE run_id=?", (state.run_id,)).fetchone()
+        if not row:
+            decision = replace(decision, outcome="SKIPPED", reason="checkpoint_disappeared", pull_request=None)
+        else:
+            current = TransactionState.from_dict(json.loads(row[0]))
+            current_pr, current_branch, current_merge = _role_evidence(current, decision.role)
+            if (
+                current.execution_mode != "MANAGED" or not current.terminal
+                or current_pr is not None
+                or current_branch != decision.expected_branch
+                or current_merge != decision.expected_merge_commit
+            ):
+                decision = replace(decision, outcome="SKIPPED", reason="checkpoint_changed_since_verification", pull_request=None)
+            else:
+                updated = _updated_state(current, decision)
+                encoded = json.dumps(updated.to_dict(), separators=(",", ":"), sort_keys=True)
+                connection.execute(
+                    "UPDATE engineering_transactions SET payload=?,phase=?,updated_at=CURRENT_TIMESTAMP WHERE run_id=?",
+                    (encoded, updated.phase, updated.run_id),
+                )
+                connection.execute(
+                    "INSERT OR IGNORE INTO execution_lifecycle_events(run_id,phase,checkpoint,recorded_at) VALUES(?,?,?,CURRENT_TIMESTAMP)",
+                    (updated.run_id, updated.phase, encoded),
+                )
+        connection.execute(
+            "INSERT INTO execution_pr_evidence_backfills(run_id,pr_role,outcome,reason,pr_number,expected_branch,expected_merge_commit,observed_at,actor) VALUES(?,?,?,?,?,?,?,?,?)",
+            (decision.run_id, decision.role, decision.outcome, decision.reason, decision.pull_request,
+             decision.expected_branch, decision.expected_merge_commit, observed_at, ACTOR),
+        )
+        connection.execute("COMMIT")
+    except (EngineeringStorageError, StateError, OSError, ValueError, json.JSONDecodeError):
+        connection.execute("ROLLBACK")
+        raise
+    finally:
+        connection.close()
+    if updated is not None:
+        try:
+            _write_projection(root / ".engineering" / "engineering-runs", updated)
+        except OSError:
+            return replace(decision, reason="exact_evidence_applied_projection_refresh_failed")
+    return decision
+
+
+def backfill(root: Path, *, apply: bool = False, run_id: str | None = None,
+             github: GitHubClient | None = None, repository: str | None = None,
+             main_contains: Callable[[str], bool | None] | None = None) -> dict[str, object]:
+    """Inspect or atomically backfill exact historical Managed PR evidence."""
+    client = github or GhCliClient()
+    repository = repository if repository is not None else _current_repository(root)
+    checked_merges: dict[str, bool | None] = {}
+
+    def current_main_contains(commit: str) -> bool | None:
+        if commit not in checked_merges:
+            check = main_contains or (lambda value: _origin_main_contains(root, value))
+            checked_merges[commit] = check(commit)
+        return checked_merges[commit]
+
+    decisions: list[BackfillDecision] = []
+    for state in _load_states(root, run_id):
+        for role in ROLES:
+            decision = _candidate_decision(state, role, client, repository, current_main_contains)
+            if apply:
+                if decision.outcome == "APPLIED":
+                    decision = _apply(root, state, decision, observed_at=_now())
+                else:
+                    _record_skip(root, decision, observed_at=_now())
+            decisions.append(decision)
+    applied = sum(item.outcome == "APPLIED" for item in decisions)
+    skipped = len(decisions) - applied
+    return {"mode": "apply" if apply else "dry_run", "applied": applied, "skipped": skipped, "decisions": [item.report() for item in decisions]}
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--apply", action="store_true", help="persist only exact, verified evidence matches")
+    parser.add_argument("--run-id", help="limit recovery to one canonical run id")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        report = backfill(Path.cwd().resolve(), apply=args.apply, run_id=args.run_id)
+    except EngineeringStorageError as error:
+        raise SystemExit(f"PR-evidence recovery could not safely access storage: {error}") from error
+    print(json.dumps(report, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - module entry point
+    raise SystemExit(main())