@joshuafolkken/kit 1.872.0

package/scripts/git/git-error.ts

@@ -0,0 +1,78 @@
+import { has_stderr_field } from './git-gh-exec'
+
+function get_error_message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+function get_stderr_from_error(cause: Error): string | undefined {
+	if (!has_stderr_field(cause)) return undefined
+
+	const stderr = cause.stderr.trim()
+
+	return stderr.length > 0 ? stderr : undefined
+}
+
+function get_error_message_from_cause(cause: Error): string | undefined {
+	const message = cause.message.trim()
+
+	if (message.length > 0) {
+		return message
+	}
+
+	return get_stderr_from_error(cause)
+}
+
+function get_cause_message(cause: unknown): string | undefined {
+	if (cause instanceof Error) {
+		return get_error_message_from_cause(cause)
+	}
+
+	if (typeof cause === 'string') {
+		return cause.trim()
+	}
+
+	return undefined
+}
+
+function display_error_details(cause: unknown): void {
+	const cause_message = get_cause_message(cause)
+
+	if (cause_message === undefined || cause_message.length === 0) {
+		return
+	}
+
+	console.error('')
+	console.error('💡 Details:', cause_message)
+}
+
+function handle(error: unknown): void {
+	const error_message = get_error_message(error)
+
+	console.error('')
+	console.error('❌ Error:', error_message)
+
+	if (error instanceof Error && error.cause !== undefined) {
+		display_error_details(error.cause)
+	}
+
+	console.error('')
+	process.exit(1)
+}
+
+function display_branch_mismatch_error(current_branch: string, target_branch_name: string): void {
+	console.error('')
+	console.error('❌ Branch mismatch detected')
+	console.error('')
+	console.error(`Current branch: ${current_branch}`)
+	console.error(`Expected branch: ${target_branch_name}`)
+	console.error('')
+	console.error('💡 Please update main branch to the latest and try again.')
+	process.exit(1)
+}
+
+const git_error = {
+	handle,
+	display_branch_mismatch_error,
+}
+
+export { git_error }

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

@@ -0,0 +1,35 @@
+// Extract the exit code from a thrown execa error. Returns the numeric exit code,
+// or undefined when the process was terminated by a signal or failed to spawn.
+function get_exit_code(error: unknown): number | undefined {
+	if (typeof error !== 'object' || error === null) return undefined
+	if (!('exitCode' in error)) return undefined
+
+	const { exitCode: exit_code } = error
+
+	return typeof exit_code === 'number' ? exit_code : undefined
+}
+
+// Whether execa killed this spawn on its own budget, which is the only reliable way to tell a
+// timeout from any other non-zero exit — a killed process writes nothing of its own, so a hang that
+// had printed one line first would otherwise be reported as whatever that line happened to say.
+//
+// It lives here rather than beside either caller because both `gh` and `git push` now pass a
+// timeout, and a second copy of the same three lines is the duplication `CLAUDE.md` prohibits
+// (joshuafolkken/kit#1251).
+function has_timed_out(error: unknown): boolean {
+	if (typeof error !== 'object' || error === null || !('timedOut' in error)) return false
+
+	return error.timedOut === true
+}
+
+// The error a spawned git command fails with. The exit code is carried on `cause` as well as in the
+// message, because callers branch on it rather than parse it: `git_command.push` reads 128 there to
+// decide whether to retry with `--set-upstream`.
+function create_spawn_error(command: string, exit_code: number | undefined): Error {
+	const exit_code_string = exit_code === undefined ? 'unknown' : String(exit_code)
+	const error_message = `git ${command} exited with code ${exit_code_string}`
+
+	return new Error(error_message, { cause: { exit_code: exit_code_string } })
+}
+
+export { create_spawn_error, get_exit_code, has_timed_out }

package/scripts/git/git-fixture-workspace.ts

