@joshuafolkken/kit 1.872.0

package/scripts/git/git-gh-issue.ts

@@ -0,0 +1,161 @@
+import { git_gh_issue_list, type IssueListOutcome } from './git-gh-issue-list'
+import { git_gh_issue_read } from './git-gh-issue-read'
+import { BLOCKED_BY_COUNT_FIELD } from './git-gh-issue-rest'
+import { git_gh_issue_write } from './git-gh-issue-write'
+
+const NUMBER_AND_BODY_FIELDS = 'number,body'
+// The backlog scan's fields. The title rides along because the pre-filing scan compares titles
+// (joshuafolkken/kit#1252) and it costs nothing: the same listing request already carries it, so the
+// two consumers share one read rather than each making their own.
+//
+// `blocked_by_count` rides along for the same reason and is the one field here that `gh --json`
+// never had: it is read out of the `issue_dependencies_summary` the listing response already
+// carries, so it costs no request at all (joshuafolkken/kit#1736). It is what lets `epic:bundle`
+// tell a row with no blockers from one with some **before** deciding whether that row is worth a
+// per-issue read — the read it used to make for every open issue in the repository. Absent on a row
+// whose summary is missing, which must not be read as zero; `git-gh-issue-rest.ts` states why.
+const BACKLOG_SCAN_FIELDS = `number,title,body,${BLOCKED_BY_COUNT_FIELD}`
+// The recently-closed scan's fields (joshuafolkken/kit#1679). It compares titles like the scan above
+// and never reads a body, and it needs the labels to tell an epic from a deliverable — the open half
+// gets that from the epic listing, which by construction holds no closed epic.
+const NUMBER_TITLE_AND_LABELS_FIELDS = 'number,title,labels'
+// The fields every listing that is *ranked* asks for: `createdAt` to order by and `labels` to
+// exclude by. Shared by the next-issues display and the `auto-ok` pickup, which rank identically.
+const SUMMARY_FIELDS = 'number,title,labels,createdAt'
+// The pickup's list, which is the display's plus the native blocker relation. Kept apart from
+// `SUMMARY_FIELDS` on purpose: a listing carries no `blockedBy`, so the field is answered from each
+// row's own dependencies endpoint, and asking for it on the shared list would put that request
+// behind the next-issues display too — where a refused one becomes a failure with no message at all,
+// since the listing swallows the error (joshuafolkken/kit#996, joshuafolkken/kit#1025).
+const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy`
+
+// Every listing below goes through the one REST invocation in `git-gh-issue-list.ts`. It kept the
+// `json_fields` / `limit` contract it had as a `gh issue list` wrapper, so these callers changed
+// only where a `gh` flag became a query parameter (joshuafolkken/kit#1025).
+//
+// **They all answer `IssueListOutcome`, not the JSON alone** (joshuafolkken/kit#1067). The page
+// ceiling now bounds every one of them, and a bound whose caller cannot see it was reached is a
+// silently shortened answer — so the flag rides out to the caller and the caller decides. The
+// disposition each one settled on, and why:
+//
+// | Caller | Truncation is | Why |
+// | --- | --- | --- |
+// | `issue_list_recent` | **ignorable** | The display shows the five newest of the twenty it asks for, and the paging is newest-first — so a truncated read is a *prefix* of the untruncated one and the five rows are the same five. Nothing is hidden that this display would have shown. |
+// | `issue_list_open_bodies` | **warning** | `epic:bundle` scanned what it scanned; a related issue past the cut is missed, which is what its existing `⚠ … cap` line already says. The scan ran, so it is something to read rather than a check that did not happen. |
+// | `issue_search_body` | **warning** | Unchanged from joshuafolkken/kit#1033 — the orphan search ran over the newest issues, and an orphan is normally an issue filed minutes ago. |
+// | `issue_list_by_label` | **warning** | Both consumers report it: `epic:bundle`'s epic listing, where an epic past the cut has its child recommended a second epic, and the auto-close, where an epic past the cut is never checked for completion. Neither may fail — the auto-close runs after the merge — so both print and continue. |
+// | `issue_list_by_label_summary` | **warning** | The `auto-ok` pickup already says the cap dropped the *oldest* opted-in issues; the ceiling drops the same ones. The answer it gives is still opted in, just possibly not the highest-priority one. |
+// | `issue_list_recently_closed` | **warning** | `issue:scout` widens its duplicate scan over what closed recently; a closed issue past the cut is one candidate the reader is not shown, exactly as on the open half. The scan ran, so it is reported beside the open one rather than failing the command. |
+// | `issue_list_by_label_in_repo` | **error** | `epic:busy` asks whether a repository already has work running in it, and it is the only one whose answer *authorizes an action*. A truncated listing with no visible holder is not "nothing is running", and reading it as one starts a second run in the same checkout — the direction joshuafolkken/kit#925 closed. It lands with the unreadable listing, on `wait`. It is also the only caller that reports the page ceiling **without** the `limit` cap beside it; `epic-busy.ts` records why a full page of parked issues must not latch the guard. |
+//
+// The split is joshuafolkken/kit#1033's, applied caller by caller rather than copied: truncation is
+// a warning where the scan *ran* and an error where the answer it produced would authorize an
+// action. Only `epic:busy` authorizes one.
+const { issue_list } = git_gh_issue_list
+
+// The newest open issues, for the next-issues display at workflow completion (#821). `createdAt`
+// rides along because the caller re-sorts explicitly rather than inheriting the listing's order.
+async function issue_list_recent(limit: number): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: SUMMARY_FIELDS, limit })
+}
+
+// Every open issue with its title and body. Used by `epic:bundle` to scan the backlog and by
+// `issue:scout` to compare titles before one is filed; a search with an empty term is not a listing,
+// and asking `gh` for one produced a partial and arbitrary answer (joshuafolkken/kit#873).
+async function issue_list_open_bodies(limit: number): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: BACKLOG_SCAN_FIELDS, limit })
+}
+
+// The issues that closed most recently, for the duplicate half of `issue:scout`
+// (joshuafolkken/kit#1679). **The work most likely to be filed twice is the work that just
+// finished** — joshuafolkken/kit#1656 was filed about five hours after joshuafolkken/kit#1623 closed
+// having already done it — and a scan that reads only open issues cannot see any of it.
+//
+// `sort=updated` rather than `created`: the question is what closed recently, and a listing ordered
+// by filing date puts a five-year-old issue closed this morning behind whatever was filed yesterday.
+// GitHub has no `sort=closed`, and `updated` moves on the close, so the newest-updated closed issues
+// are the recently-closed ones with at most a few edited-since rows riding along — which cost a line
+// in the candidate list and nothing else.
+//
+// **`labels` rather than `body`**, which is the one field list here that differs from the open scan's.
+// The duplicate half compares titles and never reads a body, and the epic exclusion the open half
+// gets for free — `epic_bundle_cli` marks a row from the *open* epic listing — cannot reach a closed
+// row at all. Without the labels a closed epic would be offered as a duplicate of a deliverable, and
+// under the new exit that reads as "this work is already done" against a container that never had an
+// implementation of its own.
+async function issue_list_recently_closed(limit: number): Promise<IssueListOutcome> {
+	return await issue_list({
+		json_fields: NUMBER_TITLE_AND_LABELS_FIELDS,
+		limit,
+		state: 'closed',
+		sort: 'updated',
+	})
+}
+
+// Open issues whose body mentions `term`. Used by `epic:audit` to find an issue that names an epic
+// as its parent while the epic's task list does not track it (joshuafolkken/kit#870).
+//
+// The one listing here whose filter runs client-side, and so the one that reaches the page ceiling
+// on an ordinary repository: its matches are normally zero, so "stop once `limit` rows are selected"
+// never fires for it (joshuafolkken/kit#1033).
+async function issue_search_body(term: string, limit: number): Promise<IssueListOutcome> {
+	return await issue_list({
+		json_fields: NUMBER_AND_BODY_FIELDS,
+		limit,
+		body_term: term,
+	})
+}
+
+async function issue_list_by_label(label: string, limit: number): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: NUMBER_AND_BODY_FIELDS, limit, label })
+}
+
+// The same filter with the fields the `auto-ok` pickup needs (joshuafolkken/kit#906): it orders by
+// `createdAt` and re-checks `labels` client-side, so bodies would be fetched and thrown away. A
+// label that does not exist in the repository is not an error — the listing comes back empty, which
+// is exactly "nobody has opted anything in".
+// `json_fields` overrides the pickup's list. Its only caller is the probe that runs *after* a failed
+// read, asking the same question without `blockedBy` so a refused dependencies endpoint is told
+// apart from an access failure (joshuafolkken/kit#1005).
+async function issue_list_by_label_summary(
+	label: string,
+	limit: number,
+	options?: { json_fields?: string },
+): Promise<IssueListOutcome> {
+	return await issue_list({
+		json_fields: options?.json_fields ?? PICKUP_FIELDS,
+		limit,
+		label,
+	})
+}
+
+// Open issues carrying `label` in one named repository — the read `epic:next` makes before it
+// offers a child, to see whether that repository already has one running (joshuafolkken/kit#925).
+//
+// `SUMMARY_FIELDS` rather than `PICKUP_FIELDS`: the answer is only "which issues hold this
+// repository", and asking for `blockedBy` would put a dependencies request behind the guard — where
+// a refused one fails the whole listing, which this caller must never read as "nothing is running".
+//
+// `repo` names the repository inside the REST path (`git-gh-api-path.ts`). Omitted, the listing is
+// the repository the command runs in, exactly as every other listing here.
+async function issue_list_by_label_in_repo(
+	label: string,
+	limit: number,
+	repo?: string,
+): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: SUMMARY_FIELDS, limit, label, repo })
+}
+
+const git_gh_issue = {
+	...git_gh_issue_read,
+	...git_gh_issue_write,
+	issue_list_recent,
+	issue_list_by_label,
+	issue_list_by_label_in_repo,
+	issue_list_by_label_summary,
+	issue_search_body,
+	issue_list_open_bodies,
+	issue_list_recently_closed,
+}
+
+export { git_gh_issue, PICKUP_FIELDS, SUMMARY_FIELDS }

package/scripts/git/git-gh-pr-auto-merge.ts

@@ -0,0 +1,85 @@
+import { git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+import { read_pull, require_pr_number } from './git-gh-pr-read'
+import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
+
+// Auto-merge for a pull request a josh command opens and would otherwise have to stay alive to land
+// (joshuafolkken/kit#2497). `pnpm josh observations:flush` used to merge its pull request only from
+// inside its own wait, so a wait that ended early — a session cut, a killed process — left a green
+// pull request open with nobody to merge it.
+//
+// **This is the one GraphQL request in the pull-request layer, because REST has no equivalent.**
+// Enabling auto-merge is `enablePullRequestAutoMerge` and nothing else. A cloud session can be
+// answered 403 for GraphQL (joshuafolkken/kit#1022), so the caller treats a failure here as a lost
+// safety net rather than a failed command — the in-process wait still merges as it always did.
+
+const GRAPHQL_PATH = 'graphql'
+const OPEN_PULLS_QUERY = `${git_gh_api_path.FULL_PAGE_QUERY}&state=open`
+const MISSING_NODE_ID_MESSAGE = 'gh api answered a pull request without a node_id'
+const ENABLE_AUTO_MERGE_MUTATION =
+	'mutation($id: ID!) { enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: MERGE }) { clientMutationId } }'
+
+interface OpenPull {
+	number: number
+	head_ref: string
+	has_auto_merge: boolean
+}
+
+async function pr_enable_auto_merge(branch_name: string): Promise<void> {
+	const pull = await read_pull(await require_pr_number(branch_name))
+	if (pull.node_id === undefined) throw new Error(MISSING_NODE_ID_MESSAGE)
+
+	await git_gh_exec.exec_gh_api({
+		path: GRAPHQL_PATH,
+		body: JSON.stringify({ query: ENABLE_AUTO_MERGE_MUTATION, variables: { id: pull.node_id } }),
+	})
+}
+
+// **A read that failed answers "not yet" rather than throwing**, because the caller polls it: the
+// next attempt asks again, and running out of attempts is what ends the wait.
+async function pr_is_merged(branch_name: string): Promise<boolean> {
+	try {
+		return git_gh_pr_rest.is_merged(await read_pull(await require_pr_number(branch_name)))
+	} catch {
+		return false
+	}
+}
+
+function head_reference_of(pull: RestPull): string {
+	return pull.head?.ref ?? ''
+}
+
+function has_head_prefix(pull: RestPull, prefix: string): boolean {
+	return git_gh_pr_rest.is_same_repository_head(pull) && head_reference_of(pull).startsWith(prefix)
+}
+
+// The listing carries `auto_merge`, so no detail read is needed; whether the checks still let it land
+// is the merge gate's question (`git_pr_checks.read_merge_progress`), asked by the caller.
+function to_open_pull(pull: RestPull): OpenPull {
+	return {
+		number: pull.number,
+		head_ref: head_reference_of(pull),
+		has_auto_merge: pull.auto_merge !== null && pull.auto_merge !== undefined,
+	}
+}
+
+async function pr_list_open_with_head_prefix(prefix: string): Promise<ReadonlyArray<OpenPull>> {
+	const json = await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.pulls_api_path()}${OPEN_PULLS_QUERY}`,
+		should_paginate: true,
+	})
+
+	return git_gh_pr_rest
+		.parse_rest_pulls(json)
+		.filter((pull) => has_head_prefix(pull, prefix))
+		.map((pull) => to_open_pull(pull))
+}
+
+const git_gh_pr_auto_merge = {
+	pr_enable_auto_merge,
+	pr_is_merged,
+	pr_list_open_with_head_prefix,
+}
+
+export type { OpenPull }
+export { git_gh_pr_auto_merge, ENABLE_AUTO_MERGE_MUTATION }

