@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,225 @@
+import { git_epic_close } from './git-epic-close'
+import { git_followup_cleanup } from './git-followup-cleanup'
+import { git_followup_flush } from './git-followup-flush'
+import { git_followup_label } from './git-followup-label'
+import { git_followup_stages, type StageLog } from './git-followup-stages'
+import { git_gh_command } from './git-gh-command'
+import { git_notify, type GitNotifyConfig } from './git-notify'
+
+const { STAGE, lap } = git_followup_stages
+
+// **Both destinations, because the step writes to whichever the notify target names.** A hint that
+// only covered the issue would send the reader to the wrong place after a `--notify-target pr` run
+// failed, which is the same defect as naming a command that cannot do the step at all.
+const COMPLETION_COMMENT_RECOVERY =
+	'post the completion report by hand — `gh pr comment <branch>` for the pull request, ' +
+	'`gh api repos/{owner}/{repo}/issues/<N>/comments` for the issue'
+
+// This step **has** a command that finishes it by hand, so it names one — unlike the epic
+// auto-close, whose absence of one is stated rather than papered over.
+const IN_PROGRESS_RECOVERY = 'gh api -X DELETE repos/{owner}/{repo}/issues/<N>/labels/in-progress'
+
+// Everything from the merge gate opening onwards. Split out of `git-pr-followup.ts` because that file
+// had eight code lines of headroom left, and cut here because this is where the run stops being able
+// to fail safely: past the merge, the branch is gone and re-running the command is not a recovery.
+interface WrapupInput {
+	branch_name: string
+	issue_number: string | undefined
+	notify_config: GitNotifyConfig | undefined
+	pr_url: string | undefined
+	should_merge: boolean
+	// The managed config-file report, which reaches the completion report on the Issue as well as the
+	// completion notification (joshuafolkken/kit#1592). Empty on a run that changed nothing `josh sync`
+	// distributes, and an empty one adds no line.
+	managed_notes: ReadonlyArray<string>
+}
+
+function build_notify_body(input: {
+	notify_config: GitNotifyConfig
+	issue_number: string | undefined
+	pr_url: string | undefined
+	managed_notes: ReadonlyArray<string>
+}): string {
+	return git_notify.build_completion_comment_body({
+		message: input.notify_config.message,
+		issue_number: input.issue_number,
+		pr_url: input.pr_url,
+		mentions: input.notify_config.mentions,
+		notes: input.managed_notes,
+	})
+}
+
+function is_blank_issue_body(body: string | undefined): boolean {
+	if (body === undefined) return true
+
+	return body.trim().length === 0
+}
+
+async function post_notify_issue(input: {
+	issue_number: string | undefined
+	body: string
+}): Promise<void> {
+	if (input.issue_number === undefined) {
+		throw new Error('Issue number is required for issue notification.')
+	}
+
+	const current_body = await git_gh_command.issue_get_body(input.issue_number)
+	const should_edit_body = current_body !== undefined && is_blank_issue_body(current_body)
+
+	await (should_edit_body
+		? git_gh_command.issue_edit_body(input.issue_number, input.body)
+		: git_gh_command.issue_comment(input.issue_number, input.body))
+}
+
+function should_notify_pr(target: GitNotifyConfig['target']): boolean {
+	return target === 'pr' || target === 'both'
+}
+
+function should_notify_issue(target: GitNotifyConfig['target']): boolean {
+	return target === 'issue' || target === 'both'
+}
+
+async function post_completion_notification(input: {
+	branch_name: string
+	issue_number: string | undefined
+	notify_config: GitNotifyConfig | undefined
+	pr_url: string | undefined
+	managed_notes: ReadonlyArray<string>
+}): Promise<void> {
+	if (input.notify_config === undefined) return
+
+	const body = build_notify_body({
+		notify_config: input.notify_config,
+		issue_number: input.issue_number,
+		pr_url: input.pr_url,
+		managed_notes: input.managed_notes,
+	})
+	const { target } = input.notify_config
+
+	if (should_notify_pr(target)) {
+		await git_gh_command.pr_comment(input.branch_name, body)
+	}
+
+	if (should_notify_issue(target)) {
+		await post_notify_issue({ issue_number: input.issue_number, body })
+	}
+}
+
+// **Guarded only once the merge has landed** (joshuafolkken/kit#1539) — the rule and its reason are
+// `git-followup-cleanup.ts`, so this module and the run's tail cannot disagree about it. After the
+// merge, a step that throws is reported and the ones after it still run, rather than taking the epic
+// close and the working-tree hold release down with it.
+async function notify_step(input: WrapupInput): Promise<void> {
+	await git_followup_cleanup.run_guarded_step(input.should_merge, {
+		label: 'The completion comment',
+		recovery: COMPLETION_COMMENT_RECOVERY,
+		run: async () => {
+			await post_completion_notification({
+				branch_name: input.branch_name,
+				issue_number: input.issue_number,
+				notify_config: input.notify_config,
+				pr_url: input.pr_url,
+				managed_notes: input.managed_notes,
+			})
+		},
+	})
+}
+
+// No `recovery`: the auto-close has no command of its own, and naming `epic:audit` — which only
+// reports contradictions — would send the reader somewhere that closes nothing. The epic's own task
+// list is what says which children are done.
+async function epic_close_step(input: WrapupInput): Promise<void> {
+	await git_followup_cleanup.run_guarded_step(input.should_merge, {
+		label: 'The epic auto-close',
+		recovery: undefined,
+		run: async () => {
+			await git_epic_close.close_completed_epics({
+				issue_number: input.issue_number,
+				is_merged: input.should_merge,
+			})
+		},
+	})
+}
+
+// **The run's own mark, taken off at the end of the run that wrote it** (joshuafolkken/kit#1794).
+// `in-progress` is added by every entry point before it implements, and nothing took it off on the
+// ordinary ending: the pull request merged, the issue closed, and the mark stayed. Removed here
+// rather than by the workflow procedure because this is the one step that knows the merge landed.
+//
+// **A merged run only.** Without `should_merge` the issue is still open and a run may still be
+// holding it, so taking the mark off would say the opposite of what is true — and the step is not
+// issued at all there, rather than issued and self-skipping. The guard flag is `input.should_merge`
+// like both siblings', so the early return above stays the *only* thing deciding whether the step
+// runs: read as redundant and deleted, a hardcoded `true` would turn the step on for a `--no-merge`
+// run instead of leaving it off.
+async function in_progress_step(input: WrapupInput): Promise<void> {
+	if (!input.should_merge) return
+
+	await git_followup_cleanup.run_guarded_step(input.should_merge, {
+		label: 'The `in-progress` label removal',
+		recovery: IN_PROGRESS_RECOVERY,
+		run: async () => {
+			await git_followup_label.strip_in_progress(input.issue_number)
+		},
+	})
+}
+
+// **The steps after the merge are issued together** (joshuafolkken/kit#1446). The completion
+// comment writes to the issue or the pull request, the auto-close reads the open epics, and the
+// label removal reads and writes the issue's labels; none needs another's answer, and measured
+// serially the first two were 1.9 s and 3.1 s of `followup`'s own clock. Past the merge none can
+// reject another — `run_guarded_step` reports the failure and answers instead — so they settle
+// independently and the stage costs the longest of them rather than their sum.
+//
+// **A run that merged nothing keeps them in sequence, because there is nothing to overlap.**
+// `close_completed_epics` returns immediately without `is_merged`, and the label removal is not
+// issued on that path at all — so the serial branch is one real step and a no-op beside it. There
+// the guard is off, so a failure still ends the run and re-running the command is the whole recovery
+// (`git-followup-cleanup.ts`), which is easier to read as one sequence than as a settled set.
+//
+// **What the overlap costs, stated rather than glossed**: mutating requests now go out at once
+// against one repository — a comment write, an auto-close that comments on and closes epics, and a
+// label delete — which is what GitHub's secondary rate limit guidance is about. Past the merge all
+// of them are guarded, so the worst case is a cleanup reported as unfinished rather than a failed
+// run, and this is a handful of requests rather than a fan-out. **Their console output can
+// interleave too**: the guard's warning and its recovery line are printed as they happen, so an
+// auto-close progress line can land between them. The recovery line names its own command and stands
+// on its own, so it is still readable out of order — and the alternative, buffering one step's
+// output until the others settle, would hold back a warning about work that has already failed.
+async function run_tail_steps(input: WrapupInput): Promise<void> {
+	if (!input.should_merge) {
+		await notify_step(input)
+		await epic_close_step(input)
+
+		return
+	}
+
+	await Promise.all([notify_step(input), epic_close_step(input), in_progress_step(input)])
+}
+
+async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {
+	if (input.should_merge) {
+		await git_gh_command.pr_merge(input.branch_name)
+		lap(log, STAGE.merge)
+	}
+
+	await run_tail_steps(input)
+	// After the merge tail and before the hold is released (`git-followup-finish.ts`): the ledger
+	// flush switches branches, so it must land while this run still holds the tree (kit#1810).
+	await git_followup_flush.flush_ledger_step(input.should_merge)
+
+	lap(log, STAGE.completion_and_epic_close)
+}
+
+const git_pr_followup_wrapup = {
+	run_wrapup,
+}
+
+export {
+	git_pr_followup_wrapup,
+	post_notify_issue,
+	post_completion_notification,
+	is_blank_issue_body,
+	build_notify_body,
+}
+export type { WrapupInput }

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