@@ -0,0 +1,88 @@
+import { mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { execa } from 'execa'
+import { git_location_environment } from './git-location-environment'
+
+// The scaffolding a test needs to drive **real git** in a throwaway repository
+// (joshuafolkken/kit#1533).
+//
+// Two suites need it — `lane-change-base.test.ts` builds a lane topology, `rename-changed-paths.test.ts`
+// builds a branch that renames a file away — and neither can use a mocked git, because what each one
+// asserts is a property of git itself rather than of an argument list this repository assembles.
+//
+// **It is one module rather than one copy per suite because this scaffolding has already had to be
+// hardened once.** joshuafolkken/kit#1530 found these fixtures committing into the repository the
+// suite was running in: under a git hook, `GIT_DIR` and `GIT_INDEX_FILE` beat `cwd` outright, and
+// `git config user.email` wrote the fixture's identity into a `--local` config that every linked work
+// tree shares. Both halves of that fix live below. A second copy would take the next such hardening
+// in one place and silently keep the old behavior in the other — the clone `CLAUDE.md` prohibits.
+
+// `restore_environment` is declared as "present, possibly undefined" rather than optional:
+// `exactOptionalPropertyTypes` is on, so an optional property cannot be *assigned* `undefined`, and
+// every suite here starts from a literal that has not opened a workspace yet.
+interface FixtureWorkspace {
+	workspace: string
+	previous_cwd: string
+	restore_environment: (() => void) | undefined
+}
+
+const MAIN_BRANCH = '--initial-branch=main'
+
+// The name commits are authored under, exported because a suite asserts it: proving the identity
+// reached the commit is half of proving it was never written into a config file.
+const AUTHOR_NAME = 'Kit Fixture'
+
+// **The identity rides on `-c` rather than being written with `git config`** (joshuafolkken/kit#1530).
+// A `--local` write outlives the test and is shared by every work tree of the repository it lands in;
+// an option is scoped to the one command.
+const IDENTITY_OPTIONS: ReadonlyArray<string> = [
+	'-c',
+	'user.email=fixture@example.test',
+	'-c',
+	`user.name=${AUTHOR_NAME}`,
+	'-c',
+	'commit.gpgsign=false',
+]
+
+// **The environment is cleared rather than inherited** (joshuafolkken/kit#1530). Run from a git hook,
+// this process holds `GIT_DIR` and `GIT_INDEX_FILE` pointing at the repository being pushed, and both
+// beat `cwd` — so every command here would act on that repository instead of on the fixture.
+async function git(cwd: string, arguments_: ReadonlyArray<string>): Promise<string> {
+	const { stdout } = await execa('git', [...IDENTITY_OPTIONS, ...arguments_], {
+		cwd,
+		env: git_location_environment.location_free_environment(),
+		extendEnv: true,
+	})
+
+	return stdout.trimEnd()
+}
+
+// Cleared for this process too, not only for the children `git` spawns: a suite's assertions drive
+// `git_command`, which spawns git with no environment of its own and so inherits this one.
+function open_workspace(prefix: string): FixtureWorkspace {
+	return {
+		restore_environment: git_location_environment.clear_git_location_variables(),
+		previous_cwd: process.cwd(),
+		workspace: mkdtempSync(path.join(tmpdir(), prefix)),
+	}
+}
+
+async function close_workspace(fixture: FixtureWorkspace): Promise<void> {
+	process.chdir(fixture.previous_cwd)
+	fixture.restore_environment?.()
+	await rm(fixture.workspace, { force: true, recursive: true })
+}
+
+const git_fixture_workspace = {
+	AUTHOR_NAME,
+	close_workspace,
+	git,
+	IDENTITY_OPTIONS,
+	MAIN_BRANCH,
+	open_workspace,
+}
+
+export type { FixtureWorkspace }
+export { git_fixture_workspace }

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

@@ -0,0 +1,88 @@
+import { git_gh_helpers } from './git-gh-helpers'
+
+// joshuafolkken/kit#1539: everything a run does after its merge is cleanup, and a merge cannot be
+// taken back. Those steps used to be plain sequential statements, so whichever of them threw first
+// discarded every one after it — and the working-tree hold release is the last of them. Three runs
+// (joshuafolkken/kit#1197, #1537, #1319) ended that way: merged, the issue closed, and the hold left
+// behind for the next run to trip over.
+//
+// **A step is run on its own, and its failure never reaches the next one.** The whole point is that
+// the steps are independent: the completion comment has nothing to do with the hold release, and
+// letting one decide the other is wrong whatever made it fail — this Issue's own defect, a Telegram
+// rate limit, or a Bad Gateway from GitHub.
+//
+// **Reported, never swallowed.** A cleanup that failed invisibly is a run that lies about what it
+// did, so the failure is printed where the run is being watched, with the command that finishes the
+// step by hand.
+// `recovery` carries a command that genuinely finishes the step, and is **`undefined` where no such
+// command exists** — the epic auto-close and the run report have no CLI entry point of their own, and
+// naming a command that only *reports* would send the reader somewhere that cannot fix anything. It
+// is stated rather than omitted so that every step answers the question one way or the other.
+interface CleanupStep {
+	label: string
+	recovery: string | undefined
+	run: () => Promise<void>
+}
+
+function report_failure(step: CleanupStep, error: unknown): void {
+	console.warn('')
+	console.warn(
+		`⚠️  ${step.label} failed after the merge: ${git_gh_helpers.get_error_message_with_stderr(error)}`,
+	)
+
+	if (step.recovery !== undefined) console.warn(`   Recovery: ${step.recovery}`)
+	console.warn('')
+}
+
+// Answers whether the step completed, so a caller can report what is left rather than having to
+// catch anything itself.
+async function run_step(step: CleanupStep): Promise<boolean> {
+	try {
+		await step.run()
+
+		return true
+	} catch (error) {
+		report_failure(step, error)
+
+		return false
+	}
+}
+
+// **The guard is what a merge earned, and nothing else.** Before the merge nothing irreversible has
+// happened and re-running `pnpm josh followup` is the whole recovery, so a failure there still ends
+// the run — swallowing it would hide a real failure behind a report saying the merge had landed. One
+// definition, so the two callers of this module cannot disagree about when a step is guarded.
+async function run_guarded_step(is_guarded: boolean, step: CleanupStep): Promise<boolean> {
+	if (!is_guarded) {
+		await step.run()
+
+		return true
+	}
+
+	return await run_step(step)
+}
+
+// Every step runs, in order, however many of them fail. The answer is whether all of them completed.
+async function run_guarded_steps(
+	is_guarded: boolean,
+	steps: ReadonlyArray<CleanupStep>,
+): Promise<boolean> {
+	let is_complete = true
+
+	for (const step of steps) {
+		const is_done = await run_guarded_step(is_guarded, step)
+
+		if (!is_done) is_complete = false
+	}
+
+	return is_complete
+}
+
+const git_followup_cleanup = {
+	run_step,
+	run_guarded_step,
+	run_guarded_steps,
+}
+
+export { git_followup_cleanup }
+export type { CleanupStep }

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

@@ -0,0 +1,63 @@
+import { observation_ledger } from '#scripts/observations/observation-ledger'
+import { observation_ledger_home } from '#scripts/observations/observation-ledger-home'
+import { observations_flush } from '#scripts/observations/observations-flush'
+import { git_command } from './git-command'
+import { git_followup_cleanup } from './git-followup-cleanup'
+import { main_sync } from './main-sync'
+
+// The observation ledger's only commit path is `pnpm josh observations:flush`, and until now no
+// command's procedure called it (joshuafolkken/kit#1810). The ledger is excluded from ordinary
+// staging (joshuafolkken/kit#1756), so an appended line stayed in the working tree until a person
+// remembered to flush it — the same "a run that had to remember is the run that forgets" defect the
+// staging side was built to avoid, left standing on the commit side. This wires the flush into
+// `pnpm josh followup`, the one step that knows the merge has landed.
+//
+// **It runs before the working-tree hold is released** (`scripts-ai/git-followup-finish.ts`, whose
+// `finish()` runs after `git_pr_followup.run()` returns), because a flush switches branches, and a
+// hold released first would let another run grab the tree mid-switch.
+
+const MAIN_SYNC_SUCCESS = 0
+const FLUSH_RECOVERY = 'pnpm josh observations:flush'
+const SYNC_FAILURE_MESSAGE =
+	'Could not return to the default branch to flush the observation ledger; `pnpm josh ms` printed the reason above.'
+
+// `observations_flush.flush` requires the default branch, so the checkout is returned to it first.
+// `main_sync.run` catches its own errors and answers with an exit code rather than throwing, so a
+// checkout it could not move is turned into the throw the guarded step below reports.
+async function sync_and_flush(): Promise<void> {
+	if ((await main_sync.run([])) !== MAIN_SYNC_SUCCESS) throw new Error(SYNC_FAILURE_MESSAGE)
+
+	console.info(await observations_flush.flush(new Date()))
+}
+
+// **Short-circuits when the ledger holds no pending append.** That is every run that recorded no
+// observation, so the ordinary run pays nothing. Guarded like its sibling tail steps (joshuafolkken/kit#1539): past the merge a flush
+// failure is reported, never allowed to take the merge, the epic close and the hold release with it.
+//
+// **A lane skips it outright** (joshuafolkken/kit#2419). Its ledger is the primary checkout's
+// (`observation-ledger-home.ts`), which this step cannot flush — `main_sync` refuses in a linked work
+// tree — so the line waits in the primary checkout and the `backlogrun` commits every lane's lines at
+// once through `pnpm josh run:carry --end` (joshuafolkken/kit#2492).
+async function flush_ledger_step(should_merge: boolean): Promise<void> {
+	if (
+		!should_merge ||
+		observation_ledger_home.is_lane() ||
+		!observation_ledger.has_pending_append(await git_command.status())
+	) {
+		return
+	}
+
+	// `should_merge` is always true past the early return; it is passed on as `run_guarded_step`'s
+	// guard flag rather than a literal `true` so this step stays identical to its sibling tail steps —
+	// hardcoding `true` would turn the guard on for a `--no-merge` run if the early return were ever
+	// dropped (the trap `in_progress_step` warns of).
+	await git_followup_cleanup.run_guarded_step(should_merge, {
+		label: 'The observation ledger flush',
+		recovery: FLUSH_RECOVERY,
+		run: sync_and_flush,
+	})
+}
+
+const git_followup_flush = { flush_ledger_step }
+
+export { git_followup_flush }

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

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+import { git_gh_command } from './git-gh-command'
+import { IN_PROGRESS_LABEL, label_name_of } from './issue-labels'
+import { parse_json_object_safe } from './parse-json-array'
+import { issue_label_schema } from './schemas'
+
+// **`in-progress` means "a run is holding this issue right now", and a merged run is not holding
+// anything** (joshuafolkken/kit#1794). `pnpm josh followup` merged the pull request and closed the
+// issue and left the label on it, so the mark stopped meaning what it says: the ledger entry
+// `k:followup-leaves-in-progress-label` recorded it on 2026-09-11 and a second sighting the same day
+// — both issues of one `queue` answering `labels: in-progress` after they had closed.
+//
+// **Nothing is broken today, and that is the whole of the argument for fixing it.** `epic:next`,
+// `epic:busy`, `run:progress` and the `auto-ok` pickup each filter to open issues, so a closed issue
+// carrying the label is invisible to all of them — until one of them loses that open filter, at
+// which point the label is already on every issue the repository has ever run.
+//
+// `queue.md` does tell whoever finds one to take it off, but that is the **failed child**'s route.
+// 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
+// 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() })
+
+// **Read, then removed — never removed on a guess.** The removal names the label in the request
+// path, so it has to name the spelling GitHub stored: GitHub keeps the casing a label was created
+// with and treats `In-Progress` as the same label, and a repository spelling it that way is exactly
+// the one joshuafolkken/kit#1132 was filed about. The comparison is `label_name_of`'s, the same one
+// every other membership test in this codebase goes through.
+function unreadable_error(issue_number: string): Error {
+	return new Error(`gh api answered no readable labels for issue #${issue_number}`)
+}
+
+async function read_label_names(issue_number: string): Promise<ReadonlyArray<string>> {
+	const raw = await git_gh_command.issue_get_labels_and_body(issue_number)
+	if (raw === undefined) throw unreadable_error(issue_number)
+
+	const parsed = parse_json_object_safe(raw, labels_read_schema)
+	if (parsed === undefined) throw unreadable_error(issue_number)
+
+	return (parsed.labels ?? []).map((label) => label.name)
+}
+
+// **An issue that does not carry it is never written to**, which is what keeps the step silent on a
+// run whose issue was never labelled — a `404` swallowed into a warning would report a failure where
+// there was nothing to do. The read itself is always paid: one `number,labels,body` call per merged
+// run, which is the read `git-epic-read.ts` already makes rather than a field list of its own.
+//
+// A run whose pull request named no issue has nothing to strip, so it returns rather than throwing:
+// the number is recovered from the `closes #N` keyword, and its absence is already reported where
+// the completion report is.
+async function strip_in_progress(issue_number: string | undefined): Promise<void> {
+	if (issue_number === undefined) return
+
+	const stored = label_name_of(await read_label_names(issue_number), IN_PROGRESS_LABEL)
+	if (stored === undefined) return
+
+	await git_gh_command.issue_remove_label(issue_number, stored)
+}
+
+const git_followup_label = {
+	strip_in_progress,
+}
+
+export { git_followup_label }

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

@@ -0,0 +1,95 @@
+import { release_history, type HistoryReader } from '#scripts/release/release-history'
+import { release_plan } from '#scripts/release/release-plan'
+import { version_targets } from '#scripts/version/version-targets'
+import { git_command } from './git-command'
+
+// What the completion notification says about versions, now that children do not set one
+// (joshuafolkken/kit#1486).
+//
+// **It used to read `package.json` and print `📦 project version: <v>`.** While every child ran
+// `pnpm josh bump minor` that value was this run's shipping version. Children no longer bump — the
+// version is decided from main's history by `pnpm josh release` — so the same read now returns the
+// **previous** release, and printing it presents an unconfirmed shipping version as a fact.
+//
+// **What goes out instead is the number a release is made of**: how many merges main has taken since
+// the version last changed. It is the count `pnpm josh release` itself acts on, taken from that
+// command's own modules rather than re-derived here, and it doubles as the visible signal that a
+// release is owed — a count that keeps climbing is a release nobody has run.
+
+// **The Telegram is sent before the merge**, deliberately: `git-pr-followup.ts` cuts its wrap-up
+// there because that is the last point at which the run can still fail safely. So the count taken
+// there cannot include this run's own merge, and a bare number would be understated by exactly one.
+// Saying so is the honest form of the same measurement. The console line printed after the merge
+// passes `false` and carries no note, because by then the merge is on the remote and the fetch below
+// brings it in; `scripts-ai/git-followup-finish.ts` is that caller, so **both branches of this flag
+// are live**. What a run *does* about the count is `pnpm josh release:scope`, asked after the merge,
+// which reads `read_pending` below rather than this line (joshuafolkken/kit#1582).
+const MERGE_PENDING_NOTE = "— this run's merge is not counted; it lands next"
+
+interface PendingReadOptions {
+	cwd?: string
+	reader?: HistoryReader
+	// Only a test passes this. Production always resolves the tip itself, so no caller can quietly
+	// point the count at a ref that is not main's.
+	tip?: string
+}
+
+// **The note belongs to the line, not to the count** (joshuafolkken/kit#1582). `read_pending`
+// returns a number and has no sentence to annotate, so `pnpm josh release:scope` — which wants the
+// number alone — would otherwise have to pass a flag about wording it never prints.
+interface PendingLineOptions extends PendingReadOptions {
+	is_merge_pending: boolean
+}
+
+// **The count is read from the fetched default branch, never from `HEAD`.** `followup` runs on the
+// feature branch, and `--first-parent` from a branch tip walks that branch rather than main — every
+// merge main took after the branch was cut is not even an ancestor, so the number would be silently
+// low and the line still say "on main". Fetching first is what makes it current, which is also what
+// lets the post-merge console line — and `pnpm josh release:scope`, asked from a lane or a feature
+// branch — count the merge that just landed (joshuafolkken/kit#1582).
+async function read_tip(options: PendingReadOptions): Promise<string> {
+	if (options.tip !== undefined) return options.tip
+
+	const default_branch = await git_command.get_default_branch()
+
+	await git_command.fetch_branch(default_branch)
+
+	return `origin/${default_branch}`
+}
+
+// **Undefined rather than a line reading zero.** A version that cannot be read, a fetch that could
+// not run, or a history whose base the search cannot resolve is not "nothing is waiting to ship" —
+// and a notification that said so would be the same class of false statement this module exists to
+// remove.
+// The manifest read is **inside** the `try` with the rest. `readFileSync` can throw after
+// `existsSync` passed — EACCES, EISDIR, a racing write — and this function is called from
+// `notify_completion`, which runs *before* `pr_merge`: an escaping rejection there would abort the
+// run and lose a merge over a cosmetic line.
+async function read_pending(options: PendingReadOptions): Promise<number | undefined> {
+	try {
+		const current_version = version_targets.read_workspace_version(options.cwd ?? process.cwd())
+
+		if (current_version === undefined) return undefined
+
+		const tip = await read_tip(options)
+		const plan = await release_history.read_release_plan(current_version, options.reader, tip)
+
+		return plan?.pending
+	} catch {
+		return undefined
+	}
+}
+
+async function pending_release_line(options: PendingLineOptions): Promise<string | undefined> {
+	const pending = await read_pending(options)
+
+	if (pending === undefined) return undefined
+
+	const line = release_plan.format_pending_line(pending)
+
+	return options.is_merge_pending ? `${line} ${MERGE_PENDING_NOTE}` : line
+}
+
+const git_followup_pending = { MERGE_PENDING_NOTE, pending_release_line, read_pending }
+
+export { git_followup_pending }

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

@@ -0,0 +1,149 @@
+import { time_format } from '#scripts/time-runtime/time-format'
+
+// Where `pnpm josh followup` spends its own wall clock (joshuafolkken/kit#1349).
+//
+// joshuafolkken/kit#1333 removed 19 seconds of dead air between reading a clean review and issuing
+// the merge, and left the next stretch of the same 134 seconds unexamined: the **44 seconds
+// `followup` spends on itself**. One invocation did nine things in order — the `closes #N`
+// check, the three GitHub reads the notification needs, the required-check wait, the CodeRabbit line
+// comments, the AI reviewers' top-level comments, the completion Telegram, the merge request, the
+// completion comment and the epic auto-close — and not one of them had ever been timed. So every
+// proposal to shorten it was a guess, and a guess made under time pressure falls on whichever stretch
+// is easiest to cut rather than on the one that is long: the notification and the auto-close, which is
+// exactly where the merge gate lives.
+//
+// **Those nine are seven printed rows now** (joshuafolkken/kit#1446): the four reads in front of the
+// wait go out together and so do the two steps after the merge, and a lap measures an interval rather
+// than a call. `STAGE` below is the list; the two names carrying `and` are the batches.
+//
+// **Laps, not a wrapper per stage.** The alternative was a `measure(name, () => …)` closure around
+// each call, which reads well and rewrites every call site in the file it instruments — nine
+// reformatted call sites in a file already at 260 of its 300 code lines. A lap records the interval
+// since the previous mark, so instrumenting a stage is one line after it and the call itself is
+// untouched. What it gives up is the stage still in flight when something throws, and
+// `INTERRUPTED_STAGE` is how that is paid for rather than lost: the caller marks one final lap on the
+// way out, so the failing stage's duration — the one a reader wants most — is still printed.
+//
+// **The printed line is the interface, and its prefix is single-sourced for the reason
+// `status-icons.ts` single-sources its icon.** `josh time` reads what a josh command printed out of
+// the transcript's tool result (`time-reported-failure.ts`), which is the only way anything can see
+// inside a single Bash span — and a reader matching a string the printer is free to reword is a reader
+// that goes quiet without failing. So the prefix is declared here and the printer builds its lines
+// from it, which is what lets a reader be added later without matching a reworded string. **No reader
+// exists yet** — `josh time` reports a `followup` span as a whole — and saying so is the point: the
+// constant is preparation, not an integration.
+//
+// **Seconds come from `time_format`** rather than from a private formatter. `verification-gate.ts`
+// already has one of its own (`48.2s`), and a third spelling of "how long did this take" in a
+// repository whose own report reads these lines is the clone `CLAUDE.md` prohibits.
+
+const STAGE_LINE_PREFIX = 'followup stage: '
+const STAGE_TOTAL_PREFIX = 'followup stages total: '
+// One wider than the longest name below, so the durations line up in one column without the reader
+// having to count. **The extra one is load-bearing**: `padEnd` adds nothing once a name reaches the
+// width, and `completion-and-epic-close` is 25 characters, so at 25 that row alone would run its
+// duration straight onto its name (joshuafolkken/kit#1446). Parsing is unaffected either way — the
+// fields are whitespace-separated.
+const STAGE_NAME_WIDTH = 26
+// Where the duration column starts, so the total lands under the stage durations rather than beside
+// the label. Derived from the two constants above instead of written out, which is what keeps the
+// block aligned when a longer stage name widens it.
+const VALUE_COLUMN = STAGE_LINE_PREFIX.length + STAGE_NAME_WIDTH
+const NO_DURATION = 0
+
+// The stages, named once. They are the units a proposal to shorten `followup` would be written
+// against, so a rename has to move the printer and whatever reads it together.
+//
+// **Two names say `and` because two stages became one** (joshuafolkken/kit#1446). Requests that need
+// nothing from one another are now issued together, and a lap records an interval rather than a
+// call — so a batch is one interval, and what it holds has to be readable from its name or the
+// shortening becomes invisible to the very measurement that found it. `closes-and-context` is the
+// former `closes-check` and `context`; `completion-and-epic-close` the former `completion-comment`
+// and `epic-close`. **`checks-wait` is untouched, and deliberately so**: it is the merge gate, and
+// this change only ever moved time that was not a wait.
+const STAGE = {
+	closes_and_context: 'closes-and-context',
+	checks_wait: 'checks-wait',
+	coderabbit_comments: 'coderabbit-comments',
+	ai_review_comments: 'ai-review-comments',
+	telegram: 'telegram',
+	merge: 'merge',
+	completion_and_epic_close: 'completion-and-epic-close',
+	// The lap that was still running when a stage threw. `followup` exits non-zero on an AI-review
+	// 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',
+} as const
+
+interface FollowupStage {
+	name: string
+	duration_ms: number
+}
+
+// Mutable on purpose: the laps are recorded as the run passes them, and a log that returned a new
+// value per lap would have every call site thread it back out.
+//
+// `last_ms` is `performance.now()`'s clock rather than `Date.now()`'s, for the reason
+// `buffered-process.ts` states: it is monotonic, so a system clock adjusted mid-wait cannot produce a
+// negative lap.
+interface StageLog {
+	stages: Array<FollowupStage>
+	last_ms: number
+}
+
+function new_log(): StageLog {
+	return { stages: [], last_ms: performance.now() }
+}
+
+function lap(log: StageLog, name: string): void {
+	const now_ms = performance.now()
+
+	log.stages.push({ name, duration_ms: now_ms - log.last_ms })
+	log.last_ms = now_ms
+}
+
+function total_ms(stages: ReadonlyArray<FollowupStage>): number {
+	return stages.reduce((sum, stage) => sum + stage.duration_ms, NO_DURATION)
+}
+
+function format_stage(stage: FollowupStage): string {
+	const name = stage.name.padEnd(STAGE_NAME_WIDTH)
+
+	return `${STAGE_LINE_PREFIX}${name}${time_format.format_seconds(stage.duration_ms)}`
+}
+
+// **An empty log prints nothing at all**, rather than a total of zero: a `0.0 s` block would read as a
+// measurement of a command that took no time. `git_pr_followup.run` cannot reach it — its `catch`
+// marks `interrupted` before the print, so its log always holds a lap — so this is the answer for any
+// other caller, and it is exercised by the unit test rather than by the command.
+//
+// **Every row is in seconds, including a `checks-wait` that ran for minutes.** `josh time` renders its
+// own tables in minutes, but its rows are whole phases of a run, while these are the stages of one
+// command and are read against each other: one unit keeps the rows comparable at a glance and the
+// block parseable by one rule.
+function format_stages(log: StageLog): Array<string> {
+	if (log.stages.length === 0) return []
+
+	const rows = log.stages.map((stage) => format_stage(stage))
+	const total = time_format.format_seconds(total_ms(log.stages))
+
+	return ['', ...rows, `${STAGE_TOTAL_PREFIX.padEnd(VALUE_COLUMN)}${total}`]
+}
+
+function print_stages(log: StageLog): void {
+	for (const line of format_stages(log)) console.info(line)
+}
+
+const git_followup_stages = {
+	STAGE,
+	STAGE_LINE_PREFIX,
+	STAGE_TOTAL_PREFIX,
+	new_log,
+	lap,
+	total_ms,
+	format_stages,
+	print_stages,
+}
+
+export type { FollowupStage, StageLog }
+export { git_followup_stages }