@joshuafolkken/kit 1.2114.0 → 1.3000.0

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

@@ -1,3 +1,4 @@
+import { PR_POLL_SCHEDULES } from '#scripts/lib/poll'
 import {
 	CHECK_WAIT_INTERVAL_MS,
 	compute_max_attempts,
@@ -10,7 +11,12 @@ import {
 	type PrStateEvaluator,
 	type SnapshotObserver,
 } from './git-pr-checks'
-import { is_coderabbit_check, is_required_check, type PrEvaluation } from './git-pr-checks-eval'
+import {
+	collect_blocking_failures,
+	is_coderabbit_check,
+	is_required_check,
+	type PrEvaluation,
+} from './git-pr-checks-eval'
 import {
 	CHECK_STATUS_FAIL,
 	CHECK_STATUS_PENDING,
@@ -32,7 +38,7 @@ import {
 // soon as the pull request is open.
 //
 // **What is lost is the live table.** `gh` printed each check's name and state as it changed; the
-// poll prints `Checking PR status… (n/N)` instead. The trade is accepted because the display was
+// poll prints `Checking PR status… (read n)` instead. The trade is accepted because the display was
 // never load-bearing — no caller parsed it — and because keeping it would have left the merge gate's
 // last GraphQL call in place, which is a 403 in a cloud session.
 
@@ -91,10 +97,9 @@ function is_awaited_check(check: RollupCheck): boolean {
 // CodeRabbit posts `Review queued` before any workflow has attached a check run, and a flat
 // `pending` sits out the whole budget on a lone CodeRabbit that has already reported.
 //
-// **The order of the questions is the old order**, and it has to be: asking "is anything still
-// pending" before "did anything fail" is what keeps a pull request whose E2E is still running from
-// being called failed by a check that has already gone red.
-function evaluate_checks_settled(snapshot: PrStateSnapshot): PrEvaluation {
+// **Every red that is not blocking keeps the old order**: "is anything still pending" before "did
+// anything fail", so a non-blocking CodeRabbit failure does not end the watch while E2E is running.
+function evaluate_awaited_settled(snapshot: PrStateSnapshot): PrEvaluation {
 	const awaited = snapshot.rollup.filter((check) => is_awaited_check(check))
 	const considered = awaited.length === 0 ? snapshot.rollup : awaited
 
@@ -108,6 +113,16 @@ function evaluate_checks_settled(snapshot: PrStateSnapshot): PrEvaluation {
 	return snapshot.rollup.some((check) => check.status === CHECK_STATUS_FAIL) ? 'failure' : 'success'
 }
 
+// **A blocking failure is asked first** (joshuafolkken/kit#5389): a red check the merge gate refuses
+// on — `collect_blocking_failures`, the gate's own predicate — already makes the pull request
+// unmergeable, so waiting for a pending E2E cannot change the verdict and only delays it. The cost is
+// that the E2E's own red is learned one push later.
+function evaluate_checks_settled(snapshot: PrStateSnapshot): PrEvaluation {
+	if (collect_blocking_failures(snapshot).length > 0) return 'failure'
+
+	return evaluate_awaited_settled(snapshot)
+}
+
 function describe_checks_failure(snapshot: PrStateSnapshot): string {
 	const failed = snapshot.rollup.filter((check) => check.status === CHECK_STATUS_FAIL)
 
@@ -138,6 +153,7 @@ async function watch_until_settled(branch_name: string, observe?: SnapshotObserv
 			PR_CHECKS_WATCH_TIMEOUT_MS / SECONDS_TO_MS,
 			CHECK_WAIT_INTERVAL_MS,
 		),
+		backoff: PR_POLL_SCHEDULES.checks_gated,
 		required_stable_reads: DEFAULT_STABLE_READS,
 		evaluator: CHECKS_SETTLED_EVALUATOR,
 	})

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

@@ -1,5 +1,5 @@
 import { package_name_schema } from '#scripts/git/git-schemas'
-import { poll } from '#scripts/lib/poll'
+import { poll, PR_POLL_SCHEDULES, type BackoffSchedule, type PollOptions } from '#scripts/lib/poll'
 import { git_gh_pr_auto_merge } from './git-gh-pr-auto-merge'
 import { git_gh_pr_snapshot } from './git-gh-pr-snapshot'
 import {
@@ -9,20 +9,26 @@ import {
 	is_merge_conflict,
 	is_review_decision_decisive,
 	PrConflictError,
+	REQUIRED_CHECKS,
 	type PrEvaluation,
 } from './git-pr-checks-eval'
+import {
+	git_pr_checks_gate,
+	type PrStateFetcher,
+	type ReviewDecisionPredicate,
+} from './git-pr-checks-gate'
+import { blocked_cause, missing_context_error } from './git-pr-checks-missing'
 import { parse_pr_state_snapshot, read_string, type PrStateSnapshot } from './git-pr-checks-parse'
 
 const SECONDS_TO_MS = 1000
-const CHECK_WAIT_INTERVAL_MS = 10_000
+const CHECK_WAIT_INTERVAL_MS = 20_000
 // The wait has to outlast what the CI it is watching is allowed to take, or it gives up on a run
-// that is still legitimately progressing — which is what 180 seconds did to every consumer whose
+// that is still legitimately progressing — which happened to consumers whose
 // suite includes E2E: `followup` became a command that needed `JOSH_CI_TIMEOUT_SECONDS` set by hand
 // on every invocation and, when that was forgotten, exited red beside a CI that was still running.
 // The budget is therefore read off the distributed `templates/workflows/ci.yml` rather than picked
-// as a round number: its longest chain is `e2e` (25 minutes) behind the `playwright-image` job it
-// needs (2), so 27 minutes is the longest run that workflow permits, and five minutes of
-// runner-queue headroom goes on top. A unit test walks the `needs` graph of the distributed
+// as a round number: its longest chain includes `e2e` and the `playwright-image` job it needs,
+// with runner-queue headroom on top. A unit test walks the `needs` graph of the distributed
 // workflows and fails if any declared budget outgrows this value; a job that declares no cap is a
 // gap the number cannot promise to cover rather than a reason to inflate it. Waiting longer costs
 // nothing on a fast project: polling returns as soon as the checks settle, and a failed check throws
@@ -30,7 +36,7 @@ const CHECK_WAIT_INTERVAL_MS = 10_000
 const DEFAULT_TIMEOUT_SECONDS = 1920
 
 // The poll loop sleeps between attempts and not after the last one, so spanning a budget takes one
-// more attempt than the budget holds intervals: without the `+ 1` a 60-second setting waited 50.
+// more attempt than the budget holds intervals; otherwise the wait ends one interval early.
 function compute_max_attempts(timeout_seconds: number, interval_ms: number): number {
 	return Math.ceil(timeout_seconds / (interval_ms / SECONDS_TO_MS)) + 1
 }
@@ -54,9 +60,9 @@ const DEFAULT_STABLE_READS = 2
 // 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,
+// **A read that failed is not a verdict.** The loop reads every twenty seconds, so a dropped connection,
 // a rate limit or one request over its budget is the kind of failure the *next* poll answers — and
-// ending a 32-minute wait on one of them costs the whole run again, so the fetch catches them rather
+// ending a merge wait on one of them costs the whole run again, so the fetch catches them rather
 // than rejecting straight out of the loop.
 //
 // **The cap is what keeps "ask again" from becoming "wait out the budget in silence".** Three
@@ -79,21 +85,11 @@ function is_pr_checks_timeout(error: unknown): boolean {
 	return error instanceof Error && error.message === PR_CHECKS_TIMEOUT_MESSAGE
 }
 
-// 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
-
 // The conservative answer, and the one every evaluator that does not say gets: read it every poll.
 function should_always_read_review_decision(): boolean {
 	return true
 }
 
-type PrStateFetcher = (
-	branch_name: string,
-	should_read_review_decision: ReviewDecisionPredicate,
-) => Promise<PrStateSnapshot>
-
 // What the loop asks of each snapshot, and what it says when the answer is `failure`.
 //
 // The merge gate's own verdict is the strictest question anyone asks of a pull request: mergeable
@@ -126,6 +122,8 @@ interface WaitForPrSuccessOptions {
 	fetcher: PrStateFetcher
 	interval_ms: number
 	max_attempts: number
+	// Lengthens the waits within the `(max_attempts - 1) × interval_ms` budget (`poll.ts`).
+	backoff?: BackoffSchedule
 	required_stable_reads: number
 	evaluator?: PrStateEvaluator
 	// Asked before every poll; a throw ends the wait with that error. `josh followup` stops here on a
@@ -148,9 +146,9 @@ function advance_stable_count(previous: number, state: PrEvaluation): number {
 }
 
 function failure_error(message: string, snapshot: PrStateSnapshot): Error {
-	return is_merge_conflict(snapshot.merge_state_status)
-		? new PrConflictError(message)
-		: new Error(message)
+	if (is_merge_conflict(snapshot.merge_state_status)) return new PrConflictError(message)
+
+	return missing_context_error(message, snapshot) ?? new Error(message)
 }
 
 function classify_poll_result(input: {
@@ -177,7 +175,6 @@ interface PollAttempt {
 	options: WaitForPrSuccessOptions
 	stable_count: number
 	failure_count: number
-	attempt: number
 }
 
 interface PollAttemptResult {
@@ -187,6 +184,9 @@ interface PollAttemptResult {
 	// What this poll could not be read with, carried so that a wait ending on an unreadable poll can
 	// report *that* rather than the timeout. Absent on every poll that was read.
 	read_failure?: unknown
+	// The last read of a poll that was not done, so a wait ending on the timeout can name what it was
+	// still blocked on (joshuafolkken/kit#5780).
+	last_snapshot?: PrStateSnapshot
 }
 
 // The two things one poll can come back with, kept apart so that only the *read* is retried. The
@@ -211,21 +211,10 @@ async function read_pr_state(
 	}
 }
 
-// The loop sleeps between attempts and not after the last one, so a poll that is about to be the
-// final one returns immediately and lets the caller run out of attempts.
-async function sleep_before_next_attempt(input: PollAttempt): Promise<void> {
-	if (input.attempt < input.options.max_attempts - 1) {
-		await poll.sleep(input.options.interval_ms)
-	}
-}
-
 // The unreadable branch: count it, give up at the cap with the failure that caused it, and otherwise
 // wait out the interval exactly as a pending poll does — without the sleep a broken endpoint would be
 // spun on rather than re-read.
-async function retry_after_unreadable(
-	input: PollAttempt,
-	cause: unknown,
-): Promise<PollAttemptResult> {
+function retry_after_unreadable(input: PollAttempt, cause: unknown): PollAttemptResult {
 	const next_failure_count = input.failure_count + 1
 	if (next_failure_count >= MAX_CONSECUTIVE_READ_FAILURES) throw cause
 
@@ -234,7 +223,6 @@ async function retry_after_unreadable(
 	console.warn(
 		`Could not read the PR state (${String(next_failure_count)}/${String(MAX_CONSECUTIVE_READ_FAILURES)}); asking again on the next poll: ${String(cause)}`,
 	)
-	await sleep_before_next_attempt(input)
 
 	return { next_stable_count: 0, next_failure_count, read_failure: cause }
 }
@@ -243,14 +231,23 @@ async function retry_after_unreadable(
 // ends on that failure rather than on the timeout: reporting expired auth or a rate limit as "the
 // checks are still running" is exactly the misread this file refuses everywhere else, and
 // `is_pr_checks_timeout` would otherwise let `git-pr-checks-watch.ts` answer `timed_out` for it.
-function to_exhaustion_error(last_read_failure: unknown): unknown {
-	return last_read_failure ?? new Error(PR_CHECKS_TIMEOUT_MESSAGE)
+// The timeout keeps its exact message for that match and names the block in its `cause`.
+function timeout_error(last_snapshot: PrStateSnapshot | undefined): Error {
+	const cause = last_snapshot && blocked_cause(last_snapshot, REQUIRED_CHECKS)
+
+	return cause === undefined
+		? new Error(PR_CHECKS_TIMEOUT_MESSAGE)
+		: new Error(PR_CHECKS_TIMEOUT_MESSAGE, { cause })
+}
+
+function to_exhaustion_error(carried: PollAttemptResult): unknown {
+	return carried.read_failure ?? timeout_error(carried.last_snapshot)
 }
 
 async function attempt_pr_success_poll(input: PollAttempt): Promise<PollAttemptResult> {
 	const evaluator = input.options.evaluator ?? MERGE_GATE_EVALUATOR
 	const read = await read_pr_state(input, evaluator)
-	if (read.kind === 'unreadable') return await retry_after_unreadable(input, read.cause)
+	if (read.kind === 'unreadable') return retry_after_unreadable(input, read.cause)
 
 	const classification = classify_poll_result({
 		snapshot: read.snapshot,
@@ -263,32 +260,57 @@ async function attempt_pr_success_poll(input: PollAttempt): Promise<PollAttemptR
 		return { snapshot: read.snapshot, next_stable_count: 0, next_failure_count: 0 }
 	}
 
-	await sleep_before_next_attempt(input)
+	return {
+		next_stable_count: classification.next_stable_count,
+		next_failure_count: 0,
+		last_snapshot: read.snapshot,
+	}
+}
+
+// Under a schedule whose waits lengthen, a poll that read a different pull request state from the
+// one before waits the schedule's first interval again, and an unreadable poll reads as a change.
+function pr_poll_options(
+	options: WaitForPrSuccessOptions,
+	progress: { carried: PollAttemptResult },
+): PollOptions {
+	const cadence = { attempts: options.max_attempts, interval_ms: options.interval_ms }
+	if (options.backoff === undefined) return cadence
+
+	function seen(): string {
+		return JSON.stringify({ last: progress.carried.last_snapshot })
+	}
 
-	return { next_stable_count: classification.next_stable_count, next_failure_count: 0 }
+	return { ...cadence, backoff: { schedule: options.backoff, seen } }
 }
 
 async function wait_for_pr_success(options: WaitForPrSuccessOptions): Promise<PrStateSnapshot> {
 	// The whole carry-over of one poll into the next, in one value: the stable-read window, the
 	// consecutive-failure count, and what the last poll could not be read with.
-	let carried: PollAttemptResult = { next_stable_count: 0, next_failure_count: 0 }
-
-	for (let attempt = 0; attempt < options.max_attempts; attempt += 1) {
-		console.info(`Checking PR status… (${String(attempt + 1)}/${String(options.max_attempts)})`)
-		// eslint-disable-next-line no-await-in-loop -- polling: the check belongs to this poll, not to all of them at once
-		await options.before_poll?.()
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		carried = await attempt_pr_success_poll({
-			options,
-			stable_count: carried.next_stable_count,
-			failure_count: carried.next_failure_count,
-			attempt,
-		})
-
-		if (carried.snapshot !== undefined) return carried.snapshot
+	const progress: { carried: PollAttemptResult } = {
+		carried: { next_stable_count: 0, next_failure_count: 0 },
 	}
+	let attempt = 0
+	const snapshot = await poll.poll_for(
+		async () => {
+			attempt += 1
+			// No `/max_attempts`: under the backoff that count is the budget, not the reads it makes.
+			console.info(`Checking PR status… (read ${String(attempt)})`)
+			await options.before_poll?.()
+			const carried = await attempt_pr_success_poll({
+				options,
+				stable_count: progress.carried.next_stable_count,
+				failure_count: progress.carried.next_failure_count,
+			})
+
+			Object.assign(progress, { carried })
+
+			return carried.snapshot
+		},
+		pr_poll_options(options, progress),
+	)
+	if (snapshot !== undefined) return snapshot
 
-	throw to_exhaustion_error(carried.read_failure)
+	throw to_exhaustion_error(progress.carried)
 }
 
 // The snapshot module rather than `git-gh-command`, which is deliberate: `git-gh-command` also
@@ -298,7 +320,8 @@ async function wait_for_pr_success(options: WaitForPrSuccessOptions): Promise<Pr
 // **Three requests, and a fourth only where it can change the answer.** The pull request detail and
 // the two commit listings are read every poll because `mergeable_state` and the rollup both move
 // while CI runs; the review listing is read when the predicate says this poll's verdict turns on it.
-// A `followup` that waits out its whole 32-minute budget went from about 800 requests to about 600.
+// Reading the review only when it can change the verdict keeps a long wait's request count down
+// (joshuafolkken/kit#1043). A GraphQL snapshot already carries it: one query per poll (#7143).
 async function default_fetch_pr_state(
 	branch_name: string,
 	should_read_review_decision: ReviewDecisionPredicate = should_always_read_review_decision,
@@ -308,7 +331,7 @@ async function default_fetch_pr_state(
 
 	if (!should_read_review_decision(snapshot)) return snapshot
 
-	const decision = await git_gh_pr_snapshot.pr_get_review_decision(checks.pr_number)
+	const decision = await git_gh_pr_snapshot.pr_read_review_decision(checks)
 
 	return { ...snapshot, review_decision: read_string(decision) }
 }
@@ -320,14 +343,16 @@ async function default_fetch_pr_state(
 // stream from it (joshuafolkken/kit#3770). It decides nothing: the wait reads the same snapshot.
 type SnapshotObserver = (snapshot: PrStateSnapshot) => Promise<void>
 
+// Gated per wait: a poll where the head's checks did not move reuses the last snapshot (#7238).
 function observed_fetcher(observe: SnapshotObserver | undefined): PrStateFetcher {
-	if (observe === undefined) return default_fetch_pr_state
+	const fetch_gated = git_pr_checks_gate.gate_fetcher(default_fetch_pr_state)
+	if (observe === undefined) return fetch_gated
 
 	return async function fetch_observed(
 		branch_name: string,
 		should_read_review_decision: ReviewDecisionPredicate,
 	): Promise<PrStateSnapshot> {
-		const snapshot = await default_fetch_pr_state(branch_name, should_read_review_decision)
+		const snapshot = await fetch_gated(branch_name, should_read_review_decision)
 
 		await observe(snapshot)
 
@@ -346,6 +371,7 @@ async function wait_for_pr_success_default(
 		fetcher: observed_fetcher(observe),
 		interval_ms: CHECK_WAIT_INTERVAL_MS,
 		max_attempts: CHECK_MAX_ATTEMPTS,
+		backoff: PR_POLL_SCHEDULES.checks_gated,
 		required_stable_reads,
 		before_poll,
 	})
@@ -354,18 +380,21 @@ async function wait_for_pr_success_default(
 // Where a pull request GitHub merges on its own stands. `failed` is what
 // auto-merge never fires under — a red required check, a conflict, a requested change — so a wait on
 // it ends now rather than at the budget; a red check outside the required list is not among them
-// (`is_auto_merge_blocked`). A read that failed answers `waiting`, so a poll asks again.
+// (`is_auto_merge_blocked`). One detail read answers both merged and the gate (joshuafolkken/kit#6721);
+// only a read that failed asks `pr_is_merged`, and otherwise answers `waiting`, so a poll asks again.
 type MergeProgress = 'merged' | 'failed' | 'waiting'
 
-async function read_merge_progress(branch_name: string): Promise<MergeProgress> {
-	if (await git_gh_pr_auto_merge.pr_is_merged(branch_name)) return 'merged'
+function to_merge_progress(snapshot: PrStateSnapshot): MergeProgress {
+	if (snapshot.is_merged === true) return 'merged'
 
-	try {
-		const snapshot = await default_fetch_pr_state(branch_name)
+	return is_auto_merge_blocked(snapshot) ? 'failed' : 'waiting'
+}
 
-		return is_auto_merge_blocked(snapshot) ? 'failed' : 'waiting'
+async function read_merge_progress(branch_name: string): Promise<MergeProgress> {
+	try {
+		return to_merge_progress(await default_fetch_pr_state(branch_name))
 	} catch {
-		return 'waiting'
+		return (await git_gh_pr_auto_merge.pr_is_merged(branch_name)) ? 'merged' : 'waiting'
 	}
 }
 
@@ -382,7 +411,11 @@ async function wait_for_pr_merged(branch_name: string): Promise<MergeProgress> {
 
 			return progress !== 'waiting'
 		},
-		{ attempts: CHECK_MAX_ATTEMPTS, interval_ms: CHECK_WAIT_INTERVAL_MS },
+		{
+			attempts: CHECK_MAX_ATTEMPTS,
+			interval_ms: CHECK_WAIT_INTERVAL_MS,
+			backoff: { schedule: PR_POLL_SCHEDULES.merge },
+		},
 	)
 
 	return progress
@@ -414,13 +447,7 @@ export {
 	MERGE_GATE_EVALUATOR,
 	should_always_read_review_decision,
 }
-export type {
-	MergeProgress,
-	PrStateFetcher,
-	PrStateEvaluator,
-	ReviewDecisionPredicate,
-	SnapshotObserver,
-}
+export type { MergeProgress, PrStateEvaluator, SnapshotObserver }
 export {
 	collect_blocking_failures,
 	describe_pr_failure,
@@ -429,3 +456,5 @@ export {
 export type { PrEvaluation } from './git-pr-checks-eval'
 export { parse_pr_state_snapshot } from './git-pr-checks-parse'
 export type { RollupCheck, PrStateSnapshot } from './git-pr-checks-parse'
+
+export { type PrStateFetcher, type ReviewDecisionPredicate } from './git-pr-checks-gate'

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

@@ -1,3 +1,4 @@
+import { poll } from '#scripts/lib/poll'
 import { git_gh_command } from './git-gh-command'
 import { git_pr_checks, type PrStateSnapshot } from './git-pr-checks'
 
@@ -24,6 +25,7 @@ interface CheckedMerge {
 	wait_for_green: WaitForGreen
 	// The snapshot the gate already passed. Absent, the merge waits for one first.
 	checked?: PrStateSnapshot | undefined
+	before_merge?: ((head?: string) => Promise<void>) | undefined
 }
 
 function checked_head(snapshot: PrStateSnapshot): string {
@@ -33,11 +35,13 @@ function checked_head(snapshot: PrStateSnapshot): string {
 }
 
 // `false` is "the head moved"; every other failure is the caller's to see.
-async function try_merge(branch_name: string, snapshot: PrStateSnapshot): Promise<boolean> {
+async function try_merge(input: CheckedMerge, snapshot: PrStateSnapshot): Promise<boolean> {
 	const head_sha = checked_head(snapshot)
 
+	await input.before_merge?.(head_sha)
+
 	try {
-		await git_gh_command.pr_merge(branch_name, head_sha)
+		await git_gh_command.pr_merge(input.branch_name, head_sha)
 
 		return true
 	} catch (error) {
@@ -48,16 +52,26 @@ async function try_merge(branch_name: string, snapshot: PrStateSnapshot): Promis
 }
 
 async function merge_checked(input: CheckedMerge): Promise<void> {
-	let snapshot = input.checked ?? (await input.wait_for_green())
-
-	for (let move = 0; move < MAX_HEAD_MOVES; move += 1) {
-		// eslint-disable-next-line no-await-in-loop -- each merge names the head the wait before it passed
-		if (await try_merge(input.branch_name, snapshot)) return
-
-		console.info(HEAD_MOVED_NOTE)
-		// eslint-disable-next-line no-await-in-loop -- the new head has to pass before it is merged
-		snapshot = await input.wait_for_green()
-	}
+	const progress = { snapshot: input.checked ?? (await input.wait_for_green()) }
+
+	const is_merged = await poll.poll_until(
+		async () => {
+			if (await try_merge(input, progress.snapshot)) return true
+
+			console.info(HEAD_MOVED_NOTE)
+			Object.assign(progress, { snapshot: await input.wait_for_green() })
+
+			return false
+		},
+		{
+			attempts: MAX_HEAD_MOVES,
+			interval_ms: 0,
+			sleeper: async () => {
+				await Promise.resolve()
+			},
+		},
+	)
+	if (is_merged) return
 
 	throw new Error(HEAD_KEPT_MOVING_MESSAGE)
 }

package/scripts/gh/git-pr.ts

@@ -10,13 +10,9 @@ import { git_gh_command } from './git-gh-command'
 import { git_pr_error } from './git-pr-error'
 import { git_pr_messages } from './git-pr-messages'
 
-// **Answers the new pull request's URL, and `undefined` when one already existed.** `pr_create`
-// filters its REST response to `.html_url`, so the address is in hand the moment the call returns —
-// which matters now that nothing waits before reporting it. `pr_get_url`
-// resolves the branch through the `?head=…` listing, and that listing is eventually consistent: read
-// in the same instant the pull request was created it can answer nothing, and `pr_get_url` folds
-// "not there yet" and "the read failed" into the same `undefined`. The five-second sleep used to
-// cover that gap incidentally.
+// Return the new pull request's URL directly from `pr_create`: the branch listing read by
+// `pr_get_url` is eventually consistent and can answer nothing immediately after creation.
+// An existing pull request returns `undefined` because this call did not create it.
 async function create_pr(
 	title: string,
 	body: string,
@@ -53,20 +49,10 @@ async function display_pr_url_if_available(branch_name: string): Promise<void> {
 	}
 }
 
-// **This command stops at "the pull request is open"; it does not wait for the checks**.
-// It used to sleep five seconds and then watch the rollup on a two-minute
-// budget — measured at 119.8 seconds of one 1555-second run, 7.7% of it — and the answer decided
-// nothing: only `timed_out` was read, and only to pick which message to print. What actually blocks
-// a merge is `pnpm josh followup`, whose `wait_for_pr_success` asks a stricter question (CLEAN merge
-// state, every required check green, no standing change request) and starts that wait from scratch
-// the moment this command returns. So the wait here was the same answer, paid for twice.
-//
-// **The conflict read went with it, and its replacement is not here.** `git-conflict.ts` read
-// `mergeStateStatus` right after the watch reported the checks settled, where `BLOCKED` genuinely
-// meant something. Called at *this* point it would fire on every healthy pull request instead:
-// GitHub reports `BLOCKED` as soon as a required check is queued. The conflict is caught in
-// `git-pr-checks-eval.ts` now, where `DIRTY` ends the wait on its first poll — about ten seconds,
-// against the two minutes this watch took to reach the same conclusion.
+// This command stops when the pull request is open. `pnpm josh followup` owns the merge decision
+// and waits for CLEAN state, passing required checks and no standing change request.
+// Conflict diagnosis belongs there too: a newly queued required check makes a healthy PR BLOCKED,
+// while `git-pr-checks-eval.ts` can identify a genuine conflict from DIRTY state.
 async function report_open_pr(branch_name: string, created_url?: string): Promise<void> {
 	git_pr_messages.display_pr_opened_message()
 
@@ -162,11 +148,11 @@ async function create(
 }
 
 function build_title(issue_info: IssueInfo): string {
-	return `${issue_info.title} ${issue_cite.plain(issue_info.number)}`
+	return `${issue_info.title} ${issue_cite.plain_for('github', issue_info.number)}`
 }
 
 function build_body(issue_info: IssueInfo, extra_body?: string): string {
-	const closes = `closes ${issue_cite.plain(issue_info.number)}`
+	const closes = `closes ${issue_cite.plain_for('github', issue_info.number)}`
 
 	if (extra_body === undefined) return closes
 

package/scripts/git/base-tree.ts

@@ -1,6 +1,6 @@
 import { rmSync } from 'node:fs'
 import { copyFile, mkdir, mkdtemp, rm, symlink } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { constants, tmpdir } from 'node:os'
 import path from 'node:path'
 import { git_worktree } from './git-worktree'
 
@@ -14,9 +14,10 @@ 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
+// `josh run:review --join` stops with SIGTERM, a terminal with SIGINT (Ctrl-C) or SIGHUP.
+const STOP_SIGNALS = ['SIGTERM', 'SIGINT', 'SIGHUP'] as const
+// 128 + the signal's number: the code the process would have exited with had no listener caught it.
+const SIGNAL_EXIT_BASE = 128
 
 // The temp directories of the trees this process holds now.
 const live_parents = new Set<string>()
@@ -50,24 +51,31 @@ async function remove(base_tree: BaseTree): Promise<void> {
 	}
 }
 
-// **A terminated run removes its trees before it exits** (joshuafolkken/kit#4794): `josh run:review
+// **A stopped 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 {
+// the process exits right after it; the next `with_tree`'s prune drops the registrations. Exiting
+// through `process.exit` also runs the `exit` listeners, which stop `test:red`'s detached probes
+// (joshuafolkken/kit#6814).
+function remove_live_trees(signal: NodeJS.Signals): void {
 	for (const parent of live_parents) rmSync(parent, { force: true, recursive: true })
 
-	process.exit(TERMINATED_EXIT_CODE)
+	process.exit(SIGNAL_EXIT_BASE + constants.signals[signal])
 }
 
 function track(parent: string): void {
-	if (live_parents.size === 0) process.on(TERMINATE_SIGNAL, remove_live_trees)
+	if (live_parents.size === 0) {
+		for (const signal of STOP_SIGNALS) process.on(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)
+	if (live_parents.size > 0) return
+
+	for (const signal of STOP_SIGNALS) process.off(signal, remove_live_trees)
 }
 
 async function with_tree<T>(

package/scripts/git/changed-paths-sync.ts

@@ -1,6 +1,5 @@
 import { changed_paths } from './changed-paths'
 import { git_diff_reads } from './git-diff-reads'
-import { git_location_environment } from './git-location-environment'
 import { git_spawn_sync, type GitSyncOptions } from './git-spawn-sync'
 
 // The synchronous counterpart of `changed_paths.read_changed_paths(false)` — the branch diff since
@@ -9,14 +8,6 @@ import { git_spawn_sync, type GitSyncOptions } from './git-spawn-sync'
 // a merge of the default branch in progress too, measured from the base `change_base.resolved_through_merge`
 // answers (joshuafolkken/kit#5309). Any failure is the empty list.
 
-// With an explicit `cwd`, the git location variables are cleared so that directory is what git
-// answers for, as in `git_spawn_sync.origin_url`.
-function options_of(cwd: string | undefined): GitSyncOptions {
-	if (cwd === undefined) return {}
-
-	return { cwd, env: git_location_environment.location_free_environment() }
-}
-
 function default_branch_reference(options: GitSyncOptions): string {
 	const output = git_spawn_sync.read([...git_diff_reads.DEFAULT_BRANCH_ARGUMENTS], options)
 	const default_branch = git_diff_reads.default_branch_of(output)
@@ -26,7 +17,8 @@ function default_branch_reference(options: GitSyncOptions): string {
 	return git_spawn_sync.read(check, options) === undefined ? default_branch : remote_reference
 }
 
-// While a merge is in progress, the later of the base of `HEAD` and the base of `MERGE_HEAD`.
+// While a merge is in progress, the later of the base of `HEAD` and the base of `MERGE_HEAD`; also
+// the merge base `git_merge_conflicts.working_tree_conflicts` probes against (joshuafolkken/kit#5582).
 function through_merge(base: string, reference: string, options: GitSyncOptions): string {
 	const incoming = git_spawn_sync.read(git_diff_reads.incoming_base_arguments(reference), options)
 
@@ -48,7 +40,7 @@ function change_base(options: GitSyncOptions): string {
 
 // Repository-root-relative paths, as the asynchronous reading returns them.
 function read_changed_paths(cwd?: string): ReadonlyArray<string> {
-	const options = options_of(cwd)
+	const options = git_spawn_sync.located(cwd)
 	const tracked = git_spawn_sync.read(
 		git_diff_reads.names_since_arguments(change_base(options)),
 		options,
@@ -58,6 +50,6 @@ function read_changed_paths(cwd?: string): ReadonlyArray<string> {
 	return [tracked, untracked].flatMap((raw = '') => changed_paths.to_paths(raw))
 }
 
-const changed_paths_sync = { read_changed_paths }
+const changed_paths_sync = { read_changed_paths, through_merge }
 
 export { changed_paths_sync }