@joshuafolkken/kit 1.1240.0 → 1.1373.0

package/scripts/followup/git-followup-issue-close.ts

@@ -1,19 +1,19 @@
 import { epic_parse } from '#scripts/epic/epic-parse'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { session_cite } from '#scripts/issue/session-cite'
 import { poll, type PollOptions } from '#scripts/lib/poll'
 import { z } from 'zod'
 
-// **A merged pull request whose `closes #N` GitHub did not apply** (joshuafolkken/kit#2770). From
-// 2026-09-30 06:34Z every merge `followup` made left its issue open — seven in a row, where every
-// earlier one was closed by the pull request within a second — although the merge request, the
-// merging account and the `closes #N` first line were all the same as before. The run then reported
-// success, and a `backlogrun` read the still-open child as a failure and stopped.
+// **A merged pull request whose `closes #N` GitHub did not apply**. GitHub can leave the issue open
+// although the merge request, the merging account and the `closes #N` first line are all correct;
+// the run would then report success, and a `backlogrun` would read the still-open child as a failure
+// and stop.
 //
 // **The issue's state is what is checked, not `closingIssuesReferences`.** That field is GraphQL-only
-// (a cloud session is answered 403 there, joshuafolkken/kit#1022) and it is not the fact that failed:
-// PR #2768 answered it empty at the time and names #2761 now, while #2761 was never closed by it. The
-// observable defect is an issue left open, so that is what is read, and what is repaired.
+// (a cloud session is answered 403 there) and it is not the fact that fails: it can name an issue
+// the pull request never closed. The observable defect is an issue left open, so that is what is
+// read, and what is repaired.
 //
 // **A short wait first**, because GitHub applies the keyword asynchronously — the closes it did apply
 // landed within a second of the merge. Closing on the first read would take the close away from the
@@ -26,7 +26,8 @@ const state_read_schema = z.object({ state: z.string().optional() })
 
 async function is_issue_closed(issue_number: string): Promise<boolean> {
 	const raw = await git_gh_command.issue_get_state_and_relations(issue_number)
-	const parsed = raw === undefined ? undefined : parse_json_object_safe(raw, state_read_schema)
+	const parsed =
+		raw === undefined ? undefined : parse_json_object_or_undefined(raw, state_read_schema)
 
 	return epic_parse.is_state_closed(parsed?.state)
 }
@@ -36,7 +37,7 @@ const FOLLOWUP_CLOSER = 'pnpm josh followup'
 // English, like every other string a script posts: the comment says why the close came from this
 // command rather than from the pull request, so a reader of the issue is not left guessing. `closer`
 // names the command that closed it — `followup` at the merge, or `run:merge` when a `backlogrun`
