@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/epic/epic-cross-repo.ts

@@ -2,6 +2,7 @@ import { repo_map_logic } from '#scripts/discovery/repo-map-logic'
 import { repo_origin } from '#scripts/discovery/repo-origin'
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { propagate_publish } from '#scripts/propagate/propagate-publish'
 import { derive_versions_endpoint } from '#scripts/version/version-command-config'
 import { load } from 'js-yaml'
@@ -69,7 +70,6 @@ function is_published(repo: string, version: string): boolean {
 	return propagate_publish.is_version_published(versions, version)
 }
 
-const GH_TIMEOUT_MS = 20_000
 // The manifest arrives base64-encoded in the API's `content` field; `jq` decodes and reads it.
 const VERSION_JQ = '.content | @base64d | fromjson | {version, private, workspaces} | tojson'
 const PNPM_WORKSPACE_FILE = 'pnpm-workspace.yaml'
@@ -145,7 +145,7 @@ function pnpm_workspace_path(repo: string): string {
 
 // A read that failed for any reason other than a missing file leaves the layout unknown.
 function classify_workspace_failure(repo: string): WorkspaceCheck {
-	const status = git_gh_exec.exec_gh_api_status_sync(pnpm_workspace_path(repo), GH_TIMEOUT_MS)
+	const status = git_gh_exec.exec_gh_api_status_sync(pnpm_workspace_path(repo), GH_API_TIMEOUT_MS)
 
 	return status === NOT_FOUND_STATUS ? 'single' : 'unreadable'
 }
@@ -154,7 +154,7 @@ function read_pnpm_workspace(repo: string): WorkspaceCheck {
 	const stdout = git_gh_exec.read_gh_api_sync({
 		path: pnpm_workspace_path(repo),
 		jq_filter: WORKSPACE_JQ,
-		timeout_ms: GH_TIMEOUT_MS,
+		timeout_ms: GH_API_TIMEOUT_MS,
 	})
 	if (stdout === undefined) return classify_workspace_failure(repo)
 
@@ -229,7 +229,7 @@ function to_manifest(repo: string, stdout: string): ManifestAnswer {
 // here is trustworthy in a way a registry 404 is not: the repository's issues are already being read,
 // so access is established and what is missing is the file.
 function classify_manifest_failure(repo: string): ManifestAnswer {
-	const status = git_gh_exec.exec_gh_api_status_sync(manifest_path(repo), GH_TIMEOUT_MS)
+	const status = git_gh_exec.exec_gh_api_status_sync(manifest_path(repo), GH_API_TIMEOUT_MS)
 
 	return { kind: status === NOT_FOUND_STATUS ? 'absent' : 'unreadable' }
 }
@@ -238,7 +238,7 @@ function fetch_manifest(repo: string): ManifestAnswer {
 	const stdout = git_gh_exec.read_gh_api_sync({
 		path: manifest_path(repo),
 		jq_filter: VERSION_JQ,
-		timeout_ms: GH_TIMEOUT_MS,
+		timeout_ms: GH_API_TIMEOUT_MS,
 	})
 
 	return stdout === undefined ? classify_manifest_failure(repo) : to_manifest(repo, stdout)

package/scripts/epic/epic-graph.ts

@@ -121,7 +121,7 @@ function find_stuck_children(children: ReadonlyArray<EpicChild>): Array<string>
 	const index = index_children(children)
 	const remaining = new Set(children.map((child) => key_of(child)))
 
-	const peel = (): number => {
+	function peel(): number {
 		const ready = [...remaining].filter((node) => !has_remaining_blocker(index, node, remaining))
 
 		for (const node of ready) remaining.delete(node)

package/scripts/epic/epic-index.ts

@@ -1,7 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
-import type { OpenIssueData } from '#scripts/git/schemas'
 import { EPIC_LABEL, has_any_label } from '#scripts/issue/issue-labels'
 import { z } from 'zod'
 import { epic_parse } from './epic-parse'

package/scripts/epic/epic-issue.ts

@@ -1,6 +1,6 @@
 import { git_gh_issue_rest } from '#scripts/gh/git-gh-issue-rest'
+import { blocked_by_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
-import { blocked_by_schema } from '#scripts/git/schemas'
 import { z } from 'zod'
 import type { IssueReference } from './epic-reference'
 
@@ -29,11 +29,7 @@ const PULL_REQUEST_SEGMENT = '/pull/'
 const epic_issue_schema = z.object({
 	number: z.number(),
 	title: z.string().default(''),
-	body: z
-		.string()
-		.nullable()
-		.default('')
-		.transform((value) => value ?? ''),
+	body: z.union([z.string(), z.null().transform(() => '')]).default(''),
 	state: z.string().default(UNKNOWN_STATE),
 	// The issue endpoint answers for a pull request as readily as for an issue, and nothing in the
 	// other fields separates them — an open PR reports `state: OPEN`, a merged one `MERGED`. The URL

package/scripts/epic/epic-lane-offer.ts

@@ -187,10 +187,10 @@ function solo_offer(
 	read: BusyRead,
 	request: LaneRequest,
 ): LaneOffer {
-	const { offered, notice } = epic_solo.select(answer.children, read, request.repo)
+	const { offered, notice = '' } = epic_solo.select(answer.children, read, request.repo)
 
 	if (offered.length === NO_LANES && answer.children.length > NO_LANES) {
-		return { children: [], verdict: WAIT_VERDICT, notice: notice ?? '' }
+		return { children: [], verdict: WAIT_VERDICT, notice }
 	}
 
 	return { ...answer, children: offered, notice: offered_notice(offered, read, request) }

package/scripts/epic/epic-next.ts

@@ -5,6 +5,7 @@ import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { lane_capacity } from '#scripts/lane/lane-capacity'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_classify } from './epic-classify'
 import { epic_cross_repo } from './epic-cross-repo'
@@ -31,12 +32,10 @@ import { epic_report, type EpicNextResult } from './epic-report'
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
-const REPO_FLAG = '--repo'
-// Asking for every free lane is opt-in, so the answer stays one token for a caller that has not been
-// changed. `--repo` alone still prints exactly one number — what joshuafolkken/kit#1491 changed for
-// it is *when* that number appears, not how many arrive (joshuafolkken/kit#1491).
-const LANES_FLAG = '--lanes'
-const FLAG_PREFIX = '--'
+// Asking for every free lane (`--lanes`) is opt-in, so the answer stays one token for a caller that
+// has not been changed. `--repo` alone still prints exactly one number — what joshuafolkken/kit#1491
+// changed for it is *when* that number appears, not how many arrive (joshuafolkken/kit#1491).
+const OPTIONS = { repo: { type: 'string' }, lanes: { type: 'boolean' } } as const
 const USAGE =
 	'Usage: josh epic:next <epic-number|owner/repo#number>... [--repo <owner/repo>] [--lanes]'
 // A repository that could not be read is refused rather than stood in for. Since
@@ -66,30 +65,6 @@ interface NextOptions {
 	usage?: string
 }
 
-// A value that is itself a flag is no value at all. `--repo --lanes` used to narrow to a repository
-// literally named `--lanes` and report `No runnable child in --lanes` with exit 0; refused here, it
-// reaches the usage line instead — the caller meant a repository and named none.
-function parse_repo(rest: ReadonlyArray<string>): string | undefined {
-	const flag_index = rest.indexOf(REPO_FLAG)
-	const value = flag_index === -1 ? undefined : rest[flag_index + 1]
-
-	return value?.startsWith(FLAG_PREFIX) === true ? undefined : value
-}
-
-// The leading arguments are epic references and everything from the first flag on is options. Split
-// on the flag rather than taking a fixed count, so `epic:next 858 909 --repo X` reads two epics and
-// `epic:next 858 --repo X` still reads one (joshuafolkken/kit#1493).
-function split_at_flag(argv: ReadonlyArray<string>): {
-	head: ReadonlyArray<string>
-	rest: ReadonlyArray<string>
-} {
-	const flag_at = argv.findIndex((entry) => entry.startsWith(FLAG_PREFIX))
-
-	return flag_at === -1
-		? { head: argv, rest: [] }
-		: { head: argv.slice(0, flag_at), rest: argv.slice(flag_at) }
-}
-
 // Every leading entry, or nothing. One entry that does not parse fails the whole read rather than
 // being dropped: a mistyped second epic would otherwise run the first one alone and report nothing
 // at all about the one that was missed — an unattended run silently doing half of what was asked.
@@ -106,21 +81,34 @@ function parse_references(head: ReadonlyArray<string>): ReadonlyArray<EpicRefere
 	return references.length === 0 ? undefined : references
 }
 
+function with_repo(
+	references: ReadonlyArray<EpicReference>,
+	values: { repo?: string; lanes?: boolean },
+): NextOptions {
+	const { repo, lanes: is_all_lanes = false } = values
+
+	if (repo === undefined) return is_all_lanes ? { usage: USAGE } : { references }
+
+	return { references, repo, is_all_lanes }
+}
+
+// The positional arguments are epic references and the flags are options, so `epic:next 858 909 --repo
+// X` reads two epics and `epic:next 858 --repo X` still reads one (joshuafolkken/kit#1493). The read is
+// strict: an unknown flag reaches the usage line rather than being ignored, and a value that is itself
+// a flag is no value at all — `--repo --lanes` used to narrow to a repository literally named
+// `--lanes` and report `No runnable child in --lanes` with exit 0.
+//
 // `--lanes` without `--repo` is refused rather than ignored: the lane count is a property of one
 // repository, so the aggregate listing has nothing to apply it to, and a flag that silently does
-// nothing is a caller believing it asked for something.
+// nothing is a caller believing it asked for something. An empty name (`--repo=` from an unset
+// variable) is no repository either: narrowed to it, the answer is `No runnable child in .` and exit 0.
 function parse_options(argv: ReadonlyArray<string>): NextOptions {
-	const { head, rest } = split_at_flag(argv)
-	const references = parse_references(head)
-	if (references === undefined) return { usage: USAGE }
-	const repo = parse_repo(rest)
-	const is_all_lanes = rest.includes(LANES_FLAG)
-
-	if (repo === undefined) {
-		return is_all_lanes || rest.includes(REPO_FLAG) ? { usage: USAGE } : { references }
-	}
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+	if (parsed === undefined) return { usage: USAGE }
+	const references = parse_references(parsed.positionals)
+	if (references === undefined || parsed.values.repo === '') return { usage: USAGE }
 
-	return { references, repo, is_all_lanes }
+	return with_repo(references, parsed.values)
 }
 
 // The answer for one epic, from an already-fetched snapshot. Split from the fetch so the whole
@@ -446,7 +434,6 @@ const epic_next = {
 	is_order_declared,
 	repo_verdict,
 	UNCHECKED_EXCLUSION,
-	split_at_flag,
 	parse_options,
 	refuse_reads,
 	views_of,

package/scripts/epic/epic-solo-stale.ts

@@ -1,5 +1,5 @@
 import { setTimeout as sleep } from 'node:timers/promises'
-import type { OpenIssueData } from '#scripts/git/schemas'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
 import { has_any_label, IN_PROGRESS_LABEL, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { lane_await } from '#scripts/lane/lane-await'
 import { lane_registry } from '#scripts/lane/lane-registry'

package/scripts/epic/epic-triage.ts

@@ -20,12 +20,16 @@ type TriageVerdict = 'triage'
 
 const TRIAGE_VERDICT: TriageVerdict = 'triage'
 
-function is_triaged(child: EpicChild): boolean {
-	const { labels } = child
-
+// Read off a bare label list too, so `josh issue:file` refuses an untriaged `auto-ok` filing by the
+// same answer the offer paths withhold it by (joshuafolkken/kit#3313).
+function has_triage_label(labels: ReadonlyArray<string>): boolean {
 	return has_label_name(labels, RUN_SOLO_LABEL) || has_label_name(labels, RUN_LANE_LABEL)
 }
 
+function is_triaged(child: EpicChild): boolean {
+	return has_triage_label(child.labels)
+}
+
 // The candidates nobody has judged, in the order they were given.
 function untriaged(children: ReadonlyArray<EpicChild>): ReadonlyArray<EpicChild> {
 	return children.filter((child) => !is_triaged(child))
@@ -41,7 +45,7 @@ function message(children: ReadonlyArray<EpicChild>, repo: string): string {
 	)
 }
 
-const epic_triage = { TRIAGE_VERDICT, is_triaged, message, untriaged }
+const epic_triage = { TRIAGE_VERDICT, has_triage_label, is_triaged, message, untriaged }
 
 export type { TriageVerdict }
 export { epic_triage }

package/scripts/epic/epic-validate.ts

@@ -1,5 +1,5 @@
+import { epic_subject_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
-import { epic_subject_schema } from '#scripts/git/schemas'
 import { EPIC_LABEL, has_label_name } from '#scripts/issue/issue-labels'
 import { epic_parse, type DeclarationState } from './epic-parse'
 

package/scripts/followup/git-followup-finish.ts

@@ -1,8 +1,8 @@
 import { git_next_issues } from '#scripts/issue/git-next-issues'
 import { review_attest } from '#scripts/review/review-attest'
 import { review_stamps } from '#scripts/review/review-stamps'
-import { run_hold } from '#scripts/run/run-hold'
-import { run_progress_clock } from '#scripts/run/run-progress-clock'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { run_progress_clock } from '#scripts/run/progress/run-progress-clock'
 import { parse_completed_issue_number } from './followup-issue-number'
 import { git_followup_cleanup, type CleanupStep } from './git-followup-cleanup'
 import { git_followup_pending } from './git-followup-pending'

package/scripts/followup/git-followup-label.ts

@@ -1,6 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_safe } from '#scripts/git/parse-json-array'
-import { issue_label_schema } from '#scripts/git/schemas'
 import { IN_PROGRESS_LABEL, label_name_of } from '#scripts/issue/issue-labels'
 import { z } from 'zod'
 
@@ -19,7 +19,7 @@ import { z } from 'zod'
 // No procedure covered the ordinary ending: merged, closed, and still marked as running.
 
 // The `number,labels,body` read answers labels as objects, and this is the one field of it this
-// step needs. The element shape is `schemas.ts`'s rather than a second spelling of it; the wrapper
+// step needs. The element shape is `git-schemas.ts`'s rather than a second spelling of it; the wrapper
 // is local because a read's *field list* is what multiplies helpers when it is shared
 // (`git-gh-issue-read.ts`).
 const labels_read_schema = z.object({ labels: z.array(issue_label_schema).optional() })

package/scripts/followup/git-followup-merged.ts

@@ -66,8 +66,8 @@ function is_posted_since(comment: IssueComment, merged_at: string): boolean {
 	return Date.parse(comment.created_at) >= Date.parse(merged_at)
 }
 
-function parse_comments(comments_json: string | undefined): Array<IssueComment> {
-	const parsed = COMMENTS_SCHEMA.safeParse(json_value.parse_or_undefined(comments_json ?? ''))
+function parse_comments(comments_json: string | undefined = ''): Array<IssueComment> {
+	const parsed = COMMENTS_SCHEMA.safeParse(json_value.parse_or_undefined(comments_json))
 
 	return parsed.success ? parsed.data : []
 }

package/scripts/followup/git-followup-stages.ts

@@ -1,3 +1,4 @@
+import { PrConflictError } from '#scripts/gh/git-pr-checks-eval'
 import { time_format } from '#scripts/time-runtime/time-format'
 
 // Where `pnpm josh followup` spends its own wall clock (joshuafolkken/kit#1349).
@@ -73,8 +74,15 @@ const STAGE = {
 	// blocker and on a red check, and those are the runs whose wait is longest — reporting nothing for
 	// them would leave the measurement blind to exactly the invocations worth measuring.
 	interrupted: 'interrupted',
+	// The interrupted lap when the wait failed on a merge conflict (joshuafolkken/kit#3221), so the
+	// stage block names the cause a resumed session used to look up with `gh pr view`.
+	conflict: 'conflict',
 } as const
 
+function stopped_lap(error: unknown): string {
+	return error instanceof PrConflictError ? STAGE.conflict : STAGE.interrupted
+}
+
 interface FollowupStage {
 	name: string
 	duration_ms: number
@@ -143,6 +151,7 @@ const git_followup_stages = {
 	total_ms,
 	format_stages,
 	print_stages,
+	stopped_lap,
 }
 
 export type { FollowupStage, StageLog }

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

@@ -0,0 +1,142 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
+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 { json_value } from '#scripts/lib/json-value'
+
+// The check wait and the notes read off its snapshot — split out of `git-pr-followup.ts` when it
+// reached its line limit (joshuafolkken/kit#3264). `git-pr-followup` re-exports each name it always
+// exported, so the move changed no call site and no suite that imports from it.
+
+// Named so a test can pin the note without restating it (joshuafolkken/kit#999).
+const WATCH_FAILED_NOTE = 'pr checks --watch failed; falling through to polling'
+
+// The watch is a look ahead, not a gate. It fails when **any** check has failed — CodeRabbit
+// included — and letting that escape ended the run before `evaluate_pr_state` could apply kit#753's
+// CodeRabbit exemption at all. It only ever bit where every check finished inside the two-minute
+// window, so a repository with a slow E2E never saw it and a fast one always would
+// (joshuafolkken/kit#999). What the watch is has since changed — `gh pr checks --watch` went through
+// GraphQL, so joshuafolkken/kit#1028 replaced it with the same poll loop bounded to two minutes —
+// but its place here has not.
+//
+// Falling through costs nothing: whether the merge may proceed is decided in one place below, and a
+// genuinely failing non-CodeRabbit check still ends the wait on the first poll by kit#990's
+// fast-fail rather than by that failure.
+// The watch fails for two different reasons — "a check failed" and "no checks reported on this
+// branch" — and its own error does not say which. The pull request itself can: a failed check leaves
+// a rollup, and a branch with no checks leaves it empty. Falling through on the empty case would
+// trade a failure reported in seconds for the whole budget spent waiting on a required check that is
+// missing rather than pending, so that one is rethrown and the old behavior kept.
+//
+// **Read from the raw payload, not from `parse_pr_state_snapshot`.** That parser never throws: a
+// malformed answer or a schema mismatch degrades to `rollup: []`, which is indistinguishable there
+// from a branch that genuinely has no checks. Rethrowing on it would put an unreadable answer back
+// 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 = json_value.parse_or_undefined(raw_json)
+
+	if (typeof parsed !== 'object' || parsed === null || !('statusCheckRollup' in parsed)) {
+		return false
+	}
+
+	const { statusCheckRollup: rollup } = parsed
+
+	return Array.isArray(rollup) && rollup.length === 0
+}
+
+// The read throws rather than answering `undefined`, so the `catch` is its only failure path.
+//
+// The **checks** half, not the whole snapshot: the question here is about `statusCheckRollup` alone,
+// and reading the review listing to answer it paged a whole conversation for nothing
+// (joshuafolkken/kit#1043).
+async function has_no_checks(branch_name: string): Promise<boolean> {
+	try {
+		const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
+
+		return reads_as_empty_rollup(checks.snapshot_json)
+	} catch {
+		// The read refines the swallow; it is not a gate of its own. An answer it cannot get is not
+		// evidence of anything, so prefer falling through — the poll below reads the same state.
+		return false
+	}
+}
+
+async function handle_watch_failure(branch_name: string, error: unknown): Promise<void> {
+	if (await has_no_checks(branch_name)) throw error
+
+	// Swallowed, but never silently: the reason a run stopped early used to be this line, so it
+	// stays visible even though it no longer decides anything.
+	console.info(`⚠️ ${WATCH_FAILED_NOTE}: ${git_gh_helpers.get_error_message_with_stderr(error)}`)
+}
+
+// **Returns whether the watch confirmed completion** (joshuafolkken/kit#2029): `true` only when
+// `pr_checks_watch` saw every check finish, `false` when it timed out with checks still pending or
+// fell through to polling on a swallowed failure. `run_checks` reads it to decide how many stable poll
+// reads the wait still needs. A timed-out watch (`timed_out: true`) never spanned the pending→settled
+// window, so it must keep the full stable-read window rather than claim the confirmation. A rethrown
+// failure — the empty-rollup case — never reaches a caller, so it needs no answer here.
+async function watch_before_polling(branch_name: string): Promise<boolean> {
+	console.info('')
+	console.info('📊 Watching PR checks...')
+
+	try {
+		const result = await git_gh_command.pr_checks_watch(branch_name)
+
+		return !result.timed_out
+	} catch (error) {
+		await handle_watch_failure(branch_name, error)
+
+		return false
+	}
+}
+
+// **A confirmed watch lowers the poll's stable-read requirement to one** (joshuafolkken/kit#2029). The
+// watch is the first confirmation that every check settled, so the poll that follows need only agree
+// once rather than twice — which removes the extra interval `followup` spent re-proving a settled run.
+// A skipped or fallen-through watch keeps `DEFAULT_STABLE_READS`, and a check that turned red is still
+// caught: the poll evaluates the full merge gate and throws on failure before any stable read counts.
+async function run_checks(input: {
+	branch_name: string
+	is_skip_watch: boolean
+}): Promise<PrStateSnapshot> {
+	const is_watch_confirmed = !input.is_skip_watch && (await watch_before_polling(input.branch_name))
+	const stable_reads = is_watch_confirmed ? WATCH_CONFIRMED_STABLE_READS : DEFAULT_STABLE_READS
+
+	return await git_pr_checks.wait_for_pr_success(input.branch_name, stable_reads)
+}
+
+// Temporary (kit#753): record every CodeRabbit check that was not passing when the merge gate
+// opened, so a merge shipped without CodeRabbit review stays auditable.
+function read_coderabbit_skip_notes(snapshot: PrStateSnapshot): Array<string> {
+	return snapshot.rollup
+		.filter((check) => is_coderabbit_check(check.name))
+		.filter((check) => check.status !== CHECK_STATUS_PASS)
+		.map(
+			(check) =>
+				`CodeRabbit check skipped (kit#753): ${check.name} was ${check.status} at merge time`,
+		)
+}
+
+// The skip is printed where the run is being watched, not only carried into the Telegram body it
+// ends up in. A merge that went ahead while CodeRabbit had not come back is the one thing kit#753's
+// exemption trades away, and it used to be invisible in `followup`'s own output
+// (joshuafolkken/kit#1217).
+function log_skip_notes(notes: ReadonlyArray<string>): void {
+	for (const note of notes) {
+		console.info(`⏭ ${note}`)
+	}
+}
+
+const git_pr_followup_checks = {
+	run_checks,
+	read_coderabbit_skip_notes,
+	log_skip_notes,
+}
+
+export { git_pr_followup_checks, WATCH_FAILED_NOTE }

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

@@ -1,18 +1,9 @@
 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,
@@ -22,12 +13,12 @@ import {
 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_pr_followup_checks } from './git-pr-followup-checks'
 import { git_pr_followup_wrapup } from './git-pr-followup-wrapup'
 
 const { STAGE, lap } = git_followup_stages
+const { run_checks, read_coderabbit_skip_notes, log_skip_notes } = git_pr_followup_checks
 
-// Named so a test can pin the note without restating it (joshuafolkken/kit#999).
-const WATCH_FAILED_NOTE = 'pr checks --watch failed; falling through to polling'
 const REPO_NAME_SEPARATOR = '/'
 
 function parse_repo_name(name_with_owner: string | undefined): string | undefined {
@@ -107,123 +98,6 @@ async function warn_if_missing_closes(branch_name: string): Promise<string | und
 	return undefined
 }
 
-// The watch is a look ahead, not a gate. It fails when **any** check has failed — CodeRabbit
-// included — and letting that escape ended the run before `evaluate_pr_state` could apply kit#753's
-// CodeRabbit exemption at all. It only ever bit where every check finished inside the two-minute
-// window, so a repository with a slow E2E never saw it and a fast one always would
-// (joshuafolkken/kit#999). What the watch is has since changed — `gh pr checks --watch` went through
-// GraphQL, so joshuafolkken/kit#1028 replaced it with the same poll loop bounded to two minutes —
-// but its place here has not.
-//
-// Falling through costs nothing: whether the merge may proceed is decided in one place below, and a
-// genuinely failing non-CodeRabbit check still ends the wait on the first poll by kit#990's
-// fast-fail rather than by that failure.
-// The watch fails for two different reasons — "a check failed" and "no checks reported on this
-// branch" — and its own error does not say which. The pull request itself can: a failed check leaves
-// a rollup, and a branch with no checks leaves it empty. Falling through on the empty case would
-// trade a failure reported in seconds for the whole budget spent waiting on a required check that is
-// missing rather than pending, so that one is rethrown and the old behavior kept.
-//
-// **Read from the raw payload, not from `parse_pr_state_snapshot`.** That parser never throws: a
-// malformed answer or a schema mismatch degrades to `rollup: []`, which is indistinguishable there
-// from a branch that genuinely has no checks. Rethrowing on it would put an unreadable answer back
-// 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 = json_value.parse_or_undefined(raw_json)
-
-	if (typeof parsed !== 'object' || parsed === null || !('statusCheckRollup' in parsed)) {
-		return false
-	}
-
-	const { statusCheckRollup: rollup } = parsed
-
-	return Array.isArray(rollup) && rollup.length === 0
-}
-
-// The read throws rather than answering `undefined`, so the `catch` is its only failure path.
-//
-// The **checks** half, not the whole snapshot: the question here is about `statusCheckRollup` alone,
-// and reading the review listing to answer it paged a whole conversation for nothing
-// (joshuafolkken/kit#1043).
-async function has_no_checks(branch_name: string): Promise<boolean> {
-	try {
-		const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
-
-		return reads_as_empty_rollup(checks.snapshot_json)
-	} catch {
-		// The read refines the swallow; it is not a gate of its own. An answer it cannot get is not
-		// evidence of anything, so prefer falling through — the poll below reads the same state.
-		return false
-	}
-}
-
-async function handle_watch_failure(branch_name: string, error: unknown): Promise<void> {
-	if (await has_no_checks(branch_name)) throw error
-
-	// Swallowed, but never silently: the reason a run stopped early used to be this line, so it
-	// stays visible even though it no longer decides anything.
-	console.info(`⚠️ ${WATCH_FAILED_NOTE}: ${git_gh_helpers.get_error_message_with_stderr(error)}`)
-}
-
-// **Returns whether the watch confirmed completion** (joshuafolkken/kit#2029): `true` only when
-// `pr_checks_watch` saw every check finish, `false` when it timed out with checks still pending or
-// fell through to polling on a swallowed failure. `run_checks` reads it to decide how many stable poll
-// reads the wait still needs. A timed-out watch (`timed_out: true`) never spanned the pending→settled
-// window, so it must keep the full stable-read window rather than claim the confirmation. A rethrown
-// failure — the empty-rollup case — never reaches a caller, so it needs no answer here.
-async function watch_before_polling(branch_name: string): Promise<boolean> {
-	console.info('')
-	console.info('📊 Watching PR checks...')
-
-	try {
-		const result = await git_gh_command.pr_checks_watch(branch_name)
-
-		return !result.timed_out
-	} catch (error) {
-		await handle_watch_failure(branch_name, error)
-
-		return false
-	}
-}
-
-// **A confirmed watch lowers the poll's stable-read requirement to one** (joshuafolkken/kit#2029). The
-// watch is the first confirmation that every check settled, so the poll that follows need only agree
-// once rather than twice — which removes the extra interval `followup` spent re-proving a settled run.
-// A skipped or fallen-through watch keeps `DEFAULT_STABLE_READS`, and a check that turned red is still
-// caught: the poll evaluates the full merge gate and throws on failure before any stable read counts.
-async function run_checks(input: {
-	branch_name: string
-	is_skip_watch: boolean
-}): Promise<PrStateSnapshot> {
-	const is_watch_confirmed = !input.is_skip_watch && (await watch_before_polling(input.branch_name))
-	const stable_reads = is_watch_confirmed ? WATCH_CONFIRMED_STABLE_READS : DEFAULT_STABLE_READS
-
-	return await git_pr_checks.wait_for_pr_success(input.branch_name, stable_reads)
-}
-
-// Temporary (kit#753): record every CodeRabbit check that was not passing when the merge gate
-// opened, so a merge shipped without CodeRabbit review stays auditable.
-function read_coderabbit_skip_notes(snapshot: PrStateSnapshot): Array<string> {
-	return snapshot.rollup
-		.filter((check) => is_coderabbit_check(check.name))
-		.filter((check) => check.status !== CHECK_STATUS_PASS)
-		.map(
-			(check) =>
-				`CodeRabbit check skipped (kit#753): ${check.name} was ${check.status} at merge time`,
-		)
-}
-
-// The skip is printed where the run is being watched, not only carried into the Telegram body it
-// ends up in. A merge that went ahead while CodeRabbit had not come back is the one thing kit#753's
-// exemption trades away, and it used to be invisible in `followup`'s own output
-// (joshuafolkken/kit#1217).
-function log_skip_notes(notes: ReadonlyArray<string>): void {
-	for (const note of notes) {
-		console.info(`⏭ ${note}`)
-	}
-}
-
 // **The one read of the four that can depend on another.** Without an issue number on the command
 // line it is the pull request body that names it (joshuafolkken/kit#1539), so the title read waits
 // for exactly that one and for nothing else. With a number in hand the `??` short-circuits and the
@@ -437,7 +311,7 @@ async function run(input: FollowupInput): Promise<string | undefined> {
 	try {
 		return await run_stages(input, log)
 	} catch (error) {
-		lap(log, STAGE.interrupted)
+		lap(log, git_followup_stages.stopped_lap(error))
 
 		throw error
 	} finally {
@@ -451,7 +325,6 @@ const git_pr_followup = {
 
 export {
 	git_pr_followup,
-	WATCH_FAILED_NOTE,
 	run_checks,
 	build_issue_url,
 	parse_repo_name,
@@ -464,3 +337,5 @@ export {
 }
 export type { FollowupInput }
 export type { TelegramContext } from '#scripts/gh/git-pr-ai-review'
+
+export { WATCH_FAILED_NOTE } from './git-pr-followup-checks'