@joshuafolkken/kit 1.1784.0 → 1.2116.0

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

@@ -1,7 +1,10 @@
+import { error_text } from '#scripts/lib/error-message'
 import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { note_unreadable_comments } from './git-gh-comments-unreadable'
 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'
+import { git_gh_pr_too_large } from './git-gh-pr-too-large'
 import { to_gh_state } from './git-gh-rest-state'
 
 // Reading pull requests through REST, in the answers `gh pr view` gives.
@@ -61,10 +64,16 @@ function lookup_path(branch_name: string): string {
 	return `${git_gh_api_path.pulls_api_path()}?head=${head}&${LOOKUP_QUERY}`
 }
 
-async function fetch_pr_number(branch_name: string): Promise<number | undefined> {
+async function fetch_branch_pull(branch_name: string): Promise<RestPull | 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
+	return git_gh_pr_rest.select_pull(git_gh_pr_rest.parse_rest_pulls(json))
+}
+
+async function fetch_pr_number(branch_name: string): Promise<number | undefined> {
+	const pull = await fetch_branch_pull(branch_name)
+
+	return pull?.number
 }
 
 // Why the resolution produced no number. `missing` is the lookup answering: the listing came back and
@@ -80,7 +89,7 @@ interface PullMergeState {
 	is_merged: boolean
 	merged_at: string | undefined
 	head_sha: string | undefined
-	// `josh ship` reads `DIRTY` here to re-merge a conflicting pull request.
+	// GitHub's merge state (`DIRTY` on a conflict).
 	merge_state_status: string | undefined
 }
 
@@ -100,8 +109,8 @@ const pending_pr_number_by_branch = new Map<string, Promise<PullNumberRead>>()
 // same `GET /pulls/{N}` each time. 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, the rule the number memo holds.
 // **Every write to a pull request clears it** through `forget_pr_numbers`, and the two state readers
-// never read it: `pr_get_merge_state` answers where the pull request stands *now*, which `josh ship`
-// asks again after every merge it pushes, and `pr_view` decides whether `josh git -y` writes onto the
+// never read it: `pr_get_merge_state` answers where the pull request stands *now*, which `josh followup`
+// asks again after every merge `josh ship` pushes, and `pr_view` decides whether `josh git -y` writes onto the
 // pull request — after a commit and a push its preflight read would otherwise outlast.
 const pull_by_number = new Map<number, Promise<RestPull>>()
 
@@ -168,9 +177,12 @@ async function resolve_pr_number(branch_name: string): Promise<number | undefine
 }
 
 // One definition, because both callers that refuse to fold an unreadable lookup raise it —
-// `require_pr_number` and `pr_exists`.
+// `require_pr_number` and `pr_exists`. The cause's first line rides in the message: a reader that
+// prints only the message — the `josh git -y` preflight, a `josh ship` log — still says why.
 function to_unreadable_error(branch_name: string, cause: unknown): Error {
-	return new Error(`${UNREADABLE_PULL_REQUEST_MESSAGE}: ${branch_name}`, { cause })
+	const [gist = ''] = error_text.message_of(cause).split('\n', 1)
+
+	return new Error(`${UNREADABLE_PULL_REQUEST_MESSAGE}: ${branch_name} (${gist})`, { cause })
 }
 
 // The number for a caller that has nothing to fold an absence into. The reads above answer their own
@@ -213,6 +225,36 @@ async function read_remembered_pull(pr_number: number): Promise<RestPull> {
 	}
 }
 
+// The listing row for a detail read GitHub refused as too large (`git-gh-pr-too-large.ts`). The row
+// carries neither `mergeable` nor `mergeable_state`, which every reader of them already takes as
+// "not known yet". Any other failure — and a listing that no longer names the number — stays the
+// detail read's own `unreadable`.
+async function read_listed_pull(
+	detail_error: unknown,
+	branch_name: string,
+	pr_number: number,
+): Promise<RestPull | undefined> {
+	if (!git_gh_pr_too_large.is_too_many_files(detail_error)) return undefined
+	const pull = await fetch_branch_pull(branch_name)
+
+	return pull?.number === pr_number ? pull : undefined
+}
+
+async function read_pull_or_listed(
+	branch_name: string,
+	pr_number: number,
+	read: (pr_number: number) => Promise<RestPull>,
+): Promise<RestPull> {
+	try {
+		return await read(pr_number)
+	} catch (error) {
+		const listed = await read_listed_pull(error, branch_name, pr_number)
+		if (listed === undefined) throw error
+
+		return listed
+	}
+}
+
 // 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(
