@joshuafolkken/kit 1.2116.0 → 1.3000.0

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

@@ -0,0 +1,53 @@
+import { git_gh_etag_read } from './git-gh-etag-read'
+
+// The single-issue reads one process has already made, keyed by request path
+// (joshuafolkken/kit#7141). `josh followup`, `backlog:drive` and `ship` read the same issue from
+// several functions, and `josh gh:usage` counted four in five of those GETs answered `304` — a
+// request each, for an answer the process already held. `git-gh-pr-read.ts`'s `pull_by_number` is
+// the same memo for pull requests.
+//
+// The promise is stored, so readers in one tick share the request as well as its answer; a read
+// that fails is dropped and re-tried. **Every write josh makes to an issue clears it** — the writes
+// in `git-gh-issue-write.ts` and the pull-request writes `forget_pr_numbers` covers, since a merge
+// closes the issues it names.
+//
+// **An answer is kept for `FRESH_MS`, not for the life of the process.** The live `run:board` gathers
+// in one long-lived worker and re-reads a decision child every tick to see what *another* process or
+// a person changed; a memo with no bound would freeze that board on its first answer.
+const FRESH_MS = 10_000
+
+interface Remembered {
+	read: Promise<string>
+	at_ms: number
+}
+
+const read_by_path = new Map<string, Remembered>()
+
+function fresh_entry(path: string, now_ms: number): Remembered | undefined {
+	const entry = read_by_path.get(path)
+
+	return entry !== undefined && now_ms - entry.at_ms < FRESH_MS ? entry : undefined
+}
+
+// The identity check keeps a failure from evicting a read that `forget` already replaced.
+async function read(path: string): Promise<string> {
+	const now_ms = Date.now()
+	const entry = fresh_entry(path, now_ms) ?? { read: git_gh_etag_read.read(path), at_ms: now_ms }
+
+	read_by_path.set(path, entry)
+
+	try {
+		return await entry.read
+	} catch (error) {
+		if (read_by_path.get(path) === entry) read_by_path.delete(path)
+		throw error
+	}
+}
+
+function forget(): void {
+	read_by_path.clear()
+}
+
+const git_gh_issue_memo = { read, forget, FRESH_MS }
+
+export { git_gh_issue_memo }

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

@@ -1,9 +1,12 @@
 import type { IssueReference } from '#scripts/issue/issue-reference'
 import { gh_author_association } from './gh-author-association'
 import { git_gh_api_path } from './git-gh-api-path'
+import { git_gh_etag_read } from './git-gh-etag-read'
 import { git_gh_exec } from './git-gh-exec'
 import { gh_failure, type GhFailure } from './git-gh-failure'
 import { git_gh_helpers } from './git-gh-helpers'
