@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -27,7 +27,7 @@ import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
 // branch name that says nothing about which repository holds it. Named once
 // because both sides of a pull request carry the same shape.
 const rest_repo_schema = z.looseObject({ full_name: z.string().optional() }).nullish()
-const rest_pull_side_schema = z.looseObject({ repo: rest_repo_schema })
+const rest_pull_side_schema = z.looseObject({ ref: z.string().optional(), repo: rest_repo_schema })
 
 type RestPullSide = z.infer<typeof rest_pull_side_schema>
 
@@ -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

@@ -1,12 +1,16 @@
 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 { read_pull, require_pr_number } from './git-gh-pr-read'
+import { git_gh_poll_read } from './git-gh-poll-read'
+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
@@ -19,17 +23,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'
 
-// Both commit endpoints answer an *object* wrapping the listing, so `--paginate` alone would emit
-// one document per page and `JSON.parse` would reject the pair; `--slurp` wraps the pages in one
-// outer array instead (`git-gh-exec.ts` → `GhApiRequest`).
-async function read_object_pages(path: string): Promise<string> {
-	return await git_gh_exec.exec_gh_api({
-		path: `${path}${FULL_PAGE_QUERY}`,
-		should_paginate: true,
-		should_slurp: true,
-	})
-}
-
 // 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> {
@@ -47,11 +40,12 @@ function read_head_sha(pull: RestPull): string {
 }
 
 // One pull request's rollup: the check runs and the status contexts, read from the head commit and
-// merged back into the single array `gh` answered with.
+// merged back into the single array `gh` answered with. Both endpoints answer an *object* wrapping the
+// listing, so their pages arrive slurped into one outer array (`git-gh-poll-read.ts`).
 async function read_status_check_rollup(commit_sha: string): Promise<Array<object>> {
 	const [check_runs_json, status_json] = await Promise.all([
-		read_object_pages(git_gh_api_path.commit_check_runs_api_path(commit_sha)),
-		read_object_pages(git_gh_api_path.commit_status_api_path(commit_sha)),
+		git_gh_poll_read.read_object_pages(git_gh_api_path.commit_check_runs_api_path(commit_sha)),
+		git_gh_poll_read.read_object_pages(git_gh_api_path.commit_status_api_path(commit_sha)),
 	])
 
 	return git_gh_pr_rollup.to_status_check_rollup({ check_runs_json, status_json })
@@ -69,10 +63,24 @@ async function pr_get_review_decision(pr_number: number): Promise<string> {
 // `git-pr-checks-eval.ts` compares strictly against: `MERGE_STATE_CLEAN` never matches a lower-case
 // `clean`, which would also take every pull request out of the CodeRabbit non-blocking exemption
 // keyed on `UNSTABLE`. The rule is shared with `to_pr_info` rather than written twice.
+//
+// **`headRefOid` is the commit the rollup was read from**, in `gh`'s spelling, so a merge can be bound
+// to the head whose checks passed rather than to whatever the branch points at by then (#4036).
+//
+// **`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.
 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([
+		read_status_check_rollup(head_sha),
+		git_gh_branch_rules.read_required_contexts(pull.base?.ref),
+	])
+
 	return {
-		statusCheckRollup: await read_status_check_rollup(read_head_sha(pull)),
+		statusCheckRollup: rollup,
 		mergeStateStatus: to_gh_state(pull.mergeable_state),
+		headRefOid: head_sha,
+		requiredContexts: required_contexts,
 	}
 }
 
@@ -81,12 +89,32 @@ interface ResolvedPull {
 	pull: RestPull
 }
 
-// The resolution and the detail read, which every path below needs and which the branch → number
-// memo in `git-gh-pr-read.ts` makes free after the first poll.
+// 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 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)
 
-	return { pr_number, pull: await read_pull(pr_number) }
+	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

@@ -1,12 +1,18 @@
 import { pr_classification, type ReleaseClassification } from '#scripts/ci/pr-classification'
 import { git_command } from '#scripts/git/git-command'
 import { poll } from '#scripts/lib/poll'
-import { z } from 'zod'
 import { git_gh_api_path } from './git-gh-api-path'
 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'
 
@@ -49,25 +55,27 @@ 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
+// `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
-const LABELS_SEGMENT = '/labels'
-const PR_LABELS = z.array(z.object({ name: z.string() }))
 
+// A pull request is an issue to the labels endpoint, so the write is the issue one: a failed answer
+// is confirmed by reading the labels back before it is reported as a failed write.
 async function add_pr_classification(number: string, label: ReleaseClassification): Promise<void> {
-	await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.issue_api_path(number)}${LABELS_SEGMENT}`,
-		body: JSON.stringify({ labels: [label] }),
-	})
+	const write = await git_gh_issue_write.issue_apply_label(number, label)
+
+	if (!write.is_applied) throw new Error(write.reason)
 }
 
+// Labels that could not be read are not "no classification": answering that would add a second
+// classification beside the one a person already put on the pull request.
 async function pr_get_classification(
 	branch_name: string,
 ): Promise<ReleaseClassification | undefined> {
 	const number = await require_pr_number(branch_name)
-	const response = await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.issue_api_path(String(number))}${LABELS_SEGMENT}`,
-	})
-	const names = PR_LABELS.parse(JSON.parse(response)).map((label) => label.name.toLowerCase())
+	const labels = await git_gh_issue_write.read_label_names(String(number))
+	if (labels === undefined) throw new Error(`Unreadable labels on branch ${branch_name}`)
+	const names = labels.map((name) => name.toLowerCase())
 	const selected = names.filter((name) => pr_classification.is_classification(name))
 	if (selected.length === 0) return undefined
 
