@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/followup/followup-job-needs.ts

@@ -0,0 +1,100 @@
+import { readFile } from 'node:fs/promises'
+import { yaml_document } from '#scripts/lib/yaml-document'
+import { z } from 'zod'
+
+// A job that only gathers others' results — kit's `Checks`, which `needs` the unit shards — ends
+// `failure` beside a shard red on a test the change never touched, and its log names no test
+// (joshuafolkken/kit#5171). It fails because of that shard alone, so it is rerun with it; the rerun
+// endpoint reruns a failed job's dependents in any case. **The workflow's own `needs` says which job
+// waits on which**, read from the checkout the pull request's head is.
+//
+// A job is known by the name a check run carries, which the workflow writes as a template: an
+// expression in it matches anything, and a name with none gains the ` (<matrix values>)` suffix GitHub
+// appends to a matrix job. A job no pattern matches — a reusable workflow's, a name built otherwise —
+// is waited on by nothing here, so its failure is kept.
+
+const EXPRESSION = /\$\{\{[^}]*\}\}/u
+const EXPRESSION_MARK = '${{'
+const ANY_TEXT = '.+'
+const MATRIX_SUFFIX = String.raw`(?: \(.+\))?`
+const REGEX_SPECIAL = /[$()*+.?[\\\]^{|}]/gu
+
+const needs_schema = z.array(z.string())
+
+const job_schema = z.looseObject({
+	name: z.string().optional(),
+	needs: z.union([z.string(), needs_schema]).optional(),
+})
+
+const workflow_schema = z.looseObject({ jobs: z.record(z.string(), job_schema) })
+
+type WorkflowJobs = z.infer<typeof workflow_schema>['jobs']
+
+interface JobNeeds {
+	pattern: RegExp
+	needs: ReadonlyArray<RegExp>
+}
+
+type NeedsGraph = ReadonlyArray<JobNeeds>
+
+function escape(text: string): string {
+	return text.replaceAll(REGEX_SPECIAL, String.raw`\$&`)
+}
+
+function name_pattern(id: string, name: string = id): RegExp {
+	const source = name.includes(EXPRESSION_MARK)
+		? name
+				.split(EXPRESSION)
+				.map((part) => escape(part))
+				.join(ANY_TEXT)
+		: `${escape(name)}${MATRIX_SUFFIX}`
+
+	return new RegExp(`^${source}$`, 'u')
+}
+
+function needs_list(needs: string | ReadonlyArray<string> = []): ReadonlyArray<string> {
+	return typeof needs === 'string' ? [needs] : needs
+}
+
+function pattern_of(jobs: WorkflowJobs, id: string): RegExp {
+	return name_pattern(id, jobs[id]?.name)
+}
+
+// The jobs of a workflow, each with the names of the jobs it needs; a workflow of another shape has
+// none. YAML that does not parse throws, which `read_graph` answers as none.
+function parse_graph(workflow: string): NeedsGraph {
+	const parsed = workflow_schema.safeParse(yaml_document.parse_yaml(workflow))
+
+	if (!parsed.success) return []
+
+	const { jobs } = parsed.data
+
+	return Object.entries(jobs).map(([id, job]) => ({
+		pattern: pattern_of(jobs, id),
+		needs: needs_list(job.needs).map((need) => pattern_of(jobs, need)),
+	}))
+}
+
+// **Whether the job named `job_name` needs one of the jobs named in `upstream`.**
+function is_waiting_on(
+	graph: NeedsGraph,
+	job_name: string,
+	upstream: ReadonlyArray<string>,
+): boolean {
+	const needs = graph.filter(({ pattern }) => pattern.test(job_name)).flatMap((job) => job.needs)
+
+	return upstream.some((name) => needs.some((pattern) => pattern.test(name)))
+}
+
+async function read_graph(workflow_path: string): Promise<NeedsGraph> {
+	try {
+		return parse_graph(await readFile(workflow_path, 'utf8'))
+	} catch {
+		return []
+	}
+}
+
+const followup_job_needs = { is_waiting_on, parse_graph, read_graph }
+
+export type { NeedsGraph }
+export { followup_job_needs }

package/scripts/followup/followup-job-rerun.ts