+import { git_gh_issue_graphql } from './git-gh-issue-graphql'
+import { git_gh_issue_memo } from './git-gh-issue-memo'
 import {
 	BLOCKED_BY_FIELD,
 	git_gh_issue_rest,
@@ -30,14 +33,17 @@ import { gh_reachability } from './git-gh-reachability'
 // `issue_dependencies_summary` can read `total_blocked_by: 0` while this endpoint returns a real
 // relation. Trusting the counter there makes `epic:next` call a graph that agrees with itself
 // contradictory and exit 1, which stops an unattended run at its first step with nothing to fix.
+//
+// Sent with the previous process's ETag (joshuafolkken/kit#6701): `backlog:next` reads every open
+// blocked issue's relations each offer, and an unchanged set answers `304`, which costs no core.
 async function read_blocked_by_listing(
 	issue_number: string,
 	repo?: string,
 	exact_total?: number,
 ): Promise<BlockedBy> {
-	const json = await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.blocked_by_api_path(issue_number, repo)}${git_gh_api_path.FULL_PAGE_QUERY}`,
-	})
+	const json = await git_gh_issue_memo.read(
+		`${git_gh_api_path.blocked_by_api_path(issue_number, repo)}${git_gh_api_path.FULL_PAGE_QUERY}`,
+	)
 
 	return git_gh_issue_rest.to_blocked_by(json, exact_total)
 }
@@ -103,6 +109,13 @@ async function read_relations(
 	}
 }
 
+// The request itself, sent with the previous process's ETag (joshuafolkken/kit#6754): every one of
+// the five commands `josh gh:usage` counts most calls for reads issues one GET at a time, and an
+// unchanged issue answers `304`, which costs no core. A caller passes its own read where it has one.
+// The default is remembered for the process (`git-gh-issue-memo.ts`), so a second read of the same
+// issue makes no request at all; a caller's own read is never remembered.
+type PathRead = (path: string) => Promise<string>
+
 // One issue through REST, answered in the field names `gh issue view --json` used. Every read below
 // goes through it, so the request, the field mapping and the blocker relations are decided once.
 //
@@ -110,13 +123,15 @@ async function read_relations(
 // labels-and-body reads never name it — and, when it was, only when the issue itself reports a
 // blocker to fetch. Both guards are about the same cost: relations are read per issue across the
 // whole open backlog, so an unconditional second request would double that pass.
+
 async function read_issue_fields(
 	issue_number: string,
 	fields: string,
 	repo?: string,
+	read_path: PathRead = git_gh_issue_memo.read,
 ): Promise<Record<string, unknown>> {
 	const rest = git_gh_issue_rest.parse_rest_issue(
-		await git_gh_exec.exec_gh_api({ path: git_gh_api_path.issue_api_path(issue_number, repo) }),
+		await read_path(git_gh_api_path.issue_api_path(issue_number, repo)),
 	)
 	const requested = git_gh_issue_rest.split_fields(fields)
 	const blocked_by = requested.includes(BLOCKED_BY_FIELD)
@@ -140,8 +155,11 @@ async function read_issue_fields(
 // neither a transport problem nor a permission one. `kind` is unchanged so the callers that only
 // separate "there is nothing at that number" from "the read failed" need no edit.
 type IssueReadReason = 'unreachable' | 'rejected' | 'malformed'
+// `detail` is the failed request's error text (gh's stderr summary and the response body), kept so a
+// report can tell an exhausted rate limit from expired auth (#6614); a `malformed` read has none.
 type IssueReadFailure =
-	{ kind: 'missing' } | { kind: 'unreadable'; reason: IssueReadReason; status: number | undefined }
+	| { kind: 'missing' }
+	| { kind: 'unreadable'; reason: IssueReadReason; status: number | undefined; detail?: string }
 type IssueRead = IssueReadFailure | { kind: 'read'; json: string }
 type FieldRead = IssueReadFailure | { kind: 'read'; text: string | undefined }
 
@@ -190,6 +208,7 @@ function to_read_failure(error: unknown): IssueReadFailure {
 		kind: 'unreadable',
 		reason: to_unreadable_reason(failure.status),
 		status: failure.status,
+		detail: error instanceof Error ? error.message : String(error),
 	}
 }
 
@@ -198,9 +217,10 @@ async function issue_view_json_classified(
 	issue_number: string,
 	fields: string,
 	repo?: string,
+	read_path?: PathRead,
 ): Promise<IssueRead> {
 	try {
-		const issue = await read_issue_fields(issue_number, fields, repo)
+		const issue = await read_issue_fields(issue_number, fields, repo, read_path)
 
 		return { kind: 'read', json: JSON.stringify(issue) }
 	} catch (error) {
@@ -269,8 +289,9 @@ async function issue_view_json(
 	issue_number: string,
 	fields: string,
 	repo?: string,
+	read_path?: PathRead,
 ): Promise<string | undefined> {
-	const read = await issue_view_json_classified(issue_number, fields, repo)
+	const read = await issue_view_json_classified(issue_number, fields, repo, read_path)
 
 	return read.kind === 'read' ? read.json : undefined
 }
@@ -353,22 +374,66 @@ async function issue_get_labels_and_body(issue_number: string): Promise<string |
 // is already keyed by a number and wants the rows as served. What the two genuinely share — the path
 // and the page size — is single-sourced in `git-gh-api-path.ts` and read from there by both.
 //
-// No `repo` parameter, unlike the reads above: the auto-close lists its candidate epics from the
-// repository it runs in, so the epic whose comments are read is always a local one. The path builder
-// takes one when a caller that needs it appears.
+// `repo` names the repository like the reads above do — `issue:read --repo` reads another repository's
+// thread (joshuafolkken/kit#5851); absent, it is the repository the command runs in. `read_path`
+// replaces the paged request, as `read_comments_conditionally` does for the run board.
 async function issue_list_comments(
 	issue_number: string,
 	timeout_ms?: number,
+	repo?: string,
+	read_path?: PathRead,
 ): Promise<string | undefined> {
-	const path = `${git_gh_api_path.issue_comments_api_path(issue_number)}${git_gh_api_path.FULL_PAGE_QUERY}`
+	const path = `${git_gh_api_path.issue_comments_api_path(issue_number, repo)}${git_gh_api_path.FULL_PAGE_QUERY}`
 
 	try {
-		return await git_gh_exec.exec_gh_api({ path, should_paginate: true, timeout_ms })
+		return await (read_path?.(path) ??
+			git_gh_exec.exec_gh_api({ path, should_paginate: true, timeout_ms }))
 	} catch {
 		return undefined
 	}
 }
 
+// One issue's fields and its comment listing, in the shapes `issue_view_json_classified` and
+// `issue_list_comments` answer. One GraphQL query serves both when it can (joshuafolkken/kit#6722),
+// so a read costs no REST core; when it cannot, the two REST reads are made side by side as before,
+// and they are what tells a missing number from a failed read.
+interface IssueWithComments {
+	read: IssueRead
+	comments_json: string | undefined
+}
+
+async function issue_read_with_comments(
+	issue_number: string,
+	fields: string,
+	repo?: string,
+): Promise<IssueWithComments> {
+	const graphql = await git_gh_issue_graphql.read_issue(issue_number, repo)
+
+	if (graphql === undefined) {
+		const [read, comments_json] = await Promise.all([
+			issue_view_json_classified(issue_number, fields, repo),
+			issue_list_comments(issue_number, undefined, repo),
+		])
+
+		return { read, comments_json }
+	}
+
+	const requested = git_gh_issue_rest.split_fields(fields)
+	const issue = git_gh_issue_rest.to_gh_issue(graphql.rest, requested, graphql.blocked_by)
+
+	return {
+		read: { kind: 'read', json: JSON.stringify(issue) },
+		comments_json: graphql.comments_json,
+	}
+}
+
+// The comment listing sent with the previous process's ETag (joshuafolkken/kit#6700): the run board
+// re-reads a decision child's thread every two minutes, and an unchanged first page answers `304`.
+// A full first page is read paged instead, by `read_listing`.
+async function read_comments_conditionally(path: string): Promise<string> {
+	return await git_gh_etag_read.read_listing(path, git_gh_api_path.FULL_PAGE_SIZE)
+}
+
 // Whether the relations endpoint has nothing at that number at all. Probed for its status rather
 // than read off `gh`'s stderr wording, because classifying by the message is prose-matching.
 //
@@ -443,7 +508,15 @@ const git_gh_issue_read = {
 	issue_get_plan_fields_classified,
 	issue_get_labels_and_body,
 	issue_list_comments,
+	issue_read_with_comments,
+	read_comments_conditionally,
 }
 
-export type { IssueRead, IssueReadFailure, IssueReadReason }
-export { git_gh_issue_read, read_blocked_by, NOT_FOUND_STATUS }
+export type { IssueRead, IssueReadFailure, IssueReadReason, IssueWithComments }
+export {
+	git_gh_issue_read,
+	read_blocked_by,
+	NOT_FOUND_STATUS,
+	PLAN_FIELDS,
+	STATE_AND_RELATIONS_FIELDS,
+}

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

@@ -7,14 +7,9 @@ import type { IssueReference } from '#scripts/issue/issue-reference'
 import { z } from 'zod'
 import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
 
-// The translation between one REST issue (`repos/{owner}/{repo}/issues/{N}`) and the JSON shape
-// `gh issue view --json <fields>` used to answer with.
-//
-// `gh issue view` goes through GraphQL, which a cloud session is answered 403 for while the REST
-// endpoint is served normally. The reads in `git-gh-issue-read.ts` are what
-// every epic command goes through, so they move to REST — and every caller downstream keeps reading
-// the field names it already reads. The mapping lives here rather than beside the requests because
-// it is pure: given the two responses, it decides the answer with nothing else to know.
+// Translate REST issues into the `gh issue view --json <fields>` shape expected by callers.
+// Cloud sessions can receive GraphQL 403s while REST remains available. Keeping the pure mapping
+// separate from requests preserves the caller contract without coupling it to transport.
 
 // Only the fields the mapping itself reads are named; every other key passes through untouched,
 // which is what lets a caller ask for a field this file has never heard of.
@@ -26,6 +21,8 @@ import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
 // readily as an issue, so it stays optional and tolerates an explicit null.
 const rest_issue_schema = z.looseObject({
 	number: z.number(),
+	// The GraphQL id a listing's blocker read addresses the row by (`git-gh-blocked-by-graphql.ts`).
+	node_id: z.string().optional(),
 	body: z.string().nullish(),
 	issue_dependencies_summary: z.looseObject({ total_blocked_by: z.number().optional() }).nullish(),
 	// Present only on a pull request, which this endpoint serves as readily as an issue.

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

@@ -4,6 +4,7 @@ import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec, type GhApiRequest } from './git-gh-exec'
 import { gh_failure } from './git-gh-failure'
+import { git_gh_issue_memo } from './git-gh-issue-memo'
 
 // Writing issues and labels through REST, in the return-value contracts the `gh <noun> <verb>`
 // wrappers had.
@@ -26,6 +27,8 @@ import { gh_failure } from './git-gh-failure'
 const PATCH_METHOD = 'PATCH'
 const DELETE_METHOD = 'DELETE'
 
+type CloseReason = 'completed' | 'not_planned' | 'duplicate'
+
 // `gh issue edit`, `gh issue comment` and `gh issue create` each printed one URL, and the callers
 // read it — `epic-run.ts` parses the epic's number back out of it. REST answers the whole
 // object, so the same value is unwrapped out of it rather than the shape being changed.
@@ -56,12 +59,22 @@ async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean
 	}
 }
 
+// Every write below to an existing issue goes through here, which clears the issue reads this process remembers
+// (`git-gh-issue-memo.ts`) — in `finally`, because a write that threw may still have landed.
+async function write_api(request: GhApiRequest): Promise<string> {
+	try {
+		return await git_gh_exec.exec_gh_api(request)
+	} finally {
+		git_gh_issue_memo.forget()
+	}
+}
+
 async function issue_patch(
 	issue_number: string,
 	fields: Readonly<Record<string, string>>,
 	repo?: string,
 ): Promise<string> {
-	return await git_gh_exec.exec_gh_api({
+	return await write_api({
 		path: git_gh_api_path.issue_api_path(issue_number, repo),
 		method: PATCH_METHOD,
 		body: JSON.stringify(fields),
@@ -87,7 +100,7 @@ async function issue_edit_title(
 // posts under the person's own `gh` login, so the marker is the only thing that tells the issue watch
 // (`issue-watch-diff.ts`) a run's comment from a person's update.
 async function issue_comment(issue_number: string, body: string, repo?: string): Promise<string> {
-	return await git_gh_exec.exec_gh_api({
+	return await write_api({
 		path: `${git_gh_api_path.issue_api_path(issue_number, repo)}${COMMENTS_SEGMENT}`,
 		body: JSON.stringify({ body: `${body}\n\n${issue_watch_diff.RUN_MARKER}` }),
 		jq_filter: HTML_URL_FILTER,
@@ -128,7 +141,7 @@ async function close_with(
 ): Promise<boolean> {
 	return await did_write_succeed(async () => {
 		if (comment !== undefined) await issue_comment(issue_number, comment)
-		await git_gh_exec.exec_gh_api({
+		await write_api({
 			path: git_gh_api_path.issue_api_path(issue_number),
 			method: PATCH_METHOD,
 			body: JSON.stringify(state),
@@ -136,8 +149,16 @@ async function close_with(
 	})
 }
 
-async function issue_close(issue_number: string, comment: string | undefined): Promise<boolean> {
-	return await close_with(issue_number, comment, { state: CLOSED_STATE })
+// `reason` is GitHub's `state_reason`, the field `git-gh-issue-rest.ts` reads back as `stateReason`;
+// left out, GitHub records `completed`.
+async function issue_close(
+	issue_number: string,
+	comment: string | undefined,
+	reason?: CloseReason,
+): Promise<boolean> {
+	const state = reason === undefined ? {} : { state_reason: reason }
+
+	return await close_with(issue_number, comment, { state: CLOSED_STATE, ...state })
 }
 
 // REST answers 422 `{"resource":"Label","code":"invalid","field":"color"}` for a color carrying a
@@ -270,7 +291,7 @@ async function issue_apply_label(
 	const labels_path = git_gh_api_path.issue_labels_api_path(issue_number, repo)
 
 	try {
-		await git_gh_exec.exec_gh_api({ path: labels_path, body: JSON.stringify({ labels: [label] }) })
+		await write_api({ path: labels_path, body: JSON.stringify({ labels: [label] }) })
 
 		return { is_applied: true }
 	} catch (error) {
@@ -312,7 +333,7 @@ async function issue_add_label(
 async function issue_remove_label(issue_number: string, label: string): Promise<void> {
 	const labels_path = git_gh_api_path.issue_labels_api_path(issue_number)
 
-	await git_gh_exec.exec_gh_api({
+	await write_api({
 		path: `${labels_path}/${encodeURIComponent(label)}`,
 		method: DELETE_METHOD,
 	})
@@ -371,7 +392,7 @@ async function issue_add_blocked_by(issue_number: string, blocker: string): Prom
 	return await did_write_succeed(async () => {
 		const issue_id = await read_issue_id(blocker)
 
-		await git_gh_exec.exec_gh_api({
+		await write_api({
 			path: git_gh_api_path.blocked_by_api_path(issue_number),
 			body: JSON.stringify({ issue_id }),
 		})
@@ -387,7 +408,7 @@ async function issue_remove_blocked_by(issue_number: string, blocker: string): P
 		const issue_id = await read_issue_id(blocker)
 		const relations_path = git_gh_api_path.blocked_by_api_path(issue_number)
 
-		await git_gh_exec.exec_gh_api({
+		await write_api({
 			path: `${relations_path}/${String(issue_id)}`,
 			method: DELETE_METHOD,
 		})
@@ -413,4 +434,4 @@ const git_gh_issue_write = {
 }
 
 export { git_gh_issue_write }
-export type { LabelWrite }
+export type { CloseReason, LabelWrite }

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

@@ -1,5 +1,6 @@
 import { gh_author_association } from './gh-author-association'
-import { git_gh_issue_list, type IssueListOutcome } from './git-gh-issue-list'
+import { git_gh_etag_read, type ReadDetail } from './git-gh-etag-read'
+import { FIRST_PAGE, 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'
@@ -14,9 +15,8 @@ const LABELLED_FIELDS = 'number,body,stateReason'
 //
 // `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. 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, which would otherwise be made for every open issue in the repository. Absent on a
+// carries, so it costs no request at all. `epic:bundle` no longer consults it: it reads the
+// relations themselves from `issue_list_open_relations` (joshuafolkken/kit#6796). Absent on a
 // row whose summary is missing, which must not be read as zero; `git-gh-issue-rest.ts` states why.
 //
 // `labels` rides along on the same response too: `epic:bundle` reads the release label off it,
@@ -81,6 +81,13 @@ async function issue_list_open_bodies(limit: number): Promise<IssueListOutcome>
 	return await issue_list({ json_fields: BACKLOG_SCAN_FIELDS, limit })
 }
 