@@ -223,7 +265,10 @@ async function read_pull_of_branch(
 	if (number_read.kind !== 'read') return number_read
 
 	try {
-		return { kind: 'read', pull: await read(number_read.pr_number) }
+		return {
+			kind: 'read',
+			pull: await read_pull_or_listed(branch_name, number_read.pr_number, read),
+		}
 	} catch (error) {
 		return { kind: 'unreadable', cause: error }
 	}
@@ -301,25 +346,39 @@ async function pr_view(branch_name: string): Promise<string> {
 	return JSON.stringify(git_gh_pr_rest.to_pr_info(read.pull))
 }
 
+// gh's own reason for a lookup that never answered, or that the branch has no pull request at all.
+function unresolved_reason(read: Exclude<PullNumberRead, { kind: 'read' }>): string {
+	return read.kind === 'unreadable' ? error_text.message_of(read.cause) : NO_PULL_REQUEST_MESSAGE
+}
+
 // `undefined` when the listing could not be read — a failed request, or a PR whose number could not
 // be resolved. Not `'[]'`.
 //
 // The two are the same string to a caller, and the callers are the merge gate: a rate limit would
 // arrive as "no reviewer left a finding" and the PR merge with the gate never actually read.
 // 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.
+// the same misread — that one only failed to close something. Either failure warns its reason
+// (`git-gh-comments-unreadable.ts`).
 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}`
+	const read = await read_pr_number(branch_name)
+
+	if (read.kind !== 'read') {
+		note_unreadable_comments(branch_name, unresolved_reason(read))
+
+		return undefined
+	}
+
+	const path = `${to_path(String(read.pr_number))}${COMMENTS_QUERY}`
 
 	try {
 		return to_json(await git_gh_exec.exec_gh_api({ path, should_paginate: true }))
-	} catch {
+	} catch (error) {
+		note_unreadable_comments(branch_name, error_text.message_of(error))
+
 		return undefined
 	}
 }
@@ -362,7 +421,9 @@ export type { PullMergeState }
 export {
 	git_gh_pr_read,
 	forget_pr_numbers,
+	read_listed_pull,
 	read_pull,
+	read_pull_or_listed,
 	require_pr_number,
 	resolve_pr_number,
 	NO_PULL_REQUEST_MESSAGE,

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

@@ -145,7 +145,8 @@ function to_pr_info(pull: RestPull): Record<string, unknown> {
 
 // The conversation comments in the shape `gh pr view --json comments` answered with. A listing that
 // will not parse throws rather than answering an empty one — `git-pr-ai-review.ts` reads an empty
-// listing as "no reviewer left a finding" and merges.
+// listing as "no reviewer left a finding" and merges. `updatedAt` is when CodeRabbit last rewrote its
+// rate-limit notice, the moment its stated window counts from (joshuafolkken/kit#5289).
 function to_pr_comments(rest_json: string): Array<Record<string, unknown>> {
 	const parsed = parse_json_array_or_undefined(rest_json, rest_comment_schema)
 	if (parsed === undefined) throw new Error(NOT_A_COMMENT_LISTING_MESSAGE)
@@ -154,6 +155,7 @@ function to_pr_comments(rest_json: string): Array<Record<string, unknown>> {
 		body: comment.body ?? EMPTY_BODY,
 		url: comment.html_url,
 		author: { login: comment.user?.login },
+		updatedAt: comment.updated_at,
 	}))
 }
 

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

@@ -2,13 +2,15 @@ import { FULL_PAGE_QUERY, 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 { require_pr_number } from './git-gh-pr-read'
-import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
+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_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.
+// 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`).
 //
 // `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