@@ -0,0 +1,303 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_branch } from '#scripts/git/git-branch'
+import { poll } from '#scripts/lib/poll'
+import { z } from 'zod'
+import {
+	followup_failed_tests,
+	KEPT_VERDICT,
+	RERUN_VERDICT,
+	UNNAMED_VERDICT,
+	type FailedTests,
+	type TestVerdict,
+} from './followup-failed-tests'
+import { followup_job_needs, type NeedsGraph } from './followup-job-needs'
+import { followup_main_move } from './followup-main-move'
+
+// A GitHub Actions job whose every step succeeded can still end `cancelled` or `timed_out`: the runner
+// stops reporting after the last step and the job's `timeout-minutes` cuts it off (joshuafolkken/kit#4813,
+// two 3-second jobs cut at 2m0s). Nothing in the change caused it, so `followup` reruns such a job once
+// — as `git-gh-retry.ts` retries a GitHub 5xx — rather than failing a pull request that is green.
+//
+// **A job red only on tests outside the change is rerun the same way** (joshuafolkken/kit#5171): a test
+// the diff never touched failing under runner load stopped `followup` and waited for a relaunched
+// session to type the rerun by hand. Only the run's first attempt qualifies, so a test that fails again
+// stops `followup` as before, and each such rerun leaves an observation (`followup-failed-tests.ts`).
+// A job that failed only for waiting on such a job is rerun with it (`followup-job-needs.ts`).
+//
+// The rerun endpoint reruns **every** failed job of a run, and GitHub refuses it while the run is still
+// going. So each run is waited out first, and it is rerun only when every job that failed in it
+// qualifies: a run holding a job that failed on the change itself is never rerun, or a test the change
+// broke could be retried into a merge.
+
+const FAILURE_CONCLUSION = 'failure'
+const FAILED_CONCLUSIONS = [FAILURE_CONCLUSION, 'cancelled', 'timed_out'] as const
+const FAILED_JOB_CONCLUSIONS: ReadonlySet<string> = new Set(FAILED_CONCLUSIONS)
+const ACTIONS_APP_SLUG = 'github-actions'
+const PASSING_STEP_CONCLUSIONS: ReadonlySet<string> = new Set(['success', 'skipped'])
+const RUN_COMPLETED = 'completed'
+const FIRST_ATTEMPT = 1
+
+// The longest `timeout-minutes` in `ci.yml` is 10; a run still going past that is not one a rerun helps.
+const COMPLETE_ATTEMPTS = 40
+const COMPLETE_INTERVAL_MS = 15_000
+
+// The rerun answers once the new attempt exists, but its check runs can trail it; a re-judge that read
+// the failed run again would fail on the very job just rerun.
+const REGISTER_ATTEMPTS = 10
+const REGISTER_INTERVAL_MS = 3000
+
+const failed_check_schema = z.looseObject({
+	id: z.number(),
+	conclusion: z.enum(FAILED_CONCLUSIONS),
+	app: z.looseObject({ slug: z.literal(ACTIONS_APP_SLUG) }),
+})
+
+const rollup_schema = z.looseObject({ statusCheckRollup: z.array(z.unknown()) })
+
+// REST answers `null` for a step that never finished; a test fixture may leave the field out.
+const step_schema = z.looseObject({ conclusion: z.string().nullish() })
+
+const job_schema = z.looseObject({
+	id: z.number(),
+	name: z.string(),
+	run_id: z.number(),
+	run_attempt: z.number().nullish(),
+	conclusion: z.string().nullish(),
+	steps: z.array(step_schema),
+})
+
+// `path` is the workflow file's, relative to the repository root.
+const run_schema = z.looseObject({ status: z.string(), path: z.string().optional() })
+
+const jobs_page_schema = z.looseObject({ jobs: z.array(job_schema) })
+
+type Job = z.infer<typeof job_schema>
+
+// A failed job and what its reading says, with the failed tests when its log named some.
+interface Judged {
+	job: Job
+	verdict: TestVerdict
+	tests?: FailedTests
+}
+
+function actions_api_path(rest: string): string {
+	return `${git_gh_api_path.repo_api_path()}/actions/${rest}`
+}
+
+async function read_actions<T>(rest: string, schema: z.ZodType<T>): Promise<T> {
+	const json = await git_gh_exec.exec_gh_api({ path: actions_api_path(rest) })
+
+	return schema.parse(JSON.parse(json))
+}
+
+async function read_failed_check_ids(branch_name: string): Promise<Array<number>> {
+	const { snapshot_json } = await git_gh_command.pr_get_checks_snapshot(branch_name)
+	const rollup = rollup_schema.parse(JSON.parse(snapshot_json)).statusCheckRollup
+
+	return rollup.flatMap((item) => {
+		const parsed = failed_check_schema.safeParse(item)
+
+		return parsed.success ? parsed.data.id : []
+	})
+}
+
+// A check run of GitHub Actions has its job's id, which is how the job — and so its run — is found.
+async function read_failed_run_ids(branch_name: string): Promise<Array<number>> {
+	const ids = await read_failed_check_ids(branch_name)
+	const jobs = await Promise.all(
+		ids.map(async (id) => await read_actions(`jobs/${String(id)}`, job_schema)),
+	)
+
+	return [...new Set(jobs.map((job) => job.run_id))]
+}
+
+async function is_run_completed(run_id: number): Promise<boolean> {
+	const run = await read_actions(`runs/${String(run_id)}`, run_schema)
+
+	return run.status === RUN_COMPLETED
+}
+
+async function await_run_completed(run_id: number): Promise<boolean> {
+	return await poll.poll_until(async () => await is_run_completed(run_id), {
+		attempts: COMPLETE_ATTEMPTS,
+		interval_ms: COMPLETE_INTERVAL_MS,
+	})
+}
+
+function has_every_step_passed(job: Job): boolean {
+	if (job.steps.length === 0) return false
+
+	return job.steps.every((step) => PASSING_STEP_CONCLUSIONS.has(step.conclusion ?? ''))
+}
+
+function is_first_failure(job: Job): boolean {
+	return (
+		job.conclusion === FAILURE_CONCLUSION && (job.run_attempt ?? FIRST_ATTEMPT) <= FIRST_ATTEMPT
+	)
+}
+
+// A job whose every step passed stopped on the runner; one red on its first attempt is judged by the
+// failed tests its log names. The log endpoint redirects to the plain text, which `gh api` follows; a
+// vitest log is colored.
+async function judge_job(job: Job, changed: ReadonlySet<string>): Promise<Judged> {
+	if (has_every_step_passed(job)) return { job, verdict: RERUN_VERDICT }
+	if (!is_first_failure(job)) return { job, verdict: KEPT_VERDICT }
+
+	const log = await git_gh_exec.exec_gh_api({
+		path: actions_api_path(`jobs/${String(job.id)}/logs`),
+		should_allow_escapes: true,
+	})
+	const tests = followup_failed_tests.read_failed_tests(log)
+
+	return { job, verdict: followup_failed_tests.verdict_of(tests, changed), tests }
+}
+
+function is_red_on_tests({ verdict, tests }: Judged): boolean {
+	return verdict === RERUN_VERDICT && tests !== undefined
+}
+
+// A job red with no test named qualifies only as one waiting on a job red on tests outside the change.
+function settle_unnamed(judged: ReadonlyArray<Judged>, graph: NeedsGraph): Array<Judged> {
+	const red_on_tests = judged.filter((entry) => is_red_on_tests(entry)).map(({ job }) => job.name)
+
+	return judged.map((entry) => {
+		if (entry.verdict !== UNNAMED_VERDICT) return entry
+
+		const is_waiting = followup_job_needs.is_waiting_on(graph, entry.job.name, red_on_tests)
+
+		return is_waiting ? { job: entry.job, verdict: RERUN_VERDICT } : entry
+	})
+}
+
+// The workflow is read only when a job named no test; a run without its `path` waits on nothing.
+async function read_needs_graph(
+	run_id: number,
+	judged: ReadonlyArray<Judged>,
+): Promise<NeedsGraph> {
+	if (judged.every(({ verdict }) => verdict !== UNNAMED_VERDICT)) return []
+
+	const run = await read_actions(`runs/${String(run_id)}`, run_schema)
+
+	return run.path === undefined ? [] : await followup_job_needs.read_graph(run.path)
+}
+
+// **The jobs the rerun would retry**, or `undefined` when the run must not be rerun: still going, or
+// holding a failed job that does not qualify.
+async function read_rerun_jobs(
+	run_id: number,
+	changed: ReadonlySet<string>,
+): Promise<Array<Judged> | undefined> {
+	if (!(await await_run_completed(run_id))) return undefined
+	const { jobs } = await read_actions(
+		`runs/${String(run_id)}/jobs?filter=latest&per_page=100`,
+		jobs_page_schema,
+	)
+	const failed = jobs.filter((job) => FAILED_JOB_CONCLUSIONS.has(job.conclusion ?? ''))
+	const judged = await Promise.all(failed.map(async (job) => await judge_job(job, changed)))
+	const settled = settle_unnamed(judged, await read_needs_graph(run_id, judged))
+
+	return settled.every(({ verdict }) => verdict === RERUN_VERDICT) ? settled : undefined
+}
+
+// One request per run, not retried: a rerun that landed before a transient failure would be refused
+// the second time.
+async function rerun_runs(run_ids: ReadonlyArray<number>): Promise<void> {
+	await Promise.all(
+		run_ids.map(
+			async (run_id) =>
+				await git_gh_exec.exec_gh_api({
+					path: actions_api_path(`runs/${String(run_id)}/rerun-failed-jobs`),
+					method: 'POST',
+					should_retry: false,
+				}),
+		),
+	)
+}
+
+async function await_rerun_registered(
+	branch_name: string,
+	jobs: ReadonlyArray<Job>,
+): Promise<void> {
+	const rerun_ids = new Set(jobs.map((job) => job.id))
+
+	await poll.poll_until(
+		async () => {
+			const failed = await read_failed_check_ids(branch_name)
+
+			return failed.every((id) => !rerun_ids.has(id))
+		},
+		{ attempts: REGISTER_ATTEMPTS, interval_ms: REGISTER_INTERVAL_MS },
+	)
+}
+
+// Every run must qualify: rerunning some would still leave the pull request red on the others. The
+// change is read once, and only when a run failed.
+async function find_rerun_jobs(branch_name: string): Promise<Array<Judged>> {
+	const run_ids = await read_failed_run_ids(branch_name)
+
+	if (run_ids.length === 0) return []
+
+	const changed = new Set(await changed_paths.read_changed_paths(false))
+	const per_run = await Promise.all(
+		run_ids.map(async (run_id) => await read_rerun_jobs(run_id, changed)),
+	)
+
+	return per_run.every((jobs) => jobs !== undefined) ? per_run.flat() : []
+}
+
+async function rerun(branch_name: string, entries: ReadonlyArray<Judged>): Promise<Array<string>> {
+	const jobs = entries.map(({ job }) => job)
+	const names = jobs.map((job) => job.name)
+
+	console.info(
+		`🔁 Rerunning CI jobs that stopped after every step passed or failed only outside the change: ${names.join(', ')}`,
+	)
+	await followup_failed_tests.record(
+		entries.flatMap(({ job, tests }) => (tests === undefined ? [] : { job: job.name, tests })),
+		git_branch.issue_from_branch(branch_name),
+	)
+	await rerun_runs([...new Set(jobs.map((job) => job.run_id))])
+	await await_rerun_registered(branch_name, jobs)
+
+	return names
+}
+
+// A failed test main has since changed is merged before any rerun (`followup-main-move.ts`).
+async function should_merge_first(
+	branch_name: string,
+	entries: ReadonlyArray<Judged>,
+): Promise<boolean> {
+	const files = [...new Set(entries.flatMap(({ tests }) => tests?.files ?? []))]
+
+	return await followup_main_move.should_merge_first(
+		files,
+		git_branch.issue_from_branch(branch_name),
+	)
+}
+
+// **Returns the names of the jobs it reran**, empty when there was none to rerun or main has to be
+// merged first. A read or a rerun that fails is reported and answers empty: the rerun is a recovery,
+// so the original failure stands.
+async function rerun_failed_jobs(branch_name: string): Promise<Array<string>> {
+	try {
+		const entries = await find_rerun_jobs(branch_name)
+
+		if (entries.length === 0 || (await should_merge_first(branch_name, entries))) return []
+
+		return await rerun(branch_name, entries)
+	} catch (error) {
+		console.info(`⚠️ CI job rerun failed: ${git_gh_helpers.get_error_message_with_stderr(error)}`)
+
+		return []
+	}
+}
+
+const followup_job_rerun = {
+	rerun_failed_jobs,
+}
+
+export { followup_job_rerun, COMPLETE_ATTEMPTS, REGISTER_ATTEMPTS }