@@ -0,0 +1,436 @@
+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
+
+// Captures the number, so the one pattern answers both questions the run asks of a PR body: whether
+// the linked issue will auto-close, and — since joshuafolkken/kit#1539 — which issue that is when the
+// invocation did not say. A second pattern here would be two readings of "closes #N" to disagree.
+const CLOSES_PATTERN = /closes\s+#(\d+)/iu
+// 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 {
+	if (name_with_owner === undefined) return undefined
+	const parts = name_with_owner.split(REPO_NAME_SEPARATOR)
+
+	return parts.at(-1)
+}
+
+function build_telegram_input(input: {
+	task_type: TelegramTaskType
+	context: TelegramContext
+	body: string | undefined
+}): TelegramSendInput {
+	return {
+		task_type: input.task_type,
+		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 sibling issue URL of a pull request: same repository, the number this run is closing. Read
+// through the shared parser rather than a second pattern here, so the two cannot disagree about what
+// a github.com URL looks like (joshuafolkken/kit#994).
+function build_issue_url(
+	pr_url: string | undefined,
+	issue_number: string | undefined,
+): string | undefined {
+	if (issue_number === undefined) return undefined
+	const target = github_issue_url.parse_pull(pr_url)
+	if (target === undefined) return undefined
+
+	return `${target.base_url}/issues/${issue_number}`
+}
+
+interface FollowupInput {
+	branch_name: string
+	issue_number: string | undefined
+	notify_config: GitNotifyConfig | undefined
+	coderabbit_ignore_reason: string | undefined
+	ai_review_ignore_reason: string | undefined
+	is_skip_watch: boolean
+	should_merge: boolean
+}
+
+function parse_closes_issue_number(body: string | undefined): string | undefined {
+	if (body === undefined) return undefined
+
+	return CLOSES_PATTERN.exec(body)?.[1]
+}
+
+function has_closes_keyword(body: string | undefined): boolean {
+	return parse_closes_issue_number(body) !== undefined
+}
+
+// **Returns the number it warned about the absence of** (joshuafolkken/kit#1539). The issue number
+// used to reach the notification from the command line alone, so an invocation that omitted it threw
+// after the merge had already landed. This stage reads the pull request body anyway, and that body
+// carries the number in its `closes #N` keyword — so the read the warning already makes is what
+// recovers it, at no extra request.
+async function warn_if_missing_closes(branch_name: string): Promise<string | undefined> {
+	const body = await git_gh_command.pr_get_body(branch_name)
+	const closes_number = parse_closes_issue_number(body)
+
+	if (closes_number !== undefined) return closes_number
+
+	console.warn('')
+	console.warn(
+		'⚠️  PR body is missing a "closes #N" keyword — the linked Issue will not auto-close on merge.',
+	)
+	console.warn('   Recovery: pnpm josh pr  (or: pnpm josh git -y --skip-commit --skip-push)')
+	console.warn('')
+
+	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 = git_pr_checks_parse.parse_json_safe(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
+// promise is never awaited at all, which is what lets this read go out in the same tick as the other
+// three.
+async function read_issue_title(
+	issue_number: string | undefined,
+	closes_number: Promise<string | undefined>,
+): Promise<string | undefined> {
+	const number = issue_number ?? (await closes_number)
+	if (number === undefined) return undefined
+
+	return await git_gh_command.issue_get_title(number)
+}
+
+interface RunContext {
+	issue_number: string | undefined
+	context: TelegramContext
+}
+
+// **The four reads in front of the check wait are issued together** (joshuafolkken/kit#1446). Not one
+// of them is a wait on anything: the `closes #N` check reads the pull request body, and the
+// notification needs the repository name, the issue title and the pull request URL — four requests
+// that were sent one at a time for 5.5 of `followup`'s measured 45.8 seconds, purely because they
+// were written as consecutive statements.
+//
+// **This overlaps requests; it decides nothing differently.** The `closes #N` warning still fires on
+// the same body, the context still carries the same four fields, and the required-check wait and the
+// AI-review scan below — the merge gate itself — are untouched. Overlapping two reads that do not
+// depend on each other is the whole of the change; skipping one would be a different thing entirely.
+//
+// **Every promise is handed to `Promise.all` in the same synchronous block**, so a rejection has a
+// handler attached in the tick it was created — the first failure still ends the run, and no other
+// read is left rejecting into nothing.
+async function read_run_context(input: {
+	branch_name: string
+	issue_number: string | undefined
+}): Promise<RunContext> {
+	const closes = warn_if_missing_closes(input.branch_name)
+	const owner = git_gh_command.repo_get_name_with_owner()
+	const url = git_gh_command.pr_get_url(input.branch_name)
+	const title = read_issue_title(input.issue_number, closes)
+	const [closes_number, name_with_owner, pr_url, issue_title] = await Promise.all([
+		closes,
+		owner,
+		url,
+		title,
+	])
+	const issue_number = input.issue_number ?? closes_number
+
+	return {
+		issue_number,
+		context: {
+			repo_name: parse_repo_name(name_with_owner),
+			issue_title,
+			issue_url: build_issue_url(pr_url, issue_number),
+			pr_url,
+		},
+	}
+}
+
+// The pending count replaces the project version line (joshuafolkken/kit#1486): children no longer
+// bump, so the local `package.json` names the previous release rather than what this run ships.
+// A count that could not be read contributes no line at all, rather than a zero nobody measured.
+async function notify_completion(
+	context: TelegramContext,
+	skip_notes: ReadonlyArray<string>,
+	is_merge_pending: boolean,
+): Promise<void> {
+	const pending_line = await git_followup_pending.pending_release_line({ is_merge_pending })
+	const lines = pending_line === undefined ? skip_notes : [pending_line, ...skip_notes]
+	const body = lines.join('\n')
+
+	// **The tolerant send** (joshuafolkken/kit#1564): this runs on the way to the merge, so a Telegram
+	// gateway timeout must not leave a reviewed, green pull request unmerged. The failure is reported
+	// under `❗` and the run carries on.
+	//
+	// **No recovery line**, deliberately, in the same sense `git_followup_cleanup`'s epic-close step
+	// has none: a completion notification is never re-sent by hand — `pnpm josh notify --task-type
+	// completion` is prohibited because it populates no PR link — and re-running `followup` after the
+	// merge is not a re-send either. Naming either would send the reader somewhere useless.
+	await telegram_notify.send_or_report(
+		build_telegram_input({
+			task_type: 'completion',
+			context,
+			body,
+		}),
+		undefined,
+	)
+}
+
+// The two comment scans, marked separately from the check wait because they answer a different
+// question: the wait is time GitHub took, and these are requests this command chose to make.
+async function run_comment_scans(
+	input: FollowupInput,
+	context: TelegramContext,
+	log: StageLog,
+): Promise<Array<string>> {
+	const comment_notes = await git_pr_coderabbit.handle_coderabbit_findings({
+		branch_name: input.branch_name,
+		ignore_reason: input.coderabbit_ignore_reason,
+	})
+
+	lap(log, STAGE.coderabbit_comments)
+	const ai_review_notes = await git_pr_ai_review.handle_ai_review_findings({
+		branch_name: input.branch_name,
+		ignore_reason: input.ai_review_ignore_reason,
+		context,
+	})
+
+	lap(log, STAGE.ai_review_comments)
+
+	return [...comment_notes, ...ai_review_notes]
+}
+
+// **The managed config-file read runs first, ahead of the check wait** (joshuafolkken/kit#1578). It
+// reads the branch diff and nothing else, so its answer is in hand before CI is waited on at all.
+// Since joshuafolkken/kit#1592 that answer stops nothing — it is a report — but the position is kept:
+// a read this cheap belongs beside the other things decided from the diff.
+//
+// **It laps no stage of its own.** The printed stage sequence is asserted as an exact list, and a
+// diff read this cheap is not what a measurement of `followup` is looking for; its cost lands inside
+// `checks-wait`, where it is indistinguishable from noise.
+//
+// **The managed report comes back beside the notes as well as inside them**, because the two have
+// different destinations: every note reaches the completion notification, and this one alone also
+// reaches the completion report posted to the Issue (joshuafolkken/kit#1592). Returning it twice is
+// what lets `run_stages` hand each destination what belongs to it without re-deriving the answer.
+async function run_review_checks(
+	input: FollowupInput,
+	context: TelegramContext,
+	log: StageLog,
+): Promise<{ notes: Array<string>; managed: Array<string> }> {
+	const managed = await git_pr_managed_config.handle_managed_config_changes({
+		should_merge: input.should_merge,
+	})
+	const snapshot = await run_checks({
+		branch_name: input.branch_name,
+		is_skip_watch: input.is_skip_watch,
+	})
+
+	lap(log, STAGE.checks_wait)
+	const check_notes = read_coderabbit_skip_notes(snapshot)
+
+	log_skip_notes(check_notes)
+	const scan_notes = await run_comment_scans(input, context, log)
+
+	return { notes: [...managed, ...check_notes, ...scan_notes], managed }
+}
+
+// **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
+// the epic close all name the same issue — and so the caller's own tail can record a run whose number
+// only the pull request knew.
+async function run_stages(input: FollowupInput, log: StageLog): Promise<string | undefined> {
+	const { issue_number, context } = await read_run_context(input)
+
+	lap(log, STAGE.closes_and_context)
+	const checks = await run_review_checks(input, context, log)
+
+	await notify_completion(context, checks.notes, input.should_merge)
+
+	lap(log, STAGE.telegram)
+	await git_pr_followup_wrapup.run_wrapup(
+		{
+			branch_name: input.branch_name,
+			issue_number,
+			notify_config: input.notify_config,
+			pr_url: context.pr_url,
+			should_merge: input.should_merge,
+			managed_notes: checks.managed,
+		},
+		log,
+	)
+
+	return issue_number
+}
+
+// **The stage block is printed on the way out of every run, failed ones included**
+// (joshuafolkken/kit#1349). A `followup` that exits non-zero on an AI-review blocker or a red check is
+// the invocation whose wait was longest, and one that printed nothing would leave the measurement
+// blind to exactly those. The `catch` marks the lap that was still running so the failing stage is
+// reported rather than dropped, and rethrows unchanged — a silent run is still a failed run.
+async function run(input: FollowupInput): Promise<string | undefined> {
+	const log = git_followup_stages.new_log()
+
+	try {
+		return await run_stages(input, log)
+	} catch (error) {
+		lap(log, STAGE.interrupted)
+
+		throw error
+	} finally {
+		git_followup_stages.print_stages(log)
+	}
+}
+
+const git_pr_followup = {
+	run,
+}
+
+export {
+	git_pr_followup,
+	WATCH_FAILED_NOTE,
+	run_checks,
+	build_issue_url,
+	parse_repo_name,
+	build_telegram_input,
+	has_closes_keyword,
+	parse_closes_issue_number,
+	warn_if_missing_closes,
+	read_coderabbit_skip_notes,
+	log_skip_notes,
+}
+export type { FollowupInput }
+export type { TelegramContext } from './git-pr-ai-review'