@joshuafolkken/kit 1.2116.0 → 1.3041.0

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

@@ -0,0 +1,213 @@
+import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
+import { error_text } from '#scripts/lib/error-message'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { git_gh_exec } from './git-gh-exec'
+import { gh_failure } from './git-gh-failure'
+import { gh_rate_limit } from './git-gh-rate-limit'
+
+// Which transport a session's GitHub reads take (joshuafolkken/kit#6784): GraphQL, metered apart
+// from the 5,000-per-hour REST core budget, or REST alone where GraphQL is refused (a cloud session
+// answers 403). The one place a GraphQL read is sent and its refusal handled — a reader asks `query`
+// and reads REST on `undefined`, with no fallback of its own.
+//
+// `JOSH_GH_TRANSPORT` picks it:
+// - `auto` (the default): one `viewer` probe (1 point) per hour, kept in the shared cache under the
+//   gh host and login, so every process and lane of the repository reuses it. A later 403 switches
+//   the record to `rest` for the rest of the hour.
+// - `rest`: no GraphQL request is sent.
+// - `graphql`: a refusal is a stop with its reason, never a silent REST read.
+//
+// A failure other than a refusal (one unresolvable id fails a whole `nodes` document, a timeout) is
+// that one read's, so it reads through REST without changing the session's transport.
+
+const TRANSPORT_ENV_VAR = 'JOSH_GH_TRANSPORT'
+const GRAPHQL_PATH = 'graphql'
+const FORBIDDEN_STATUS = 403
+const MS_KEPT = 3_600_000
+const DEFAULT_HOST = 'github.com'
+const PROBE_QUERY = 'query { viewer { login } }'
+const NOT_PROBED = 'not probed'
+
+const TRANSPORT_CACHE: CacheSlot = { prefix: 'josh-gh-transport-', ttl_ms: MS_KEPT }
+
+const REFUSED_MESSAGE = `GitHub refused a GraphQL read, and ${TRANSPORT_ENV_VAR}=graphql forbids reading it through REST — set it to auto or rest to read where GraphQL is refused`
+
+const partial_document_schema = z.looseObject({
+	data: z.looseObject({}),
+	errors: z.array(z.unknown()).nonempty(),
+})
+
+const transport_schema = z.enum(['graphql', 'rest'])
+const setting_schema = z.enum(['auto', 'graphql', 'rest'])
+
+type Transport = z.infer<typeof transport_schema>
+type TransportSetting = z.infer<typeof setting_schema>
+
+interface GraphqlBody {
+	query: string
+	variables?: object
+}
+
+// One `gh config get` per host and process: the login the cache record is keyed under.
+const logins = new Map<string, Promise<string>>()
+
+function parse_setting(raw: string | undefined): TransportSetting | undefined {
+	if (raw === undefined || raw === '') return 'auto'
+
+	return setting_schema.safeParse(raw).data
+}
+
+function setting(): TransportSetting {
+	const raw = process.env[TRANSPORT_ENV_VAR]
+	const parsed = parse_setting(raw)
+
+	if (parsed === undefined) {
+		throw new Error(`${TRANSPORT_ENV_VAR} must be auto, graphql or rest, not ${String(raw)}`)
+	}
+
+	return parsed
+}
+
+async function read_login(host: string): Promise<string> {
+	try {
+		return await git_gh_exec.exec_gh_command(['config', 'get', 'user', '--host', host])
+	} catch {
+		return ''
+	}
+}
+
+async function key_of(): Promise<string> {
+	const host = process.env['GH_HOST'] ?? DEFAULT_HOST
+	const login = logins.get(host) ?? read_login(host)
+
+	logins.set(host, login)
+
+	return `${host}/${await login}`
+}
+
+// A 403 that names a rate limit is that one read's throttling, not a refusal of the session.
+function is_refused(error: unknown): boolean {
+	if (gh_failure.failure_of(error)?.status !== FORBIDDEN_STATUS) return false
+
+	return !gh_rate_limit.is_exhausted(error_text.message_of(error))
+}
+
+async function send(body: GraphqlBody): Promise<string> {
+	return await git_gh_exec.exec_gh_api({ path: GRAPHQL_PATH, body: JSON.stringify(body) })
+}
+
+// `undefined` is a failure that says nothing about the session, which is probed again next time.
+async function probe(): Promise<Transport | undefined> {
+	try {
+		await send({ query: PROBE_QUERY })
+
+		return 'graphql'
+	} catch (error) {
+		return is_refused(error) ? 'rest' : undefined
+	}
+}
+
+async function current(now_ms: number = Date.now()): Promise<Transport> {
+	const chosen = setting()
+	if (chosen !== 'auto') return chosen
+
+	const request = { slot: TRANSPORT_CACHE, key: await key_of(), schema: transport_schema }
+
+	return (await shared_cache.remember(request, probe, now_ms)) ?? 'graphql'
+}
+
+async function on_failure(error: unknown, now_ms: number): Promise<void> {
+	if (!is_refused(error)) return
+	if (setting() === 'graphql') throw new Error(REFUSED_MESSAGE, { cause: error })
+
+	shared_cache.write(TRANSPORT_CACHE, await key_of(), 'rest' satisfies Transport, now_ms)
+}
+
+// What a failed read still answers: the partial document `query_partial` keeps; absent, nothing.
+type Recovered = (error: unknown) => string | undefined
+
+// A document whose `errors` sit beside answered `data` — one alias that resolved to nothing.
+function partial_answer(error: unknown): string | undefined {
+	const body = gh_failure.body_of(error)
+	if (body === undefined) return undefined
+
+	return json_value.parse_with(body, partial_document_schema) === undefined ? undefined : body
+}
+
+async function sent_or_failed(
+	body: GraphqlBody,
+	now_ms: number,
+	recovered?: Recovered,
+): Promise<string | undefined> {
+	try {
+		return await send(body)
+	} catch (error) {
+		await on_failure(error, now_ms)
+
+		return recovered?.(error)
+	}
+}
+
+async function answer_of(
+	body: GraphqlBody,
+	now_ms: number,
+	recovered?: Recovered,
+): Promise<string | undefined> {
+	if ((await current(now_ms)) === 'rest') return undefined
+
+	return await sent_or_failed(body, now_ms, recovered)
+}
+
+// The answer's JSON, or `undefined` for the caller to read through REST.
+async function query(body: GraphqlBody, now_ms: number = Date.now()): Promise<string | undefined> {
+	return await answer_of(body, now_ms)
+}
+
+// `query`, but a document with `errors` beside non-null `data` is the answer, for a reader whose
+// unanswered aliases are `null` and read through REST one by one (joshuafolkken/kit#6964).
+async function query_partial(
+	body: GraphqlBody,
+	now_ms: number = Date.now(),
+): Promise<string | undefined> {
+	return await answer_of(body, now_ms, partial_answer)
+}
+
+async function kept(now_ms: number): Promise<Transport | undefined> {
+	return shared_cache.read(TRANSPORT_CACHE, await key_of(), transport_schema, now_ms)
+}
+
+// The session's transport as far as it is known without a probe: the explicit setting, the kept
+// answer under `auto`, or `undefined` (not probed this hour, or an invalid setting).
+async function known(now_ms: number = Date.now()): Promise<Transport | undefined> {
+	const chosen = parse_setting(process.env[TRANSPORT_ENV_VAR])
+	if (chosen === undefined) return undefined
+
+	return chosen === 'auto' ? await kept(now_ms) : chosen
+}
+
+// The session's transport for a display, read without a probe: `graphql (auto)`, `not probed (auto)`.
+async function label(now_ms: number = Date.now()): Promise<string> {
+	const chosen = parse_setting(process.env[TRANSPORT_ENV_VAR])
+	if (chosen === undefined) return `invalid ${TRANSPORT_ENV_VAR}`
+	if (chosen !== 'auto') return chosen
+
+	return `${(await kept(now_ms)) ?? NOT_PROBED} (auto)`
+}
+
+function forget_logins(): void {
+	logins.clear()
+}
+
+const git_gh_transport = {
+	current,
+	forget_logins,
+	known,
+	label,
+	query,
+	query_partial,
+	TRANSPORT_CACHE,
+}
+
+export type { GraphqlBody, Transport }
+export { git_gh_transport, GRAPHQL_PATH, PROBE_QUERY, REFUSED_MESSAGE, TRANSPORT_ENV_VAR }

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