package/scripts/followup/followup-main-move.ts

@@ -0,0 +1,113 @@
+import { git_command } from '#scripts/git/git-command'
+import { main_merge_guard } from '#scripts/git/main-merge-guard'
+import type { ObservationEntry } from '#scripts/observations/observation-record'
+import { followup_failed_tests } from './followup-failed-tests'
+
+// **A test red outside the change that main has since changed is merged, not rerun**
+// (joshuafolkken/kit#5316): a date-bound test fixed on main went red on a lane still on the old base,
+// and the rerun on that base was red again before `merge_again` (`run-ship-sync.ts`) took main in. So
+// before a rerun, a failed test whose file or subject module (`followup_failed_tests.subjects_of`) main
+// moved since the branch point skips it: `followup` fails as before and ship's merge, gate and push go
+// first. The rerun right is unspent, and after the merge the same file is no longer incoming, so a
+// test still red is rerun once as before.
+
+const OBSERVATION_SLUG = 'followup-main-merge-first'
+const OBSERVATION_DEPTH = 'd1'
+const LATEST_COMMIT = 1
+const SHORT_SHA_LENGTH = 12
+
+interface MainMove {
+	files: ReadonlyArray<string>
+	commit: string
+}
+
+// A failed test file beside the path main moved for it: the file itself or its subject module.
+interface MovedTest {
+	file: string
+	moved: string
+}
+
+function moved_tests(
+	test_files: ReadonlyArray<string>,
+	incoming: ReadonlySet<string>,
+): Array<MovedTest> {
+	return test_files.flatMap((file) => {
+		const moved = followup_failed_tests.subjects_of(file).find((subject) => incoming.has(subject))
+
+		return moved === undefined ? [] : { file, moved }
+	})
+}
+
+// The main-side commit is the latest on main's own line that touched the first moved path.
+async function latest_commit(file: string, main_reference: string): Promise<string> {
+	const [commit] = await git_command.log_first_parent(LATEST_COMMIT, file, main_reference)
+
+	return commit ?? main_reference
+}
+
+// **The failed test files main moved since the branch point**, `undefined` when main did not move or
+// moved none of them. The fetch is what makes `origin/<default>` current, as `main_merge.merge` does.
+async function read_main_move(test_files: ReadonlyArray<string>): Promise<MainMove | undefined> {
+	if (test_files.length === 0) return undefined
+
+	const default_branch = await git_command.get_default_branch()
+
+	await git_command.fetch_branch(default_branch)
+
+	const incoming = new Set(await main_merge_guard.incoming_paths(default_branch))
+	const moved = moved_tests(test_files, incoming)
+	const [first] = moved
+
+	if (first === undefined) return undefined
+
+	return {
+		files: moved.map(({ file }) => file),
+		commit: await latest_commit(first.moved, `origin/${default_branch}`),
+	}
+}
+
+function observation_of(move: MainMove): ObservationEntry {
+	return {
+		slug: OBSERVATION_SLUG,
+		depth: OBSERVATION_DEPTH,
+		where: move.files.join(', '),
+		what: `followup put the main merge before the rerun; the failed test moved on main at ${move.commit.slice(0, SHORT_SHA_LENGTH)}`,
+	}
+}
+
+// A fetch or read that fails is reported and keeps the rerun: the merge is the shortcut, the rerun the
+// recovery that stood before it.
+async function read_or_rerun(test_files: ReadonlyArray<string>): Promise<MainMove | undefined> {
+	try {
+		return await read_main_move(test_files)
+	} catch (error) {
+		console.info(`⚠️ Could not compare the failed tests with main, rerunning: ${String(error)}`)
+
+		return undefined
+	}
+}
+
+// **Whether the rerun is skipped for a merge of main**, with the reason posted on the issue.
+async function should_merge_first(
+	test_files: ReadonlyArray<string>,
+	issue: number | undefined,
+): Promise<boolean> {
+	const move = await read_or_rerun(test_files)
+
+	if (move === undefined) return false
+
+	console.info(
+		`🔀 Not rerunning: main changed the failed tests since the branch point (${move.files.join(', ')}); merge main first.`,
+	)
+	await followup_failed_tests.record_entry(observation_of(move), issue)
+
+	return true
+}
+
+const followup_main_move = {
+	read_main_move,
+	should_merge_first,
+}
+
+export type { MainMove }
+export { followup_main_move, OBSERVATION_SLUG }