+// The same listing with each row's blocker relations, for `epic:bundle`. The listing reads them in
+// one GraphQL query per hundred rows (`git-gh-issue-list.ts`), so the cost stays flat as the backlog
+// grows; read row by row they cost two requests per blocked issue (joshuafolkken/kit#6796).
+async function issue_list_open_relations(limit: number): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: `${BACKLOG_SCAN_FIELDS},blockedBy`, limit })
+}
+
 // The issues that closed most recently, for the duplicate half of `issue:scout`.
 // **The work most likely to be filed twice is the work that just
 // finished**, and a scan that reads only open issues cannot see any of it.
@@ -143,6 +150,18 @@ async function issue_list_by_label_summary(
 	})
 }
 
+// The first page `issue_list_by_label_summary` reads over REST, saying whether it changed since the
+// previous process read it (joshuafolkken/kit#7226): `backlog:drive` asks it of the `auto-ok` listing
+// before an offer, and the `--wait` arrival probe asks the same. It answers for that one page only —
+// a change past its hundred rows reads as unchanged. The ETag is shared with the listing only where
+// the listing reads REST; on GraphQL it keeps its own. A failure throws, as
+// `git_gh_etag_read.read_detail` does.
+async function issue_list_label_first_page(label: string): Promise<ReadDetail> {
+	const path = git_gh_issue_list.listing_path({ label }, FIRST_PAGE)
+
+	return await git_gh_etag_read.read_detail(path)
+}
+
 // 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.
 //
