@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,387 @@
+import { poll } 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 {
+	describe_pr_failure,
+	evaluate_pr_state,
+	is_auto_merge_blocked,
+	is_review_decision_decisive,
+	type PrEvaluation,
+} from './git-pr-checks-eval'
+import { parse_pr_state_snapshot, read_string, type PrStateSnapshot } from './git-pr-checks-parse'
+import { package_name_schema } from './schemas'
+
+const SECONDS_TO_MS = 1000
+const CHECK_WAIT_INTERVAL_MS = 10_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
+// 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
+// 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 immediately rather than waiting out the
+// budget. See joshuafolkken/kit#851.
+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.
+function compute_max_attempts(timeout_seconds: number, interval_ms: number): number {
+	return Math.ceil(timeout_seconds / (interval_ms / SECONDS_TO_MS)) + 1
+}
+
+const DEFAULT_MAX_ATTEMPTS = compute_max_attempts(DEFAULT_TIMEOUT_SECONDS, CHECK_WAIT_INTERVAL_MS)
+
+function get_configured_max_attempts(): number {
+	const environment_seconds = Number(process.env['JOSH_CI_TIMEOUT_SECONDS'])
+
+	return Number.isFinite(environment_seconds) && environment_seconds > 0
+		? compute_max_attempts(environment_seconds, CHECK_WAIT_INTERVAL_MS)
+		: DEFAULT_MAX_ATTEMPTS
+}
+
+const CHECK_MAX_ATTEMPTS = get_configured_max_attempts()
+const DEFAULT_STABLE_READS = 2
+
+// One authoritative gate poll is enough once `pr_checks_watch` has already seen every check finish:
+// the watch is the first confirmation, so the poll that follows need only agree once. The two reads
+// exist for the pending→settled window a bare poll opens on, and the watch has itself already spanned
+// that window — so waiting a second interval after it merely re-proves what the watch established
+// (joshuafolkken/kit#2029).
+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 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. Before joshuafolkken/kit#1077
+// every one of them rejected straight out of the loop, because the fetch had no `catch` at all.
+//
+// **The cap is what keeps "ask again" from becoming "wait out the budget in silence".** Three
+// consecutive failures and the wait ends carrying the failure that caused it, so an endpoint that has
+// stopped answering is reported as itself rather than as a timeout thirty minutes later. The counter
+// is *consecutive*: any successful read puts it back to zero, because what it measures is "nobody is
+// answering", not "the run has been unlucky".
+//
+// **The loop's own budget is unchanged**, so nothing here can extend a wait: a fetch that never
+// succeeds still runs out of attempts. And a failed read never counts as a passing one — it resets
+// the stable-read window, the same direction joshuafolkken/kit#925 / #950 / #973 / #1048 take.
+const MAX_CONSECUTIVE_READ_FAILURES = 3
+
+// The wait's own timeout, named so a caller can tell it apart from a failing check. The bounded
+// watch in `git-pr-checks-watch.ts` answers `timed_out` for one and rethrows the other, and matching
+// on prose is the only distinction the loop offers (joshuafolkken/kit#1028).
+const PR_CHECKS_TIMEOUT_MESSAGE = 'Timed out while waiting for PR checks to complete.'
+
+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 (joshuafolkken/kit#1043).
+type ReviewDecisionPredicate = (snapshot: PrStateSnapshot) => boolean
+
+// The conservative answer, and the one every evaluator that does not say gets: read it every poll,
+// which is what all of them did before the predicate existed.
+const SHOULD_ALWAYS_READ_REVIEW_DECISION: ReviewDecisionPredicate = () => 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 loop used to hard-code the merge gate's own verdict, which is the strictest question anyone
+// asks of a pull request: mergeable *and* every required check green *and* no change request
+// standing. `gh pr checks --watch` asked a much weaker one — have the checks finished? — and the
+// conversion in joshuafolkken/kit#1028 gave the watch the strict verdict by accident: on a repository
+// whose `mergeable_state` is `blocked`, the watch could never succeed, and a standing change request
+// made it *throw* out of `pnpm josh git`. Naming the question is what keeps the two apart.
+//
+// **`should_read_review_decision` is part of the same question.** An evaluator that never reads
+// `review_decision` must not make the fetcher pay for it, and one that does must get a value read in
+// the poll it decides on. Omitting it reads the listing on every poll, so a new evaluator is never
+// silently cheaper than it is correct.
+interface PrStateEvaluator {
+	evaluate: (snapshot: PrStateSnapshot) => PrEvaluation
+	describe: (snapshot: PrStateSnapshot) => string
+	should_read_review_decision?: ReviewDecisionPredicate
+}
+
+// The merge gate's verdict, and the default: an omitted `evaluator` leaves every existing caller
+// exactly where it was.
+const MERGE_GATE_EVALUATOR: PrStateEvaluator = {
+	evaluate: evaluate_pr_state,
+	describe: describe_pr_failure,
+	should_read_review_decision: is_review_decision_decisive,
+}
+
+interface WaitForPrSuccessOptions {
+	branch_name: string
+	fetcher: PrStateFetcher
+	interval_ms: number
+	max_attempts: number
+	required_stable_reads: number
+	evaluator?: PrStateEvaluator
+}
+
+function parse_repo_name_from_package(package_json_content: string): string {
+	const result = package_name_schema.safeParse(JSON.parse(package_json_content))
+
+	if (!result.success) {
+		throw new Error('package.json name field is missing or not a non-empty string')
+	}
+
+	return result.data.name
+}
+
+function advance_stable_count(previous: number, state: PrEvaluation): number {
+	return state === 'success' ? previous + 1 : 0
+}
+
+function classify_poll_result(input: {
+	snapshot: PrStateSnapshot
+	stable_count: number
+	required_stable_reads: number
+	evaluator: PrStateEvaluator
+}): { is_done: boolean; next_stable_count: number } {
+	const state = input.evaluator.evaluate(input.snapshot)
+
+	if (state === 'failure') throw new Error(input.evaluator.describe(input.snapshot))
+
+	const next_stable_count = advance_stable_count(input.stable_count, state)
+
+	return {
+		is_done: next_stable_count >= input.required_stable_reads,
+		next_stable_count,
+	}
+}
+
+interface PollAttempt {
+	options: WaitForPrSuccessOptions
+	stable_count: number
+	failure_count: number
+	attempt: number
+}
+
+interface PollAttemptResult {
+	snapshot?: PrStateSnapshot
+	next_stable_count: number
+	next_failure_count: number
+	// 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 two things one poll can come back with, kept apart so that only the *read* is retried. The
+// throw `classify_poll_result` raises on a `failure` verdict is an answer — the checks are red — and
+// retrying it would undo the fast fail joshuafolkken/kit#990 added.
+type SnapshotRead =
+	{ kind: 'read'; snapshot: PrStateSnapshot } | { kind: 'unreadable'; cause: unknown }
+
+async function read_pr_state(
+	input: PollAttempt,
+	evaluator: PrStateEvaluator,
+): Promise<SnapshotRead> {
+	try {
+		const snapshot = await input.options.fetcher(
+			input.options.branch_name,
+			evaluator.should_read_review_decision ?? SHOULD_ALWAYS_READ_REVIEW_DECISION,
+		)
+
+		return { kind: 'read', snapshot }
+	} catch (error) {
+		return { kind: 'unreadable', cause: error }
+	}
+}
+
+// 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> {
+	const next_failure_count = input.failure_count + 1
+	if (next_failure_count >= MAX_CONSECUTIVE_READ_FAILURES) throw cause
+
+	// The reason goes in the line. Where the next read succeeds nothing else ever reports these, and
+	// an operator cannot tell a rate limit from expired auth from a dropped connection without it.
+	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 }
+}
+
+// What the loop throws when it runs out of attempts. A wait whose **last** poll could not be read
+// 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)
+}
+
+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)
+
+	const classification = classify_poll_result({
+		snapshot: read.snapshot,
+		stable_count: input.stable_count,
+		required_stable_reads: input.options.required_stable_reads,
+		evaluator,
+	})
+
+	if (classification.is_done) {
+		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 }
+}
+
+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)})`)
+		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
+	}
+
+	throw to_exhaustion_error(carried.read_failure)
+}
+
+// The snapshot module rather than `git-gh-command`, which is deliberate: `git-gh-command` also
+// exposes the watch, and the watch now polls through this file (joshuafolkken/kit#1028). Naming the
+// one read it actually needs keeps that from closing into an import cycle.
+//
+// **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
+// (joshuafolkken/kit#1043).
+async function default_fetch_pr_state(
+	branch_name: string,
+	should_read_review_decision: ReviewDecisionPredicate = SHOULD_ALWAYS_READ_REVIEW_DECISION,
+): Promise<PrStateSnapshot> {
+	const checks = await git_gh_pr_snapshot.pr_get_checks_snapshot(branch_name)
+	const snapshot = parse_pr_state_snapshot(checks.snapshot_json)
+
+	if (!should_read_review_decision(snapshot)) return snapshot
+
+	const decision = await git_gh_pr_snapshot.pr_get_review_decision(checks.pr_number)
+
+	return { ...snapshot, review_decision: read_string(decision) }
+}
+
+// **`required_stable_reads` is a parameter, not a constant, so the caller can lower it** — `run_checks`
+// passes `WATCH_CONFIRMED_STABLE_READS` when the watch already confirmed completion. It defaults to
+// `DEFAULT_STABLE_READS`, so every caller that names only the branch is exactly where it was.
+async function wait_for_pr_success_default(
+	branch_name: string,
+	required_stable_reads: number = DEFAULT_STABLE_READS,
+): Promise<PrStateSnapshot> {
+	return await wait_for_pr_success({
+		branch_name,
+		fetcher: default_fetch_pr_state,
+		interval_ms: CHECK_WAIT_INTERVAL_MS,
+		max_attempts: CHECK_MAX_ATTEMPTS,
+		required_stable_reads,
+	})
+}
+
+// Where a pull request GitHub merges on its own stands (joshuafolkken/kit#2497). `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.
+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'
+
+	try {
+		const snapshot = await default_fetch_pr_state(branch_name)
+
+		return is_auto_merge_blocked(snapshot) ? 'failed' : 'waiting'
+	} catch {
+		return 'waiting'
+	}
+}
+
+// **The wait for a pull request GitHub merges on its own.** Once auto-merge is enabled, the merge gate
+// above is the wrong question: the merge lands the moment the checks pass, and a merged pull request
+// never reads as mergeable again, so `wait_for_pr_success` would run out its budget on one that is
+// already in. The budget is the gate's, so the two waits give up alike.
+async function wait_for_pr_merged(branch_name: string): Promise<MergeProgress> {
+	let progress: MergeProgress = 'waiting'
+
+	await poll.poll_until(
+		async () => {
+			progress = await read_merge_progress(branch_name)
+
+			return progress !== 'waiting'
+		},
+		{ attempts: CHECK_MAX_ATTEMPTS, interval_ms: CHECK_WAIT_INTERVAL_MS },
+	)
+
+	return progress
+}
+
+const git_pr_checks = {
+	read_merge_progress,
+	wait_for_pr_merged,
+	wait_for_pr_success: wait_for_pr_success_default,
+}
+
+export {
+	git_pr_checks,
+	parse_repo_name_from_package,
+	wait_for_pr_success,
+	compute_max_attempts,
+	get_configured_max_attempts,
+	DEFAULT_STABLE_READS,
+	WATCH_CONFIRMED_STABLE_READS,
+	DEFAULT_MAX_ATTEMPTS,
+	MAX_CONSECUTIVE_READ_FAILURES,
+	DEFAULT_TIMEOUT_SECONDS,
+	CHECK_WAIT_INTERVAL_MS,
+	PR_CHECKS_TIMEOUT_MESSAGE,
+	SECONDS_TO_MS,
+	is_pr_checks_timeout,
+	default_fetch_pr_state,
+	MERGE_GATE_EVALUATOR,
+	SHOULD_ALWAYS_READ_REVIEW_DECISION,
+}
+export type { MergeProgress, PrStateFetcher, PrStateEvaluator, ReviewDecisionPredicate }
+export {
+	collect_blocking_failures,
+	describe_pr_failure,
+	evaluate_pr_state,
+} from './git-pr-checks-eval'
+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'

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