@@ -93,13 +95,26 @@ interface ResolvedPull {
 // **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 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)
+	} catch (error) {
+		const listed = await read_listed_pull(error, branch_name, pr_number)
+		if (listed === undefined) throw error
+		const state = await git_gh_pr_graphql_state.read_merge_state_status(listed, error)
+
+		return { ...listed, mergeable_state: state }
+	}
+}
+
 async function resolve_pull(branch_name: string): Promise<ResolvedPull> {
 	const pr_number = await require_pr_number(branch_name)
-	const json = await git_gh_exec.exec_gh_api({
-		path: git_gh_api_path.pull_api_path(String(pr_number)),
-	})
 
-	return { pr_number, pull: git_gh_pr_rest.parse_rest_pull(json) }
+	return { pr_number, pull: await read_detail_or_listed(branch_name, pr_number) }
 }
 
 // Everything the snapshot carries except the review decision: three requests rather than four.

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

@@ -0,0 +1,20 @@
+import { error_text } from '#scripts/lib/error-message'
+import { gh_failure } from './git-gh-failure'
+
+// GitHub refuses the single-pull JSON (`GET /pulls/{N}`) of some pull requests with
+// `HTTP 422: … too many files changed`, every time, however few files the pull request changes — while
+// the listing, the files, the diff and GraphQL all answer for the same one (joshuafolkken/kit#5226).
+// The refusal is about that one response, so the branch-keyed reads fall back to the listing row
+// rather than reporting the pull request unreadable.
+const UNPROCESSABLE_STATUS = 422
+const TOO_MANY_FILES_TEXT = 'too many files changed'
+
+function is_too_many_files(error: unknown): boolean {
+	if (gh_failure.failure_of(error)?.status !== UNPROCESSABLE_STATUS) return false
+
+	return error_text.message_of(error).includes(TOO_MANY_FILES_TEXT)
+}
+
+const git_gh_pr_too_large = { is_too_many_files }
+
+export { git_gh_pr_too_large }

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

@@ -6,7 +6,13 @@ import { git_gh_exec } from './git-gh-exec'
 import { gh_failure } from './git-gh-failure'
 import { git_gh_helpers } from './git-gh-helpers'
 import { git_gh_issue_write } from './git-gh-issue-write'
-import { forget_pr_numbers, git_gh_pr_read, read_pull, require_pr_number } from './git-gh-pr-read'
+import {
+	forget_pr_numbers,
+	git_gh_pr_read,
+	read_pull,
+	read_pull_or_listed,
+	require_pr_number,
+} 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'
 
@@ -188,10 +194,14 @@ function is_head_moved(error: unknown): boolean {
 }
 
 // `undefined` is "nobody read it", kept apart from the `false` that means "the pull request is not
