@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -36,7 +36,6 @@ const LABEL_NAMES_FILTER = '.[].name'
 const LABELS_SEGMENT = '/labels'
 const COMMENTS_SEGMENT = '/comments'
 const CLOSED_STATE = 'closed'
-const NOT_PLANNED_REASON = 'not_planned'
 const COLOR_HASH = '#'
 const UNPROCESSABLE_STATUS = 422
 const ALREADY_EXISTS_CODE = 'already_exists'
@@ -57,21 +56,39 @@ async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean
 	}
 }
 
-async function issue_edit_body(issue_number: string, body: string): Promise<string> {
+async function issue_patch(
+	issue_number: string,
+	fields: Readonly<Record<string, string>>,
+	repo?: string,
+): Promise<string> {
 	return await git_gh_exec.exec_gh_api({
-		path: git_gh_api_path.issue_api_path(issue_number),
+		path: git_gh_api_path.issue_api_path(issue_number, repo),
 		method: PATCH_METHOD,
-		body: JSON.stringify({ body }),
+		body: JSON.stringify(fields),
 		jq_filter: HTML_URL_FILTER,
 	})
 }
 
+// The optional `repo` (`owner/name`) on these writes addresses an issue in another repository; left
+// out, the path keeps gh's `{owner}/{repo}` placeholder — the checkout's own repository.
+async function issue_edit_body(issue_number: string, body: string, repo?: string): Promise<string> {
+	return await issue_patch(issue_number, { body }, repo)
+}
+
+async function issue_edit_title(
+	issue_number: string,
+	title: string,
+	repo?: string,
+): Promise<string> {
+	return await issue_patch(issue_number, { title }, repo)
+}
+
 // **Every comment josh posts carries `RUN_MARKER`**, an HTML comment GitHub does not render. A run
 // posts under the person's own `gh` login, so the marker is the only thing that tells the issue watch
 // (`issue-watch-diff.ts`) a run's comment from a person's update.
-async function issue_comment(issue_number: string, body: string): Promise<string> {
+async function issue_comment(issue_number: string, body: string, repo?: string): Promise<string> {
 	return await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.issue_api_path(issue_number)}${COMMENTS_SEGMENT}`,
+		path: `${git_gh_api_path.issue_api_path(issue_number, repo)}${COMMENTS_SEGMENT}`,
 		body: JSON.stringify({ body: `${body}\n\n${issue_watch_diff.RUN_MARKER}` }),
 		jq_filter: HTML_URL_FILTER,
 	})
@@ -119,18 +136,6 @@ async function issue_close(issue_number: string, comment: string | undefined): P
 	return await close_with(issue_number, comment, { state: CLOSED_STATE })
 }
 
-// The same close as "not planned" — the reason `issue-merged.ts` reads as no merge, so a closed issue
-// that was withdrawn is never taken for one whose work landed.
-async function issue_close_not_planned(
-	issue_number: string,
-	comment: string | undefined,
-): Promise<boolean> {
-	return await close_with(issue_number, comment, {
-		state: CLOSED_STATE,
-		state_reason: NOT_PLANNED_REASON,
-	})
-}
-
 // REST answers 422 `{"resource":"Label","code":"invalid","field":"color"}` for a color carrying a
 // leading `#`. The one caller passes the hash form (`EPIC_LABEL_COLOR`), so dropping it here is what
 // keeps that call site unchanged.
@@ -225,12 +230,16 @@ async function issue_create_with_label(input: {
 // say why it refused.
 type LabelWrite = { is_applied: true } | { is_applied: false; reason: string }
 
-// The issue's label names, read back after a failed write. A read that itself fails answers
-// `undefined`, which the caller treats as "not applied" — the write's own error is the reason then.
-async function read_label_names(issue_number: string): Promise<Array<string> | undefined> {
+// The issue's label names, every page of them — read back after a failed write, and by a pull
+// request's classification read. A read that itself fails answers `undefined`, which the write
+// treats as "not applied" — its own error is the reason then.
+async function read_label_names(
+	issue_number: string,
+	repo?: string,
+): Promise<Array<string> | undefined> {
 	try {
 		const raw = await git_gh_exec.exec_gh_api({
-			path: `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`,
+			path: git_gh_api_path.issue_labels_api_path(issue_number, repo),
 			should_paginate: true,
 			jq_filter: LABEL_NAMES_FILTER,
 		})
@@ -247,15 +256,19 @@ async function read_label_names(issue_number: string): Promise<Array<string> | u
 // after the write or a secondary rate limit can each throw after the label landed — which refused a
 // lane dispatch whose label was in fact applied. So a throw is confirmed by
 // reading the labels back, and only a label that is really absent answers `is_applied: false`.
-async function issue_apply_label(issue_number: string, label: string): Promise<LabelWrite> {
-	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
+async function issue_apply_label(
+	issue_number: string,
+	label: string,
+	repo?: string,
+): Promise<LabelWrite> {
+	const labels_path = git_gh_api_path.issue_labels_api_path(issue_number, repo)
 
 	try {
 		await git_gh_exec.exec_gh_api({ path: labels_path, body: JSON.stringify({ labels: [label] }) })
 
 		return { is_applied: true }
 	} catch (error) {
-		const names = await read_label_names(issue_number)
+		const names = await read_label_names(issue_number, repo)
 
 		if (names?.includes(label) === true) return { is_applied: true }
 		error_text.trace_swallowed('git_gh_issue_write.issue_apply_label', error)
@@ -271,8 +284,12 @@ async function issue_apply_label(issue_number: string, label: string): Promise<L
 // Applied after the body edit so a failure leaves an issue with the epic sections and no label,
 // which `epic:check` reports — rather than a labelled issue with nothing to track. The caller checks
 // the return: the label is what the auto-close filters on.
-async function issue_add_label(issue_number: string, label: string): Promise<boolean> {
-	const write = await issue_apply_label(issue_number, label)
+async function issue_add_label(
+	issue_number: string,
+	label: string,
+	repo?: string,
+): Promise<boolean> {
+	const write = await issue_apply_label(issue_number, label, repo)
 
 	return write.is_applied
 }
@@ -287,7 +304,7 @@ async function issue_add_label(issue_number: string, label: string): Promise<boo
 // a `false` swallowed here would reach that guard as a success and the step would be reported as
 // done.
 async function issue_remove_label(issue_number: string, label: string): Promise<void> {
-	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
+	const labels_path = git_gh_api_path.issue_labels_api_path(issue_number)
 
 	await git_gh_exec.exec_gh_api({
 		path: `${labels_path}/${encodeURIComponent(label)}`,
@@ -295,6 +312,25 @@ async function issue_remove_label(issue_number: string, label: string): Promise<
 	})
 }
 
+// **The removal for a caller that wants the label gone, not removed by this call** — a release that
+// may find the label already off. A failed DELETE is confirmed against the labels the issue carries,
+// the read `issue_apply_label` confirms an addition with, so an absent label answers `true` and a
+// failure that left the label on answers `false`.
+async function issue_clear_label(issue_number: string, label: string): Promise<boolean> {
+	try {
+		await issue_remove_label(issue_number, label)
+
+		return true
+	} catch (error) {
+		const names = await read_label_names(issue_number)
+
+		if (names?.includes(label) === false) return true
+		error_text.trace_swallowed('git_gh_issue_write.issue_clear_label', error)
+
+		return false
+	}
+}
+
 // The blocker's **database id**, which is the only thing the dependencies endpoint accepts — and the
 // reason this resolution exists rather than the issue number being sent straight through.
 //
@@ -354,16 +390,18 @@ async function issue_remove_blocked_by(issue_number: string, blocker: string): P
 
 const git_gh_issue_write = {
 	issue_edit_body,
+	issue_edit_title,
 	issue_comment,
 	issue_try_comment,
 	issue_close,
-	issue_close_not_planned,
 	label_ensure,
 	issue_create_request,
 	issue_create_with_label,
+	read_label_names,
 	issue_apply_label,
 	issue_add_label,
 	issue_remove_label,
+	issue_clear_label,
 	issue_add_blocked_by,
 	issue_remove_blocked_by,
 }

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

@@ -4,6 +4,9 @@ import { BLOCKED_BY_COUNT_FIELD } from './git-gh-issue-rest'
 import { git_gh_issue_write } from './git-gh-issue-write'
 
 const NUMBER_AND_BODY_FIELDS = 'number,body'
+// The label listing's fields. `stateReason` rides along on the same response: the epic auto-close
+// reads `reopened` off it, so its sweep leaves an epic a person reopened to them (#4564).
+const LABELLED_FIELDS = 'number,body,stateReason'
 // The backlog scan's fields. The title rides along because the pre-filing scan compares titles
 // and it costs nothing: the same listing request already carries it, so the
 // two consumers share one read rather than each making their own.
@@ -111,7 +114,7 @@ async function issue_search_body(term: string, limit: number): Promise<IssueList
 }
 
 async function issue_list_by_label(label: string, limit: number): Promise<IssueListOutcome> {
-	return await issue_list({ json_fields: NUMBER_AND_BODY_FIELDS, limit, label })
+	return await issue_list({ json_fields: LABELLED_FIELDS, limit, label })
 }
 
 // The same filter with the fields the `auto-ok` pickup needs: it orders by
@@ -151,8 +154,9 @@ async function issue_list_by_label_in_repo(
 }
 
 // Every open issue with what `josh auto-ok:judge` judges it by — its labels and body — and `updatedAt`,
-// so the backlog driver's resident check reads an issue's comments again only once it has moved.
-const JUDGEMENT_FIELDS = 'number,title,body,labels,updatedAt'
+// so the backlog driver's resident check reads an issue's comments again only once it has moved; and
+// `author_association` and `user`, so an issue a third party filed is never judged.
+const JUDGEMENT_FIELDS = 'number,title,body,labels,updatedAt,author_association,user'
 
 async function issue_list_open_for_judgement(limit: number): Promise<IssueListOutcome> {
 	return await issue_list({ json_fields: JUDGEMENT_FIELDS, limit })

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

@@ -0,0 +1,89 @@
+import { error_text } from '#scripts/lib/error-message'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { FULL_PAGE_QUERY } from './git-gh-api-path'
+import { git_gh_conditional, type ConditionalRead } from './git-gh-conditional'
+import { git_gh_exec } from './git-gh-exec'
+
+// The merge gate's per-poll reads, each sent with the ETag of this process's previous answer
+// (joshuafolkken/kit#4550).
+//
+// **Never a pull request's detail**: GitHub computes its `mergeable_state` lazily, under an unchanged
+// ETag, so a 304 would keep a stale state (joshuafolkken/kit#4589).
+//
+// **`pnpm josh followup` reads the same pull request every 10 seconds** while its checks run, and
+// every lane waiting on its merge does so at once. A `304 Not Modified` does not count against the
+// rate limit, so a poll that finds nothing changed costs only its pull detail read.
+//
+// **A listing is read one page at a time only while it fits in one.** A listing longer than a page is
+// read through `--paginate --slurp` as before; the conditional read cannot page, and a partial
+// listing would drop checks from the verdict.
+
+const UNREADABLE_POLL_MESSAGE = 'gh api could not read a merge-gate poll'
+const PAGE_SIZE = 100
+
+interface KeptAnswer {
+	etag: string
+	body: string
+}
+
+const kept_by_path = new Map<string, KeptAnswer>()
+
+const page_schema = z.object({ total_count: z.number() })
+
+// gh's own failure rides along as the cause and in the message: the poll loop's warning prints the
+// message alone, and a rate limit must read differently there from expired auth.
+function unreadable(path: string, answer: ConditionalRead): Error {
+	const cause = answer.kind === 'unreadable' ? answer.cause : undefined
+	const reason = cause === undefined ? '' : `: ${error_text.message_of(cause)}`
+
+	return new Error(`${UNREADABLE_POLL_MESSAGE}: ${path}${reason}`, { cause })
+}
+
+function to_body(path: string, answer: ConditionalRead): string {
+	const previous = kept_by_path.get(path)
+
+	if (previous !== undefined && answer.kind === 'unchanged') return previous.body
+	if (answer.kind !== 'changed') throw unreadable(path, answer)
+	if (answer.etag !== undefined) kept_by_path.set(path, { etag: answer.etag, body: answer.body })
+
+	return answer.body
+}
+
+// The answer for `path`, or the previous one where GitHub says it has not changed. A failure throws,
+// the contract the unconditional read had.
+async function read(path: string): Promise<string> {
+	const answer = await git_gh_conditional.read_conditional(path, kept_by_path.get(path)?.etag)
+
+	return to_body(path, answer)
+}
+
+// A page that does not parse as a listing is not taken as the whole one: the full read answers it, and
+// its own parser reports what it was.
+function is_whole_listing(page: string): boolean {
+	const total = json_value.parse_with(page, page_schema)?.total_count
+
+	return total !== undefined && total <= PAGE_SIZE
+}
+
+// A commit listing in the `--slurp` shape — an array of pages — however it was read.
+async function read_object_pages(path: string): Promise<string> {
+	const full_path = `${path}${FULL_PAGE_QUERY}`
+	const page = await read(full_path)
+
+	if (is_whole_listing(page)) return `[${page}]`
+
+	return await git_gh_exec.exec_gh_api({
+		path: full_path,
+		should_paginate: true,
+		should_slurp: true,
+	})
+}
+
+function forget_poll_reads(): void {
+	kept_by_path.clear()
+}
+
+const git_gh_poll_read = { UNREADABLE_POLL_MESSAGE, forget_poll_reads, read, read_object_pages }
+
+export { git_gh_poll_read }

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

@@ -17,8 +17,10 @@ import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 const GRAPHQL_PATH = 'graphql'
 const OPEN_PULLS_QUERY = `${git_gh_api_path.FULL_PAGE_QUERY}&state=open`
 const MISSING_NODE_ID_MESSAGE = 'gh api answered a pull request without a node_id'
+// **`expectedHeadOid` binds the auto-merge to the commit the caller pushed** (#4036): GitHub then
+// refuses it if the head has moved, rather than landing a commit nobody here pushed or checked.
 const ENABLE_AUTO_MERGE_MUTATION =
-	'mutation($id: ID!) { enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: MERGE }) { clientMutationId } }'
+	'mutation($id: ID!, $head: GitObjectID!) { enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: MERGE, expectedHeadOid: $head }) { clientMutationId } }'
 
 interface OpenPull {
 	number: number
@@ -26,13 +28,16 @@ interface OpenPull {
 	has_auto_merge: boolean
 }
 
-async function pr_enable_auto_merge(branch_name: string): Promise<void> {
+async function pr_enable_auto_merge(branch_name: string, head_sha: string): Promise<void> {
 	const pull = await read_pull(await require_pr_number(branch_name))
 	if (pull.node_id === undefined) throw new Error(MISSING_NODE_ID_MESSAGE)
 
 	await git_gh_exec.exec_gh_api({
 		path: GRAPHQL_PATH,
-		body: JSON.stringify({ query: ENABLE_AUTO_MERGE_MUTATION, variables: { id: pull.node_id } }),
+		body: JSON.stringify({
+			query: ENABLE_AUTO_MERGE_MUTATION,
+			variables: { id: pull.node_id, head: head_sha },
+		}),
 	})
 }
 

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>
 

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

@@ -1,7 +1,9 @@
 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 type { RestPull } from './git-gh-pr-rest'
+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_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'
@@ -19,17 +21,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 +38,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 +61,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 +87,19 @@ 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).
 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: await read_pull(pr_number) }
+	return { pr_number, pull: git_gh_pr_rest.parse_rest_pull(json) }
 }
 
 // Everything the snapshot carries except the review decision: three requests rather than four.

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

@@ -1,9 +1,9 @@
 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'
@@ -49,25 +49,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,16 +168,25 @@ 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> {
@@ -240,11 +251,11 @@ 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
 	}
@@ -259,6 +270,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-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