@@ -0,0 +1,129 @@
+import { git_gh_command } from './git-gh-command'
+import { has_ignore_reason } from './git-pr-ai-review'
+import { parse_json_array_or_undefined } from './parse-json-array'
+import { pull_comment_schema } from './schemas'
+
+// cspell:words coderabbit coderabbitai
+
+// CodeRabbit's line comments, and what `followup` does about the unresolved ones. Split out of
+// `git-pr-followup.ts` when that file passed its length limit; this is the sibling of
+// `git-pr-ai-review.ts`, which already owned the summary-comment half of the same reviewer.
+
+const CODERABBIT_AUTHOR = 'coderabbitai[bot]'
+const CODERABBIT_FLAG = '_⚠️ Potential issue_'
+const CODERABBIT_RESOLVED = '✅ Addressed in commit'
+
+interface PullComment {
+	body?: string | undefined
+	html_url?: string | undefined
+	user?: { login?: string | undefined } | undefined
+}
+
+// `undefined` when the listing could not be read, which is not the same as a pull request with no
+// line comments (joshuafolkken/kit#973).
+function parse_pull_comments(raw_json: string | undefined): Array<PullComment> | undefined {
+	if (raw_json === undefined) return undefined
+
+	return parse_json_array_or_undefined(raw_json, pull_comment_schema)
+}
+
+function read_unresolved_cr_urls(comments: ReadonlyArray<PullComment>): Array<string> {
+	return comments
+		.filter((comment) => comment.user?.login === CODERABBIT_AUTHOR)
+		.filter((comment) => (comment.body ?? '').includes(CODERABBIT_FLAG))
+		.filter((comment) => !(comment.body ?? '').includes(CODERABBIT_RESOLVED))
+		.map((comment) => comment.html_url ?? '')
+		.filter((url) => url.length > 0)
+}
+
+function build_ignore_reason_comment(reason: string, urls: ReadonlyArray<string>): string {
+	const lines = [
+		'Some CodeRabbit findings were intentionally left unresolved.',
+		`Reason: ${reason.trim()}`,
+		'Affected comments:',
+	]
+
+	for (const url of urls) {
+		lines.push(`- ${url}`)
+	}
+
+	return lines.join('\n')
+}
+
+function log_unresolved_coderabbit(urls: ReadonlyArray<string>): void {
+	console.warn('⚠ Unresolved CodeRabbit comments are non-blocking (temporary policy — kit#753):')
+
+	for (const url of urls) {
+		console.warn(`- ${url}`)
+	}
+}
+
+// Temporary (kit#753): unresolved CodeRabbit line comments no longer block the merge. They are
+// logged, returned as audit notes for the completion notification, and — when an ignore reason is
+// supplied — still documented on the PR. Revert together with kit#752.
+// Unreadable is reported, never blocked — the opposite of the AI review gate's handling of the same
+// gap, and for the reason kit#753 gave: CodeRabbit does not block the merge at all right now, so an
+// unreadable CodeRabbit listing cannot either. What it must not do is pass as "nothing unresolved",
+// which is what the reader's old `'[]'` made of it (joshuafolkken/kit#973).
+const UNREADABLE_CR_NOTE =
+	'CodeRabbit line comments could not be read; unresolved findings were not checked (kit#753).'
+
+// An ignore reason is recorded on the pull request here for the same reason it is on the branch
+// below: it is the audit trail, not a way past a block — there is no block on this path. Dropping it
+// would leave the completion note saying the listing went unread while the PR itself said nothing.
+async function report_unreadable_cr(input: {
+	branch_name: string
+	ignore_reason: string | undefined
+}): Promise<Array<string>> {
+	console.warn(`⚠ ${UNREADABLE_CR_NOTE}`)
+
+	if (has_ignore_reason(input.ignore_reason)) {
+		const body = `${UNREADABLE_CR_NOTE}\nReason: ${input.ignore_reason.trim()}`
+
+		await git_gh_command.pr_comment(input.branch_name, body)
+	}
+
+	return [UNREADABLE_CR_NOTE]
+}
+
+// Documented on the pull request when a reason was given, logged when it was not. Either way the
+// finding is recorded rather than dropped — kit#753 removed the block, not the audit trail.
+async function record_unresolved_cr(input: {
+	branch_name: string
+	ignore_reason: string | undefined
+	unresolved_urls: ReadonlyArray<string>
+}): Promise<void> {
+	if (!has_ignore_reason(input.ignore_reason)) {
+		log_unresolved_coderabbit(input.unresolved_urls)
+
+		return
+	}
+
+	const reason_comment = build_ignore_reason_comment(input.ignore_reason, input.unresolved_urls)
+
+	await git_gh_command.pr_comment(input.branch_name, reason_comment)
+}
+
+async function handle_coderabbit_findings(input: {
+	branch_name: string
+	ignore_reason: string | undefined
+}): Promise<Array<string>> {
+	const raw = await git_gh_command.pr_get_review_comments(input.branch_name)
+	const comments = parse_pull_comments(raw)
+	if (comments === undefined) return await report_unreadable_cr(input)
+	const unresolved_urls = read_unresolved_cr_urls(comments)
+	if (unresolved_urls.length === 0) return []
+
+	await record_unresolved_cr({ ...input, unresolved_urls })
+
+	return unresolved_urls.map((url) => `CodeRabbit unresolved comment skipped (kit#753): ${url}`)
+}
+
+const git_pr_coderabbit = {
+	parse_pull_comments,
+	read_unresolved_cr_urls,
+	build_ignore_reason_comment,
+	handle_coderabbit_findings,
+}
+
+export { git_pr_coderabbit, UNREADABLE_CR_NOTE }

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