-// merged". Folding the two would report an unread state as a settled answer.
-async function read_merge_state(pr_number: number): Promise<boolean | undefined> {
+// merged". Folding the two would report an unread state as a settled answer. The listing row, which
+// carries `merged_at` too, stands in for a detail GitHub refuses as too many files changed.
+async function read_merge_state(
+	branch_name: string,
+	pr_number: number,
+): Promise<boolean | undefined> {
 	try {
-		return git_gh_pr_rest.is_merged(await read_pull(pr_number))
+		return git_gh_pr_rest.is_merged(await read_pull_or_listed(branch_name, pr_number, read_pull))
 	} catch (error) {
 		// The reason goes in the line, for the same reason the poll loop's warning carries one: the
 		// failure this throws below names the *merge* request as its cause, so without this an operator
@@ -220,10 +230,14 @@ async function sleep_between_read_backs(attempt: number): Promise<void> {
 // **A read that failed is still not an answer.** Out of attempts it throws rather than reporting
 // `false`, carrying the merge failure as its `cause`, so no run ever concludes "the merge did not
 // happen" from a read nobody got.
-async function has_merge_landed(pr_number: number, merge_error: unknown): Promise<boolean> {
+async function has_merge_landed(
+	branch_name: string,
+	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(pr_number)
+		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
@@ -257,7 +271,7 @@ async function pr_merge(branch_name: string, head_sha: string): Promise<void> {
 	try {
 		await put_merge(pr_number, head_sha)
 	} catch (error) {
-		if (!(await has_merge_landed(pr_number, error))) throw error
+		if (!(await has_merge_landed(branch_name, pr_number, error))) throw error
 	}
 }
 

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

@@ -0,0 +1,141 @@
+import { setTimeout as delay } from 'node:timers/promises'
+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.
+//
+// **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
+// the next time. Three failures without a status are still not retried: a timeout (it has already
+// spent a minute, and a write it killed may have landed — `GH_REQUEST_TIMEOUT_MS`'s note), an error
+// `to_gh_error` never built (gh missing, a refused body), which no wait can change, and one that wrote
+// a body anyway — a GraphQL `errors` document is served with a 200, so it names no status and is
+// still GitHub's answer.
+//
+// **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`.
+
+const FIRST_RETRY_DELAY_MS = 2000
+const SECOND_RETRY_DELAY_MS = 5000
+const RETRY_DELAYS_MS = [FIRST_RETRY_DELAY_MS, SECOND_RETRY_DELAY_MS]
+const MAX_ATTEMPTS = RETRY_DELAYS_MS.length + 1
+const SERVER_ERROR_FLOOR = 500
+// gh's own exit code for "authentication required" (`gh auth login`, no `GH_TOKEN`). It writes no
+// error document either, so without this it would read as a request that got no answer — and no
+// wait logs anyone in.
+const GH_AUTH_REQUIRED_EXIT_CODE = 4
+
+const SPENT_NOTE = 'gh: request failed transiently on every attempt'
+
+// gh's own summary line for a failed request, e.g. `gh: Server Error (HTTP 502)`. It is the only
+// place the status is written when the body is an HTML error page rather than GitHub's JSON document.
+const SUMMARY_STATUS_PATTERN = /\(HTTP (?<status>\d{3})\)/u
+
+interface RetryHooks {
+	wait: (milliseconds: number) => Promise<void>
+	note: (text: string) => void
+}
+
+const DEFAULT_HOOKS: RetryHooks = {
+	wait: async (milliseconds) => {
+		await delay(milliseconds)
+	},
+	note: (text) => {
+		process.stderr.write(`${text}\n`)
+	},
+}
+
+function summary_status(error: Error): number | undefined {
+	const { status } = SUMMARY_STATUS_PATTERN.exec(error.message)?.groups ?? {}
+
+	return status === undefined ? undefined : Number(status)
+}
+
+// Whether the failed spawn wrote a response body: a request that got no answer at all wrote none.
+function has_answer(spawn_error: unknown): boolean {
+	if (!(spawn_error instanceof Error) || !('stdout' in spawn_error)) return false
+
+	return typeof spawn_error.stdout === 'string' && spawn_error.stdout.trim().length > 0
+}
+
+function is_transient_status(status: number | undefined, spawn_error: unknown): boolean {
+	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
+}
+
+function is_transient(error: unknown): 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)
+}
+
+function first_line(error: unknown): string {
+	return error_text.message_of(error).split('\n', 1)[0] ?? ''
+}
+
+function retry_note(error: unknown, attempt: number, wait_ms: number): string {
+	const ordinal = `${String(attempt)}/${String(MAX_ATTEMPTS)}`
+
+	return `gh: request failed transiently (attempt ${ordinal}: ${first_line(error)}) — retrying in ${String(wait_ms)} ms`
+}
+
+// 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
+}
+
+// The line a request transient to its last attempt leaves on stderr, naming the failure by the first
+// line of its message: a stopped `josh ship` stage that ended on that failure reads it as the
+// infrastructure (joshuafolkken/kit#5052). A recovered retry writes none.
+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)))
+}
+
+async function with_retry<T>(
+	request: () => Promise<T>,
+	hooks: RetryHooks = DEFAULT_HOOKS,
+	attempt = 1,
+): Promise<T> {
+	try {
+		return await request()
+	} catch (error) {
+		const wait_ms = retry_delay(error, attempt)
+
+		if (wait_ms === undefined) {
+			note_spent(error, attempt, hooks)
+			throw error
+		}
+
+		hooks.note(retry_note(error, attempt, wait_ms))
+		await hooks.wait(wait_ms)
+
+		return await with_retry(request, hooks, attempt + 1)
+	}
+}
+
+const gh_retry = { MAX_ATTEMPTS, RETRY_DELAYS_MS, is_transient, spent_note, with_retry }
+
+export type { RetryHooks }
+export { gh_retry }

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