@@ -176,8 +195,10 @@ const git_gh_issue = {
 	issue_list_by_label,
 	issue_list_by_label_in_repo,
 	issue_list_by_label_summary,
+	issue_list_label_first_page,
 	issue_search_body,
 	issue_list_open_bodies,
+	issue_list_open_relations,
 	issue_list_open_for_judgement,
 	issue_list_recently_closed,
 }

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

@@ -3,30 +3,28 @@ import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 import { FULL_PAGE_QUERY } from './git-gh-api-path'
 import { git_gh_conditional, type ConditionalRead } from './git-gh-conditional'
+import { git_gh_etag_read, type KeptAnswer, type ReadDetail } from './git-gh-etag-read'
 import { git_gh_exec } from './git-gh-exec'
 
 // The merge gate's per-poll reads, each sent with the ETag of this process's previous answer
 // (joshuafolkken/kit#4550).
 //
-// **Never a pull request's detail**: GitHub computes its `mergeable_state` lazily, under an unchanged
-// ETag, so a 304 would keep a stale state (joshuafolkken/kit#4589).
+// **A pull request's detail says whether it was answered 304** (`read_detail`): GitHub computes its
+// `mergeable_state` lazily, under an unchanged ETag, so the kept body's state can be stale and the
+// caller reads it afresh (joshuafolkken/kit#4589, joshuafolkken/kit#6721).
 //
