@joshuafolkken/kit 1.1050.0 → 1.1128.0

package/scripts/{git → followup}/git-pr-followup.ts

@@ -1,18 +1,28 @@
-import { git_closes_keyword } from './git-closes-keyword'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
+import { git_pr_ai_review, type TelegramContext } from '#scripts/gh/git-pr-ai-review'
+import {
+	DEFAULT_STABLE_READS,
+	git_pr_checks,
+	WATCH_CONFIRMED_STABLE_READS,
+} from '#scripts/gh/git-pr-checks'
+import { is_coderabbit_check } from '#scripts/gh/git-pr-checks-eval'
+import { CHECK_STATUS_PASS, type PrStateSnapshot } from '#scripts/gh/git-pr-checks-parse'
+import { git_pr_coderabbit } from '#scripts/gh/git-pr-coderabbit'
+import { git_pr_managed_config } from '#scripts/gh/git-pr-managed-config'
+import { github_issue_url } from '#scripts/gh/github-issue-url'
+import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
+import { json_value } from '#scripts/lib/json-value'
+import type { GitNotifyConfig } from '#scripts/notify/git-notify'
+import {
+	telegram_notify,
+	type TelegramSendInput,
+	type TelegramTaskType,
+} from '#scripts/notify/telegram-notify'
+import { git_followup_merged } from './git-followup-merged'
 import { git_followup_pending } from './git-followup-pending'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
-import { git_gh_command } from './git-gh-command'
-import { git_gh_helpers } from './git-gh-helpers'
-import type { GitNotifyConfig } from './git-notify'
-import { git_pr_ai_review, type TelegramContext } from './git-pr-ai-review'
-import { DEFAULT_STABLE_READS, git_pr_checks, WATCH_CONFIRMED_STABLE_READS } from './git-pr-checks'
-import { is_coderabbit_check } from './git-pr-checks-eval'
-import { CHECK_STATUS_PASS, git_pr_checks_parse, type PrStateSnapshot } from './git-pr-checks-parse'
-import { git_pr_coderabbit } from './git-pr-coderabbit'
 import { git_pr_followup_wrapup } from './git-pr-followup-wrapup'
-import { git_pr_managed_config } from './git-pr-managed-config'
-import { github_issue_url } from './github-issue-url'
-import { telegram_notify, type TelegramSendInput, type TelegramTaskType } from './telegram-notify'
 
 const { STAGE, lap } = git_followup_stages
 
@@ -64,6 +74,10 @@ interface FollowupInput {
 	ai_review_ignore_reason: string | undefined
 	is_skip_watch: boolean
 	should_merge: boolean
+	// The pull request merged before this run (joshuafolkken/kit#3023): only the tail is left to run.
+	is_merged?: boolean | undefined
+	// When it merged — a completion report posted before it is the `prrun` stop's, not this tail's.
+	merged_at?: string | undefined
 }
 
 const { parse_closes_issue_number } = git_closes_keyword