@@ -166,21 +174,34 @@ async function pr_update_body(branch_name: string, body: string): Promise<void>
 }
 
 // A merge moves the remembered detail read's state, so it is cleared first.
-async function put_merge(pr_number: number): Promise<void> {
+//
+// **`sha` binds the merge to the head the checks passed on** (#4036): without it GitHub merges
+// whatever the branch points at, so a commit pushed after the gate went green would land unverified.
+// A head that moved is answered 409 (`is_head_moved`).
+async function put_merge(pr_number: number, head_sha: string): Promise<void> {
 	forget_pr_numbers()
 	await git_gh_exec.exec_gh_api({
 		path: git_gh_api_path.pull_merge_api_path(String(pr_number)),
 		method: PUT_METHOD,
-		body: JSON.stringify({ merge_method: MERGE_COMMIT_METHOD }),
+		body: JSON.stringify({ merge_method: MERGE_COMMIT_METHOD, sha: head_sha }),
 		timeout_ms: MERGE_REQUEST_TIMEOUT_MS,
 	})
 }
 
+// GitHub's answer to a merge whose `sha` is no longer the branch head.
+function is_head_moved(error: unknown): boolean {
+	return gh_failure.failure_of(error)?.status === HEAD_MOVED_STATUS
+}
+
 // `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
@@ -209,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
@@ -240,13 +265,13 @@ async function has_merge_landed(pr_number: number, merge_error: unknown): Promis
 // 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): Promise<void> {
+async function pr_merge(branch_name: string, head_sha: string): Promise<void> {
 	const pr_number = await require_pr_number(branch_name)
 
 	try {
-		await put_merge(pr_number)
+		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
 	}
 }
 
@@ -259,6 +284,7 @@ const git_gh_pr = {
 	pr_comment,
 	pr_merge,
 	pr_update_body,
+	is_head_moved,
 }
 
 export { git_gh_pr, MERGE_COMMIT_METHOD, MERGE_REQUEST_TIMEOUT_MS, MERGE_UNCONFIRMED_MESSAGE }

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

@@ -2,6 +2,7 @@ import {
 	CHECK_STATUS_FAIL,
 	CHECK_STATUS_MISSING,
 	CHECK_STATUS_PASS,
+	CHECK_STATUS_PENDING,
 	type PrStateSnapshot,
 	type RollupCheck,
 } from './git-pr-checks-parse'
@@ -12,7 +13,7 @@ import {
 // to restore the old behavior. Revert once the fresh-context review subagent replaces it.
 const DEFAULT_REQUIRED_CHECKS = ['SonarQube']
 // The single source of the check name every CodeRabbit exemption is keyed on — the merge gate's
-// `is_unstable_only_from_coderabbit`, the look-ahead's `is_awaited_check`, and the fixtures the two
+// `is_unstable_only_from_optional`, the look-ahead's `is_awaited_check`, and the fixtures the two
 // are tested from. A second literal spelling of it anywhere is how one of them silently stops
 // matching after CodeRabbit renames its context.
 const CODERABBIT_CHECK_NAME = 'CodeRabbit'
@@ -131,15 +132,46 @@ function is_coderabbit_rate_limited(check: RollupCheck): boolean {
 	)
 }
 
-// Temporary: a pending or failing CodeRabbit check makes GitHub report UNSTABLE even
-// though CodeRabbit is not required. Accept that state only when CodeRabbit checks are the
-// sole non-passing ones — any other non-passing check keeps the gate strict.
-function is_unstable_only_from_coderabbit(snapshot: PrStateSnapshot): boolean {
+function matches_any(check_name: string, required_names: ReadonlyArray<string>): boolean {
+	return required_names.some((required) => is_required_match(check_name, required))
+}
+
+// A check still running that the base branch's rules do not require — GitHub's default-setup
+// `CodeQL`, which runs for about thirty minutes beside a six-minute CI (joshuafolkken/kit#4351).
+// With no required context known nothing qualifies, so the gate waits for `CLEAN` as it always did.
+function is_optional_pending(
+	check: RollupCheck,
+	required_contexts: ReadonlyArray<string>,
+): boolean {
+	if (required_contexts.length === 0 || check.status !== CHECK_STATUS_PENDING) return false
+
+	return !matches_any(check.name, required_contexts)
+}
+
+function is_every_context_passing(
+	checks: ReadonlyArray<RollupCheck>,
+	contexts: ReadonlyArray<string>,
+): boolean {
+	return contexts.every(
+		(context) => find_required_check(checks, context)?.status === CHECK_STATUS_PASS,
+	)
+}
+
+// GitHub reports UNSTABLE for a pull request whose required checks are green while a check outside
+// them is pending or failing. Accept that state when every non-passing check is CodeRabbit's
+// (temporary: CodeRabbit is not required) or an optional one still running, and every context the
+// base branch requires has passed in the rollup itself — any other non-passing check keeps the gate
+// strict. A failed optional check never reaches here: `collect_blocking_failures` ends the wait first.
+function is_unstable_only_from_optional(snapshot: PrStateSnapshot): boolean {
 	if (snapshot.merge_state_status !== MERGE_STATE_UNSTABLE) return false
+	const required_contexts = snapshot.required_contexts ?? []
 	const non_passing = snapshot.rollup.filter((check) => check.status !== CHECK_STATUS_PASS)
 	if (non_passing.length === 0) return false
+	const is_tolerated = non_passing.every(
+		(check) => is_coderabbit_check(check.name) || is_optional_pending(check, required_contexts),
+	)
 
-	return non_passing.every((check) => is_coderabbit_check(check.name))
+	return is_tolerated && is_every_context_passing(snapshot.rollup, required_contexts)
 }
 
 function is_required_check(check_name: string): boolean {
@@ -169,7 +201,7 @@ function collect_blocking_failures(snapshot: PrStateSnapshot): Array<string> {
 function is_mergeable_state(snapshot: PrStateSnapshot): boolean {
 	if (is_merge_state_clean(snapshot.merge_state_status)) return true
 
-	return is_unstable_only_from_coderabbit(snapshot)
+	return is_unstable_only_from_optional(snapshot)
 }
 
 // The wait's own error text: naming the checks that failed is what turns a red `followup` into
@@ -255,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-parse.ts

@@ -1,5 +1,6 @@
 import { pr_raw_schema, type RollupItemData } from '#scripts/git/git-schemas'
 import { json_value } from '#scripts/lib/json-value'
+import type { z } from 'zod'
 
 const CHECK_STATUS_PASS = 'pass'
 const CHECK_STATUS_PENDING = 'pending'
@@ -9,8 +10,8 @@ const CHECK_STATUS_MISSING = 'missing'
 // GitHub reports a job whose `if:` condition was false as COMPLETED with conclusion `skipped`, and
 // counts it as satisfied for branch protection — a pull request reaches CLEAN with such jobs in its
 // rollup. Recording them as `fail` would disagree with GitHub itself, and it would disable the
-// CodeRabbit non-blocking exemption: `is_unstable_only_from_coderabbit` opens the gate only when
-// every non-passing check is CodeRabbit's, so kit's own conditional jobs (`auto-merge`, `E2E`,
+// CodeRabbit non-blocking exemption: `is_unstable_only_from_optional` opens the gate only when
+// every non-passing check is CodeRabbit's or an optional one still running, so kit's own conditional jobs (`auto-merge`, `E2E`,
 // `Notify Auto Tag`) would keep a slow review blocking the merge until the wait loop timed out. That
 // is invisible on fast reviews, where CLEAN short-circuits the predicate — it surfaces only on the
 // exact path the exemption exists to protect.
@@ -45,6 +46,12 @@ interface PrStateSnapshot {
 	rollup: Array<RollupCheck>
 	merge_state_status: string | undefined
 	review_decision: string | undefined
+	// The commit `rollup` was read from — the head a merge has to name so that it lands what passed and
+	// nothing pushed since (#4036). Absent where the snapshot carried none.
+	head_sha?: string
+	// The base branch's required status check contexts (joshuafolkken/kit#4351). Absent where the
+	// branch requires none or they could not be read, which keeps the merge gate waiting for `CLEAN`.
+	required_contexts?: Array<string>
 }
 
 function read_string(value: unknown): string | undefined {
@@ -118,16 +125,39 @@ function parse_rollup_checks(raw_json: string): Array<RollupCheck> {
 	return checks
 }
 
-function parse_pr_state_snapshot(raw_json: string): PrStateSnapshot {
-	const parsed = json_value.parse_or_undefined(raw_json)
-	const result = pr_raw_schema.safeParse(parsed)
-	const data = result.success ? result.data : undefined
+function with_head_sha(snapshot: PrStateSnapshot, head_sha: string | undefined): PrStateSnapshot {
+	return head_sha === undefined ? snapshot : { ...snapshot, head_sha }
+}
+
+function with_required_contexts(
+	snapshot: PrStateSnapshot,
+	required_contexts: Array<string> | undefined,
+): PrStateSnapshot {
+	if (required_contexts === undefined || required_contexts.length === 0) return snapshot
+
+	return { ...snapshot, required_contexts }
+}
 
-	return {
+type PrRawData = Partial<z.infer<typeof pr_raw_schema>>
+
+function read_pr_raw_data(raw_json: string): PrRawData {
+	const result = pr_raw_schema.safeParse(json_value.parse_or_undefined(raw_json))
+
+	return result.success ? result.data : {}
+}
+
+function parse_pr_state_snapshot(raw_json: string): PrStateSnapshot {
+	const data = read_pr_raw_data(raw_json)
+	const snapshot = {
 		rollup: parse_rollup_checks(raw_json),
-		merge_state_status: read_string(data?.mergeStateStatus),
-		review_decision: read_string(data?.reviewDecision),
+		merge_state_status: read_string(data.mergeStateStatus),
+		review_decision: read_string(data.reviewDecision),
 	}
+
+	return with_required_contexts(
+		with_head_sha(snapshot, read_string(data.headRefOid)),
+		data.requiredContexts,
+	)
 }
 
 export {