package/scripts/git/git-gh-pr-read.ts

@@ -0,0 +1,322 @@
+import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+import { git_gh_helpers } from './git-gh-helpers'
+import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
+
+// Reading pull requests through REST, in the answers `gh pr view` used to give.
+//
+// `gh pr view` goes through GraphQL, which a cloud session is answered 403 for (joshuafolkken/kit#1022).
+// The reads move to `gh api`, and every caller downstream keeps the contract it already reads — the
+// empty string from `pr_view`, `undefined` from the two comment readers. `pr_exists` is the one
+// exception, and it is deliberate: it gates a **write**, so a lookup that failed cannot answer
+// `false` there (joshuafolkken/kit#1043).
+//
+// One thing has no counterpart in REST: `gh pr view` accepted a **branch name** and every REST
+// endpoint is keyed by **number**. The resolution below is the single place that bridges the two
+// (joshuafolkken/kit#1027).
+
+// The branch → number resolution, remembered for the life of the process.
+//
+// Without it the conversion would turn one request into two at six call sites: a `josh git` run
+// alone asks `pr_exists`, `pr_view` and `pr_get_url` about the same branch, and `josh followup` adds
+// `pr_get_body` and both comment readers. A pull request's number never changes, so the memo is
+// sound for every one of them — with one exception, which is why `forget_pr_numbers` exists:
+// `git-pr.ts` opens a *second* pull request on a branch whose first one merged, and a cached number
+// would then keep answering with the merged one. `pr_create` clears it.
+//
+// **Only a resolved number is remembered.** A branch with no pull request is re-resolved every time,
+// which is exactly the case `pr_create` is about to change, and a failed read is re-tried rather
+// than remembered as an absence.
+const pr_number_by_branch = new Map<string, number>()
+
+// Newest first, and spelled out rather than left to the endpoint's default: `select_pull` falls back
+// to the first row when no open pull request is on the branch, and that fallback only means "the
+// most recent one" while this ordering holds.
+const LOOKUP_QUERY = 'state=all&sort=created&direction=desc&per_page=100'
+// The comment listings are paged: REST answers 30 rows by default, while `gh pr view --json comments`
+// answered the whole conversation. Truncating them is the kit#973 failure again in another form — the
+// newest Claude Review blocker falls off a listing that is ordered oldest first, and the merge gate
+// finds nothing to stop on. `gh api --paginate` merges the pages of an array endpoint into one array,
+// so the answer stays the flat listing every caller parses. The page size itself is
+// `FULL_PAGE_QUERY`, shared with the merge-gate listings (joshuafolkken/kit#1028).
+const COMMENTS_QUERY = FULL_PAGE_QUERY
+// Written as a constant rather than inline: `{owner}` inside a template literal reads as a broken
+// interpolation.
+const OWNER_PLACEHOLDER = '{owner}'
+const NO_HEAD_REF_MESSAGE = 'gh api answered a pull request with no head branch'
+const FORK_HEAD_MESSAGE =
+	'gh api answered a pull request whose head branch is in another repository'
+// What a branch-keyed caller that cannot fold an absence into its own answer throws. Lives here
+// rather than beside either caller: the merge-gate snapshot and the two branch-keyed writes all need
+// it, and three copies of one message is the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1029).
+const NO_PULL_REQUEST_MESSAGE = 'gh api found no pull request for branch'
+// And what it throws when the lookup never answered at all. Separate from the message above because
+// the two are different diagnoses: one says the branch has nothing, the other says nobody looked
+// (joshuafolkken/kit#1048).
+const UNREADABLE_PULL_REQUEST_MESSAGE = 'gh api could not read the pull requests for branch'
+
+// `head` names the owner of the head repository, which for every branch this tooling opens is the
+// repository's own owner. `gh api` expands `{owner}` inside the query string as readily as inside
+// the path, so the lookup costs no separate request to learn the name — and none of these reads
+// gains a second way to fail. Only the branch is escaped: an expanded `{owner}` would not be.
+function lookup_path(branch_name: string): string {
+	const head = `${OWNER_PLACEHOLDER}:${encodeURIComponent(branch_name)}`
+
+	return `${git_gh_api_path.pulls_api_path()}?head=${head}&${LOOKUP_QUERY}`
+}
+
+async function fetch_pr_number(branch_name: string): Promise<number | undefined> {
+	const json = await git_gh_exec.exec_gh_api({ path: lookup_path(branch_name) })
+
+	return git_gh_pr_rest.select_pull(git_gh_pr_rest.parse_rest_pulls(json))?.number
+}
+
+// Why the resolution produced no number. `missing` is the lookup answering: the listing came back and
+// held no pull request for this branch. `unreadable` is the lookup failing — a rate limit, expired
+// auth, a dropped connection, a 200 carrying something other than a listing.
+//
+// The vocabulary is `IssueRead`'s in `git-gh-issue-read.ts`, which tells the same two apart for an
+// issue number (joshuafolkken/kit#957); reusing it rather than inventing a second spelling for one
+// distinction is the point. The *classification* is cheaper here and needs no status probe: a branch
+// with no pull request is a 200 with an empty listing rather than a 404, so the lookup's own outcome
+// already separates them (joshuafolkken/kit#1048).
+type PullNumberRead =
+	{ kind: 'read'; pr_number: number } | { kind: 'missing' } | { kind: 'unreadable'; cause: unknown }
+
+// The lookups still in flight, keyed the same way the resolved numbers are.
+const pending_pr_number_by_branch = new Map<string, Promise<PullNumberRead>>()
+
+async function fetch_pr_number_read(branch_name: string): Promise<PullNumberRead> {
+	try {
+		const pr_number = await fetch_pr_number(branch_name)
+		if (pr_number === undefined) return { kind: 'missing' }
+		pr_number_by_branch.set(branch_name, pr_number)
+
+		return { kind: 'read', pr_number }
+	} catch (error) {
+		return { kind: 'unreadable', cause: error }
+	}
+}
+
+// **The lookup in flight is shared, not only the number it resolves to** (joshuafolkken/kit#1446).
+// The memo above answers a caller arriving *after* the first lookup returned, which was every caller
+// while the branch-keyed reads were issued one at a time. `josh followup` now asks `pr_get_body` and
+// `pr_get_url` about the same branch in the same tick, and two callers that both miss an empty map
+// each fire their own `GET /pulls?head=…` — the second request this memo exists to remove,
+// reappearing the moment the callers stopped being serial. Overlapping the reads must not cost a
+// request it was meant to save.
+//
+// **A pending entry is dropped as soon as it settles**, so the property stated above is untouched:
+// only a resolved number is *remembered*, and a `missing` or `unreadable` lookup is re-tried by the
+// next caller rather than remembered as an absence.
+async function start_pr_number_read(branch_name: string): Promise<PullNumberRead> {
+	const pending = pending_pr_number_by_branch.get(branch_name)
+	if (pending !== undefined) return await pending
+
+	const lookup = fetch_pr_number_read(branch_name)
+
+	pending_pr_number_by_branch.set(branch_name, lookup)
+
+	try {
+		return await lookup
+	} finally {
+		pending_pr_number_by_branch.delete(branch_name)
+	}
+}
+
+// Defined after the map it clears, so the two memos are declared before anything reaches them.
+function forget_pr_numbers(): void {
+	pr_number_by_branch.clear()
+	pending_pr_number_by_branch.clear()
+}
+
+async function read_pr_number(branch_name: string): Promise<PullNumberRead> {
+	const cached = pr_number_by_branch.get(branch_name)
+	if (cached !== undefined) return { kind: 'read', pr_number: cached }
+
+	return await start_pr_number_read(branch_name)
+}
+
+// `undefined` covers both "this branch has no pull request" and "the lookup failed", which is the
+// distinction `gh pr view` never made either — every *read* here folds them together on purpose:
+// `pr_view` answers the empty string either way, the comment readers `undefined`. The two callers
+// that act on the absence rather than displaying it — `require_pr_number` and `pr_exists` — opt out.
+async function resolve_pr_number(branch_name: string): Promise<number | undefined> {
+	const read = await read_pr_number(branch_name)
+
+	return read.kind === 'read' ? read.pr_number : undefined
+}
+
+// One definition, because both callers that refuse to fold an unreadable lookup raise it —
+// `require_pr_number` and `pr_exists` (joshuafolkken/kit#1043).
+function to_unreadable_error(branch_name: string, cause: unknown): Error {
+	return new Error(`${UNREADABLE_PULL_REQUEST_MESSAGE}: ${branch_name}`, { cause })
+}
+
+// The number for a caller that has nothing to fold an absence into. The reads above answer their own
+// empty value for a branch with no pull request; a write cannot — `gh pr comment <branch>` and
+// `gh pr merge <branch>` both failed there, and the merge-gate snapshot already threw for the same
+// reason. One throw shared by all three (joshuafolkken/kit#1029).
+//
+// **This is the caller the distinction was written for.** Folding both into
+// `NO_PULL_REQUEST_MESSAGE` reported a rate-limited lookup as "there is no pull request for this
+// branch" — safe, in that the run stops without merging, but wrong about why, which is the
+// joshuafolkken/kit#973 misread costing diagnosis time instead of correctness. The failure travels as
+// the `cause`, so `git_error.handle` prints gh's own reason under 💡 Details
+// (joshuafolkken/kit#1048).
+async function require_pr_number(branch_name: string): Promise<number> {
+	const read = await read_pr_number(branch_name)
+	if (read.kind === 'read') return read.pr_number
+	if (read.kind === 'missing') throw new Error(`${NO_PULL_REQUEST_MESSAGE}: ${branch_name}`)
+
+	throw to_unreadable_error(branch_name, read.cause)
+}
+
+async function read_pull(pr_number: number): Promise<RestPull> {
+	const json = await git_gh_exec.exec_gh_api({
+		path: git_gh_api_path.pull_api_path(String(pr_number)),
+	})
+
+	return git_gh_pr_rest.parse_rest_pull(json)
+}
+
+// One pull request named by its branch: the resolution, then the detail read that carries
+// `mergeable` and `mergeable_state`, which the lookup listing does not.
+async function read_pull_of_branch(branch_name: string): Promise<RestPull | undefined> {
+	const pr_number = await resolve_pr_number(branch_name)
+	if (pr_number === undefined) return undefined
+
+	try {
+		return await read_pull(pr_number)
+	} catch {
+		return undefined
+	}
+}
+
+// **`false` means the branch has no pull request, and nothing else.** This is the second half of
+// joshuafolkken/kit#1048's distinction, on the caller that needs it most: `pr_exists` is not read for
+// display, it decides whether `git-pr.ts` **opens** a pull request. Folding an unreadable lookup into
+// `false` therefore made a rate-limited run try to create a second pull request on a branch that
+// already had one — surviving only because `pr_create`'s 422 → `PR_ALREADY_EXISTS` recovery caught it
+// (joshuafolkken/kit#1029), which is an accident rather than a design. The throw is the one
+// `require_pr_number` raises, so gh's own reason travels as the `cause` (joshuafolkken/kit#1043).
+async function pr_exists(branch_name: string): Promise<boolean> {
+	const read = await read_pr_number(branch_name)
+	if (read.kind === 'unreadable') throw to_unreadable_error(branch_name, read.cause)
+
+	return read.kind === 'read'
+}
+
+async function pr_get_number(branch_name: string): Promise<number | undefined> {
+	return await resolve_pr_number(branch_name)
+}
+
+async function pr_get_url(branch_name: string): Promise<string | undefined> {
+	const pull = await read_pull_of_branch(branch_name)
+	if (pull?.html_url === undefined) return undefined
+
+	return git_gh_helpers.parse_pr_state_string(pull.html_url)
+}
+
+// REST answers JSON null for a pull request with no body where `gh --json body` answered an empty
+// string, and both used to arrive here as the empty answer this folds to `undefined`.
+async function pr_get_body(branch_name: string): Promise<string | undefined> {
+	const pull = await read_pull_of_branch(branch_name)
+	const body = pull?.body
+
+	return typeof body === 'string' && body.length > 0 ? body : undefined
+}
+
+// The empty string means "there is nothing to read" — a branch with no pull request, or a read that
+// failed. `git-pr.ts` checks the length before parsing.
+async function pr_view(branch_name: string): Promise<string> {
+	const pull = await read_pull_of_branch(branch_name)
+	if (pull === undefined) return ''
+
+	return JSON.stringify(git_gh_pr_rest.to_pr_info(pull))
+}
+
+// Already keyed by number, so no resolution is needed. It throws where the others fold to an empty
+// answer, which is the contract `sync-dependabot-pins.ts` relies on: it checks out the branch it is
+// handed, and a guessed one would push template pins onto the wrong PR.
+async function pr_head_reference(pr_number: number): Promise<string> {
+	const pull = await read_pull(pr_number)
+	const reference = pull.head?.ref
+	if (reference === undefined) throw new Error(NO_HEAD_REF_MESSAGE)
+	// A fork's head is not on `origin` under this name, and `origin` may well carry a different branch
+	// that answers to it. Refusing is the same contract the missing ref has: the caller checks out what
+	// it is handed, so a guessed branch pushes template pins onto the wrong pull request.
+	if (!git_gh_pr_rest.is_same_repository_head(pull)) throw new Error(FORK_HEAD_MESSAGE)
+
+	return reference
+}
+
+// `undefined` when the listing could not be read — a failed request, or a PR whose number could not
+// be resolved. Not `'[]'`, which every failure used to become.
+//
+// The two are the same string to a caller, and the callers are the merge gate: a rate limit arrived
+// as "no reviewer left a finding" and the PR merged with the gate never actually read
+// (joshuafolkken/kit#973). The direction is what makes it worse than the epic auto-close's version of
+// the same misread — that one only failed to close something.
+async function read_comments(
+	branch_name: string,
+	to_path: (pr_number: string) => string,
+	to_json: (raw: string) => string,
+): Promise<string | undefined> {
+	const pr_number = await resolve_pr_number(branch_name)
+	if (pr_number === undefined) return undefined
+	const path = `${to_path(String(pr_number))}${COMMENTS_QUERY}`
+
+	try {
+		return to_json(await git_gh_exec.exec_gh_api({ path, should_paginate: true }))
+	} catch {
+		return undefined
+	}
+}
+
+function to_comments_json(raw: string): string {
+	return JSON.stringify(git_gh_pr_rest.to_pr_comments(raw))
+}
+
+// `git-pr-coderabbit.ts` parses `html_url` and `user.login` itself, so the review thread is handed on
+// as REST serves it (joshuafolkken/kit#1023).
+function as_served(raw: string): string {
+	return raw
+}
+
+// The conversation comments, mapped back into the shape `gh pr view --json comments` answered with —
+// `git-pr-ai-review.ts` reads `author.login` and `url`, which REST spells `user.login` / `html_url`.
+async function pr_get_comments(branch_name: string): Promise<string | undefined> {
+	return await read_comments(branch_name, git_gh_api_path.issue_comments_api_path, to_comments_json)
+}
+
+async function pr_get_review_comments(branch_name: string): Promise<string | undefined> {
+	return await read_comments(branch_name, git_gh_api_path.pull_comments_api_path, as_served)
+}
+
+const git_gh_pr_read = {
+	pr_exists,
+	pr_get_number,
+	pr_get_url,
+	pr_get_body,
+	pr_view,
+	pr_head_reference,
+	pr_get_comments,
+	pr_get_review_comments,
+}
+
+// The merge-gate snapshot needs the same branch → number resolution and the same detail read, and it
+// needs them separately: the reviews endpoint is keyed by number while the rollup is keyed by the
+// head commit the detail carries. Exported rather than re-derived so the memo above stays one memo
+// (joshuafolkken/kit#1028).
+export {
+	git_gh_pr_read,
+	forget_pr_numbers,
+	read_pull,
+	require_pr_number,
+	resolve_pr_number,
+	FORK_HEAD_MESSAGE,
+	NO_HEAD_REF_MESSAGE,
+	NO_PULL_REQUEST_MESSAGE,
+	UNREADABLE_PULL_REQUEST_MESSAGE,
+}