@erclx/canon 4.20.1 → 4.21.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "4.20.1",
+  "version": "4.21.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-address-review/SKILL.md

@@ -27,10 +27,10 @@ For inline review comments, read them via `gh api` on the PR's review comments.
 Also read the CI check status so the fixes cover failing checks, not only review comments:
 
 ```bash
-gh pr checks <number>
+canon pr checks <number> --json
 ```
 
-Treat a failing check as a finding to resolve alongside the review comments. When no checks are configured, `gh pr checks` reports none and the flow continues on the review findings alone.
+Read the verdict off the record's `state` rather than off the exit. Treat `failing` as a finding to resolve alongside the review comments. A `pending` covers a tip whose runs have yet to conclude and a tip carrying no run at all, which the record separates on `matched`, and neither is a green to continue on. Fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb.
 
 ## Step 2: address each finding
 
@@ -161,10 +161,10 @@ gh pr comment <number> --body-file .canon/tmp/address-review/reply-<number>.md
 
 ## Step 7: confirm resolution
 
-After the follow-up push, watch CI on the PR. Poll `gh pr checks <number>`
-until no check is pending, then read the final status. When every finding is
-addressed and all checks pass, post one closing comment so the thread has a
-clear terminal state:
+After the follow-up push, watch CI on the PR. Poll
+`canon pr checks <number> --json` until the record's `state` leaves `pending`,
+then read it. When every finding is addressed and the state is `passing`, post
+one closing comment so the thread has a clear terminal state:
 
 ```bash
 gh pr comment <number> --body "✅ All review findings addressed, CI green."

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -72,6 +72,8 @@ The report is also where the count in `## Parallelism` is legible. That threshol
 
 The count reads low, and it errs in the direction that breaks the trigger. A review's `commit.oid` is stamped with the head at submission rather than with the commit the reviewer read, so an author pushing between the diff read and the post leaves the pass recorded against a commit it never saw, and `SEEN` then fires on a head still awaiting its first look at that delta. Measured on `#1299` on 2026-08-31, where a pass written against `5653721` landed stamped `a5ceb40` and the delta it skipped was a real fix. So a `SEEN` on a head you do not recognize is worth one `gh pr view --json reviews` before it is believed, and a wave past three is likelier to trip the fallback late than early.
 
+The other side of that comparison used to lag as well, which made the two errors compound rather than cancel. `gh pr view --json headRefOid` answers from the pull request object and that object trails the branch ref by up to a minute after a push, reporting nothing about the trail, so a pass stamped ahead of the commit it read was compared against a head stamped behind the commit that exists. Two sessions were wrong off that field on 2026-09-01: a reviewing session posted a finding calling a pushed commit unpushed, and a worker fired a green claim it retracted on its own thread minutes later. The head now comes from `canon pr head`, which resolves the tip through `git ls-remote` and reports which commit each source names, and the object's head stays behind it as the fallback for a target whose CLI predates the verb. The review stamp is unchanged, so the paragraph above still holds on its own half.
+
 ## The watch beside it
 
 `${CLAUDE_SKILL_DIR}/scripts/watch.sh` is a long-running loop rather than a scheduled prompt. It reads the open pull request list and the session roster together every sixty seconds and prints one line per new pull request, per worker whose status changed, and per worker that dropped out of the roster. Start it in the background and read what it emits. It writes nothing.

package/claude/skills/claude-orchestrate/scripts/poll.sh

