autoforge-cli 0.1.0a0__py3-none-any.whl

autoforge/replan_txn.py

@@ -0,0 +1,1930 @@
+"""The REPLAN_REEXECUTE transaction: typed durable state and pure verifiers.
+
+REPLAN_REEXECUTE is the only phase in which the controller performs a
+*destructive* GitHub write on work an agent produced: it closes the PR that
+holds the accumulated review findings and activates a replacement in its
+place. Nothing about that write is recoverable by re-running it, so the phase
+is modelled as one explicit transaction rather than as a sequence of
+independent checks.
+
+Everything here is pure. GitHub I/O and state persistence live in the engine;
+this module owns the *decisions*, so the normal path and the crash-recovery
+path cannot drift apart by construction — they call the same predicates on
+the same persisted intent.
+
+Lifecycle (monotonic; ``REJECTED`` is terminal)::
+
+    PENDING ──► PREPARED ──► VERIFIED ──► SUPERSEDE_INTENT ──► SUPERSEDED ──► (activated)
+        │           │             │                │                │
+        │           │             │                ▼                │
+        │           │             │          COMPENSATING           │
+        │           │             │                │                │
+        └───────────┴─────────────┴────────────────┴────────────────┴──► REJECTED
+
+``COMPENSATING`` is entered when the close landed on facts that had already
+moved; it is persisted *before* the reopen, so a crash after a successful
+reopen resumes into "finish undoing", never into "close again".
+
+``SUPERSEDE_INTENT`` is written *before* ``gh pr close``, together with the
+source PR's ``closed`` issue-event count. Issue events are append-only, so a
+resume that finds the source still OPEN can prove from that count whether any
+close landed after the intent: none did, and the close is retried once
+(:func:`verify_close_never_ran`); one did, and the reopen that followed is a
+human decision the controller never overrides.
+
+``PREPARED`` is written *before* the agent is invoked, and carries the
+transaction id. Because that id cannot exist anywhere before it is persisted,
+"crashed before invoking the agent" and "crashed while the agent ran" are the
+same recoverable state: either a PR carrying the id exists, or none does.
+
+Causal provenance
+-----------------
+A replacement belongs to a transaction only if its PR body carries the
+controller-generated marker for *that* transaction id:
+
+.. code-block:: text
+
+    <!-- autoforge-replan-transaction: {"transaction_id": "...", ...} -->
+
+The id is random, generated by the controller and persisted before
+invocation; the controller renders the marker itself on the replacement PR
+it creates (#164), and reads it back from GitHub. Shape alone
+("an open PR linked to the issue", "the only other PR") is never proof:
+:func:`select_bound_candidate` ignores every unmarked PR and every PR that
+already existed when the transaction was prepared. The marker is also
+re-checked on the last read before the destructive write
+(:func:`verify_target_marker`), because a body can be edited after the
+controller verified it.
+
+The same marker carries the agent's *attestation* — how many historical
+findings it accounted for, and whether its own tests passed — rendered by the
+controller from the validated CONTROL_RESULT. Putting the attestation on
+GitHub rather than only in the CONTROL_RESULT is what lets recovery enforce
+exactly the same acceptance rules as the normal path: after a crash there is
+no CONTROL_RESULT to consult, but the marker is still there.
+
+Publication (#164)
+------------------
+The agent commits on its worktree's detached ``HEAD`` and publishes nothing.
+The controller pushes the candidate to a branch it derives from the issue and
+the transaction id (:func:`replacement_branch_for`, compared against
+"absent"), then creates the replacement PR, as two effect records (ADR 0004
+K1, K7) owned by the transaction id and journaled before either is sent. A
+journaled plan is completed before anything else, so a crash after the push
+or the create resumes the effects, never the agent; binding then requires
+the PR's HEAD to be the journaled candidate.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import secrets
+from collections.abc import Callable, Iterable
+from dataclasses import asdict, dataclass, field, fields
+from enum import StrEnum
+
+from .claims import IMPLEMENTATION, collect, scan
+from .errors import ClaimConflictError, ConfigurationError
+from .github import PRInfo
+from .validation import GitHubPullRequestRef, parse_issue_url, parse_pr_url, same_pr_url
+
+MARKER_NAME = "autoforge-replan-transaction"
+# Matches *every* complete comment bearing this name, whatever the payload
+# looks like -- the payload is then classified, and anything that is not a
+# usable attestation is reported as malformed rather than passed over. A
+# pattern that only recognised well-formed payloads would silently downgrade
+# "this PR carries a broken attestation" (a conclusive refusal) to "this PR
+# carries no attestation", which is exactly the ambiguity the phase must fail
+# closed on. The payload is therefore *any* text, angle brackets included.
+#
+# The one thing it may not contain is a comment delimiter. Tempering it with
+# `(?!-->|<!--)` stops a marker whose own `-->` is missing from swallowing the
+# body up to some later `-->` and hiding a valid marker inside the match: an
+# unterminated marker is not a complete comment and is evidence of nothing,
+# while every complete one is classified.
+#
+# The pattern is linear in the body it scans (see ``claims.MarkerKind.pattern``
+# for the rule): possessive whitespace runs and no whitespace quantifier next
+# to the lazy payload, which :func:`scan_replan_markers` strips instead.
+MARKER_RE = re.compile(rf"<!--\s*+{MARKER_NAME}\s*+:(?P<payload>(?:(?!-->|<!--)[\s\S])*?)-->")
+
+# The controller's receipt for its own destructive close, posted with a
+# separate `gh pr comment` after the close is observed (see
+# :func:`render_close_receipt`) -- never inside `gh pr close --comment`,
+# whose comment predates the close.
+CLOSE_RECEIPT_NAME = "autoforge-replan-close"
+CLOSE_RECEIPT_RE = re.compile(rf"<!--\s*{CLOSE_RECEIPT_NAME}\s*:\s*(?P<txn>[0-9a-f]{{32}})\s*-->")
+
+TRANSACTION_ID_RE = re.compile(r"^[0-9a-f]{32}$")
+
+
+def new_transaction_id() -> str:
+    """A fresh, unguessable transaction id (controller-generated, never agent)."""
+    return secrets.token_hex(16)
+
+
+def replacement_branch_for(issue_number: int, transaction_id: str) -> str:
+    """The branch the controller pushes the replacement to (#164).
+
+    Derived from controller state alone, never chosen by the agent: the
+    issue and the transaction id, which is random and persisted before the
+    agent runs. So the name differs from the source branch (``autoforge/<n>``
+    or whatever the source PR was headed at, never carrying this id) and from
+    every earlier replan's branch, and the push compares it against "absent".
+    """
+    if issue_number < 1 or not TRANSACTION_ID_RE.match(transaction_id):
+        raise ValueError("a replacement branch needs the issue number and the transaction id")
+    return f"autoforge/{issue_number}-replan-{transaction_id}"
+
+
+def render_marker(attestation: ReplanAttestation) -> str:
+    """The exact marker a replacement PR body must contain (used in the prompt)."""
+    payload = json.dumps(asdict(attestation), sort_keys=True)
+    return f"<!-- {MARKER_NAME}: {payload} -->"
+
+
+def render_close_receipt(transaction_id: str) -> str:
+    """The receipt the controller publishes *after* it closes the source PR.
+
+    ``SUPERSEDE_INTENT`` is persisted before ``gh pr close`` runs, so on its
+    own it proves an intended write, never a performed one: after a crash in
+    that window, a source a human closed and one this transaction closed look
+    identical from the journal. The receipt is the missing half. It is posted
+    with a separate ``gh pr comment`` only after the controller observed its
+    own close landing -- never inside ``gh pr close --comment``, whose comment
+    predates the close and could therefore be present even when the close never
+    landed. So a source found CLOSED *carrying* the receipt for this
+    transaction was closed by this transaction, and one found CLOSED without it
+    cannot be attributed to it -- a human may have closed it, or the controller
+    may have crashed between its close and the receipt -- which is a refusal,
+    not an adoption. The same gap is why the receipt alone never licenses a
+    resume to close a source found OPEN under a recorded intent: without it,
+    "the close never ran" and "it landed, lost its receipt to a crash, and a
+    human reopened the PR" are the same evidence. What tells them apart is the
+    source's ``closed`` issue-event count, recorded with the intent and
+    compared by :func:`verify_close_never_ran` (#69).
+
+    This is crash-recovery attribution, not authentication: the transaction id
+    is published in the replacement PR body, so a human who wanted to could
+    copy it into a comment. It is trusted against crashes and concurrent
+    humans, not against a forger.
+    """
+    return f"<!-- {CLOSE_RECEIPT_NAME}: {transaction_id} -->"
+
+
+def has_close_receipt(comment_bodies: Iterable[str], transaction_id: str) -> bool:
+    """True when some comment carries this transaction's close receipt."""
+    if not TRANSACTION_ID_RE.match(transaction_id or ""):
+        return False
+    return any(
+        match.group("txn") == transaction_id
+        for body in comment_bodies
+        for match in CLOSE_RECEIPT_RE.finditer(body or "")
+    )
+
+
+#: How many times the controller may call ``gh pr close`` on one source PR
+#: under one transaction: the write itself, and one retry from a resume that
+#: proved the write never landed (#69). Every retry is safe on the evidence,
+#: but a close that keeps failing to land is a fault a human should look at,
+#: not one to keep retrying; the bound is what "retries exactly once" means.
+MAX_CLOSE_ATTEMPTS = 2
+
+
+class ReplanStage(StrEnum):
+    """Monotonic transaction stages. ``REJECTED`` is terminal for the run."""
+
+    # Recorded by REVIEW when it routes to REPLAN_REEXECUTE: the decision to
+    # replan, before the controller has checkpointed anything. It carries the
+    # escalation metadata and no transaction id.
+    PENDING = "pending"
+    PREPARED = "prepared"
+    VERIFIED = "verified"
+    SUPERSEDE_INTENT = "supersede_intent"
+    # The controller closed the source, then found a checkpoint had moved
+    # inside the close window. Persisted *before* `gh pr reopen` so that the
+    # decision to undo survives a crash: from here the only outcomes are a
+    # confirmed reopen or a block naming the manual step. Never a second close.
+    COMPENSATING = "compensating"
+    SUPERSEDED = "superseded"
+    REJECTED = "rejected"
+
+
+class Disposition(StrEnum):
+    """How conclusive an observation is — the distinction recovery turns on.
+
+    ``UNKNOWN`` (a transient GitHub failure) must stay resumable; only
+    ``REJECTED`` and ``AMBIGUOUS`` are terminal, and they are persisted so a
+    later resume replays the decision instead of recomputing it.
+    """
+
+    OK = "ok"
+    NONE = "none"  # no candidate yet; the agent has not (verifiably) produced one
+    AMBIGUOUS = "ambiguous"  # more than one candidate claims this transaction
+    REJECTED = "rejected"  # conclusively unacceptable
+
+
+@dataclass(frozen=True)
+class ReplanAttestation:
+    """The agent's machine-readable claim, published on the replacement PR."""
+
+    transaction_id: str
+    execution_attempt: int
+    findings_considered: int
+    unique_constraints: int
+    tests_passed: bool
+
+
+@dataclass(frozen=True)
+class MarkerScan:
+    attestations: list[ReplanAttestation]
+    malformed: list[str]  # human-readable reasons, one per unusable marker
+
+
+def _attestation_from_payload(payload: dict) -> ReplanAttestation:
+    """Strictly typed marker payload; raises ValueError with a usable reason."""
+    txn_id = payload.get("transaction_id")
+    if not isinstance(txn_id, str) or not TRANSACTION_ID_RE.match(txn_id):
+        raise ValueError("transaction_id must be 32 lowercase hex characters")
+    ints: dict[str, int] = {}
+    for key in ("execution_attempt", "findings_considered", "unique_constraints"):
+        value = payload.get(key)
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+            raise ValueError(f"{key} must be an integer >= 0")
+        ints[key] = value
+    tests_passed = payload.get("tests_passed")
+    if not isinstance(tests_passed, bool):
+        raise ValueError("tests_passed must be a boolean")
+    return ReplanAttestation(
+        transaction_id=txn_id,
+        execution_attempt=ints["execution_attempt"],
+        findings_considered=ints["findings_considered"],
+        unique_constraints=ints["unique_constraints"],
+        tests_passed=tests_passed,
+    )
+
+
+def scan_replan_markers(body: str) -> MarkerScan:
+    """Every replan marker in ``body``, split into usable and malformed.
+
+    A malformed marker is reported rather than skipped: a PR body that tries
+    to carry an attestation and fails is evidence of a broken agent, not of an
+    unrelated PR, and the caller fails closed on it. "Malformed" therefore
+    covers every complete marker whose payload is not a usable attestation --
+    unparsable text, a JSON scalar or array, and a JSON object with bad
+    fields alike.
+    """
+    attestations: list[ReplanAttestation] = []
+    malformed: list[str] = []
+    for match in MARKER_RE.finditer(body or ""):
+        raw = match.group("payload").strip()
+        try:
+            payload = json.loads(raw)
+        except ValueError as exc:
+            malformed.append(f"marker payload is not valid JSON ({exc})")
+            continue
+        if not isinstance(payload, dict):
+            malformed.append("marker payload must be a JSON object")
+            continue
+        try:
+            attestations.append(_attestation_from_payload(payload))
+        except ValueError as exc:
+            malformed.append(f"marker payload is invalid ({exc})")
+    return MarkerScan(attestations, malformed)
+
+
+def sole_attestation(
+    scan: MarkerScan, transaction_id: str, ref: str, label: str = "PR"
+) -> tuple[ReplanAttestation | None, str]:
+    """The one attestation ``ref`` publishes for ``transaction_id``, or a defect.
+
+    ``(None, "")`` means the body claims nothing for this transaction -- not an
+    error, just a PR that is none of this transaction's business. A non-empty
+    defect is *conclusive*: the body carries marker evidence for this
+    transaction that cannot be accepted.
+
+    The prompt asks for exactly one marker and nothing marker-shaped beside it,
+    so that is what is enforced: a second copy of ours, an unusable marker
+    beside the valid one, and a *valid* marker belonging to another transaction
+    are all defects. The last one matters as much as the others -- counting
+    only our own markers would let a body publish two provenances at once while
+    every objective check still passed, and provenance that names two
+    transactions proves neither.
+
+    Candidate binding and the final read before the destructive close share
+    this function, so "acceptable enough to adopt" and "still acceptable to
+    close the source for" cannot drift apart into two different rules.
+    """
+    mine = [a for a in scan.attestations if a.transaction_id == transaction_id]
+    if not mine:
+        return None, ""
+    if len(mine) > 1:
+        return None, f"{label} {ref} carries {len(mine)} markers for this transaction"
+    if scan.malformed:
+        return None, (
+            f"{label} {ref} carries the marker for replan transaction {transaction_id} "
+            f"alongside an unusable one ({'; '.join(scan.malformed)})"
+        )
+    others = len(scan.attestations) - 1
+    if others:
+        return None, (
+            f"{label} {ref} carries the marker for replan transaction {transaction_id} "
+            f"alongside {others} valid marker(s) for other transactions; a replacement "
+            "body must publish exactly one attestation"
+        )
+    return mine[0], ""
+
+
+def source_marker_defect(
+    scan: MarkerScan, transaction_id: str, ref: str, *, preexisting: bool
+) -> str:
+    """Why the *source* PR's own body refuses this replan, or ``""``.
+
+    The source can never be adopted as its own replacement, but excluding it
+    *before* reading its body would turn "the agent marked the PR being
+    superseded" into "no candidate exists" -- and that observation is what
+    decides whether the agent is invoked again. Marker-bearing work would then
+    exist while a second implementation attempt started on top of it, which is
+    exactly what crash idempotency forbids. The prompt says putting the marker
+    on the superseded PR rejects the replan, so it has to be *found and
+    refused*, never missed.
+
+    A valid marker for another transaction is left alone: a source PR may
+    itself be an earlier replan's replacement, and that older marker is
+    legitimate history. An unusable marker is refused only when the source
+    postdates the transaction id (``preexisting`` is false, the same
+    watermark/snapshot classification every other candidate gets): a body
+    that tried to carry an attestation and failed is then evidence of a
+    botched attempt. A source that already existed when the transaction was
+    prepared is evidence of nothing about it -- its unusable markers, like
+    those on any other pre-existing PR, neither adopt nor block -- while a
+    *valid* marker for this transaction is a copied one and is refused
+    whatever the source's age.
+    """
+    if any(a.transaction_id == transaction_id for a in scan.attestations):
+        return (
+            f"source PR {ref} carries the marker for replan transaction {transaction_id}; "
+            "the marker belongs on the replacement the agent creates, and a replan whose "
+            "attestation sits on the PR being superseded is refused, never restarted"
+        )
+    if scan.malformed and not preexisting:
+        return (
+            f"source PR {ref} carries an unusable replan marker "
+            f"({'; '.join(scan.malformed)}), which cannot be ruled out as a botched "
+            f"attestation for replan transaction {transaction_id}"
+        )
+    return ""
+
+
+# Persisted URL and id fields are validated by shape as well as by type: a
+# string that is not a GitHub URL would otherwise surface as a
+# ``ConfigurationError`` from the first ``parse_*_url`` on the resume path -- a
+# crash, not a refusal -- and a transaction id that is not one would be
+# silently overwritten (at PENDING) or could bind nothing (later) without the
+# journal ever being called what it is: corrupt.
+_ISSUE_URL_FIELDS = frozenset({"issue_url"})
+_PR_URL_FIELDS = frozenset(
+    {"decision_pr_url", "source_pr_url", "replacement_pr_url", "rejected_pr_url"}
+)
+_PR_URL_LIST_FIELDS = frozenset({"preexisting_pr_urls"})
+
+
+def _url_defect(name: str, value: str, parser: Callable[[str], object]) -> str:
+    try:
+        parser(value)
+    except ConfigurationError as exc:
+        return f"{name} is not a GitHub URL ({exc})"
+    return ""
+
+
+def _field_defect(name: str, annotation: str, value: object) -> str:
+    """Why ``value`` cannot be loaded into the field ``name``, or ``""``.
+
+    The check is driven by the dataclass annotation (a string, because the
+    module defers annotation evaluation), so a field added to the transaction
+    is validated by construction: an annotation this does not understand is a
+    programming error and is raised, never waved through.
+    """
+    kind = type(value).__name__
+    if annotation == "str":
+        if not isinstance(value, str):
+            return f"{name} must be a string, got {kind}"
+        if value and name in _ISSUE_URL_FIELDS | _PR_URL_FIELDS:
+            parser = parse_issue_url if name in _ISSUE_URL_FIELDS else parse_pr_url
+            return _url_defect(name, value, parser)
+        if value and name == "transaction_id" and not TRANSACTION_ID_RE.match(value):
+            return f"{name} must be 32 lowercase hex characters, got {value!r}"
+        return ""
+    if annotation == "int":
+        if not isinstance(value, int) or isinstance(value, bool) or value < 0:
+            return f"{name} must be an integer >= 0, got {value!r}"
+        return ""
+    if annotation == "list[str]":
+        if not isinstance(value, list) or not all(isinstance(item, str) for item in value):
+            return f"{name} must be a list of strings, got {kind}"
+        if name in _PR_URL_LIST_FIELDS:
+            for item in value:
+                defect = _url_defect(f"{name} entry {item!r}", item, parse_pr_url)
+                if defect:
+                    return defect
+        return ""
+    if annotation == "dict":
+        if not isinstance(value, dict):
+            return f"{name} must be an object, got {kind}"
+        return ""
+    raise TypeError(f"ReplanTransaction field {name!r} has unvalidated type {annotation!r}")
+
+
+# The fields each stage's writer fills *together with* the stage. A journal at
+# a stage in which one of them is empty was not written by this controller (a
+# hand edit, a truncated write, an older version), so the type-valid fields
+# around it prove nothing either: it is corruption, not a checkpoint with a
+# gap. Requirements accumulate along the lifecycle, and ``REJECTED`` -- which
+# any stage can reach -- requires nothing. Type validity alone would let a
+# ``VERIFIED`` journal with ``source_branch == ""`` reach the close with a
+# checkpoint that was never proven (#35 R2-F1); this table is what rules that
+# out, and the verifiers refuse the same gap again in depth.
+#
+# The table must cover *every* field its stage writes, not only the ones a
+# verifier compares: an omitted field falls back to the dataclass default,
+# and a default is a value the acceptance predicates will happily enforce.
+# ``evidence_finding_count`` defaulting to 0 is the case that shows why (#35
+# R5-F1): ``verify_attestation`` would then accept a replacement attesting it
+# considered 0 findings, and the source holding the real ones would be closed
+# against an acknowledgement nobody required. So the evidence group is
+# required whole, and the values the writer records there are never
+# legitimately empty -- a replan is only ever decided after a review that
+# ended with findings, so the preserved count is >= 1 and its rendering is
+# non-empty; the observations and verification failures render "(none)" when
+# there are none; the review round that decided the replan is >= 1; and the
+# open-PR snapshot contains the source itself, which ``_prepare_replan`` reads
+# as OPEN and requires to be listed. A field whose legitimate value *can* be
+# falsy is required to be present instead (``_PRESENT_AT_STAGE``): the
+# replacement's ``unique_constraints`` may honestly be 0, but a journal at
+# ``VERIFIED`` that does not record it at all was not written whole.
+_STAGE_ORDER: tuple[ReplanStage, ...] = (
+    ReplanStage.PENDING,
+    ReplanStage.PREPARED,
+    ReplanStage.VERIFIED,
+    ReplanStage.SUPERSEDE_INTENT,
+)
+_REQUIRED_AT_STAGE: dict[ReplanStage, tuple[str, ...]] = {
+    # REVIEW records the issue whose lifecycle it was reviewing, the PR it
+    # decided on, both halves of the revision it reviewed there and the base
+    # it reviewed that revision against; a branch-less decision could only be
+    # compared vacuously (#35 R3-F2), a PR-less one would let the prepare
+    # step take its source from whatever the run happens to hold (#35
+    # R4-F1), an issue-less one would let it take the issue the replacement
+    # must be linked to from whatever the run happens to hold (#35 R6-F1),
+    # and a base-less one would let a source retargeted to another base --
+    # a different diff, which the findings never described -- be superseded
+    # on the strength of the reviewed one (#68). The merge base completes
+    # the diff: a base rewritten under its name moves it while the HEAD,
+    # the branch and the base name all stay put (#96), so a decision without
+    # it would let the source be superseded for a diff no review saw. The
+    # policy metadata is recorded with the decision and always names its
+    # trigger.
+    ReplanStage.PENDING: (
+        "issue_url",
+        "decision_pr_url",
+        "decision_head_sha",
+        "decision_branch",
+        "decision_base_ref",
+        "decision_merge_base_sha",
+        "escalation",
+    ),
+    ReplanStage.PREPARED: (
+        "transaction_id",
+        "source_pr_url",
+        "source_branch",
+        "source_head_sha",
+        "source_base_ref",
+        "source_merge_base_sha",
+        "source_review_round",
+        "base_branch",
+        "evidence_finding_count",
+        "rendered_findings",
+        "rendered_observations",
+        "rendered_verification_failures",
+        "preexisting_pr_urls",
+        "pr_number_watermark",
+        "expected_execution_attempt",
+    ),
+    # The verified attestation is re-checked exactly on the last read before
+    # the close and again before activation; it must be >= the preserved
+    # evidence count, so it is never legitimately 0 either.
+    ReplanStage.VERIFIED: (
+        "replacement_pr_url",
+        "replacement_branch",
+        "replacement_head_sha",
+        "attested_findings_considered",
+    ),
+    # The intent is written with the time, the number of close attempts it
+    # covers (1 for the write, 2 once a resume retried it) and the source
+    # PR's ``closed`` event count read just before it (#69). The count is
+    # what a resume compares GitHub against before it may retry, so an
+    # intent without it can only be refused; it is 0 for a source that was
+    # never closed before, so it is required present, not non-zero.
+    ReplanStage.SUPERSEDE_INTENT: ("close_intent_at", "close_attempts"),
+    # Both follow SUPERSEDE_INTENT and are alternatives to each other.
+    ReplanStage.COMPENSATING: ("compensating_at", "compensation_reason"),
+    ReplanStage.SUPERSEDED: ("superseded_at",),
+}
+# Written together with the stage, but 0 is an honest value: present-or-corrupt.
+_PRESENT_AT_STAGE: dict[ReplanStage, tuple[str, ...]] = {
+    ReplanStage.VERIFIED: ("attested_unique_constraints",),
+    ReplanStage.SUPERSEDE_INTENT: ("source_closed_event_count",),
+}
+
+
+#: Stages at which the controller has committed to closing the source PR:
+#: the intent is durable, and the close may already have landed. From here
+#: the reducer only reads, confirms, and then activates the replacement or
+#: undoes the close; it invokes no agent. The one write it may still perform
+#: is the bounded retry of the close at ``SUPERSEDE_INTENT``, and only once
+#: the source's issue events have proven the first attempt never landed
+#: (:func:`verify_close_never_ran`).
+CLOSE_BEGUN_STAGES: frozenset[ReplanStage] = frozenset(
+    {ReplanStage.SUPERSEDE_INTENT, ReplanStage.COMPENSATING, ReplanStage.SUPERSEDED}
+)
+#: Stages at which the controller has performed no write the run would have to
+#: account for: refusing to go on costs nothing here, so this is where a loop
+#: bound may stop the phase before the reducer runs.
+_PRE_WRITE_STAGES: frozenset[ReplanStage] = frozenset(
+    {ReplanStage.PENDING, ReplanStage.PREPARED, ReplanStage.VERIFIED}
+)
+#: Stages from which the reducer may still launch the replan agent: no PR
+#: bound to the transaction exists yet. Binding and ``VERIFIED`` are saved
+#: together, so a persisted journal at any later stage is finished by the
+#: controller alone -- read, verify, close, activate, reopen or refuse.
+_AGENT_STAGES: frozenset[ReplanStage] = frozenset({ReplanStage.PENDING, ReplanStage.PREPARED})
+
+
+def _stages_reached(stage: ReplanStage) -> tuple[ReplanStage, ...]:
+    if stage is ReplanStage.REJECTED:
+        return ()
+    if stage in _STAGE_ORDER:
+        return _STAGE_ORDER[: _STAGE_ORDER.index(stage) + 1]
+    return (*_STAGE_ORDER, stage)
+
+
+def required_fields_at(stage: ReplanStage) -> tuple[str, ...]:
+    """Every field a journal at ``stage`` must carry non-empty, in lifecycle order."""
+    return tuple(name for earlier in _stages_reached(stage) for name in _REQUIRED_AT_STAGE[earlier])
+
+
+def present_fields_at(stage: ReplanStage) -> tuple[str, ...]:
+    """Every field a journal at ``stage`` must carry, though possibly falsy."""
+    return tuple(
+        name for earlier in _stages_reached(stage) for name in _PRESENT_AT_STAGE.get(earlier, ())
+    )
+
+
+def _stage_defects(stage: ReplanStage, values: dict[str, object]) -> list[str]:
+    """Required-but-empty (or forbidden-but-set) fields for ``stage``."""
+    defects: list[str] = []
+    for name in required_fields_at(stage):
+        if name not in values:
+            defects.append(f"{name} is required at stage {stage.value!r} but missing")
+        elif not values[name]:
+            defects.append(f"{name} is required at stage {stage.value!r} but empty")
+    for name in present_fields_at(stage):
+        if name not in values:
+            defects.append(f"{name} is required at stage {stage.value!r} but missing")
+    # The id is created together with PREPARED and can exist nowhere before
+    # it (see the module docstring); a PENDING journal carrying one was not
+    # written by this controller.
+    if stage is ReplanStage.PENDING and values.get("transaction_id"):
+        defects.append(f"transaction_id is set at stage {stage.value!r}, before it is created")
+    return defects
+
+
+@dataclass
+class ReplanTransaction:
+    """Durable intent for one replan. Persisted as ``state.replan_transaction``.
+
+    The field groups mirror the invariants: a *source* checkpoint (the PR that
+    may be closed), a *base* the replacement must be built on, the *evidence*
+    the replacement must answer for, the *provenance* that binds a candidate
+    to this transaction, the verified *target*, and the record of the
+    destructive write.
+    """
+
+    transaction_id: str = ""
+    stage: ReplanStage = ReplanStage.PENDING
+
+    # -- decision point: the review state that routed to this replan -------
+    # Recorded by REVIEW when the transaction is created, before the
+    # controller looks at GitHub again. The source may only be superseded at
+    # exactly this revision of exactly this PR: it is the one whose findings
+    # justify the replan. The PR identity is recorded alongside the revision
+    # because the prepare step otherwise has only ``state.current_pr_url`` to
+    # take its source from, and two open PRs can share a HEAD and a branch
+    # (one branch, two bases); a decision that binds the revision but not the
+    # PR could be checkpointed onto the wrong one. The issue is recorded here
+    # for the same reason: it is the lifecycle the source belongs to and the
+    # one the replacement must be linked to, and the prepare step would
+    # otherwise take it from ``state.current_issue_url``. It is never
+    # re-derived later; :func:`verify_run_binding` binds it to the run's
+    # active issue at every stage instead. The base branch the review was
+    # bound to completes the revision: a PR's diff is HEAD against base, so
+    # the same HEAD on the same branch retargeted to another base is a
+    # different change from the one the findings describe. The merge base
+    # is the commit that diff was computed from: a base rewritten under its
+    # name (force-push, reset) moves it while the HEAD, the branch and the
+    # base name stay equal, so it is bound with them (#96). It is the SHA the
+    # review bound (``state.current_merge_base_sha`` at REVIEW entry), never
+    # re-read from GitHub after the decision.
+    issue_url: str = ""
+    decision_pr_url: str = ""
+    decision_head_sha: str = ""
+    decision_branch: str = ""
+    decision_base_ref: str = ""
+    decision_merge_base_sha: str = ""
+
+    # -- source checkpoint: exactly what may be superseded -----------------
+    source_pr_url: str = ""
+    source_branch: str = ""
+    source_head_sha: str = ""
+    source_base_ref: str = ""
+    source_merge_base_sha: str = ""
+    source_review_round: int = 0
+
+    # -- base: independently verified default branch ----------------------
+    base_branch: str = ""
+
+    # -- evidence the replacement must account for ------------------------
+    evidence_finding_count: int = 0
+    rendered_findings: str = ""
+    rendered_observations: str = ""
+    rendered_verification_failures: str = ""
+
+    # -- provenance -------------------------------------------------------
+    # Largest PR number in the repository when this transaction was prepared,
+    # read *before* the transaction id existed. GitHub allocates PR numbers
+    # from a monotonic per-repository counter, so any PR at or below this
+    # predates the id and therefore cannot be the replacement -- whether or not
+    # it was linked to the issue, named for it, or even open at the time.
+    pr_number_watermark: int = 0
+    # Defence in depth over the watermark: the issue's open PRs at PREPARED,
+    # by identity. None of them can ever be adopted as the replacement.
+    preexisting_pr_urls: list[str] = field(default_factory=list)
+    expected_execution_attempt: int = 0
+
+    # -- target: the verified replacement ---------------------------------
+    replacement_pr_url: str = ""
+    replacement_branch: str = ""
+    replacement_head_sha: str = ""
+    attested_findings_considered: int = 0
+    attested_unique_constraints: int = 0
+
+    # -- destructive write ------------------------------------------------
+    close_intent_at: str = ""
+    # The source PR's ``closed`` issue-event count, read from GitHub after
+    # the pre-close checkpoint held and immediately before the intent was
+    # persisted (#69). Issue events are append-only and undeletable, so a
+    # resume that finds the source OPEN can compare: a higher count proves a
+    # close landed after the intent (this transaction's, or a human's; either
+    # way the reopen that followed is the last word) and refuses; an equal
+    # count proves no close has happened since and licenses the one retry.
+    # Absence of a comment never decides a write; this count does.
+    source_closed_event_count: int = 0
+    # How many times ``gh pr close`` has been called under this intent: 1 by
+    # the write, 2 by the retry a resume performed. Bounded by
+    # ``MAX_CLOSE_ATTEMPTS``.
+    close_attempts: int = 0
+    superseded_at: str = ""
+
+    # -- compensation -----------------------------------------------------
+    # Written together with stage COMPENSATING, before `gh pr reopen` is
+    # called. ``compensation_reason`` is the drift that made the close
+    # unacceptable; it is replayed verbatim by a resume so the undo cannot be
+    # re-derived (and possibly re-decided) from GitHub facts that have since
+    # settled back into place.
+    compensating_at: str = ""
+    compensation_reason: str = ""
+
+    # -- disposition ------------------------------------------------------
+    rejection_reason: str = ""
+    rejected_pr_url: str = ""
+
+    escalation: dict = field(default_factory=dict)
+
+    # -- journal integrity (never persisted) ------------------------------
+    # Why :meth:`from_dict` coerced this transaction to ``REJECTED``: one
+    # reason per persisted field it could not read. Empty for a well-formed
+    # journal. Kept off disk so the corrupt evidence is never overwritten by
+    # the defaults that stand in for it here.
+    journal_defects: list[str] = field(default_factory=list)
+
+    # -- persistence ------------------------------------------------------
+    def to_dict(self) -> dict:
+        data = asdict(self)
+        data["stage"] = self.stage.value
+        del data["journal_defects"]
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ReplanTransaction:
+        """Load persisted intent; unknown/omitted fields fall back to defaults.
+
+        Every *present* field is schema-checked. A field that cannot be read
+        -- an unknown stage, a watermark stored as a string, an escalation
+        stored as a list -- is *not* coerced to a runnable value: the
+        transaction becomes ``REJECTED`` with the defects named, so a
+        hand-edited, truncated or future-version journal fails closed
+        instead of resuming a destructive write from an unknown position, and
+        instead of crashing on the first use of the field so that every
+        ``resume`` dies identically. The unreadable fields fall back to their
+        defaults in memory only (see ``journal_defects``).
+
+        Omission is only tolerated where the stage tolerates it: every field
+        the recorded stage's writer fills is required to be present and
+        non-empty (:func:`required_fields_at`), or at least present where 0
+        is an honest value (:func:`present_fields_at`), so an incomplete
+        checkpoint is corruption rather than a checkpoint some later verifier
+        might compare vacuously -- or, for the evidence fields, enforce at
+        their defaults.
+        """
+        if not isinstance(data, dict):
+            raise ValueError("replan transaction must be a JSON object")
+        kwargs: dict = {}
+        defects: list[str] = []
+        raw_stage = data.get("stage", ReplanStage.PENDING.value)
+        try:
+            if not isinstance(raw_stage, str):
+                raise ValueError(raw_stage)
+            stage = ReplanStage(raw_stage)
+        except ValueError:
+            stage = ReplanStage.REJECTED
+            defects.append(f"unknown stage {raw_stage!r}")
+        for spec in fields(cls):
+            if spec.name in ("stage", "journal_defects") or spec.name not in data:
+                continue
+            value = data[spec.name]
+            defect = _field_defect(spec.name, str(spec.type), value)
+            if defect:
+                defects.append(defect)
+                continue
+            kwargs[spec.name] = value
+        if not defects:
+            # Only a journal whose fields all read cleanly is judged for
+            # completeness: a field that already failed its type check has
+            # been reported once and must not be reported again as "empty".
+            defects.extend(_stage_defects(stage, kwargs))
+        if defects:
+            stage = ReplanStage.REJECTED
+            prior = kwargs.get("rejection_reason", "")
+            kwargs["rejection_reason"] = (
+                "persisted replan transaction is corrupt: "
+                + "; ".join(defects)
+                + f" (recorded stage {raw_stage!r}"
+                + (f", recorded rejection: {prior}" if prior else "")
+                + ")"
+            )
+        return cls(stage=stage, journal_defects=defects, **kwargs)
+
+    @property
+    def is_bound(self) -> bool:
+        return bool(self.replacement_pr_url)
+
+    def rendered_marker(self, findings_considered: int, unique_constraints: int) -> str:
+        """The marker the controller renders on the replacement PR it creates (#164).
+
+        The transaction id and the execution attempt are the checkpoint's;
+        the counts are the validated result's, and ``tests_passed`` is
+        ``True`` because a result reporting otherwise is rejected before
+        anything is published.
+        """
+        return render_marker(
+            ReplanAttestation(
+                transaction_id=self.transaction_id,
+                execution_attempt=self.expected_execution_attempt,
+                findings_considered=findings_considered,
+                unique_constraints=unique_constraints,
+                tests_passed=True,
+            )
+        )
+
+
+def budget_may_stop(txn: ReplanTransaction) -> bool:
+    """Whether the run's step budget may stop the replan step before the reducer runs.
+
+    True only while the journal proves the controller has written nothing
+    (``PENDING``, ``PREPARED``, ``VERIFIED``): blocking there leaves the
+    source open with its findings and needs nothing recorded. From
+    ``SUPERSEDE_INTENT`` on, the persisted intent is a decision the
+    controller finishes -- what remains is read, confirm and activate, read,
+    confirm and reopen, or the one retry of a close GitHub proves never ran,
+    with no agent -- so
+    the step counts and the budget ends the run at the next phase boundary
+    instead of inside the transaction, where a plain budget block would
+    strand a source the controller closed with nothing recorded about it
+    (#71). A journal the reducer will refuse anyway -- ``REJECTED``, or one
+    that could not be read whole and therefore cannot prove it is before the
+    write -- is handed to the reducer too: its refusal names the transaction
+    and the source PR's fate, which the budget text cannot.
+    """
+    return txn.stage in _PRE_WRITE_STAGES
+
+
+def may_invoke_agent(txn: ReplanTransaction) -> bool:
+    """Whether a REPLAN_REEXECUTE step from this journal may launch the replan agent.
+
+    True only at ``PENDING`` and ``PREPARED``, where no replacement PR is
+    bound to the transaction and the reducer falls through to the
+    invocation when it finds none. From ``VERIFIED`` on the reducer resolves
+    the step itself, and a ``REJECTED`` journal -- recorded, or coerced there
+    because it could not be read whole -- replays its refusal. The dry-run
+    plan follows this partition so it shows an agent command, template and
+    prompt only for a step that can launch one.
+    """
+    return txn.stage in _AGENT_STAGES
+
+
+# ---------------------------------------------------------------------------
+# State-protocol migration. The journal's schema is part of the state
+# protocol, and each protocol step so far added one binding to it: 1 -> 2
+# when REVIEW started recording the PR and the issue its replan decision was
+# made on (``decision_pr_url``; ``issue_url`` at PENDING) so that every later
+# stage could be bound to that decision rather than to whatever the run
+# happened to hold, and 2 -> 3 when it started recording the base branch the
+# deciding review was bound to (``decision_base_ref`` at PENDING,
+# ``source_base_ref`` at PREPARED) so that a source retargeted to another
+# base could not be superseded on the strength of a review of a different
+# diff (#68). A journal written under an older protocol was written whole by
+# the controller of its day and is not corrupt; it simply never recorded the
+# binding, and there is nothing to reconstruct it from: "missing field ->
+# fill from the run's current PR and issue" or "-> fill from the source PR's
+# current base" is precisely the rebinding the fields exist to forbid (#35
+# R4-F1, R6-F1), and #66 R7-F1 is where an in-flight protocol-1 journal was
+# found to be refused as *corruption* under a protocol that still called
+# itself 1. 3 -> 4 added the merge base the deciding review's diff was
+# computed from (``decision_merge_base_sha`` at PENDING,
+# ``source_merge_base_sha`` at PREPARED), so that a base rewritten under its
+# name between the review and the close -- same HEAD, same branch, same
+# base name, another diff -- could not be superseded on the strength of a
+# review of the diff it used to show (#96). Filling it from the merge base
+# GitHub reports *now* would bind the decision to exactly the rewrite the
+# field exists to detect, so a protocol-3 journal in flight is refused like
+# the others. 4 -> 5 added the source PR's ``closed`` issue-event count and
+# the close attempt count to the intent (``source_closed_event_count`` and
+# ``close_attempts`` at SUPERSEDE_INTENT), so that a resume finding the
+# source OPEN under an intent could prove the close never ran and retry it
+# once instead of blocking (#69). This step touched no stage before the
+# write: a protocol-4 journal at PENDING, PREPARED or VERIFIED is exactly
+# what protocol 5 writes there and is loaded as such. One at
+# SUPERSEDE_INTENT, COMPENSATING or SUPERSEDED is refused like the others:
+# reading the count *now* would record the very close it exists to detect
+# as if it predated the intent, and would license the retry the field was
+# added to forbid in that case.
+# ---------------------------------------------------------------------------
+
+#: The binding each legacy protocol's journal lacks, as the refusal states
+#: it: what was not recorded, and what this controller will not fill it from.
+_LEGACY_JOURNAL_GAPS: dict[str, str] = {
+    "1": (
+        "did not record the PR and issue the replan decision was made on, and this controller "
+        "does not reconstruct them from the run's current PR and issue"
+    ),
+    "2": (
+        "did not record the base branch the review that decided the replan was bound to, and "
+        "this controller does not reconstruct it from the source PR's current base"
+    ),
+    "3": (
+        "did not record the merge base the review that decided the replan was bound to, and "
+        "this controller does not reconstruct it from the merge base GitHub reports now"
+    ),
+    "4": (
+        "did not record the source PR's closed-event count and the number of close attempts "
+        "with the close intent, and this controller does not reconstruct them from the events "
+        "GitHub reports now"
+    ),
+}
+#: The in-flight stages at which each legacy protocol's gap matters. A
+#: protocol whose step changed a field written at ``PENDING`` lacks it at
+#: every later stage, so every in-flight stage is refused; a step that only
+#: added to a later stage's record leaves the earlier stages' journals
+#: identical to the current schema, and those load as current.
+_LEGACY_GAP_STAGES: dict[str, frozenset[str]] = {
+    "4": frozenset(stage.value for stage in CLOSE_BEGUN_STAGES),
+}
+_STAGE_VALUES: frozenset[str] = frozenset(stage.value for stage in ReplanStage)
+#: Protocol labels whose journal schema this controller can still describe
+#: (and so refuse in flight) but cannot load whole.
+LEGACY_JOURNAL_PROTOCOLS: frozenset[str] = frozenset(_LEGACY_JOURNAL_GAPS)
+
+_LEGACY_STAGE_FATES: dict[str, str] = {
+    ReplanStage.PENDING.value: (
+        "the decision to replan was recorded but nothing was checkpointed, no transaction id "
+        "exists and no PR was closed"
+    ),
+    ReplanStage.PREPARED.value: (
+        "a transaction id was created and the replan agent may have been invoked, so a "
+        "replacement PR carrying its marker may exist; no PR was closed by it"
+    ),
+    ReplanStage.VERIFIED.value: (
+        "a replacement PR was verified against the checkpoint; no PR was closed by it"
+    ),
+    ReplanStage.SUPERSEDE_INTENT.value: (
+        "the controller intended to close the source PR and may have done so: a CLOSED source "
+        f"carrying an `<!-- {CLOSE_RECEIPT_NAME}: <transaction id> -->` comment was closed by "
+        "this transaction, and one without it was not; the replacement was not activated"
+    ),
+    ReplanStage.COMPENSATING.value: (
+        "the controller closed the source PR, found a checkpoint had moved, and decided to "
+        "reopen it; the reopen may not have been performed or confirmed, so the source PR may "
+        "still be CLOSED; the replacement was not activated"
+    ),
+    ReplanStage.SUPERSEDED.value: (
+        "the controller closed the source PR and confirmed the close; the replacement was not "
+        "activated in the run's state"
+    ),
+}
+
+
+def legacy_journal_refusal(raw: object, *, protocol: str, written_by: str) -> str:
+    """Why a state's journal under legacy ``protocol`` cannot be loaded, or ``""``.
+
+    As far as the journal is concerned, a legacy state whose journal is
+    empty -- no replan in flight -- or terminal (``REJECTED``, of which every
+    protocol reads nothing but the recorded reason) *is* a current state and
+    is loaded as one. A journal at any other stage is in flight under a
+    schema that never bound what the current one binds, and it is refused at
+    the state boundary: never migrated, since the binding cannot be
+    reconstructed without re-deciding the replan, and never read as
+    corruption, since it was written whole. The refusal names the stage, the
+    PRs, the binding the protocol lacks, what that stage implies about the
+    source PR, and the two ways out -- finish or undo the transaction with
+    the controller that wrote it, or resolve it by hand on GitHub and start a
+    new run. Where the protocol step only added to a later stage's record
+    (``_LEGACY_GAP_STAGES``), a journal at an earlier stage is written
+    exactly as the current schema writes it and loads as current.
+
+    ``raw`` is read defensively: this runs before any schema check, so a
+    non-object journal is left for the state's own type check, and an
+    unreadable stage or PR is reported as such rather than trusted.
+    """
+    if protocol not in _LEGACY_JOURNAL_GAPS:
+        raise ValueError(f"protocol {protocol!r} is not a legacy journal protocol")
+    if not isinstance(raw, dict) or not raw:
+        return ""
+    stage = raw.get("stage")
+    if stage == ReplanStage.REJECTED.value:
+        return ""
+    scoped = _LEGACY_GAP_STAGES.get(protocol)
+    if scoped is not None and stage in _STAGE_VALUES and stage not in scoped:
+        return ""
+
+    def _text(name: str) -> str:
+        value = raw.get(name)
+        return value if isinstance(value, str) and value else "(none)"
+
+    fate = _LEGACY_STAGE_FATES.get(stage) if isinstance(stage, str) else None
+    if fate is None:
+        fate = (
+            f"the journal records an unreadable stage {stage!r}, so what it did to the source "
+            "PR cannot be determined from local state"
+        )
+    return (
+        f"state file was written by controller {written_by or '(unknown)'} under "
+        f"protocol_version {protocol!r} with a replan in flight (stage "
+        f"{stage!r}, transaction {_text('transaction_id')}, source PR {_text('source_pr_url')}, "
+        f"replacement PR {_text('replacement_pr_url')}); protocol {protocol!r} "
+        f"{_LEGACY_JOURNAL_GAPS[protocol]}. At that stage "
+        f"{fate}. Finish or undo the replan with the controller that wrote it, then upgrade; "
+        "or resolve it by hand on GitHub and start a new run. The state file was left unchanged"
+    )
+
+
+# ---------------------------------------------------------------------------
+# Verification predicates. Each returns "" when the check passes, or a
+# human-readable reason why the transaction must not proceed. They are the
+# single definition of "acceptable" for the normal path and for `resume`:
+# there is exactly one, so the two cannot drift.
+# ---------------------------------------------------------------------------
+
+
+def _canonical(url: str) -> str:
+    """A PR URL as text, for messages -- never for an identity comparison.
+
+    The canonical form keeps the owner/repository spelling its author used,
+    and GitHub treats ``Owner/Repo`` and ``owner/repo`` as one repository, so
+    two canonical strings can differ while naming the same PR. Identity is
+    :func:`same_pr_url` for a pair and :func:`_identity` for a set.
+    """
+    try:
+        return parse_pr_url(url).canonical
+    except Exception:
+        return ""
+
+
+def _identity(url: str) -> tuple[str, str, str, int] | None:
+    """The PR as GitHub identifies it (:attr:`GitHubRef.identity`), or None.
+
+    ``None`` for an unusable URL, and a caller must never compare two ``None``
+    values as equal: an unusable checkpoint matches nothing, exactly as
+    :func:`same_pr_url` returns False for it.
+    """
+    try:
+        return parse_pr_url(url).identity
+    except Exception:
+        return None
+
+
+def _same_sha(observed: str, expected: str) -> bool:
+    """One rule for every SHA comparison: case-insensitive, and never vacuous.
+
+    `gh` reports hexadecimal SHAs in lower case, but a checkpoint can come
+    from anywhere a human can type (state recorded from a CONTROL_RESULT, a
+    hand-repaired journal), so case must not decide a supersede. An empty
+    side never matches: an unreadable HEAD is not "the same" as anything.
+    """
+    return bool(observed) and bool(expected) and observed.lower() == expected.lower()
+
+
+def _source_branch_drift(pr: PRInfo, txn: ReplanTransaction, when: str = "") -> str:
+    """The source branch comparison, shared by the pre- and post-close reads.
+
+    Like :func:`_same_sha`, never vacuous: the branch is checkpointed by
+    ``PREPARED`` together with the HEAD and is half of what "exactly the
+    implementation the controller decided to replace" means, so a checkpoint
+    that records no branch has not proven it and must not be closed on.
+    :meth:`ReplanTransaction.from_dict` already refuses such a journal at any
+    stage from ``PREPARED`` on; this is the same rule again at the point of
+    use, so a transaction assembled any other way cannot slip past it.
+    """
+    if not txn.source_branch:
+        return (
+            f"the replan transaction records no branch for source PR {txn.source_pr_url}, so "
+            "the checkpoint cannot prove which branch it decided to supersede"
+        )
+    if pr.head_ref != txn.source_branch:
+        return (
+            f"source PR {txn.source_pr_url} moved from the checkpointed branch "
+            f"{txn.source_branch!r} to {pr.head_ref!r}{when}"
+        )
+    return ""
+
+
+def _source_base_drift(pr: PRInfo, txn: ReplanTransaction, when: str = "") -> str:
+    """The source base comparison, shared by the pre- and post-close reads.
+
+    The third half of the checkpointed revision, next to the HEAD and the
+    branch: a PR's diff is its HEAD against its base, so a source retargeted
+    to another base (``gh pr edit --base``) carries a change no review of
+    this transaction ever saw, at an unchanged HEAD. Never vacuous, for the
+    same reason as :func:`_source_branch_drift`, and an unreadable base on
+    the PR is drift too: it is not "the same" as anything.
+    """
+    if not txn.source_base_ref:
+        return (
+            f"the replan transaction records no base branch for source PR {txn.source_pr_url}, "
+            "so the checkpoint cannot prove which change it decided to supersede"
+        )
+    if pr.base_ref != txn.source_base_ref:
+        return (
+            f"source PR {txn.source_pr_url} was retargeted from the checkpointed base "
+            f"{txn.source_base_ref!r} to {pr.base_ref!r}{when}"
+        )
+    return ""
+
+
+def _source_merge_base_drift(merge_base_sha: str, txn: ReplanTransaction, when: str = "") -> str:
+    """The source merge-base comparison, shared by the pre- and post-close reads.
+
+    The last part of the checkpointed revision: the diff is HEAD against base
+    *from their merge base*, and a base branch rewritten under its name
+    (force-push, reset) moves that commit while the HEAD, the branch and the
+    base name all read back equal (#96). ``merge_base_sha`` is what GitHub
+    reports for the checkpointed base and the observed HEAD right now, read
+    by the caller beside the PR; it is never on the PR object itself. Never
+    vacuous, for the reason :func:`_source_branch_drift` gives, and an
+    unreadable merge base is drift too: it is not "the same" as anything.
+    """
+    if not txn.source_merge_base_sha:
+        return (
+            f"the replan transaction records no merge base for source PR {txn.source_pr_url}, "
+            "so the checkpoint cannot prove which diff it decided to supersede"
+        )
+    if not _same_sha(merge_base_sha, txn.source_merge_base_sha):
+        return (
+            f"source PR {txn.source_pr_url} moved from the checkpointed merge base "
+            f"{txn.source_merge_base_sha} to {merge_base_sha or '(unreadable)'}{when}; base "
+            f"{txn.source_base_ref!r} was rewritten under its name, so the PR's diff is no "
+            "longer the one the review that decided this replan saw"
+        )
+    return ""
+
+
+def verify_run_binding(
+    txn: ReplanTransaction, repository: str, current_pr_url: str, current_issue_url: str
+) -> str:
+    """Every PR the journal names as the source must be the PR this run holds,
+    and the issue it names must be the issue this run is working on.
+
+    Every other source verifier compares GitHub against the journal, so a
+    journal whose ``source_pr_url`` was substituted for the well-formed URL of
+    some *other* PR would only ever be compared against itself: that PR reads
+    back as OPEN, on the checkpointed branch, at the checkpointed HEAD, and
+    the close goes to a PR outside this run's lifecycle -- in another
+    repository, if the operator's credentials reach it (#35 R3-F1). The
+    journal is recovery input, not authority over what the run is working on,
+    so before any stage reads or writes the source it is re-bound to the
+    controller's own ``repository`` and ``current_pr_url``, which
+    ``_prepare_replan`` took it from in the first place. Identity is compared
+    as GitHub does (repository case-insensitively, then the number), never as
+    URL strings.
+
+    The binding is two-sided. ``current_pr_url`` is itself persisted state,
+    and a ``PENDING`` journal names no checkpointed source yet: the prepare
+    step creates one from ``current_pr_url``. So the decision ``REVIEW``
+    recorded must name the PR it reviewed, and that ``decision_pr_url`` is
+    bound to the run exactly like the checkpoint is; otherwise a run whose
+    ``current_pr_url`` was substituted between the review and the prepare
+    step would checkpoint -- and later close -- a PR no review decided on
+    (#35 R4-F1). From ``PREPARED`` on both are required and both must bind,
+    which also pins the checkpoint to the decision.
+
+    The issue is bound the same way, because the PR binding alone proves only
+    *which PR* may be closed, not *for which lifecycle*. The replacement is
+    accepted on the strength of being linked to ``txn.issue_url``
+    (:func:`verify_target_pr`), so a well-formed journal whose ``issue_url``
+    was substituted for another issue of the same repository would let a
+    marker-bearing PR linked only to that other issue be adopted, the source
+    of *this* issue be closed for it, and the run carry on with
+    ``current_issue_url`` pointing at an issue the active PR no longer
+    implements (#35 R6-F1). So ``REVIEW`` records the issue it was reviewing
+    for together with the decision, the prepare step never re-derives it, and
+    here it is compared by identity against the run's ``current_issue_url``
+    at every stage -- which also pins the linkage requirement to the issue
+    whose source is being superseded.
+    """
+    try:
+        held = parse_pr_url(current_pr_url)
+    except ConfigurationError as exc:
+        return (
+            f"the run's current PR URL is unusable ({exc}), so the replan transaction "
+            "cannot be bound to it"
+        )
+    if txn.source_pr_url:
+        drift = _bind_to_run("checkpointed source PR", txn.source_pr_url, repository, held)
+        if drift:
+            return drift
+    elif txn.stage is not ReplanStage.PENDING:
+        return "the replan transaction names no source PR, so there is nothing it may act on"
+    if not txn.decision_pr_url:
+        return (
+            "the replan transaction does not record the PR whose review decided it, so the "
+            "source cannot be bound to that decision"
+        )
+    drift = _bind_to_run("decision PR", txn.decision_pr_url, repository, held)
+    if drift:
+        return drift
+    return _bind_issue_to_run(txn, repository, current_issue_url)
+
+
+def _bind_issue_to_run(txn: ReplanTransaction, repository: str, current_issue_url: str) -> str:
+    """The issue the journal names must be the issue the run is working on."""
+    try:
+        held = parse_issue_url(current_issue_url)
+    except ConfigurationError as exc:
+        return (
+            f"the run's current issue URL is unusable ({exc}), so the replan transaction "
+            "cannot be bound to it"
+        )
+    if not txn.issue_url:
+        return (
+            "the replan transaction does not record the issue whose review decided it, so "
+            "the replacement cannot be required to belong to the same lifecycle as the source"
+        )
+    try:
+        ref = parse_issue_url(txn.issue_url)
+    except ConfigurationError as exc:
+        return f"the replan issue URL is unusable: {exc}"
+    if not ref.same_repository(repository):
+        return (
+            f"replan issue {ref.canonical} is not in {repository}; the transaction does not "
+            "belong to this run"
+        )
+    if not ref.same_target(held):
+        return (
+            f"replan issue {ref.canonical} is not the run's current issue {held.canonical}; "
+            "the transaction does not belong to this run"
+        )
+    return ""
+
+
+def _bind_to_run(what: str, url: str, repository: str, held: GitHubPullRequestRef) -> str:
+    """One identity rule for every PR the journal names as the source."""
+    try:
+        ref = parse_pr_url(url)
+    except ConfigurationError as exc:
+        return f"the {what} URL is unusable: {exc}"
+    if not ref.same_repository(repository):
+        return (
+            f"{what} {ref.canonical} is not in {repository}; the transaction does not belong "
+            "to this run"
+        )
+    if not ref.same_target(held):
+        return (
+            f"{what} {ref.canonical} is not the run's current PR {held.canonical}; the "
+            "transaction does not belong to this run"
+        )
+    return ""
+
+
+def verify_decision_point(pr: PRInfo, txn: ReplanTransaction, merge_base_sha: str) -> str:
+    """The source must still be the revision whose review decided the replan.
+
+    Checked once, before the transaction is prepared. ``REVIEW`` records the
+    HEAD and branch it reviewed; the checkpoint is then taken from GitHub, and
+    between those two moments a human (or a stray push) can move the source.
+    Superseding the moved source would close a revision this replan decision
+    never saw -- the accumulated findings belong to the reviewed revision, not
+    to whatever is on the branch now.
+
+    The PR read must also *be* the PR the decision names: the prepare step
+    reads it from ``state.current_pr_url``, and :func:`verify_run_binding`
+    has bound that to the decision, but the identity GitHub reports is the
+    fact, so it is compared here rather than assumed.
+
+    The base branch is compared with the HEAD and the branch: the diff the
+    review saw is HEAD against base, and retargeting the PR changes it at
+    an unchanged HEAD (#68). The merge base is compared with all three:
+    ``merge_base_sha`` is what GitHub reports for the PR's base and HEAD
+    now, and a base rewritten under its name moves it while the other three
+    read back equal, which is the same new diff by another route (#96).
+
+    An empty ``decision_pr_url``, ``decision_head_sha``, ``decision_branch``,
+    ``decision_base_ref`` or ``decision_merge_base_sha`` is itself a
+    refusal: without all five there is no proof the checkpoint is the
+    decision point. :meth:`ReplanTransaction.from_dict` refuses such a
+    journal at every stage; this is the same rule at the point of use, never
+    vacuous.
+    """
+    if not txn.decision_pr_url:
+        return (
+            "the replan transaction does not record the PR whose review decided it, so the "
+            "source cannot be proven to be the PR the findings belong to"
+        )
+    if not same_pr_url(pr.url, txn.decision_pr_url):
+        return (
+            f"source PR read back as {pr.url or '(none)'}, but the review that decided this "
+            f"replan ran on {txn.decision_pr_url}; the current work was never reviewed "
+            "against this decision"
+        )
+    if not txn.decision_head_sha:
+        return (
+            "the replan transaction does not record the reviewed HEAD that decided it, so the "
+            "source cannot be proven to be the revision the findings belong to"
+        )
+    if not txn.decision_branch:
+        return (
+            "the replan transaction does not record the reviewed branch that decided it, so the "
+            "source cannot be proven to be the revision the findings belong to"
+        )
+    if not txn.decision_base_ref:
+        return (
+            "the replan transaction does not record the base branch the review that decided it "
+            "was bound to, so the source cannot be proven to be the change the findings "
+            "belong to"
+        )
+    if not txn.decision_merge_base_sha:
+        return (
+            "the replan transaction does not record the merge base the review that decided it "
+            "was bound to, so the source cannot be proven to be the diff the findings belong to"
+        )
+    if not _same_sha(pr.head_sha, txn.decision_head_sha):
+        return (
+            f"source PR {txn.source_pr_url} is at HEAD {pr.head_sha or '(unreadable)'}, but the "
+            f"review that decided this replan ran on {txn.decision_head_sha}; the current work "
+            "was never reviewed against this decision"
+        )
+    if pr.head_ref != txn.decision_branch:
+        return (
+            f"source PR {txn.source_pr_url} is on branch {pr.head_ref!r}, but the review that "
+            f"decided this replan ran on {txn.decision_branch!r}"
+        )
+    if pr.base_ref != txn.decision_base_ref:
+        return (
+            f"source PR {txn.source_pr_url} targets base {pr.base_ref!r}, but the review that "
+            f"decided this replan was bound to base {txn.decision_base_ref!r}; the current "
+            "change was never reviewed against this decision"
+        )
+    if not _same_sha(merge_base_sha, txn.decision_merge_base_sha):
+        return (
+            f"source PR {txn.source_pr_url} has merge base {merge_base_sha or '(unreadable)'} "
+            f"with base {pr.base_ref!r}, but the review that decided this replan was bound to "
+            f"merge base {txn.decision_merge_base_sha}; base {pr.base_ref!r} was rewritten "
+            "under its name and the current diff was never reviewed against this decision"
+        )
+    return ""
+
+
+def verify_source_checkpoint(pr: PRInfo, txn: ReplanTransaction, merge_base_sha: str) -> str:
+    """The source PR must still be *exactly* what the transaction checkpointed.
+
+    Closing a PR is irreversible for the review evidence it carries, so this
+    is the compare half of a compare-and-swap: identity, OPEN state, branch,
+    base, the exact checkpointed HEAD and the merge base GitHub reports for
+    that base and HEAD now (``merge_base_sha``, read by the caller beside the
+    PR). Any drift — including a push that landed after the checkpoint, a
+    retarget to another base, a base rewritten under its name, and a close
+    performed by someone else — means the controller is no longer looking at
+    the implementation it decided to replace, and must not close it.
+    """
+    if not same_pr_url(pr.url, txn.source_pr_url):
+        return (
+            f"source PR identity mismatch: read {pr.url or '(none)'}, "
+            f"checkpoint {txn.source_pr_url}"
+        )
+    if pr.state == "MERGED":
+        return f"source PR {txn.source_pr_url} is already MERGED; refusing to supersede it"
+    if not pr.is_open:
+        return (
+            f"source PR {txn.source_pr_url} is {pr.state or '(unknown)'}, expected OPEN at the "
+            "checkpoint; it was not closed by this transaction"
+        )
+    drift = _source_branch_drift(pr, txn) or _source_base_drift(pr, txn)
+    if drift:
+        return drift
+    if not _same_sha(pr.head_sha, txn.source_head_sha):
+        return (
+            f"source PR {txn.source_pr_url} advanced from the checkpointed HEAD "
+            f"{txn.source_head_sha} to {pr.head_sha or '(unreadable)'}; the newer work was never "
+            "reviewed against this replan decision"
+        )
+    drift = _source_merge_base_drift(merge_base_sha, txn)
+    if drift:
+        return drift
+    # Defence in depth: the checkpoint is only allowed to hold the revision the
+    # review decided on, so a journal in which the two disagree is unusable.
+    if txn.decision_head_sha and not _same_sha(txn.source_head_sha, txn.decision_head_sha):
+        return (
+            f"checkpointed source HEAD {txn.source_head_sha} is not the reviewed HEAD "
+            f"{txn.decision_head_sha} that decided this replan"
+        )
+    if txn.decision_base_ref and txn.source_base_ref != txn.decision_base_ref:
+        return (
+            f"checkpointed source base {txn.source_base_ref!r} is not the base "
+            f"{txn.decision_base_ref!r} the review that decided this replan was bound to"
+        )
+    if txn.decision_merge_base_sha and not _same_sha(
+        txn.source_merge_base_sha, txn.decision_merge_base_sha
+    ):
+        return (
+            f"checkpointed source merge base {txn.source_merge_base_sha} is not the merge base "
+            f"{txn.decision_merge_base_sha} the review that decided this replan was bound to"
+        )
+    return ""
+
+
+def verify_target_pr(
+    pr: PRInfo,
+    txn: ReplanTransaction,
+    repository: str,
+    *,
+    require_checkpoint_head: bool,
+) -> str:
+    """Objective facts a replacement must satisfy, re-derived from GitHub.
+
+    ``require_checkpoint_head`` is off while the candidate is first being
+    bound (its HEAD and branch *become* the checkpoint) and on for every later
+    read, including the final read immediately before the destructive write;
+    on those reads the checkpointed branch must exist as well as match, for
+    the reason :func:`_source_branch_drift` gives for the source.
+    """
+    ref_canonical = _canonical(pr.url)
+    if not ref_canonical:
+        return f"replacement PR URL {pr.url!r} is not a pull-request URL"
+    if same_pr_url(ref_canonical, txn.source_pr_url):
+        return "replacement PR must differ from the superseded PR"
+    if txn.replacement_pr_url and not same_pr_url(ref_canonical, txn.replacement_pr_url):
+        return (
+            f"replacement PR identity mismatch: read {ref_canonical}, "
+            f"checkpoint {txn.replacement_pr_url}"
+        )
+    pr_repo = parse_pr_url(ref_canonical).repository
+    if pr_repo.lower() != repository.lower() or (
+        pr.repository and pr.repository.lower() != repository.lower()
+    ):
+        return f"replacement PR {ref_canonical} is not in {repository}"
+    if not pr.is_open:
+        return f"replacement PR {ref_canonical} is {pr.state or '(unknown)'}, expected OPEN"
+    if not pr.head_sha:
+        return f"replacement PR {ref_canonical} has no readable head SHA"
+    if not pr.head_ref or pr.head_ref == txn.source_branch:
+        return "replacement branch must be present and differ from the superseded branch"
+    if require_checkpoint_head and not txn.replacement_branch:
+        return (
+            f"the replan transaction records no branch for replacement PR {ref_canonical}, so "
+            "the verified checkpoint is incomplete"
+        )
+    if txn.replacement_branch and pr.head_ref != txn.replacement_branch:
+        return (
+            f"replacement PR {ref_canonical} moved from the checkpointed branch "
+            f"{txn.replacement_branch!r} to {pr.head_ref!r}"
+        )
+    if pr.base_ref != txn.base_branch:
+        return f"replacement PR base {pr.base_ref!r} != verified default branch {txn.base_branch!r}"
+    try:
+        issue = parse_issue_url(txn.issue_url)
+    except ConfigurationError as exc:
+        return f"replan transaction records no usable issue URL ({exc})"
+    if not issue.same_repository(repository):
+        # Linkage is a number within one repository, so an issue of another
+        # repository can never be what a PR here is linked to.
+        # ``verify_run_binding`` refuses such a journal before this is
+        # reached; this is the same rule at the point of use.
+        return f"replan issue {issue.canonical} is not in {repository}"
+    if issue.number not in pr.linked_issue_numbers:
+        return f"replacement PR {ref_canonical} is not linked to issue #{issue.number}"
+    # The replacement is the issue's implementation PR from here on, and the
+    # issue's implementation PR is identified by one durable claim everywhere
+    # (``claims.IMPLEMENTATION``): ANALYZE_EXECUTE adopts the open PR carrying
+    # it and refuses to persist one without it. A replacement without the
+    # marker would be activated here and then be invisible to the next entry
+    # after a lost state file, which launches a second implementation.
+    marked = scan(IMPLEMENTATION, pr.body or "")
+    if marked.defects:
+        return (
+            f"replacement PR {ref_canonical} carries an unreadable ai-implementation marker "
+            f"({'; '.join(marked.defects)})"
+        )
+    if not marked.claims:
+        return (
+            f"replacement PR {ref_canonical} does not carry the ai-implementation marker for "
+            f"issue #{issue.number}; without it no later entry could find it as the issue's PR"
+        )
+    if marked.claims[0].issue.identity != issue.identity:
+        return (
+            f"replacement PR {ref_canonical} carries the ai-implementation marker of "
+            f"{marked.claims[0].issue.canonical}, not of issue #{issue.number}"
+        )
+    if require_checkpoint_head and not _same_sha(pr.head_sha, txn.replacement_head_sha):
+        return (
+            f"replacement PR {ref_canonical} advanced from the verified HEAD "
+            f"{txn.replacement_head_sha} to {pr.head_sha}; it is no longer the implementation "
+            "the controller verified"
+        )
+    return ""
+
+
+def verify_sole_implementation_claimant(
+    open_prs: list[PRInfo], target_url: str, txn: ReplanTransaction, repository: str
+) -> str:
+    """The replacement is the issue's *only* open implementation claimant, or why not.
+
+    :func:`verify_target_pr` proves the replacement's own body carries the
+    issue's ``ai-implementation`` marker; this proves nothing else does. The
+    marker is the identity every ``ANALYZE_EXECUTE`` entry and read-back
+    finds the issue's PR by, and both refuse two claimants rather than
+    choose (github-safety.md, "Before/After ANALYZE_EXECUTE"). A replan that
+    installed one of two would therefore activate a PR precisely where the
+    entry fails closed, and the run would carry toward merge a choice the
+    controller never makes. So the same strict open listing the entry reads
+    is asked the same question at every checkpoint of the transaction:
+    exactly one open PR carries the marker, and it is the replacement.
+
+    The source is left out of the question, claims and defects alike: it is
+    the PR the replan is closing, it legitimately carries the marker (the
+    read-back that accepted it required it to), and the question is what
+    the entry will find once it is gone. Before the close that is a
+    prediction; after it, the listing no longer holds the source anyway.
+    Every other open PR counts, whatever its branch, linkage or age: a
+    second marked PR is ambiguity and an unreadable marker anywhere is
+    inconclusive, exactly as at entry.
+
+    ``open_prs`` must be a *complete* listing (one the client could not read
+    to the end is refused before it reaches here), because "nothing else
+    claims the issue" is not knowable from a partial set.
+    """
+    try:
+        issue = parse_issue_url(txn.issue_url)
+    except ConfigurationError as exc:
+        return f"replan transaction records no usable issue URL ({exc})"
+    if not issue.same_repository(repository):
+        return f"replan issue {issue.canonical} is not in {repository}"
+    others = [pr for pr in open_prs if not same_pr_url(pr.url, txn.source_pr_url)]
+    claimants = collect(IMPLEMENTATION, others, "open PR").claimants(
+        issue.identity, f"issue {issue.canonical}"
+    )
+    try:
+        holder = claimants.exactly_one()
+    except ClaimConflictError as exc:
+        return (
+            f"the replacement cannot be shown to be the one open PR implementing issue "
+            f"#{issue.number} (the superseded PR aside): {exc}; the next ANALYZE_EXECUTE "
+            "entry would refuse to choose, so the replan does not either"
+        )
+    if not same_pr_url(holder.obj.url, target_url):
+        return (
+            f"the open PR carrying the ai-implementation marker for issue #{issue.number} is "
+            f"{holder.obj.url}, not the replacement {target_url}"
+        )
+    return ""
+
+
+def verify_attestation(attestation: ReplanAttestation, txn: ReplanTransaction) -> str:
+    """The agent's published claim must satisfy the controller's requirements.
+
+    ``findings_considered`` is the acknowledgement invariant: the replacement
+    lifecycle may only supersede the source once the agent has stated it
+    accounted for every actionable finding the controller preserved. The
+    controller never lowers that requirement — a transaction is only prepared
+    when the evidence is provably complete.
+    """
+    if attestation.transaction_id != txn.transaction_id:
+        return (
+            f"attestation belongs to transaction {attestation.transaction_id!r}, "
+            f"not {txn.transaction_id!r}"
+        )
+    if attestation.execution_attempt != txn.expected_execution_attempt:
+        return (
+            f"attested execution_attempt {attestation.execution_attempt} != "
+            f"{txn.expected_execution_attempt} expected by the controller"
+        )
+    if not attestation.tests_passed:
+        return "the replacement attests tests_passed=false"
+    if attestation.findings_considered < txn.evidence_finding_count:
+        return (
+            f"the replacement attests it considered {attestation.findings_considered} of the "
+            f"{txn.evidence_finding_count} historical finding(s) the controller preserved"
+        )
+    if attestation.unique_constraints > attestation.findings_considered:
+        return (
+            f"attested unique_constraints {attestation.unique_constraints} exceeds "
+            f"findings_considered {attestation.findings_considered}"
+        )
+    return ""
+
+
+def verify_closed_source(pr: PRInfo, txn: ReplanTransaction, merge_base_sha: str) -> str:
+    """The source, re-read *after* the controller's close, is still the one it closed.
+
+    ``gh pr close`` carries no precondition, so the swap half of the
+    compare-and-swap is completed here instead: everything the pre-close read
+    established must still be true of the PR that is now closed, except the
+    state itself. A HEAD or branch that moved means a push landed inside the
+    write window, a base that moved means a retarget did, and a merge base
+    that moved (``merge_base_sha``, read by the caller for the closed PR's
+    base and HEAD) means the base was rewritten under its name, i.e. the
+    close destroyed the visibility of a change that no review ever saw -- the
+    caller undoes the close rather than accepting it.
+    """
+    if not same_pr_url(pr.url, txn.source_pr_url):
+        return (
+            f"source PR identity mismatch after the close: read {pr.url or '(none)'}, "
+            f"checkpoint {txn.source_pr_url}"
+        )
+    if pr.state != "CLOSED":
+        return (
+            f"source PR {txn.source_pr_url} is {pr.state or '(unknown)'} after this "
+            "transaction's close attempt; expected CLOSED"
+        )
+    when = " inside the close window"
+    drift = _source_branch_drift(pr, txn, when) or _source_base_drift(pr, txn, when)
+    if drift:
+        return drift
+    if not _same_sha(pr.head_sha, txn.source_head_sha):
+        return (
+            f"source PR {txn.source_pr_url} advanced from the checkpointed HEAD "
+            f"{txn.source_head_sha} to {pr.head_sha or '(unreadable)'} inside the close window; "
+            "the newer work was never reviewed against this replan decision"
+        )
+    return _source_merge_base_drift(merge_base_sha, txn, when)
+
+
+def verify_close_never_ran(closed_event_count: int, txn: ReplanTransaction) -> str:
+    """Why a source found OPEN under a recorded intent may not be closed now, or ``""``.
+
+    ``SUPERSEDE_INTENT`` proves an intended write, never a performed one, and
+    the receipt proves a performed one only when it was published: a crash
+    between ``gh pr close`` landing and the receipt, followed by a human
+    reopen, leaves an OPEN source with no receipt -- the same evidence a crash
+    *before* the close leaves -- and only the first of those is a human
+    decision a retry would override (R11-F1). Absence of a comment therefore
+    never licenses the write. What does is GitHub's own timeline: the intent
+    records the source's ``closed`` issue-event count, read immediately
+    before it was persisted, and issue events are append-only and cannot be
+    deleted by anyone, so ``closed_event_count`` -- the same count read now
+    -- is proof-grade either way (#69):
+
+    - higher than the watermark: a close landed after the intent, this
+      transaction's or a human's, and the PR is OPEN again, so a reopen
+      followed it and is the last word. Refused; never closed again.
+    - lower: impossible for an append-only log, so the watermark is not this
+      PR's (a substituted journal) or the listing was not read whole. Refused.
+    - equal: no close of any kind has happened since the intent. The write
+      never ran, and the caller may perform it -- through the same pre-close
+      revalidation as the first attempt, and at most ``MAX_CLOSE_ATTEMPTS``
+      times in total, so a close that keeps failing to land is handed to a
+      human rather than retried indefinitely.
+
+    Pure: the caller reads the count and persists the incremented attempt
+    before the write, exactly as the first intent was persisted.
+    """
+    if txn.stage is not ReplanStage.SUPERSEDE_INTENT:
+        return (
+            f"the replan transaction is at stage {txn.stage.value!r}, not under a recorded "
+            "close intent, so there is no close to retry"
+        )
+    if closed_event_count > txn.source_closed_event_count:
+        return (
+            f"source PR {txn.source_pr_url} is open under a recorded close intent for replan "
+            f"transaction {txn.transaction_id}, and its closed-event count rose from "
+            f"{txn.source_closed_event_count} at the intent to {closed_event_count}: a close "
+            "landed after the intent (this transaction's, or a human's) and the PR was reopened "
+            "afterwards, so the reopen is the last word and the controller will not close it "
+            "again"
+        )
+    if closed_event_count < txn.source_closed_event_count:
+        return (
+            f"source PR {txn.source_pr_url} reports {closed_event_count} closed event(s), fewer "
+            f"than the {txn.source_closed_event_count} the close intent recorded; issue events "
+            "cannot be deleted, so the recorded count is not this PR's or the listing was not "
+            "read whole, and the controller will not close on it"
+        )
+    if txn.close_attempts >= MAX_CLOSE_ATTEMPTS:
+        return (
+            f"source PR {txn.source_pr_url} is still open after {txn.close_attempts} close "
+            f"attempt(s) under replan transaction {txn.transaction_id}, none of which landed; "
+            "the close is retried at most once, so a human must look at why it does not land"
+        )
+    return ""
+
+
+def verify_target_marker(pr: PRInfo, txn: ReplanTransaction) -> str:
+    """The replacement's body still *proves* it is this transaction's replacement.
+
+    :func:`verify_target_pr` re-derives the objective facts (identity, state,
+    branch, base, linkage, HEAD); none of them is provenance. The marker is,
+    and a body can be edited after the controller verified it: dropping the
+    marker, or restating the attestation with different numbers, leaves every
+    objective fact valid while removing the only evidence that this PR belongs
+    to this replan. So the body is re-scanned on the final read, under exactly
+    the rules that bound it in the first place -- :func:`sole_attestation`,
+    literally the same function: one usable marker for this transaction and
+    nothing marker-shaped beside it, a valid marker for another transaction
+    included -- plus equality with the attestation the controller checkpointed
+    at ``VERIFIED``.
+    """
+    scan = scan_replan_markers(pr.body or "")
+    ref = _canonical(pr.url) or pr.url or "(none)"
+    attestation, defect = sole_attestation(scan, txn.transaction_id, ref, "replacement PR")
+    if defect:
+        return defect
+    if attestation is None:
+        if scan.malformed:
+            return (
+                f"replacement PR {ref} carries an unusable replan marker "
+                f"({'; '.join(scan.malformed)})"
+            )
+        return (
+            f"replacement PR {ref} no longer carries the marker for replan transaction "
+            f"{txn.transaction_id}, so it can no longer be proven to be its replacement"
+        )
+    drift = verify_attestation(attestation, txn)
+    if drift:
+        return drift
+    if (
+        attestation.findings_considered != txn.attested_findings_considered
+        or attestation.unique_constraints != txn.attested_unique_constraints
+    ):
+        return (
+            f"replacement PR {ref} now attests findings_considered="
+            f"{attestation.findings_considered}/unique_constraints="
+            f"{attestation.unique_constraints}, but the controller verified "
+            f"{txn.attested_findings_considered}/{txn.attested_unique_constraints}"
+        )
+    return ""
+
+
+@dataclass(frozen=True)
+class CandidateSelection:
+    """The result of looking for this transaction's replacement on GitHub."""
+
+    disposition: Disposition
+    pr: PRInfo | None = None
+    attestation: ReplanAttestation | None = None
+    reason: str = ""
+
+
+def select_bound_candidate(open_prs: list[PRInfo], txn: ReplanTransaction) -> CandidateSelection:
+    """Find the one PR causally bound to ``txn``, or fail closed.
+
+    ``open_prs`` must be *every* open PR in the repository, not the subset
+    that already looks related to the issue: an agent creates the PR and links
+    it to the issue in separate operations, so a crash between the two leaves
+    a marked replacement that no issue-shaped filter can see. Missing it would
+    report "no candidate" and start a second implementation attempt — the one
+    outcome crash idempotency forbids. Found here, it is judged on its merits
+    instead: :func:`verify_target_pr` refuses it for the missing linkage, and
+    the phase blocks for a human with the PR named.
+
+    Binding is positive proof, never shape: a candidate must carry a marker
+    for this exact transaction id, and must have been *created* after that id
+    existed. Everything else is ignored, so an unrelated open PR neither gets
+    adopted nor blocks a healthy replan. Two bound candidates are ambiguous,
+    and a candidate whose marker is unusable in any way -- malformed, doubled,
+    accompanied by a valid marker for a different transaction, or sitting on a
+    PR that predates the transaction -- is a conclusive rejection.
+
+    The source PR is not adoptable, but it is still *read*: a marker the agent
+    put on the PR being superseded is a refusal, and skipping the body would
+    downgrade it to "no candidate exists" -- the observation that starts a
+    second implementation attempt.
+
+    Novelty is decided by ``pr_number_watermark`` rather than by the snapshot
+    of issue PRs: GitHub numbers PRs from a monotonic per-repository counter,
+    so "number <= watermark" covers every PR that already existed, including
+    ones that were closed, unlinked, or named nothing like this issue at
+    ``PREPARED`` and were only linked to it afterwards.
+    """
+    if not TRANSACTION_ID_RE.match(txn.transaction_id):
+        # No id means nothing can be causally bound to this transaction; a
+        # marker matching "" would otherwise adopt an arbitrary PR.
+        return CandidateSelection(
+            Disposition.REJECTED,
+            reason=(
+                "replan transaction has no usable transaction id; no PR can be proven to be "
+                "its replacement"
+            ),
+        )
+    if txn.pr_number_watermark < 1:
+        # Without the watermark there is no proof any candidate postdates the
+        # transaction id, and provenance would fall back to shape.
+        return CandidateSelection(
+            Disposition.REJECTED,
+            reason=(
+                f"replan transaction {txn.transaction_id} has no pull-request number watermark, "
+                "so no PR can be proven to have been created after it"
+            ),
+        )
+    # Membership and the source comparison are by GitHub identity: a listing
+    # that spells the repository differently from the checkpoint names the
+    # same PRs. ``source`` is None for an unusable checkpoint and a listed
+    # PR's identity never is, so the two can never compare equal.
+    preexisting = {ident for url in txn.preexisting_pr_urls if (ident := _identity(url))}
+    source = _identity(txn.source_pr_url)
+    bound: list[tuple[PRInfo, ReplanAttestation]] = []
+    malformed: list[str] = []
+    for pr in open_prs:
+        canonical = _canonical(pr.url)
+        if not canonical:
+            continue
+        identity = _identity(pr.url)
+        scan = scan_replan_markers(pr.body or "")
+        under_watermark = pr.number <= txn.pr_number_watermark
+        predates = under_watermark or identity in preexisting
+        if identity == source:
+            # Read before it is excluded: a marker the agent put on the PR
+            # being superseded must be refused, not silently reported as
+            # "no candidate" -- see :func:`source_marker_defect`.
+            defect = source_marker_defect(scan, txn.transaction_id, canonical, preexisting=predates)
+            if defect:
+                return CandidateSelection(Disposition.REJECTED, reason=defect)
+            continue
+        mine = [a for a in scan.attestations if a.transaction_id == txn.transaction_id]
+        if predates:
+            if mine:
+                # The id did not exist when this PR was created, so a match
+                # means the marker was copied. Never adopt it.
+                how = (
+                    f"its number {pr.number} is at or below the watermark {txn.pr_number_watermark}"
+                    if under_watermark
+                    else "it was in the snapshot of the issue's open PRs"
+                )
+                return CandidateSelection(
+                    Disposition.REJECTED,
+                    reason=(
+                        f"PR {canonical} already existed when replan transaction "
+                        f"{txn.transaction_id} was prepared ({how}) but carries its marker; "
+                        "refusing to adopt a pre-existing PR as a replacement"
+                    ),
+                )
+            continue
+        # Exactly one attestation, and it is ours: a doubled marker, an
+        # unusable one beside the valid one, and a valid marker for another
+        # transaction are all conclusive refusals rather than adoptions.
+        attestation, defect = sole_attestation(scan, txn.transaction_id, canonical)
+        if defect:
+            return CandidateSelection(Disposition.REJECTED, reason=defect)
+        if scan.malformed:
+            malformed.append(f"{canonical}: {'; '.join(scan.malformed)}")
+        if attestation is not None:
+            bound.append((pr, attestation))
+    if len(bound) > 1:
+        urls = ", ".join(sorted(_canonical(pr.url) for pr, _ in bound))
+        return CandidateSelection(
+            Disposition.AMBIGUOUS,
+            reason=(
+                f"{len(bound)} open PRs claim replan transaction {txn.transaction_id}: {urls}. "
+                "The controller cannot tell which one is the replacement"
+            ),
+        )
+    if bound:
+        pr, attestation = bound[0]
+        return CandidateSelection(Disposition.OK, pr=pr, attestation=attestation)
+    if malformed:
+        return CandidateSelection(
+            Disposition.REJECTED,
+            reason="unusable replan marker on " + "; ".join(malformed),
+        )
+    return CandidateSelection(Disposition.NONE)
+
+
+def find_non_open_claimant(all_prs: list[PRInfo], txn: ReplanTransaction) -> CandidateSelection:
+    """A marker-bearing non-open PR for ``txn``, or NONE when there is none.
+
+    ``select_bound_candidate`` only sees open PRs. A replacement the first
+    agent created and that was then closed (by a human, or by the agent
+    itself) is invisible there, and reporting "no candidate" would invoke the
+    agent a second time -- the one outcome crash idempotency forbids. This
+    scans the exhaustive repository-wide set (open, closed and merged alike)
+    for a PR carrying this transaction's marker that is not open, and turns
+    it into a durable rejection naming the PR, never into absence.
+
+    Pre-existing non-open PRs carrying a copied marker are reported as
+    pre-existing, exactly as the open path does; post-watermark ones are
+    reported with their observed state (CLOSED/MERGED), because they prove a
+    first implementation attempt already happened. A post-watermark PR whose
+    marker is *unusable* is reported the same way rather than skipped: the
+    marker protocol classifies by name, so a complete marker with a garbage
+    payload is broken evidence, never absent evidence. The source PR is read
+    for its own marker here too, for the reason
+    :func:`select_bound_candidate` gives.
+    """
+    if not TRANSACTION_ID_RE.match(txn.transaction_id):
+        return CandidateSelection(Disposition.NONE)
+    if txn.pr_number_watermark < 1:
+        return CandidateSelection(Disposition.NONE)
+    # Membership and the source comparison are by GitHub identity: a listing
+    # that spells the repository differently from the checkpoint names the
+    # same PRs. ``source`` is None for an unusable checkpoint and a listed
+    # PR's identity never is, so the two can never compare equal.
+    preexisting = {ident for url in txn.preexisting_pr_urls if (ident := _identity(url))}
+    source = _identity(txn.source_pr_url)
+    for pr in all_prs:
+        if pr.is_open:
+            continue
+        canonical = _canonical(pr.url)
+        if not canonical:
+            continue
+        identity = _identity(pr.url)
+        scan = scan_replan_markers(pr.body or "")
+        under_watermark = pr.number <= txn.pr_number_watermark
+        predates = under_watermark or identity in preexisting
+        if identity == source:
+            defect = source_marker_defect(scan, txn.transaction_id, canonical, preexisting=predates)
+            if defect:
+                return CandidateSelection(Disposition.REJECTED, reason=defect)
+            continue
+        mine = [a for a in scan.attestations if a.transaction_id == txn.transaction_id]
+        if not mine and not scan.malformed:
+            continue
+        if predates and not mine:
+            # A PR that predates the transaction id cannot be evidence about
+            # it, and the open path ignores its unusable markers for exactly
+            # the same reason. Only a *copied* valid marker is reported below.
+            continue
+        if not mine:
+            # A complete marker with this name whose payload is not a usable
+            # attestation is evidence of a first attempt, not absence of one.
+            # Classified here as strictly as on the open path, because the
+            # alternative is invoking the agent a second time.
+            return CandidateSelection(
+                Disposition.REJECTED,
+                reason=(
+                    f"PR {canonical} carries an unusable replan marker "
+                    f"({'; '.join(scan.malformed)}) and is {pr.state or '(unknown)'}, "
+                    "expected OPEN; complete marker evidence is never absence, so this "
+                    "must be decided by a human, not by invoking the agent again"
+                ),
+            )
+        if predates:
+            how = (
+                f"its number {pr.number} is at or below the watermark {txn.pr_number_watermark}"
+                if under_watermark
+                else "it was in the snapshot of the issue's open PRs"
+            )
+            return CandidateSelection(
+                Disposition.REJECTED,
+                reason=(
+                    f"PR {canonical} already existed when replan transaction "
+                    f"{txn.transaction_id} was prepared ({how}) but carries its marker; "
+                    "refusing to adopt a pre-existing PR as a replacement"
+                ),
+            )
+        return CandidateSelection(
+            Disposition.REJECTED,
+            reason=(
+                f"PR {canonical} carries the marker for replan transaction "
+                f"{txn.transaction_id} but is {pr.state or '(unknown)'}, expected OPEN; "
+                "a first replacement attempt already exists and must be decided by a human, "
+                "not by invoking the agent again"
+            ),
+        )
+    return CandidateSelection(Disposition.NONE)