@@ -1,6 +1,7 @@
 // cspell:words coderabbit coderabbitai
 import { ai_review_pull_comment_schema } from '#scripts/git/git-schemas'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { gh_comment_input } from './gh-comment-input'
 import {
 	classify_ai_review_comments,
 	type ClassifiedFinding,
@@ -35,9 +36,11 @@ function to_review_comment(raw: AiReviewPullComment): ReviewComment {
 }
 
 function format_ai_review_finding(finding: ClassifiedFinding): string {
-	const suffix = finding.url === undefined ? '' : ` — ${finding.url}`
-
-	return `- ${finding.author_login}: ${finding.summary}${suffix}`
+	return gh_comment_input.format({
+		author: finding.author_login,
+		body: finding.summary,
+		url: finding.url,
+	})
 }
 
 // Temporary: CodeRabbit findings are surfaced as console info and audit notes for the
@@ -52,7 +55,7 @@ function log_info_findings(infos: ReadonlyArray<ClassifiedFinding>): Array<strin
 		console.warn(format_ai_review_finding(info))
 	}
 
-	return infos.map((info) => `CodeRabbit skipped (kit#753): ${info.summary}`)
+	return infos.map((info) => `CodeRabbit skipped (kit#753): ${format_ai_review_finding(info)}`)
 }
 
 function build_ai_review_blocker_body(blockers: ReadonlyArray<ClassifiedFinding>): string {
@@ -76,7 +79,7 @@ function build_ai_review_ignore_comment(
 	]
 
 	for (const blocker of blockers) {
-		lines.push(`- ${blocker.author_login}: ${blocker.summary} (${blocker.url ?? 'no-url'})`)
+		lines.push(format_ai_review_finding(blocker))
 	}
 
 	return lines.join('\n')

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

@@ -1,3 +1,8 @@
+import {
+	collect_missing_contexts,
+	describe_missing_context,
+	is_required_match,
+} from './git-pr-checks-missing'
 import {
 	CHECK_STATUS_FAIL,
 	CHECK_STATUS_MISSING,
@@ -37,10 +42,6 @@ const MERGE_STATE_UNSTABLE = 'UNSTABLE'
 // that no amount of waiting resolves, so it ends the wait rather than polling through it.
 const MERGE_STATE_DIRTY = 'DIRTY'
 const REVIEW_CHANGES_REQUESTED = 'CHANGES_REQUESTED'
-// GitHub reports a check-suite job as `<App> / <Job>` (e.g. `CodeRabbit / Review`). A required
-// check name matches that suite when it is the `<App>` segment, so the required-check list stays the
-// bare app name even after the provider renames its job.
-const CHECK_SUITE_SEPARATOR = ' / '
 const FAILURE_MESSAGE_PREFIX = 'PR checks failed'
 const FAILURE_REASON_REVIEW = 'review requested changes'
 const FAILURE_REASON_CHECKS = 'failed checks'
@@ -48,15 +49,6 @@ const FAILURE_REASON_CONFLICT = 'merge conflict'
 
 type PrEvaluation = 'success' | 'pending' | 'failure'
 
-// A required check matches either its exact context name or a check-suite job nested under it
-// (`<required> / <job>`). The separator keeps the prefix anchored, so an unrelated context such as
-// `CodeRabbitNightly` does not satisfy a required `CodeRabbit`.
-function is_required_match(check_name: string, required_name: string): boolean {
-	if (check_name === required_name) return true
-
-	return check_name.startsWith(`${required_name}${CHECK_SUITE_SEPARATOR}`)
-}
-
 function find_required_check(
 	checks: ReadonlyArray<RollupCheck>,
 	required_name: string,
@@ -82,9 +74,10 @@ function is_review_blocked(review_decision: string | undefined): boolean {
 //
 // **`BLOCKED` is deliberately not here.** GitHub reports it while a required check is merely queued,
 // which is every healthy pull request for its first seconds. Treating it as a conflict is safe only
-// after the checks have settled; there is no such moment on this path, and a green-but-`BLOCKED`
-// pull request (branch protection requiring a review, which this repository does not set)
-// therefore reaches the timeout rather than a named failure.
+// after the checks have settled; there is no such moment on this path. A required context with no
+// check-run is named once the gap outlasts a grace window (`git-pr-checks-missing.ts`), while a
+// green-but-`BLOCKED` pull request held by a required review (which this repository does not set)
+// still reaches the timeout.
 function is_merge_conflict(merge_state_status: string | undefined): boolean {
 	return merge_state_status === MERGE_STATE_DIRTY
 }
@@ -212,6 +205,9 @@ function collect_failure_reasons(snapshot: PrStateSnapshot): Array<string> {
 	if (is_review_blocked(snapshot.review_decision)) reasons.push(FAILURE_REASON_REVIEW)
 	const failed = collect_blocking_failures(snapshot)
 	if (failed.length > 0) reasons.push(`${FAILURE_REASON_CHECKS}: ${failed.join(', ')}`)
+	reasons.push(
+		...collect_missing_contexts(snapshot).map((context) => describe_missing_context(context)),
+	)
 
 	return reasons
 }
@@ -223,11 +219,12 @@ function describe_pr_failure(snapshot: PrStateSnapshot): string {
 	return `${FAILURE_MESSAGE_PREFIX} (${reasons.join('; ')}).`
 }
 
+// A required context with no check-run fails like a failed check (`git-pr-checks-missing.ts`).
 function evaluate_pr_state(snapshot: PrStateSnapshot): PrEvaluation {
 	const statuses = read_required_statuses(snapshot.rollup)
 	const failure = evaluate_failure_state({
 		review_decision: snapshot.review_decision,
-		failed_checks: collect_blocking_failures(snapshot),
+		failed_checks: [...collect_blocking_failures(snapshot), ...collect_missing_contexts(snapshot)],
 		merge_state_status: snapshot.merge_state_status,
 	})
 
@@ -303,5 +300,7 @@ export {
 	CODERABBIT_CHECK_NAME,
 	is_required_check,
 	is_merge_conflict,
+	is_mergeable_state,
+	matches_any,
 }
 export type { PrEvaluation }

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

@@ -0,0 +1,24 @@
+import { FAILURE_REASON_CHECKS } from './git-pr-checks-eval'
+
+// The check names a failed checks wait reported — `git-pr-checks-eval.ts`'s `PR checks failed
+// (failed checks: <a>, <b>; …).` — read back by `josh lane:why` from a ship log and by `josh ship` into
+// a followup `check` stop's record (joshuafolkken/kit#7333). The list ends at the next reason or the
+// closing `).`, so a matrix name such as `Unit Tests (3/6)` stays whole.
+
+const FAILED_CHECKS = new RegExp(
+	String.raw`${FAILURE_REASON_CHECKS}: (?<names>.+?)(?=; |\)\.$)`,
+	'gmu',
+)
+const NAME_SEPARATOR = ', '
+
+// Every check name `text` lists as failed, in order, each list read whole.
+function names_of(text: string): Array<string> {
+	return [...text.matchAll(FAILED_CHECKS)]
+		.flatMap((match) => (match.groups?.['names'] ?? '').split(NAME_SEPARATOR))
+		.map((name) => name.trim())
+		.filter((name) => name !== '')
+}
+
+const git_pr_checks_failed = { names_of }
+
+export { git_pr_checks_failed }

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

@@ -0,0 +1,129 @@
+// **A CI completion wait reads its full snapshot only when the head's checks moved**
+// (joshuafolkken/kit#7238). Each poll first asks the head's two commit listings — `check-runs` and
+// `status` — with their ETags; a 304 from both is a poll where CI did not move, so the last snapshot
+// answers it and the GraphQL session spends no query. A 304 still counts as a read, so the
+// stable-read window advances on it exactly as on an unchanged full read.
+//
+// **The listings are asked by the branch, not by the last `head_sha`.** A push during the wait moves
+// the branch; the old commit's listings would answer 304 for ever and keep a verdict on what is no
+// longer the head. The combined status names its `sha`, so a moved head changes its ETag.
+//
+// **Answers the probe cannot vouch for, so the poll reads anyway:**
+// - Anything once no check is pending. The probe only says CI has not moved; after CI settles the
+//   merge state still moves on its own (a lagging `BLOCKED` turning `CLEAN`, a base move to
+//   `DIRTY`), so only a snapshot that still waits on a running check is reused.
+// - `mergeable_state` is computed late and moves without the pull request's ETag moving
+//   (joshuafolkken/kit#4589, joshuafolkken/kit#6721), so a snapshot whose merge state is not yet
+//   known is never reused.
+// - A review decision the predicate wants this poll is not in the commit listings.
+// - A probe that could not be read is taken as changed.
+//
+// The ETags a probe took are kept only once the full read after it succeeded, so a read that throws
+// never leaves a 304 vouching for a snapshot that was not taken.
+import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_conditional, type ConditionalRead } from './git-gh-conditional'
+import { CHECK_STATUS_PENDING, type PrStateSnapshot } from './git-pr-checks-parse'
+
+// Whether this poll has to read the review listing, asked of the snapshot *without* one. It is a
+// question about the current poll rather than a cache key: answering `false` skips one request now
+// and nothing is carried into the next poll.
+type ReviewDecisionPredicate = (snapshot: PrStateSnapshot) => boolean
+
+type PrStateFetcher = (
+	branch_name: string,
+	should_read_review_decision: ReviewDecisionPredicate,
+) => Promise<PrStateSnapshot>
+
+type EtagsByPath = ReadonlyMap<string, string | undefined>
+
+interface HeadProbe {
+	is_unchanged: boolean
+	etags: EtagsByPath
+}
+
+interface GateState {
+	last: PrStateSnapshot | undefined
+	etags: EtagsByPath
+}
+
+const MERGE_STATE_UNKNOWN = 'UNKNOWN'
+
+function probe_paths(branch_name: string): Array<string> {
+	const reference = encodeURIComponent(branch_name)
+
+	return [
+		`${git_gh_api_path.commit_check_runs_api_path(reference)}${FULL_PAGE_QUERY}`,
+		git_gh_api_path.commit_status_api_path(reference),
+	]
+}
+
+// A 304 keeps the ETag it was asked with; a listing that could not be read keeps none, so the next
+// probe reads it whole.
+function next_etag(read: ConditionalRead, previous: string | undefined): string | undefined {
+	if (read.kind === 'unchanged') return previous
+
+	return read.kind === 'changed' ? read.etag : undefined
+}
+
+async function probe_head(branch_name: string, etags: EtagsByPath): Promise<HeadProbe> {
+	const reads = await Promise.all(
+		probe_paths(branch_name).map(async (path) => ({
+			path,
+			read: await git_gh_conditional.read_conditional(path, etags.get(path)),
+		})),
+	)
+
+	return {
+		is_unchanged: reads.every(({ read }) => read.kind === 'unchanged'),
+		etags: new Map(reads.map(({ path, read }) => [path, next_etag(read, etags.get(path))])),
+	}
+}
+
+function is_merge_state_known(snapshot: PrStateSnapshot): boolean {
+	const status = snapshot.merge_state_status
+
+	return status !== undefined && status.toUpperCase() !== MERGE_STATE_UNKNOWN
+}
+
+function is_ci_running(snapshot: PrStateSnapshot): boolean {
+	return snapshot.rollup.some((check) => check.status === CHECK_STATUS_PENDING)
+}
+
+function can_reuse(snapshot: PrStateSnapshot, should_read: ReviewDecisionPredicate): boolean {
+	return is_ci_running(snapshot) && is_merge_state_known(snapshot) && !should_read(snapshot)
+}
+
+// The last snapshot where it can answer an unchanged poll, otherwise `undefined`.
+function reusable(
+	last: PrStateSnapshot | undefined,
+	should_read: ReviewDecisionPredicate,
+): PrStateSnapshot | undefined {
+	return last !== undefined && can_reuse(last, should_read) ? last : undefined
+}
+
+// One gate per wait: the last snapshot and the ETags are that wait's, never shared between two.
+function gate_fetcher(inner: PrStateFetcher): PrStateFetcher {
+	const state: GateState = { last: undefined, etags: new Map() }
+
+	return async function fetch_gated(
+		branch_name: string,
+		should_read_review_decision: ReviewDecisionPredicate,
+	): Promise<PrStateSnapshot> {
+		const probe = await probe_head(branch_name, state.etags)
+		const reused = probe.is_unchanged
+			? reusable(state.last, should_read_review_decision)
+			: undefined
+		if (reused !== undefined) return reused
+
+		const snapshot = await inner(branch_name, should_read_review_decision)
+
+		Object.assign(state, { last: snapshot, etags: probe.etags })
+
+		return snapshot
+	}
+}
+
+const git_pr_checks_gate = { gate_fetcher }
+
+export { git_pr_checks_gate }
+export type { PrStateFetcher, ReviewDecisionPredicate }

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

@@ -0,0 +1,165 @@
+import { CHECK_STATUS_PENDING, type PrStateSnapshot, type RollupCheck } from './git-pr-checks-parse'
+
+// **A context the base branch requires that has no check-run once every other check has settled**
+// (joshuafolkken/kit#5774). GitHub holds such a pull request `BLOCKED` forever while every check it
+// does show is green, so the wait read it as `pending` and ran its whole 32-minute budget out into a
+// timeout that named nothing — a partial rerun had dropped the required `Checks` job from its run's
+// latest attempt. Naming it ends the wait once the gap has outlasted a grace window.
+//
+// **The required list is the base branch's rules** (`git-gh-branch-rules.ts`), the list GitHub blocks
+// the merge on. With no rule known nothing is missing, so an unreadable ruleset keeps the wait exactly
+// as it was. A `CLEAN` pull request has met its requirements whatever the rollup shows, and a rollup
+// with a check still pending may yet register the missing one, so neither is a failure.
+//
+// **A gap on one read is not yet a missing context.** GitHub creates a `needs:`-gated job's check-run
+// only once its prerequisites finish (`Checks`, `E2E`), and an outside app's check (`SonarCloud Code
+// Analysis`) can trail the job that triggered it — so a healthy run shows every check settled with a
+// required one absent for a few seconds. The gap therefore has to hold for `MISSING_GRACE_MS` on the
+// same head before it is named. What is remembered can only delay a failure, never produce a success,
+// and a read where the context is present or a check is pending again forgets it.
+const MISSING_GRACE_MS = 120_000
+
+// GitHub reports a check-suite job as `<App> / <Job>` (e.g. `CodeRabbit / Review`). A required
+// check name matches that suite when it is the `<App>` segment, so the required-check list stays the
+// bare app name even after the provider renames its job.
+const CHECK_SUITE_SEPARATOR = ' / '
+const MERGE_STATE_CLEAN = 'CLEAN'
+
+// A required check matches either its exact context name or a check-suite job nested under it
+// (`<required> / <job>`). The separator keeps the prefix anchored, so an unrelated context such as
+// `CodeRabbitNightly` does not satisfy a required `CodeRabbit`.
+function is_required_match(check_name: string, required_name: string): boolean {
+	if (check_name === required_name) return true
+
+	return check_name.startsWith(`${required_name}${CHECK_SUITE_SEPARATOR}`)
+}
+
+function is_settled(rollup: ReadonlyArray<RollupCheck>): boolean {
+	return rollup.length > 0 && rollup.every((check) => check.status !== CHECK_STATUS_PENDING)
+}
+
+// When each head's context was first read settled and absent, keyed `<head sha> <context>`.
+const first_absent_at = new Map<string, number>()
+
+function forget_missing_contexts(): void {
+	first_absent_at.clear()
+}
+
+function absence_key(snapshot: PrStateSnapshot, context: string): string {
+	return `${snapshot.head_sha ?? ''} ${context}`
+}
+
+function has_outlasted_grace(key: string, now: number): boolean {
+	const first = first_absent_at.get(key)
+	if (first !== undefined) return now - first >= MISSING_GRACE_MS
+	first_absent_at.set(key, now)
+
+	return false
+}
+
+function absent_from(
+	rollup: ReadonlyArray<RollupCheck>,
+	required: ReadonlyArray<string>,
+): Array<string> {
+	return required.filter((context) =>
+		rollup.every((check) => !is_required_match(check.name, context)),
+	)
+}
+
+function collect_absent_contexts(snapshot: PrStateSnapshot): Array<string> {
+	if (snapshot.merge_state_status === MERGE_STATE_CLEAN || !is_settled(snapshot.rollup)) return []
+
+	return absent_from(snapshot.rollup, snapshot.required_contexts ?? [])
+}
+
+function forget_present_contexts(snapshot: PrStateSnapshot, absent: ReadonlyArray<string>): void {
+	const present = (snapshot.required_contexts ?? []).filter((context) => !absent.includes(context))
+	for (const context of present) first_absent_at.delete(absence_key(snapshot, context))
+}
+
+function collect_missing_contexts(snapshot: PrStateSnapshot): Array<string> {
+	const absent = collect_absent_contexts(snapshot)
+
+	forget_present_contexts(snapshot, absent)
+	const now = Date.now()
+
+	return absent.filter((context) => has_outlasted_grace(absence_key(snapshot, context), now))
+}
+
+function describe_missing_context(context: string): string {
+	return `required context ${context} has no check-run`
+}
+
+// **The failure a missing context ends the wait with**, typed so `followup` can rerun the whole run
+// that lost the job (joshuafolkken/kit#5778): no failed job is left for `rerun-failed-jobs` to retry.
+interface MissingContexts {
+	contexts: ReadonlyArray<string>
+	head_sha: string
+}
+
+class MissingContextError extends Error {
+	override name = 'MissingContextError'
+	readonly missing: MissingContexts
+
+	constructor(message: string, options: ErrorOptions & { missing: MissingContexts }) {
+		super(message, options)
+		this.missing = options.missing
+	}
+}
+
+// Read after the verdict named the gap, so the grace window it asks again has already run out.
+function missing_context_error(
+	message: string,
+	snapshot: PrStateSnapshot,
+): MissingContextError | undefined {
+	const contexts = collect_missing_contexts(snapshot)
+	if (contexts.length === 0 || snapshot.head_sha === undefined) return undefined
+
+	return new MissingContextError(message, { missing: { contexts, head_sha: snapshot.head_sha } })
+}
+
+// **Why a wait that ran out of budget was still waiting** (joshuafolkken/kit#5780): the required checks
+// and the base branch's required contexts the last read showed no check-run for — or, with none
+// absent, the merge state GitHub held the pull request in. Read without the grace window, since the
+// wait is already over. A `josh ship` park carries the line as its cause, so `run:board` shows it.
+const BLOCKED_LEAD = 'BLOCKED: '
+const MERGE_STATE_LEAD = 'mergeStateStatus: '
+
+// The required checks and the base branch's required contexts the snapshot holds no check-run for.
+function absent_required(
+	snapshot: PrStateSnapshot,
+	required_checks: ReadonlyArray<string>,
+): Array<string> {
+	const required = [...new Set([...required_checks, ...(snapshot.required_contexts ?? [])])]
+
+	return absent_from(snapshot.rollup, required)
+}
+
+function blocked_cause(
+	snapshot: PrStateSnapshot,
+	required_checks: ReadonlyArray<string>,
+): string | undefined {
+	const absent = absent_required(snapshot, required_checks)
+	if (absent.length > 0) return `${BLOCKED_LEAD}${absent.join(', ')} missing`
+	if (snapshot.merge_state_status === undefined) return undefined
+
+	return `${MERGE_STATE_LEAD}${snapshot.merge_state_status}`
+}
+
+function is_blocked_cause(message: string): boolean {
+	return message.startsWith(BLOCKED_LEAD) || message.startsWith(MERGE_STATE_LEAD)
+}
+
+export {
+	absent_required,
+	blocked_cause,
+	collect_missing_contexts,
+	describe_missing_context,
+	forget_missing_contexts,
+	is_blocked_cause,
+	is_required_match,
+	missing_context_error,
+	MISSING_GRACE_MS,
+	MissingContextError,
+	type MissingContexts,
+}

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

@@ -52,6 +52,9 @@ interface PrStateSnapshot {
 	// 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>
+	// `true` once the pull request is merged, which the auto-merge wait reads off this snapshot rather
+	// than a second detail read (joshuafolkken/kit#6721). Absent otherwise.
+	is_merged?: boolean
 }
 
 function read_string(value: unknown): string | undefined {
@@ -152,6 +155,7 @@ function parse_pr_state_snapshot(raw_json: string): PrStateSnapshot {
 		rollup: parse_rollup_checks(raw_json),
 		merge_state_status: read_string(data.mergeStateStatus),
 		review_decision: read_string(data.reviewDecision),
+		...(data.merged === true && { is_merged: true }),
 	}
 
 	return with_required_contexts(