-// finds the child still open afterwards (joshuafolkken/kit#2769).
+// finds the child still open afterwards.
 function build_close_comment(pr_url: string | undefined, closer: string = FOLLOWUP_CLOSER): string {
 	return (
 		`Closed by \`${closer}\`: ${pr_url ?? 'the merged pull request'} merged, ` +
@@ -58,11 +59,13 @@ async function ensure_issue_closed(
 		(await poll.poll_until(async () => await is_issue_closed(issue_number), wait))
 	if (is_done) return
 
-	console.warn(`⚠️  Issue #${issue_number} is still open after the merge — closing it.`)
+	console.warn(
+		`⚠️  Issue ${session_cite.issue(issue_number)} is still open after the merge — closing it.`,
+	)
 	const comment = build_close_comment(input.pr_url, input.closer)
 
 	if (!(await git_gh_command.issue_close(issue_number, comment))) {
-		throw new Error(`gh api could not close issue #${issue_number}`)
+		throw new Error(`gh api could not close issue ${session_cite.issue(issue_number)}`)
 	}
 }
 

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

@@ -1,11 +1,12 @@
 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 { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { IN_PROGRESS_LABEL, label_name_of } from '#scripts/issue/issue-labels'
+import { session_cite } from '#scripts/issue/session-cite'
 import { z } from 'zod'
 
 // **`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
+// anything**. `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.
@@ -26,18 +27,20 @@ const labels_read_schema = z.object({ labels: z.array(issue_label_schema).option
 
 // **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
+// with and treats `In-Progress` as the same label, so a repository may spell it that way. 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}`)
+	return new Error(
+		`gh api answered no readable labels for issue ${session_cite.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)
+	const parsed = parse_json_object_or_undefined(raw, labels_read_schema)
 	if (parsed === undefined) throw unreadable_error(issue_number)
 
 	return (parsed.labels ?? []).map((label) => label.name)

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

@@ -3,7 +3,7 @@ import type { PullMergeState } from '#scripts/gh/git-gh-pr-read'
 import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
-// joshuafolkken/kit#3023: `prrun` stops at a green, mergeable pull request and a person merges it by
+// `prrun` stops at a green, mergeable pull request and a person merges it by
 // hand. Re-running `pnpm josh followup` then has to finish what a merged `fullrun` finishes — the
 // completion report, the epic close, the merged issue's close, the `in-progress` removal, the hold
 // release and the completion Telegram — **from the one tail `followup` already runs**, not a copy of

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

@@ -3,13 +3,11 @@ import { release_history, type HistoryReader } from '#scripts/release/release-hi
 import { release_plan } from '#scripts/release/release-plan'
 import { version_targets } from '#scripts/version/version-targets'
 
-// What the completion notification says about versions, now that children do not set one
-// (joshuafolkken/kit#1486).
+// What the completion notification says about versions, now that children do not set one.
 //
-// **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.
+// **It does not print the `package.json` version.** Children do not bump — the version is decided
+// from main's history by `pnpm josh release` — so that read 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
@@ -23,7 +21,7 @@ import { version_targets } from '#scripts/version/version-targets'
 // passes `false` and carries no note, because by then the merge is on the remote and the fetch below
 // brings it in; `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).
+// which reads `read_pending` below rather than this line.
 const MERGE_PENDING_NOTE = "— this run's merge is not counted; it lands next"
 
 interface PendingReadOptions {
@@ -34,7 +32,7 @@ interface PendingReadOptions {
 	tip?: string
 }
 
-// **The note belongs to the line, not to the count** (joshuafolkken/kit#1582). `read_pending`
+// **The note belongs to the line, not to the count**. `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 {
@@ -46,7 +44,7 @@ interface PendingLineOptions extends PendingReadOptions {
 // 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).
+// branch — count the merge that just landed.
 async function read_tip(options: PendingReadOptions): Promise<string> {
 	if (options.tip !== undefined) return options.tip
 

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

@@ -1,21 +1,17 @@
 import { PrConflictError } from '#scripts/gh/git-pr-checks-eval'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
 import { time_format } from '#scripts/time-runtime/time-format'
 
-// Where `pnpm josh followup` spends its own wall clock (joshuafolkken/kit#1349).
+// Where `pnpm josh followup` spends its own wall clock.
 //
-// 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.
+// One invocation does 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. Untimed, every proposal to shorten it is 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.
 //
-// **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.
+// **Those nine are seven printed rows**: 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
@@ -43,7 +39,7 @@ 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
+// duration straight onto its name. 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
@@ -55,7 +51,7 @@ 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
+// **Two names say `and` because two stages became one**. 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
@@ -74,8 +70,8 @@ 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`.
+	// The interrupted lap when the wait failed on a merge conflict, so the
+	// stage block names the cause a resumed session would otherwise look up with `gh pr view`.
 	conflict: 'conflict',
 } as const
 
@@ -142,6 +138,20 @@ function print_stages(log: StageLog): void {
 	for (const line of format_stages(log)) console.info(line)
 }
 
+// The wait for CI goes to the lane ledger as well, where `josh lane:stats` reads it beside the review
+// round it would overlap: the printed block reaches only this run's reader. A wait that threw is the
+// `interrupted` lap and records nothing here.
+async function record_ci_wait(log: StageLog): Promise<void> {
+	const wait = log.stages.find((stage) => stage.name === STAGE.checks_wait)
+
+	if (wait === undefined) return
+
+	await lane_ledger.record_stage({
+		stage: lane_ledger.CI_WAIT_STAGE,
+		elapsed_ms: wait.duration_ms,
+	})
+}
+
 const git_followup_stages = {
 	STAGE,
 	STAGE_LINE_PREFIX,
@@ -151,6 +161,7 @@ const git_followup_stages = {
 	total_ms,
 	format_stages,
 	print_stages,
+	record_ci_wait,
 	stopped_lap,
 }
 

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

@@ -2,6 +2,7 @@
 import { parseArgs } from 'node:util'
 import { git_branch } from '#scripts/git/git-branch'
 import { git_error } from '#scripts/git/git-error'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_body } from '#scripts/josh/cli-body'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
@@ -41,7 +42,7 @@ interface CliArguments {
 // The text is a constant rather than an inline literal: it is one option per supported flag, so it
 // grows with the command and would otherwise push `display_help` past the function line limit every
 // time a flag is added — a limit that exists to catch functions doing several things, which this one
-// never was (joshuafolkken/kit#1578).
+// never was.
 const HELP_TEXT = `
 🚦 PR Followup Workflow
 
@@ -99,8 +100,8 @@ async function resolve_branch_name(raw_branch: string | undefined): Promise<stri
 // The message is resolved here rather than inside `git_notify`, so the file form reaches the config
 // as text and the config keeps one `message` field. `--notify-message-file` exists because the inline
 // form is a double-quoted shell argument: a backtick or a `$` in the body is evaluated before this
-// process starts, and joshuafolkken/kit#1198 recorded both halves of that — a Telegram body that
-// silently lost a word, and a comment body whose text ran as git commands.
+// process starts — a Telegram body can silently lose a word, and a comment body's text can run as
+// git commands.
 function build_notify_config(values: CliArguments['values']): GitNotifyConfig | undefined {
 	return git_notify.build_notify_config({
 		raw_target: values['notify-target'] ?? 'issue',
@@ -118,13 +119,13 @@ function is_merge_resolved(values: CliArguments['values']): boolean {
 	return values['no-merge'] !== true
 }
 
-// joshuafolkken/kit#1522: `/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 reads the silence as a clean round. **This is the seam where that stops
-// being free**: a merge is refused unless the review attested the checkout it was briefed on.
+// `/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 produced *no* signal, so a check that only
+// **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
@@ -141,10 +142,8 @@ function is_merge_permitted(status: string): boolean {
 	return status === 'ok' || status === 'not-required'
 }
 
-const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
-
 function is_valid_issue(issue_number: string | undefined): boolean {
-	return issue_number !== undefined && ISSUE_NUMBER_PATTERN.test(issue_number)
+	return issue_number !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
 }
 
 async function assert_review_attested(should_merge: boolean): Promise<void> {
@@ -157,13 +156,12 @@ async function assert_review_attested(should_merge: boolean): Promise<void> {
 	throw new Error(review_attest.refusal_message(verdict))
 }
 
-// joshuafolkken/kit#2343: recording a review round was prose, and prose failed — eleven merges after
-// the instruction landed, `review:record` had never run once, so the recurrence ledger stayed blind.
-// **This is the seam where that stops being a request and becomes a gate**: a merge is refused unless
-// the round left a `- rf:` line for its issue, a zero-finding `none` line included.
+// 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.
 //
 // **Absence is a refusal, `missing` exactly as `assert_review_attested`'s is** — the defect this
-// exists for produced *no* line, so silence must not read as success. A checkout that keeps no ledger
+// 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(
@@ -180,7 +178,7 @@ async function assert_review_recorded(
 	throw new Error(review_record.refusal_message(issue))
 }
 
-// joshuafolkken/kit#2446: a runtime change merges only with its acceptance criteria run for real and
+// A runtime change merges only with its acceptance criteria run for real and
 // recorded in the pull request body — `live_evidence` carries the why. `exempt` (no runtime path
 // changed) merges as before, and a `--no-merge` run has not reached the gate at all.
 async function assert_live_evidence(should_merge: boolean, branch_name: string): Promise<void> {
@@ -205,8 +203,8 @@ async function assert_merge_gates(
 }
 
 // After the gates, before the CI wait: a line appended since the run's commit rides the pull request
-// itself, so it merges with it — a lane's included (joshuafolkken/kit#2919). **A pull request that has
-// already merged skips both** (joshuafolkken/kit#3023): the gates guard a merge this run no longer
+// itself, so it merges with it — a lane's included. **A pull request that has
+// already merged skips both**: the gates guard a merge this run no longer
 // makes, and a ledger commit would land on a branch that has already gone in.
 async function prepare_merge(
 	plan: MergePlan,
@@ -235,7 +233,7 @@ async function main(): Promise<void> {
 
 	await prepare_merge(plan, issue_number, branch_name)
 	// **The number the run reports on is the one it used**, which is the number the pull request
-	// closes where the invocation named none (joshuafolkken/kit#1539). Recovered inside `run`, so the
+	// closes where the invocation named none. Recovered inside `run`, so the
 	// tail records a run the command line could not identify rather than silently skipping it.
 	const used_issue_number = await git_pr_followup.run({
 		branch_name,

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

@@ -10,23 +10,19 @@ import { CHECK_STATUS_PASS, type PrStateSnapshot } from '#scripts/gh/git-pr-chec
 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
+// reached its line limit. `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).
+// Named so a test can pin the note without restating it.
 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.
+// included — and letting that escape would end the run before `evaluate_pr_state` could apply the
+// CodeRabbit exemption at all, wherever every check finishes inside the two-minute window.
 //
 // 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.
+// genuinely failing non-CodeRabbit check still ends the wait on the first poll by the 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
@@ -53,8 +49,7 @@ function reads_as_empty_rollup(raw_json: string): boolean {
 // 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).
+// and reading the review listing to answer it paged a whole conversation for nothing.
 async function has_no_checks(branch_name: string): Promise<boolean> {
 	try {
 		const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
@@ -70,12 +65,11 @@ async function has_no_checks(branch_name: string): Promise<boolean> {
 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.
+	// Swallowed, but never silently: the line stays visible even though it decides nothing.
 	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
+// **Returns whether the watch confirmed completion**: `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
@@ -96,7 +90,7 @@ async function watch_before_polling(branch_name: string): Promise<boolean> {
 	}
 }
 
-// **A confirmed watch lowers the poll's stable-read requirement to one** (joshuafolkken/kit#2029). The
+// **A confirmed watch lowers the poll's stable-read requirement to one**. 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
@@ -111,7 +105,7 @@ async function run_checks(input: {
 	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
+// Temporary: 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
@@ -124,9 +118,8 @@ function read_coderabbit_skip_notes(snapshot: PrStateSnapshot): Array<string> {
 }
 
 // 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).
+// ends up in. A merge that went ahead while CodeRabbit had not come back is the one thing the
+// CodeRabbit exemption trades away, so it must be visible in `followup`'s own output.
 function log_skip_notes(notes: ReadonlyArray<string>): void {
 	for (const note of notes) {
 		console.info(`⏭ ${note}`)

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

@@ -26,17 +26,17 @@ interface WrapupInput {
 	branch_name: string
 	issue_number: string | undefined
 	// The number the pull request body's `closes #N` names — the only issue the merge claimed to
-	// close, so the only one the merged-issue close may write to (joshuafolkken/kit#2770).
+	// close, so the only one the merged-issue close may write to.
 	closes_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`
+	// completion notification. Empty on a run that changed nothing `josh sync`
 	// distributes, and an empty one adds no line.
 	managed_notes: ReadonlyArray<string>
 	// A pull request merged before this run is not merged again, and a tail whose completion report is
-	// already on the issue does not post it twice (joshuafolkken/kit#3023, `git-followup-merged.ts`).
+	// already on the issue does not post it twice (`git-followup-merged.ts`).
 	is_merged?: boolean | undefined
 	is_completion_recorded?: boolean | undefined
 }
@@ -112,7 +112,7 @@ async function post_completion_notification(input: {
 	}
 }
 
-// **Guarded only once the merge has landed** (joshuafolkken/kit#1539) — the rule and its reason are
+// **Guarded only once the merge has landed** — 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.
@@ -150,7 +150,7 @@ async function epic_close_step(input: WrapupInput): Promise<void> {
 	})
 }
 
-// **The run's own mark, taken off at the end of the run that wrote it** (joshuafolkken/kit#1794).
+// **The run's own mark, taken off at the end of the run that wrote it**.
 // `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.
@@ -173,7 +173,7 @@ async function in_progress_step(input: WrapupInput): Promise<void> {
 	})
 }
 
-// **The merged issue's close, confirmed rather than assumed** (joshuafolkken/kit#2770): GitHub stopped
+// **The merged issue's close, confirmed rather than assumed**: GitHub stopped
 // applying `closes #N` on some merges, and nothing noticed. The epic auto-close does not wait on it —
 // it already excludes the merged issue from its reads — so it runs beside the other steps. It acts on
 // the body's `closes #N` rather than the run's issue number: a pull request that closes nothing, or
@@ -193,7 +193,7 @@ async function issue_close_step(input: WrapupInput): Promise<void> {
 	})
 }
 
-// **The steps after the merge are issued together** (joshuafolkken/kit#1446). The completion
+// **The steps after the merge are issued together**. The completion
 // comment writes to the issue or the pull request, the auto-close reads the open epics, the label
 // removal reads and writes the issue's labels, and the merged-issue close reads and may close the
 // issue; none needs another's answer, and measured

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

@@ -45,7 +45,7 @@ function build_telegram_input(input: {
 
 // 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).
+// a github.com URL looks like.
 function build_issue_url(
 	pr_url: string | undefined,
 	issue_number: string | undefined,
@@ -65,7 +65,7 @@ interface FollowupInput {
 	ai_review_ignore_reason: string | undefined
 	is_skip_watch: boolean
 	should_merge: boolean
-	// The pull request merged before this run (joshuafolkken/kit#3023): only the tail is left to run.
+	// The pull request merged before this run: only the tail is left to run.
 	is_merged?: boolean | undefined
 	// When it merged — a completion report posted before it is the `prrun` stop's, not this tail's.
 	merged_at?: string | undefined
@@ -77,9 +77,9 @@ 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
+// **Returns the number it warned about the absence of**. Taking the issue number from the command
+// line alone would make an invocation that omitted it throw 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> {
@@ -99,7 +99,7 @@ async function warn_if_missing_closes(branch_name: string): Promise<string | und
 }
 
 // **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
+// line it is the pull request body that names it, 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.
@@ -119,7 +119,7 @@ interface RunContext {
 	context: TelegramContext
 }
 
-// **The four reads in front of the check wait are issued together** (joshuafolkken/kit#1446). Not one
+// **The four reads in front of the check wait are issued together**. 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
@@ -158,7 +158,7 @@ async function read_run_context(input: {
 	}
 }
 
-// The pending count replaces the project version line (joshuafolkken/kit#1486): children no longer
+// The pending count replaces the project version line: 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(
@@ -170,7 +170,7 @@ async function notify_completion(
 	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
+	// **The tolerant send**: 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.
 	//
@@ -212,10 +212,10 @@ async function run_comment_scans(
 	return [...comment_notes, ...ai_review_notes]
 }
 
-// **The managed config-file read runs first, ahead of the check wait** (joshuafolkken/kit#1578). It
+// **The managed config-file read runs first, ahead of the check wait**. 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.
+// That answer stops nothing — it is a report — but 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
@@ -223,7 +223,7 @@ async function run_comment_scans(
 //
 // **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
+// reaches the completion report posted to the Issue. 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,
@@ -249,7 +249,7 @@ async function run_review_checks(
 	return { notes: [...managed, ...check_notes, ...scan_notes], managed }
 }
 
-// **A tail re-run after a merge does not report twice** (joshuafolkken/kit#3023): where the issue
+// **A tail re-run after a merge does not report twice**: where the issue
 // already carries this pull request's completion report, the Telegram is skipped here and the comment
 // in the wrapup. Answers whether it was recorded, so the wrapup skips on the same read.
 async function notify_unless_recorded(
@@ -269,7 +269,7 @@ async function notify_unless_recorded(
 	return is_recorded
 }
 
-// **Answers with the issue number the run actually used** (joshuafolkken/kit#1539), which is the one
+// **Answers with the issue number the run actually used**, 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
@@ -300,8 +300,8 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 	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 stage block is printed on the way out of every run, failed ones included**.
+// 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.
@@ -316,6 +316,7 @@ async function run(input: FollowupInput): Promise<string | undefined> {
 		throw error
 	} finally {
 		git_followup_stages.print_stages(log)
+		await git_followup_stages.record_ci_wait(log)
 	}
 }