@@ -7,6 +7,7 @@ import {
 	type ReviewComment,
 } from './git-ai-review-scan'
 import { git_gh_command } from './git-gh-command'
+import { is_retry_pending, note_unreadable_stop } from './git-gh-comments-unreadable'
 import { git_pr_confirmation, has_ignore_reason, type TelegramContext } from './git-pr-confirmation'
 
 interface AiReviewPullComment {
@@ -132,6 +133,19 @@ const UNREADABLE_COMMENTS_BODY =
 // never read the gate reports exactly like one that read it and found nothing.
 const UNREADABLE_COMMENTS_NOTE = 'AI reviewer comments could not be read; the scan was bypassed.'
 
+// An attempt the ship will run again sends no confirmation; the final one does (is_retry_pending).
+async function confirm_unreadable_stop(context: TelegramContext): Promise<void> {
+	note_unreadable_stop()
+	if (is_retry_pending()) return
+
+	await git_pr_confirmation.notify_confirmation({
+		context,
+		body: UNREADABLE_COMMENTS_BODY,
+		recommended: 'Re-run `pnpm josh followup` once the comments can be read',
+		alternatives: [IGNORE_ALTERNATIVE],
+	})
+}
+
 async function handle_unreadable_comments(input: {
 	branch_name: string
 	ignore_reason: string | undefined
@@ -146,12 +160,7 @@ async function handle_unreadable_comments(input: {
 		return [UNREADABLE_COMMENTS_NOTE]
 	}
 
-	await git_pr_confirmation.notify_confirmation({
-		context: input.context,
-		body: UNREADABLE_COMMENTS_BODY,
-		recommended: 'Re-run `pnpm josh followup` once the comments can be read',
-		alternatives: [IGNORE_ALTERNATIVE],
-	})
+	await confirm_unreadable_stop(input.context)
 
 	throw new Error(UNREADABLE_COMMENTS_BODY)
 }

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

@@ -287,6 +287,9 @@ class PrConflictError extends Error {
 }
 
 export {
+	FAILURE_MESSAGE_PREFIX,
+	FAILURE_REASON_CHECKS,
+	FAILURE_REASON_CONFLICT,
 	PrConflictError,
 	evaluate_pr_state,
 	is_auto_merge_blocked,

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

@@ -48,10 +48,10 @@ function get_configured_max_attempts(): number {
 const CHECK_MAX_ATTEMPTS = get_configured_max_attempts()
 const DEFAULT_STABLE_READS = 2
 
-// One authoritative gate poll is enough once `pr_checks_watch` has already seen every check finish:
-// the watch is the first confirmation, so the poll that follows need only agree once. The two reads
-// exist for the pending→settled window a bare poll opens on, and the watch has itself already spanned
-// that window — so waiting a second interval after it merely re-proves what the watch established.
+// One authoritative gate poll is enough once `pr_checks_watch` has returned — every check finished, or
+// its budget ran out on a pending read. The two reads exist for the pending→settled window a bare poll
+// opens on, and a returned watch has either spanned that window or seen its pending side, which the
+// poll's first settled read then closes — so a second interval merely re-proves it (#5080).
 const WATCH_CONFIRMED_STABLE_READS = 1
 
 // **A read that failed is not a verdict.** The loop reads every ten seconds, so a dropped connection,
@@ -314,7 +314,7 @@ async function default_fetch_pr_state(
 }
 
 // **`required_stable_reads` is a parameter, not a constant, so the caller can lower it** — `run_checks`
-// passes `WATCH_CONFIRMED_STABLE_READS` when the watch already confirmed completion. It defaults to
+// passes `WATCH_CONFIRMED_STABLE_READS` when the watch returned. It defaults to
 // `DEFAULT_STABLE_READS`, so every caller that names only the branch is exactly where it was.
 // What a caller is shown of each poll it waits on — `followup` reports the checks to the run's event
 // stream from it (joshuafolkken/kit#3770). It decides nothing: the wait reads the same snapshot.

package/scripts/git/base-tree.ts

@@ -1,3 +1,4 @@
+import { rmSync } from 'node:fs'
 import { copyFile, mkdir, mkdtemp, rm, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
@@ -13,6 +14,12 @@ import { git_worktree } from './git-worktree'
 
 const TREE_NAME = 'tree'
 const NODE_MODULES = 'node_modules'
+const TERMINATE_SIGNAL = 'SIGTERM'
+// 128 + SIGTERM's 15: the code the process would have exited with had no listener caught the signal.
+const TERMINATED_EXIT_CODE = 143
+
+// The temp directories of the trees this process holds now.
+const live_parents = new Set<string>()
 
 interface BaseTree {
 	// The temp directory holding the tree — a file written here sits beside the tree, never in it.
@@ -43,6 +50,26 @@ async function remove(base_tree: BaseTree): Promise<void> {
 	}
 }
 
+// **A terminated run removes its trees before it exits** (joshuafolkken/kit#4794): `josh run:review
+// --join` stops a `test:pinned` that fell behind, and a `finally` never runs past a signal, so each
+// tree would stay in the temp directory and in `git worktree list`. The removal is synchronous because
+// the process exits right after it; the next `with_tree`'s prune drops the registrations.
+function remove_live_trees(): void {
+	for (const parent of live_parents) rmSync(parent, { force: true, recursive: true })
+
+	process.exit(TERMINATED_EXIT_CODE)
+}
+
+function track(parent: string): void {
+	if (live_parents.size === 0) process.on(TERMINATE_SIGNAL, remove_live_trees)
+	live_parents.add(parent)
+}
+
+function untrack(parent: string): void {
+	live_parents.delete(parent)
+	if (live_parents.size === 0) process.off(TERMINATE_SIGNAL, remove_live_trees)
+}
+
 async function with_tree<T>(
 	prefix: string,
 	commit: string,
@@ -51,12 +78,15 @@ async function with_tree<T>(
 	const parent = await mkdtemp(path.join(tmpdir(), prefix))
 	const base_tree = { parent, tree: path.join(parent, TREE_NAME) }
 
+	track(parent)
+
 	try {
 		await prepare(base_tree.tree, commit)
 
 		return await use(base_tree)
 	} finally {
 		await remove(base_tree)
+		untrack(parent)
 	}
 }
 

package/scripts/git/change-base.ts

@@ -1,4 +1,5 @@
 import { git_command } from './git-command'
+import { git_diff_reads } from './git-diff-reads'
 import { git_spawn } from './git-spawn'
 
 // **The change base as a commit, or nothing — never a ref name**.
@@ -22,29 +23,22 @@ async function resolved(): Promise<string | undefined> {
 	}
 }
 
-const MERGE_BASE_COMMAND = 'merge-base'
-const MERGE_HEAD = 'MERGE_HEAD'
-const LINE_BREAK = '\n'
-
 // Where the side a merge in progress brings in left the default branch — `undefined` where no merge
 // is in progress, which is every ordinary run.
 async function incoming_base(): Promise<string | undefined> {
 	try {
 		const reference = await git_command.default_branch_reference()
 
-		return await git_spawn.read([MERGE_BASE_COMMAND, reference, MERGE_HEAD])
+		return await git_spawn.read([...git_diff_reads.incoming_base_arguments(reference)])
 	} catch {
 		return undefined
 	}
 }
 
-// `--independent` drops every commit another one listed reaches, so of two commits on the default
-// branch's history it keeps the later.
 async function later_of(base: string, incoming: string): Promise<string> {
-	const kept = await git_spawn.read([MERGE_BASE_COMMAND, '--independent', base, incoming])
-	const [later = base] = kept.split(LINE_BREAK)
+	const kept = await git_spawn.read([...git_diff_reads.later_base_arguments(base, incoming)])
 
-	return later
+	return git_diff_reads.later_base_of(kept, base)
 }
 
 // **The base of the tree, not of `HEAD`, while a merge is in progress.** A merge of the default