@joshuafolkken/kit 1.2116.0 → 1.3000.0

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

@@ -1,16 +1,18 @@
-import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_branch_rules } from './git-gh-branch-rules'
-import { git_gh_exec } from './git-gh-exec'
 import { git_gh_poll_read } from './git-gh-poll-read'
+import { git_gh_pr_graphql_snapshot } from './git-gh-pr-graphql-snapshot'
 import { git_gh_pr_graphql_state } from './git-gh-pr-graphql-state'
 import { read_listed_pull, read_pull, require_pr_number } from './git-gh-pr-read'
-import type { RestPull } from './git-gh-pr-rest'
+import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 import { git_gh_pr_review } from './git-gh-pr-review'
 import { git_gh_pr_rollup } from './git-gh-pr-rollup'
 import { to_gh_state } from './git-gh-rest-state'
 
-// The merge gate's pull request state snapshot, rebuilt from REST — GraphQL only for the merge state
-// of a pull request whose REST detail GitHub refuses as too large (`resolve_pull`).
+// The merge gate's pull request state snapshot. A session whose transport allows GraphQL reads it in
+// one query (`git-gh-pr-graphql-snapshot.ts`, joshuafolkken/kit#6786); otherwise, or where that query
+// does not answer, it is rebuilt from REST — GraphQL only for the merge state of a pull request whose
+// REST detail GitHub refuses as too large or answers 304 (`resolve_pull`).
 //
 // `gh pr view --json mergeStateStatus,reviewDecision,statusCheckRollup` is answered 403 in a cloud
 // session, and all three fields are GraphQL-only: one has no REST
@@ -23,15 +25,6 @@ import { to_gh_state } from './git-gh-rest-state'
 
 const NO_HEAD_SHA_MESSAGE = 'gh api answered a pull request with no head commit'
 
