code-coordinator 0.5.46__py3-none-any.whl

coord/github_ops.py

@@ -0,0 +1,1954 @@
+"""GitHub operations via gh CLI."""
+
+from __future__ import annotations
+
+import json
+import re
+import socket
+import subprocess
+from datetime import datetime
+from typing import Any
+
+
+# ── Typed gh errors ─────────────────────────────────────────────────────────
+
+
+class GhError(RuntimeError):
+    """Base class for typed ``gh`` CLI errors.
+
+    Subclass of :class:`RuntimeError` so existing ``except RuntimeError``
+    call sites keep working without modification; catch a subclass specifically
+    to distinguish it from a generic ``gh`` failure.
+    """
+
+
+class GhNotFound(GhError):
+    """Raised when a GitHub resource (e.g. a label) does not exist in the repo.
+
+    Callers (e.g. ``serve_app`` HTTP handlers) that need to distinguish
+    "the resource doesn't exist" (a 4xx-class client error) from transient
+    backend failures (auth, network, rate-limit — which are 5xx) should
+    catch this specifically and return an appropriate HTTP status code.
+    """
+
+
+class GhTooOldForJsonChecks(GhError):
+    """Raised when the installed ``gh`` doesn't support ``gh pr checks --json``
+    *at all* (#1564 Addendum 2), as opposed to supporting ``--json`` but
+    rejecting one of the requested field names (a plain :class:`RuntimeError`
+    from :func:`get_pr_checks`, e.g. the original ``conclusion`` bug).
+
+    The fleet that surfaced this issue runs the merge gate across hosts with
+    wildly different ``gh`` versions — and because ``coord merge`` re-invokes
+    itself on the daemon host (``COORD_MERGE_ON_DAEMON``, see ``serve_app.py``),
+    it is the *daemon's* ``gh`` that decides every production merge, not the
+    thin client's. A daemon stuck on a too-old ``gh`` must fail with a message
+    that names the problem and the fix, not the same undiagnosable
+    "could not read CI status" text used for auth/network flakes — see
+    :func:`coord.ci_github.GitHubCi._fetch`, which catches this subclass
+    ahead of the generic ``RuntimeError`` branch for exactly that reason.
+    """
+
+
+# Keywords indicating a transient/infra failure that should never trigger
+# label auto-creation.  Checked against the full lowercase error string.
+_TRANSIENT_ERROR_KEYWORDS: tuple[str, ...] = (
+    "http 401",
+    "http 403",
+    "http 429",
+    "authentication required",
+    "bad credentials",
+    "credentials not found",
+    "gh auth login",
+    "api rate limit",
+    "rate limit exceeded",
+    "secondary rate limit",
+    "timed out",
+    "connection refused",
+    "connection reset",
+    "connection error",
+    "could not resolve host",
+    "no such host",
+    "dial tcp",
+)
+
+
+def _is_transient_error(exc: Exception) -> bool:
+    """True when the ``gh`` error suggests an auth, rate-limit, or network failure.
+
+    These failures should never trigger label auto-creation or other
+    retry-with-side-effects logic — the root cause is infra, not a missing
+    resource.
+    """
+    msg = str(exc).lower()
+    return any(kw in msg for kw in _TRANSIENT_ERROR_KEYWORDS)
+
+
+def _is_label_not_found(exc: Exception) -> bool:
+    """True when ``gh`` reported that a label does not exist in the repository.
+
+    Returns ``False`` for transient errors (:func:`_is_transient_error`) so
+    callers never attempt auto-creation on auth/network/rate-limit failures.
+    """
+    if _is_transient_error(exc):
+        return False
+    msg = str(exc).lower()
+    # "could not resolve to a label" — the GraphQL error gh surfaces
+    # "label 'foo' not found" — the REST error in some gh versions
+    return "could not resolve to a label" in msg or (
+        "label" in msg and "not found" in msg
+    )
+
+
+def _gh(*args: str) -> str:
+    """Run ``gh`` with *args* and return its stdout, or raise :class:`GhError`.
+
+    #1483: this is the single seam every ``_gh``-backed helper in this module
+    funnels through, so it is also the single place that must absorb the
+    ways ``gh`` can fail to even run — not just a non-zero exit.
+    ``subprocess.run`` raises ``FileNotFoundError`` when the ``gh`` binary
+    isn't on PATH (the elitebook incident that prompted #1483: a worker's
+    systemd PATH didn't include the linuxbrew-installed ``gh``) and
+    ``subprocess.TimeoutExpired`` when it hangs past the 30s budget; both are
+    caught here and re-raised as :class:`GhError` (a ``RuntimeError``
+    subclass) so every existing ``except RuntimeError`` call site — and any
+    future one — gets the same fail-safe behavior the pre-#1483 direct
+    ``shutil.which("gh")`` + ``subprocess.run(..., check=False)`` call sites
+    had, for free, without each caller having to remember to guard for it.
+    """
+    try:
+        result = subprocess.run(
+            ["gh", *args],
+            capture_output=True, text=True, timeout=30,
+        )
+    except FileNotFoundError as exc:
+        raise GhError(f"gh {' '.join(args)} failed: gh not found: {exc}") from exc
+    except subprocess.TimeoutExpired as exc:
+        raise GhError(f"gh {' '.join(args)} failed: timed out: {exc}") from exc
+    except OSError as exc:
+        raise GhError(f"gh {' '.join(args)} failed: {exc}") from exc
+    if result.returncode != 0:
+        raise RuntimeError(f"gh {' '.join(args)} failed: {result.stderr.strip()}")
+    return result.stdout.strip()
+
+
+def _json_loads_or(raw: str | None, default: Any = None) -> Any:
+    """Decode *raw* as JSON, or return *default* on empty/malformed input.
+
+    #1353: ``_gh`` above treats a ``gh`` invocation that exits 0 with empty
+    stdout as a success — indistinguishable, from ``_gh``'s point of view,
+    from a real empty payload. Roughly half of this module's call sites used
+    to hand ``_gh``'s output straight to a bare ``json.loads``, so that empty
+    string decoded to exactly ``json.JSONDecodeError: Expecting value: line 1
+    column 1 (char 0)`` — a one-line, unattributable crash that took down an
+    entire ``coord merge`` drain in the incident that prompted this (see
+    issue #1353). This is the one guarded decode every such call site now
+    routes through, so "gh returned nothing useful" degrades to a documented
+    *default* value at every site uniformly, rather than at only the two
+    sites (``get_pr_commit_messages``, ``pr_is_merged``) that happened to
+    hand-roll their own guard beforehand.
+
+    Does **not** change ``_gh``'s own failure contract: a non-zero ``gh``
+    exit still raises ``RuntimeError``/``GhError`` same as always — this only
+    covers the exit-0-but-stdout-is-garbage case that used to reach a bare
+    ``json.loads``.
+    """
+    if raw is None or not raw.strip():
+        return default
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return default
+
+
+def _gh_json(*args: str, default: Any = None) -> Any:
+    """Run ``gh`` with *args* and JSON-decode its stdout, failing open.
+
+    Composes :func:`_gh` (still raises on a non-zero ``gh`` exit / missing
+    binary / timeout) with :func:`_json_loads_or` (fails open to *default* on
+    empty/malformed stdout from an otherwise-successful invocation). See
+    :func:`_json_loads_or` for why this exists.
+    """
+    return _json_loads_or(_gh(*args), default)
+
+
+def get_open_issues(repo: str) -> list[dict]:
+    # #658: raised from 100 → 500 so repos with many open issues don't silently
+    # skip old issue numbers during coord sync.  GitHub paginates the REST list
+    # endpoint at 100 items internally, so this costs ~5 API calls for a large
+    # repo — acceptable for a background sync.
+    return _gh_json(
+        "issue", "list", "--repo", repo, "--state", "open",
+        "--json", "number,title,labels,milestone,body,assignees",
+        "--limit", "500",
+        default=[],
+    )
+
+
+def get_closed_epics(repo: str, *, label: str = "epic") -> list[dict]:
+    """Return closed issues in *repo* carrying *label* (default ``"epic"``).
+
+    Used by ``coord plans`` (#974) so a milestone's tracking epic is still
+    found once it has been closed while the milestone itself stays open
+    (e.g. all work-order nodes finished and someone tidied up the epic
+    before remembering to close the milestone) — see
+    :func:`coord.plans.find_tracking_issue`. A small, label-filtered,
+    closed-only lookup rather than a full ``--state all`` issue fetch, since
+    only closed *epics* are of interest here.
+    """
+    return _gh_json(
+        "issue", "list", "--repo", repo, "--state", "closed", "--label", label,
+        "--json", "number,title,labels,milestone,body,assignees",
+        "--limit", "500",
+        default=[],
+    )
+
+
+def get_issue(repo: str, issue_number: int) -> dict:
+    """Fetch a single issue by number.
+
+    Returns ``{number, title, body, state, milestone, labels, ...}``.
+    ``milestone`` is ``None`` when the issue has none, else ``{"number":
+    ..., "title": ...}`` — used by ``coord milestone order`` (#768) to
+    resolve a tracking issue's milestone and validate node membership
+    without a second call. ``labels`` is a list of ``{"name": ..., ...}``
+    dicts — #1138's ``enforce_oracle_readiness`` reads issue labels (e.g.
+    ``oracle:exempt``) off this same call, so it must be requested here
+    too, not just on the list endpoints (``get_open_issues``,
+    ``get_closed_epics``).
+    """
+    return _gh_json(
+        "issue", "view", str(issue_number), "--repo", repo,
+        "--json", "number,title,body,state,milestone,labels",
+        default={},
+    )
+
+
+# ── Sub-issues (#1195) ───────────────────────────────────────────────────────
+#
+# The REST sub-issues API is live on GitHub today but used nowhere in this
+# repo before #1195 — every epic->child relation so far is the `## Work
+# order` / `## Sub-issues` markdown checklist `coord.milestone_order` parses.
+# These wrap the raw endpoints; `coord.parentage_github.GitHubParentage` is
+# the adapter that turns them into the backend-agnostic `coord.parentage`
+# seam shape (`Child`/`ParentRef`).
+#
+# Gotcha verified while filing #1195: the write endpoints (POST/DELETE) take
+# the child's internal database `id`, NOT its issue `number` — resolve via
+# `get_issue`'s `--jq .id` before writing (see `_resolve_issue_id`).
+
+
+def get_sub_issues(repo: str, issue_number: int) -> list[dict]:
+    """The live sub-issues of *issue_number* (``GET .../sub_issues``).
+
+    Returns ``[]`` for an issue with no sub-issues (confirmed live: this is
+    the API's normal response, not a 404/410 — see #1195's filing notes).
+    Each item is a full issue object; callers only need ``number``/``state``.
+    """
+    return _gh_json("api", f"repos/{repo}/issues/{issue_number}/sub_issues", default=[])
+
+
+def get_issue_parent(repo: str, issue_number: int) -> dict | None:
+    """The parent of *issue_number*, or ``None`` when it has none.
+
+    Reads the ``parent`` field GitHub already includes on ``GET
+    /issues/{n}`` (confirmed live while filing #1195 — no preview header
+    needed). ``None`` covers both "field absent" and the documented
+    ``parent: null`` shape.
+    """
+    raw = _gh("api", f"repos/{repo}/issues/{issue_number}", "--jq", ".parent")
+    stripped = raw.strip()
+    if not stripped or stripped == "null":
+        return None
+    return _json_loads_or(stripped, default=None)
+
+
+def _resolve_issue_id(repo: str, issue_number: int) -> int:
+    """Issue `number` -> internal database `id` (#1195's write-path gotcha:
+    the sub-issues POST/DELETE endpoints want the latter, not the former)."""
+    raw = _gh("api", f"repos/{repo}/issues/{issue_number}", "--jq", ".id")
+    return int(raw.strip())
+
+
+def add_sub_issue(repo: str, parent_number: int, child_number: int) -> None:
+    """Make *child_number* a sub-issue of *parent_number* (``POST
+    .../sub_issues``). Resolves *child_number* to its database id first —
+    the endpoint wants ``sub_issue_id`` (a database id), not the issue
+    number, and 422s if the body doesn't shape up."""
+    child_id = _resolve_issue_id(repo, child_number)
+    _gh(
+        "api", f"repos/{repo}/issues/{parent_number}/sub_issues",
+        "-X", "POST",
+        "-F", f"sub_issue_id={child_id}",
+    )
+
+
+def remove_sub_issue(repo: str, parent_number: int, child_number: int) -> None:
+    """Detach *child_number* from *parent_number* (``DELETE
+    .../sub_issue`` — singular, unlike the GET/POST plural; a real GitHub
+    API asymmetry, not a typo here)."""
+    child_id = _resolve_issue_id(repo, child_number)
+    _gh(
+        "api", f"repos/{repo}/issues/{parent_number}/sub_issue",
+        "-X", "DELETE",
+        "-F", f"sub_issue_id={child_id}",
+    )
+
+
+def edit_issue(
+    repo: str,
+    issue_number: int,
+    *,
+    title: str | None = None,
+    body: str | None = None,
+) -> None:
+    """Edit an issue's title and/or body. The GitHub backend of the
+    issue-tracker seam (`state.edit_issue_content`) — GitLab / bare-DB adapters
+    slot in alongside this later. The body is piped via stdin (`--body-file -`)
+    to avoid arg-length and shell-quoting issues on long markdown bodies."""
+    if title is None and body is None:
+        return
+    args = ["issue", "edit", str(issue_number), "--repo", repo]
+    if title is not None:
+        args += ["--title", title]
+    if body is not None:
+        args += ["--body-file", "-"]
+    result = subprocess.run(
+        ["gh", *args],
+        input=body if body is not None else None,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(
+            f"gh issue edit #{issue_number} failed: {result.stderr.strip()}"
+        )
+
+
+def create_milestone(
+    repo: str,
+    title: str,
+    *,
+    description: str | None = None,
+    due_on: str | None = None,
+) -> dict:
+    """Create a GitHub milestone via ``gh api POST .../milestones`` (#645 seam).
+
+    The GitHub backend of the milestone-tracker seam
+    (``coord.state.write_milestone``) — GitLab / bare-DB adapters slot in
+    alongside this later, same as ``edit_issue``. ``due_on`` is an ISO 8601
+    timestamp (e.g. ``"2026-08-01T00:00:00Z"``) per the GitHub API; this
+    layer does not validate the format, it just forwards it. Returns the
+    created milestone's JSON (``number``, ``title``, ``description``,
+    ``due_on``, ``html_url``, ...).
+    """
+    args = ["api", f"repos/{repo}/milestones", "-f", f"title={title}"]
+    if description is not None:
+        args += ["-f", f"description={description}"]
+    if due_on is not None:
+        args += ["-f", f"due_on={due_on}"]
+    return _json_loads_or(_gh(*args), default={})
+
+
+def edit_milestone(
+    repo: str,
+    number: int,
+    *,
+    title: str | None = None,
+    description: str | None = None,
+    due_on: str | None = None,
+) -> dict:
+    """Edit a GitHub milestone's title/description/due date via
+    ``gh api -X PATCH .../milestones/{number}`` (#645 seam, mirrors
+    ``edit_issue``). A no-op (all three fields ``None``) returns ``{}``
+    without shelling out. Returns the updated milestone's JSON."""
+    if title is None and description is None and due_on is None:
+        return {}
+    args = ["api", "-X", "PATCH", f"repos/{repo}/milestones/{number}"]
+    if title is not None:
+        args += ["-f", f"title={title}"]
+    if description is not None:
+        args += ["-f", f"description={description}"]
+    if due_on is not None:
+        args += ["-f", f"due_on={due_on}"]
+    return _json_loads_or(_gh(*args), default={})
+
+
+class IssueHasOpenChildrenError(RuntimeError):
+    """Raised by :func:`close_issue` when *issue_number* has open children and
+    ``force`` was not passed (#1196).
+
+    The close-invariant chokepoint: every deterministic close path in this
+    codebase (``merge_queue``, ``state._close_issue_local``,
+    ``commands/issues``) funnels through :func:`close_issue`, so guarding
+    here is the one place that stops an epic reading as "done" while its
+    sub-issues are still open — see claude-coordinator#1041, the incident
+    that prompted this. A subclass of ``RuntimeError`` so existing
+    ``except RuntimeError`` / ``except Exception`` call sites keep working
+    without modification; catch this specifically to distinguish "refused,
+    has open children" from any other close failure.
+    """
+
+
+def get_issues_live_state(repo: str, numbers: list[int]) -> dict[int, str]:
+    """Batch-fetch the *live* open/closed state of each issue in *numbers*.
+
+    One GraphQL request (one aliased ``issue(number: N)`` field per number)
+    rather than N ``gh issue view`` round-trips — see #1354: a close-guard
+    that fans out one lookup per child turns closing an epic into N API
+    calls. Returns ``{number: "open" | "closed"}``; a number that GitHub
+    doesn't resolve (deleted, wrong repo) is simply absent from the result.
+
+    Returns ``{}`` on any failure — a bad *repo* string, a ``gh`` error, or
+    an unparseable response — so callers can treat "no live data" uniformly
+    and fall back to their offline signal (see :func:`get_open_children`),
+    matching the deliberate fail-open contract on the parent lookup.
+    """
+    if not numbers:
+        return {}
+    try:
+        owner, name = repo.split("/", 1)
+    except ValueError:
+        return {}
+    unique = sorted(set(numbers))
+    fields = "\n".join(
+        f"  n{n}: issue(number: {n}) {{ number state }}" for n in unique
+    )
+    query = (
+        f"query {{ repository(owner: {json.dumps(owner)}, name: {json.dumps(name)}) {{\n"
+        f"{fields}\n"
+        f"}} }}"
+    )
+    try:
+        data = _gh_json("api", "graphql", "-f", f"query={query}", default={})
+    except RuntimeError:
+        return {}
+    data_field = data.get("data") if isinstance(data, dict) else None
+    repo_data = data_field.get("repository") if isinstance(data_field, dict) else None
+    if not isinstance(repo_data, dict):
+        return {}
+    result: dict[int, str] = {}
+    for value in repo_data.values():
+        if not isinstance(value, dict):
+            continue
+        num, state = value.get("number"), value.get("state")
+        if num is None or state is None:
+            continue
+        result[int(num)] = str(state).lower()
+    return result
+
+
+def get_open_children(repo: str, issue_number: int) -> list[dict]:
+    """Open children of *issue_number*, per the #1195 parentage seam (#1196).
+
+    Uses :class:`coord.parentage.MarkdownParentage` over the issue's own
+    body (fetched via :func:`get_issue`) to discover *which* issues are
+    children — the ``## Sub-issues`` checklist convention (#1008) is the
+    primary parentage source; with ``fallback_to_work_order=True`` this also
+    falls back to a ``## Work order`` block (#1221) so epics seeded before
+    #1008 — which have only a Work order block, not a Sub-issues checklist —
+    still register their children instead of silently reading as childless.
+
+    Each discovered child's reported state then comes from a **live**
+    lookup (:func:`get_issues_live_state`, one batched GraphQL call for all
+    children at once) rather than the checklist's own ``- [x]``/``- [ ]``
+    box (#1354: the box is a proxy that drifts — a closed child's box is
+    often never ticked, and a ticked box can just as easily sit over a
+    child that was later reopened). The checkbox is used only as the
+    per-child fallback when the live lookup doesn't cover that number
+    (batch call failed entirely, or GitHub didn't resolve that number) —
+    preserving the pre-#1354 offline behavior for exactly the cases where a
+    live answer isn't available, rather than treating a lookup failure as
+    grounds to refuse or to silently allow the close.
+
+    The live GitHub sub-issues REST API (:class:`coord.parentage_github.
+    GitHubParentage`) is wired but not yet backfilled onto existing epics
+    (EP-2, unbuilt), so using it *instead of* the markdown checklist here to
+    discover children would silently miss every real epic and defeat the
+    guard — only the per-child *state* is live, not the parent->child edges
+    themselves.
+
+    Returns ``[{"number": int, "state": "open"}, ...]``. **Fails open**
+    (returns ``[]``) both when the issue lookup itself errors (a transient
+    ``gh`` failure must not permanently wedge every close in the system —
+    :func:`close_issue` is the enforcement point, not this lookup) and when
+    the body's ``## Sub-issues`` or ``## Work order`` block fails to parse
+    (a malformed checklist on *this* issue must not block closing some
+    *other*, well-formed one — the same per-issue fail-isolation #1195
+    already applies to the ``/board`` children display).
+    """
+    try:
+        issue = get_issue(repo, issue_number)
+    except RuntimeError:
+        return []
+    from coord.parentage import MarkdownParentage  # noqa: PLC0415
+
+    body = issue.get("body") or ""
+    try:
+        children = MarkdownParentage().children(
+            repo, issue_number, body=body, fallback_to_work_order=True,
+        )
+    except Exception:  # noqa: BLE001 — malformed checklist: fail open, don't wedge close
+        return []
+    if not children:
+        return []
+    live_states = get_issues_live_state(repo, [c.number for c in children])
+    return [
+        {"number": c.number, "state": live_states.get(c.number, c.state)}
+        for c in children
+        if live_states.get(c.number, c.state) == "open"
+    ]
+
+
+def has_open_children(repo: str, issue_number: int) -> bool:
+    """True when *issue_number* has at least one open child (#1196)."""
+    return bool(get_open_children(repo, issue_number))
+
+
+def is_epic_issue(repo: str, issue_number: int) -> bool:
+    """True when *issue_number* carries the tracking/epic label (#1318).
+
+    Same label :data:`coord.milestone_order.TRACKING_ISSUE_LABEL` that
+    ``dispatch.enforce_epic_dispatch_guard`` (#1314) and
+    ``plan_followup.pr()`` (#1077/#1314) already check at dispatch/PR-create
+    time. This is the merge-time counterpart used by the pre-merge
+    epic-closing-keyword guard: a closing keyword anywhere in a PR body or
+    commit message that targets an epic must never be allowed to auto-close
+    it on merge.
+
+    Fail-open: any ``gh`` error returns ``False`` — a transient read failure
+    must not itself block a merge; the caller still has its other gates.
+    """
+    from coord.milestone_order import TRACKING_ISSUE_LABEL  # noqa: PLC0415
+
+    try:
+        issue_data = get_issue(repo, issue_number)
+    except RuntimeError:
+        return False
+    labels = {lbl.get("name", "") for lbl in (issue_data.get("labels") or [])}
+    return TRACKING_ISSUE_LABEL in labels
+
+
+def close_issue(
+    repo: str, issue_number: int, *, comment: str | None = None, force: bool = False,
+) -> None:
+    """Close a GitHub issue, optionally posting *comment* first.
+
+    The deterministic counterpart to a ``Closes #N`` keyword in a PR body:
+    ``coord merge`` calls this after a successful merge so an issue is never
+    stranded open when a worker-created PR forgot the keyword (and
+    conventional-commit ``fix(#N):`` subjects are *not* GitHub closing
+    keywords).  Idempotent — closing an already-closed issue is a no-op.
+    Raises RuntimeError on any other ``gh`` failure.  Part of the
+    issue-tracker seam (GitHub backend); GitLab / bare-DB adapters slot in
+    alongside this later (#806).
+
+    #1196: the close-invariant chokepoint. Refuses (raises
+    :class:`IssueHasOpenChildrenError`) when *issue_number* has open
+    children unless *force* is ``True`` — an epic must not read as "done"
+    while its sub-issues are still open/unstarted. Every deterministic
+    close path in the codebase funnels through here, so this single guard
+    covers all of them.
+    """
+    if not force:
+        open_children = get_open_children(repo, issue_number)
+        if open_children:
+            numbers = ", ".join(f"#{c['number']}" for c in open_children)
+            raise IssueHasOpenChildrenError(
+                f"refusing to close {repo}#{issue_number}: open children "
+                f"{numbers} — pass force=True (CLI: --force) to override"
+            )
+    if comment:
+        post_issue_comment(repo, issue_number, comment)
+    result = subprocess.run(
+        ["gh", "issue", "close", str(issue_number), "--repo", repo],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0 and "already closed" not in result.stderr.lower():
+        raise RuntimeError(
+            f"gh issue close #{issue_number} failed: {result.stderr.strip()}"
+        )
+
+
+def reopen_issue(
+    repo: str, issue_number: int, *, comment: str | None = None,
+) -> None:
+    """Reopen a GitHub issue, optionally posting *comment* first.
+
+    Idempotent — reopening an already-open issue is a no-op. Raises
+    RuntimeError on any other ``gh`` failure. Part of the issue-tracker seam
+    (GitHub backend); GitLab / bare-DB adapters slot in alongside this later
+    (#806).
+
+    Mirror of :func:`close_issue` for the complement operation (issue #1078).
+    """
+    if comment:
+        post_issue_comment(repo, issue_number, comment)
+    result = subprocess.run(
+        ["gh", "issue", "reopen", str(issue_number), "--repo", repo],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0 and "already open" not in result.stderr.lower():
+        raise RuntimeError(
+            f"gh issue reopen #{issue_number} failed: {result.stderr.strip()}"
+        )
+
+
+def check_pr_mergeable(repo: str, number: int) -> bool | None:
+    """Return GitHub's current mergeability verdict for PR *number* (#1477).
+
+    Used by the merge queue's stale-``CONFLICT`` reconciliation
+    (:func:`coord.merge_queue.reconcile_conflict_entries`) to re-test whether
+    a parked entry's branch has since become clean — a conflict-fix worker
+    landed, or a human pushed a fix by hand — rather than trusting the
+    ``gh pr merge`` failure message cached from whenever the queue last
+    attempted it.
+
+    Returns ``True`` when GitHub reports ``MERGEABLE``, ``False`` when it
+    reports ``CONFLICTING``, and ``None`` for anything else — including
+    ``UNKNOWN`` (GitHub computes mergeability asynchronously; a very recent
+    push can read back unresolved for a few seconds) and any ``gh``
+    error/timeout. Callers must treat ``None`` the same as ``False`` — an
+    inconclusive read is never a green light to unpark an entry.
+    """
+    try:
+        value = _gh_json(
+            "pr", "view", str(number), "--repo", repo, "--json", "mergeable",
+            default={},
+        ).get("mergeable")
+    except Exception:  # noqa: BLE001 — fail-safe: unknown mergeability blocks nothing
+        return None
+    if value == "MERGEABLE":
+        return True
+    if value == "CONFLICTING":
+        return False
+    return None
+
+
+def branch_has_merge_commit(repo: str, number: int) -> bool | None:
+    """True when any commit on PR *number* has more than one parent (#1467).
+
+    GitHub refuses to rebase-merge (``gh pr merge --rebase``) any branch
+    containing a merge commit — a *linearity* requirement distinct from a
+    content conflict. :func:`check_pr_mergeable`'s ``mergeable`` field can't
+    detect this: GitHub reports a branch with a merge commit as
+    ``MERGEABLE`` right up until the rebase-merge attempt itself fails with
+    "This branch can't be rebased". This probe answers the question
+    ``check_pr_mergeable`` can't, so :mod:`coord.merge_queue` can fall back
+    from ``--rebase`` to ``--squash`` before ever hitting that refusal.
+
+    Reads ``repos/{repo}/pulls/{number}/commits`` — each commit's
+    ``parents`` array has length > 1 only for a merge commit — rather than a
+    local ``git rev-list --merges``, because ``coord merge`` runs on the
+    daemon host, which has no guaranteed checkout of an arbitrary configured
+    repo. Pages up to 100 commits, comfortably above any real worker branch.
+
+    Returns ``True``/``False`` when determined, and ``None`` on any ``gh``
+    failure or malformed response — an inconclusive read. Mirrors
+    :func:`check_pr_mergeable`'s fail-closed contract: callers must treat
+    ``None`` as "don't know" and never let it drive a behaviour change (here:
+    never silently switch merge method, or unpark a queue entry, on an
+    inconclusive read).
+    """
+    try:
+        raw = _gh("api", f"repos/{repo}/pulls/{number}/commits?per_page=100")
+        commits = json.loads(raw)
+    except Exception:  # noqa: BLE001 — fail-safe: unknown parents blocks nothing
+        return None
+    if not isinstance(commits, list):
+        return None
+    try:
+        return any(len(c.get("parents") or []) > 1 for c in commits)
+    except (AttributeError, TypeError):
+        return None
+
+
+def get_pr_body(repo: str, number: int) -> str:
+    """Return PR *number*'s current body text (empty string if unset)."""
+    return _gh_json(
+        "pr", "view", str(number), "--repo", repo, "--json", "body", default={},
+    ).get("body") or ""
+
+
+def edit_pr_body(repo: str, number: int, body: str) -> None:
+    """Overwrite PR *number*'s body text via ``gh pr edit --body``."""
+    _gh("pr", "edit", str(number), "--repo", repo, "--body", body)
+
+
+def get_pr_commit_messages(repo: str, number: int) -> list[str]:
+    """Return the full commit message (headline + body) of every commit on
+    PR *number*, in commit order (#1318).
+
+    GitHub's closing-keyword scanner reads commit messages verbatim once
+    they land on the base branch — for ``--rebase``/``--merge`` methods
+    that's every original commit, unchanged, so a keyword buried in
+    commit-message prose (e.g. explaining a bug fixed elsewhere, in a
+    quote) can auto-close an issue on merge exactly like a PR-body keyword
+    (#1196) does, and no PR-body edit can neutralize it. Best-effort:
+    returns ``[]`` on any ``gh`` failure or malformed response, same
+    fail-open posture as :func:`get_pr_body`.
+    """
+    try:
+        raw = _gh("pr", "view", str(number), "--repo", repo, "--json", "commits")
+    except RuntimeError:
+        return []
+    data = _json_loads_or(raw, default={})
+    commits = (data.get("commits") if isinstance(data, dict) else None) or []
+    messages: list[str] = []
+    for c in commits:
+        headline = (c.get("messageHeadline") or "").strip()
+        body = (c.get("messageBody") or "").strip()
+        messages.append(f"{headline}\n\n{body}" if body else headline)
+    return messages
+
+
+def issue_is_closed(repo: str, issue_number: int) -> bool:
+    """True when issue ``issue_number`` is closed on GitHub.
+
+    Best-effort and **fail-open**: any ``gh`` error returns ``False`` so a
+    transient GitHub/CLI failure never silently blocks a legitimate dispatch.
+    """
+    try:
+        return get_issue(repo, issue_number).get("state", "").upper() == "CLOSED"
+    except (RuntimeError, json.JSONDecodeError):
+        return False
+
+
+def pr_is_merged(repo: str, branch: str) -> bool:
+    """True when ``branch``'s *current* tip is a commit that actually merged on ``repo``.
+
+    Uses ``gh pr list --head <branch> --state all`` rather than ``pr view`` so
+    the result survives **branch deletion after merge** and the quadraui case
+    where a PR merged into ``develop`` leaves its linked issue OPEN (so
+    :func:`issue_is_closed` would miss it).  Best-effort and **fail-open**:
+    returns ``False`` when there is no PR, the PR is still open, or ``gh``
+    errors — never blocks a legitimate dispatch on a transient failure.
+
+    #1150: branch reuse across merge cycles is a designed pattern
+    (``--fix-of``/``--rework-of`` continue on the same branch; ``--force`` can
+    re-target a branch name with prior history) — so "a PR with this head ref
+    name merged *at some point*" is not proof that the branch's *current*
+    commits are merged. To distinguish those cases, once a merged PR is found
+    we resolve the branch's current tip via :func:`get_branch_sha` (the same
+    GitHub-API SHA lookup #821 uses for stale-review detection) and require it
+    to match the merged PR's ``headRefOid`` — the exact commit that landed.
+
+    When the tip can't be resolved via ``get_branch_sha`` (it fails closed to
+    ``None`` on *any* error, transient or not — see its docstring), we do
+    **not** blindly trust the historical merge, because that would reintroduce
+    this same issue's bug class under a transient-failure trigger: a rate
+    limit or network blip at the wrong moment would read as "already merged"
+    and callers (``reconcile``'s merge sweep, ``prune_stale_queue_entries``)
+    would permanently mark live, unmerged work as done or delete its queue
+    entry. Trusting history is only actually safe in the one case where it's
+    *structurally* impossible for new commits to exist: the branch was
+    positively confirmed deleted (a 404, via :func:`branch_exists_on_remote`,
+    which distinguishes "GitHub said not found" from any other failure).
+    Every other unresolved case — auth hiccup, timeout, rate limit — fails
+    open toward ``False`` ("not yet merged"), matching this function's and
+    ``prune_stale_queue_entries``'s documented fail-open convention.
+    """
+    if not branch:
+        return False
+    try:
+        raw = _gh(
+            "pr", "list", "--repo", repo, "--head", branch,
+            "--state", "all", "--json", "number,state,mergedAt,headRefOid",
+            "--limit", "10",
+        )
+    except RuntimeError:
+        return False
+    prs = _json_loads_or(raw, default=[])
+    if not isinstance(prs, list):
+        return False
+    merged = [
+        p for p in prs
+        if p.get("mergedAt") or p.get("state", "").upper() == "MERGED"
+    ]
+    if not merged:
+        return False
+
+    current_sha = get_branch_sha(repo, branch)
+    if current_sha is not None:
+        return any(p.get("headRefOid") == current_sha for p in merged)
+    # SHA lookup failed. Only trust the historical merge if we can positively
+    # confirm the branch is gone (a 404 means no further commits could have
+    # been pushed to it). Any other failure (transient network/auth/rate
+    # limit) fails open toward False — see docstring.
+    if not branch_exists_on_remote(repo, branch):
+        return True  # confirmed deleted — no new commits possible; trust history
+    return False
+
+
+def work_is_terminal(
+    repo_github: str,
+    issue_number: int | None,
+    branch: str | None,
+    *,
+    cache: dict | None = None,
+) -> bool:
+    """True when work is already done on GitHub: **issue closed OR PR merged**.
+
+    The single chokepoint guard (#522) consulted before any fix/review
+    dispatch, so already-merged/closed work can never re-enter the loop (the
+    root cause of the 2026-06-09 launch flood: #349 ×4, #194).
+
+    Best-effort and **fail-open**: any error resolves to ``False`` so a
+    transient GitHub/CLI failure never blocks a legitimate dispatch.
+
+    *cache* — optional ``dict`` shared across a single ``notify`` run, keyed by
+    ``(repo_github, issue_number, branch)``, so a burst of transitions for the
+    same merged issue costs **one** ``gh`` round-trip, not one per call.
+    """
+    if not repo_github:
+        return False
+
+    key = (repo_github, issue_number, branch)
+    if cache is not None and key in cache:
+        return cache[key]
+
+    terminal = False
+    try:
+        if issue_number and issue_is_closed(repo_github, issue_number):
+            terminal = True
+        elif branch and pr_is_merged(repo_github, branch):
+            terminal = True
+    except Exception:  # noqa: BLE001 — fail-open: never block a dispatch
+        terminal = False
+
+    if cache is not None:
+        cache[key] = terminal
+    return terminal
+
+
+# ── #873: durable issue_comments mirror — capture-at-write ──────────────────
+
+_COMMENT_ID_RE = re.compile(r"issuecomment-(\d+)")
+
+# Memoized per-process: the authenticated gh identity, used as a best-effort
+# `author` on capture-at-write rows. One extra `gh api user` call the first
+# time a comment is posted in this process; the backfill sync
+# (state.sync_issue_comments) overwrites it with the real per-comment author
+# regardless, so a stale/failed lookup here is harmless.
+_login_cache: dict[str, str | None] = {}
+
+
+def parse_comment_id(url: str) -> int | None:
+    """Extract the numeric REST comment id from a GitHub comment URL
+    (``...#issuecomment-<digits>``) — the format both ``gh issue comment``'s
+    stdout and ``gh issue view --json comments``'s ``url`` field use. Returns
+    ``None`` when *url* doesn't match (e.g. blank, or gh's output format
+    changes)."""
+    m = _COMMENT_ID_RE.search(url or "")
+    return int(m.group(1)) if m else None
+
+
+def _current_gh_login() -> str | None:
+    if "login" not in _login_cache:
+        try:
+            _login_cache["login"] = _gh("api", "user", "--jq", ".login") or None
+        except Exception:  # noqa: BLE001 — best-effort; capture still proceeds without it
+            _login_cache["login"] = None
+    return _login_cache["login"]
+
+
+def get_issue_comments(repo: str, issue_number: int) -> list[dict]:
+    """All comments on *issue_number*, oldest first (gh's default order).
+
+    Each dict carries at least ``id`` (a GraphQL node id — NOT the numeric
+    REST id; use :func:`parse_comment_id` on ``url`` for that), ``url``,
+    ``author`` (``{"login": ...}``), ``body``, ``createdAt``. Used by
+    ``state.sync_issue_comments`` (#873) to backfill the ``issue_comments``
+    mirror with human + out-of-band comments coord never wrote itself.
+    """
+    return _gh_json(
+        "issue", "view", str(issue_number), "--repo", repo, "--json", "comments",
+        default={},
+    ).get("comments", [])
+
+
+def post_issue_comment(repo: str, issue_number: int, body: str):
+    url = _gh("issue", "comment", str(issue_number), "--repo", repo, "--body", body)
+    _capture_comment_write(repo, issue_number, body, url)
+
+
+def _capture_comment_write(repo: str, issue_number: int, body: str, url: str) -> None:
+    """Best-effort mirror of a just-posted comment into the durable
+    ``issue_comments`` table (#873).
+
+    Capture-at-write: the coord-authored prose message bus (completion
+    summaries, review bodies, failure reports) becomes durable and
+    machine-independent the instant it posts, rather than depending on a
+    later reconciliation/recovery pass. Never raises — a mirror failure must
+    never undo (or even surface as an error against) a GitHub comment that
+    already landed.
+    """
+    try:
+        from coord import state  # noqa: PLC0415 — avoid a github_ops<->state import cycle
+
+        state.record_issue_comment_capture(
+            repo_name=repo,
+            issue_number=issue_number,
+            body=body,
+            gh_comment_id=parse_comment_id(url),
+            author=_current_gh_login(),
+        )
+    except Exception:  # noqa: BLE001 — fail-open, see docstring
+        pass
+
+
+def add_issue_labels(repo: str, issue_number: int, labels: list[str]) -> None:
+    """Add labels to an issue. Idempotent — `gh issue edit --add-label`
+    silently no-ops when the label is already present.  Raises RuntimeError
+    on `gh` failure; callers should wrap in try/except when labeling is
+    best-effort (e.g. post-dispatch auto-tagging)."""
+    if not labels:
+        return
+    args = ["issue", "edit", str(issue_number), "--repo", repo]
+    for lbl in labels:
+        args.extend(["--add-label", lbl])
+    _gh(*args)
+
+
+def create_label(
+    repo: str,
+    label: str,
+    *,
+    color: str | None = None,
+    description: str | None = None,
+    force: bool = True,
+) -> None:
+    """Create *label* in *repo* via ``gh label create``.
+
+    ``force=True`` (the default) makes this idempotent — ``gh`` overwrites
+    the color/description if the label already exists instead of erroring.
+    Raises ``RuntimeError`` (a plain non-zero ``gh`` exit) or its subclass
+    :class:`GhError` (``gh`` missing from PATH or timed out — see ``_gh``) on
+    failure; callers that treat label pre-creation as best-effort (e.g. a
+    concurrent-create race) should catch ``RuntimeError`` to cover both. Used
+    by ``coord set-test-mode`` (#1483) to ensure the ``test-mode:*`` labels
+    exist before ``change_issue_labels`` tries to add one.
+    """
+    args = ["label", "create", label, "--repo", repo]
+    if color:
+        args.extend(["--color", color])
+    if description:
+        args.extend(["--description", description])
+    if force:
+        args.append("--force")
+    _gh(*args)
+
+
+def remove_issue_label(repo: str, issue_number: int, label: str) -> None:
+    """Remove a label from an issue via ``gh issue edit --remove-label``.
+
+    Idempotent — ``gh`` silently no-ops if the label is not present.
+    Raises RuntimeError on ``gh`` failure.
+    """
+    _gh("issue", "edit", str(issue_number), "--repo", repo, "--remove-label", label)
+
+
+def change_issue_labels(
+    repo: str,
+    issue_number: int,
+    *,
+    add: set[str],
+    remove: set[str],
+) -> tuple[list[str], bool]:
+    """Atomically add and/or remove arbitrary labels on an issue (#802).
+
+    Fetches the current label set first, computes the minimal delta, and
+    runs a single ``gh issue edit`` call only when something actually
+    changes — tolerates already-present ``add`` labels and already-absent
+    ``remove`` labels (idempotent, matches ``_apply_label_change``'s
+    pre-#802 behavior).
+
+    Returns ``(new_labels, changed)`` where ``new_labels`` is the final
+    label list (sorted) and ``changed`` is ``True`` when any labels were
+    added or removed. Raises ``RuntimeError`` on ``gh`` failure.
+    """
+    view_data = _gh_json(
+        "issue", "view", str(issue_number), "--repo", repo, "--json", "labels",
+        default={},
+    )
+    current: set[str] = {
+        lbl.get("name", "")
+        for lbl in view_data.get("labels", [])
+    }
+
+    to_add = add - current
+    to_remove = remove & current
+    changed = bool(to_add or to_remove)
+
+    if changed:
+        args = ["issue", "edit", str(issue_number), "--repo", repo]
+        for lbl in sorted(to_add):
+            args.extend(["--add-label", lbl])
+        for lbl in sorted(to_remove):
+            args.extend(["--remove-label", lbl])
+        try:
+            _gh(*args)
+        except RuntimeError as exc:
+            if to_add and _is_label_not_found(exc):
+                # A label in ``to_add`` doesn't exist in the repo yet.
+                # Auto-create each label and retry the edit once.  Only
+                # triggered on the add path (``to_add`` is non-empty) and
+                # only for label-not-found errors — auth, network, and
+                # rate-limit failures are re-raised immediately without
+                # touching GitHub.  ``gh label create`` errors are swallowed
+                # so an "already exists" race on a concurrent create is
+                # handled gracefully.
+                for lbl in sorted(to_add):
+                    try:
+                        _gh("label", "create", lbl, "--repo", repo)
+                    except RuntimeError:
+                        pass  # idempotent: label may already exist
+                try:
+                    _gh(*args)
+                except RuntimeError as retry_exc:
+                    if _is_label_not_found(retry_exc):
+                        raise GhNotFound(str(retry_exc)) from retry_exc
+                    raise
+            else:
+                raise
+
+    new_labels = sorted((current - to_remove) | to_add)
+    return new_labels, changed
+
+
+_TEST_MODE_LABELS = ("test-mode:smoke", "test-mode:auto")
+
+
+def set_test_mode_label(
+    repo_github: str,
+    repo_name: str,
+    issue_number: int,
+    mode: str,
+) -> None:
+    """Persist the per-issue test-mode policy as a GitHub label.
+
+    Removes any existing ``test-mode:*`` label then adds ``test-mode:{mode}``.
+    Also updates the local issues cache so the TUI pipeline reflects the change
+    without waiting for the next ``coord sync``.
+
+    ``repo_github`` — ``owner/name`` slug for the ``gh`` CLI.
+    ``repo_name``   — coordinator-local repo name for the DB cache.
+    ``mode``        — ``"smoke"`` or ``"auto"``.
+    """
+    from coord import state as _state  # noqa: PLC0415
+
+    if mode not in ("smoke", "auto"):
+        raise ValueError(f"mode must be 'smoke' or 'auto', got {mode!r}")
+
+    # Step 1: remove any stale test-mode:* labels.
+    for old_label in _TEST_MODE_LABELS:
+        try:
+            remove_issue_label(repo_github, issue_number, old_label)
+        except RuntimeError:
+            pass  # already absent — not an error
+
+    # Step 2: add the new label (idempotent).
+    new_label = f"test-mode:{mode}"
+    add_issue_labels(repo_github, issue_number, [new_label])
+
+    # Step 3: refresh the local cache so the TUI sees the update.
+    try:
+        issue_data = get_issue(repo_github, issue_number)
+        current_labels = [lbl.get("name", "") for lbl in issue_data.get("labels", [])]
+        _state.update_issue_labels(repo_name, issue_number, current_labels)
+    except Exception:
+        pass  # cache update is best-effort
+
+
+def get_repo_file(repo: str, path: str, branch: str = "develop") -> str:
+    import base64
+    raw = _gh("api", f"repos/{repo}/contents/{path}?ref={branch}")
+    data = _json_loads_or(raw, default=None)
+    # #1353: an empty/malformed-but-exit-0 response used to bare-json.loads()
+    # into an unattributable JSONDecodeError (or, post-decode, a KeyError on
+    # "content"). Both callers of this function (_default_gate_a_file_exists,
+    # _default_fetch_repo_file) already catch RuntimeError to mean "file
+    # doesn't exist" — raise that instead, so a `gh` hiccup degrades to the
+    # same handled path as a real 404 rather than an uncaught crash.
+    if not isinstance(data, dict) or "content" not in data:
+        raise RuntimeError(
+            f"gh api repos/{repo}/contents/{path}?ref={branch}: "
+            "empty or malformed response"
+        )
+    return base64.b64decode(data["content"]).decode()
+
+
+def list_repo_dir(repo: str, path: str, branch: str = "develop") -> list[str]:
+    """Filenames (not full paths) directly under *path* on *branch*.
+
+    Same ``contents`` endpoint :func:`get_repo_file` uses, which returns a
+    JSON array (rather than a single file object) when *path* is a
+    directory. Raises like :func:`get_repo_file` (``RuntimeError`` via
+    ``_gh``) when *path* doesn't exist — callers that want a soft "not
+    found" should catch that, mirroring ``_default_gate_a_file_exists``.
+    """
+    raw = _gh("api", f"repos/{repo}/contents/{path}?ref={branch}")
+    data = _json_loads_or(raw, default=None)
+    if not isinstance(data, list):
+        return []
+    return [entry["name"] for entry in data if entry.get("type") == "file"]
+
+
+def check_branch_exists(repo: str, branch: str) -> bool:
+    try:
+        _gh("api", f"repos/{repo}/branches/{branch}")
+        return True
+    except RuntimeError:
+        return False
+
+
+def list_remote_branch_names(repo: str) -> set[str]:
+    """Return the set of branch names that currently exist on `repo` (owner/name).
+
+    One paginated ``gh api`` call.  Used by ``coord merge`` to skip re-enqueuing
+    done-work whose branch was already merged-and-deleted (the dominant
+    merge-queue clog source).  Returns an empty set on error so callers can
+    fail OPEN (treat "couldn't determine" as "don't skip").
+    """
+    try:
+        raw = _gh(
+            "api", "--paginate",
+            f"repos/{repo}/git/refs/heads",
+            "--jq", ".[].ref",
+        )
+    except RuntimeError:
+        return set()
+    prefix = "refs/heads/"
+    return {
+        line.strip()[len(prefix):]
+        for line in raw.splitlines()
+        if line.strip().startswith(prefix)
+    }
+
+
+def branch_exists_on_remote(repo: str, branch: str) -> bool:
+    """Return True if `branch` currently exists on `repo` (owner/name) at GitHub.
+
+    Uses a targeted ``gh api`` call rather than listing all branches.  Fails
+    OPEN (returns True) on any infrastructure problem — an unresponsive ``gh``,
+    a network glitch, or an authentication issue must never prevent a legitimate
+    dispatch.  Only returns False when we receive a clear "not found" signal
+    from GitHub (HTTP 4xx in the error output).
+
+    Called by ``dispatch_review`` and ``_dispatch_fix`` (#586) to avoid
+    routing a follow-on assignment to a machine that can't fetch the branch.
+    """
+    try:
+        _gh("api", f"repos/{repo}/git/refs/heads/{branch}")
+        return True
+    except RuntimeError as exc:
+        err = str(exc).lower()
+        # Only return False when GitHub explicitly told us the ref doesn't
+        # exist (HTTP 4xx response).  Any other failure (gh not installed,
+        # not authenticated, network timeout) is treated as "unknown" and we
+        # fail OPEN so the guard doesn't block legitimate dispatch.
+        if "http 4" in err or "could not resolve" in err or "not found" in err:
+            return False
+        return True
+
+
+def delete_remote_branch(repo: str, branch: str) -> bool:
+    """Delete a remote branch. Returns True on success, False on failure."""
+    try:
+        _gh("api", "-X", "DELETE", f"repos/{repo}/git/refs/heads/{branch}")
+        return True
+    except RuntimeError:
+        return False
+
+
+def create_remote_branch(repo: str, branch: str, sha: str) -> bool:
+    """Create a remote branch (a ``refs/heads/{branch}`` ref) pointing at
+    *sha*. Returns True on success, False on failure.
+
+    #934: used by ``coord.branch_model.ensure_feature_branch_exists`` to
+    create ``feature/ms-NN`` off ``develop`` on demand, idempotently (the
+    caller checks ``branch_exists_on_remote`` first).
+    """
+    try:
+        _gh(
+            "api", "-X", "POST", f"repos/{repo}/git/refs",
+            "-f", f"ref=refs/heads/{branch}",
+            "-f", f"sha={sha}",
+        )
+        return True
+    except RuntimeError:
+        return False
+
+
+def get_default_branch_head(repo: str, branch: str) -> str:
+    """Return the full commit SHA at the tip of `branch` on `repo` (owner/name)."""
+    raw = _gh("api", f"repos/{repo}/branches/{branch}")
+    data = _json_loads_or(raw, default=None)
+    # #1353: every caller of this already catches RuntimeError to mean "HEAD
+    # lookup failed" — raise that instead of letting an empty/malformed
+    # exit-0 response crash with an unattributable JSONDecodeError/KeyError.
+    if not isinstance(data, dict) or "commit" not in data:
+        raise RuntimeError(
+            f"gh api repos/{repo}/branches/{branch}: empty or malformed response"
+        )
+    return data["commit"]["sha"]
+
+
+def get_branch_sha(repo: str, branch: str) -> str | None:
+    """Return the current HEAD SHA for *branch* on *repo*, or ``None`` on failure.
+
+    Best-effort wrapper around the GitHub branches API.  Returns ``None`` when
+    GitHub is unavailable, ``gh`` is not authenticated, or the branch does not
+    exist — callers treat ``None`` as "SHA tracking unavailable" and skip the
+    commit-bound staleness check introduced in #821.
+    """
+    try:
+        raw = _gh("api", f"repos/{repo}/branches/{branch}")
+        data = _json_loads_or(raw, default={})
+        return data["commit"]["sha"]
+    except Exception:  # noqa: BLE001 — fail-safe: unknown SHA is not blocking
+        return None
+
+
+def get_branch_commit_timestamp(repo: str, branch: str) -> float | None:
+    """Return the unix timestamp of *branch*'s current HEAD commit on *repo*,
+    or ``None`` on failure (#1851).
+
+    The base-side half of :func:`coord.ci_store.checks_are_stale`'s
+    comparison: a green CI check's ``started_at`` predating this timestamp
+    means the check ran before the base's newest commit landed — GitHub only
+    re-runs ``pull_request`` checks on head ``synchronize``, never on base
+    movement, so that check never saw it.
+
+    Same endpoint as :func:`get_branch_sha` (``GET
+    repos/{repo}/branches/{branch}``) — reads the commit's ``committer.date``
+    (when it landed on the branch) rather than ``author.date`` (when it was
+    originally authored, which for a rebased/cherry-picked commit can predate
+    the merge by a wide margin and would understate how fresh the base
+    actually is). Best-effort like :func:`get_branch_sha`: returns ``None``
+    when GitHub is unavailable, ``gh`` is not authenticated, the branch
+    doesn't exist, or the response is missing the expected fields — callers
+    must treat ``None`` as "unknown" and fail closed (stale), never as "the
+    base never moved".
+    """
+    try:
+        raw = _gh("api", f"repos/{repo}/branches/{branch}")
+        data = _json_loads_or(raw, default={})
+        date = data["commit"]["commit"]["committer"]["date"]
+        return datetime.fromisoformat(str(date).replace("Z", "+00:00")).timestamp()
+    except Exception:  # noqa: BLE001 — fail-safe: unknown timestamp is stale, not blocking here
+        return None
+
+
+# ── PR operations (used by the merge queue) ──────────────────────────────
+
+def find_pr_for_branch(repo: str, branch: str) -> dict | None:
+    """Return the first open PR whose head ref matches `branch`, or None."""
+    items = _gh_json(
+        "pr", "list", "--repo", repo, "--state", "open",
+        "--head", branch,
+        "--json", "number,title,url,headRefName,baseRefName,additions,deletions,mergeable",
+        "--limit", "1",
+        default=[],
+    )
+    return items[0] if items else None
+
+
+def get_pr_state_for_branch(repo: str, branch: str) -> str | None:
+    """Return the current lifecycle state (``OPEN``/``MERGED``/``CLOSED``) of
+    the PR whose head is *branch*, or ``None`` when no such PR exists (or
+    ``gh`` fails).
+
+    Unlike :func:`find_pr_for_branch` (``pr list --state open`` — only ever
+    finds *open* PRs), this resolves the branch directly via ``gh pr view``,
+    which answers regardless of state. Used by
+    :meth:`coord.drive.GitMergeVerifier.verify_merged` (#1483) to confirm a
+    MERGED PR whose branch may since have been deleted from the remote.
+    """
+    try:
+        state = _gh("pr", "view", branch, "--repo", repo, "--json", "state", "-q", ".state")
+    except RuntimeError:
+        return None
+    return state or None
+
+
+def get_pr_head_ref(repo: str, number: int) -> str | None:
+    """Return PR *number*'s head branch name, or ``None`` on any ``gh``
+    failure (including "no such PR").
+
+    Used by ``coord test``'s branch-reconciliation fallback (#349, #1483) to
+    recover the PR's actual head ref when the DB's recorded branch name has
+    gone stale.
+    """
+    try:
+        head_ref = _gh(
+            "pr", "view", str(number), "--repo", repo,
+            "--json", "headRefName", "--jq", ".headRefName",
+        )
+    except RuntimeError:
+        return None
+    return head_ref or None
+
+
+# #1564: `gh pr checks --json` does NOT have a `conclusion` field — it never
+# has. Requesting it makes `gh` exit 1 with empty stdout, which used to make
+# every single merge look like an unreadable CI status (fail-closed, so it
+# blocked every merge rather than passing every one, but neither is correct).
+# `bucket` is gh's own pass/fail/pending/skipping/cancel rollup of `state`
+# (which is a per-check verdict like SUCCESS/FAILURE, not a lifecycle phase)
+# and is exactly what the merge gate wants. Pinned in a regression test
+# (tests/test_github_ops.py::TestPrChecksJsonFieldsAreValid) that shells out
+# to `gh pr checks --help` and asserts every field here is one `gh` advertises,
+# so the next `gh` schema change fails a test instead of silently breaking
+# the gate again.
+PR_CHECKS_JSON_FIELDS: tuple[str, ...] = (
+    "name", "state", "bucket", "link", "startedAt", "completedAt",
+)
+
+# #1564 Addendum 2: the fleet that surfaced this issue runs `gh` versions that
+# disagree about whether `gh pr checks` even *has* a `--json` flag —
+# dellserver's 2.45.0 (Ubuntu's apt package) does not: `gh pr checks --json
+# name,state,bucket` fails with `unknown flag: --json`, exit 1, empty stdout.
+# 2.86.0 (elitebook) and 2.92.0 (precision) both support `--json` fine. There
+# is no gh version floor documented anywhere else in this codebase, so this
+# constant is the single source of truth for it — surfaced in the actionable
+# error message below (:func:`_gh_too_old_message`) and in
+# ``docs/AGENT_OPERATIONS.md``'s daemon-host prerequisites.
+#
+# 2.86.0 is simply the *oldest version this fleet has directly observed
+# working* — nobody has bisected the actual gh release that first shipped
+# `pr checks --json` support, so treat this as a confirmed-good floor, not a
+# precisely-researched one. Lower it if a narrower floor is ever confirmed.
+GH_PR_CHECKS_JSON_MIN_VERSION = "2.86.0"
+
+# The exact, stable cobra/pflag message `gh` emits for a flag it doesn't
+# recognise at all — confirmed verbatim against dellserver's gh 2.45.0.
+# Distinct from (and must be checked before assuming) the "field not valid"
+# failure a newer gh gives for a bad field *name* (e.g. the original
+# `conclusion` bug), which instead exits 1 with a "Unknown JSON field" body.
+_GH_UNKNOWN_JSON_FLAG_MARKER = "unknown flag: --json"
+
+
+def _gh_version() -> str | None:
+    """Best-effort parse of ``gh --version``'s version string (e.g. "2.45.0").
+
+    Returns ``None`` if ``gh`` is missing, times out, or prints something
+    this can't parse — callers must treat that as "unknown", never fail on it.
+    """
+    try:
+        result = subprocess.run(
+            ["gh", "--version"], capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    match = re.search(r"gh version (\S+)", result.stdout or "")
+    return match.group(1) if match else None
+
+
+def _gh_too_old_message(stderr: str) -> str:
+    """Build the actionable error text for :class:`GhTooOldForJsonChecks`.
+
+    Names the host and the installed (if determinable) and required gh
+    versions explicitly — this is the whole point of #1564 Addendum 2: an
+    operator reading a merge refusal should never have to guess whether the
+    gate found a red check, hit a network blip, or is simply running on a
+    `gh` too old to ask the question at all.
+    """
+    host = socket.gethostname()
+    version = _gh_version() or "unknown"
+    return (
+        f"gh on host {host!r} (version {version}) does not support "
+        f"`gh pr checks --json` at all ({stderr!r}) — gh >= "
+        f"{GH_PR_CHECKS_JSON_MIN_VERSION} is required on whichever host runs "
+        f"the CI merge gate. Since `coord merge` re-invokes itself on the "
+        f"daemon (COORD_MERGE_ON_DAEMON), that means the *daemon* host's gh, "
+        f"not the client's. See docs/AGENT_OPERATIONS.md's daemon-host "
+        f"prerequisites."
+    )
+
+
+def get_repo_workflow_count(repo: str) -> int:
+    """Number of GitHub Actions workflows GitHub recognises for *repo* (#1904).
+
+    Backs :meth:`coord.ci_github.GitHubCi.expects_checks` — the signal that
+    distinguishes "this repo has no CI configured" (an empty ``gh pr checks``
+    result is correct) from "CI exists but never triggered for this PR" (an
+    empty result is a red flag: a throttled webhook, a wedged run, a
+    ``paths:``-filtered-out workflow). Queries the workflow *definitions*
+    GitHub knows about for the repo as a whole — not any particular branch
+    or PR's check runs — so the answer doesn't depend on whether this PR's
+    push ever actually triggered a run, which is exactly the case this
+    exists to catch.
+
+    Raises (``RuntimeError``/:class:`GhError`) on any read failure — auth,
+    rate-limit, malformed response — rather than defaulting to 0. A caller
+    that can't tell "no workflows" from "couldn't check" must not silently
+    treat the latter as the former; see #1525 for the identical reasoning
+    applied to check-run reads themselves.
+    """
+    data = _gh_json("api", f"repos/{repo}/actions/workflows", default=None)
+    if not isinstance(data, dict) or not isinstance(data.get("total_count"), int):
+        raise RuntimeError(
+            f"gh api repos/{repo}/actions/workflows: malformed response"
+        )
+    return data["total_count"]
+
+
+def get_pr_checks(repo: str, number: int) -> list[dict]:
+    """Return ``gh pr checks``' raw check-run list for PR *number*.
+
+    ``gh pr checks`` exits non-zero when any check has failed, but its JSON
+    stdout is still valid in that case — only raise when stdout is genuinely
+    empty (a real lookup failure: bad PR number, auth, rate-limit, an old gh
+    that doesn't support ``--json`` at all, ...). The single ``gh`` sink for
+    :class:`coord.ci_github.GitHubCi`, the CI backend behind the merge gate
+    (#1483).
+
+    Raises :class:`GhTooOldForJsonChecks` — instead of the generic
+    ``RuntimeError`` below — when the installed ``gh`` doesn't recognise
+    ``--json`` on ``pr checks`` at all (#1564 Addendum 2), so callers can
+    surface a distinct, actionable "upgrade gh" message rather than lumping
+    it in with ordinary read failures.
+    """
+    result = subprocess.run(
+        [
+            "gh", "pr", "checks", str(number),
+            "--repo", repo,
+            "--json", ",".join(PR_CHECKS_JSON_FIELDS),
+        ],
+        capture_output=True, text=True, timeout=30,
+    )
+    stdout = (result.stdout or "").strip()
+    if result.returncode != 0 and not stdout:
+        stderr = result.stderr.strip()
+        if _GH_UNKNOWN_JSON_FLAG_MARKER in stderr:
+            raise GhTooOldForJsonChecks(_gh_too_old_message(stderr))
+        raise RuntimeError(f"gh pr checks failed: {stderr}")
+    # #1525: unlike the fail-open sites elsewhere in this module, a malformed
+    # (non-empty) response here must NOT be swallowed to a quiet ``[]`` —
+    # ``ci_github.GitHubCi._fetch`` deliberately catches the ``ValueError``
+    # (``json.JSONDecodeError`` is a subclass) this raises and turns it into
+    # a synthetic *failing* check, so the merge gate blocks and says why
+    # instead of reading "no checks" as "clear to merge" (the exact silent
+    # fail-open that let PR #1521 merge past a real CI failure). Only the
+    # genuinely-empty-stdout case (``stdout or "[]"``, unchanged from before)
+    # is a deliberate default here — that's ``gh``'s normal "zero checks
+    # configured" response, not a decode failure.
+    return json.loads(stdout or "[]")
+
+
+def get_run_jobs(repo: str, run_id: str) -> list[dict]:
+    """Return ``gh api .../actions/runs/{run_id}/jobs``' raw ``jobs`` list (#1892).
+
+    The single ``gh`` sink for :meth:`coord.ci_github.GitHubCi.
+    list_jobs_for_run` — the one call that carries per-step detail
+    (``runner_name``, each step's ``name``/``conclusion``) a plain
+    ``gh pr checks`` read never has. Deliberately NOT the ``--json``
+    field-selection style :func:`get_pr_checks` uses: ``gh api`` returns the
+    endpoint's full JSON shape and this needs several nested fields
+    (``steps[].name``, ``steps[].conclusion``, ``runner_name``) that aren't
+    worth hand-picking.
+
+    Raises ``RuntimeError``/``ValueError`` on any read failure — auth,
+    rate-limit, malformed response, or the run id simply not existing
+    (rerun raced a retention window). Callers on the classification path
+    (:mod:`coord.ci_store`'s false-negative bias) must catch and treat a
+    raised error the same as "no job data" — never as evidence either way.
+    """
+    data = _gh_json("api", f"repos/{repo}/actions/runs/{run_id}/jobs", default=None)
+    if not isinstance(data, dict) or not isinstance(data.get("jobs"), list):
+        raise RuntimeError(
+            f"gh api repos/{repo}/actions/runs/{run_id}/jobs: malformed response"
+        )
+    return data["jobs"]
+
+
+def rerun_workflow_run(repo: str, run_id: str) -> bool:
+    """Re-run Actions workflow run *run_id* on *repo* via ``gh run rerun``.
+
+    The single ``gh`` sink (#1483) for :meth:`coord.ci_github.GitHubCi.
+    rerun_for_pr` (#1851) — the same seam :func:`get_pr_checks` is for
+    reading checks. Returns ``True`` only on a clean (exit 0) rerun; any
+    subprocess failure (missing ``gh``, timeout, non-zero exit — e.g. the run
+    is already in progress, or the id is stale/invalid) returns ``False``
+    rather than raising, matching this module's other best-effort mutators
+    (:func:`merge_pr`, :func:`edit_pr_body`).
+    """
+    try:
+        result = subprocess.run(
+            ["gh", "run", "rerun", str(run_id), "--repo", repo],
+            capture_output=True, text=True, timeout=30,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return result.returncode == 0
+
+
+def truncate_diff_text(diff: str, max_chars: int = 60000) -> str:
+    """Truncate *diff* to *max_chars* with a trailing note, if it's over.
+
+    Factored out of :func:`pr_diff` (#1475) so callers that need the full,
+    untruncated diff for content hashing (``compute_patch_id``) can still
+    apply the same display truncation to a *separate* copy shown to a human
+    reviewer or embedded in a briefing, without a second ``gh`` fetch.
+    """
+    if len(diff) > max_chars:
+        return diff[:max_chars] + f"\n... [diff truncated at {max_chars} chars] ..."
+    return diff
+
+
+def pr_diff(repo_github: str, pr_number: int, *, max_chars: int | None = 60000) -> str | None:
+    """Return the merge-base (three-dot) diff for PR ``pr_number``, or None.
+
+    ``gh pr diff`` is three-dot / merge-base by GitHub semantics, so the output
+    is exactly the branch's own changes (#612) — code merged to the base after
+    the branch was cut never appears as spurious deletions. Truncated to
+    *max_chars* with a trailing note so a huge diff can't blow the briefing
+    size — pass ``max_chars=None`` to get the full, untruncated diff (#1475:
+    needed for content-hashing via ``compute_patch_id``, which must not hash
+    a mutated/truncated string). Best-effort: returns None on any ``gh`` error
+    so the caller falls back to the in-briefing three-dot diff instructions.
+    """
+    try:
+        diff = _gh("pr", "diff", str(pr_number), "--repo", repo_github)
+    except RuntimeError:
+        return None
+    if max_chars is None:
+        return diff
+    return truncate_diff_text(diff, max_chars)
+
+
+def compute_patch_id(diff_text: str | None) -> str | None:
+    """Return the ``git patch-id --stable`` hash of *diff_text*, or ``None``.
+
+    #1475: a content-addressed fingerprint of a diff — insensitive to commit
+    SHA / line numbers, but sensitive to the surrounding context lines. A
+    pure rebase with no conflict replays the identical diff against a new
+    base and produces the same patch-id even though the commit SHA changed;
+    a conflict resolution or genuine content change produces a different one
+    (that distinction is #1476's job, not this function's).
+
+    ``git patch-id`` operates purely on the piped diff text — no working
+    directory or repo checkout required, so this is safe to call from any
+    process. Returns ``None`` for empty/missing input or on any subprocess
+    failure; callers must fail closed (treat a missing patch-id as "cannot
+    confirm identical content", never as "identical").
+    """
+    if not diff_text or not diff_text.strip():
+        return None
+    try:
+        result = subprocess.run(
+            ["git", "patch-id", "--stable"],
+            input=diff_text, capture_output=True, text=True, timeout=15,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    if result.returncode != 0:
+        return None
+    line = result.stdout.strip().splitlines()[0] if result.stdout.strip() else ""
+    if not line:
+        return None
+    return line.split()[0]
+
+
+def get_compare_diff(repo: str, base: str, head: str) -> str | None:
+    """Return the raw three-dot (``base...head``) unified diff text, or None.
+
+    *head* may be a branch name or a commit SHA — GitHub's compare API treats
+    them identically, so this also works for a historical SHA that is no
+    longer any branch's tip (e.g. the HEAD a review approved before a
+    conflict-fix rebase moved the branch on, #1476). Factored out of
+    :func:`get_branch_patch_id` so a scoped re-review can fetch the diff for
+    an old SHA as well as the current branch tip, without duplicating the
+    ``gh api compare`` call shape. Returns ``None`` on any ``gh`` failure —
+    callers must fail closed (missing diff ⇒ cannot confirm anything about
+    its content).
+    """
+    try:
+        return _gh(
+            "api", f"repos/{repo}/compare/{base}...{head}",
+            "-H", "Accept: application/vnd.github.v3.diff",
+        )
+    except RuntimeError:
+        return None
+
+
+def get_compare_files(repo: str, base: str, head: str) -> list[str] | None:
+    """Return the list of file paths changed in the three-dot ``base...head``
+    compare, or ``None`` on any ``gh`` failure.
+
+    #1720: the dispatch-time file-overlap fence needs *which files*, not the
+    diff content — asking the compare API for ``.files[].filename`` directly
+    is cheaper and simpler than fetching :func:`get_compare_diff`'s full
+    unified-diff text and parsing ``diff --git a/... b/...`` headers out of
+    it. Uses the GitHub API (not a local checkout) so it works from any host
+    with `gh` on PATH, matching this module's existing checkout-independent
+    diff helpers (:func:`pr_diff`, :func:`get_compare_diff`) rather than the
+    coordinator assuming it has a local clone of every dispatched repo.
+
+    ``--jq`` on a leaf-string selector (``.filename``, unlike the object
+    selector in :func:`get_repo_milestones`) emits *raw* text, one path per
+    line, not JSON-quoted — so this reads lines directly rather than
+    JSON-decoding them. Returns ``None`` (not ``[]``) on failure so callers
+    can distinguish "no files changed" from "couldn't ask" and fail open
+    accordingly.
+    """
+    try:
+        raw = _gh(
+            "api", f"repos/{repo}/compare/{base}...{head}",
+            "--jq", ".files[].filename",
+        )
+    except RuntimeError:
+        return None
+    return [line for line in (ln.strip() for ln in raw.splitlines()) if line]
+
+
+def branch_commits_ahead(repo: str, base: str, branch: str) -> int | None:
+    """Commits *branch* is ahead of *base* on the remote, or ``None``.
+
+    #1534: the coordinator usually has no local checkout of a worker's branch,
+    so the zero-commit question has to be asked of GitHub.  Uses the same
+    three-dot compare API as :func:`get_branch_diff_size` and reads
+    ``ahead_by`` — no PR required.
+
+    Returns ``None`` (never 0) on any ``gh`` failure, an unparseable payload,
+    or a missing ``ahead_by`` field.  Callers MUST treat ``None`` as "unknown,
+    assume non-zero": this exists to *refuse* work on a provably empty branch,
+    and a network blip must not silently become a refusal — that would strand
+    real reviews.  This is the opposite polarity from
+    :func:`branch_is_fully_merged`, which returns a plain ``False`` on error
+    because *its* fail-safe direction is "keep the PR open".
+    """
+    if not branch or not base:
+        return None
+    if branch == base:
+        return 0
+    try:
+        raw = _gh("api", f"repos/{repo}/compare/{base}...{branch}")
+        cmp = json.loads(raw)
+    except Exception:  # noqa: BLE001 — unknown, not zero
+        return None
+    if not isinstance(cmp, dict):
+        return None
+    ahead = cmp.get("ahead_by")
+    if not isinstance(ahead, int) or isinstance(ahead, bool):
+        return None
+    return ahead
+
+
+def branch_commits_ahead_for_assignment(assignment: Any, config: Any) -> int | None:
+    """:func:`branch_commits_ahead` for a board *assignment*, or ``None``.
+
+    #1606: `coord retry`'s advisory zero-commit gate
+    (``coord/commands/dispatch.py``'s ``retry()``) and `coord diagnose
+    --stage work`'s ADVISORY-row recovery (``coord/diagnose.py``'s
+    ``_work_advisory_commits_ahead``) both ask GitHub this exact question —
+    they used to do it via two independently-written inline copies of
+    "branch empty -> 0, repo missing -> None, else ask GitHub", which even
+    diverged in how they looked up the repo config (``cfg.repo(name)`` vs.
+    a hand-rolled scan over ``config.repos`` — equivalent, but two copies is
+    how they drift apart later). This is the one copy both now call.
+
+    *assignment* needs only ``.branch`` and ``.repo_name``; *config* needs
+    only ``.repo(name)`` returning an object with ``.github`` /
+    ``.default_branch`` (both ``coord.models.Assignment`` and
+    ``coord.config.Config`` satisfy this — left untyped here to avoid
+    github_ops.py importing either module).
+
+    An assignment with no branch (or a blank one) is treated as 0 commits
+    ahead without ever calling GitHub — there is nothing to compare. A repo
+    that ``config`` doesn't know about returns ``None`` ("cannot confirm"),
+    never a bare 0, matching :func:`branch_commits_ahead`'s own fail-closed
+    polarity: an unconfirmable commit count must never be silently read as
+    "empty branch, safe to touch".
+    """
+    branch = (getattr(assignment, "branch", None) or "").strip()
+    if not branch:
+        return 0
+    repo_cfg = config.repo(assignment.repo_name)
+    if repo_cfg is None:
+        return None
+    base = repo_cfg.default_branch or "main"
+    return branch_commits_ahead(repo_cfg.github, base, branch)
+
+
+def get_branch_patch_id(repo: str, base: str, branch: str) -> str | None:
+    """Return the content-addressed patch-id for *branch*'s diff against *base*.
+
+    #1475: uses the GitHub three-dot compare API (no PR required, mirroring
+    :func:`get_branch_diff_size`) to fetch the raw unified diff, then hashes
+    it with :func:`compute_patch_id`. Returns ``None`` on any failure — the
+    merge-queue gate treats a missing patch-id as "cannot confirm identical
+    content" and falls back to the pre-#1475 SHA-only staleness check
+    (fail closed).
+    """
+    return compute_patch_id(get_compare_diff(repo, base, branch))
+
+
+def create_pr(
+    repo: str,
+    *,
+    base: str,
+    head: str,
+    title: str,
+    body: str,
+) -> dict:
+    """Open a PR. Returns {number, url}. If one already exists for `head`, returns it."""
+    existing = find_pr_for_branch(repo, head)
+    if existing is not None:
+        return {"number": existing["number"], "url": existing["url"], "existed": True}
+    url = _gh(
+        "pr", "create", "--repo", repo,
+        "--base", base, "--head", head,
+        "--title", title, "--body", body,
+    )
+    # gh pr create returns the URL on the last line of stdout.
+    pr_url = url.strip().splitlines()[-1] if url.strip() else ""
+    number = int(pr_url.rsplit("/", 1)[-1]) if pr_url else 0
+    return {"number": number, "url": pr_url, "existed": False}
+
+
+def get_pr_size(repo: str, number: int) -> int:
+    """Return additions+deletions for sequencing. 0 on lookup failure."""
+    try:
+        raw = _gh(
+            "pr", "view", str(number), "--repo", repo,
+            "--json", "additions,deletions",
+        )
+    except RuntimeError:
+        return 0
+    data = _json_loads_or(raw, default={})
+    return int(data.get("additions", 0)) + int(data.get("deletions", 0))
+
+
+def get_branch_diff_size(repo: str, base: str, branch: str) -> int:
+    """Return total diff size (additions+deletions) for *branch* relative to *base*.
+
+    Uses the GitHub three-dot compare API — no PR required.  Sums
+    ``additions + deletions`` across all changed files.  Returns ``0`` on any
+    failure so callers can treat size as unknown-but-not-blocking.
+
+    Prefer this over :func:`get_pr_size` at enqueue time so size is populated
+    before a PR is opened and the ordering shown to the user matches the
+    ordering used at merge time (#776 size unification).
+    """
+    try:
+        raw = _gh("api", f"repos/{repo}/compare/{base}...{branch}")
+        data = json.loads(raw)
+        return sum(
+            int(f.get("additions", 0)) + int(f.get("deletions", 0))
+            for f in data.get("files", [])
+        )
+    except Exception:  # noqa: BLE001 — fail-open: unknown size is not blocking
+        return 0
+
+
+def merge_pr(repo: str, number: int, method: str = "rebase") -> tuple[bool, str]:
+    """Merge a PR. Returns (success, message).
+
+    Conflict / not-rebaseable cases come back as (False, <gh stderr>). Caller
+    decides whether to retry or surface to the user — we never resolve conflicts
+    here.
+    """
+    flag = {"rebase": "--rebase", "squash": "--squash", "merge": "--merge"}.get(method, "--rebase")
+    try:
+        out = _gh("pr", "merge", str(number), "--repo", repo, flag, "--delete-branch=false")
+    except RuntimeError as e:
+        return False, str(e)
+    return True, out
+
+
+def list_open_prs(repo: str) -> list[dict]:
+    return _gh_json(
+        "pr", "list", "--repo", repo, "--state", "open",
+        "--json", "number,title,headRefName",
+        default=[],
+    )
+
+
+def get_recent_develop_commits(repo: str, count: int = 10) -> list[dict]:
+    commits = _gh_json(
+        "api", f"repos/{repo}/commits?sha=develop&per_page={count}",
+        default=[],
+    )
+    return [
+        {"sha": c["sha"][:7], "message": c["commit"]["message"].split("\n")[0]}
+        for c in commits
+    ]
+
+
+def create_issue(
+    repo: str,
+    title: str,
+    body: str,
+    labels: list[str] | None = None,
+    milestone: str | None = None,
+) -> dict:
+    args = ["issue", "create", "--repo", repo, "--title", title, "--body", body]
+    if labels:
+        for label in labels:
+            args.extend(["--label", label])
+    if milestone:
+        args.extend(["--milestone", milestone])
+    raw = _gh(*args)
+    url = raw.strip()
+    number = int(url.rstrip("/").rsplit("/", 1)[-1])
+    return {"number": number, "url": url}
+
+
+def update_issue_body(repo: str, issue_number: int, body: str) -> None:
+    _gh(
+        "api", "-X", "PATCH",
+        f"repos/{repo}/issues/{issue_number}",
+        "-f", f"body={body}",
+    )
+
+
+def get_repo_milestones(repo: str, *, state: str = "open") -> list[dict]:
+    """Return milestones for *repo* (open ones by default).
+
+    Each item has at least ``number`` and ``title`` keys, matching the
+    shape returned by the GitHub milestones REST endpoint. Used to resolve a
+    milestone title → number (``coord milestone assign``) without a separate
+    call.
+    """
+    raw = _gh(
+        "api", "--paginate",
+        f"repos/{repo}/milestones?state={state}",
+        "--jq", ".[] | {number: .number, title: .title}",
+    )
+    # --jq emits one JSON object per line when applied to an array.  #1353:
+    # a single malformed line used to bare-json.loads() into an unattributable
+    # crash that discarded every other (well-formed) milestone line too — skip
+    # just the bad line instead.
+    results = []
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        parsed = _json_loads_or(line, default=None)
+        if parsed is not None:
+            results.append(parsed)
+    return results
+
+
+def get_milestone(repo: str, milestone_number: int) -> dict:
+    """Fetch a single milestone by number; returns ``{number, title, ...}``.
+
+    Used to resolve a milestone number → title so the local issues cache
+    ``milestone_title`` column can be populated without listing all milestones.
+    Raises RuntimeError (propagated from ``_gh``) when the milestone does not
+    exist.
+    """
+    return _gh_json("api", f"repos/{repo}/milestones/{milestone_number}", default={})
+
+
+def get_milestone_issues(
+    repo: str, milestone_title: str, *, state: str = "all"
+) -> list[dict]:
+    """Return every issue under *milestone_title* in *repo* (open+closed by default).
+
+    Each item has ``number``, ``title``, ``state`` ("OPEN"/"CLOSED"), and
+    ``labels`` (list of ``{"name": ...}``). ``gh issue list --milestone`` takes
+    the milestone TITLE, not its number (unlike most other milestone-related
+    calls in this module) — matches the existing ``--milestone`` usage in
+    :func:`create_issue`. Used by ``--audit-of`` (#885) to enumerate a
+    milestone's issue states for the audit briefing without a separate call
+    per issue.
+    """
+    return _gh_json(
+        "issue", "list", "--repo", repo, "--milestone", milestone_title,
+        "--state", state, "--json", "number,title,state,labels",
+        "--limit", "200",
+        default=[],
+    )
+
+
+def assign_issue_milestone(
+    repo: str, issue_number: int, milestone_number: int
+) -> None:
+    """Assign *milestone_number* to *issue_number* on *repo* via the GitHub API.
+
+    Uses ``gh api -X PATCH`` with ``-F milestone=<int>`` (capital -F so the
+    value is sent as a JSON integer, as GitHub's REST API requires). Raises
+    RuntimeError on any ``gh`` failure.
+    """
+    _gh(
+        "api", "-X", "PATCH",
+        f"repos/{repo}/issues/{issue_number}",
+        "-F", f"milestone={milestone_number}",
+    )
+
+
+def unassign_issue_milestone(repo: str, issue_number: int) -> None:
+    """Clear *issue_number*'s milestone on *repo* via the GitHub API (#1003).
+
+    The counterpart to :func:`assign_issue_milestone` — ``-F milestone=null``
+    sends a JSON ``null`` (per ``gh api``'s typed-field convention: literal
+    ``null``/``true``/``false``/numbers are sent as their JSON type, not a
+    string), which GitHub's REST API treats as "remove the milestone".
+    Idempotent — clearing an issue that has no milestone is a no-op on
+    GitHub's side. Raises RuntimeError on any ``gh`` failure.
+    """
+    _gh(
+        "api", "-X", "PATCH",
+        f"repos/{repo}/issues/{issue_number}",
+        "-F", "milestone=null",
+    )
+
+
+def close_pr(repo: str, number: int, *, comment: str | None = None) -> None:
+    """Close an open PR, optionally posting a comment first.
+
+    Posts *comment* (if given) via ``gh issue comment`` — PRs share the GitHub
+    issue comment stream — then closes the PR via ``gh pr close``.  Raises
+    RuntimeError on ``gh`` failure.
+    """
+    if comment:
+        post_issue_comment(repo, number, comment)
+    _gh("pr", "close", str(number), "--repo", repo)
+
+
+def branch_is_fully_merged(
+    repo: str,
+    branch: str,
+    default_branch: str = "main",
+) -> bool:
+    """Return True when *branch* has 0 commits ahead of *default_branch*.
+
+    Uses the GitHub three-dot compare API.  Returns False on any error —
+    fail-safe so we never accidentally close a live PR.
+
+    Note: only detects **fast-forward** merges.  After a squash or rebase
+    merge the branch's original commits remain "ahead" (different SHAs) even
+    though the work has landed.  The ``issue_is_closed`` check is the primary
+    stale-PR signal for those cases.
+    """
+    if not branch or not default_branch or branch == default_branch:
+        return False
+    try:
+        raw = _gh("api", f"repos/{repo}/compare/{default_branch}...{branch}")
+        cmp = json.loads(raw)
+        return isinstance(cmp, dict) and cmp.get("ahead_by") == 0
+    except Exception:  # noqa: BLE001 — fail-safe: keep the PR open on any error
+        return False
+
+
+def post_pr_review(repo: str, number: int, verdict: str, body: str) -> None:
+    """Post a PR review via the gh CLI.
+
+    *verdict* must be ``"approve"`` or ``"request-changes"``.  Any other value
+    raises :class:`ValueError` before invoking gh.
+    """
+    if verdict == "approve":
+        flag = "--approve"
+    elif verdict == "request-changes":
+        flag = "--request-changes"
+    else:
+        raise ValueError(f"Invalid review verdict: {verdict!r} (must be 'approve' or 'request-changes')")
+    _gh("pr", "review", str(number), "--repo", repo, flag, "--body", body)