-// **`pnpm josh followup` reads the same pull request every 10 seconds** while its checks run, and
+// **`pnpm josh followup` repeatedly reads the same pull request** while its checks run, and
 // every lane waiting on its merge does so at once. A `304 Not Modified` does not count against the
 // rate limit, so a poll that finds nothing changed costs only its pull detail read.
 //
 // **A listing is read one page at a time only while it fits in one.** A listing longer than a page is
 // read through `--paginate --slurp` as before; the conditional read cannot page, and a partial
-// listing would drop checks from the verdict.
+// listing would drop checks from the verdict. A bare-array listing (`read_array_pages`, the reviews
+// listing) has no `total_count`, so a first page shorter than a page is the whole one.
 
 const UNREADABLE_POLL_MESSAGE = 'gh api could not read a merge-gate poll'
 const PAGE_SIZE = 100
 
-interface KeptAnswer {
-	etag: string
-	body: string
-}
-
 const kept_by_path = new Map<string, KeptAnswer>()
 
 const page_schema = z.object({ total_count: z.number() })
@@ -40,22 +38,36 @@ function unreadable(path: string, answer: ConditionalRead): Error {
 	return new Error(`${UNREADABLE_POLL_MESSAGE}: ${path}${reason}`, { cause })
 }
 
-function to_body(path: string, answer: ConditionalRead): string {
-	const previous = kept_by_path.get(path)
+// The body `answer` stands for, keeping the new one; `undefined` where it has none to give.
+function settle_kept(path: string, answer: ConditionalRead): string | undefined {
+	const settled = git_gh_etag_read.settle(kept_by_path.get(path), answer)
 
-	if (previous !== undefined && answer.kind === 'unchanged') return previous.body
-	if (answer.kind !== 'changed') throw unreadable(path, answer)
-	if (answer.etag !== undefined) kept_by_path.set(path, { etag: answer.etag, body: answer.body })
+	if (settled?.kept !== undefined) kept_by_path.set(path, settled.kept)
 
-	return answer.body
+	return settled?.body
+}
+
+async function read_answer(path: string): Promise<ConditionalRead> {
+	return await git_gh_conditional.read_conditional(path, kept_by_path.get(path)?.etag)
 }
 
 // The answer for `path`, or the previous one where GitHub says it has not changed. A failure throws,
 // the contract the unconditional read had.
 async function read(path: string): Promise<string> {
-	const answer = await git_gh_conditional.read_conditional(path, kept_by_path.get(path)?.etag)
+	const answer = await read_answer(path)
+	const body = settle_kept(path, answer)
+	if (body === undefined) throw unreadable(path, answer)
+
+	return body
+}
+
+// `read`, saying whether the body is the kept one. A failure answers `undefined`, so the caller falls
+// back to its unconditional read and throws that read's own error.
+async function read_detail(path: string): Promise<ReadDetail | undefined> {
+	const answer = await read_answer(path)
+	const body = settle_kept(path, answer)
 
-	return to_body(path, answer)
+	return body === undefined ? undefined : { body, is_unchanged: answer.kind === 'unchanged' }
 }
 
 // A page that does not parse as a listing is not taken as the whole one: the full read answers it, and
@@ -80,10 +92,23 @@ async function read_object_pages(path: string): Promise<string> {
 	})
 }
 
