autoforge-cli 0.1.0a0__py3-none-any.whl

autoforge/github.py

@@ -0,0 +1,3402 @@
+"""GitHub abstraction over the `gh` CLI (verification reads + controller-owned writes).
+
+Business logic must use these typed objects, never parse raw `gh` JSON
+inline. The controller reads GitHub through this client to verify what an
+agent claims, and it performs every GitHub write itself through it:
+
+- the typed effect writes of ADR 0004 (D12.2), one method per GitHub effect
+  kind: :meth:`GitHubClient.create_pull_request` (K2, K7),
+  :meth:`GitHubClient.write_pr_body` (K3),
+  :meth:`GitHubClient.create_pr_comment` (K4),
+  :meth:`GitHubClient.create_issue` (K5),
+  :meth:`GitHubClient.write_issue_body` (K6) and
+  :meth:`GitHubClient.create_issue_comment` (K8). Each is issued exactly
+  once, outside the transient-retry loop that reads keep (D4.3): an
+  ambiguous outcome is never re-sent, the caller reconciles it by reading
+  the target back by its identity. The payload travels on stdin, never in
+  argv, and the repository is named in the API path (D7.4). What a write
+  returns is informational; the caller's read-back is the evidence;
+- the writes that keep their own mechanisms (D5.4):
+  :meth:`GitHubClient.merge_pr`, always behind the safety gate and bound to
+  the reviewed HEAD via ``--match-head-commit``, and the merged PR's remote
+  head branch deletion behind ``merge.delete_branch``,
+  :meth:`GitHubClient.delete_branch_ref` (#283);
+  :meth:`GitHubClient.disable_auto_merge`; :meth:`GitHubClient.close_pr`,
+  its receipt and the compensating :meth:`GitHubClient.reopen_pr` for a
+  verified replacement lifecycle, never deleting a branch; and the EPIC
+  roadmap splice, :meth:`GitHubClient.edit_issue_body`.
+
+Every call goes through `gh` except the exact reads (#327):
+:meth:`GitHubClient.get_pr_exact`, :meth:`GitHubClient.get_issue_exact` and
+:meth:`GitHubClient.get_comment_exact` read one object from GitHub's REST
+API directly (:func:`https_get`), with the credential `gh auth token`
+prints, because `gh` rewrites the text it prints and an effect's read-back
+must compare GitHub's own bytes. They are read-only and bounded.
+
+Every `gh` process starts in an empty directory of its own, never in the
+operator's checkout (:func:`gh_workdir`, #283): `gh` runs git where it is
+started, and nothing it is asked here needs a local repository.
+"""
+
+from __future__ import annotations
+
+import functools
+import http.client
+import io
+import json
+import os
+import re
+import shutil
+import ssl
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable, Iterator, Sequence
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import NoReturn
+from urllib.parse import quote, urlencode
+
+from .errors import (
+    ConfigurationError,
+    GitHubChecksAccessError,
+    GitHubError,
+    GitHubNotFoundError,
+    GitHubPlanLimitedError,
+    GitHubUnavailableError,
+    GitHubWrongTargetError,
+)
+from .executor import ExecutionRequest, ExecutionResult, execute
+from .locking import assert_shared_git_lock_free
+from .redaction import redact
+from .validation import (
+    GitHubCommentRef,
+    GitHubIssueRef,
+    GitHubPullRequestRef,
+    GitHubRef,
+    parse_api_issue_url,
+    parse_api_repository_url,
+    parse_comment_url,
+    parse_github_url,
+    parse_issue_url,
+    parse_pr_url,
+)
+
+# Transient `gh` failures: the same read may well succeed later, so the engine
+# treats them as *inconclusive* (bounded re-checks) instead of conclusive.
+# Phrase markers cover network-level errors (as the Go runtime behind `gh`
+# reports them: ``dial tcp ...: connect: network is unreachable``, ``lookup
+# api.github.com: temporary failure in name resolution``, ...) and the reason
+# phrases GitHub attaches to server-side / throttling statuses; the HTTP
+# status itself is matched as a whole class (every 5xx, plus 429) rather than
+# an enumerated list, so e.g. ``HTTP 500`` is not silently conclusive. `gh`
+# prints the status as ``HTTP 502: Bad Gateway`` (GraphQL) or ``gh: Bad
+# Gateway (HTTP 502)`` (REST); both shapes are matched, bare numbers elsewhere
+# in the message (PR numbers, SHAs) are not.
+_TRANSIENT_MARKERS = (
+    # -- connection / socket level (OS errno strings as surfaced by Go's net package)
+    "timeout",
+    "timed out",
+    "connection reset",
+    "connection refused",
+    "connection aborted",
+    "broken pipe",
+    "unexpected eof",
+    "network is unreachable",
+    "network is down",
+    "no route to host",
+    "host is down",
+    # Every `dial tcp ...` error is a failure to *open* the connection, never an
+    # answer from GitHub, so the whole family is transient even when the
+    # trailing errno phrase is one not listed here.
+    "dial tcp",
+    "temporarily unavailable",
+    "tls handshake",
+    # -- name resolution (Go resolver / glibc phrases)
+    "no such host",
+    "temporary failure in name resolution",
+    "server misbehaving",
+    # `gh` wraps any connection-level error (whatever host is configured) as
+    # ``error connecting to <host>\ncheck your internet connection or ...``.
+    "error connecting to",
+    # -- GitHub-side throttling / server errors
+    "rate limit",
+    "too many requests",
+    "internal server error",
+    "bad gateway",
+    "service unavailable",
+    "gateway timeout",
+    "gateway time-out",
+)
+_TRANSIENT_HTTP_STATUS = re.compile(r"\bhttp\s+(?:5\d\d|429)\b")
+
+
+def is_transient_gh_failure(stderr: str) -> bool:
+    """Whether a failed `gh` invocation's stderr describes a transient failure."""
+    text = stderr.lower()
+    return any(m in text for m in _TRANSIENT_MARKERS) or bool(_TRANSIENT_HTTP_STATUS.search(text))
+
+
+# Conclusive "does not exist" answers. GraphQL (`gh issue view`, `gh pr view`)
+# says ``Could not resolve to an Issue with the number of 999.``; REST says
+# ``HTTP 404: Not Found``; `gh pr` commands say ``could not find pull request``.
+# A private object the token cannot see is reported the same way by GitHub.
+_NOT_FOUND_MARKERS = (
+    "could not resolve to a",
+    "could not find",
+)
+_NOT_FOUND_HTTP_STATUS = re.compile(r"\bhttp\s+404\b")
+
+
+def is_not_found_gh_failure(stderr: str) -> bool:
+    """Whether a failed `gh` invocation's stderr says the object does not exist."""
+    text = stderr.lower()
+    return any(m in text for m in _NOT_FOUND_MARKERS) or bool(_NOT_FOUND_HTTP_STATUS.search(text))
+
+
+# Conclusive "you may not read this" answers: no credentials at all (`gh`
+# prints ``To get started with GitHub CLI, please run:  gh auth login``),
+# rejected credentials (``HTTP 401: Bad credentials``) or a token that cannot
+# see the object (``HTTP 403``, ``Must have admin rights``, ``Resource not
+# accessible by integration``). A read-only diagnostic distinguishes these
+# from a *negative answer*: they say nothing about the repository, only about
+# what this token may see of it. GitHub's plan-entitlement 403 is not one of
+# them (#289, :func:`is_plan_limited_gh_failure`): it is about the plan, and
+# no token permission changes it.
+_ACCESS_DENIED_MARKERS = (
+    "gh auth login",
+    "bad credentials",
+    "requires authentication",
+    "must have admin",
+    "resource not accessible",
+    "forbidden",
+    "unauthorized",
+)
+_ACCESS_DENIED_HTTP_STATUS = re.compile(r"\bhttp\s+40[13]\b")
+
+
+def is_access_denied_gh_failure(stderr: str) -> bool:
+    """Whether a failed `gh` invocation's stderr says the token may not read the object.
+
+    A plan limitation is not (#289): its HTTP 403 names a paid plan, and
+    no token permission changes it.
+    """
+    if is_plan_limited_gh_failure(stderr):
+        return False
+    text = stderr.lower()
+    return any(m in text for m in _ACCESS_DENIED_MARKERS) or bool(
+        _ACCESS_DENIED_HTTP_STATUS.search(text)
+    )
+
+
+# GitHub refusing a credential the check results of a PR (#291). GraphQL
+# answers the CheckRun (or StatusContext) node inside ``statusCheckRollup``
+# with ``Resource not accessible by personal access token (<path>)`` -- a
+# fine-grained token on a private repository, which cannot be given Checks:
+# read -- and `gh pr view` then fails the whole read. A GitHub App
+# installation token without Checks: read gets the same refusal worded "by
+# integration": the same fact (this credential may not read these check
+# results, the PR itself is readable), so it is the same class. The match
+# is narrow: the phrase must name one of those two credentials and the
+# GraphQL path in parentheses after it must run through
+# ``statusCheckRollup``. The same phrase on any other path (a comment, a
+# label), or a bare ``HTTP 403``, is not a checks refusal and keeps its
+# ordinary classification.
+_CHECKS_ACCESS_DENIED = re.compile(
+    r"resource not accessible by (personal access token|integration)\s*"
+    r"\(([^()\n]*\bstatuscheckrollup\b[^()\n]*)\)",
+    re.IGNORECASE,
+)
+
+
+def checks_access_denial(stderr: str) -> str:
+    """The credential GitHub refused a PR's check results, or "" (#291).
+
+    ``personal access token`` or ``integration``, read from GitHub's own
+    refusal of a ``statusCheckRollup`` path; anything else is "".
+    """
+    match = _CHECKS_ACCESS_DENIED.search(stderr or "")
+    return match.group(1).lower() if match else ""
+
+
+def is_checks_access_denied_gh_failure(stderr: str) -> bool:
+    """Whether a failed `gh` invocation's stderr is GitHub refusing a PR's check results."""
+    return bool(checks_access_denial(stderr))
+
+
+def checks_access_remedy(credential: str) -> str:
+    """What lets the controller read check results, for the credential GitHub refused (#291).
+
+    The engine's BLOCKED reason and `doctor`'s checks row say the same.
+    """
+    if credential == "integration":
+        return (
+            "a GitHub App installation token needs Checks: read on this repository: grant "
+            "it, or run AutoForge with `gh auth login` (an OAuth login) or a classic token "
+            "with the `repo` scope"
+        )
+    return (
+        "a fine-grained personal access token cannot be given Checks: read, so on a "
+        "private repository whose pull requests have check runs run AutoForge with "
+        "`gh auth login` (an OAuth login) or a classic token with the `repo` scope"
+    )
+
+
+# GitHub's plan does not offer the feature (#289): on GitHub Free a private
+# repository has no rulesets and no classic branch protection, and GitHub
+# answers those endpoints with ``HTTP 403 "Upgrade to GitHub Pro or make
+# this repository public to enable this feature."`` to every caller, the
+# owner's admin login included. That is about the plan, not about the
+# token, and no permission changes it. Matched narrowly: GitHub's own
+# sentence naming a paid plan (Pro, Team or Enterprise) *and* an HTTP 403;
+# any other 403 is an ordinary access refusal.
+_PLAN_LIMITED = re.compile(
+    r"\bupgrade to github (?:pro|team|enterprise)\b[^.\n]{0,80}?\bto enable this feature\b",
+    re.IGNORECASE,
+)
+_HTTP_403 = re.compile(r"\bhttp\s+403\b", re.IGNORECASE)
+
+
+def is_plan_limited_gh_failure(stderr: str) -> bool:
+    """Whether a failed `gh` invocation's stderr is GitHub's plan-entitlement 403."""
+    text = stderr or ""
+    return bool(_PLAN_LIMITED.search(text)) and bool(_HTTP_403.search(text))
+
+
+# The oldest `gh` the client works with. `gh api --paginate --slurp` (the
+# page-of-pages listing behind every paginated read: branch rules in `doctor`,
+# a PR's changed files at the merge gate) arrived in 2.48.0; an older `gh`
+# rejects the flag, so those reads fail conclusively instead of paginating.
+GH_MIN_VERSION = (2, 48, 0)
+_GH_VERSION_RE = re.compile(r"^gh version (\d+)\.(\d+)\.(\d+)\b")
+
+
+def parse_gh_version(text: str) -> tuple[int, int, int] | None:
+    """The ``X.Y.Z`` of a `gh --version` output's first line, or None if unparsable.
+
+    Only the shape `gh` prints (``gh version 2.48.0 (2024-04-09)``) is read;
+    anything else is "unknown", never a guess in either direction.
+    """
+    first = (text or "").strip().splitlines()
+    match = _GH_VERSION_RE.match(first[0]) if first else None
+    if match is None:
+        return None
+    major, minor, patch = (int(part) for part in match.groups())
+    return (major, minor, patch)
+
+
+@dataclass
+class RepoInfo:
+    name_with_owner: str
+    default_branch: str = ""
+
+
+@dataclass
+class IssueInfo:
+    url: str
+    number: int
+    title: str
+    state: str  # OPEN | CLOSED
+    body: str = ""
+    repository: str = ""
+
+    @property
+    def is_open(self) -> bool:
+        return self.state == "OPEN"
+
+
+_CHECK_OK_CONCLUSIONS = frozenset({"SUCCESS", "NEUTRAL", "SKIPPED"})
+_CHECK_PENDING_STATES = frozenset(
+    {"QUEUED", "IN_PROGRESS", "PENDING", "WAITING", "REQUESTED", "EXPECTED"}
+)
+
+
+@dataclass
+class CheckInfo:
+    name: str
+    state: str  # CheckRun: COMPLETED | IN_PROGRESS | ... ; StatusContext: SUCCESS | PENDING | ...
+    conclusion: str = ""  # CheckRun only: SUCCESS | FAILURE | ...
+    # Where GitHub says the result came from. For a GitHub Actions check run
+    # this is ``https://github.com/<owner>/<repo>/actions/runs/<id>/job/<job>``
+    # and names the exact workflow run; the merge gate uses it to verify the
+    # *definition* that produced a green required check (see
+    # :func:`parse_actions_run_url`). Empty for a legacy commit status.
+    details_url: str = ""
+    # GitHub's ``__typename`` of the rollup entry: ``CheckRun`` (a check run,
+    # what a fine-grained token is refused on a private repository, #291) or
+    # ``StatusContext`` (a legacy commit status); "" when GitHub named none.
+    kind: str = ""
+
+    @property
+    def actions_run(self) -> ActionsRunRef | None:
+        return parse_actions_run_url(self.details_url)
+
+    @property
+    def outcome(self) -> str:
+        """``success`` | ``pending`` | ``failure`` | ``unknown`` (fail closed).
+
+        Covers both GitHub check runs (``status``/``conclusion``) and legacy
+        commit statuses (``state`` only). Anything unrecognised is ``unknown``
+        and callers must treat it as not passing.
+        """
+        state = (self.state or "").upper()
+        conclusion = (self.conclusion or "").upper()
+        if state == "COMPLETED":
+            if conclusion in _CHECK_OK_CONCLUSIONS:
+                return "success"
+            return "failure" if conclusion else "unknown"
+        if state in _CHECK_PENDING_STATES:
+            return "pending"
+        if state == "SUCCESS" and not conclusion:
+            return "success"
+        if state in ("FAILURE", "ERROR") and not conclusion:
+            return "failure"
+        return "unknown"
+
+    @property
+    def succeeded(self) -> bool:
+        """Whether this entry reports an actual success (#289).
+
+        A check run that completed with ``SUCCESS``, or a commit status in
+        state ``SUCCESS``. ``NEUTRAL`` and ``SKIPPED`` are an ``outcome`` of
+        ``success`` (they fail nothing) but not a success: the merge gate
+        needs at least one entry that is.
+        """
+        state = (self.state or "").upper()
+        conclusion = (self.conclusion or "").upper()
+        if state == "COMPLETED":
+            return conclusion == "SUCCESS"
+        return state == "SUCCESS" and not conclusion
+
+
+@dataclass(frozen=True)
+class ActionsRunRef:
+    """A GitHub Actions workflow run named by a check's details URL."""
+
+    repository: str  # owner/repo, as written in the URL
+    run_id: int
+
+
+_ACTIONS_RUN_URL = re.compile(
+    r"^https://github\.com/([A-Za-z0-9_.-]+)/([A-Za-z0-9_.-]+)/actions/runs/([1-9][0-9]*)(?:/.*)?$"
+)
+
+
+def parse_actions_run_url(url: str) -> ActionsRunRef | None:
+    """``https://github.com/<owner>/<repo>/actions/runs/<id>[/job/<n>...]`` or None.
+
+    Anything else (a legacy status target, an external CI dashboard, an
+    empty URL) is ``None``: the check did not come from a GitHub Actions run
+    the controller can read back, which is a fact for the caller to refuse
+    on, not a shape to guess around.
+    """
+    m = _ACTIONS_RUN_URL.match(url or "")
+    if not m:
+        return None
+    return ActionsRunRef(repository=f"{m.group(1)}/{m.group(2)}", run_id=int(m.group(3)))
+
+
+@dataclass(frozen=True)
+class WorkflowRunInfo:
+    """One GitHub Actions workflow run, as the REST API reports it."""
+
+    id: int
+    repository: str  # owner/repo the run belongs to (where its workflow file lives)
+    path: str  # workflow file, e.g. ``.github/workflows/ci.yml``
+    workflow_id: int
+    event: str  # ``push`` | ``pull_request`` | ...
+    head_sha: str  # lower-case; for ``pull_request`` runs the PR head, not the merge commit
+    head_branch: str
+    status: str  # ``completed`` | ``in_progress`` | ``queued`` | ...
+    conclusion: str  # ``success`` | ``failure`` | ``cancelled`` | ... ; "" while not completed
+    run_attempt: int = 1
+
+    @property
+    def completed(self) -> bool:
+        return self.status == "completed"
+
+
+@dataclass(frozen=True)
+class WorkflowJob:
+    """A job of a workflow run: its name and its step names in order.
+
+    Step names are what GitHub shows: a ``name:`` when the step has one,
+    otherwise ``Run <command>`` / ``Run <action>``, so an unnamed ``run:``
+    whose command changed is visible as a different step name.
+    """
+
+    name: str
+    steps: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class WorkflowRunJobs:
+    """The jobs of one run and GitHub's own count, so a short listing shows."""
+
+    jobs: tuple[WorkflowJob, ...]
+    total: int
+
+    @property
+    def complete(self) -> bool:
+        return len(self.jobs) == self.total
+
+    def structure(self) -> tuple[tuple[str, tuple[str, ...]], ...]:
+        """``((job name, step names), ...)`` sorted by job name.
+
+        GitHub lists jobs in no fixed order (matrix legs start in parallel),
+        so two runs of one definition compare equal only on the sorted shape.
+        """
+        return tuple(sorted((job.name, job.steps) for job in self.jobs))
+
+
+@dataclass(frozen=True)
+class WorkflowRuns:
+    """The runs one listing matched and GitHub's own count, so a short listing shows."""
+
+    runs: tuple[WorkflowRunInfo, ...]
+    total: int
+
+    @property
+    def complete(self) -> bool:
+        return len(self.runs) == self.total
+
+
+@dataclass
+class CommentInfo:
+    id: int
+    url: str
+    body: str
+    author: str = ""
+    created_at: str = ""
+    parent_url: str = ""  # canonical issue/PR URL this comment belongs to
+
+
+@dataclass
+class PRInfo:
+    url: str
+    number: int
+    title: str
+    state: str  # OPEN | CLOSED | MERGED
+    head_sha: str
+    base_ref: str = ""
+    head_ref: str = ""
+    mergeable: str = ""  # MERGEABLE | CONFLICTING | UNKNOWN
+    # CLEAN | HAS_HOOKS | UNSTABLE | BLOCKED | BEHIND | DIRTY | DRAFT | UNKNOWN
+    merge_state_status: str = ""
+    auto_merge_enabled: bool = False  # GitHub auto-merge is armed on this PR
+    is_draft: bool = False
+    body: str = ""
+    repository: str = ""
+    head_repository: str = ""
+    linked_issue_numbers: list[int] = field(default_factory=list)
+    # The check results of the PR's head as GitHub reported them, or None
+    # when this read did not request them (#291). Only
+    # :meth:`GitHubClient.get_pr_with_checks` fills it: ``[]`` is "read, and
+    # GitHub reports no check", a list is what was read. An identity read
+    # (:meth:`GitHubClient.get_pr`, every listing) leaves it None, so a
+    # caller that needs checks can never mistake "not read" (or "refused",
+    # which raises :class:`GitHubChecksAccessError`) for "no checks".
+    checks: list[CheckInfo] | None = None
+
+    @property
+    def is_open(self) -> bool:
+        return self.state == "OPEN"
+
+    @property
+    def checks_read(self) -> bool:
+        """Whether this PRInfo carries the check results GitHub reported (possibly none)."""
+        return self.checks is not None
+
+
+@dataclass(frozen=True)
+class CreatedObject:
+    """What GitHub's reply to a controller write says it wrote (ADR 0004 D12.2).
+
+    Informational only: a caller never treats it as evidence. The effect's
+    completion is the caller's read-back of the target by its identity
+    (D2.1), exactly as when the reply was lost.
+
+    ``url`` is canonical: an issue or PR URL, or for a comment the
+    ``...#issuecomment-<id>`` URL. ``number`` is the issue or PR number, and
+    ``None`` for a comment (its id is in the URL).
+    """
+
+    url: str
+    number: int | None
+
+
+@dataclass(frozen=True)
+class ChangedFile:
+    """One file a PR changes, with the path it had before a rename or copy.
+
+    A rename is reported by GitHub as a single changed file carrying both
+    ends, not as a delete plus an add, so ``previous_path`` is the only place
+    the path the PR *removed* appears.
+
+    A copy carries a former path too, and is deliberately not distinguished:
+    treating both ends as touched can at worst refuse something harmless,
+    while reading ``status`` to tell them apart would make a caller that
+    refuses depend on GitHub classifying the change the way it expects.
+    """
+
+    path: str
+    previous_path: str = ""
+
+    @property
+    def paths(self) -> tuple[str, ...]:
+        """Every path this change touches -- both ends of a rename."""
+        if self.previous_path and self.previous_path != self.path:
+            return (self.path, self.previous_path)
+        return (self.path,)
+
+
+@dataclass(frozen=True)
+class ChangedFiles:
+    """The files a PR touches, and whether that listing is provably complete.
+
+    Every page of the listing is read, but GitHub serves at most 3000 files
+    of a PR through the files endpoint, so a listing shorter than
+    ``total`` says nothing about the files it does not contain. A caller that
+    uses this to *refuse* something must fail closed when :attr:`complete` is
+    false rather than read absence as proof.
+    """
+
+    files: tuple[ChangedFile, ...]
+    total: int
+
+    @property
+    def paths(self) -> tuple[str, ...]:
+        """Every path the PR touches, the former path of a rename included."""
+        return tuple(path for file in self.files for path in file.paths)
+
+    @property
+    def complete(self) -> bool:
+        # Counted in *files*, never in paths: a rename is one file and two
+        # paths, and GitHub's ``changedFiles`` counts files.
+        return len(self.files) >= self.total
+
+
+@dataclass(frozen=True)
+class MergeQueueStatus:
+    """Merge-queue facts for a PR (GraphQL only; not exposed by ``gh pr view``)."""
+
+    enabled: bool  # the base branch requires a merge queue
+    in_queue: bool  # the PR is currently enqueued
+
+
+@dataclass(frozen=True)
+class RequiredStatusChecksRule:
+    """One ``required_status_checks`` rule in effect on a branch, and where it came from.
+
+    Read from ``GET /repos/{owner}/{repo}/rules/branches/{branch}``, which
+    lists the rules of every *active* ruleset that applies to the branch --
+    repository and organization rulesets alike -- and nothing from a
+    disabled or evaluate-only ruleset, nor from classic branch protection.
+    """
+
+    contexts: tuple[str, ...]
+    ruleset_id: int
+    ruleset_source: str = ""  # "owner/repo" or the organization name
+    ruleset_source_type: str = ""  # Repository | Organization
+    strict: bool = False  # strict_required_status_checks_policy
+
+
+@dataclass(frozen=True)
+class RulesetInfo:
+    """A ruleset as GitHub describes it (``GET /repos/{owner}/{repo}/rulesets[/{id}]``).
+
+    ``bypass_actors`` is ``None`` when GitHub did not return the field, which
+    it withholds from any token without write access to the ruleset -- a
+    read-only token gets a 200 with the field absent -- and which the listing
+    endpoint never includes. Absent is not empty: ``()`` is GitHub saying
+    nobody may bypass, ``None`` is GitHub declining to say.
+    ``current_user_can_bypass`` is returned to every caller of the
+    single-ruleset read.
+    """
+
+    id: int
+    name: str
+    enforcement: str  # active | evaluate | disabled
+    target: str = ""  # branch | tag | push
+    source: str = ""
+    source_type: str = ""
+    bypass_actors: tuple[str, ...] | None = None  # "<actor_type> <actor_id> (<bypass_mode>)"
+    current_user_can_bypass: str = ""  # always | pull_requests_only | never
+    html_url: str = ""
+
+    @property
+    def is_active(self) -> bool:
+        return self.enforcement == "active"
+
+
+@dataclass(frozen=True)
+class ClassicBranchProtection:
+    """Classic branch protection (``GET /repos/{owner}/{repo}/branches/{branch}/protection``).
+
+    The pre-ruleset mechanism. ``required_contexts`` is empty when the
+    protection exists but requires no status check; ``enforce_admins`` is the
+    classic analogue of "no bypass actors".
+    """
+
+    required_status_checks: bool
+    required_contexts: tuple[str, ...]
+    enforce_admins: bool
+
+
+Runner = Callable[[ExecutionRequest], ExecutionResult]
+
+# -- where `gh` runs (#283) -------------------------------------------------------
+# `gh` runs git in its own working directory for some commands. gh 2.103.2's
+# `gh pr merge` asks git whether the PR's head branch exists locally on every
+# merge, and with `--delete-branch` it may check out the base branch, pull,
+# prune or remove a worktree, and then deletes the local branch
+# (pkg/cmd/pr/merge/merge.go; its git client sets no repository directory, so
+# git runs where `gh` was started). Started in the operator's checkout, that
+# git reads the shared repository's configuration and runs its hooks, which an
+# agent can write, with the controller's credential in the environment. So
+# every `gh` the controller starts runs in a fresh, empty directory of its
+# own, in the temporary directory, and with ``GIT_DIR`` naming that same
+# directory: it is no git directory, so a git that `gh` starts fails instead
+# of finding a repository, whatever the controller's own environment says (an
+# inherited ``GIT_DIR``, a ``TMPDIR`` inside a checkout). Nothing the
+# controller asks of `gh` needs a local repository: every call names its
+# repository, PR or issue explicitly.
+GH_WORKDIR_PREFIX = "autoforge-gh-"
+
+
+@contextmanager
+def gh_workdir() -> Iterator[str]:
+    """A fresh empty directory for one `gh` process, removed once it has exited (#283)."""
+    try:
+        path = tempfile.mkdtemp(prefix=GH_WORKDIR_PREFIX)
+    except OSError as exc:
+        raise GitHubError(f"cannot create an empty working directory for gh: {exc}") from exc
+    try:
+        yield path
+    finally:
+        shutil.rmtree(path, ignore_errors=True)
+
+
+def gh_request(
+    command: Sequence[str],
+    workdir: str,
+    *,
+    timeout_seconds: int,
+    stdin: bytes | None = None,
+) -> ExecutionRequest:
+    """The request that runs ``command``, a `gh` argv, in ``workdir`` (:func:`gh_workdir`).
+
+    ``command`` still names what it named from the controller's own directory,
+    now that the child starts elsewhere: a relative path is made absolute, and
+    so is each relative ``PATH`` entry (:func:`_anchored_search_path`), where a
+    bare name, and every program `gh` itself starts, is looked up.
+    """
+    executable = command[0]
+    if os.sep in executable and not os.path.isabs(executable):
+        executable = os.path.join(os.getcwd(), executable)
+    env = {"GIT_DIR": workdir}
+    search_path = _anchored_search_path(os.environ.get("PATH"))
+    if search_path is not None:
+        env["PATH"] = search_path
+    return ExecutionRequest(
+        command=[executable, *command[1:]],
+        cwd=workdir,
+        env=env,
+        timeout_seconds=timeout_seconds,
+        stdin_data=stdin,
+    )
+
+
+def _anchored_search_path(path: str | None) -> str | None:
+    """``path``, a ``PATH`` value, each relative entry made absolute from this directory.
+
+    The empty entry, like ``.``, is the current directory, as exec's lookup
+    reads it. Left relative, an entry would be looked up from the empty
+    directory a `gh` starts in: ``bin`` would no longer find what it found,
+    and ``..`` would reach the shared temporary directory that one was made
+    in. None when ``PATH`` is unset or every entry is absolute, since the
+    child's lookup then does not depend on its directory. Do not normalize
+    ``..``: the kernel must follow any preceding symlink before resolving it.
+    """
+    if path is None:
+        return None
+    entries = path.split(os.pathsep)
+    if all(os.path.isabs(entry) for entry in entries):
+        return None
+    cwd = os.getcwd()
+    return os.pathsep.join(
+        entry if os.path.isabs(entry) else os.path.join(cwd, entry) if entry else cwd
+        for entry in entries
+    )
+
+
+# -- the exact read -------------------------------------------------------------
+# `gh` rewrites every JSON reply before printing it (go-gh's asciisanitizer on
+# the HTTP transport, which no flag turns off): a C0 or C1 control character
+# and its JSON escape become caret notation, and so does the *literal text* of
+# an escape, the six characters `\u001b` written in a body, which the reply
+# carries as `\\u001b` and `gh` prints as `\^[`. The rewrite is not reversible
+# (`\^[` is also what the literal text `\^[` reads as), so no comparison of
+# what `gh` printed can prove that a body is a given text. An effect's
+# completion read-back needs that proof; the exact read gives it, by reading
+# one object with GitHub's REST API directly, under the credential `gh` holds.
+# What it reads is compared, never printed.
+EXACT_READ_ROOT = "https://api.github.com/"
+# A PR, issue or comment object: 65536 characters of body, each at most 12
+# bytes as a JSON escape, plus the rest of the object, well inside this.
+EXACT_READ_MAX_BYTES = 1 << 21
+_EXACT_READ_HEADERS = (
+    ("Accept", "application/vnd.github+json"),
+    ("X-GitHub-Api-Version", "2022-11-28"),
+    ("User-Agent", "autoforge"),
+)
+_JSON_CONTENT_TYPE_RE = re.compile(r"^application/json\s*(?:;|$)", re.IGNORECASE)
+# What `gh auth token` may print: visible ASCII, so it can never end the
+# Authorization header and start another.
+_API_TOKEN_RE = re.compile(r"[\x21-\x7e]{1,4096}")
+
+
+@dataclass(frozen=True)
+class HttpsRequest:
+    """One GET of the exact read. ``headers`` carries the credential: never in a repr."""
+
+    url: str
+    headers: tuple[tuple[str, str], ...] = field(repr=False)
+    timeout_seconds: float
+    max_bytes: int
+
+
+@dataclass(frozen=True)
+class HttpsReply:
+    """What GitHub answered: the status, the headers (names lower-cased) and the body.
+
+    ``body`` is at most ``max_bytes + 1`` bytes, so a longer one is seen as
+    too long without being read whole. For a status that is not 2xx it is at
+    most :data:`EXACT_READ_ERROR_BYTES`, read only to tell a rate limit from
+    a refusal and never quoted.
+    """
+
+    status: int
+    headers: dict[str, str]
+    body: bytes = field(repr=False)
+
+
+HttpsGet = Callable[[HttpsRequest], HttpsReply]
+# What is read of an error reply: enough for GitHub's JSON message.
+EXACT_READ_ERROR_BYTES = 4096
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """A 3xx is the answer, never followed: a redirect would carry the credential elsewhere."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+class _DeadlineReader(io.RawIOBase):
+    """The raw reader of one reply: no receive on ``sock`` outlasts ``deadline``.
+
+    ``http.client`` reads everything of a reply through one buffered reader
+    over this: the status line, the headers, a chunked body's framing and its
+    trailers, and the body. One of its calls can take many receives (a line,
+    a chunk's size, the trailers after the last chunk), and a socket timeout
+    bounds each receive alone, so a server sending a byte at a time inside it
+    would never trip it. Each receive here waits at most until the deadline,
+    and none starts after it, whatever call it is part of.
+    """
+
+    def __init__(self, sock, deadline: float, timeout: float) -> None:
+        super().__init__()
+        self._sock = sock
+        self._raw = sock.makefile("rb", buffering=0)
+        self._deadline = deadline
+        self._timeout = timeout
+
+    def readable(self) -> bool:
+        return True
+
+    def readinto(self, buffer):
+        remaining = self._deadline - time.monotonic()
+        try:
+            if remaining <= 0:
+                raise TimeoutError
+            self._sock.settimeout(remaining)
+            return self._raw.readinto(buffer)
+        except TimeoutError:  # the deadline has passed, or this receive reached it
+            raise TimeoutError(f"the reply took longer than {self._timeout:g}s") from None
+
+    def close(self) -> None:
+        if not self.closed:
+            self._raw.close()
+        super().close()
+
+
+class _DeadlineResponse(http.client.HTTPResponse):
+    """A reply read through a :class:`_DeadlineReader` instead of the socket's own file."""
+
+    def __init__(self, sock, *args, deadline, timeout, **kwargs):
+        super().__init__(sock, *args, **kwargs)
+        self.fp.close()  # nothing has been read from it
+        self.fp = io.BufferedReader(_DeadlineReader(sock, deadline, timeout))
+
+
+class _DeadlineHandler(urllib.request.HTTPHandler, urllib.request.HTTPSHandler):
+    """Opens the request so that every reply on its connection is read by one deadline.
+
+    That is the request's reply, and a proxy's answer to the tunnel opened
+    for it. One handler serves both schemes, so the transport's tests on a
+    loopback ``http`` server read a reply as the read of GitHub does.
+    """
+
+    def __init__(self, context: ssl.SSLContext, deadline: float, timeout: float) -> None:
+        super().__init__(context=context)
+        self._response = functools.partial(_DeadlineResponse, deadline=deadline, timeout=timeout)
+
+    def do_open(self, http_class, req, **http_conn_args):
+        def connection(*args, **kwargs):
+            opened = http_class(*args, **kwargs)
+            opened.response_class = self._response
+            return opened
+
+        return super().do_open(connection, req, **http_conn_args)
+
+
+def _read_bounded(stream, limit: int) -> bytes:
+    """Up to ``limit`` bytes of ``stream``."""
+    body = bytearray()
+    while len(body) < limit:
+        chunk = stream.read1(min(1 << 16, limit - len(body)))
+        if not chunk:
+            break
+        body += chunk
+    return bytes(body)
+
+
+def _tls_context() -> ssl.SSLContext:
+    """A client context that verifies the certificate chain and the host name.
+
+    ``ssl.create_default_context`` with the system's trust store, without its
+    ``SSLKEYLOGFILE`` handling: that would write the session secrets of the
+    connection carrying the credential to a file (and fail every read when
+    the variable names an unwritable path). ``PROTOCOL_TLS_CLIENT`` sets
+    ``CERT_REQUIRED`` and ``check_hostname``.
+    """
+    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    context.load_default_certs(ssl.Purpose.SERVER_AUTH)
+    return context
+
+
+def https_get(request: HttpsRequest) -> HttpsReply:
+    """The exact read's transport: one GET, the certificate verified, no redirect followed.
+
+    Connecting (the TCP connection, the TLS handshake, sending the request)
+    is bounded by ``timeout_seconds`` on each socket operation. The reply is
+    read in all within ``timeout_seconds`` of the call: its status line,
+    headers, a chunked body's framing and trailers, and its body
+    (:class:`_DeadlineReader`), so a server that trickles any of it cannot
+    hold the controller. The body is read up to ``max_bytes + 1`` bytes. A
+    status that is not 2xx is returned for the client to classify, with at
+    most :data:`EXACT_READ_ERROR_BYTES` of its body. Connection and TLS
+    failures, and the deadline, raise as ``urllib`` raises them (an
+    ``OSError``). The TLS context verifies the chain and the host name
+    (:func:`_tls_context`). The proxy variables
+    apply, as they do to `gh`; HTTPS through a proxy is a tunnel, so the
+    certificate verified is still GitHub's.
+    """
+    timeout = request.timeout_seconds
+    deadline = time.monotonic() + timeout
+    opener = urllib.request.build_opener(
+        _NoRedirect(), _DeadlineHandler(_tls_context(), deadline, timeout)
+    )
+    req = urllib.request.Request(request.url, headers=dict(request.headers), method="GET")
+    try:
+        with opener.open(req, timeout=timeout) as resp:
+            headers = {name.lower(): value for name, value in resp.headers.items()}
+            body = _read_bounded(resp, request.max_bytes + 1)
+            return HttpsReply(resp.status, headers, body)
+    except urllib.error.HTTPError as exc:
+        with exc:
+            headers = {name.lower(): value for name, value in (exc.headers or {}).items()}
+            limit = min(EXACT_READ_ERROR_BYTES, request.max_bytes)
+            body = _read_bounded(exc, limit) if exc.fp is not None else b""
+            return HttpsReply(exc.code, headers, body)
+
+
+def _exact_transport_failure(exc: Exception, what: str) -> GitHubError:
+    """What a failure the exact read's transport raised means; no reply was read.
+
+    A certificate that does not verify is conclusive (whoever answered is
+    not known to be GitHub); a connection that failed or broke is
+    inconclusive, as `gh`'s own are; anything else is conclusive.
+    """
+    reason = exc.reason if isinstance(exc, urllib.error.URLError) else exc
+    if isinstance(reason, ssl.SSLCertVerificationError):
+        return GitHubError(
+            f"{what}: the TLS certificate did not verify ({redact(str(reason)):.200})"
+        )
+    detail = f"{type(exc).__name__}: {redact(str(exc)):.200}"
+    if isinstance(exc, (OSError, http.client.HTTPException)):
+        return GitHubUnavailableError(f"{what}: GitHub could not be read ({detail})")
+    return GitHubError(f"{what}: the exact read failed ({detail})")
+
+
+# The PR identity read (:meth:`GitHubClient.get_pr`): everything a caller
+# binds a PR by, and no check results. GitHub refuses a fine-grained token
+# the check runs of a private PR and `gh` then fails the *whole* view
+# (#291), so a read that does not need checks never asks for them.
+_PR_FIELDS = (
+    "url,number,title,state,headRefOid,baseRefName,headRefName,mergeable,mergeStateStatus,"
+    "autoMergeRequest,isDraft,body,headRepository,headRepositoryOwner,"
+    "closingIssuesReferences"
+)
+# The checks read (:meth:`GitHubClient.get_pr_with_checks`): the same fields
+# and the head's check results, in one GraphQL answer, so the checks a
+# caller judges are those of the HEAD it judged them with.
+_PR_CHECKS_FIELDS = f"{_PR_FIELDS},statusCheckRollup"
+# The open PRs `doctor` may probe the checks read on (#291): the most
+# recently updated ones, each with the number of check results on its head
+# commit. ``contexts.totalCount`` is returned even to a token GitHub
+# refuses the check-run nodes themselves, so it selects a candidate without
+# being the read it tests.
+_CHECKS_PROBE_PAGE_SIZE = 20
+_CHECKS_PROBE_QUERY = (
+    "query($owner: String!, $name: String!) {"
+    " repository(owner: $owner, name: $name) {"
+    f" pullRequests(first: {_CHECKS_PROBE_PAGE_SIZE}, states: [OPEN],"
+    " orderBy: {field: UPDATED_AT, direction: DESC}) {"
+    " nodes { url number commits(last: 1) { nodes { commit { oid"
+    " statusCheckRollup { contexts { totalCount } } } } } } } } }"
+)
+# Page size of a PR's changed-files listing; every page is read. GitHub stops
+# the endpoint at 3000 files whatever the paging, so a listing that does not
+# reach GitHub's own ``changedFiles`` count is reported as incomplete and the
+# merge gate fails closed on it, which is the honest answer for a PR too
+# large for the controller to prove anything about.
+_PR_FILES_PAGE_SIZE = 100
+# Page size of the issue-event listing behind the replan close watermark.
+_EVENTS_PAGE_SIZE = 100
+# Page sizes of the Actions listings behind the check-definition gate.
+_JOBS_PAGE_SIZE = 100
+_RUNS_PAGE_SIZE = 100
+_MERGE_QUEUE_QUERY = (
+    "query($owner: String!, $name: String!, $number: Int!) {"
+    " repository(owner: $owner, name: $name) {"
+    " pullRequest(number: $number) { isMergeQueueEnabled isInMergeQueue } } }"
+)
+# The highest PR number is read as a proven numeric maximum over every PR
+# state, never inferred from one CREATED_AT-ordered node: creation-time
+# ordering has no numeric tie-breaker, so same-second PRs can return a lower
+# number first and let a higher-numbered pre-existing PR slip past the
+# watermark. Listing `--state all` and taking the maximum covers open,
+# closed and merged PRs alike; a listing that reaches the ceiling is refused
+# rather than reported as a maximum.
+_PR_NUMBER_LIST_FIELDS = "number"
+_PR_LIST_FIELDS = (
+    "url,number,title,state,headRefOid,baseRefName,headRefName,isDraft,body,"
+    "headRepository,headRepositoryOwner,closingIssuesReferences"
+)
+# One page of the open-PR listing, read by cursor until GitHub reports no
+# further page (issue #20). `gh pr list --limit N` reads at most N rows and
+# says nothing about the rest, so a strict caller had to refuse a listing
+# that reached its ceiling; a cursor walk has no ceiling to reach. The node
+# fields are the ones `gh pr list --json` would return under the same names,
+# so the same decoder reads both; ``closingIssuesReferences`` is the one
+# connection `gh` flattens, and :meth:`GitHubClient.list_open_prs` flattens
+# it the same way. Creation order, ascending, keeps the walk stable: a PR
+# opened while it runs lands at the end, not inside a page already read.
+_PR_PAGE_SIZE = 100
+_OPEN_PR_PAGE_QUERY = (
+    "query($owner: String!, $name: String!, $after: String) {"
+    " repository(owner: $owner, name: $name) {"
+    f" pullRequests(first: {_PR_PAGE_SIZE}, states: [OPEN], after: $after,"
+    " orderBy: {field: CREATED_AT, direction: ASC}) {"
+    " pageInfo { hasNextPage endCursor }"
+    " nodes { url number title state headRefOid baseRefName headRefName isDraft body"
+    " headRepository { name } headRepositoryOwner { login }"
+    " closingIssuesReferences(first: 100) { nodes { number } } } } } }"
+)
+# One page of an issue's or a PR's conversation comments, read by cursor until
+# GitHub reports no further page. `gh issue view --json comments` and `gh pr
+# view --json comments` read `comments(first: 100)` and never a second page,
+# so a comment past the hundredth was reported as absent to every identity
+# read built on them (K4, K8, the replan close receipt). The node fields are
+# the ones those views returned under the same names, so the same decoder
+# reads both. The connection is in creation order and a cursor names a
+# comment (its database id), not an offset: a comment posted while the walk
+# runs lands at the end, and one deleted does not shift the pages after it.
+_COMMENT_PAGE_SIZE = 100
+
+
+def _comment_page_query(parent: str) -> str:
+    """The comment-page query of ``parent``, ``issue`` or ``pullRequest``."""
+    return (
+        "query($owner: String!, $name: String!, $number: Int!, $after: String) {"
+        " repository(owner: $owner, name: $name) {"
+        f" {parent}(number: $number) {{"
+        f" comments(first: {_COMMENT_PAGE_SIZE}, after: $after) {{"
+        " pageInfo { hasNextPage endCursor }"
+        " nodes { url body createdAt author { login } } } } } }"
+    )
+
+
+_ISSUE_COMMENT_PAGE_QUERY = _comment_page_query("issue")
+_PR_COMMENT_PAGE_QUERY = _comment_page_query("pullRequest")
+
+
+# -- strict row decoding ----------------------------------------------------------
+#
+# One decoder per object kind, used by every view and every listing. A row
+# that is not the object we asked for is a conclusive GitHubError, never an
+# object with a manufactured identity (``url=""``, ``number=0``, ``id=0``):
+# such an object matches nothing and is invisible to every later comparison,
+# so a listing containing it would prove "absent" for something that exists.
+# The identity of a row is its ``url`` parsed with the typed parser; a
+# ``number`` the row also carries must agree with it.
+
+
+def _row_object(row: object, what: str) -> dict:
+    if not isinstance(row, dict):
+        raise GitHubError(f"{what}: `gh` returned a non-object entry ({type(row).__name__})")
+    return row
+
+
+def _linked_issue_nodes(connection: object, what: str) -> list[dict]:
+    """The ``nodes`` of a GraphQL ``closingIssuesReferences`` connection.
+
+    Read like every other field: ``null``/absent is "no linked issue", any
+    other type than the connection object, its ``nodes`` list and a node
+    carrying an issue ``number`` is a conclusive GitHubError. Silently
+    dropping such a node would make a PR that closes an issue look unlinked
+    to it. (GitHub nulls the connection only alongside ``errors``, which the
+    page reader rejects first.)
+    """
+    if connection is None:
+        return []
+    if not isinstance(connection, dict):
+        raise GitHubError(
+            f"{what}: closingIssuesReferences is not a connection: {connection!r:.200}"
+        )
+    nodes = connection.get("nodes")
+    if nodes is None:
+        return []
+    if not isinstance(nodes, list):
+        raise GitHubError(f"{what}: closingIssuesReferences.nodes is not a list: {nodes!r:.200}")
+    for node in nodes:
+        number = node.get("number") if isinstance(node, dict) else None
+        if isinstance(number, bool) or not isinstance(number, int) or number <= 0:
+            raise GitHubError(f"{what}: a linked issue has no issue number: {node!r:.200}")
+    return nodes
+
+
+def _rollup_checks(row: dict, what: str) -> list[CheckInfo] | None:
+    """The check results of a PR row, or None when the row did not carry them (#291).
+
+    Absent: the read did not request ``statusCheckRollup`` (an identity read
+    or a listing), which says nothing about the checks. ``null`` or ``[]``:
+    read, and GitHub reports none. Any other value than a list of objects is
+    a conclusive GitHubError: an entry dropped as unreadable could be the one
+    failing check, so a malformed rollup is never read as a shorter one.
+    """
+    if "statusCheckRollup" not in row:
+        return None
+    rollup = row.get("statusCheckRollup")
+    if rollup is None:
+        return []
+    if not isinstance(rollup, list):
+        raise GitHubError(f"{what}: statusCheckRollup is not a list: {rollup!r:.200}")
+    checks: list[CheckInfo] = []
+    for c in rollup:
+        if not isinstance(c, dict):
+            raise GitHubError(f"{what}: a status check is not an object: {c!r:.200}")
+        details = c.get("detailsUrl") or c.get("targetUrl") or ""
+        kind = c.get("__typename")
+        checks.append(
+            CheckInfo(
+                name=str(c.get("name", "") or c.get("context", "")),
+                state=str(c.get("status", "") or c.get("state", "")).upper(),
+                conclusion=str(c.get("conclusion", "")).upper(),
+                details_url=details if isinstance(details, str) else "",
+                kind=kind if isinstance(kind, str) else "",
+            )
+        )
+    return checks
+
+
+def _text_field(row: dict, key: str, what: str) -> str:
+    """A string field, ``null``/absent read as empty; any other type is malformed."""
+    value = row.get(key)
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        raise GitHubError(f"{what}: field {key!r} is {type(value).__name__}, expected a string")
+    return value
+
+
+def _number_field(row: dict, key: str, what: str, expected: int) -> int:
+    value = row.get(key)
+    if not isinstance(value, int) or isinstance(value, bool):
+        raise GitHubError(f"{what}: field {key!r} is not an integer")
+    if value != expected:
+        raise GitHubError(f"{what}: field {key!r} is {value} but the url names #{expected}")
+    return value
+
+
+def _decode_issue(row: object, what: str) -> IssueInfo:
+    data = _row_object(row, what)
+    url = _text_field(data, "url", what)
+    try:
+        ref = parse_issue_url(url)
+    except ConfigurationError as exc:
+        raise GitHubError(f"{what}: url {url!r} is not a GitHub issue URL ({exc})") from exc
+    return IssueInfo(
+        url=ref.canonical,
+        number=_number_field(data, "number", what, ref.number),
+        title=_text_field(data, "title", what),
+        state=_text_field(data, "state", what).upper(),
+        body=_text_field(data, "body", what),
+        repository=ref.repository,
+    )
+
+
+def _decode_rest_comment(row: object, requested: GitHubCommentRef) -> CommentInfo:
+    """One issue-style comment as the REST API returns it (``gh api``).
+
+    The REST row spells its fields differently from the ``gh pr view``
+    rows (``html_url``, ``user.login``, ``created_at``) but is held to the
+    same rule: the URL must parse as a comment URL and its ``id`` must be the
+    comment the URL names. The merge gate re-reads the round's review
+    comment through this, so a row whose identity cannot be read is a
+    conclusive GitHubError, never a comment with a borrowed URL that the
+    gate could mistake for the one it asked about.
+    """
+    what = f"comment {requested.canonical}"
+    data = _row_object(row, what)
+    url = _text_field(data, "html_url", what)
+    try:
+        ref = parse_comment_url(url)
+    except ConfigurationError as exc:
+        raise GitHubError(f"{what}: html_url {url!r} is not a GitHub comment URL ({exc})") from exc
+    user = data.get("user")
+    login = _text_field(user, "login", what) if isinstance(user, dict) else ""
+    return CommentInfo(
+        id=_number_field(data, "id", what, ref.comment_id),
+        url=ref.canonical,
+        body=_text_field(data, "body", what),
+        author=login,
+        created_at=_text_field(data, "created_at", what),
+        parent_url=ref.parent.canonical,
+    )
+
+
+def _decode_comment(row: object, parent_url: str) -> CommentInfo:
+    what = f"comment on {parent_url}"
+    data = _row_object(row, what)
+    url = _text_field(data, "url", what)
+    try:
+        ref = parse_comment_url(url)
+    except ConfigurationError as exc:
+        raise GitHubError(f"{what}: url {url!r} is not a GitHub comment URL ({exc})") from exc
+    author = data.get("author")
+    login = _text_field(author, "login", what) if isinstance(author, dict) else ""
+    return CommentInfo(
+        id=ref.comment_id,
+        url=ref.canonical,
+        body=_text_field(data, "body", what),
+        author=login,
+        created_at=_text_field(data, "createdAt", what),
+        parent_url=parent_url,
+    )
+
+
+# `gh pr list` paginates internally to satisfy --limit; this is the ceiling a
+# strict caller is willing to read before declaring the set unknowable. The
+# open-PR listing walks cursors instead and has no ceiling (issue #20); the
+# all-states listing and the PR-number watermark still read up to this many.
+STRICT_PR_LIST_LIMIT = 1000
+# The same ceiling for `gh issue list`: a FIX entry reads every open issue to
+# find the follow-up issues an earlier fixer created.
+STRICT_ISSUE_LIST_LIMIT = 1000
+_ISSUE_LIST_FIELDS = "url,number,title,state,body"
+
+MERGE_METHODS = ("squash", "merge", "rebase")
+_SHA40_RE = re.compile(r"^[0-9a-f]{40}$")
+# A full object id in either object format (SHA-1 or SHA-256), lower case.
+_FULL_SHA_RE = re.compile(r"^(?:[0-9a-f]{40}|[0-9a-f]{64})$")
+
+# GitHub's own limits on what a typed write may publish (ADR 0004 D2.4): an
+# issue or PR body and a comment are refused above 65,536 characters (HTTP
+# 422, "body is too long"), a title above 256. A payload past either is
+# refused before any process runs, never sent to collect the 422.
+MAX_BODY_CHARS = 65536
+MAX_TITLE_CHARS = 256
+
+# The newest-first all-states issue listing read down to the K5 number
+# watermark (:meth:`GitHubClient.list_issues_above`): one page per read, and a
+# bound on how many pages one walk may read, so a listing that cannot be read
+# down to the watermark is refused rather than read forever.
+_ISSUE_PAGE_SIZE = 100
+_ISSUE_WALK_MAX_PAGES = 100
+# Page size of the head-filtered PR listing (:meth:`GitHubClient.list_prs_for_head`).
+_HEAD_PR_PAGE_SIZE = 100
+
+# The answers of the compare endpoint (base...commit) that put the commit in
+# the base's history: it is ahead of the base by no commit (D7.5).
+_IN_HISTORY_STATUSES = frozenset({"behind", "identical"})
+_NOT_IN_HISTORY_STATUSES = frozenset({"ahead", "diverged"})
+
+_GITHUB_NAME_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+
+def _repository_path(repository: str) -> str:
+    """``owner/repo`` as it goes into a REST path (ADR 0004 D7.4).
+
+    Exactly two GitHub name segments, neither made of dots alone: the path
+    must name the repository and nothing else, so no ``..`` segment, no
+    third segment and no ``{owner}`` placeholder `gh` would fill in from a
+    git remote.
+    """
+    owner, sep, name = (repository if isinstance(repository, str) else "").partition("/")
+    for part in (owner, name):
+        if not sep or not _GITHUB_NAME_RE.fullmatch(part) or not part.strip("."):
+            raise GitHubError(f"{repository!r} is not an owner/repo repository name")
+    return f"{owner}/{name}"
+
+
+# What ``git check-ref-format`` refuses in a branch name, plus whitespace: a
+# branch the controller deletes or reads by name is one exact ref, never a
+# path that could reach another (``..``) or a pattern.
+_BRANCH_FORBIDDEN_RE = re.compile(r"[\x00-\x20\x7f~^:?*\[\\]|\.\.|@\{|//|/\.|\.lock(?:/|\Z)")
+
+
+def _branch_path(branch: str, what: str) -> str:
+    """``branch`` as it goes into a ``git/ref/heads/`` REST path: one branch, percent-encoded."""
+    if (
+        not isinstance(branch, str)
+        or not branch
+        or branch == "@"
+        or branch.startswith(("/", ".", "-"))
+        or branch.endswith(("/", "."))
+        or _BRANCH_FORBIDDEN_RE.search(branch)
+    ):
+        raise GitHubError(f"{what}: {branch!r:.120} is not a branch name")
+    return quote(branch, safe="/")
+
+
+def _check_write_bounds(what: str, *, body: str, title: str | None = None) -> None:
+    """Refuse a payload GitHub would refuse, before any process runs."""
+    if not isinstance(body, str):
+        raise GitHubError(f"{what}: the body is {type(body).__name__}, not text")
+    if len(body) > MAX_BODY_CHARS:
+        raise GitHubError(
+            f"{what}: the body is {len(body)} characters, over GitHub's limit of "
+            f"{MAX_BODY_CHARS}; nothing was sent"
+        )
+    if title is None:
+        return
+    if not isinstance(title, str):
+        raise GitHubError(f"{what}: the title is {type(title).__name__}, not text")
+    if len(title) > MAX_TITLE_CHARS:
+        raise GitHubError(
+            f"{what}: the title is {len(title)} characters, over GitHub's limit of "
+            f"{MAX_TITLE_CHARS}; nothing was sent"
+        )
+
+
+def _full_sha(value: str, role: str, what: str) -> str:
+    sha = value.lower() if isinstance(value, str) else ""
+    if not _FULL_SHA_RE.fullmatch(sha):
+        raise GitHubError(f"{what}: {role} {value!r:.80} is not a full commit SHA")
+    return sha
+
+
+def _write_unknown(what: str, problem: str) -> NoReturn:
+    """A write `gh` reported as done whose reply cannot be read (D4.3).
+
+    The write may well have landed; only a read-back by the effect's
+    identity can tell, so this is an ambiguous outcome, never a refusal.
+    The reply itself is not quoted: it echoes the payload.
+    """
+    raise GitHubUnavailableError(f"{what}: {problem}; the outcome is unknown")
+
+
+def _created_comment(reply: dict, target: GitHubRef, what: str) -> CreatedObject:
+    """The comment a create reply names, which must be on ``target``."""
+    try:
+        ref = parse_comment_url(str(reply.get("html_url") or ""))
+    except ConfigurationError:
+        _write_unknown(what, "the reply's html_url is not a GitHub comment URL")
+    comment_id = reply.get("id")
+    if isinstance(comment_id, bool) or comment_id != ref.comment_id:
+        _write_unknown(what, "the reply's id does not match its html_url")
+    if not ref.on(target):
+        _write_unknown(what, f"the reply names a comment on another object ({ref.canonical})")
+    return CreatedObject(url=ref.canonical, number=None)
+
+
+def _replied_object(
+    reply: dict, what: str, *, repository: str, expect: str | None, number: int | None = None
+) -> CreatedObject:
+    """The issue or PR a write reply names: in ``repository``, of kind ``expect``."""
+    try:
+        ref = parse_github_url(str(reply.get("html_url") or ""), expect=expect)
+    except ConfigurationError:
+        _write_unknown(what, f"the reply's html_url is not a GitHub {expect or 'issue/PR'} URL")
+    replied = reply.get("number")
+    if isinstance(replied, bool) or replied != ref.number:
+        _write_unknown(what, "the reply's number does not match its html_url")
+    if not ref.same_repository(repository) or (number is not None and ref.number != number):
+        _write_unknown(what, f"the reply names another object ({ref.canonical})")
+    return CreatedObject(url=ref.canonical, number=ref.number)
+
+
+@dataclass(frozen=True)
+class _ListedIssue:
+    """One row of the newest-first REST issue listing (issues and PRs alike)."""
+
+    number: int
+    created_at: datetime
+    is_pull_request: bool
+    row: dict
+
+
+def _listed_issue(row: object, what: str) -> _ListedIssue:
+    """The number, creation time and kind of one REST issue-listing row, strictly.
+
+    The REST issues listing returns pull requests too (a PR is an issue
+    there), marked by a ``pull_request`` key; they share one number
+    sequence with issues. A row without a usable number or creation time
+    is a conclusive GitHubError, never skipped: the watermark walk decides
+    where to stop from these two values.
+    """
+    data = _row_object(row, what)
+    number = data.get("number")
+    if isinstance(number, bool) or not isinstance(number, int) or number < 1:
+        raise GitHubError(f"{what}: a row has no usable number: {number!r:.40}")
+    text = data.get("created_at")
+    try:
+        created = datetime.fromisoformat(text) if isinstance(text, str) else None
+    except ValueError:
+        created = None
+    if created is None or created.tzinfo is None:
+        raise GitHubError(f"{what}: #{number} has no usable created_at: {text!r:.40}")
+    return _ListedIssue(
+        number=number,
+        created_at=created,
+        is_pull_request="pull_request" in data,
+        row=data,
+    )
+
+
+def _rest_issue_row(data: dict) -> dict:
+    """A REST issue row in the ``gh issue view --json`` shape :func:`_decode_issue` reads.
+
+    REST names the HTML URL ``html_url`` (its ``url`` is the API URL) and
+    spells the state in lower case; the decoder upper-cases it.
+    """
+    return {
+        "url": data.get("html_url"),
+        "number": data.get("number"),
+        "title": data.get("title"),
+        "state": data.get("state"),
+        "body": data.get("body"),
+    }
+
+
+def _rest_pr_row(row: object, what: str) -> dict:
+    """A REST pull-request row in the ``gh pr view --json`` shape ``_pr_from_data`` reads.
+
+    One decoder reads every PR, so the REST row is translated, never decoded
+    separately: ``html_url`` is the PR URL, ``head``/``base`` carry the refs
+    and the head commit, a closed PR with a ``merged_at`` is ``MERGED`` (REST
+    has no merged state), and ``auto_merge`` is the armed auto-merge.
+    Closing-issue references, mergeability and checks are not in the REST
+    listing (``checks`` is None, not read); a caller that needs them reads
+    the PR with ``get_pr``, or ``get_pr_with_checks`` for the checks.
+    """
+    data = _row_object(row, what)
+    head = data.get("head")
+    base = data.get("base")
+    if not isinstance(head, dict) or not isinstance(base, dict):
+        raise GitHubError(f"{what}: a row has no head or base object")
+    state = data.get("state")
+    if isinstance(state, str) and state.lower() == "closed" and data.get("merged_at"):
+        state = "MERGED"
+    head_repo = head.get("repo")
+    repo_name: object = None
+    owner_login: object = None
+    if isinstance(head_repo, dict):
+        repo_name = head_repo.get("name")
+        owner = head_repo.get("owner")
+        owner_login = owner.get("login") if isinstance(owner, dict) else None
+    return {
+        "url": data.get("html_url"),
+        "number": data.get("number"),
+        "title": data.get("title"),
+        "state": state,
+        "headRefOid": head.get("sha"),
+        "headRefName": head.get("ref"),
+        "baseRefName": base.get("ref"),
+        "isDraft": data.get("draft", False),
+        "body": data.get("body"),
+        "headRepository": {"name": repo_name} if repo_name else None,
+        "headRepositoryOwner": {"login": owner_login} if owner_login else None,
+        "autoMergeRequest": data.get("auto_merge"),
+    }
+
+
+def build_merge_argv(pr_url: str, method: str = "squash", match_head_sha: str = "") -> list[str]:
+    """Pure argv builder for ``gh pr merge`` (no ``gh`` prefix, no execution).
+
+    Shared by :meth:`GitHubClient.merge_pr` and the engine's dry-run plan so
+    the command shown in dry-run is exactly the one that would run.
+    ``match_head_sha`` must be the full 40-hex reviewed HEAD; GitHub then
+    refuses the merge server-side if the PR HEAD moved. It never carries
+    ``--delete-branch``, which deletes the local branch too (#283):
+    ``merge.delete_branch`` deletes the remote head branch only, through
+    :meth:`GitHubClient.delete_branch_ref`.
+    """
+    if method not in MERGE_METHODS:
+        raise ConfigurationError(f"merge.method must be one of {MERGE_METHODS}, got {method!r}")
+    if not match_head_sha or not _SHA40_RE.match(match_head_sha.lower()):
+        raise ConfigurationError(
+            "merge requires the full 40-hex reviewed HEAD SHA for --match-head-commit, "
+            f"got {match_head_sha!r}"
+        )
+    ref = parse_pr_url(pr_url)
+    return ["pr", "merge", ref.canonical, f"--{method}", "--match-head-commit", match_head_sha]
+
+
+def build_disable_auto_merge_argv(pr_url: str) -> list[str]:
+    """``gh pr merge <pr> --disable-auto``: disarm GitHub auto-merge on a PR."""
+    return ["pr", "merge", parse_pr_url(pr_url).canonical, "--disable-auto"]
+
+
+def build_edit_issue_body_argv(issue_url: str, body_file: str) -> list[str]:
+    """``gh issue edit <issue> --body-file <file>``: replace an issue's body.
+
+    The body travels through a file, never through ``--body``: an issue body
+    is arbitrary multi-line text that the executor's argv would otherwise
+    expose in process listings, and the executor gives ``gh`` no stdin.
+    """
+    return ["issue", "edit", parse_issue_url(issue_url).canonical, "--body-file", body_file]
+
+
+def _as_int(value: object, what: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise GitHubError(f"`gh` returned a non-integer {what}: {value!r}")
+    return value
+
+
+def _ruleset_from_data(data: dict) -> RulesetInfo:
+    # Presence is the evidence: GitHub omits `bypass_actors` for a token
+    # without write access to the ruleset, so an absent field must not read
+    # as an empty list.
+    actors: list[str] | None = None
+    if "bypass_actors" in data:
+        raw = data["bypass_actors"]
+        if not isinstance(raw, list):
+            raise GitHubError("ruleset bypass_actors is not an array")
+        actors = []
+        for actor in raw:
+            if not isinstance(actor, dict):
+                raise GitHubError("ruleset bypass_actors entry is not an object")
+            actor_type = actor.get("actor_type") or "?"
+            actor_id = actor.get("actor_id")
+            mode = actor.get("bypass_mode") or "always"
+            label = f"{actor_type} {actor_id}" if actor_id is not None else str(actor_type)
+            actors.append(f"{label} ({mode})")
+    links = data.get("_links") or {}
+    html = links.get("html") if isinstance(links, dict) else None
+    return RulesetInfo(
+        id=_as_int(data.get("id"), "ruleset id"),
+        name=str(data.get("name") or ""),
+        enforcement=str(data.get("enforcement") or ""),
+        target=str(data.get("target") or ""),
+        source=str(data.get("source") or ""),
+        source_type=str(data.get("source_type") or ""),
+        bypass_actors=None if actors is None else tuple(actors),
+        current_user_can_bypass=str(data.get("current_user_can_bypass") or ""),
+        html_url=str(html.get("href") or "") if isinstance(html, dict) else "",
+    )
+
+
+# -- the native EPIC dependency graph (ADR 0008 D3, #179) ----------------------------
+#
+# Read-only: the parallel EPIC scheduler's snapshot reads an EPIC's direct
+# native sub-issues and each child's native ``blocked_by`` list, nothing
+# else (``blocking`` is never read, prose never parsed). Every row is
+# decoded strictly into the eligibility facts of D3.5; a row that is not
+# the object asked for is a conclusive GitHubError, never a node with a
+# manufactured identity.
+
+# GitHub's documented limits on the native graph: "You can add up to 100
+# sub-issues per parent issue" (docs, "Adding sub-issues"), and "You can
+# link up to 50 issues for each relationship type" (changelog 2025-08-21,
+# "Dependencies on issues"). The snapshot refuses a graph past either
+# (D3.4) instead of reading it partially.
+MAX_SUB_ISSUES = 100
+MAX_BLOCKED_BY = 50
+# Both listings are read with the REST maximum page size, every page.
+_GRAPH_PAGE_SIZE = 100
+ISSUE_STATES = ("open", "closed")
+# A ``state_reason`` is GitHub's word (``completed``, ``not_planned``,
+# ``duplicate``, ``reopened``, or one it adds later). An unknown word is kept
+# and shown; anything that is not a short word is a malformed answer.
+_STATE_REASON_RE = re.compile(r"^[A-Za-z0-9_.:-]{1,64}$")
+# The fields that name a blocker beyond its ``id``. A row carrying none of
+# them names a blocker the token may not read (see :func:`_decode_blocker`).
+_BLOCKER_IDENTITY_FIELDS = ("html_url", "number", "state", "repository_url")
+
+
+@dataclass(frozen=True)
+class IssueNode:
+    """One issue as the dependency graph reads it: its eligibility facts (ADR 0008 D3.5).
+
+    Decoded from a REST issue object (``GET .../issues/<n>`` or a
+    ``/sub_issues`` row). ``id`` is GitHub's numeric issue id; ``url`` the
+    issue's canonical HTML URL and ``repository`` the ``owner/repo`` it
+    names; ``state`` is ``open`` or ``closed``; ``state_reason`` is GitHub's
+    word or None; ``parent`` is the issue ``parent_issue_url`` names (None
+    when it has none); ``sub_issues_total`` is ``sub_issues_summary.total``;
+    ``blocked_by_total`` and ``blocked_by_open`` are
+    ``issue_dependencies_summary.total_blocked_by`` and ``.blocked_by``.
+    Titles, bodies, labels, assignees, milestones and timestamps are never
+    read into a node.
+    """
+
+    id: int
+    number: int
+    url: str
+    repository: str
+    state: str
+    state_reason: str | None
+    parent: GitHubIssueRef | None
+    sub_issues_total: int
+    blocked_by_total: int
+    blocked_by_open: int
+
+    @property
+    def ref(self) -> GitHubIssueRef:
+        return parse_issue_url(self.url)
+
+    @property
+    def is_open(self) -> bool:
+        return self.state == "open"
+
+
+@dataclass(frozen=True)
+class BlockerNode:
+    """One row of an issue's native ``blocked_by`` listing (ADR 0008 D3.2, D3.6).
+
+    A readable blocker carries its ``number``, ``url``, ``repository``,
+    ``state`` and ``state_reason``, wherever it lives. ``readable`` False is
+    a blocker GitHub names by its ``id`` alone, with none of the fields that
+    would identify it: the token may not read it. Its other fields are None
+    rather than a made-up identity, and it blocks its child (fail closed).
+    """
+
+    id: int
+    readable: bool
+    number: int | None = None
+    url: str | None = None
+    repository: str | None = None
+    state: str | None = None
+    state_reason: str | None = None
+
+
+def _positive_id(data: dict, key: str, what: str) -> int:
+    value = data.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise GitHubError(f"{what}: field {key!r} is not a positive integer: {value!r:.40}")
+    return value
+
+
+def _rest_state(data: dict, what: str) -> str:
+    state = data.get("state")
+    if not isinstance(state, str) or state.lower() not in ISSUE_STATES:
+        raise GitHubError(f"{what}: state {state!r:.40} is neither open nor closed")
+    return state.lower()
+
+
+def _rest_state_reason(data: dict, what: str) -> str | None:
+    reason = data.get("state_reason")
+    if reason is None:
+        return None
+    if not isinstance(reason, str) or not _STATE_REASON_RE.fullmatch(reason):
+        raise GitHubError(f"{what}: state_reason {reason!r:.80} is not a reason word")
+    return reason.lower()
+
+
+def _summary_count(data: dict, summary: str, key: str, what: str) -> int:
+    block = data.get(summary)
+    if not isinstance(block, dict):
+        raise GitHubError(f"{what}: {summary} is not an object")
+    value = block.get(key)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise GitHubError(f"{what}: {summary}.{key} is not a count: {value!r:.40}")
+    return value
+
+
+def _rest_issue_ref(data: dict, what: str) -> GitHubIssueRef:
+    """The issue a REST row is: its ``html_url``, which ``number`` and ``repository_url`` match.
+
+    A pull request is an issue to the REST API, but its ``html_url`` is a
+    ``/pull/`` URL, so it is refused here: no graph edge names one.
+    """
+    url = data.get("html_url")
+    try:
+        ref = parse_issue_url(url if isinstance(url, str) else "")
+    except ConfigurationError as exc:
+        raise GitHubError(f"{what}: html_url {url!r:.200} is not a GitHub issue URL") from exc
+    _number_field(data, "number", what, ref.number)
+    api_repository = data.get("repository_url")
+    try:
+        repository = parse_api_repository_url(
+            api_repository if isinstance(api_repository, str) else ""
+        )
+    except ConfigurationError as exc:
+        raise GitHubError(
+            f"{what}: repository_url {api_repository!r:.200} is not a GitHub repository"
+        ) from exc
+    if not ref.same_repository(repository):
+        raise GitHubError(f"{what}: repository_url names {repository}, html_url {ref.repository}")
+    return ref
+
+
+def _decode_issue_node(row: object, what: str) -> IssueNode:
+    """One REST issue object as an :class:`IssueNode`, strictly.
+
+    GitHub leaves ``parent_issue_url`` out of an issue that has no parent
+    (observed live for #179, ``tests/fixtures/github_graph/README.md``), so
+    an absent field reads as no parent, like a null one. That is never the
+    more permissive outcome: a ``/sub_issues`` row without a parent is
+    refused by the snapshot, and a re-read child without one is stale. An
+    answer from an API without native sub-issues still fails here, on the
+    two summaries it lacks.
+    """
+    data = _row_object(row, what)
+    ref = _rest_issue_ref(data, what)
+    what = f"{what}: {ref.canonical}"
+    parent_url = data.get("parent_issue_url")
+    parent: GitHubIssueRef | None = None
+    if parent_url is not None:
+        try:
+            parent = parse_api_issue_url(parent_url if isinstance(parent_url, str) else "")
+        except ConfigurationError as exc:
+            raise GitHubError(
+                f"{what}: parent_issue_url {parent_url!r:.200} is not a GitHub issue"
+            ) from exc
+    blocked_total = _summary_count(data, "issue_dependencies_summary", "total_blocked_by", what)
+    blocked_open = _summary_count(data, "issue_dependencies_summary", "blocked_by", what)
+    if blocked_open > blocked_total:
+        raise GitHubError(
+            f"{what}: {blocked_open} open blockers but {blocked_total} blockers in total"
+        )
+    return IssueNode(
+        id=_positive_id(data, "id", what),
+        number=ref.number,
+        url=ref.canonical,
+        repository=ref.repository,
+        state=_rest_state(data, what),
+        state_reason=_rest_state_reason(data, what),
+        parent=parent,
+        sub_issues_total=_summary_count(data, "sub_issues_summary", "total", what),
+        blocked_by_total=blocked_total,
+        blocked_by_open=blocked_open,
+    )
+
+
+def _decode_blocker(row: object, what: str) -> BlockerNode:
+    """One ``blocked_by`` row as a :class:`BlockerNode`, strictly.
+
+    GitHub documents no shape for a blocker the token may not read. A row
+    that carries a positive ``id`` and none of the fields naming the issue
+    (``html_url``, ``number``, ``state``, ``repository_url``) is read as such
+    a blocker: ``readable`` False, which blocks its child. A row with some
+    of them and not the others is malformed, as is every other defect. A
+    blocker GitHub leaves out of the listing altogether makes the listing
+    shorter than the child's ``total_blocked_by``, which refuses the whole
+    snapshot instead (ADR 0008 D3.3), the stricter of the two outcomes.
+    """
+    data = _row_object(row, what)
+    issue_id = _positive_id(data, "id", what)
+    if all(data.get(key) is None for key in _BLOCKER_IDENTITY_FIELDS):
+        return BlockerNode(id=issue_id, readable=False)
+    ref = _rest_issue_ref(data, what)
+    what = f"{what}: {ref.canonical}"
+    return BlockerNode(
+        id=issue_id,
+        readable=True,
+        number=ref.number,
+        url=ref.canonical,
+        repository=ref.repository,
+        state=_rest_state(data, what),
+        state_reason=_rest_state_reason(data, what),
+    )
+
+
+class GitHubClient:
+    """Thin typed wrapper around `gh`. Inject ``runner`` (and ``https``) for tests."""
+
+    def __init__(
+        self,
+        gh_command: str = "gh",
+        timeout_seconds: int = 120,
+        runner: Runner | None = None,
+        transient_retries: int = 1,
+        retry_delay_seconds: float = 2.0,
+        https: HttpsGet | None = None,
+    ) -> None:
+        self.gh_command = gh_command
+        self.timeout_seconds = timeout_seconds
+        self._runner: Runner = runner or execute
+        self._https: HttpsGet = https or https_get
+        self.transient_retries = max(0, transient_retries)
+        self.retry_delay_seconds = retry_delay_seconds
+
+    # -- low level ------------------------------------------------------
+    def _invoke(self, args: list[str], stdin: bytes | None = None) -> ExecutionResult:
+        # No GitHub call while this process holds the shared-Git lock (ADR
+        # 0008 D11.2): its holder must never wait on anything remote.
+        assert_shared_git_lock_free("call GitHub")
+        with gh_workdir() as workdir:
+            return self._runner(
+                gh_request(
+                    [self.gh_command, *args],
+                    workdir,
+                    timeout_seconds=self.timeout_seconds,
+                    stdin=stdin,
+                )
+            )
+
+    def _timeout_message(self, args: list[str]) -> str:
+        return f"`gh {' '.join(args)}` timed out after {self.timeout_seconds}s"
+
+    @staticmethod
+    def _exit_failure(args: list[str], res: ExecutionResult) -> tuple[str, bool]:
+        """The message of a non-zero `gh` exit, and whether it is transient.
+
+        `gh` stderr can echo the request it made, including an
+        ``Authorization`` header or a token in a URL, and this message ends
+        up in `block_reason`, `verification_failures` and the run log.
+        Classify the raw tail, quote it redacted.
+        """
+        tail = res.stderr.strip()[-1000:]
+        message = f"`gh {' '.join(args)}` failed (exit {res.exit_code}): {redact(tail)}"
+        # GitHub refusing the check results is an answer, never a reason to
+        # retry, whatever else the tail says (#291). It is looked for in the
+        # whole stderr, where _conclusive classifies it, so a refusal before
+        # the tail is never retried and then reported as unavailable.
+        transient = is_transient_gh_failure(tail) and not checks_access_denial(res.stderr)
+        return message, transient
+
+    @staticmethod
+    def _conclusive(message: str, stderr: str | None = None) -> GitHubError:
+        """A non-transient failure: a refused checks read, a plan limit, not found, or other.
+
+        ``stderr`` is the raw tail `gh` printed (``message`` quotes it
+        redacted, after the command line); the checks refusal is read from
+        it, never from the command line, which names ``statusCheckRollup``
+        itself. A checks refusal is classified first: the PR exists, so it
+        must never be read as not-found (#291).
+        """
+        answer = message if stderr is None else stderr
+        credential = checks_access_denial(answer)
+        if credential:
+            return GitHubChecksAccessError(message, credential=credential)
+        # The plan, not the credential (#289): never access denied, never absence.
+        if is_plan_limited_gh_failure(answer):
+            return GitHubPlanLimitedError(message)
+        if is_not_found_gh_failure(message):
+            return GitHubNotFoundError(message)
+        return GitHubError(message)
+
+    def _run_gh(self, args: list[str], allow_fail: bool = False) -> ExecutionResult:
+        attempts = self.transient_retries + 1
+        last_error = ""
+        last_stderr: str | None = None
+        transient = False
+        for i in range(attempts):
+            res = self._invoke(args)
+            last_stderr = None
+            if res.timed_out:
+                last_error = self._timeout_message(args)
+                transient = True
+            elif res.truncated:
+                # Head + marker + tail of a reply is not the reply: parsing it
+                # would read a document `gh` never returned. Not transient,
+                # and not something `allow_fail` may hand back as output.
+                raise GitHubError(
+                    f"`gh {' '.join(args)}` output was truncated at the executor's capture "
+                    "bound and cannot be parsed"
+                )
+            elif res.exit_code != 0:
+                last_error, transient = self._exit_failure(args, res)
+                last_stderr = res.stderr
+            else:
+                return res
+            if allow_fail and not transient:
+                return res
+            if not transient or i == attempts - 1:
+                break
+            time.sleep(self.retry_delay_seconds)
+        if transient:
+            raise GitHubUnavailableError(last_error)
+        raise self._conclusive(last_error, last_stderr)
+
+    def _run_gh_once(self, args: list[str], *, stdin: bytes | None = None) -> ExecutionResult:
+        """Run `gh` exactly once: the transport of a write (ADR 0004 D4.3).
+
+        A write is never re-sent on an ambiguous outcome, because the first
+        attempt may have landed: a timeout, a transient failure and a reply
+        that cannot be read are GitHubUnavailableError, "outcome unknown",
+        and the caller reconciles by reading the target back. A 404 is
+        GitHubNotFoundError and any other conclusive failure (a 422, a 403)
+        GitHubError, classified exactly as :meth:`_run_gh` classifies them.
+        ``stdin`` is the payload, so it never appears in argv, a process
+        listing or an error message.
+        """
+        res = self._invoke(args, stdin)
+        if res.timed_out:
+            raise GitHubUnavailableError(f"{self._timeout_message(args)}; the outcome is unknown")
+        if res.exit_code != 0:
+            message, transient = self._exit_failure(args, res)
+            if transient:
+                raise GitHubUnavailableError(f"{message}; the outcome is unknown")
+            raise self._conclusive(message, res.stderr)
+        if res.truncated:
+            # The write was accepted (exit 0) but its reply is not readable:
+            # unlike a read, this is not a conclusive failure, the write may
+            # have landed.
+            raise GitHubUnavailableError(
+                f"`gh {' '.join(args)}` reply was truncated at the executor's capture "
+                "bound; the outcome is unknown"
+            )
+        return res
+
+    def _write(self, method: str, path: str, payload: dict[str, str], what: str) -> dict:
+        """One REST write: ``gh api --method <method> <path> --input -``, payload on stdin.
+
+        The reply is parsed whole in Python (no ``--jq``): a reply that is
+        not a JSON object is an unknown outcome, not a refusal.
+        """
+        res = self._run_gh_once(
+            ["api", "--method", method, path, "--input", "-"],
+            stdin=json.dumps(payload).encode("utf-8"),
+        )
+        try:
+            reply = json.loads(res.stdout)
+        except json.JSONDecodeError:
+            _write_unknown(what, "`gh` returned a reply that is not JSON")
+        if not isinstance(reply, dict):
+            _write_unknown(what, "`gh` returned a reply that is not a JSON object")
+        return reply
+
+    def _json(self, args: list[str]) -> object:
+        res = self._run_gh(args)
+        try:
+            return json.loads(res.stdout)
+        except json.JSONDecodeError as exc:
+            raise GitHubError(f"`gh` returned invalid JSON: {exc}") from exc
+
+    def _api_json(self, args: list[str]) -> dict:
+        data = self._json(args)
+        if not isinstance(data, dict):
+            raise GitHubError("`gh` returned a non-object JSON payload")
+        return data
+
+    def _api_list(self, args: list[str]) -> list:
+        data = self._json(args)
+        if not isinstance(data, list):
+            raise GitHubError("`gh` returned a non-array JSON payload")
+        return data
+
+    def _graphql_data(self, args: list[str], what: str) -> dict:
+        """The ``data`` object of one GraphQL response, only when it is complete.
+
+        GraphQL answers a partially failed query with ``data`` *and*
+        ``errors``: the fields it could not resolve are ``null`` or missing
+        and the rest is present. Such a response must never be consumed as a
+        complete answer (a missing PR node would prove "no PR exists"), so
+        any ``errors`` entry is a conclusive GitHubError, whatever ``gh``'s
+        exit status was, and ``data`` must be an object.
+        """
+        page = self._api_json(args)
+        if "errors" in page:
+            raise GitHubError(f"{what}: GraphQL reported errors: {page.get('errors')!r:.500}")
+        data = page.get("data")
+        if not isinstance(data, dict):
+            raise GitHubError(f"{what}: GraphQL response has no data object: {page!r:.200}")
+        return data
+
+    def _api_pages(self, endpoint: str) -> list:
+        """Every item of a paginated REST array endpoint, all pages read.
+
+        ``gh api --paginate --slurp`` wraps the pages in one outer array, so
+        the result is a JSON array of pages and each page a JSON array; any
+        other shape is a malformed answer, not an empty one.
+        """
+        data = self._json(["api", "--paginate", "--slurp", endpoint])
+        if not isinstance(data, list) or not all(isinstance(page, list) for page in data):
+            raise GitHubError(
+                f"`gh api {endpoint}` returned a non-paginated JSON payload: {data!r:.200}"
+            )
+        return [item for page in data for item in page]
+
+    def _api_full_pages(self, endpoint: str, page_size: int, what: str) -> list:
+        """:meth:`_api_pages`, and every page before the last holds ``page_size`` rows.
+
+        ``endpoint`` asks for ``per_page=page_size``. A page short of it
+        before the last means rows went missing between page reads, or were
+        held back from a page: the listing is not known to be complete, so
+        it is a conclusive GitHubError, never a shorter answer.
+        """
+        data = self._json(["api", "--paginate", "--slurp", endpoint])
+        if not isinstance(data, list) or not all(isinstance(page, list) for page in data):
+            raise GitHubError(f"{what}: `gh api` returned a non-paginated JSON payload")
+        for index, page in enumerate(data[:-1]):
+            if len(page) != page_size:
+                raise GitHubError(
+                    f"{what}: page {index + 1} of {len(data)} holds {len(page)} rows, "
+                    f"not {page_size}; the listing may be incomplete"
+                )
+        return [item for page in data for item in page]
+
+    def _api_token(self, what: str) -> str:
+        """The credential `gh` holds for github.com, for one exact read.
+
+        ``gh auth token`` prints the token `gh` itself would send (``GH_TOKEN``
+        or ``GITHUB_TOKEN`` when set, else the login's). It stays in memory for
+        the one request: never in argv, a file or a message. A failure names
+        the command and `gh`'s redacted stderr, never what it printed.
+        """
+        args = ["auth", "token", "--hostname", "github.com"]
+        res = self._invoke(args)
+        if res.timed_out:
+            raise GitHubUnavailableError(f"{what}: {self._timeout_message(args)}")
+        if res.exit_code != 0:
+            message, transient = self._exit_failure(args, res)
+            raise (GitHubUnavailableError if transient else GitHubError)(f"{what}: {message}")
+        token = "" if res.truncated else res.stdout.strip()
+        if not _API_TOKEN_RE.fullmatch(token):
+            raise GitHubError(f"{what}: `gh auth token` printed no usable credential")
+        return token
+
+    def _exact_object(self, path: str, what: str) -> dict:
+        """One REST object as GitHub holds it, past `gh`'s sanitizer (the exact read).
+
+        ``path`` is relative to :data:`EXACT_READ_ROOT`, built by a typed
+        caller from a parsed URL, so the read reaches GitHub's API and nothing
+        else. It sends one GET with the credential `gh` holds, follows no
+        redirect and reads a bounded reply. Failures are classified as `gh`'s
+        are: no connection, a 5xx, a 429 or a rate-limited 403 (by its headers
+        or GitHub's message) is GitHubUnavailableError (inconclusive), a 404
+        GitHubNotFoundError, and
+        any other status, a redirect, a certificate that does not verify, or a
+        reply that is not one JSON object within the bound a conclusive
+        GitHubError. No message quotes the reply.
+        """
+        assert_shared_git_lock_free("call GitHub")
+        # The credential goes straight into the request, whose repr leaves the
+        # headers out: no local of this frame holds it on its own.
+        request = HttpsRequest(
+            url=EXACT_READ_ROOT + path,
+            headers=(*_EXACT_READ_HEADERS, ("Authorization", "Bearer " + self._api_token(what))),
+            timeout_seconds=self.timeout_seconds,
+            max_bytes=EXACT_READ_MAX_BYTES,
+        )
+        try:
+            reply = self._https(request)
+        except Exception as exc:  # every transport failure is classified, none escapes
+            raise _exact_transport_failure(exc, what) from None
+        status = reply.status
+        # A primary limit sends its headers; a secondary limit may send neither,
+        # only GitHub's message, which is read for this and never quoted.
+        rate_limited = (
+            reply.headers.get("x-ratelimit-remaining") == "0"
+            or "retry-after" in reply.headers
+            or b"rate limit" in reply.body[:EXACT_READ_ERROR_BYTES].lower()
+        )
+        if status >= 500 or status == 429 or (status == 403 and rate_limited):
+            raise GitHubUnavailableError(f"{what}: GitHub answered HTTP {status}")
+        if status == 404:
+            raise GitHubNotFoundError(f"{what}: GitHub answered HTTP 404")
+        if status != 200:
+            redirect = " (a redirect, which is never followed)" if 300 <= status < 400 else ""
+            raise GitHubError(f"{what}: GitHub answered HTTP {status}{redirect}")
+        content_type = reply.headers.get("content-type", "")
+        if not _JSON_CONTENT_TYPE_RE.match(content_type):
+            raise GitHubError(f"{what}: GitHub answered {content_type[:80]!r}, not JSON")
+        if len(reply.body) > EXACT_READ_MAX_BYTES:
+            raise GitHubError(f"{what}: the reply is over {EXACT_READ_MAX_BYTES} bytes")
+        try:
+            data = json.loads(reply.body.decode("utf-8"))
+        except ValueError:
+            raise GitHubError(f"{what}: the reply is not UTF-8 JSON") from None
+        if not isinstance(data, dict):
+            raise GitHubError(f"{what}: the reply is not a JSON object")
+        return data
+
+    # -- environment / doctor --------------------------------------------
+    def version(self) -> str:
+        res = self._run_gh(["--version"])
+        first = (res.stdout or "").strip().splitlines()
+        return first[0] if first else ""
+
+    def auth_status(self) -> tuple[bool, str]:
+        """(authenticated?, human-readable detail). Never raises for non-auth."""
+        try:
+            with gh_workdir() as workdir:
+                res = self._runner(
+                    gh_request(
+                        [self.gh_command, "auth", "status"],
+                        workdir,
+                        timeout_seconds=self.timeout_seconds,
+                    )
+                )
+        except Exception as exc:  # spawn failure etc.
+            return False, str(exc)
+        text = (res.stdout or "") + (res.stderr or "")
+        return res.exit_code == 0, text.strip()
+
+    # -- repository -------------------------------------------------------
+    def get_repo(self, repo: str) -> RepoInfo:
+        """``repo`` as 'owner/name'."""
+        data = self._api_json(["repo", "view", repo, "--json", "nameWithOwner,defaultBranchRef"])
+        return RepoInfo(
+            name_with_owner=data.get("nameWithOwner", repo),
+            default_branch=(data.get("defaultBranchRef") or {}).get("name", ""),
+        )
+
+    # -- branch rules (read-only; `doctor`) ---------------------------------
+    def get_required_status_check_rules(
+        self, repo: str, branch: str
+    ) -> list[RequiredStatusChecksRule]:
+        """The ``required_status_checks`` rules in effect on ``branch`` (may be empty).
+
+        Effective rules only: what GitHub *enforces* on the branch right now,
+        which is the question a merge gate asks. Every page is read, so an
+        empty result means no active ruleset requires a check, not that the
+        first page held none.
+        """
+        rules: list[RequiredStatusChecksRule] = []
+        for item in self._api_pages(f"repos/{repo}/rules/branches/{branch}"):
+            if not isinstance(item, dict) or item.get("type") != "required_status_checks":
+                continue
+            params = item.get("parameters") or {}
+            if not isinstance(params, dict):
+                raise GitHubError("branch rule `required_status_checks` has no parameters")
+            contexts = []
+            for check in params.get("required_status_checks") or []:
+                context = check.get("context") if isinstance(check, dict) else None
+                if not isinstance(context, str) or not context:
+                    raise GitHubError("branch rule `required_status_checks` names no context")
+                contexts.append(context)
+            rules.append(
+                RequiredStatusChecksRule(
+                    contexts=tuple(contexts),
+                    ruleset_id=_as_int(item.get("ruleset_id"), "ruleset_id"),
+                    ruleset_source=str(item.get("ruleset_source") or ""),
+                    ruleset_source_type=str(item.get("ruleset_source_type") or ""),
+                    strict=bool(params.get("strict_required_status_checks_policy", False)),
+                )
+            )
+        return rules
+
+    def get_ruleset(self, repo: str, ruleset_id: int) -> RulesetInfo:
+        """One ruleset with its enforcement level and bypass actors."""
+        data = self._api_json(["api", f"repos/{repo}/rulesets/{ruleset_id}"])
+        return _ruleset_from_data(data)
+
+    def list_rulesets(self, repo: str) -> list[RulesetInfo]:
+        """Every ruleset applying to ``repo`` (organization ones included), any enforcement."""
+        return [
+            _ruleset_from_data(item)
+            for item in self._api_pages(f"repos/{repo}/rulesets")
+            if isinstance(item, dict)
+        ]
+
+    def get_branch_protection(self, repo: str, branch: str) -> ClassicBranchProtection | None:
+        """Classic branch protection on ``branch``, or None when GitHub says it has none.
+
+        ``HTTP 404: Branch not protected`` is the conclusive negative answer
+        and yields None; an access failure propagates, because a token that
+        may not read the protection has not shown the branch to be
+        unprotected.
+        """
+        try:
+            data = self._api_json(["api", f"repos/{repo}/branches/{branch}/protection"])
+        except GitHubNotFoundError:
+            return None
+        checks = data.get("required_status_checks")
+        contexts: list[str] = []
+        if isinstance(checks, dict):
+            for context in checks.get("contexts") or []:
+                if isinstance(context, str) and context:
+                    contexts.append(context)
+            for check in checks.get("checks") or []:
+                context = check.get("context") if isinstance(check, dict) else None
+                if isinstance(context, str) and context and context not in contexts:
+                    contexts.append(context)
+        admins = data.get("enforce_admins")
+        return ClassicBranchProtection(
+            required_status_checks=isinstance(checks, dict),
+            required_contexts=tuple(contexts),
+            enforce_admins=bool(admins.get("enabled")) if isinstance(admins, dict) else False,
+        )
+
+    # -- issues -----------------------------------------------------------
+    def get_issue(self, url: str) -> IssueInfo:
+        ref = parse_issue_url(url)
+        data = self._api_json(
+            ["issue", "view", ref.canonical, "--json", "url,number,title,state,body"]
+        )
+        answered = data.get("url") if isinstance(data, dict) else None
+        if isinstance(answered, str) and "/pull/" in answered:
+            try:
+                pr = parse_pr_url(answered).canonical
+            except ConfigurationError:
+                pr = ""
+            if pr:
+                raise GitHubWrongTargetError(
+                    f"issue {ref.canonical}: `gh` answered with pull request {pr}", pr
+                )
+        issue = _decode_issue(data, f"issue {ref.canonical}")
+        if not parse_issue_url(issue.url).same_target(ref):
+            # A pull request of that number, or the issue it was transferred
+            # to: typed, so a caller can name which (#243).
+            raise GitHubWrongTargetError(
+                f"issue {ref.canonical}: `gh` answered with {issue.url}", issue.url
+            )
+        return issue
+
+    def get_issue_exact(self, url: str) -> IssueInfo:
+        """The issue as GitHub holds it, its title and body byte for byte (the exact read).
+
+        :meth:`get_pr_exact` for an issue. A pull request of that number, or
+        an issue transferred away (GitHub redirects it), is a conclusive
+        GitHubError.
+        """
+        ref = parse_issue_url(url)
+        what = f"exact read of {ref.canonical}"
+        path = f"repos/{_repository_path(ref.repository)}/issues/{ref.number}"
+        issue = _decode_issue(_rest_issue_row(self._exact_object(path, what)), what)
+        if not parse_issue_url(issue.url).same_target(ref):
+            raise GitHubWrongTargetError(f"{what}: GitHub answered with {issue.url}", issue.url)
+        return issue
+
+    def get_issue_state(self, url: str) -> str:
+        return self.get_issue(url).state
+
+    def edit_issue_body(self, url: str, body: str) -> None:
+        """Replace the whole body of an issue (``gh issue edit --body-file``).
+
+        The only controller-owned issue-body write: UPDATE_EPIC splices the
+        EPIC's managed roadmap section into a body it read moments before.
+        ``gh issue edit`` has no precondition, so the caller proves the write
+        did what it meant by reading the body back and comparing every byte
+        outside the managed section (``engine._apply_update_epic``); the exit
+        status alone is no evidence. The body is handed over in a private
+        temporary file that is removed whether or not ``gh`` succeeds.
+        """
+        fd, path = tempfile.mkstemp(prefix="autoforge-issue-body-", suffix=".md")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8", newline="") as handle:
+                handle.write(body)
+            self._run_gh(build_edit_issue_body_argv(url, path))
+        finally:
+            try:
+                os.unlink(path)
+            except FileNotFoundError:
+                pass
+
+    def list_open_issues(self, repo: str, *, strict: bool = False) -> list[IssueInfo]:
+        """Every open issue in ``repo`` (bodies included), pull requests excluded.
+
+        ``strict`` raises GitHubError instead of returning a set that may be
+        incomplete: the listing is bounded by :data:`STRICT_ISSUE_LIST_LIMIT`,
+        and a caller deciding "no such issue exists" must not confuse that
+        with "the issue was past the limit".
+        """
+        limit = STRICT_ISSUE_LIST_LIMIT if strict else 100
+        data = self._api_list(
+            [
+                "issue",
+                "list",
+                "--repo",
+                repo,
+                "--state",
+                "open",
+                "--limit",
+                str(limit),
+                "--json",
+                _ISSUE_LIST_FIELDS,
+            ]
+        )
+        # Truncation is judged on the rows `gh` returned, before any of them
+        # is decoded: a malformed row must not shorten the count below the
+        # ceiling and turn "may be truncated" into "complete".
+        if strict and len(data) >= limit:
+            raise GitHubError(
+                f"{repo} has at least {limit} open issues, so the listing may be truncated "
+                "and the set of follow-up issues cannot be established"
+            )
+        return [_decode_issue(d, f"open issue listing of {repo}") for d in data]
+
+    def issue_exists(self, url: str) -> bool:
+        try:
+            self.get_issue(url)
+            return True
+        except GitHubError:
+            return False
+
+    # -- the native EPIC dependency graph (read-only; ADR 0008 D3, #179) ---------
+    def get_repository_id(self, repo: str) -> int:
+        """GitHub's numeric id of ``repo`` (``owner/name``), the RunKey's repository part."""
+        path = _repository_path(repo)
+        data = self._api_json(["api", f"repos/{path}"])
+        return _positive_id(data, "id", f"repository {path}")
+
+    def get_issue_node(self, url: str) -> IssueNode:
+        """The eligibility facts of one issue (``GET .../issues/<n>``).
+
+        The answer must be the issue asked for: one GitHub answers for
+        another (a transferred issue's redirect, a pull request's number)
+        is a conclusive GitHubError.
+        """
+        ref = parse_issue_url(url)
+        path = f"repos/{_repository_path(ref.repository)}/issues/{ref.number}"
+        node = _decode_issue_node(self._api_json(["api", path]), f"issue {ref.canonical}")
+        if not node.ref.same_target(ref):
+            raise GitHubError(f"issue {ref.canonical}: GitHub answered with {node.url}")
+        return node
+
+    def list_sub_issues(self, url: str) -> tuple[IssueNode, ...]:
+        """Every direct native sub-issue of an issue, every page read, in API order.
+
+        Not recursive (ADR 0008 D3.1). The caller checks the length against
+        the parent's ``sub_issues_summary.total`` and de-duplicates by ``id``.
+        """
+        ref = parse_issue_url(url)
+        what = f"sub-issues of {ref.canonical}"
+        endpoint = (
+            f"repos/{_repository_path(ref.repository)}/issues/{ref.number}/sub_issues"
+            f"?per_page={_GRAPH_PAGE_SIZE}"
+        )
+        rows = self._api_full_pages(endpoint, _GRAPH_PAGE_SIZE, what)
+        return tuple(_decode_issue_node(row, what) for row in rows)
+
+    def list_blocked_by(self, url: str) -> tuple[BlockerNode, ...]:
+        """Every native ``blocked_by`` dependency of an issue, every page read, in API order.
+
+        ``blocking`` is never read (ADR 0008 D3.2). A blocker may live in
+        any repository; one the token may not read is a ``readable`` False
+        node (:func:`_decode_blocker`). The caller checks the length against
+        the issue's ``total_blocked_by`` and de-duplicates by ``id``.
+        """
+        ref = parse_issue_url(url)
+        what = f"blockers of {ref.canonical}"
+        endpoint = (
+            f"repos/{_repository_path(ref.repository)}/issues/{ref.number}"
+            f"/dependencies/blocked_by?per_page={_GRAPH_PAGE_SIZE}"
+        )
+        rows = self._api_full_pages(endpoint, _GRAPH_PAGE_SIZE, what)
+        return tuple(_decode_blocker(row, what) for row in rows)
+
+    # -- pull requests ------------------------------------------------------
+    @staticmethod
+    def _pr_from_data(row: object, what: str) -> PRInfo:
+        """One strict decoder for every PR view and listing (see ``_decode_issue``)."""
+        data = _row_object(row, what)
+        url = _text_field(data, "url", what)
+        try:
+            ref = parse_pr_url(url)
+        except ConfigurationError as exc:
+            raise GitHubError(
+                f"{what}: url {url!r} is not a GitHub pull request URL ({exc})"
+            ) from exc
+        number = _number_field(data, "number", what, ref.number)
+        checks = _rollup_checks(data, what)
+        linked: list[int] = []
+        for linked_issue in data.get("closingIssuesReferences") or []:
+            if isinstance(linked_issue, dict) and isinstance(linked_issue.get("number"), int):
+                linked.append(int(linked_issue["number"]))
+        head_repo = ""
+        hr = data.get("headRepository") or {}
+        hro = data.get("headRepositoryOwner") or {}
+        if isinstance(hr, dict) and hr.get("name"):
+            owner = hro.get("login", "") if isinstance(hro, dict) else ""
+            head_repo = f"{owner}/{hr['name']}" if owner else str(hr["name"])
+        return PRInfo(
+            url=ref.canonical,
+            number=number,
+            title=_text_field(data, "title", what),
+            state=_text_field(data, "state", what).upper(),
+            head_sha=_text_field(data, "headRefOid", what).lower(),
+            base_ref=_text_field(data, "baseRefName", what),
+            head_ref=_text_field(data, "headRefName", what),
+            mergeable=_text_field(data, "mergeable", what).upper(),
+            merge_state_status=_text_field(data, "mergeStateStatus", what).upper(),
+            auto_merge_enabled=data.get("autoMergeRequest") is not None,
+            is_draft=bool(data.get("isDraft", False)),
+            body=_text_field(data, "body", what),
+            repository=ref.repository,
+            head_repository=head_repo,
+            linked_issue_numbers=linked,
+            checks=checks,
+        )
+
+    def _view_pr(self, url: str, fields: str) -> PRInfo:
+        ref = parse_pr_url(url)
+        data = self._api_json(["pr", "view", ref.canonical, "--json", fields])
+        pr = self._pr_from_data(data, f"PR {ref.canonical}")
+        if not parse_pr_url(pr.url).same_target(ref):
+            raise GitHubError(f"PR {ref.canonical}: `gh` answered with {pr.url}")
+        return pr
+
+    def get_pr(self, url: str) -> PRInfo:
+        """The PR's identity read: state, HEAD, base, branch, body, links; no check results.
+
+        ``statusCheckRollup`` is not requested, so a credential GitHub
+        refuses the PR's check runs (#291) still reads the PR, and
+        ``checks`` is None ("not read"), never ``[]``. Every caller that
+        does not judge checks uses this read.
+        """
+        return self._view_pr(url, _PR_FIELDS)
+
+    def get_pr_exact(self, url: str) -> PRInfo:
+        """The PR as GitHub holds it, its title and body byte for byte (the exact read).
+
+        The fields a REST listing row carries (:meth:`list_prs_for_head`),
+        through the one PR decoder: state, HEAD, refs, head repository, title
+        and body; no checks, closing issues or mergeability. An effect's
+        read-back makes it when the text `gh` printed differs from the
+        payload, since `gh`'s sanitizer may have rewritten it. An answer
+        naming another PR is a conclusive GitHubError.
+        """
+        ref = parse_pr_url(url)
+        what = f"exact read of {ref.canonical}"
+        path = f"repos/{_repository_path(ref.repository)}/pulls/{ref.number}"
+        data = self._exact_object(path, what)
+        pr = self._pr_from_data(_rest_pr_row(data, what), what)
+        if not parse_pr_url(pr.url).same_target(ref):
+            raise GitHubError(f"{what}: GitHub answered with {pr.url}")
+        return pr
+
+    def get_pr_with_checks(self, url: str) -> PRInfo:
+        """The PR's checks read: the identity fields and the head's check results, at once.
+
+        One ``gh pr view`` answer, so the checks are those of the HEAD it
+        reports. ``checks`` is always a list here: ``[]`` is GitHub reporting
+        no check for the head, which is not a set of passed checks. GitHub
+        refusing this credential the check results raises
+        :class:`GitHubChecksAccessError` (conclusive, never retried, never a
+        not-found and never ``[]``); a 404, a transient failure and an
+        authentication failure are classified as for every other read.
+        """
+        pr = self._view_pr(url, _PR_CHECKS_FIELDS)
+        if pr.checks is None:
+            raise GitHubError(f"PR {pr.url}: `gh` returned no statusCheckRollup field")
+        return pr
+
+    def get_pr_head_sha(self, url: str) -> str:
+        return self.get_pr(url).head_sha
+
+    def get_pr_state(self, url: str) -> str:
+        return self.get_pr(url).state
+
+    def get_pr_branch(self, url: str) -> str:
+        return self.get_pr(url).head_ref
+
+    def get_pr_checks(self, url: str) -> list[CheckInfo]:
+        checks = self.get_pr_with_checks(url).checks
+        if checks is None:  # get_pr_with_checks never returns one; never read it as []
+            raise GitHubError(f"PR {url}: its check results were not read")
+        return checks
+
+    def list_checks_probe_candidates(self, repo: str) -> list[tuple[str, int]]:
+        """Open PRs whose head has check results, for `doctor`'s checks probe (#291).
+
+        ``(url, count)`` for each of the most recently updated open PRs
+        (one page of :data:`_CHECKS_PROBE_PAGE_SIZE`) whose head commit's
+        rollup counts at least one check result, in that order. The count
+        is GitHub's ``contexts.totalCount``, which it returns even to a
+        credential it refuses the check-run nodes, so this read selects a
+        PR to probe and proves nothing about the checks read itself. Not a
+        complete listing: a probe that finds no candidate here knows nothing.
+        """
+        what = f"open PRs of {repo} with check results"
+        owner, _, name = repo.partition("/")
+        data = self._graphql_data(
+            [
+                "api",
+                "graphql",
+                "-f",
+                f"query={_CHECKS_PROBE_QUERY}",
+                "-f",
+                f"owner={owner}",
+                "-f",
+                f"name={name}",
+            ],
+            what,
+        )
+        repository = data.get("repository")
+        connection = repository.get("pullRequests") if isinstance(repository, dict) else None
+        nodes = connection.get("nodes") if isinstance(connection, dict) else None
+        if not isinstance(nodes, list):
+            raise GitHubError(f"{what}: no pull-request nodes: {data!r:.200}")
+        found: list[tuple[str, int]] = []
+        for node in nodes:
+            row = _row_object(node, what)
+            url = _text_field(row, "url", what)
+            try:
+                ref = parse_pr_url(url)
+            except ConfigurationError as exc:
+                raise GitHubError(f"{what}: url {url!r} is not a pull request URL") from exc
+            commits = row.get("commits")
+            heads = commits.get("nodes") if isinstance(commits, dict) else None
+            if not isinstance(heads, list):
+                raise GitHubError(f"{what}: {ref.canonical} has no commit nodes")
+            count = 0
+            for head in heads:
+                commit = head.get("commit") if isinstance(head, dict) else None
+                rollup = commit.get("statusCheckRollup") if isinstance(commit, dict) else None
+                contexts = rollup.get("contexts") if isinstance(rollup, dict) else None
+                total = contexts.get("totalCount") if isinstance(contexts, dict) else 0
+                if isinstance(total, int) and not isinstance(total, bool):
+                    count = max(count, total)
+            if count > 0:
+                found.append((ref.canonical, count))
+        return found
+
+    def get_pr_changed_files(self, url: str) -> ChangedFiles:
+        """Every file the PR changes, a rename's former path included.
+
+        Read through the REST files endpoint rather than ``gh pr view --json
+        files``: the GraphQL type behind that flag carries a file's *current*
+        path only, so a renamed file appears there under its new name alone.
+        A caller refusing on protected paths would then miss a PR that renames
+        a protected file *out* of the protected range -- the same edit
+        dressed differently. REST names the other end ``previous_filename``.
+
+        Every page is read (``gh api --paginate --slurp``), so the listing
+        is short only past GitHub's own 3000-file ceiling on this endpoint,
+        not past one page of it.
+
+        The count comes from ``gh pr view`` because REST has none, and is read
+        *after* the listing so that a file added between the two reads makes
+        the listing look short (fail closed) rather than complete. Missing,
+        non-list or unusable data raises GitHubError; a short listing is
+        reported as incomplete rather than as "these are all the files".
+        """
+        ref = parse_pr_url(url)
+        endpoint = f"repos/{ref.repository}/pulls/{ref.number}/files"
+        raw = self._api_pages(f"{endpoint}?per_page={_PR_FILES_PAGE_SIZE}")
+        files: list[ChangedFile] = []
+        for entry in raw:
+            path = entry.get("filename") if isinstance(entry, dict) else None
+            previous = entry.get("previous_filename") if isinstance(entry, dict) else None
+            bad_previous = previous is not None and (not isinstance(previous, str) or not previous)
+            if not isinstance(path, str) or not path or bad_previous:
+                raise GitHubError(
+                    f"changed files of {ref.canonical} contain an unusable entry: {entry!r}"
+                )
+            files.append(ChangedFile(path=path, previous_path=previous or ""))
+        data = self._api_json(["pr", "view", ref.canonical, "--json", "changedFiles"])
+        total = data.get("changedFiles")
+        if isinstance(total, bool) or not isinstance(total, int) or total < 0:
+            raise GitHubError(f"changedFiles of {ref.canonical} is not a count: {total!r}")
+        return ChangedFiles(files=tuple(files), total=total)
+
+    def get_pr_close_event_count(self, url: str) -> int:
+        """How many times the PR has been closed so far, from its issue events.
+
+        The replan transaction records this immediately before it persists
+        its close intent (#69). Issue events are append-only: GitHub writes a
+        ``closed`` event for every close (a merge included) and no actor can
+        delete one, so a count that is higher on a later read proves a close
+        happened in between, and an equal count proves none did -- whoever
+        would have performed it. That is what lets a resume that finds the
+        source OPEN under a recorded intent distinguish "the close never
+        ran" from "it landed, lost its receipt to a crash, and a human
+        reopened the PR" without comparing clocks and without turning the
+        absence of a comment into a licence to close.
+
+        Read through the REST issue-events endpoint (a PR is an issue there),
+        every page (``gh api --paginate --slurp``), and counted strictly: an
+        entry without a string ``event`` name is a malformed answer, refused
+        rather than skipped, because a skipped event would lower the count
+        and a lower count is what licenses the retry.
+        """
+        ref = parse_pr_url(url)
+        endpoint = f"repos/{ref.repository}/issues/{ref.number}/events"
+        count = 0
+        for entry in self._api_pages(f"{endpoint}?per_page={_EVENTS_PAGE_SIZE}"):
+            kind = entry.get("event") if isinstance(entry, dict) else None
+            if not isinstance(kind, str) or not kind:
+                raise GitHubError(
+                    f"issue events of {ref.canonical} contain an unusable entry: {entry!r:.200}"
+                )
+            if kind == "closed":
+                count += 1
+        return count
+
+    def get_pr_merge_queue_status(self, url: str) -> MergeQueueStatus:
+        """Whether the PR's base branch requires a merge queue / the PR is enqueued.
+
+        ``gh pr merge`` silently switches to auto-merge or queue insertion on
+        such branches, so the engine must know this *before* writing. Missing
+        or non-boolean data raises GitHubError (fail closed).
+        """
+        ref = parse_pr_url(url)
+        owner, _, name = ref.repository.partition("/")
+        data = self._api_json(
+            [
+                "api",
+                "graphql",
+                "-f",
+                f"query={_MERGE_QUEUE_QUERY}",
+                "-F",
+                f"owner={owner}",
+                "-F",
+                f"name={name}",
+                "-F",
+                f"number={ref.number}",
+            ]
+        )
+        pr = ((data.get("data") or {}).get("repository") or {}).get("pullRequest")
+        if not isinstance(pr, dict):
+            raise GitHubError(f"merge-queue status for {ref.canonical} unavailable: {data}")
+        enabled = pr.get("isMergeQueueEnabled")
+        in_queue = pr.get("isInMergeQueue")
+        if not isinstance(enabled, bool) or not isinstance(in_queue, bool):
+            raise GitHubError(f"merge-queue status for {ref.canonical} is not boolean: {pr}")
+        return MergeQueueStatus(enabled=enabled, in_queue=in_queue)
+
+    # -- GitHub Actions (the definition behind a required check) -------------
+    def _run_from_data(self, data: object, what: str) -> WorkflowRunInfo:
+        if not isinstance(data, dict):
+            raise GitHubError(f"{what} is not an object: {data!r:.200}")
+        repo = data.get("repository")
+        full_name = repo.get("full_name") if isinstance(repo, dict) else None
+        run_id = data.get("id")
+        workflow_id = data.get("workflow_id")
+        attempt = data.get("run_attempt", 1)
+        head_sha = data.get("head_sha")
+        for name, value in (("id", run_id), ("workflow_id", workflow_id), ("run_attempt", attempt)):
+            if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+                raise GitHubError(f"{what} has no usable {name}: {value!r}")
+        assert isinstance(run_id, int) and isinstance(workflow_id, int)
+        assert isinstance(attempt, int)
+        if not isinstance(full_name, str) or not full_name:
+            raise GitHubError(f"{what} names no repository: {repo!r:.200}")
+        if not isinstance(head_sha, str) or not head_sha:
+            raise GitHubError(f"{what} has no head_sha: {head_sha!r}")
+        text = {
+            key: value if isinstance(value := data.get(key), str) else ""
+            for key in ("path", "event", "head_branch", "status", "conclusion")
+        }
+        if not text["path"] or not text["status"]:
+            raise GitHubError(f"{what} has no workflow path or status: {data!r:.200}")
+        return WorkflowRunInfo(
+            id=run_id,
+            repository=full_name,
+            path=text["path"],
+            workflow_id=workflow_id,
+            event=text["event"],
+            head_sha=head_sha.lower(),
+            head_branch=text["head_branch"],
+            status=text["status"],
+            conclusion=text["conclusion"],
+            run_attempt=attempt,
+        )
+
+    def get_workflow_run(self, repository: str, run_id: int) -> WorkflowRunInfo:
+        """One workflow run by id, in the repository the check's URL names."""
+        what = f"workflow run {run_id} of {repository}"
+        data = self._api_json(["api", f"repos/{repository}/actions/runs/{run_id}"])
+        return self._run_from_data(data, what)
+
+    def get_workflow_run_jobs(self, repository: str, run_id: int) -> WorkflowRunJobs:
+        """Every job of the run's latest attempt with its step names, all pages read.
+
+        The endpoint answers an object per page (``total_count`` + ``jobs``);
+        the count comes from GitHub, so a listing that does not reach it is
+        reported as incomplete rather than as "these are all the jobs". A job
+        without a usable name, or a step without one, is malformed data
+        (GitHubError): the comparison built on it would compare nothing.
+        """
+        what = f"the jobs of workflow run {run_id} of {repository}"
+        endpoint = f"repos/{repository}/actions/runs/{run_id}/jobs?per_page={_JOBS_PAGE_SIZE}"
+        pages = self._json(["api", "--paginate", "--slurp", endpoint])
+        if not isinstance(pages, list) or not all(isinstance(page, dict) for page in pages):
+            raise GitHubError(f"{what}: non-paginated JSON payload: {pages!r:.200}")
+        total = -1
+        jobs: list[WorkflowJob] = []
+        for page in pages:
+            count = page.get("total_count")
+            if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+                raise GitHubError(f"{what}: total_count is not a count: {count!r}")
+            total = max(total, count)
+            listed = page.get("jobs")
+            if not isinstance(listed, list):
+                raise GitHubError(f"{what}: jobs is not a list: {listed!r:.200}")
+            for job in listed:
+                name = job.get("name") if isinstance(job, dict) else None
+                steps = job.get("steps") if isinstance(job, dict) else None
+                if not isinstance(name, str) or not name or not isinstance(steps, list):
+                    raise GitHubError(f"{what}: unusable job entry: {job!r:.200}")
+                names: list[str] = []
+                for step in steps:
+                    step_name = step.get("name") if isinstance(step, dict) else None
+                    if not isinstance(step_name, str) or not step_name:
+                        raise GitHubError(
+                            f"{what}: job {name!r} has an unusable step: {step!r:.200}"
+                        )
+                    names.append(step_name)
+                jobs.append(WorkflowJob(name=name, steps=tuple(names)))
+        if total < 0:
+            raise GitHubError(f"{what}: no page was returned")
+        return WorkflowRunJobs(jobs=tuple(jobs), total=total)
+
+    def get_branch_head_sha(self, repository: str, branch: str) -> str:
+        """The commit a branch currently points at (lower-case SHA)."""
+        data = self._api_json(["api", f"repos/{repository}/branches/{branch}"])
+        commit = data.get("commit")
+        sha = commit.get("sha") if isinstance(commit, dict) else None
+        if not isinstance(sha, str) or not sha:
+            raise GitHubError(f"branch {branch!r} of {repository} has no readable head SHA")
+        return sha.lower()
+
+    def get_branch_ref(self, repository: str, branch: str) -> str | None:
+        """The commit ``refs/heads/<branch>`` of ``repository`` points at; None when absent.
+
+        One exact ref, through ``git/ref/heads/<branch>``: the singular
+        endpoint answers that ref or a 404, where the plural one answers a
+        prefix with every ref under it. A 404 is the branch not existing
+        (the caller reads a repository it can read). An answer naming another
+        ref, or a ref that is not a commit, is a conclusive GitHubError,
+        never "absent" (#283).
+        """
+        what = f"branch {branch!r} of {repository}"
+        path = f"repos/{_repository_path(repository)}/git/ref/heads/{_branch_path(branch, what)}"
+        try:
+            data = self._api_json(["api", path])
+        except GitHubNotFoundError:
+            return None
+        target = data.get("object")
+        sha = target.get("sha") if isinstance(target, dict) else None
+        if (
+            data.get("ref") != f"refs/heads/{branch}"
+            or not isinstance(target, dict)
+            or target.get("type") != "commit"
+            or not isinstance(sha, str)
+            or not _FULL_SHA_RE.fullmatch(sha.lower())
+        ):
+            raise GitHubError(f"{what}: GitHub answered with another ref, or an unreadable one")
+        return sha.lower()
+
+    def get_merge_base_sha(self, repository: str, base_ref: str, head_sha: str) -> str:
+        """The merge base of a base branch and a commit (lower-case SHA).
+
+        This is the commit a PR diff is computed against, so it is what a
+        review is bound to (#96): a base branch rewritten under the same
+        name (force-push, reset) moves it while the base *name* and the PR
+        HEAD stay put; ordinary commits landing on the base do not move it.
+
+        Read through the compare endpoint, projected with ``--jq`` before it
+        reaches the controller: the full response carries every commit and
+        every file patch between the two revisions, which for a long-lived
+        base can exceed the executor's output bound, and truncated `gh`
+        output is refused rather than parsed. The base is percent-encoded
+        (git allows ``#`` and ``%`` in a ref name) and the head is the
+        reviewed commit itself, never a branch name, so the answer cannot
+        change under the read.
+        """
+        if not _SHA40_RE.fullmatch(head_sha.lower()):
+            raise GitHubError(f"merge base of {base_ref!r}: head {head_sha!r} is not a full SHA")
+        data = self._api_json(
+            [
+                "api",
+                f"repos/{repository}/compare/{quote(base_ref, safe='')}...{head_sha.lower()}",
+                "--jq",
+                "{merge_base_sha: .merge_base_commit.sha}",
+            ]
+        )
+        sha = data.get("merge_base_sha")
+        if not isinstance(sha, str) or not _SHA40_RE.fullmatch(sha.lower()):
+            raise GitHubError(
+                f"merge base of {base_ref!r} and {head_sha[:12]} of {repository} is unreadable:"
+                f" {sha!r:.100}"
+            )
+        return sha.lower()
+
+    def find_workflow_runs(
+        self, repository: str, workflow_id: int, *, branch: str, event: str, head_sha: str
+    ) -> WorkflowRuns:
+        """Runs of one workflow filtered by branch, event and head commit, all pages read.
+
+        The runs of a single commit on a single branch are normally one, but
+        the caller picks a *reference* out of them, so the listing is read
+        like the jobs listing: every page, against GitHub's own
+        ``total_count``, and a listing that does not reach it is reported as
+        incomplete rather than as "these are all the runs".
+        """
+        query = urlencode(
+            {"branch": branch, "event": event, "head_sha": head_sha, "per_page": _RUNS_PAGE_SIZE}
+        )
+        what = f"the runs of workflow {workflow_id} of {repository}"
+        endpoint = f"repos/{repository}/actions/workflows/{workflow_id}/runs?{query}"
+        pages = self._json(["api", "--paginate", "--slurp", endpoint])
+        if not isinstance(pages, list) or not all(isinstance(page, dict) for page in pages):
+            raise GitHubError(f"{what}: non-paginated JSON payload: {pages!r:.200}")
+        total = -1
+        runs: list[WorkflowRunInfo] = []
+        for page in pages:
+            count = page.get("total_count")
+            if isinstance(count, bool) or not isinstance(count, int) or count < 0:
+                raise GitHubError(f"{what}: total_count is not a count: {count!r}")
+            total = max(total, count)
+            listed = page.get("workflow_runs")
+            if not isinstance(listed, list):
+                raise GitHubError(f"{what}: workflow_runs is not a list: {listed!r:.200}")
+            runs.extend(self._run_from_data(run, f"a run in {what}") for run in listed)
+        if total < 0:
+            raise GitHubError(f"{what}: no page was returned")
+        return WorkflowRuns(runs=tuple(runs), total=total)
+
+    def pr_exists(self, url: str) -> bool:
+        """Whether GitHub resolves the PR: False only for a conclusive not-found.
+
+        Any other failure propagates: a refused read (authentication,
+        permissions, a refused checks read, #291), malformed data or a
+        transient error says nothing about whether the PR exists, so it is
+        never reported as its absence.
+        """
+        try:
+            self.get_pr(url)
+            return True
+        except GitHubNotFoundError:
+            return False
+
+    def _walk_connection(
+        self,
+        query: str,
+        variables: list[str],
+        connection_of: Callable[[dict, str], dict],
+        what: str,
+    ) -> Iterator[object]:
+        """Every node of one GraphQL connection, read by cursor to its end.
+
+        ``variables`` are the query's ``-f``/``-F`` arguments; the walk adds
+        ``after``. ``connection_of`` picks the connection out of a page's
+        ``data``, raising (its message led by the page's name) when the page
+        does not hold one. Nodes are yielded page by page, as read and
+        undecoded. Pages are walked until GitHub says there is no next one;
+        a page GitHub answered with errors (so possibly partial), a
+        connection without usable ``nodes`` and ``pageInfo``, a next page
+        GitHub announces without a cursor to reach it, or a cursor the walk
+        already used (a cycle) is a conclusive GitHubError, never a shorter
+        listing.
+        """
+        after: str | None = None
+        # Every cursor the walk has already asked for. A cursor that comes
+        # back a second time, however many pages later, would walk a cycle
+        # forever; the walk terminates only because each page's cursor is new.
+        used_cursors: set[str] = set()
+        page_number = 0
+        while True:
+            page_number += 1
+            args = ["api", "graphql", "-f", f"query={query}", *variables]
+            if after is not None:
+                args += ["-f", f"after={after}"]
+            page_what = f"{what}, page {page_number}"
+            connection = connection_of(self._graphql_data(args, page_what), page_what)
+            nodes = connection.get("nodes")
+            info = connection.get("pageInfo")
+            if not isinstance(nodes, list) or not isinstance(info, dict):
+                raise GitHubError(
+                    f"{page_what} has no usable nodes or pageInfo: {connection!r:.200}"
+                )
+            yield from nodes
+            has_next = info.get("hasNextPage")
+            if not isinstance(has_next, bool):
+                raise GitHubError(
+                    f"{page_what} does not say whether a next page exists: {info!r:.200}"
+                )
+            if not has_next:
+                return
+            cursor = info.get("endCursor")
+            if not isinstance(cursor, str) or not cursor:
+                raise GitHubError(
+                    f"{what} cannot be read to its end: page {page_number} announces a "
+                    f"next page but no cursor that reaches it ({cursor!r})"
+                )
+            if cursor in used_cursors:
+                raise GitHubError(
+                    f"{what} cannot be read to its end: page {page_number} announces a "
+                    f"next page behind a cursor the walk already used ({cursor!r})"
+                )
+            used_cursors.add(cursor)
+            after = cursor
+
+    def list_open_prs(self, repo: str) -> list[PRInfo]:
+        """Every open PR in ``repo`` (bodies included), read to the end.
+
+        The listing is complete or it raises: every caller decides "no
+        candidate exists" on it (an ANALYZE_EXECUTE entry launching an
+        implementer, a replan concluding no replacement was created), and
+        "the candidate was past a limit" must never be reported as absence
+        (issue #20). The pages are walked by cursor
+        (:meth:`_walk_connection`), so a page that cannot be read or walked
+        past is a conclusive GitHubError, never a shorter list. A PR seen
+        twice (the listing moved under the walk) is kept once.
+        """
+        what = f"open PR listing of {repo}"
+        owner, _, name = repo.partition("/")
+
+        def pull_requests(data: dict, page_what: str) -> dict:
+            repository = data.get("repository")
+            if not isinstance(repository, dict):
+                raise GitHubError(f"{page_what}: repository is not readable: {repository!r:.200}")
+            connection = repository.get("pullRequests")
+            if not isinstance(connection, dict):
+                raise GitHubError(
+                    f"{page_what} is not a pull-request connection: {connection!r:.200}"
+                )
+            return connection
+
+        # `-f` sends each variable as a string. `-F` would type-coerce it: an
+        # all-digit owner login would become an integer and a repository
+        # named `null`, `true` or `false` a null or boolean, which GitHub
+        # refuses for a `String!` variable.
+        variables = ["-f", f"owner={owner}", "-f", f"name={name}"]
+        prs: list[PRInfo] = []
+        seen: set[int] = set()
+        for node in self._walk_connection(_OPEN_PR_PAGE_QUERY, variables, pull_requests, what):
+            row = _row_object(node, what)
+            # `gh pr list --json` flattens this connection to its nodes; the
+            # decoder reads that shape. The connection is validated here,
+            # before flattening: a malformed one must not read as "this PR
+            # closes no issue".
+            linked = _linked_issue_nodes(row.get("closingIssuesReferences"), what)
+            pr = self._pr_from_data(dict(row, closingIssuesReferences=linked), what)
+            if pr.number in seen:
+                continue
+            seen.add(pr.number)
+            prs.append(pr)
+        return prs
+
+    def list_all_prs(self, repo: str, *, strict: bool = False) -> list[PRInfo]:
+        """Every PR in ``repo`` across all states (bodies included).
+
+        Needed where "no candidate exists" must be proven, not assumed: a
+        replacement the agent created and that was then closed is invisible to
+        :meth:`list_open_prs`, and treating it as absent would start a second
+        implementation attempt. ``strict`` refuses a possibly-truncated
+        listing instead of reporting it as complete.
+        """
+        limit = STRICT_PR_LIST_LIMIT if strict else 100
+        data = self._api_list(
+            [
+                "pr",
+                "list",
+                "--repo",
+                repo,
+                "--state",
+                "all",
+                "--limit",
+                str(limit),
+                "--json",
+                _PR_LIST_FIELDS,
+            ]
+        )
+        if strict and len(data) >= limit:
+            raise GitHubError(
+                f"{repo} has at least {limit} pull requests, so the listing may be "
+                "truncated and the set of candidates cannot be established"
+            )
+        return [self._pr_from_data(d, f"PR listing of {repo}") for d in data]
+
+    def latest_pr_number(self, repo: str) -> int:
+        """The largest PR number that currently exists in ``repo`` (0 if none).
+
+        Used as a provenance watermark: a PR whose number is <= the value read
+        before a replan transaction id was generated cannot have been created
+        after it, so it can never be that transaction's replacement even if the
+        marker is later copied into its body.
+
+        Implemented as a proven numeric maximum over ``--state all`` (open,
+        closed and merged alike), never inferred from one CREATED_AT-ordered
+        node. A listing that reaches the ceiling, or malformed number data,
+        raises GitHubError (fail closed) rather than returning an
+        under-estimate that would let a pre-existing PR slip past the
+        watermark.
+        """
+        data = self._api_list(
+            [
+                "pr",
+                "list",
+                "--repo",
+                repo,
+                "--state",
+                "all",
+                "--limit",
+                str(STRICT_PR_LIST_LIMIT),
+                "--json",
+                _PR_NUMBER_LIST_FIELDS,
+            ]
+        )
+        if len(data) >= STRICT_PR_LIST_LIMIT:
+            raise GitHubError(
+                f"{repo} has at least {STRICT_PR_LIST_LIMIT} pull requests, so the latest "
+                "pull-request number cannot be established"
+            )
+        highest = 0
+        for entry in data:
+            if not isinstance(entry, dict):
+                raise GitHubError(
+                    f"latest pull-request number for {repo} is not an object: {entry!r}"
+                )
+            number = entry.get("number")
+            if not isinstance(number, int) or isinstance(number, bool) or number < 1:
+                raise GitHubError(
+                    f"latest pull-request number for {repo} is not a number: {entry!r}"
+                )
+            highest = max(highest, number)
+        return highest
+
+    # -- effect identity reads (ADR 0004 D4.5, D7.5) -----------------------------
+    def commit_in_history(self, repository: str, base_sha: str, commit_sha: str) -> bool:
+        """Whether ``commit_sha`` is in the history of ``base_sha``, in GitHub's word (D7.5).
+
+        Read through the compare endpoint with ``base_sha`` as the base and
+        the commit as the head, projected to its ``status`` with ``--jq``
+        (the full answer carries every commit and patch between the two):
+        ``behind`` or ``identical`` means the commit is an ancestor of, or
+        equal to, the base; ``ahead`` or ``diverged`` means it is not. A 404
+        means GitHub does not know the commit as part of this repository, so
+        it is not in the history: that is a definitive answer, not a
+        transient one. (GitHub also answers 404 for an unknown base or a
+        repository it does not show; reading that as "not in the history"
+        only widens what the caller has to publish.) Any other status is a
+        conclusive GitHubError, never guessed.
+
+        Both SHAs must be full object ids (40 or 64 hex digits), checked
+        before any process runs: a branch name or a short SHA could resolve
+        differently between the read and its use.
+        """
+        what = f"history of {base_sha!r:.80} in {repository!r:.120}"
+        base = _full_sha(base_sha, "base", what)
+        commit = _full_sha(commit_sha, "commit", what)
+        repo = _repository_path(repository)
+        try:
+            res = self._run_gh(
+                ["api", f"repos/{repo}/compare/{base}...{commit}", "--jq", ".status"]
+            )
+        except GitHubNotFoundError:
+            return False
+        status = res.stdout.strip()
+        if status in _IN_HISTORY_STATUSES:
+            return True
+        if status in _NOT_IN_HISTORY_STATUSES:
+            return False
+        raise GitHubError(
+            f"{what}: the compare of {commit[:12]} answered an unknown status {status!r:.40}"
+        )
+
+    def latest_issue_number(self, repository: str) -> int:
+        """The largest issue *or pull-request* number in ``repository`` (0 if none).
+
+        The K5 provenance watermark, mirroring :meth:`latest_pr_number`: an
+        issue whose number is <= the value read before a create cannot be
+        the issue that create made. Issues and pull requests share one
+        number sequence, and the REST issues listing returns both (a pull
+        request is an issue there), so the maximum is taken over both: it is
+        the last number GitHub handed out, whichever kind took it.
+
+        A proven numeric maximum over the all-states listing read to its
+        end (``--paginate``, which, unlike ``gh pr list --limit``, has no
+        ceiling that could cut it short), projected to the numbers with
+        ``--jq`` so a large repository's bodies never reach the executor's
+        output bound. Never inferred from creation order. A row without a
+        positive integer number raises GitHubError (fail closed), as does a
+        listing that cannot be read to its end.
+        """
+        repo = _repository_path(repository)
+        endpoint = f"repos/{repo}/issues?" + urlencode({"state": "all", "per_page": 100})
+        res = self._run_gh(["api", "--paginate", endpoint, "--jq", ".[].number"])
+        highest = 0
+        for line in res.stdout.splitlines():
+            text = line.strip()
+            if not text:
+                continue
+            if not text.isdigit() or not text.isascii() or int(text) < 1:
+                raise GitHubError(
+                    f"latest issue number for {repo}: a listed number is not a positive "
+                    f"integer: {text!r:.40}"
+                )
+            highest = max(highest, int(text))
+        return highest
+
+    def list_issues_above(self, repository: str, watermark: int) -> list[IssueInfo]:
+        """Every issue of ``repository`` numbered above ``watermark``, in any state.
+
+        The K5 identity read (D4.5): the all-states listing read newest
+        first (``sort=created``, ``direction=desc``) down to the watermark,
+        never the search API. Pull requests, which the REST issues listing
+        also returns (marked by a ``pull_request`` key), are not issues and
+        are left out; they still mark where the walk is, since they share
+        the number sequence.
+
+        GitHub orders by creation time to the second, so rows created in
+        the same second may come in any order: the walk does not stop at
+        the first row at or below the watermark, but reads on while the
+        listing is still in that row's second, and keeps every issue above
+        the watermark it meets. A listing that ends first is read to its
+        end. The result is newest first. (An issue transferred in keeps its
+        old creation time under a new number, so it may sort below the
+        watermark's second and not be listed; it is not an issue the
+        caller created.)
+
+        A malformed row, or a listing that cannot be read down to the
+        watermark within ``_ISSUE_WALK_MAX_PAGES`` pages, raises GitHubError.
+        """
+        if isinstance(watermark, bool) or not isinstance(watermark, int) or watermark < 0:
+            raise GitHubError(f"issues above {watermark!r:.40}: the watermark is not a number")
+        repo = _repository_path(repository)
+        what = f"issues of {repo} above #{watermark}"
+        found: dict[int, IssueInfo] = {}
+        boundary: datetime | None = None
+        for page in range(1, _ISSUE_WALK_MAX_PAGES + 1):
+            endpoint = f"repos/{repo}/issues?" + urlencode(
+                {
+                    "state": "all",
+                    "sort": "created",
+                    "direction": "desc",
+                    "per_page": _ISSUE_PAGE_SIZE,
+                    "page": page,
+                }
+            )
+            rows = [_listed_issue(row, what) for row in self._api_list(["api", endpoint])]
+            for row in rows:
+                if row.number <= watermark:
+                    if boundary is None:
+                        boundary = row.created_at
+                    continue
+                if row.is_pull_request or row.number in found:
+                    continue
+                issue = _decode_issue(_rest_issue_row(row.row), what)
+                if issue.repository.lower() != repo.lower():
+                    raise GitHubError(f"{what}: the listing returned {issue.url}")
+                found[row.number] = issue
+            if len(rows) < _ISSUE_PAGE_SIZE:
+                break
+            if boundary is not None and rows[-1].created_at < boundary:
+                break
+        else:
+            raise GitHubError(
+                f"{what}: the listing cannot be read down to the watermark within "
+                f"{_ISSUE_WALK_MAX_PAGES * _ISSUE_PAGE_SIZE} rows"
+            )
+        return sorted(found.values(), key=lambda issue: issue.number, reverse=True)
+
+    def list_prs_for_head(self, repository: str, branch: str) -> list[PRInfo]:
+        """Every PR of ``repository`` headed at ``branch`` of the same repository, any state.
+
+        The K2/K7 identity read (D4.5): the REST pulls listing filtered by
+        ``head=<owner>:<branch>`` and ``state=all``, read to the end, so it
+        sees closed and merged PRs too; never the search API. A row the
+        filter returns that is not headed at ``branch`` of this repository
+        (a fork's PR, or a PR whose head repository is gone) is left out.
+
+        The rows go through the one PR decoder; the REST listing carries
+        neither closing-issue references, mergeability nor checks, so those
+        are empty (``checks`` None, not read): a caller that needs them reads
+        the PR with :meth:`get_pr`, or :meth:`get_pr_with_checks` for the checks.
+        """
+        repo = _repository_path(repository)
+        if not isinstance(branch, str) or not branch.strip() or ":" in branch:
+            raise GitHubError(f"PRs of {repo}: head branch {branch!r:.120} is not a branch name")
+        owner = repo.split("/", 1)[0]
+        what = f"PRs of {repo} headed at {branch!r:.120}"
+        endpoint = f"repos/{repo}/pulls?" + urlencode(
+            {"state": "all", "head": f"{owner}:{branch}", "per_page": _HEAD_PR_PAGE_SIZE}
+        )
+        prs: list[PRInfo] = []
+        for row in self._api_pages(endpoint):
+            pr = self._pr_from_data(_rest_pr_row(row, what), what)
+            if pr.repository.lower() != repo.lower():
+                raise GitHubError(f"{what}: the listing returned {pr.url}")
+            if pr.head_ref == branch and pr.head_repository.lower() == repo.lower():
+                prs.append(pr)
+        return sorted(prs, key=lambda pr: pr.number, reverse=True)
+
+    # -- typed effect writes (ADR 0004 D12.2) ------------------------------------
+    # One method per effect kind, each issued once outside the retry loop
+    # (D4.3, :meth:`_run_gh_once`), its payload on stdin, the repository in
+    # the API path (D7.4). The typed result is what GitHub's reply says it
+    # wrote: informational, never the evidence; the caller reads it back.
+    def create_issue_comment(self, issue_url: str, body: str) -> CreatedObject:
+        """Post ``body`` as a new comment on an issue (K8)."""
+        ref = parse_issue_url(issue_url)
+        what = f"comment on {ref.canonical}"
+        _check_write_bounds(what, body=body)
+        path = f"repos/{_repository_path(ref.repository)}/issues/{ref.number}/comments"
+        return _created_comment(self._write("POST", path, {"body": body}, what), ref, what)
+
+    def create_pr_comment(self, pr_url: str, body: str) -> CreatedObject:
+        """Post ``body`` as a new comment on a pull request (K4).
+
+        A PR's conversation comments are issue comments to the REST API, so
+        this is the issues comments endpoint with the PR's number.
+        """
+        ref = parse_pr_url(pr_url)
+        what = f"comment on {ref.canonical}"
+        _check_write_bounds(what, body=body)
+        path = f"repos/{_repository_path(ref.repository)}/issues/{ref.number}/comments"
+        return _created_comment(self._write("POST", path, {"body": body}, what), ref, what)
+
+    def create_pull_request(
+        self, repository: str, *, base: str, head: str, title: str, body: str
+    ) -> CreatedObject:
+        """Open a PR from ``head`` onto ``base``, both branches of ``repository`` (K2, K7).
+
+        ``head`` is a branch of the same repository: an ``owner:branch``
+        head would open a PR from another repository, so a ``:`` in it is
+        refused (git forbids it in a branch name anyway). A 422 such as
+        "a pull request already exists" is a conclusive GitHubError.
+        """
+        repo = _repository_path(repository)
+        what = f"pull request {head!r:.120} -> {base!r:.120} in {repo}"
+        for role, name in (("base", base), ("head", head)):
+            if not isinstance(name, str) or not name.strip() or ":" in name:
+                raise GitHubError(f"{what}: {role} {name!r:.120} is not a branch name")
+        _check_write_bounds(what, body=body, title=title)
+        payload = {"title": title, "head": head, "base": base, "body": body}
+        reply = self._write("POST", f"repos/{repo}/pulls", payload, what)
+        return _replied_object(reply, what, repository=repo, expect="pr")
+
+    def write_pr_body(self, pr_url: str, body: str) -> None:
+        """Replace the whole body of a pull request (K3)."""
+        ref = parse_pr_url(pr_url)
+        what = f"body of {ref.canonical}"
+        _check_write_bounds(what, body=body)
+        path = f"repos/{_repository_path(ref.repository)}/pulls/{ref.number}"
+        reply = self._write("PATCH", path, {"body": body}, what)
+        _replied_object(reply, what, repository=ref.repository, expect="pr", number=ref.number)
+
+    def create_issue(self, repository: str, *, title: str, body: str) -> CreatedObject:
+        """Open a new issue in ``repository`` (K5)."""
+        repo = _repository_path(repository)
+        what = f"new issue in {repo}"
+        _check_write_bounds(what, body=body, title=title)
+        reply = self._write("POST", f"repos/{repo}/issues", {"title": title, "body": body}, what)
+        return _replied_object(reply, what, repository=repo, expect="issue")
+
+    def write_issue_body(self, issue_url: str, body: str) -> None:
+        """Replace the whole body of an issue (K6).
+
+        Unlike :meth:`edit_issue_body`, the EPIC roadmap splice that keeps
+        its own mechanism (D5.4), this is the typed effect write: issued
+        once, payload on stdin, reply checked to name the issue.
+        """
+        ref = parse_issue_url(issue_url)
+        what = f"body of {ref.canonical}"
+        _check_write_bounds(what, body=body)
+        path = f"repos/{_repository_path(ref.repository)}/issues/{ref.number}"
+        reply = self._write("PATCH", path, {"body": body}, what)
+        # A PR is an issue to this endpoint: the reply may name it by either path.
+        _replied_object(reply, what, repository=ref.repository, expect=None, number=ref.number)
+
+    # -- merge (the only write; controller-owned, engine-gated) ------------------
+    def merge_pr(self, url: str, method: str = "squash", match_head_sha: str = "") -> None:
+        """Run ``gh pr merge`` bound to ``match_head_sha``.
+
+        Raises GitHubError when ``gh`` fails (conflict, branch protection,
+        HEAD moved, permissions, ...). A normal return only means ``gh``
+        exited 0: callers must re-read the PR and confirm ``state == MERGED``
+        before treating the merge as done (merge queues / auto-merge may
+        leave the PR open). No branch is deleted here (#283).
+        """
+        self._run_gh(build_merge_argv(url, method, match_head_sha))
+
+    def delete_branch_ref(self, repository: str, branch: str, *, default_branch: str) -> None:
+        """Delete ``refs/heads/<branch>`` of ``repository`` on GitHub, and nothing else (#283).
+
+        The controller's one branch deletion, behind ``merge.delete_branch``:
+        ``DELETE repos/<owner>/<repo>/git/refs/heads/<branch>``, a REST call
+        that names its repository and its ref, so no local git runs and no
+        local branch or worktree is touched. ``default_branch`` is the
+        repository's default branch as the caller just read it from GitHub:
+        that branch (in any letter case), and an empty answer, are refused
+        before any process starts, so no caller reaches the default branch
+        through this method. Sent exactly once, outside the transient retry
+        (D4.3): an ambiguous outcome is reconciled by reading the ref back
+        (:meth:`get_branch_ref`), never by sending the deletion again.
+        """
+        what = f"deleting branch {branch!r} of {repository}"
+        path = f"repos/{_repository_path(repository)}/git/refs/heads/{_branch_path(branch, what)}"
+        if not default_branch or branch.lower() == default_branch.lower():
+            raise GitHubError(
+                f"{what}: refused, the repository's default branch is "
+                f"{default_branch or '(unknown)'!r}, and it is never deleted; nothing was sent"
+            )
+        self._run_gh_once(["api", "--method", "DELETE", path])
+
+    def disable_auto_merge(self, url: str) -> None:
+        """Disarm GitHub auto-merge on ``url`` (``gh pr merge --disable-auto``).
+
+        Used only to undo an auto-merge that a controller ``merge_pr`` call
+        left armed, so no unreviewed HEAD can merge later on its own.
+        """
+        self._run_gh(build_disable_auto_merge_argv(url))
+
+    def close_pr(self, url: str, comment: str) -> None:
+        """Close an obsolete PR without merging or deleting any branch.
+
+        ``gh pr close`` takes no precondition -- GitHub has no conditional
+        close -- so a caller that needs the close bound to a checkpoint must
+        complete the comparison *after* the write and undo it with
+        :meth:`reopen_pr` when the checkpoint no longer holds.
+
+        The comment posted here must NOT carry ownership proof: ``gh pr close
+        --comment`` posts the comment as a separate effect before the close
+        lands, so a receipt in it can predate the close and later be mistaken
+        for proof that this transaction closed the PR. Ownership is posted
+        afterwards with :meth:`comment_pr`, only after the close is observed.
+        """
+        ref = parse_pr_url(url)
+        self._run_gh(["pr", "close", ref.canonical, "--comment", comment])
+
+    def comment_pr(self, url: str, body: str) -> None:
+        """Post a follow-up comment on a PR (open or closed).
+
+        Used for the replan close receipt: posted only after the controller
+        observed its own close landing, so presence of the receipt proves the
+        close was this transaction's. Never posted by a resume that did not
+        perform the close.
+        """
+        ref = parse_pr_url(url)
+        self._run_gh(["pr", "comment", ref.canonical, "--body", body])
+
+    def reopen_pr(self, url: str, comment: str) -> None:
+        """Undo a controller close (``gh pr reopen``).
+
+        The compensating half of :meth:`close_pr`: the only supported caller
+        is a checkpointed close whose preconditions turned out to have moved
+        inside the write window. The branch is never deleted by ``close_pr``,
+        so the PR comes back with its commits and review history intact.
+        """
+        ref = parse_pr_url(url)
+        self._run_gh(["pr", "reopen", ref.canonical, "--comment", comment])
+
+    # -- comments -----------------------------------------------------------
+    def get_pr_comments(self, url: str) -> list[CommentInfo]:
+        """Every conversation comment of a PR, oldest first (:meth:`_comments`)."""
+        ref = parse_pr_url(url)
+        return self._comments(_PR_COMMENT_PAGE_QUERY, "pullRequest", ref)
+
+    def get_issue_comments(self, url: str) -> list[CommentInfo]:
+        """Every comment of an issue (an EPIC's progress comments), oldest first."""
+        ref = parse_issue_url(url)
+        return self._comments(_ISSUE_COMMENT_PAGE_QUERY, "issue", ref)
+
+    def _comments(self, query: str, parent: str, ref: GitHubRef) -> list[CommentInfo]:
+        """The complete comment listing of ``ref`` (ADR 0004 D4.5), or a GitHubError.
+
+        Every identity read of a comment marker decides "absent" on this
+        listing (a review comment, a progress comment, a replan close
+        receipt), so it is read by cursor to its end
+        (:meth:`_walk_connection`) and a listing that cannot be is an error,
+        never the comments it did read. A missing issue or PR is
+        GitHubNotFoundError, as GitHub's "Could not resolve" is classified.
+        A comment seen twice is kept once.
+        """
+        parent_url = ref.canonical
+        what = f"comments of {parent_url}"
+        owner, _, name = ref.repository.partition("/")
+
+        def comments(data: dict, page_what: str) -> dict:
+            repository = data.get("repository")
+            if not isinstance(repository, dict):
+                raise GitHubError(f"{page_what}: repository is not readable: {repository!r:.200}")
+            holder = repository.get(parent)
+            if not isinstance(holder, dict):
+                raise GitHubError(f"{page_what}: {parent} is not readable: {holder!r:.200}")
+            connection = holder.get("comments")
+            if not isinstance(connection, dict):
+                raise GitHubError(f"{page_what} is not a comment connection: {connection!r:.200}")
+            return connection
+
+        # Strings as `-f`, like the open-PR walk; the number as `-F`, which
+        # sends it as the integer the `Int!` variable needs.
+        variables = ["-f", f"owner={owner}", "-f", f"name={name}", "-F", f"number={ref.number}"]
+        found: list[CommentInfo] = []
+        seen: set[int] = set()
+        for node in self._walk_connection(query, variables, comments, what):
+            comment = _decode_comment(node, parent_url)
+            if comment.id in seen:
+                continue
+            seen.add(comment.id)
+            found.append(comment)
+        return found
+
+    def get_comment(self, comment_url: str) -> CommentInfo:
+        """Fetch one issue-style comment by its HTML URL (``#issuecomment-<id>``).
+
+        The comment is addressed by its id alone (GitHub's comments API has
+        no per-issue path), so the returned ``url`` and ``parent_url`` are
+        what GitHub says the comment is on, which need not be the parent the
+        requested URL named; the caller compares. A comment that no longer
+        exists is a :class:`GitHubNotFoundError` (conclusive).
+        """
+        ref: GitHubCommentRef = parse_comment_url(comment_url)
+        data = self._api_json(
+            ["api", f"repos/{ref.parent.owner}/{ref.parent.repo}/issues/comments/{ref.comment_id}"]
+        )
+        return _decode_rest_comment(data, ref)
+
+    def get_comment_exact(self, comment_url: str) -> CommentInfo:
+        """The comment as GitHub holds it, its body byte for byte (the exact read).
+
+        :meth:`get_pr_exact` for an issue-style comment. Unlike
+        :meth:`get_comment`, an answer for a comment on another parent than
+        the URL names is a conclusive GitHubError: the read-back compares a
+        comment it found on that parent.
+        """
+        ref: GitHubCommentRef = parse_comment_url(comment_url)
+        what = f"exact read of {ref.canonical}"
+        path = f"repos/{_repository_path(ref.parent.repository)}/issues/comments/{ref.comment_id}"
+        comment = _decode_rest_comment(self._exact_object(path, what), ref)
+        if not parse_comment_url(comment.url).same_target(ref):
+            raise GitHubError(f"{what}: GitHub answered with {comment.url}")
+        return comment
+
+
+__all__ = [
+    "EXACT_READ_ERROR_BYTES",
+    "EXACT_READ_MAX_BYTES",
+    "EXACT_READ_ROOT",
+    "MAX_BODY_CHARS",
+    "MAX_TITLE_CHARS",
+    "MERGE_METHODS",
+    "CheckInfo",
+    "CommentInfo",
+    "CreatedObject",
+    "GitHubClient",
+    "GitHubIssueRef",
+    "GitHubPullRequestRef",
+    "HttpsReply",
+    "HttpsRequest",
+    "IssueInfo",
+    "MergeQueueStatus",
+    "PRInfo",
+    "RepoInfo",
+    "build_disable_auto_merge_argv",
+    "build_edit_issue_body_argv",
+    "build_merge_argv",
+    "https_get",
+]