pr:review over REST only, with --once for cloud sessions

[thejackshelton]

Cloud sessions reach GitHub through a proxy that allows REST only. pnpm pr:review used GraphQL (gh repo view --json, gh pr view --json three times), so it failed there. This PR ports it to REST and adds a single-poll mode. land.ts, land-lib.ts and merge-train*.ts are untouched; their call sites get ported in a later PR (#220 and #222 are changing land.ts).

What changed

• scripts/gh-rest.ts (new): typed helpers over gh api, REST only. The repo comes from GH_REPO ([HOST/]OWNER/REPO) or from the origin remote URL (https, ssh, scp-style, or a proxy URL ending in /owner/repo). Helpers: repo, prView (state OPEN/CLOSED/MERGED, head sha and ref, base, mergeable, labels, body, draft, fork), prFiles, prCommits, prList(base?), prForBranch, prCreate, addLabels, removeLabel, issueComment, prSetBase, prMerge(pr, sha) (PUT pulls/<n>/merge with the sha guard, so GitHub refuses a moved head), checkRuns(sha), prComments, and reviewComments. All list endpoints use --paginate --slurp.
  • Mergeable mapping: mergeable_state: "dirty" or mergeable: false maps to CONFLICTING, mergeable: null to UNKNOWN, and anything else to MERGEABLE. On 12 live PRs it matched gh pr view --json mergeable: 216, 214, 210, 208, 206, 203 and 200 are CONFLICTING; 218, 212, 198, 196 (unstable) and 194 are MERGEABLE.
  • Validation: every answer is validated, and an unexpected shape throws with the field's name (for example gh-rest: unexpected pull.head.sha).
  • Retries: reads retry transient failures 5 times, the same as the old gh() wrapper. Writes never retry, since a retried POST could post twice. A malformed answer is never retried.
• scripts/pr-review.ts: every gh call now goes through gh-rest. The no-argument form finds the current branch's PR with pulls?head=owner:branch, taking the open one or else the newest. The verdict logic is unchanged and still comes entirely from pr-review-vouch.ts: CI wait, Macroscope review of the latest commit, vouched skips, UNREVIEWED, unanswered findings, --conflicts-ok, and exit codes.
  • New --once flag: polls a single time and exits 0 if clean, 1 if not clean, or 2 if pending. Pending means not settled(), the point where --wait would poll again. A cloud session can loop on it within its 30-minute command limit. --once and --wait together is an error.
  • One clock: the settled test and the verdict now read the same now, so --once can never print a clean verdict and also exit 2.
• scripts/pr-review-vouch.ts: adds onceExit, plus the UNKNOWN and IGNORED handling described in round 2. parsePrHead, parsePrCommits and parseCrossRepository stay because land.ts and merge-train.ts use them.

Round 2: an UNKNOWN mergeability is pending (Claude review, Medium)

This bug predates this PR. While GitHub is still computing mergeability (REST mergeable: null, GraphQL UNKNOWN), settled() and outcome() treated it as clean, so pr:review could exit 0 on a conflicting PR.

• Fix: an UNKNOWN mergeability without --conflicts-ok is now pending. settled() is false, so --wait polls again and --once exits 2. outcome() lists mergeability of <sha> (GitHub has not computed it yet) under "Still running", so a single poll exits 1. A failed check still ends the wait.
• --conflicts-ok stays separate: judgedHead now marks the head IGNORED rather than reusing UNKNOWN. That covers CONFLICTING or UNKNOWN under --conflicts-ok, and any PR that is no longer open, because GitHub reports null for every merged PR. IGNORED is judged on the checks alone. Merged PRs keep their exit 0, and land.ts's --wait --conflicts-ok admission behaves as before.
• Seen live (2026-10-08): master moved to 3099f7b while I was running the matrix. origin/master's pr:review exited 0 on GRID G1a engine: grid.ts (Blink 145 grid layout) and the G-P differential test against the Chrome grid corpus #212, PNT1-effects 1/2: opacity as a native group alpha and z-index with Appendix E stacking (supersedes the opacity and stacking parts of #84-#85) #196, MQ-R1 runtime: @media bands switched on resize and rotation on iOS/Android (device-env lane, resize step scripts) #214 and CASC 2: @property decided at build time as Chrome 145 registers it (initial values, inherits, invalid at computed-value time) #216. Seconds later, this branch exited 1 on each: CONFLICTING for GRID G1a engine: grid.ts (Blink 145 grid layout) and the G-P differential test against the Chrome grid corpus #212 and PNT1-effects 1/2: opacity as a native group alpha and z-index with Appendix E stacking (supersedes the opacity and stacking parts of #84-#85) #196, and "Still running: mergeability of …" for MQ-R1 runtime: @media bands switched on resize and rotation on iOS/Android (device-env lane, resize step scripts) #214 and CASC 2: @property decided at build time as Chrome 145 registers it (initial values, inherits, invalid at computed-value time) #216. REST then reported all four mergeable: false, mergeable_state: dirty. Once GitHub had recomputed, old and new matched (table below).
• Lows folded in:
  • parsePull throws pull.mergeable (missing) when the field is absent. List endpoints and write answers use parsePullSummary, which has no mergeable field.
  • GH_REPO with a host other than github.com is refused, since every call goes to github.com.
  • The grep test builds both patterns from one subcommand list, which now includes label.
  • With no PR number, pr:review uses only an open PR for the current branch. It refuses if there is none ("pass the PR number") or if there is more than one; it never falls back to a closed or merged PR.

Equivalence on real PRs (read-only, head 8a353d9)

The old script is origin/master's scripts/pr-review.ts, run from the main checkout with its own pr-review-vouch.ts (unchanged on origin/master). Both ran back to back without --wait, then the new one ran again with --once. "Output" compares stdout and stderr byte for byte.

PR (args)	state	old exit	new exit	new --once	output	findings	verdict lines (new)
215	merged	0	0	0	identical	0	UNREVIEWED
213	merged	0	0	0	identical	0	UNREVIEWED
2	merged, reviewed clean	0	0	0	identical	0	–
219	open, clean	0	0	0	identical	0	UNREVIEWED
221	open, clean	0	0	0	identical	0	UNREVIEWED
222	open, clean	0	0	0	identical	0	UNREVIEWED
214 --conflicts-ok	conflicting, ignored	0	0	0	identical	0	UNREVIEWED
216 --conflicts-ok	conflicting, ignored	0	0	0	identical	0	UNREVIEWED
30	findings, no CI run	1	1	2	identical	2	Still running: Correctness; Failed: no CI run
25	"Diff unchanged" skip (vouch path)	1	1	1	identical	0	Failed: Correctness (not vouched: empty diff)
29	"No code objects reviewed" skip (vouch path, fork check)	1	1	1	identical	0	Failed: Correctness
31	correctness never started	1	1	2	identical	0	Still running: Correctness
1	no CI run	1	1	2	identical	0	Failed: no CI run
212, 196, 214, 216, first run just after master moved	open, dirty	0	1	1	differs (the bug above)	0	CONFLICTING, or Still running: mergeability
212, 196, 214, 216, 30 s later	open, dirty	1	1	1	identical	0	Failed: PR head … is CONFLICTING

PRs 30, 31 and 1 report pending under --once because settled() is false there: CI or the correctness check is still missing. --wait keeps polling in exactly those states.

With no PR number, both versions resolved #224 from the branch. The new script also ran over every PR from 1 to 212 (round 1) with no errors.

Tests

• New packages/parity/test/gh-rest.test.ts:
  • remote URL parsing (https, ssh, scp, proxy, and malformed URLs) and GH_REPO precedence
  • mergeable mapping
  • pull shape validation naming each field
  • multi-page flattening for comments, check runs, files, PR lists and commits
  • branch lookup
  • reads retry but malformed answers and writes do not
  • write payloads go as JSON on stdin
  • the merge sha guard and a refused merge
  • PR-number checks
• packages/parity/test/pr-review.test.ts: the judgedHead test now expects IGNORED instead of UNKNOWN; that was the requested change. New tests cover UNKNOWN as pending (settled false, exit 1, --once 2, a failure still ends the wait) and IGNORED from --conflicts-ok or a closed PR passing on the checks alone. It also adds "pr-review over REST", using the existing run() and HEAD fakes and a fake gh that serves REST JSON with no network. It covers clean, an unanswered finding, an answered finding, pending (exit 1, --once 2), dirty with and without --conflicts-ok, UNREVIEWED, and malformed REST answers. It also adds a grep test that fails if pr-review.ts or gh-rest.ts names a GraphQL-using gh subcommand ('pr', 'view'-style argument pairs, gh pr … text) or "graphql". This test fails on origin/master's pr-review.ts.

No existing test, tolerance or check was changed or removed.

What passed

• pnpm typecheck
• pnpm exec vitest run on these test files, plus land and merge-train, 232 tests:
  • packages/parity/test/pr-review.test.ts
  • packages/parity/test/gh-rest.test.ts
  • packages/parity/test/chrome-ports.test.ts
  • packages/parity/test/registry-claims.test.ts
  • packages/dragon/test/registry-claims.test.ts
  • packages/parity/test/land.test.ts
  • packages/parity/test/merge-train.test.ts

This PR was itself opened with ghRest().prCreate (POST repos/…/pulls).

🤖 Generated with Claude Code