package/scripts/followup/followup-review-gates.ts

@@ -0,0 +1,81 @@
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
+import { review_attest } from '#scripts/review/review-attest'
+import { review_interaction } from '#scripts/review/review-interaction'
+import { review_record } from '#scripts/review/review-record'
+
+// The merge gates over the review rounds — that the review read its own checkout, and that each round
+// the change owes left its ledger line. `git-followup-workflow.ts` runs them first, before the gates over
+// the pull request body.
+
+// `/code-review` is forked by the harness and inherits the *session's* working directory, so a run
+// implementing in a lane can be reviewed against a different tree entirely — one holding the
+// previous child's already-merged code. That review finds nothing wrong and says so, and the run
+// would read the silence as a clean round. **This is the seam where that is caught**: a merge is
+// refused unless the review attested the checkout it was briefed on.
+//
+// **Absence is a refusal, not a pass.** The defect produces *no* signal, so a check that only
+// compared two present records would answer `ok` in exactly the state it exists to catch.
+//
+// **Scoped to a checkout that actually briefed a review.** `review_attest.check` answers
+// `not-required` where no `josh review:brief` was run here inside a run's lifetime, so a project or
+// a flow that does not use the brief merges exactly as it did before.
+//
+// The direction is deliberate: a wrongly-refused merge costs one re-run of the review, and a wrongly
+// allowed one ships a diff nobody read. Thrown rather than reported, so no `completion` Telegram is
+// sent and nothing merges — `git_pr_followup.run` is never reached.
+// `ok` means the guard was satisfied and `not-required` means it never applied to this checkout —
+// both let the merge proceed, so the two gates below read the verdict through one predicate rather
+// than repeating the pair of statuses.
+function is_merge_permitted(status: string): boolean {
+	return status === 'ok' || status === 'not-required'
+}
+
+function is_valid_issue(issue_number: string | undefined): issue_number is string {
+	return issue_number !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
+}
+
+async function assert_review_attested(should_merge: boolean): Promise<void> {
+	if (!should_merge) return
+
+	const verdict = await review_attest.check_here()
+
+	if (!is_merge_permitted(verdict.status)) throw new Error(review_attest.refusal_message(verdict))
+
+	const refusal = await issue_watch_gate.review_refusal_here()
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+// Recording a review round as a prose request leaves the recurrence ledger blind whenever it is
+// skipped. **This is the seam where it is a gate instead**: a merge is refused unless the round left
+// a `- rf:` line for its issue, a zero-finding `none` line included — and, for a change to the run
+// tooling, unless the interaction review left its `- ri:` line too (joshuafolkken/kit#4276).
+//
+// **Absence is a refusal, `missing` exactly as `assert_review_attested`'s is** — the defect this
+// exists for produces *no* line, so silence must not read as success. A checkout that keeps no ledger
+// answers `not-required` and merges as before, and a run whose issue the followup cannot identify has
+// no key to check, so it carries on rather than blocking on missing information.
+async function assert_review_recorded(
+	should_merge: boolean,
+	issue_number: string | undefined,
+): Promise<void> {
+	if (!should_merge || !is_valid_issue(issue_number)) return
+
+	const issue = Number(issue_number)
+	const verdict = await review_record.check(issue)
+
+	if (!is_merge_permitted(verdict.status)) throw new Error(review_record.refusal_message(issue))
+
+	const refusal = await review_interaction.refusal(issue)
+
+	if (refusal !== undefined) throw new Error(refusal)
+}
+
+const followup_review_gates = {
+	assert_review_attested,
+	assert_review_recorded,
+	is_valid_issue,
+}
+
+export { followup_review_gates }

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

@@ -7,6 +7,7 @@ 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'
+import { git_followup_stages } from './git-followup-stages'
 
 // **The count of unreleased merges, not the project version**. The local `package.json` version
 // reads as "the version this run just shipped", but children do not bump, so that number names the
@@ -17,38 +18,69 @@ import { git_followup_pending } from './git-followup-pending'
 // Printed after the merge, and the count is read from a freshly fetched default branch — so this
 // run's own merge is already in it and nothing here says otherwise, unlike the Telegram sent one step
 // earlier from a tree the merge had not reached.
-async function print_pending_release(): Promise<void> {
+async function read_pending_release(): Promise<ReadonlyArray<string>> {
 	const line = await git_followup_pending.pending_release_line({ is_merge_pending: false })
 
-	if (line !== undefined) console.info(line)
+	return line === undefined ? [] : [line]
+}
+
+async function print_pending_release(): Promise<void> {
+	const lines = await read_pending_release()
+
+	for (const line of lines) console.info(line)
 }
 
 // #821: surface what to run next right where the completion is read. Printed before the project
 // version line, which stays the final line of the console output by contract.
-async function print_next_issues(completed_issue_number: string | undefined): Promise<void> {
-	const lines = await git_next_issues.fetch_next_issue_lines(
+//
+// Merged runs only, like the epic auto-close: on `--no-merge` the linked issue is still open
+// and still the current task, so a "next" list would hide the one issue that matters.
+async function read_next_issues(
+	completed_issue_number: string | undefined,
+	should_merge: boolean,
+): Promise<ReadonlyArray<string>> {
+	if (!should_merge) return []
+
+	return await git_next_issues.fetch_next_issue_lines(
 		parse_completed_issue_number(completed_issue_number),
 	)
+}
+
+async function print_next_issues(completed_issue_number: string | undefined): Promise<void> {
+	const lines = await read_next_issues(completed_issue_number, true)
+
 	for (const line of lines) console.info(line)
 }
 
-// The tail printed once the workflow itself has finished. `print_pending_release` stays last by
-// contract, so anything added here goes above it.
+// The tail printed once the workflow itself has finished. `print_pending_release`'s line stays last
+// by contract, so anything added here goes above it.
+//
+// **The two reads need nothing from one another, so they go out together** (#5131), and the time
+// they take is printed as a `completion` stage row: the stage block is already out by now, and an
+// untimed tail is the fixed cost `josh ship --log` could not see. The row goes above the completion
+// lines, because the pending-release line is the one that has to stay last.
 async function print_completion(
 	issue_number: string | undefined,
 	should_merge: boolean,
 ): Promise<void> {
+	const started_ms = performance.now()
+	const [next_lines, release_lines] = await Promise.all([
+		read_next_issues(issue_number, should_merge),
+		read_pending_release(),
+	])
+	const duration_ms = performance.now() - started_ms
+
+	console.info(
+		git_followup_stages.format_stage({ name: git_followup_stages.STAGE.completion, duration_ms }),
+	)
 	console.info('')
 	console.info('✅ PR followup completed.')
-	// Merged runs only, like the epic auto-close: on `--no-merge` the linked issue is still open
-	// and still the current task, so a "next" list would hide the one issue that matters.
-	if (should_merge) await print_next_issues(issue_number)
-	await print_pending_release()
+	for (const line of [...next_lines, ...release_lines]) console.info(line)
 }
 
 // A **merged** run ends here, and the round-1 review snapshot's lifetime is one run.
 // `--no-merge` is not the end of one — the pull request is still open and
-// the issue is still the current task, the same line `print_next_issues` and the epic auto-close
+// the issue is still the current task, the same line `read_next_issues` and the epic auto-close
 // already draw — and clearing there would be the unsafe direction: the next round-1 brief would find
 // no record and write a fresh one against the already-fixed tree, which is the arm-A skip over
 // unreviewed fix code the record exists to prevent.