+// A bare-array listing (the reviews endpoint), whose pages `gh` merges into one array on its own —
+// slurping it would produce `[[…],[…]]`, which the listing schema then rejects.
+async function read_array_pages(path: string): Promise<string> {
+	return await git_gh_etag_read.read_listing(`${path}${FULL_PAGE_QUERY}`, PAGE_SIZE, read)
+}
+
 function forget_poll_reads(): void {
 	kept_by_path.clear()
 }
 
-const git_gh_poll_read = { UNREADABLE_POLL_MESSAGE, forget_poll_reads, read, read_object_pages }
+const git_gh_poll_read = {
+	UNREADABLE_POLL_MESSAGE,
+	forget_poll_reads,
+	read,
+	read_array_pages,
+	read_detail,
+	read_object_pages,
+}
 
 export { git_gh_poll_read }

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

@@ -5,10 +5,7 @@ import { GRAPHQL_PATH } from './git-gh-pr-graphql-state'
 import { read_pull, read_pull_or_listed, 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.
-// `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.
+// Auto-merge lets a josh-owned pull request land even if its waiting process ends early.
 //
 // **This is a GraphQL request because REST has no equivalent** — the pull-request layer's only other
 // one is `git-gh-pr-graphql-state.ts`. Enabling auto-merge is `enablePullRequestAutoMerge` and