-// The reviews endpoint answers a bare array, 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_exec.exec_gh_api({
-		path: `${path}${FULL_PAGE_QUERY}`,
-		should_paginate: true,
-	})
-}
-
 function read_head_sha(pull: RestPull): string {
 	const sha = pull.head?.sha
 	if (sha === undefined) throw new Error(NO_HEAD_SHA_MESSAGE)
@@ -53,10 +46,16 @@ async function read_status_check_rollup(commit_sha: string): Promise<Array<objec
 
 // The review history, folded into GraphQL's `reviewDecision`. One request, and the only one of the
 // four the merge gate does not need on every poll — see `is_review_decision_decisive`.
-async function pr_get_review_decision(pr_number: number): Promise<string> {
+async function read_rest_review_decision(pr_number: number): Promise<string> {
 	const path = git_gh_api_path.pull_reviews_api_path(String(pr_number))
 
-	return git_gh_pr_review.to_review_decision(await read_array_pages(path))
+	return git_gh_pr_review.to_review_decision(await git_gh_poll_read.read_array_pages(path))
+}
+
+async function pr_get_review_decision(pr_number: number): Promise<string> {
+	const graphql_decision = await git_gh_pr_graphql_snapshot.read_review_decision(pr_number)
+
+	return graphql_decision ?? (await read_rest_review_decision(pr_number))
 }
 
 // `mergeStateStatus` is upper-cased because that is the spelling `gh` uses and the spelling
@@ -69,6 +68,9 @@ async function pr_get_review_decision(pr_number: number): Promise<string> {
 //
 // **`requiredContexts` is the base branch's required checks** (`git-gh-branch-rules.ts`), which the
 // merge gate reads to accept an `UNSTABLE` pull request held only by an optional check.
+//
+// **`merged` is carried only once the pull request is in**, so the wait on an auto-merge reads it
+// from the same detail read rather than a second one (joshuafolkken/kit#6721).
 async function build_checks_fields(pull: RestPull): Promise<Record<string, unknown>> {
 	const head_sha = read_head_sha(pull)
 	const [rollup, required_contexts] = await Promise.all([
@@ -81,6 +83,7 @@ async function build_checks_fields(pull: RestPull): Promise<Record<string, unkno
 		mergeStateStatus: to_gh_state(pull.mergeable_state),
 		headRefOid: head_sha,
 		requiredContexts: required_contexts,
+		...(git_gh_pr_rest.is_merged(pull) && { merged: true }),
 	}
 }
 
@@ -92,16 +95,29 @@ interface ResolvedPull {
 // The resolution and the detail read, which every path below needs. The branch → number memo in
 // `git-gh-pr-read.ts` makes the first free after the first poll.
 //
-// **The detail is read without an ETag.** GitHub computes `mergeable_state` lazily and can change it
-// under an unchanged ETag, so a 304 answered from the poll cache kept the gate reading a stale
-// `blocked` on a pull request that had turned `clean` (joshuafolkken/kit#4589).
-//
+// **A detail answered 304 keeps its body but not its `mergeable_state`.** GitHub computes that state
+// lazily and can change it under an unchanged ETag, so a 304 alone kept the gate reading a stale
+// `blocked` on a pull request that had turned `clean` (joshuafolkken/kit#4589). The state is read from
+// GraphQL instead, which costs no REST core quota (joshuafolkken/kit#6721); where GraphQL does not
+// answer, or the conditional read fails, the detail is read unconditionally as before.
+async function read_polled_pull(pr_number: number): Promise<RestPull> {
+	const polled = await git_gh_poll_read.read_detail(
+		git_gh_api_path.pull_api_path(String(pr_number)),
+	)
+	if (polled === undefined) return await read_pull(pr_number)
+	const pull = git_gh_pr_rest.parse_rest_pull(polled.body)
+	if (!polled.is_unchanged) return pull
+	const state = await git_gh_pr_graphql_state.try_read_merge_state(pull.node_id)
+
+	return state === undefined ? await read_pull(pr_number) : { ...pull, mergeable_state: state }
+}
+
 // **A detail GitHub refuses as too many files changed** is stood in for by the listing row, whose
 // missing `mergeable_state` is read from GraphQL (`git-gh-pr-graphql-state.ts`) — or the snapshot
 // throws with the reason, since an unknown state would hold the gate pending until its budget ran out.
 async function read_detail_or_listed(branch_name: string, pr_number: number): Promise<RestPull> {
 	try {
-		return await read_pull(pr_number)
+		return await read_polled_pull(pr_number)
 	} catch (error) {
 		const listed = await read_listed_pull(error, branch_name, pr_number)
 		if (listed === undefined) throw error
@@ -119,18 +135,45 @@ async function resolve_pull(branch_name: string): Promise<ResolvedPull> {
 
 // Everything the snapshot carries except the review decision: three requests rather than four.
 // `pr_number` travels with it so a caller that then *does* want the review decision needs no second
-// resolution.
+// resolution. **`graphql` is the decision the one GraphQL query already read**, so a poll round that
+// wants it asks no second query (joshuafolkken/kit#7143); absent on the REST path.
 interface PrChecksSnapshot {
 	pr_number: number
 	snapshot_json: string
+	graphql?: { review_decision: string | undefined }
 }
 
 async function pr_get_checks_snapshot(branch_name: string): Promise<PrChecksSnapshot> {
+	const graphql = await git_gh_pr_graphql_snapshot.read_snapshot(branch_name)
+
+	if (graphql !== undefined) {
+		return {
+			pr_number: graphql.pr_number,
+			snapshot_json: JSON.stringify(graphql.fields),
+			graphql: { review_decision: graphql.review_decision },
+		}
+	}
+
 	const { pr_number, pull } = await resolve_pull(branch_name)
 
 	return { pr_number, snapshot_json: JSON.stringify(await build_checks_fields(pull)) }
 }
 
+// GraphQL's `null` decision is no answer (`to_review_decision`), so it is folded from the REST reviews.
+async function graphql_or_rest_decision(
+	decision: string | undefined,
+	pr_number: number,
+): Promise<string> {
+	return decision ?? (await read_rest_review_decision(pr_number))
+}
+
+// The review decision of a snapshot already read: the GraphQL query's own where it answered one.
+async function pr_read_review_decision(checks: PrChecksSnapshot): Promise<string> {
+	if (checks.graphql === undefined) return await pr_get_review_decision(checks.pr_number)
+
+	return await graphql_or_rest_decision(checks.graphql.review_decision, checks.pr_number)
+}
+
 // Throws where the branch has no pull request or a read fails, which is the contract `gh pr view`
 // had: `git-pr-followup.ts` catches it and falls through to the poll, and folding a failure into an
 // empty snapshot instead would read as "no checks, nothing requested" — green.
@@ -140,6 +183,17 @@ async function pr_get_checks_snapshot(branch_name: string): Promise<PrChecksSnap
 // three-field value `gh pr view --json …` answered with is still one thing, and it is asserted here
 // rather than reassembled inside a test.
 async function pr_get_state_snapshot(branch_name: string): Promise<string> {
+	const graphql = await git_gh_pr_graphql_snapshot.read_snapshot(branch_name)
+
+	if (graphql !== undefined) {
+		const review_decision = await graphql_or_rest_decision(
+			graphql.review_decision,
+			graphql.pr_number,
+		)
+
+		return JSON.stringify({ ...graphql.fields, reviewDecision: review_decision })
+	}
+
 	const { pr_number, pull } = await resolve_pull(branch_name)
 	const [fields, review_decision] = await Promise.all([
 		build_checks_fields(pull),
@@ -153,6 +207,7 @@ const git_gh_pr_snapshot = {
 	pr_get_state_snapshot,
 	pr_get_checks_snapshot,
 	pr_get_review_decision,
+	pr_read_review_decision,
 }
 
 export {
@@ -160,5 +215,6 @@ export {
 	pr_get_state_snapshot,
 	pr_get_checks_snapshot,
 	pr_get_review_decision,
+	pr_read_review_decision,
 	NO_HEAD_SHA_MESSAGE,
 }

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

@@ -15,6 +15,7 @@ import {
 } from './git-gh-pr-read'
 import { git_gh_pr_rest } from './git-gh-pr-rest'
 import { git_gh_pr_snapshot } from './git-gh-pr-snapshot'
+import { gh_retry } from './git-gh-retry'
 
 // The pull-request writes, through REST.
 //
@@ -55,6 +56,11 @@ const MERGE_UNCONFIRMED_MESSAGE =
 	'gh api could not read the pull request back after the merge request failed'
 const MERGE_READ_BACK_ATTEMPTS = 3
 const MERGE_READ_BACK_INTERVAL_MS = 1000
+// GitHub's 405 body for a merge it is still carrying out — typically the earlier request of a pair
+// whose first answer was a 504. The read-back then waits for it to land, about a minute at most.
+const MERGE_IN_PROGRESS_MESSAGE = 'Merge already in progress'
+const MERGE_IN_PROGRESS_ATTEMPTS = 30
+const MERGE_IN_PROGRESS_INTERVAL_MS = 2000
 // `PUT pulls/{N}/merge` with a `sha` that is no longer the branch head.
 const HEAD_MOVED_STATUS = 409
 const PR_NUMBER_PATTERN = /\/pull\/([1-9]\d*)$/u
@@ -185,6 +191,7 @@ async function put_merge(pr_number: number, head_sha: string): Promise<void> {
 		method: PUT_METHOD,
 		body: JSON.stringify({ merge_method: MERGE_COMMIT_METHOD, sha: head_sha }),
 		timeout_ms: MERGE_REQUEST_TIMEOUT_MS,
+		should_retry: false,
 	})
 }
 
@@ -212,11 +219,21 @@ async function read_merge_state(
 	}
 }
 
-// The wait goes **between** attempts and never after the last one — the convention `poll.wait_between`
-// and `git-pr-checks.ts`'s own `sleep_before_next_attempt` both hold to. Without the guard a merge
-// whose read-back never succeeds delays its own failure report by a whole interval.
-async function sleep_between_read_backs(attempt: number): Promise<void> {
-	if (attempt < MERGE_READ_BACK_ATTEMPTS - 1) await poll.sleep(MERGE_READ_BACK_INTERVAL_MS)
+function is_merge_in_progress(error: unknown): boolean {
+	return error instanceof Error && error.message.includes(MERGE_IN_PROGRESS_MESSAGE)
+}
+
+// **"Not merged" is not a verdict while GitHub says the merge is still running** (#7171), so only an
+// answer of merged ends the wait early. Out of attempts it answers false, and the caller rethrows the
+// 405 itself.
+async function has_in_progress_merge_landed(
+	branch_name: string,
+	pr_number: number,
+): Promise<boolean> {
+	return await poll.poll_until(
+		async () => (await read_merge_state(branch_name, pr_number)) === true,
+		{ attempts: MERGE_IN_PROGRESS_ATTEMPTS, interval_ms: MERGE_IN_PROGRESS_INTERVAL_MS },
+	)
 }
 
 // Whether the merge is actually there, asked only after the request failed.
@@ -235,15 +252,16 @@ async function has_merge_landed(
 	pr_number: number,
 	merge_error: unknown,
 ): Promise<boolean> {
-	for (let attempt = 0; attempt < MERGE_READ_BACK_ATTEMPTS; attempt += 1) {
-		// eslint-disable-next-line no-await-in-loop -- a retry runs only after the previous attempt has answered
-		const is_merged = await read_merge_state(branch_name, pr_number)
-		if (is_merged !== undefined) return is_merged
-
-		// eslint-disable-next-line no-await-in-loop -- a retry runs only after the previous attempt has answered
-		await sleep_between_read_backs(attempt)
+	if (is_merge_in_progress(merge_error)) {
+		return await has_in_progress_merge_landed(branch_name, pr_number)
 	}
 
+	const is_merged = await poll.poll_for(
+		async () => await read_merge_state(branch_name, pr_number),
+		{ attempts: MERGE_READ_BACK_ATTEMPTS, interval_ms: MERGE_READ_BACK_INTERVAL_MS },
+	)
+	if (is_merged !== undefined) return is_merged
+
 	throw new Error(MERGE_UNCONFIRMED_MESSAGE, { cause: merge_error })
 }
 
@@ -258,16 +276,18 @@ async function has_merge_landed(
 // **A failed merge request is not proof the merge did not happen**, so the pull request's own state
 // settles it: merged, and this returns as if the request had succeeded, which is what lets
 // `followup` carry on to the notification and the epic close, and what makes re-running it recover
-// instead of failing on the 405. Not merged, and the original failure is rethrown unchanged.
+// instead of failing on the 405. Not merged, and the original failure reaches the bounded retry.
 //
 // **The question is "is this pull request merged", not "did my request merge it"**, and that is
 // deliberate: the state the recovery has to act on is whether the branch is in, and a merge someone
 // made by hand between the failure and the read leaves `followup` with exactly the same work to
 // finish. REST offers nothing that would tell the two apart without keeping the merge commit's SHA
 // across a request that never answered.
-async function pr_merge(branch_name: string, head_sha: string): Promise<void> {
-	const pr_number = await require_pr_number(branch_name)
-
+async function merge_with_confirmation(
+	branch_name: string,
+	pr_number: number,
+	head_sha: string,
+): Promise<void> {
 	try {
 		await put_merge(pr_number, head_sha)
 	} catch (error) {
@@ -275,6 +295,14 @@ async function pr_merge(branch_name: string, head_sha: string): Promise<void> {
 	}
 }
 
+async function pr_merge(branch_name: string, head_sha: string): Promise<void> {
+	const pr_number = await require_pr_number(branch_name)
+
+	await gh_retry.with_retry(async () => {
+		await merge_with_confirmation(branch_name, pr_number, head_sha)
+	})
+}
+
 const git_gh_pr = {
 	...git_gh_pr_read,
 	...git_gh_pr_snapshot,
@@ -287,4 +315,10 @@ const git_gh_pr = {
 	is_head_moved,
 }
 
-export { git_gh_pr, MERGE_COMMIT_METHOD, MERGE_REQUEST_TIMEOUT_MS, MERGE_UNCONFIRMED_MESSAGE }
+export {
+	git_gh_pr,
+	MERGE_COMMIT_METHOD,
+	MERGE_IN_PROGRESS_ATTEMPTS,
+	MERGE_REQUEST_TIMEOUT_MS,
+	MERGE_UNCONFIRMED_MESSAGE,
+}

package/scripts/gh/git-gh-rate-limit.ts

@@ -0,0 +1,91 @@
+import { error_text } from '#scripts/lib/error-message'
+import { git_gh_exec } from './git-gh-exec'
+
+// Whether a failed GitHub read failed on an exhausted rate limit, and when it resets (#6564). While
+// the limit is spent, `gh auth status` itself reports the token invalid, so the auth hint sent a lane
+// child into an authentication stop. The single classifier `issue:read` (#6614) and `run:merge`
+// (#6502) are to share.
+//
+// The input is text — gh's stderr summary and the response body (`to_gh_error`), headers under
+// `--include`, or a stop record — so a reader holding no error object can classify it too.
+
+const FORBIDDEN_STATUS = 403
+const TOO_MANY_REQUESTS_STATUS = 429
+const RATE_LIMIT_STATUSES: ReadonlySet<number> = new Set([
+	FORBIDDEN_STATUS,
+	TOO_MANY_REQUESTS_STATUS,
+])
+const MILLISECONDS_PER_SECOND = 1000
+// GitHub's own wording for the primary and the secondary limit, in the body and in gh's summary.
+const RATE_LIMIT_MESSAGE = /rate limit (?:already )?exceeded|exceeded a secondary rate limit/iu
+const EXHAUSTED_HEADER = /^x-ratelimit-remaining:\s*0\s*$/imu
+const RESET_HEADER = /^x-ratelimit-reset:\s*(?<epoch>\d+)\s*$/imu
+// gh's summary `(HTTP 403)`, a header status line `HTTP/2.0 403 Forbidden`, or the error document's
+// `"status": "403"`.
+const STATUS_PATTERNS: ReadonlyArray<RegExp> = [
+	/\(HTTP (?<status>\d{3})\)/u,
+	/^HTTP\/\S+ (?<status>\d{3})/mu,
+	/"status":\s*"?(?<status>\d{3})/u,
+]
+const AUTH_HINT = 'check `gh auth status` and the network'
+
+function status_of(text: string): number | undefined {
+	const status = STATUS_PATTERNS.map((pattern) => pattern.exec(text)?.groups?.['status']).find(
+		(found) => found !== undefined,
+	)
+
+	return status === undefined ? undefined : Number(status)
+}
+
+// A limited status alone is not enough — a 403 is also an org policy or a missing scope — so the
+// limit has to be named, by GitHub's message or by a spent `x-ratelimit-remaining`.
+function is_exhausted(text: string): boolean {
+	if (RATE_LIMIT_MESSAGE.test(text)) return true
+	const status = status_of(text)
+
+	return status !== undefined && RATE_LIMIT_STATUSES.has(status) && EXHAUSTED_HEADER.test(text)
+}
+
+function epoch_to_date(epoch: string | undefined): Date | undefined {
+	const seconds = Number(epoch)
+	if (epoch === undefined || !Number.isSafeInteger(seconds) || seconds <= 0) return undefined
+
+	return new Date(seconds * MILLISECONDS_PER_SECOND)
+}
+
+// `GET /rate_limit` does not count against the limit it reports. A failed read answers `undefined`.
+async function read_reset(): Promise<Date | undefined> {
+	try {
+		const epoch = await git_gh_exec.exec_gh_api({
+			path: 'rate_limit',
+			jq_filter: '.resources.core.reset',
+			should_retry: false,
+		})
+
+		return epoch_to_date(epoch.trim())
+	} catch (error) {
+		error_text.trace_swallowed('gh_rate_limit.read_reset', error)
+
+		return undefined
+	}
+}
+
+function exhausted_message(resets_at: Date | undefined): string {
+	const when = resets_at === undefined ? 'at an unread time' : `at ${resets_at.toISOString()}`
+
+	return `GitHub rate limit exhausted, resets ${when} — wait for the reset; this is not an authentication failure, so do not refresh gh auth`
+}
+
+// The hint beside a failed GitHub read; the reset comes from the response headers when present.
+async function failure_hint(text: string): Promise<string> {
+	if (!is_exhausted(text)) return AUTH_HINT
+
+	const resets_at =
+		epoch_to_date(RESET_HEADER.exec(text)?.groups?.['epoch']) ?? (await read_reset())
+
+	return exhausted_message(resets_at)
+}
+
+const gh_rate_limit = { AUTH_HINT, exhausted_message, failure_hint, is_exhausted }
+
+export { gh_rate_limit }

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

@@ -1,35 +1,52 @@
+import { repo_party } from '#scripts/discovery/repo-party'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { error_text } from '#scripts/lib/error-message'
+import { z } from 'zod'
 import { 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_etag_read } from './git-gh-etag-read'
+import { gh_rate_limit } from './git-gh-rate-limit'
 
 // `owner/repo` for the repository the session runs in.
 //
-// Read through REST rather than `gh repo view --json nameWithOwner`: the `gh <noun> <verb>` form
-// goes through GraphQL, which a cloud session is refused outright (403), so this read answered
-// `undefined` there and every caller needing the name inherited that answer.
+// Resolved locally first (joshuafolkken/kit#6752): `gh` expands `{owner}/{repo}` from `GH_REPO` or the
+// remotes, so reading it back cost one REST call per process. `current_repository` answers nothing
+// where `gh`'s pick is ambiguous or unreadable; only then the REST read (not GraphQL, which a cloud
+// session is refused), through the ETag layer. A failed read is `undefined`, except an exhausted rate
+// limit, which is thrown rather than read as "no repository".
 //
-// The pull-request reads no longer go through it at all: they address `repos/{owner}/{repo}` and
-// name the head filter's owner as `{owner}` too, which `gh api` expands inside a query string as
-// readily as inside a path. That keeps six branch-keyed reads from gaining a second way to fail, and
-// it is what makes `pr_get_review_comments` REST end to end. The remaining
-// caller is the completion notification, which puts the name in its Telegram body.
-//
-// The failure contract is unchanged: `undefined` when the read fails, for a caller that has nothing
-// better to do with the error than treat the name as unknown.
-async function repo_get_name_with_owner(): Promise<string | undefined> {
+// The local slug is the remote as typed — another case, or a renamed repository's old name — so a
+// caller matching it against a name GitHub returned reads `repo_get_canonical_name_with_owner`.
+
+const repository_schema = z.object({ full_name: z.string() })
+
+function local_name_with_owner(): string | undefined {
+	const identity = repo_party.current_repository()
+
+	return identity === undefined ? undefined : `${identity.owner}/${identity.repo}`
+}
+
+async function repo_get_canonical_name_with_owner(): Promise<string | undefined> {
 	try {
-		const result: string = await git_gh_exec.exec_gh_api({
-			path: git_gh_api_path.repo_api_path(),
-			jq_filter: '.full_name',
-		})
+		const body = await git_gh_etag_read.read(git_gh_api_path.repo_api_path())
+		const name = parse_json
+			.parse_json_object_or_undefined(body, repository_schema)
+			?.full_name.trim()
+
+		return name === '' ? undefined : name
+	} catch (error) {
+		if (gh_rate_limit.is_exhausted(error_text.message_of(error))) throw error
+		error_text.trace_swallowed('git_gh_repo.repo_get_name_with_owner', error)
 
-		return git_gh_helpers.parse_pr_state_string(result)
-	} catch {
 		return undefined
 	}
 }
 
+async function repo_get_name_with_owner(): Promise<string | undefined> {
+	return local_name_with_owner() ?? (await repo_get_canonical_name_with_owner())
+}
+
 const git_gh_repo = {
+	repo_get_canonical_name_with_owner,
 	repo_get_name_with_owner,
 }
 

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

@@ -3,9 +3,8 @@ import { get_exit_code, has_timed_out } from '#scripts/git/git-execa-error'
 import { error_text } from '#scripts/lib/error-message'
 import { gh_failure } from './git-gh-failure'
 
-// One REST request asked again, a bounded number of times, when GitHub failed it transiently
-// (joshuafolkken/kit#4717). A single 502 on `review:record --comment` used to stop a whole ship stage
-// and cost a relaunched session that changed nothing; the same request seconds later succeeds.
+// Bounded retries keep a transient GitHub failure from stopping a ship stage that needs no code
+// change (joshuafolkken/kit#4717).
 //
 // **Transient is a 5xx or a request that got no answer at all** — a dropped connection writes no
 // error document, so its status is `undefined`. A 4xx is the request's own fault and answers the same
@@ -17,10 +16,10 @@ import { gh_failure } from './git-gh-failure'
 //
 // **A retried write can land twice** when the first attempt reached GitHub before it failed. The
 // writes on this path tolerate it: a duplicate pull request is refused with the 422 the creator reads
-// (`handle_pr_create_error`), a repeated merge is read back by `has_merge_landed`, and at worst a
-// review-round comment is posted twice — cheaper than the stopped stage it replaces. Issue creation
-// has no such guard — a second issue opens and nothing reads the first back — so
-// `issue_create_request` opts out with `should_retry: false`.
+// (`handle_pr_create_error`), and at worst a
+// review-round comment is posted twice — cheaper than the stopped stage it replaces. Merge requests
+// opt out so their caller reads the result before another write; issue creation opts out because a
+// second issue opens and nothing reads the first back.
 
 const FIRST_RETRY_DELAY_MS = 2000
 const SECOND_RETRY_DELAY_MS = 5000
@@ -65,25 +64,37 @@ function has_answer(spawn_error: unknown): boolean {
 	return typeof spawn_error.stdout === 'string' && spawn_error.stdout.trim().length > 0
 }
 
-function is_transient_status(status: number | undefined, spawn_error: unknown): boolean {
+function is_transient_status(
+	status: number | undefined,
+	spawn_error: unknown,
+	is_read: boolean,
+): boolean {
+	if (is_read && has_timed_out(spawn_error)) return true
 	if (status === undefined) return !has_answer(spawn_error)
 
 	return status >= SERVER_ERROR_FLOOR
 }
 
-// A spawn no wait can change: one it killed on its budget, or one gh refused before asking.
-function is_final_spawn(spawn_error: unknown): boolean {
-	return has_timed_out(spawn_error) || get_exit_code(spawn_error) === GH_AUTH_REQUIRED_EXIT_CODE
+// A timed-out write may have landed; a read can safely be repeated. Auth never improves by waiting.
+function is_final_spawn(spawn_error: unknown, is_read: boolean): boolean {
+	return (
+		(!is_read && has_timed_out(spawn_error)) ||
+		get_exit_code(spawn_error) === GH_AUTH_REQUIRED_EXIT_CODE
+	)
 }
 
-function is_transient(error: unknown): boolean {
+function is_transient_request(error: unknown, is_read: boolean): boolean {
 	const failure = gh_failure.failure_of(error)
 
 	if (failure === undefined || !(error instanceof Error)) return false
 
 	const status = failure.status ?? summary_status(error)
 
-	return !is_final_spawn(error.cause) && is_transient_status(status, error.cause)
+	return !is_final_spawn(error.cause, is_read) && is_transient_status(status, error.cause, is_read)
+}
+
+function is_transient(error: unknown): boolean {
+	return is_transient_request(error, false)
 }
 
 function first_line(error: unknown): string {
@@ -98,8 +109,8 @@ function retry_note(error: unknown, attempt: number, wait_ms: number): string {
 
 // The wait before asking again, or `undefined` when this failure is final — not transient, or the
 // last attempt spent.
-function retry_delay(error: unknown, attempt: number): number | undefined {
-	return is_transient(error) ? RETRY_DELAYS_MS[attempt - 1] : undefined
+function retry_delay(error: unknown, attempt: number, is_read: boolean): number | undefined {
+	return is_transient_request(error, is_read) ? RETRY_DELAYS_MS[attempt - 1] : undefined
 }
 
 // The line a request transient to its last attempt leaves on stderr, naming the failure by the first
@@ -109,33 +120,58 @@ function spent_note(message: string): string {
 	return `${SPENT_NOTE} (${message})`
 }
 
-function note_spent(error: unknown, attempt: number, hooks: RetryHooks): void {
-	if (attempt === MAX_ATTEMPTS && is_transient(error)) hooks.note(spent_note(first_line(error)))
+function note_spent(error: unknown, attempt: number, hooks: RetryHooks, is_read: boolean): void {
+	if (attempt === MAX_ATTEMPTS && is_transient_request(error, is_read)) {
+		hooks.note(spent_note(first_line(error)))
+	}
 }
 
-async function with_retry<T>(
+async function retry_request<T>(
 	request: () => Promise<T>,
-	hooks: RetryHooks = DEFAULT_HOOKS,
-	attempt = 1,
+	hooks: RetryHooks,
+	attempt: number,
+	is_read: boolean,
 ): Promise<T> {
 	try {
 		return await request()
 	} catch (error) {
-		const wait_ms = retry_delay(error, attempt)
+		const wait_ms = retry_delay(error, attempt, is_read)
 
 		if (wait_ms === undefined) {
-			note_spent(error, attempt, hooks)
+			note_spent(error, attempt, hooks, is_read)
 			throw error
 		}
 
 		hooks.note(retry_note(error, attempt, wait_ms))
 		await hooks.wait(wait_ms)
 
-		return await with_retry(request, hooks, attempt + 1)
+		return await retry_request(request, hooks, attempt + 1, is_read)
 	}
 }
 
-const gh_retry = { MAX_ATTEMPTS, RETRY_DELAYS_MS, is_transient, spent_note, with_retry }
+async function with_retry<T>(
+	request: () => Promise<T>,
+	hooks: RetryHooks = DEFAULT_HOOKS,
+	attempt = 1,
+): Promise<T> {
+	return await retry_request(request, hooks, attempt, false)
+}
+
+async function with_read_retry<T>(
+	request: () => Promise<T>,
+	hooks: RetryHooks = DEFAULT_HOOKS,
+): Promise<T> {
+	return await retry_request(request, hooks, 1, true)
+}
+
+const gh_retry = {
+	MAX_ATTEMPTS,
+	RETRY_DELAYS_MS,
+	is_transient,
+	spent_note,
+	with_retry,
+	with_read_retry,
+}
 
 export type { RetryHooks }
 export { gh_retry }

package/scripts/gh/git-gh-spawn-width.ts

@@ -0,0 +1,6 @@
+// One width for every asynchronous `gh` spawn, so `Promise.all` fan-outs anywhere (`backlog:next`
+// reads up to hundreds) stay under GitHub's secondary rate limit. Kept apart from `git-gh-exec.ts`
+// so a test that mocks the spawn layer wholesale does not take the width away from its callers.
+const GH_SPAWN_CONCURRENCY = 8
+
+export { GH_SPAWN_CONCURRENCY }