@@ -187,7 +187,25 @@ snapshot() {
       continue
     fi
 
-    head=$(jq -r '.headRefOid // empty' <<<"$payload")
+    # The tip is the authority for the head, not the pull request object. That
+    # object lags the ref by up to a minute after a push, so MOVED fired late
+    # and the merge-tree read below judged a commit the branch had already left
+    # behind. Read on the record's own field rather than on the exit, since an
+    # operator shell profile can wrap canon in a function that flattens it.
+    # The trailing assignment is load-bearing under `set -e` and `set -o
+    # pipefail` at the top of this file. Every refusal exits 1, and a refusal
+    # here is ordinary rather than exceptional, so an unguarded pipeline would
+    # end the whole poll on the first pull request whose branch was deleted.
+    head=$(canon pr head "$n" --json 2>/dev/null | jq -r '.tip // empty') || head=""
+
+    # The object's head is the fallback rather than the source. This script
+    # ships with the plugin and the verb ships with the CLI, so a target on an
+    # older binary reaches no `pr head` at all, and answering there with the
+    # lagging head is the behavior this poll already had.
+    if [ -z "$head" ]; then
+      head=$(jq -r '.headRefOid // empty' <<<"$payload")
+    fi
+
     if [ -z "$head" ]; then
       carry_forward "$n" "returned no head"
       continue

package/claude/skills/claude-pr-review/SKILL.md

@@ -29,7 +29,7 @@ reader scanning the thread finds the current verdict where the last one sat.
 
 ## Step 1: resolve the PR and read context
 
-Resolve the PR: `gh pr view --json number,headRefName,headRefOid,title,body` for the current branch, or use a PR number the user names. The first seven characters of `headRefOid` are `<short-sha>`, which names the body file in Step 4.
+Resolve the PR: `gh pr view --json number,headRefName,headRefOid,title,body` for the current branch, or use a PR number the user names. Take `<headRefOid>` from `canon pr head <number> --json`, off that record's `tip`, and fall back to the `headRefOid` field above when no record comes back, which is a target whose CLI predates the verb. The first seven characters are `<short-sha>`, which names the body file in Step 4.
 
 Read these in parallel from the project root, skipping any that do not exist:
 

package/claude/skills/git-ship/SKILL.md

@@ -30,7 +30,7 @@ Run `git diff --cached --name-only 2>/dev/null` to check for staged files. If ou
 5. Invoke `canon:git-stage` to group staged changes and commit by concern
 6. Invoke `canon:git-branch` to rename branch to match conventional format
 7. Invoke `canon:git-pr` to push branch and open pull request
-8. After the PR opens, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
+8. After the PR opens, watch CI. Poll `canon pr checks <number> --json` until the record's `state` leaves `pending`, branching on that field rather than on the exit, and fall back to `gh pr checks <number>` when no record comes back at all, which is a target whose CLI predates the verb. On `passing`, continue. On `failing`, stop the sequence and report the failing check with its URL. Do not auto-fix. This step may output on failure, the one exception to the no-text-between-steps rule.
 9. If step 1 wrote or updated at least one memory file, invoke `canon:claude-memory-review` scoped to those entries to propose fixes while session context is fresh. If the pen got nothing, skip this step.
 
 A caller wrapping this sequence may act between step 7 and step 8, which is the one gap the order leaves open, since the pull request exists there and nothing has read its checks yet. `claude-autoship` marks the pull request draft in it. Nothing else may go there, and a caller that needs a step anywhere else in the sequence is asking for a change to this body rather than for a place to stand.

package/docs/agents/commands.md

@@ -71,6 +71,8 @@ Full help: `canon <command> --help`. Behavior notes for the install and sync ver
 | `canon labels scan`           | Fail a pull request whose title or body carries a phase label, a label a code span quotes, a gitignored record path, or a session link (`--event`, `--json`)          |
 | `canon autoship classify`     | Decide whether a changed set needs the review pass, naming the file and the test that decided it (`--json`)                                                           |
 | `canon pr key-changes`        | Compare the files a pull request body's Key Changes names against its own diff, in both directions (`--body`, `--base`, `--json`)                                     |
+| `canon pr head`               | Compare the head a pull request object reports against the branch tip the remote carries, naming both shas (`--root`, `--json`)                                       |
+| `canon pr checks`             | Report the check runs belonging to the branch tip, reading pending for a tip carrying none rather than clean (`--root`, `--json`)                                     |
 | `canon repo metadata propose` | Compare a description, homepage, and topic set computed from the README and `package.json` against what the remote carries, writing nothing (`--root`, `--json`)      |
 | `canon repo metadata apply`   | Write an explicitly supplied description, homepage, or topic set to the remote through `gh repo edit` (`--description`, `--homepage`, `--topics`, `--root`, `--json`) |
 | `canon census [path]`         | Report tracked file count, a breakdown by extension, and a line total that skips whatever reads as binary (`--json`)                                                  |
@@ -132,6 +134,7 @@ Each domain exposes a consistent shape where applicable: `list`, `install`, `syn
 | `labels`    | `audit`                                                                                                                               |
 | `migrate`   | `rename`, `records`                                                                                                                   |
 | `autoship`  | `classify`                                                                                                                            |
+| `pr`        | `key-changes`, `head`, `checks`                                                                                                       |
 | `audits`    | `run`, `list`                                                                                                                         |
 | `gate`      | `run`                                                                                                                                 |
 

package/docs/agents/index.md

@@ -28,6 +28,7 @@ CLI catalog and invocation rules for agents, split by command domain. Start with
 - [Markdown audit](markdown-audit.md): Running the audit over any markdown path, where its bans and checkpoints are read from, what each check reports, and why the ban half gates while the structural half reports
 - [Output shape](output-shape.md): Two framed shapes every command renders into, how JSON and --names modes keep stdout clean, and the exit discipline that lets piped output drain
 - [Overview](overview.md): What this folder covers, the invocation rules every command inherits, and where domain behavior is documented instead
+- [Head-sensitive pull request reads](pr-reads.md): Resolving a branch tip from the remote rather than from the pull request object, reading check runs keyed on that tip, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
 - [Records](records.md): The two roots a record folder resolves at, validating the session records and the standards corpus, the per-kind checks, the refusal reasons, migrating a record a frontmatter change orphaned, reading each folder's size and growth, backing the folders to a private remote, and which root each kind defaults to
 - [Restated instructions](restated.md): Counting the instructions the always-loaded file and every path-scoped rule share with the seed, the shipped skill bodies, and each other, how a match is decided, the three classes, which surface a later edit starts from, and why the sweep reports rather than gates
 - [Review classification](review-classification.md): Deciding whether a changed set needs the review pass, the two tests it runs, why an empty set refuses rather than skipping, and the written fallback a target on an older binary falls back to

package/docs/agents/pr-reads.md

@@ -0,0 +1,73 @@
+---
+title: Head-sensitive pull request reads
+description: Resolving a branch tip from the remote rather than from the pull request object, reading check runs keyed on that tip, why an empty run list is not a pass, the refusal reasons each verb names, and what the remote read costs
+---
+
+# Head-sensitive pull request reads
+
+`canon pr head` and `canon pr checks` answer about a commit. Both resolve the branch tip from the remote with `git ls-remote` and report what they found for that sha, rather than taking the pull request object's word for which commit the branch is on.
+
+```bash
+canon pr head
+canon pr head 1341 --json
+canon pr checks
+canon pr checks 1341 --json
+```
+
+## The pull request object is not the authority for a head
+
+`gh pr view --json headRefOid` reads a field on the pull request object. That object trails the branch ref by up to a minute after a push and carries nothing saying how far behind it is, so a session that keys a read on it is describing whichever commit GitHub last folded into the object.
+
+Two failures on 2026-09-01 came off that one field. A reviewing session posted a finding calling a pushed commit unpushed. A worker fired a green claim and retracted it on its own thread minutes later. Neither session did anything wrong with the value it was handed. The value was stale and said so nowhere.
+
+The remote ref carries no such lag. `git ls-remote --heads origin <branch>` asks the remote itself rather than a tracking ref, which is only as current as the last fetch, and the push worth catching is the one this process never saw.
+
+The argument is stated here once. The shipped skill bodies call the verb rather than repeating it, because a sentence telling a session to compare two shas is a sentence a session can decide it already followed.
+
+## What each verb answers
+
+`canon pr head` reports `fresh` when the object and the remote name the same commit and `stale` when they disagree, with both shas on the record. The tip is the authority and the object's head is the claim being checked against it.
+
+`canon pr checks` reads `repos/{owner}/{repo}/commits/<tip>/check-runs` and collapses it to `passing`, `failing`, or `pending`. A failure outranks a run still going, since a run in flight cannot clear a job that already failed.
+
+`gh pr checks` cannot be made to answer this question at all, which is the argument for the move rather than a preference between two working commands. Its `--json` field set is `bucket, completedAt, description, event, link, name, startedAt, state, workflow`, with no sha among them, so a caller cannot even learn which commit its answer describes.
+
+## An empty run list is not a pass
+
+Keying the query on a sha is necessary and not sufficient. The endpoint answered with `total_count` 2 and an empty row list during a measured window on 2026-09-02, so a reader that finds no run for the tip and reports `passing` reproduces the false green behind a better query.
+
+Both empty cases report `pending` instead: a tip carrying no run yet, and a listing whose rows all belong to some other commit. The record separates them, since `matched` counts the runs belonging to the tip and `foreign` counts the rest, and a caller that wants to tell "not started" from "still going" reads those two numbers rather than the state alone.
+
+`matched` counts runs and not distinct checks, which is where it parts company with the list `gh pr checks` prints. A workflow that fires twice on one commit lands two runs under one name, so a pull request whose body was edited after the push reads 3 against that command's 2. Measured on 2026-09-02 against a commit whose phase-label workflow ran on the push and again on a later body edit. Read a `matched` above the check count as that, rather than as the verb disagreeing with the command.
+
+A listing carrying even one foreign run reports `pending` whatever the matching half says. A set that describes another commit says nothing about this one, so answering off the rows that happen to match would put a verdict on a set already known to be incomplete.
+
+A count above the rows returned reports `pending` for the same reason. The query asks for 100 rows against the endpoint's default of 30, and a commit carrying more than that comes back short, so the verb reports the tip as unread rather than collapsing the page it happens to hold. `reported` against `matched` and `foreign` is where a reader sees which of the three shapes produced the answer.
+
+## Reading the answer
+
+Branch on the record rather than on the exit. Both verbs exit 0 whenever they resolved a tip, whatever the verdict, and 1 only when they refused. An operator shell profile can wrap `canon` in a function whose status comes from a trailing command, which flattens every non-zero exit to 0, so the exit is not a channel either verb puts a verdict on. `gh pr checks` reserving exit 8 for pending is the pattern being replaced rather than one to copy.
+
+Each refusal names a different repair:
+
+| Reason             | What it means                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------ |
+| `gh-missing`       | `gh` is not on the path, so no pull request resolved                                       |
+| `gh-failed`        | `gh` could not answer for this branch, so name a number instead                            |
+| `no-branch`        | The pull request carries no head branch name, so no ref could be read                      |
+| `unresolvable-ref` | The remote read failed, which is not the same answer as an absent branch                   |
+| `no-remote-branch` | The remote carries no branch by that name, so there is no tip to compare against           |
+| `no-object-head`   | The pull request object reported no head, so `head` has nothing to compare the tip against |
+| `runs-unreadable`  | The check runs for the tip could not be read, which is unread rather than none             |
+
+A failed remote read and a branch the remote does not carry stay apart rather than collapsing into one reason. Reading the first as the second would report a network refusal as a deleted branch, and the repairs have nothing in common.
+
+## What it costs
+
+One remote round trip per call, sampled here at 0.41s, 0.55s, and 0.67s on 2026-09-01 and 2026-09-02, against 0.001s for the local ref read. The spread is the network rather than the command, so read it as roughly half a second and not as a figure to compare a later reading against. Every caller pointed at these verbs already spends a `gh` round trip on the same line, so the added cost lands on a path that was never local to begin with.
+
+One head-sensitive read is left on the object deliberately. `canon targets pulls` reads `statusCheckRollup` for every open pull request across every target, where resolving a tip per row would cost one remote read per pull request across a dozen projects, against a surface that reports a listing rather than gating a push.
+
+The orchestrator poll spends that same read per open pull request and repeats it on a three-minute timer, which makes it the heaviest caller here rather than an exception to the paragraph above. Six open pull requests is around 120 remote reads an hour. What separates the two cases is what each reading decides rather than what it costs. The poll's head fires the review trigger, so a stale one sends a pass at a commit nobody read or withholds one that is owed. The listing decides nothing, so the same spend buys a fresher column in a report and no correctness at all.
+
+`canon pr key-changes` also stays on the object, for a different reason. It reads the body, the file list, and `headRefOid` in one call on purpose, so the three describe one commit. That is a consistency requirement rather than a freshness one, and keying its head elsewhere would break it.

package/docs/operating-model.md

@@ -108,6 +108,13 @@ Findings travel on the PR. `claude-pr-review` posts them there.
 threads, and pushes a follow-up. `claude-pr-review` then runs again, reading only
 what the follow-up added.
 
+Both halves of that loop key on a commit rather than on the pull request object,
+which trails the branch ref by up to a minute after a push and says nothing
+about the trail. `canon pr head` resolves the tip the review pass scopes its
+delta against, and `canon pr checks` reports the runs belonging to that tip, so a
+follow-up push cannot be read as green off the predecessor's completed run. See
+[Head-sensitive pull request reads](agents/pr-reads.md).
+
 What the session channel carries is the handback instruction and the worker's
 reply to it, which is a notification layer over a record that stays on the PR. A
 reply that changes an outcome, such as a worker naming the plan question that

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/canon",
   "type": "module",
-  "version": "4.20.1",
+  "version": "4.21.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/cli.ts

@@ -88,7 +88,7 @@ function showHelp(): void {
     `${GREY}│${NC}    deps [cmd]         ${GREY}# Read the resolved dependency set for advisories (audit)${NC}`,
     `${GREY}│${NC}    labels [cmd]       ${GREY}# Read a changed set against the pull request label map (audit)${NC}`,
     `${GREY}│${NC}    autoship [cmd]     ${GREY}# Decide whether a changed set needs the review pass (classify)${NC}`,
-    `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request body against its own diff (key-changes)${NC}`,
+    `${GREY}│${NC}    pr [cmd]           ${GREY}# Read a pull request against its own diff and its branch tip (key-changes, head, checks)${NC}`,
     `${GREY}│${NC}    repo [cmd]         ${GREY}# This repository's own remote metadata (metadata propose, apply)${NC}`,
     `${GREY}│${NC}    census [path]      ${GREY}# Report tracked file count, extension breakdown, and line totals${NC}`,
     `${GREY}│${NC}    audits [cmd]       ${GREY}# Run every health check as one set (run, list)${NC}`,

package/src/commands/pr.ts

@@ -15,6 +15,8 @@ import {
   compareKeyChanges,
   treeRoots,
 } from '@/pr/bijection'
+import { type CheckRunListing, collapseChecks } from '@/pr/checks'
+import { type HeadRefusal, resolveHead, resolveTip } from '@/pr/head'
 import { KEY_CHANGES } from '@/pr/paths'
 import { intro, logInfo, logStep, logWarn, outro, plural } from '@/ui'
 
@@ -41,6 +43,32 @@ interface KeyChangesOptions {
   readonly json?: boolean
 }
 
+interface ReadOptions {
+  readonly root?: string
+  readonly json?: boolean
+}
+
+/** Why a head-sensitive read produced no answer about a commit. */
+type PullRefusal = 'gh-missing' | 'gh-failed' | 'no-branch' | 'runs-unreadable'
+
+/** What a reader does about each way the two sha-keyed verbs produced nothing. */
+const PULL_REFUSALS: Record<PullRefusal | HeadRefusal, string> = {
+  'gh-missing':
+    'gh is not on the path, so no pull request could be resolved. Name the branch through a checkout that carries one.',
+  'gh-failed':
+    'gh could not answer for this branch. Name the pull request number instead.',
+  'no-branch':
+    'The pull request carries no head branch name, so no ref could be read for it.',
+  'unresolvable-ref':
+    'git could not read the remote, so the branch tip is unknown. That is a failed read rather than an absent branch, so nothing is reported about the head.',
+  'no-remote-branch':
+    'The remote carries no branch by that name. It was deleted or never pushed, so there is no tip to compare against.',
+  'no-object-head':
+    'The pull request object reported no head commit, so there is nothing to compare the tip against.',
+  'runs-unreadable':
+    'The check runs for this commit could not be read. An empty answer here would report a commit as having no check rather than as unread, so nothing is reported.',
+}
+
 /** Why the read produced no comparison, ahead of the ones the compare owns. */
 type SourceRefusal =
   | 'gh-missing'
@@ -139,6 +167,75 @@ export function register(program: Command): void {
     .action(async (number: string | undefined, opts: KeyChangesOptions) => {
       process.exitCode = await runKeyChanges(number, opts)
     })
+
+  pr.command('head')
+    .description(
+      "Compare a pull request's reported head against the branch tip",
+    )
+    .argument('[number]', 'Pull request to read, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        'The pull request object lags the branch ref by up to a minute after a',
+        'push and reports nothing about the lag, so a session reading',
+        '`headRefOid` alone calls a pushed commit unpushed. This resolves the',
+        'tip from the remote with `git ls-remote` and reports which commit each',
+        'source names.',
+        '',
+        'Read the verdict off the record rather than off the exit. A stale head',
+        'exits 0, because an operator shell profile can wrap this binary in a',
+        'function whose status comes from a trailing command.',
+        '',
+        'Exit codes:',
+        '  0  the tip resolved, whether the object agreed with it or not',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr head',
+        '  canon pr head 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: ReadOptions) => {
+      process.exitCode = await runHead(number, opts)
+    })
+
+  pr.command('checks')
+    .description('Report the check runs belonging to the branch tip')
+    .argument('[number]', 'Pull request to read, defaulting to this branch')
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--root <path>', 'Repository to read, defaulting to the cwd')
+    .option('--json', 'Add a machine-readable record on stdout')
+    .addHelpText(
+      'after',
+      [
+        '',
+        '`gh pr checks` cannot be made sha-aware at all: its field set carries no',
+        'sha, so a caller cannot learn which commit its answer describes. This',
+        'resolves the tip from the remote and reads the check runs keyed on it.',
+        '',
+        'Pending is reported for a tip carrying no run yet as well as for one',
+        'still going, since the endpoint has answered with a non-zero count and',
+        'an empty row list, and reading that as passing is the false green the',
+        'sha key alone does not close.',
+        '',
+        'Exit codes:',
+        '  0  the runs for the tip were read, whatever they say',
+        '  1  refused, with the reason on stderr or in the JSON record',
+        '',
+        'Examples:',
+        '  canon pr checks',
+        '  canon pr checks 1341 --json',
+        '',
+      ].join('\n'),
+    )
+    .action(async (number: string | undefined, opts: ReadOptions) => {
+      process.exitCode = await runChecks(number, opts)
+    })
 }
 
 interface PullRequestRead {
@@ -400,20 +497,287 @@ async function runKeyChanges(
   return report.unmet.length === 0 ? 0 : 2
 }
 
+/** The head branch and reported head of the pull request a caller named. */
+interface PullIdentity {
+  readonly number: number | undefined
+  readonly branch: string
+  readonly head?: string
+}
+
+type IdentityRead =
+  | { readonly kind: 'read'; readonly identity: PullIdentity }
+  | { readonly kind: 'refused'; readonly reason: PullRefusal }
+
+/**
+ * Runs one `gh` invocation and hands back its stdout, or null when it failed.
+ *
+ * See src/worktrees/reclaim.ts for why gh needs the stripped environment: it
+ * resolves its repository through the same variables git does and they beat
+ * `cwd`, so a run from inside a hook would answer for another repository.
+ */
+async function gh(
+  cwd: string,
+  args: readonly string[],
+): Promise<string | null> {
+  try {
+    const result = await execa('gh', [...args], {
+      cwd,
+      timeout: GH_TIMEOUT_MS,
+      env: gitEnv(),
+      extendEnv: false,
+    })
+    return result.stdout
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Reads the head branch and the head the pull request object reports.
+ *
+ * Both come from one call, so the branch a ref is read for and the head that
+ * ref is compared against describe the same object.
+ */
+async function readIdentity(
+  cwd: string,
+  number: string | undefined,
+): Promise<IdentityRead> {
+  if (Bun.which('gh') === null) {
+    return { kind: 'refused', reason: 'gh-missing' }
+  }
+
+  const args = ['pr', 'view']
+  if (number !== undefined) args.push(number)
+  args.push('--json', 'number,headRefName,headRefOid')
+
+  const stdout = await gh(cwd, args)
+  if (stdout === null) return { kind: 'refused', reason: 'gh-failed' }
+
+  let row: { number?: number; headRefName?: string; headRefOid?: string }
+  try {
+    row = JSON.parse(stdout)
+  } catch {
+    return { kind: 'refused', reason: 'gh-failed' }
+  }
+
+  if (row.headRefName === undefined || row.headRefName === '') {
+    return { kind: 'refused', reason: 'no-branch' }
+  }
+
+  return {
+    kind: 'read',
+    identity: {
+      number: row.number,
+      branch: row.headRefName,
+      ...(row.headRefOid !== undefined && { head: row.headRefOid }),
+    },
+  }
+}
+
+/**
+ * Reads the branch tip from the remote rather than from a tracking ref.
+ *
+ * A tracking ref is only as current as the last fetch, and the push this is
+ * meant to catch is one this process never saw.
+ */
+function refReader(root: string) {
+  return async (branch: string): Promise<string | null> => {
+    const result = await $`git -C ${root} ls-remote --heads origin ${branch}`
+      .env(gitEnv())
+      .quiet()
+      .nothrow()
+    return result.exitCode === 0 ? result.text() : null
+  }
+}
+
+async function runHead(
+  number: string | undefined,
+  opts: ReadOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr head')
+
+  const read = await readIdentity(root, number)
+  if (read.kind === 'refused') {
+    return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
+  }
+
+  const { identity } = read
+  const reading = await resolveHead(
+    identity.branch,
+    identity.head,
+    refReader(root),
+  )
+
+  if (reading.kind === 'refused') {
+    return refuseWith(
+      reading.reason,
+      PULL_REFUSALS[reading.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  logStep('Scope')
+  logInfo(
+    `${identity.number === undefined ? 'the pull request on' : `#${identity.number} on`} ${reading.branch}`,
+  )
+
+  logStep(reading.state === 'fresh' ? 'Fresh' : 'Stale')
+  if (reading.state === 'fresh') {
+    logInfo(
+      `the object and the remote both name ${reading.tip.slice(0, 8)}, so a read keyed on either describes the same commit`,
+    )
+  } else {
+    logWarn(
+      `the remote carries ${reading.tip.slice(0, 8)} and the pull request object still reports ${reading.object.slice(0, 8)}. Key every head-sensitive read on the tip.`,
+    )
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(identity.number !== undefined && { number: identity.number }),
+        branch: reading.branch,
+        state: reading.state,
+        tip: reading.tip,
+        object: reading.object,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
+async function runChecks(
+  number: string | undefined,
+  opts: ReadOptions,
+): Promise<number> {
+  const root = resolve(opts.root ?? process.cwd())
+  const emitJson = opts.json ?? false
+
+  intro('canon pr checks')
+
+  const read = await readIdentity(root, number)
+  if (read.kind === 'refused') {
+    return refuseWith(read.reason, PULL_REFUSALS[read.reason], emitJson, root)
+  }
+
+  const { identity } = read
+  const resolved = await resolveTip(identity.branch, refReader(root))
+  if (resolved.kind === 'refused') {
+    return refuseWith(
+      resolved.reason,
+      PULL_REFUSALS[resolved.reason],
+      emitJson,
+      root,
+    )
+  }
+
+  // The page size is raised rather than paged through. `collapseChecks` reads
+  // a count above the rows it was handed as pending, so a commit past the
+  // ceiling reports unread rather than clean, and 100 is the endpoint's own
+  // maximum against a default of 30.
+  const listed = await gh(root, [
+    'api',
+    `repos/{owner}/{repo}/commits/${resolved.tip}/check-runs?per_page=100`,
+  ])
+  if (listed === null) {
+    return refuseWith(
+      'runs-unreadable',
+      PULL_REFUSALS['runs-unreadable'],
+      emitJson,
+      root,
+    )
+  }
+
+  let listing: CheckRunListing
+  try {
+    listing = JSON.parse(listed)
+  } catch {
+    return refuseWith(
+      'runs-unreadable',
+      PULL_REFUSALS['runs-unreadable'],
+      emitJson,
+      root,
+    )
+  }
+
+  const reading = collapseChecks(resolved.tip, listing)
+
+  logStep('Scope')
+  logInfo(
+    `${identity.branch} at ${reading.tip.slice(0, 8)}, ${plural(reading.matched, 'run')} belonging to it`,
+  )
+  // Named rather than folded into the count above, since a listing carrying a
+  // run for another commit is what makes the verdict pending on its own.
+  if (reading.foreign > 0) {
+    logWarn(
+      `${plural(reading.foreign, 'further run')} belonging to another commit, so this listing does not describe the tip alone.`,
+    )
+  }
+
+  logStep(
+    reading.state === 'passing'
+      ? 'Passing'
+      : reading.state === 'failing'
+        ? 'Failing'
+        : 'Pending',
+  )
+  if (reading.state === 'passing') {
+    logInfo('every run on the tip completed and none failed')
+  } else if (reading.state === 'failing') {
+    logWarn('a run on the tip failed, which no run still going can clear')
+  } else if (reading.matched === 0) {
+    logInfo(
+      `no run belongs to the tip yet${reading.reported > 0 ? `, against a reported count of ${reading.reported}` : ''}. That is unread rather than clean.`,
+    )
+  } else {
+    logInfo('a run on the tip has yet to conclude')
+  }
+
+  outro()
+
+  if (emitJson) {
+    process.stdout.write(
+      `${JSON.stringify({
+        root,
+        ...(identity.number !== undefined && { number: identity.number }),
+        branch: identity.branch,
+        ...reading,
+      })}\n`,
+    )
+  }
+
+  return 0
+}
+
 /**
  * Frames a refusal on stderr in both modes and puts the record on stdout alone,
  * so an operator reading the terminal sees the reason rather than a command
  * that appeared to do nothing.
  */
 function refuse(reason: Refusal, emitJson: boolean, root: string): number {
+  return refuseWith(reason, REFUSALS[reason], emitJson, root)
+}
+
+function refuseWith(
+  reason: string,
+  message: string,
+  emitJson: boolean,
+  root: string,
+): number {
   logStep('Refused')
-  logWarn(REFUSALS[reason])
+  logWarn(message)
   outro()
 
   if (emitJson) {
-    process.stdout.write(
-      `${JSON.stringify({ root, reason, message: REFUSALS[reason] })}\n`,
-    )
+    process.stdout.write(`${JSON.stringify({ root, reason, message })}\n`)
   }
   return 1
 }

package/src/pr/checks.ts

@@ -0,0 +1,83 @@
+import { type ChecksState, type RawCheck, rollup } from '@/targets/pulls'
+
+/** One row of `repos/{owner}/{repo}/commits/<sha>/check-runs`. */
+export interface RawCheckRun {
+  readonly head_sha?: string
+  readonly status?: string
+  readonly conclusion?: string | null
+}
+
+/** What that endpoint returns, count and rows apart. */
+export interface CheckRunListing {
+  readonly total_count?: number
+  readonly check_runs?: readonly RawCheckRun[]
+}
+
+export interface ChecksReading {
+  readonly state: ChecksState
+  /** The commit the answer describes. */
+  readonly tip: string
+  /** Runs the listing carried for the tip. */
+  readonly matched: number
+  /** Runs the listing carried for some other commit. */
+  readonly foreign: number
+  /** What the endpoint said it holds, which can exceed the rows it returned. */
+  readonly reported: number
+}
+
+/**
+ * Puts a check-run row into the shape `rollup` reads.
+ *
+ * REST spells its statuses lowercase and `rollup` reads the GraphQL enum the
+ * pull request listing returns, so the vocabulary is converted at this boundary
+ * rather than teaching that function a second one. A null conclusion becomes an
+ * absent one, since `rollup` reads absence as a run that has not concluded.
+ */
+function adapt(run: RawCheckRun): RawCheck {
+  return {
+    ...(run.status !== undefined && { status: run.status.toUpperCase() }),
+    ...(run.conclusion !== undefined &&
+      run.conclusion !== null && {
+        conclusion: run.conclusion.toUpperCase(),
+      }),
+  }
+}
+
+/**
+ * Collapses a check-run listing to one word about one commit.
+ *
+ * Keying the query on a sha is necessary and not sufficient. The endpoint
+ * returned `total_count` 2 with an empty row list during a measured window on
+ * 2026-09-02, so a reader that finds no run for the tip and reports `passing`
+ * reproduces the false green behind a better query. Both that case and a
+ * listing carrying a run for another commit report `pending` instead.
+ *
+ * The foreign test runs ahead of the collapse rather than after it. A listing
+ * that describes another commit says nothing about this one, so answering off
+ * the matching half would report a verdict on a set known to be incomplete.
+ */
+export function collapseChecks(
+  tip: string,
+  listing: CheckRunListing,
+): ChecksReading {
+  const runs = listing.check_runs ?? []
+  const matched = runs.filter((run) => run.head_sha === tip)
+  const reading = {
+    tip,
+    matched: matched.length,
+    foreign: runs.length - matched.length,
+    reported: listing.total_count ?? runs.length,
+  }
+
+  if (reading.foreign > 0) return { ...reading, state: 'pending' }
+
+  // A count above the rows returned is a listing this reader holds only part
+  // of, whether the endpoint paged or answered inconsistently. Collapsing the
+  // part in hand would report `passing` off a set a failing run can still be
+  // sitting outside of, which is the false green keyed on a sha alone.
+  if (reading.reported > runs.length) return { ...reading, state: 'pending' }
+
+  if (matched.length === 0) return { ...reading, state: 'pending' }
+
+  return { ...reading, state: rollup(matched.map(adapt)) ?? 'pending' }
+}

package/src/pr/head.ts

@@ -0,0 +1,108 @@
+/** Whether the pull request object's head still names the branch tip. */
+export type HeadState = 'fresh' | 'stale'
+
+/** Why the tip could not be resolved from the remote. */
+export type TipRefusal = 'unresolvable-ref' | 'no-remote-branch'
+
+/** Why the comparison produced no reading, adding the object's own half. */
+export type HeadRefusal = TipRefusal | 'no-object-head'
+
+export type TipReading =
+  | { readonly kind: 'read'; readonly tip: string }
+  | { readonly kind: 'refused'; readonly reason: TipRefusal }
+
+export type HeadReading =
+  | {
+      readonly kind: 'read'
+      readonly state: HeadState
+      readonly branch: string
+      readonly tip: string
+      readonly object: string
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: HeadRefusal
+      readonly branch: string
+    }
+
+/**
+ * Hands back the stdout of `git ls-remote --heads origin <branch>`, or null
+ * when the command failed.
+ *
+ * Injected rather than called here, so the disagreement this module exists to
+ * report is a fixture rather than a live push nobody can stage in a test.
+ */
+export type RefReader = (branch: string) => Promise<string | null>
+
+/**
+ * The sha `git ls-remote` reported for exactly this branch.
+ *
+ * Matched on the whole ref rather than on a suffix, because the command takes
+ * its argument as a pattern: `--heads origin x` also returns `refs/heads/feat/x`,
+ * and reading the first line back would answer about another branch entirely.
+ */
+function findRef(stdout: string, branch: string): string | undefined {
+  for (const line of stdout.split('\n')) {
+    const [sha, ref] = line.trim().split(/\s+/)
+    if (sha !== undefined && ref === `refs/heads/${branch}`) return sha
+  }
+  return undefined
+}
+
+/**
+ * Resolves a branch tip from the remote itself.
+ *
+ * The remote rather than the remote-tracking ref, since a tracking ref is only
+ * as current as the last fetch and the whole point here is answering about a
+ * push this process never saw. It costs a round trip, measured at 0.410s
+ * against 0.001s for the local read.
+ *
+ * A read that failed and a branch the remote does not carry are separated
+ * rather than collapsed. Reading the first as the second would report a
+ * network refusal as a deleted branch, which is a different repair.
+ */
+export async function resolveTip(
+  branch: string,
+  read: RefReader,
+): Promise<TipReading> {
+  const stdout = await read(branch)
+  if (stdout === null) return { kind: 'refused', reason: 'unresolvable-ref' }
+
+  const tip = findRef(stdout, branch)
+  if (tip === undefined) return { kind: 'refused', reason: 'no-remote-branch' }
+
+  return { kind: 'read', tip }
+}
+
+/**
+ * Compares the head a pull request object reports against the branch tip.
+ *
+ * `gh pr view --json headRefOid` answers from the pull request object, which
+ * lags the branch ref by up to a minute after a push and reports nothing about
+ * the lag. A session that trusts it calls a pushed commit unpushed and fires a
+ * green claim against a commit CI never saw, both of which happened on
+ * 2026-09-01. The tip is the authority and the object's head is the claim being
+ * checked against it.
+ */
+export async function resolveHead(
+  branch: string,
+  objectHead: string | undefined,
+  read: RefReader,
+): Promise<HeadReading> {
+  const resolved = await resolveTip(branch, read)
+  if (resolved.kind === 'refused') {
+    return { kind: 'refused', reason: resolved.reason, branch }
+  }
+
+  if (objectHead === undefined || objectHead === '') {
+    return { kind: 'refused', reason: 'no-object-head', branch }
+  }
+
+  return {
+    kind: 'read',
+    state: resolved.tip === objectHead ? 'fresh' : 'stale',
+    branch,
+    tip: resolved.tip,
+    object: objectHead,
+  }
+}

package/src/targets/pulls.ts

@@ -87,7 +87,13 @@ interface RawPull {
   readonly statusCheckRollup?: readonly RawCheck[]
 }
 
-interface RawCheck {
+/**
+ * One check as the pull request listing spells it, in the GraphQL enum.
+ *
+ * Exported because `src/pr/checks.ts` adapts the REST check-run row onto it
+ * rather than writing a second collapse beside `rollup`.
+ */
+export interface RawCheck {
   readonly status?: string
   readonly conclusion?: string
   readonly state?: string