@@ -0,0 +1,64 @@
+import { telegram_notify, type TelegramSendInput } from './telegram-notify'
+
+// What to type when the confirmation notification itself could not be delivered
+// (joshuafolkken/kit#1564). The `--body-file` spelling rather than `--body`, because the body names
+// commands and a backtick inside shell double quotes is evaluated before the command runs.
+const CONFIRMATION_RECOVERY =
+	'send it by hand — `pnpm josh notify --task-type confirmation --issue-url <url> ' +
+	'--body-file <path>`'
+
+interface TelegramContext {
+	repo_name: string | undefined
+	issue_title: string | undefined
+	issue_url: string | undefined
+	pr_url: string | undefined
+}
+
+function build_confirmation_input(input: {
+	context: TelegramContext
+	body: string
+}): TelegramSendInput {
+	return {
+		task_type: 'confirmation',
+		repo_name: input.context.repo_name,
+		issue_title: input.context.issue_title,
+		body: input.body,
+		issue_url: input.context.issue_url,
+		pr_url: input.context.pr_url,
+	}
+}
+
+// **The tolerant send** (joshuafolkken/kit#1564). What stops the run is the blocker this
+// notification is *about*, and it is raised by the caller — so a failed send must not replace that
+// diagnosis with a Telegram error. It is reported and the caller's own stop still happens.
+//
+// Unlike the completion notification, this one *has* a recovery: a `confirmation` is exactly what
+// `josh notify` is for, and the run stops here anyway, so re-sending it by hand loses nothing.
+async function notify_confirmation(input: {
+	context: TelegramContext
+	body: string
+}): Promise<void> {
+	await telegram_notify.send_or_report(build_confirmation_input(input), CONFIRMATION_RECOVERY)
+}
+
+// A blank or whitespace-only reason is no reason at all: a bypass has to say something a person can
+// audit later, so the emptiness check is what keeps `--…-ignore-reason ""` from being a silent pass.
+function has_ignore_reason(reason: string | undefined): reason is string {
+	return reason !== undefined && reason.trim().length > 0
+}
+
+// Shared by every `followup` gate that can stop the run — the AI review scan and, since
+// joshuafolkken/kit#1578, the managed config-file gate. They ask the same two questions (was a reason
+// given, and how is the confirmation sent), and a second copy of either answer is what lets the two
+// gates drift apart.
+const git_pr_confirmation = {
+	notify_confirmation,
+	build_confirmation_input,
+	has_ignore_reason,
+}
+
+// `has_ignore_reason` stays a named export beside the namespace: `git-pr-coderabbit.ts` imports it
+// from `git-pr-ai-review.ts`, which re-exports this one, and a namespace-only surface would make
+// that re-export a property read.
+export { git_pr_confirmation, has_ignore_reason }
+export type { TelegramContext }

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

@@ -0,0 +1,25 @@
+function is_pr_already_exists_message(message: string): boolean {
+	return message === 'PR_ALREADY_EXISTS'
+}
+
+function has_error_cause(error: Error): boolean {
+	return error.cause instanceof Error && is_pr_already_exists_message(error.cause.message)
+}
+
+function is_pr_already_exists_error(error: unknown): boolean {
+	if (error instanceof Error) {
+		if (is_pr_already_exists_message(error.message)) {
+			return true
+		}
+
+		return has_error_cause(error)
+	}
+
+	return false
+}
+
+const git_pr_error = {
+	is_pr_already_exists_error,
+}
+
+export { git_pr_error }