@@ -116,7 +130,7 @@ async function warn_if_missing_closes(branch_name: string): Promise<string | und
 // on the path this whole change exists to remove. So the question asked here is the narrow one —
 // *is this definitely an empty rollup* — and every other outcome falls through.
 function reads_as_empty_rollup(raw_json: string): boolean {
-	const parsed = git_pr_checks_parse.parse_json_safe(raw_json)
+	const parsed = json_value.parse_or_undefined(raw_json)
 
 	if (typeof parsed !== 'object' || parsed === null || !('statusCheckRollup' in parsed)) {
 		return false
@@ -342,6 +356,8 @@ async function run_review_checks(
 	context: TelegramContext,
 	log: StageLog,
 ): Promise<{ notes: Array<string>; managed: Array<string> }> {
+	if (input.is_merged === true) return { notes: [], managed: [] }
+
 	const managed = await git_pr_managed_config.handle_managed_config_changes({
 		should_merge: input.should_merge,
 	})
@@ -359,6 +375,26 @@ async function run_review_checks(
 	return { notes: [...managed, ...check_notes, ...scan_notes], managed }
 }
 
+// **A tail re-run after a merge does not report twice** (joshuafolkken/kit#3023): where the issue
+// already carries this pull request's completion report, the Telegram is skipped here and the comment
+// in the wrapup. Answers whether it was recorded, so the wrapup skips on the same read.
+async function notify_unless_recorded(
+	input: FollowupInput,
+	issue_number: string | undefined,
+	context: TelegramContext,
+	checks: { notes: Array<string> },
+): Promise<boolean> {
+	const is_recorded = await git_followup_merged.is_completion_recorded({
+		merged_at: input.is_merged === true ? input.merged_at : undefined,
+		issue_number,
+		pr_url: context.pr_url,
+	})
+
+	if (!is_recorded) await notify_completion(context, checks.notes, input.should_merge)
+
+	return is_recorded
+}
+
 // **Answers with the issue number the run actually used** (joshuafolkken/kit#1539), which is the one
 // the invocation named or, failing that, the one the pull request body closes. Everything downstream
 // takes it from here rather than from the input, so the Telegram context, the completion comment and
@@ -369,8 +405,7 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 
 	lap(log, STAGE.closes_and_context)
 	const checks = await run_review_checks(input, context, log)
-
-	await notify_completion(context, checks.notes, input.should_merge)
+	const is_completion_recorded = await notify_unless_recorded(input, issue_number, context, checks)
 
 	lap(log, STAGE.telegram)
 	await git_pr_followup_wrapup.run_wrapup(
@@ -382,6 +417,8 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 			pr_url: context.pr_url,
 			should_merge: input.should_merge,
 			managed_notes: checks.managed,
+			is_merged: input.is_merged,
+			is_completion_recorded,
 		},
 		log,
 	)
@@ -426,4 +463,4 @@ export {
 	log_skip_notes,
 }
 export type { FollowupInput }
-export type { TelegramContext } from './git-pr-ai-review'
+export type { TelegramContext } from '#scripts/gh/git-pr-ai-review'

package/scripts/gate/core-budget.ts

@@ -4,6 +4,7 @@ import { availableParallelism } from 'node:os'
 import path from 'node:path'
 import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { process_identity } from '#scripts/josh/process-identity'
+import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { z } from 'zod'
 
@@ -45,9 +46,7 @@ const WAIT_CAP_MS = 120_000
 // The head of the ledger is always admitted, so the smallest budget worth planning against is one core.
 const MIN_BUDGET = 1
 
-const reservation_schema = z.object({
-	pid: z.number(),
-	process_start: z.string().optional(),
+const reservation_schema = process_owner_schema.extend({
 	weight: z.number(),
 	claimed_at: z.number(),
 })
@@ -228,6 +227,7 @@ async function await_admission(context: WaitContext): Promise<void> {
 	while (!is_admitted(context.key, live_reservations(context.directory), context.budget)) {
 		if (context.now() >= context.deadline) return
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await context.sleep(context.poll_interval_ms)
 	}
 }
@@ -273,16 +273,10 @@ async function with_core_reservation<T>(
 }
 
 const core_budget = {
-	MIN_BUDGET,
-	POLL_INTERVAL_MS,
 	RESERVED_PREFIX,
-	WAIT_CAP_MS,
 	admitted_keys,
 	admitted_load,
-	is_admitted,
-	is_running,
 	live_reservations,
-	read_reservation,
 	release,
 	reserve,
 	with_core_reservation,

package/scripts/gate/gate-plan.ts

@@ -66,6 +66,11 @@ const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
 	{ label: TYPE_CHECK_LABEL, target: 'check', reserved_cores: 1 },
 	{ label: 'cspell', target: 'cspell:dot', reserved_cores: 1 },
 	{ label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
+	// **The unused-member check reserves no core** (joshuafolkken/kit#2987): it builds one TypeScript
+	// program and walks it single-threaded for about 5s — over well before lint and the type check, so
+	// a reservation would only take a place from the four-core CI runner's fan-out and a worker from
+	// the unit suite for the whole gate.
+	{ label: 'exports', target: 'exports:unused', reserved_cores: 0 },
 ]
 
 // The checks, in the order their output is printed — the static set, then the unit suite last (the
@@ -91,8 +96,8 @@ function has_unit_check(checks: ReadonlyArray<GateCheck>): boolean {
 	return checks.some((check) => check.label === UNIT_LABEL)
 }
 
-// What the three non-elastic checks hold between them: 2 + 1 + 1. Reduced over `STATIC_CHECKS`
-// rather than over all four, because that is the set the sentence above names: `resolve_unit_worker_cap`
+// What the non-elastic checks hold between them: 2 + 1 + 1. Reduced over `STATIC_CHECKS`
+// rather than over every check, because that is the set the sentence above names: `resolve_unit_worker_cap`
 // spends this as the cores the unit suite must leave to its siblings, so summing the unit check into
 // it would have the suite subtract its own reservation from its own budget the day that reservation
 // stops being zero. The two sets give the same number today, which is exactly why the narrower one
@@ -331,7 +336,6 @@ function format_gate_plan(
 }
 
 const gate_plan = {
-	BEHAVIOR_LABEL,
 	GATE_CHECKS,
 	LINT_LABEL,
 	MEASURED_CORES,
@@ -343,7 +347,6 @@ const gate_plan = {
 	check_weight,
 	format_gate_plan,
 	format_machine,
-	format_unit_cap,
 	has_unit_check,
 	plan_of,
 	resolve_concurrency,

package/scripts/gate/gate-report.ts

@@ -193,16 +193,10 @@ function report_gate_steps(
 
 const gate_report = {
 	format_failure_actions,
-	format_seconds,
-	gate_step_header,
 	has_checker_warning,
-	has_warnings,
 	is_gate_step_failed,
 	is_skip_notice,
-	print_gate_step,
-	print_gate_summary,
 	report_gate_steps,
-	should_print_body,
 }
 
 export type { GateReport, GateStep, GateStepResult }

package/scripts/gate/gate-tree.ts

@@ -43,7 +43,7 @@ async function read_gate_tree(): Promise<GateTree> {
 	return { files, base }
 }
 
-const gate_tree = { read_base, read_changed_files, read_gate_tree }
+const gate_tree = { read_gate_tree }
 
 export type { GateTree }
 export { gate_tree }

package/scripts/gate/pre-commit-type-check.ts

@@ -174,13 +174,7 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 const pre_commit_type_check = {
 	FORCE_ENV,
 	TYPE_CHECK_ARGUMENTS,
-	format_refusal,
-	format_skip,
-	is_recorded_check_this_check,
-	read_commit_tree,
-	reusable_green_commit,
 	run_pre_commit_type_check,
-	unexpected_arguments,
 }
 
 export type { CommitTree }

package/scripts/gate/project-checks.ts

@@ -2,6 +2,7 @@ import { existsSync, globSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { project_profile } from '#scripts/init/project-profile'
+import { json_value } from '#scripts/lib/json-value'
 import { SKIP_MARKER } from '#scripts/test/skip-marker'
 import { z } from 'zod'
 
@@ -70,23 +71,23 @@ function has_bin(directory: string, bin_name: string): boolean {
 }
 
 function josh_settings(manifest: unknown): unknown {
-	if (typeof manifest !== 'object' || manifest === null || !('josh' in manifest)) return undefined
-
-	return manifest.josh
+	return json_value.is_record(manifest) ? manifest['josh'] : undefined
 }
 
 function is_basic_manifest(manifest: unknown): boolean {
 	const josh = josh_settings(manifest)
-	if (typeof josh !== 'object' || josh === null || !('profile' in josh)) return false
+	if (!json_value.is_record(josh)) return false
 
-	return project_profile.parse_profile(josh.profile) === 'basic'
+	return project_profile.parse_profile(josh['profile']) === 'basic'
 }
 
+// The try covers the read alone — a missing or unreadable manifest — since the parse already answers
+// `undefined` for text that is not JSON.
 function read_manifest(directory: string): unknown {
 	try {
 		const manifest_path = path.join(project_root(directory), PACKAGE_JSON)
 
-		return JSON.parse(readFileSync(manifest_path, 'utf8'))
+		return json_value.parse_or_undefined(readFileSync(manifest_path, 'utf8'))
 	} catch {
 		return undefined
 	}
@@ -158,8 +159,6 @@ function eslint_skip_reason(directory: string): string | undefined {
 const project_checks = {
 	CSPELL_CONFIGS,
 	ESLINT_CONFIGS,
-	SCRIPT_FILES,
-	TYPE_CONFIGS,
 	TYPE_FILES,
 	WEB_FILES,
 	eslint_skip_reason,

package/scripts/gate/scoped-green.ts

@@ -252,7 +252,6 @@ const scoped_green = {
 	read_before,
 	record_green,
 	record_if_green,
-	refusal,
 	refusal_for,
 }
 

package/scripts/gate/type-check-step.ts

@@ -74,6 +74,7 @@ async function resolve_toolkit_step(
 // The command the gate spawns through `pnpm`, so a toolkit step resolves the same shim `pnpm` would.
 async function resolve_type_check_args(start_directory: string): Promise<ReadonlyArray<string>> {
 	for (const bin_name of TOOLKIT_BINS) {
+		// eslint-disable-next-line no-await-in-loop -- the first toolkit bin that resolves wins
 		const step = await resolve_toolkit_step(start_directory, bin_name)
 		if (step !== undefined) return step
 	}
@@ -83,7 +84,6 @@ async function resolve_type_check_args(start_directory: string): Promise<Readonl
 
 const type_check_step = {
 	parse_usage_commands,
-	resolve_toolkit_step,
 	resolve_type_check_args,
 }
 

package/scripts/gate/verification-gate.ts

@@ -488,10 +488,8 @@ const verification_gate = {
 	mark_gate_running,
 	record_green_gate,
 	run_gate_steps,
-	run_marked_gate,
 	scoped_precheck_refusal,
 	with_gate_marker,
-	run_checked_gate,
 	run_gate_command,
 	run_gate_step,
 	run_verification_gate,

package/scripts/gh/fix-gh-packages.ts

@@ -1,7 +1,9 @@
 import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { file_reader } from '#scripts/lib/read-file'
+import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
 import { fix_gh_packages_logic, type LockfilePackage } from './fix-gh-packages-logic'
 import { gh_cli_token } from './gh-cli-token'
@@ -9,7 +11,8 @@ import { gh_cli_token } from './gh-cli-token'
 const LOCKFILE = 'pnpm-lock.yaml'
 const NPMRC = '.npmrc'
 const GH_PACKAGES_HOST = 'npm.pkg.github.com'
-const FETCH_TIMEOUT_MS = 10_000
+// The packument reads are independent; the width keeps a large lockfile from bursting the registry.
+const FETCH_CONCURRENCY = 8
 
 const npm_distribution_schema = z.looseObject({ tarball: z.string().optional() })
 const npm_version_schema = z.looseObject({ dist: npm_distribution_schema.optional() })
@@ -42,10 +45,7 @@ async function fetch_tarball_url(
 	token: string,
 ): Promise<string | undefined> {
 	const url = `https://${GH_PACKAGES_HOST}/${package_path}`
-	const response = await fetch(url, {
-		headers: { Authorization: `Bearer ${token}` },
-		signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
-	})
+	const response = await timed_fetch(url, { headers: { Authorization: `Bearer ${token}` } })
 
 	if (!response.ok) {
 		console.warn(`fix-gh-packages: fetch failed for ${package_path} (${String(response.status)})`)
@@ -79,14 +79,13 @@ async function collect_fixes(
 	scopes: Set<string>,
 	token: string,
 ): Promise<Map<string, string>> {
-	const fixes = new Map<string, string>()
-
-	for (const [key, entry] of Object.entries(packages)) {
-		const pair = await process_package_entry(key, entry, scopes, token)
-		if (pair !== undefined) fixes.set(pair[0], pair[1])
-	}
+	const pairs = await bounded_pool.bounded_map(
+		Object.entries(packages),
+		FETCH_CONCURRENCY,
+		async ([key, entry]) => await process_package_entry(key, entry, scopes, token),
+	)
 
-	return fixes
+	return new Map(pairs.filter((pair) => pair !== undefined))
 }
 
 async function apply_fixes(cwd: string, scopes: Set<string>, token: string): Promise<void> {
@@ -128,3 +127,7 @@ async function main(): Promise<void> {
 
 const [, argv1] = process.argv
 if (argv1 !== undefined && realpathSync(argv1) === fileURLToPath(import.meta.url)) await main()
+
+const fix_gh_packages = { collect_fixes }
+
+export { fix_gh_packages }

package/scripts/gh/gh-spawn.ts

@@ -1,6 +1,6 @@
-import { git_gh_api_path } from '#scripts/git/git-gh-api-path'
-import { git_gh_exec } from '#scripts/git/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
 
 // The synchronous twin of `git_gh_repo.repo_get_name_with_owner`: same fact, read the same way, but
 // synchronously because `josh init` / `josh sync` / `josh doctor` decide before they can await.

package/scripts/{git → gh}/git-ai-review-scan.ts

@@ -146,9 +146,5 @@ function classify_ai_review_comments(comments: ReadonlyArray<ReviewComment>): Cl
 	}
 }
 
-const git_ai_review_scan = {
-	classify_ai_review_comments,
-}
-
-export { git_ai_review_scan, classify_ai_review_comments }
+export { classify_ai_review_comments }
 export type { ReviewComment, ClassifiedFinding, ClassifiedFindings, FindingKind }

package/scripts/{git → gh}/git-gh-check.ts

@@ -1,3 +1,4 @@
+import { COMMAND_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
 const GH_NOT_INSTALLED_MSG = 'gh CLI is not installed. Install it from https://cli.github.com/'
@@ -6,7 +7,7 @@ const gh_check: { promise?: Promise<void> } = {}
 
 async function run_gh_check(): Promise<void> {
 	try {
-		await execa('gh', ['--version'])
+		await execa('gh', ['--version'], { timeout: COMMAND_TIMEOUT_MS })
 	} catch {
 		delete gh_check.promise
 		throw new Error(GH_NOT_INSTALLED_MSG)

package/scripts/{git → gh}/git-gh-exec.ts

@@ -1,7 +1,7 @@
+import { has_timed_out } from '#scripts/git/git-execa-error'
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
 import { error_text } from '#scripts/lib/error-message'
 import { execa, execaSync } from 'execa'
-import { has_timed_out } from './git-execa-error'
 import { check_gh_installed } from './git-gh-check'
 import { gh_failure } from './git-gh-failure'
 

package/scripts/{git → gh}/git-gh-failure.ts

@@ -1,5 +1,5 @@
+import { parse_json } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
-import { parse_json } from './parse-json-array'
 
 // Why one `gh api` request failed, taken from **that request** rather than from a later probe
 // (joshuafolkken/kit#1690).

package/scripts/{git → gh}/git-gh-helpers.ts

@@ -36,7 +36,6 @@ function handle_pr_create_error(error: unknown): never {
 
 const git_gh_helpers = {
 	parse_pr_state_string,
-	is_pr_already_exists_message,
 	get_error_message_with_stderr,
 	handle_pr_create_error,
 }

package/scripts/{git → gh}/git-gh-issue-list.ts

@@ -1,3 +1,4 @@
+import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { read_blocked_by } from './git-gh-issue-read'
@@ -178,6 +179,7 @@ async function fetch_selected(request: IssueListRequest): Promise<SelectedRows>
 	let has_more = true
 
 	while (page <= MAX_PAGES && wants_more(has_more, selected.length, request.limit)) {
+		// eslint-disable-next-line no-await-in-loop -- paging stops as soon as enough rows are selected
 		const result = await fetch_page(request, page)
 
 		selected.push(...result.selected)
@@ -197,20 +199,21 @@ async function fetch_selected(request: IssueListRequest): Promise<SelectedRows>
 // issue GitHub itself reports as unblocked costs no request. A backlog with no declared blockers
 // therefore costs exactly what `gh` cost — one listing — rather than one request per row.
 //
-// Sequential rather than a burst: the only caller that asks for the field is the `auto-ok` pickup,
-// whose listing is already narrowed by a label, and a rate limit reached in parallel would fail rows
-// that a paced pass reads.
+// Bounded rather than sequential (joshuafolkken/kit#3103): the pass was paced one request at a time,
+// which made every `backlog:plan` wait about 0.7 s per opted-in issue declaring a blocker. The width
+// is the one `epic:bundle` already reads the same endpoint at, so the burst stays bounded while a
+// rate-limited read still fails the whole listing rather than a row (`bounded-pool.ts`).
+const RELATION_CONCURRENCY = 8
+
 async function read_relations(
 	rows: ReadonlyArray<RestIssue>,
 	repo?: string,
 ): Promise<Array<BlockedBy>> {
-	const relations: Array<BlockedBy> = []
-
-	for (const row of rows) {
-		relations.push(await read_blocked_by(String(row.number), row, repo))
-	}
-
-	return relations
+	return await bounded_pool.bounded_map(
+		rows,
+		RELATION_CONCURRENCY,
+		async (row) => await read_blocked_by(String(row.number), row, repo),
+	)
 }
 
 // The listing, plus what it could not cover. `json` is `undefined` — never `'[]'` — when the listing

package/scripts/{git → gh}/git-gh-issue-read.ts

@@ -1,3 +1,4 @@
+import type { IssueReference } from '#scripts/issue/issue-reference'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { gh_failure, type GhFailure } from './git-gh-failure'
@@ -9,7 +10,6 @@ import {
 	type RestIssue,
 } from './git-gh-issue-rest'
 import { gh_reachability } from './git-gh-reachability'
-import type { IssueReference } from './issue-reference'
 
 // Reading one issue. Split out of `git-gh-issue.ts`, which had grown past the file-length limit
 // while holding both the reads and the writes; the reads are what every epic command goes through,

package/scripts/{git → gh}/git-gh-issue-rest.ts

@@ -1,8 +1,11 @@
+import {
+	parse_json_array_or_undefined,
+	parse_json_object_safe,
+} from '#scripts/git/parse-json-array'
+import { blocking_issue_schema } from '#scripts/git/schemas'
+import type { IssueReference } from '#scripts/issue/issue-reference'
 import { z } from 'zod'
 import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
-import type { IssueReference } from './issue-reference'
-import { parse_json_array_or_undefined, parse_json_object_safe } from './parse-json-array'
-import { blocking_issue_schema } from './schemas'
 
 // The translation between one REST issue (`repos/{owner}/{repo}/issues/{N}`) and the JSON shape
 // `gh issue view --json <fields>` used to answer with.

package/scripts/{git → gh}/git-gh-issue-write.ts

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec, type GhApiRequest } from './git-gh-exec'
 
@@ -43,7 +44,9 @@ async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean
 		await write()
 
 		return true
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('git_gh_issue_write.did_write_succeed', error)
+
 		return false
 	}
 }

package/scripts/{git → gh}/git-gh-pr-auto-merge.ts

@@ -1,3 +1,4 @@
+import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { read_pull, require_pr_number } from './git-gh-pr-read'
@@ -40,7 +41,9 @@ async function pr_enable_auto_merge(branch_name: string): Promise<void> {
 async function pr_is_merged(branch_name: string): Promise<boolean> {
 	try {
 		return git_gh_pr_rest.is_merged(await read_pull(await require_pr_number(branch_name)))
-	} catch {
+	} catch (error) {
+		error_text.trace_swallowed('git_gh_pr_auto_merge.pr_is_merged', error)
+
 		return false
 	}
 }

package/scripts/{git → gh}/git-gh-pr-read.ts

@@ -77,6 +77,12 @@ async function fetch_pr_number(branch_name: string): Promise<number | undefined>
 // distinction is the point. The *classification* is cheaper here and needs no status probe: a branch
 // with no pull request is a 200 with an empty listing rather than a 404, so the lookup's own outcome
 // already separates them (joshuafolkken/kit#1048).
+interface PullMergeState {
+	is_merged: boolean
+	merged_at: string | undefined
+	head_sha: string | undefined
+}
+
 type PullNumberRead =
 	{ kind: 'read'; pr_number: number } | { kind: 'missing' } | { kind: 'unreadable'; cause: unknown }
 
@@ -215,6 +221,22 @@ async function pr_get_url(branch_name: string): Promise<string | undefined> {
 	return git_gh_helpers.parse_pr_state_string(pull.html_url)
 }
 
+// **Where the branch's pull request stands** — a merge a person made by hand included
+// (joshuafolkken/kit#3023): whether it merged and when, and the commit its head is on, which a push
+// made on GitHub moves without touching the local branch. `undefined` covers both "no pull request"
+// and "nothing could be read": `followup` then takes its ordinary path, whose merge step settles a
+// pull request that did merge after all (`pr_merge`), so an unread answer costs a wait, not a wrong tail.
+async function pr_get_merge_state(branch_name: string): Promise<PullMergeState | undefined> {
+	const pull = await read_pull_of_branch(branch_name)
+	if (pull === undefined) return undefined
+
+	return {
+		is_merged: git_gh_pr_rest.is_merged(pull),
+		merged_at: pull.merged_at ?? undefined,
+		head_sha: pull.head?.sha,
+	}
+}
+
 // REST answers JSON null for a pull request with no body where `gh --json body` answered an empty
 // string, and both used to arrive here as the empty answer this folds to `undefined`.
 async function pr_get_body(branch_name: string): Promise<string | undefined> {
@@ -281,6 +303,7 @@ const git_gh_pr_read = {
 	pr_get_number,
 	pr_get_url,
 	pr_get_body,
+	pr_get_merge_state,
 	pr_view,
 	pr_get_comments,
 	pr_get_review_comments,
@@ -290,6 +313,7 @@ const git_gh_pr_read = {
 // needs them separately: the reviews endpoint is keyed by number while the rollup is keyed by the
 // head commit the detail carries. Exported rather than re-derived so the memo above stays one memo
 // (joshuafolkken/kit#1028).
+export type { PullMergeState }
 export {
 	git_gh_pr_read,
 	forget_pr_numbers,

package/scripts/{git → gh}/git-gh-pr-rest.ts

@@ -1,7 +1,10 @@
+import {
+	parse_json_array_or_undefined,
+	parse_json_object_safe,
+} from '#scripts/git/parse-json-array'
+import { rest_comment_schema } from '#scripts/git/schemas'
 import { z } from 'zod'
 import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
-import { parse_json_array_or_undefined, parse_json_object_safe } from './parse-json-array'
-import { rest_comment_schema } from './schemas'
 
 // The translation between one REST pull request (`repos/{owner}/{repo}/pulls/{N}`) and the JSON
 // shape `gh pr view --json <fields>` used to answer with.

package/scripts/{git → gh}/git-gh-pr-review.ts

@@ -1,5 +1,5 @@
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
-import { parse_json_array_or_undefined } from './parse-json-array'
 
 // GraphQL's `reviewDecision`, rebuilt from the review history REST serves.
 //
@@ -90,7 +90,7 @@ function to_review_decision(reviews_json: string): string {
 	return latest.has(REVIEW_APPROVED) ? REVIEW_APPROVED : REVIEW_NONE
 }
 
-const git_gh_pr_review = { to_review_decision, parse_rest_reviews }
+const git_gh_pr_review = { to_review_decision }
 
 export {
 	git_gh_pr_review,