@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/document/issue-citation-budget.ts

@@ -0,0 +1,94 @@
+// The issue-number citation ceiling of every agent-read document — an exact ratchet.
+//
+// Issue-number citations and the "why / measured / rejected" prose around them are what swell the
+// documents an agent reads at run time; a reduction epic cuts them only for the next PRs to add them
+// back, because nothing held the reduced count. This list is that hold:
+// `issue-citation-budget.test.ts` fails `pnpm josh gate` when an agent-read document cites more issue
+// numbers than its entry records, and when it cites fewer — a reduction must lower its entry in the
+// same PR, so the ceiling follows the count down and never sits loose above it. A document absent from
+// the list has a ceiling of zero. History belongs in `docs/maintainers/<topic>-rationale.md`, which
+// this budget does not hold (`docs/maintainers/residency-rationale.md` → "The issue-citation ratchet").
+//
+// The ratchet is exact rather than block-quantized like `document-byte-budget.ts`: a single added
+// citation is the growth this exists to refuse, so there is no headroom to quantize.
+
+interface CitationBudget {
+	path: string
+	citations: number
+}
+
+// An issue number as a document cites it — `#1234` or `joshuafolkken/kit#1234`. Three digits or more,
+// so a placeholder (`#N`, `#<N>`) and a list ordinal are not counted.
+const CITATION_PATTERN = /#\d{3,}\b/gu
+
+const ISSUE_CITATION_BUDGET: ReadonlyArray<CitationBudget> = [
+	{ path: 'docs/josh-commands-backlog.md', citations: 13 },
+	{ path: 'docs/josh-commands-run.md', citations: 4 },
+	{ path: 'docs/josh-commands.md', citations: 2 },
+	{ path: 'prompts/collaboration-workflow/file-edits.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/glossary.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/issue-citation.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/issue-template.md', citations: 5 },
+	{ path: 'prompts/collaboration-workflow/operating-rules.md', citations: 3 },
+	{ path: 'prompts/collaboration-workflow/output-bounds.md', citations: 3 },
+	{ path: 'prompts/collaboration-workflow/overview.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/plan-comment.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/principles.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/report-format.md', citations: 7 },
+	{ path: 'prompts/collaboration-workflow/residency.md', citations: 3 },
+	{ path: 'prompts/collaboration-workflow/rule-delivery.md', citations: 5 },
+	{ path: 'prompts/collaboration-workflow/shell-body.md', citations: 2 },
+	{ path: 'prompts/collaboration-workflow/turn-batching.md', citations: 2 },
+	{ path: 'prompts/collaboration-workflow/upstream-interrupt.md', citations: 1 },
+	{ path: 'prompts/collaboration-workflow/wip-cap.md', citations: 2 },
+	{ path: 'prompts/refactoring.md', citations: 1 },
+	{ path: 'prompts/review-rubric.md', citations: 1 },
+	{ path: 'prompts/sonar-hotspot-handling.md', citations: 2 },
+	{ path: 'prompts/testing-guide.md', citations: 3 },
+]
+
+const BUDGET_FILE = 'scripts/document/issue-citation-budget.ts'
+
+function count_citations(text: string): number {
+	return text.match(CITATION_PATTERN)?.length ?? 0
+}
+
+// The recorded ceiling for one path — zero when the list carries no entry for it.
+function recorded_citations_for(relative_path: string): number {
+	return ISSUE_CITATION_BUDGET.find((entry) => entry.path === relative_path)?.citations ?? 0
+}
+
+function over_budget_message(relative_path: string, current: number, recorded: number): string {
+	const hint = `move the history to docs/maintainers/<topic>-rationale.md, or record ${current.toString()} in ${BUDGET_FILE} so the reason shows in the PR diff`
+
+	return `${relative_path} cites ${current.toString()} issue numbers, over its ceiling of ${recorded.toString()}. Cut the citations — ${hint}.`
+}
+
+function stale_budget_message(relative_path: string, current: number, recorded: number): string {
+	const hint = `lower its entry to ${current.toString()} in ${BUDGET_FILE} (remove the entry at 0) so the ratchet holds the reduction`
+
+	return `${relative_path} cites ${current.toString()} issue numbers but records ${recorded.toString()}. ${hint}.`
+}
+
+// The failure for one document, or undefined when its count equals its record. Growth and a
+// reduction left unrecorded both fail, which is what makes the ceiling a ratchet rather than a cap.
+function citation_violation(
+	relative_path: string,
+	current: number,
+	recorded: number,
+): string | undefined {
+	if (current > recorded) return over_budget_message(relative_path, current, recorded)
+	if (current < recorded) return stale_budget_message(relative_path, current, recorded)
+
+	return undefined
+}
+
+const issue_citation_budget = {
+	ISSUE_CITATION_BUDGET,
+	citation_violation,
+	count_citations,
+	recorded_citations_for,
+}
+
+export type { CitationBudget }
+export { issue_citation_budget }

package/scripts/epic/epic-cli-argv.ts

@@ -33,9 +33,9 @@ interface FormFlags {
 	value_flags?: ReadonlyArray<string>
 }
 
-type OptionEntry = [string, ParseArgsOptionsConfig[string]]
-
 function options_of(form: FormFlags): ParseArgsOptionsConfig {
+	type OptionEntry = [string, ParseArgsOptionsConfig[string]]
+
 	const entries: Array<OptionEntry> = [
 		...form.switches.map((flag): OptionEntry => [cli_flags.option_name(flag), SWITCH_OPTION]),
 		...(form.value_flags ?? []).map((flag): OptionEntry => [

package/scripts/epic/epic-fetch.ts

@@ -1,6 +1,6 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { IssueReadFailure } from '#scripts/gh/git-gh-issue-read'
-import { issue_sample_gate } from '#scripts/issue/issue-sample-gate'
+import { issue_sample_prime } from '#scripts/issue/issue-sample-prime'
 import { epic_cross_repo } from './epic-cross-repo'
 import type { EpicChild, IssueReference } from './epic-graph'
 import { epic_issue, type EpicIssue } from './epic-issue'
@@ -23,6 +23,8 @@ function to_child(parsed: EpicIssue, repo: string): EpicChild {
 		labels: epic_issue.label_names(parsed),
 		blocked_by: epic_issue.blocker_references_of(parsed, repo),
 		body: parsed.body,
+		author_association: parsed.author_association,
+		user: parsed.user,
 	}
 }
 
@@ -134,7 +136,7 @@ async function fetch_child_read(
 
 	const parsed = epic_issue.parse_epic_issue(read.json)
 
-	await issue_sample_gate.prime([parsed?.body])
+	await issue_sample_prime.prime([parsed?.body])
 
 	return { child: parsed === undefined ? undefined : to_child(parsed, repo), is_unreachable: false }
 }

package/scripts/epic/epic-graph.ts

@@ -1,3 +1,4 @@
+import type { AuthorFields } from '#scripts/gh/gh-author-association'
 import type { DependencyLink } from './epic-parse'
 import {
 	format_dependency_link,
@@ -23,13 +24,17 @@ import {
 // exist, `blocker_categories` dropped it, and the child ran as though nothing blocked it. It also
 // made `epic_cross_repo.resolve_cross_repo`'s cross-repository branch unreachable: every blocker
 // arrived carrying the blocked child's repository, so `blocker.repo === blocked.repo` always held.
-interface EpicChild {
+//
+// The author fields (`AuthorFields`) are read only by `backlog:next`, which offers a child only when
+// its author has write access (joshuafolkken/kit#4633); absent on rows built without a read.
+interface EpicChild extends AuthorFields {
 	number: number
 	repo: string
 	state: 'OPEN' | 'CLOSED'
 	labels: ReadonlyArray<string>
 	blocked_by: ReadonlyArray<IssueReference>
-	// Read only to hold a child until its declared start time; absent on rows built without a read.
+	// Read to hold a child until its declared start time and to rank it by its causing-lane minutes;
+	// absent on rows built without a read.
 	body?: string | undefined
 }
 

package/scripts/epic/epic-issue.ts

@@ -1,5 +1,5 @@
 import { git_gh_issue_rest } from '#scripts/gh/git-gh-issue-rest'
-import { blocked_by_schema } from '#scripts/git/git-schemas'
+import { author_fields_schema, blocked_by_schema } from '#scripts/git/git-schemas'
 import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 import { REPOSITORY_SEGMENT_SOURCE } from './epic-parse'
@@ -36,6 +36,8 @@ const epic_issue_schema = z.object({
 	url: z.string().default(''),
 	labels: z.array(label_schema).default([]),
 	blockedBy: blocked_by_schema,
+	// Who filed the issue, for `backlog:next`'s author-trust check (joshuafolkken/kit#4633).
+	...author_fields_schema,
 })
 
 type EpicIssue = z.infer<typeof epic_issue_schema>

package/scripts/epic/epic-rank.ts

@@ -1,3 +1,5 @@
+import { expected_effect_lint } from '#scripts/issue/expected-effect-lint'
+import { issue_priority } from '#scripts/issue/issue-priority'
 import { issue_rank } from '#scripts/issue/issue-rank'
 import { epic_graph, type EpicChild } from './epic-graph'
 
@@ -27,7 +29,10 @@ function rank(
 	const dependents = dependents_of(pool)
 
 	return issue_rank.rank(children, (child) => ({
+		is_last: issue_priority.is_last(child.body),
 		labels: child.labels,
+		lost_minutes: issue_priority.lost_minutes(child.body),
+		gain_minutes: expected_effect_lint.weekly_minutes(child.body),
 		dependents: dependents.get(epic_graph.key_of(child)) ?? 0,
 	}))
 }

package/scripts/exports/unused-members-check.ts

@@ -0,0 +1,62 @@
+import path from 'node:path'
+import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
+import type { NamespaceMember } from '#tools/exports/namespace-members'
+
+const CHECK = 'exports'
+const FAIL_EXIT_CODE = 1
+// A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
+// `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
+//
+// **Not a skip notice**. `SKIP_MARKER` means "a check passed without running",
+// and the gate withholds its green record on it — so a consumer, where this notice prints on every
+// run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
+const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — ${NOTHING_TO_CHECK_MARKER} in a consumer project.`
+
+function format_member(root: string, member: NamespaceMember): string {
+	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
+}
+
+function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
+	if (members.length === 0) return `josh ${CHECK}: no unused namespace member`
+
+	return [
+		`josh ${CHECK}: ${String(members.length)} namespace member(s) nothing reads — remove each from its namespace object (and the declaration, if nothing in its file uses it either):`,
+		...members.map((member) => `  ${format_member(root, member)}`),
+	].join('\n')
+}
+
+// Loaded only past the consumer skip: the scanner pulls in `typescript`, an optional peer a
+// basic-profile consumer may not have, and this check runs in every consumer's gate. For the same
+// reason the scanner is left out of the published package (`package.json` `files`); only this check
+// ships. `files` narrows the scan to the namespaces they declare or import directly; undefined scans
+// the whole program.
+async function find_members(
+	root: string,
+	files: ReadonlyArray<string> | undefined,
+): Promise<ReadonlyArray<NamespaceMember>> {
+	const { unused_members } = await import('#tools/exports/unused-members')
+	if (files === undefined) return unused_members.find_unused_members(root)
+
+	return await unused_members.find_unused_members_in(root, files)
+}
+
+async function run_unused_members(root: string, files?: ReadonlyArray<string>): Promise<number> {
+	if (doctor_consumer.is_kit_consumer(root)) {
+		console.info(CONSUMER_NOTICE)
+
+		return 0
+	}
+
+	const members = await find_members(root, files)
+	const output = report(root, members)
+
+	if (members.length === 0) console.info(output)
+	else console.error(output)
+
+	return members.length === 0 ? 0 : FAIL_EXIT_CODE
+}
+
+const unused_members_check = { run_unused_members, CONSUMER_NOTICE }
+
+export { unused_members_check }

package/scripts/exports/unused-members-cli.ts

@@ -1,58 +1,13 @@
 #!/usr/bin/env tsx
-import path from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
 import { project_checks } from '#scripts/gate/project-checks'
-import { NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
-import type { NamespaceMember } from '#tools/exports/namespace-members'
+import { unused_members_check } from './unused-members-check'
 
-const CHECK = 'exports'
-const FAIL_EXIT_CODE = 1
-// A consumer's namespaces are read from `.svelte` files and routes a TypeScript program over its
-// `tsconfig.json` does not see, so every member they use would read as unused. The check is kit's own.
-//
-// **Not a skip notice**. `SKIP_MARKER` means "a check passed without running",
-// and the gate withholds its green record on it — so a consumer, where this notice prints on every
-// run, never got a green record. Out of scope by design is not unverified, so the marker stays out.
-const CONSUMER_NOTICE = `josh ${CHECK}: checks only the kit repository itself — ${NOTHING_TO_CHECK_MARKER} in a consumer project.`
-
-function format_member(root: string, member: NamespaceMember): string {
-	return `${path.relative(root, member.file)}:${String(member.line)}  ${member.namespace}.${member.member}`
-}
-
-function report(root: string, members: ReadonlyArray<NamespaceMember>): string {
-	if (members.length === 0) return `josh ${CHECK}: no unused namespace member`
-
-	return [
-		`josh ${CHECK}: ${String(members.length)} namespace member(s) nothing reads — remove each from its namespace object (and the declaration, if nothing in its file uses it either):`,
-		...members.map((member) => `  ${format_member(root, member)}`),
-	].join('\n')
-}
-
-async function run_unused_members(root: string): Promise<number> {
-	if (doctor_consumer.is_kit_consumer(root)) {
-		console.info(CONSUMER_NOTICE)
-
-		return 0
-	}
-
-	// Loaded only past the skip: the scanner pulls in `typescript`, an optional peer a basic-profile
-	// consumer may not have, and this check runs in every consumer's gate. For the same reason the
-	// scanner is left out of the published package (`package.json` `files`); only this entry ships.
-	const { unused_members } = await import('#tools/exports/unused-members')
-	const members = unused_members.find_unused_members(root)
-	const output = report(root, members)
-
-	if (members.length === 0) console.info(output)
-	else console.error(output)
-
-	return members.length === 0 ? 0 : FAIL_EXIT_CODE
-}
+// The `josh exports:unused` entry point: the whole-program scan the gate runs. `josh lint:related`
+// imports the check itself, narrowed to the changed files.
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run_unused_members(project_checks.project_root(process.cwd()))
+	process.exitCode = await unused_members_check.run_unused_members(
+		project_checks.project_root(process.cwd()),
+	)
 }
-
-const unused_members_cli = { run_unused_members, CONSUMER_NOTICE }
-
-export { unused_members_cli }

package/scripts/followup/followup-ci-path.ts

@@ -0,0 +1,67 @@
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import { is_coderabbit_check } from '#scripts/gh/git-pr-checks-eval'
+import { CHECK_STATUS_PENDING, type PrStateSnapshot } from '#scripts/gh/git-pr-checks-parse'
+
+// Which check `followup`'s CI wait waited on last (joshuafolkken/kit#5295). The `ci-wait` row alone
+// says how long the wait was, not which job held it, so the next job to shorten could not be chosen.
+//
+// **A check is timed when it is seen pending and then settled**: its time is the interval from the
+// wait's first poll to the first poll that saw it settled. A check already settled at the first poll
+// held nothing up and is not recorded. CodeRabbit is left out — its wait is `coderabbit-wait`'s
+// (`followup-coderabbit-wait.ts`), so it is never counted twice. The clock is `performance.now()`'s
+// for the reason `git-followup-stages.ts` states.
+
+// Mutable for the reason `StageLog` is: the observer adds to it as the wait polls.
+interface CiPath {
+	start_ms?: number
+	pending: Set<string>
+	check_ms: Record<string, number>
+}
+
+// The `ci-wait` row's critical-path fields, both absent where no check was seen to settle.
+interface CiPathRecord {
+	last_check?: string
+	check_ms?: Record<string, number>
+}
+
+function new_path(): CiPath {
+	return { pending: new Set(), check_ms: {} }
+}
+
+function settle(path: CiPath, name: string, elapsed_ms: number): void {
+	if (path.pending.delete(name)) path.check_ms[name] = elapsed_ms
+}
+
+function observe(path: CiPath, snapshot: PrStateSnapshot, now_ms: number): void {
+	path.start_ms ??= now_ms
+	const elapsed_ms = now_ms - path.start_ms
+	const checks = snapshot.rollup.filter((check) => !is_coderabbit_check(check.name))
+
+	for (const check of checks) {
+		if (check.status === CHECK_STATUS_PENDING) path.pending.add(check.name)
+		else settle(path, check.name, elapsed_ms)
+	}
+}
+
+// **Only the first check wait is timed**: the `ci-wait` row is that wait's lap, and the wait the merge
+// goes back to when the head moved (#4036) times checks the row does not cover.
+function observer_of(path: CiPath): SnapshotObserver {
+	const is_first_wait = path.start_ms === undefined
+
+	return async function time_checks(snapshot: PrStateSnapshot): Promise<void> {
+		if (is_first_wait) observe(path, snapshot, performance.now())
+	}
+}
+
+function record_of(path: CiPath): CiPathRecord {
+	const [last] = Object.entries(path.check_ms).toSorted((left, right) => right[1] - left[1])
+
+	if (last === undefined) return {}
+
+	return { last_check: last[0], check_ms: { ...path.check_ms } }
+}
+
+const followup_ci_path = { new_path, observe, observer_of, record_of }
+
+export type { CiPath, CiPathRecord }
+export { followup_ci_path }

package/scripts/followup/followup-coderabbit-retrigger.ts

@@ -0,0 +1,261 @@
+// cspell:words coderabbit coderabbitai
+import { is_coderabbit_author, is_coderabbit_rate_limit } from '#scripts/gh/git-ai-review-scan'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import { parse_pr_state_snapshot } from '#scripts/gh/git-pr-checks-parse'
+import { ai_review_pull_comment_schema } from '#scripts/git/git-schemas'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { poll } from '#scripts/lib/poll'
+import type { CodeRabbitState } from '#scripts/run/event/run-event-checks'
+import { followup_checks_event } from './followup-checks-event'
+import { followup_coderabbit_wait, type CodeRabbitWait } from './followup-coderabbit-wait'
+
+// A rate-limited CodeRabbit, retriggered once by `followup` itself (joshuafolkken/kit#5289): read the
+// window off CodeRabbit's own notice, wait it out, post `@coderabbitai review`, and wait for the check
+// again. **Once per pull request** — a retrigger comment older than the latest notice means the one
+// attempt was spent, and a second rate limit is the person's call (bypassing it is Tier C); one newer
+// than it, whoever posted it, is a review still to come and is waited for, not posted again. The pull
+// request, not the ledger, answers "already retriggered", so a re-run `followup` reads the same answer.
+
+const RETRIGGER_BODY = '@coderabbitai review'
+// `Please wait **12 minutes and 34 seconds** before requesting another review.` — the clause between
+// `wait` and `before`, read as `<number> <unit>` token pairs.
+const WAIT_OPENER = /please wait/iu
+const WAIT_CLOSER = /before/iu
+const TOKEN = /\d+|[a-z]+/giu
+const DIGITS = /^\d+$/u
+const SECOND_MS = 1000
+const SECONDS_PER_MINUTE = 60
+const MINUTES_PER_HOUR = 60
+const MINUTE_MS = SECONDS_PER_MINUTE * SECOND_MS
+const UNIT_MS: Readonly<Record<string, number>> = {
+	h: MINUTES_PER_HOUR * MINUTE_MS,
+	m: MINUTE_MS,
+	s: SECOND_MS,
+}
+// Past the window's end, so the retrigger does not land on its last second.
+const MARGIN_SECONDS = 15
+const MARGIN_MS = MARGIN_SECONDS * SECOND_MS
+// The longest window `followup` waits out; a longer one is left to the person (`followup.md`).
+const WINDOW_CAP_MINUTES = 30
+const WINDOW_CAP_MS = WINDOW_CAP_MINUTES * MINUTE_MS
+// The wait for the retriggered review: twenty minutes, polled every thirty seconds.
+const REVIEW_WAIT_ATTEMPTS = 40
+const REVIEW_WAIT_INTERVAL_SECONDS = 30
+const REVIEW_WAIT_INTERVAL_MS = REVIEW_WAIT_INTERVAL_SECONDS * SECOND_MS
+const NO_TIME = 0
+const FIRST = 0
+const NEXT = 1
+const RATE_LIMITED: CodeRabbitState = 'rate-limited'
+const TIER_C = 'bypassing it is Tier C — explicit user instruction only'
+const BY_HAND = `wait it out, post \`${RETRIGGER_BODY}\` and rerun followup; ${TIER_C}`
+const AGAIN_NOTE = `CodeRabbit rate-limited again after the one \`${RETRIGGER_BODY}\` (kit#5289): ${TIER_C}`
+const UNREADABLE_NOTE = `CodeRabbit rate-limited with no window readable from its comments (kit#5289): no retrigger posted — ${BY_HAND}`
+const UNFINISHED_NOTE = `CodeRabbit still reviewing after \`${RETRIGGER_BODY}\` (kit#5289): the merge goes ahead without it`
+
+interface PullComment {
+	body?: string | undefined
+	author?: { login?: string | undefined } | undefined
+	updatedAt?: string | undefined
+}
+
+type Decision =
+	{ kind: 'retrigger'; wait_ms: number } | { kind: 'await' } | { kind: 'stop'; note: string }
+
+interface Retrigger {
+	is_retriggered: boolean
+	notes: Array<string>
+}
+
+interface Settled<T> {
+	snapshot: T
+	is_retriggered: boolean
+	notes: Array<string>
+}
+
+function wait_clause_of(body: string): string {
+	const after_opener = body.split(WAIT_OPENER)[NEXT] ?? ''
+
+	return after_opener.split(WAIT_CLOSER)[FIRST] ?? ''
+}
+
+// The time one token stands for: a number times the unit the next token starts with.
+function token_ms(tokens: ReadonlyArray<string>, index: number): number {
+	const token = tokens[index] ?? ''
+	if (!DIGITS.test(token)) return NO_TIME
+	const unit = (tokens[index + NEXT] ?? '').charAt(FIRST).toLowerCase()
+
+	return Number(token) * (UNIT_MS[unit] ?? NO_TIME)
+}
+
+// The wait CodeRabbit's notice states, or `undefined` for a comment that states none.
+function parse_wait_ms(body: string): number | undefined {
+	if (!is_coderabbit_rate_limit(body)) return undefined
+	const tokens = wait_clause_of(body).match(TOKEN) ?? []
+	const wait_ms = tokens.reduce((sum, _token, index) => sum + token_ms(tokens, index), NO_TIME)
+
+	return wait_ms === NO_TIME ? undefined : wait_ms
+}
+
+function is_notice(comment: PullComment): boolean {
+	return (
+		is_coderabbit_author(comment.author?.login ?? '') &&
+		is_coderabbit_rate_limit(comment.body ?? '')
+	)
+}
+
+function is_retrigger(comment: PullComment): boolean {
+	return comment.body?.trim() === RETRIGGER_BODY
+}
+
+function written_ms(comment: PullComment): number {
+	return Date.parse(comment.updatedAt ?? '')
+}
+
+// The latest time among the comments `is_match` picks; one with no readable time counts as none.
+function latest_ms(
+	comments: ReadonlyArray<PullComment>,
+	is_match: (comment: PullComment) => boolean,
+): number | undefined {
+	const times = comments
+		.filter((comment) => is_match(comment))
+		.map((comment) => written_ms(comment))
+		.filter((ms) => !Number.isNaN(ms))
+
+	return times.length === 0 ? undefined : Math.max(...times)
+}
+
+// The latest end any CodeRabbit notice states — the window counts from when the notice was written.
+function window_end_ms(comments: ReadonlyArray<PullComment>): number | undefined {
+	const ends = comments
+		.filter((comment) => is_notice(comment))
+		.map((comment) => written_ms(comment) + (parse_wait_ms(comment.body ?? '') ?? NaN))
+		.filter((ms) => !Number.isNaN(ms))
+
+	return ends.length === 0 ? undefined : Math.max(...ends)
+}
+
+// A retrigger written after the latest notice is still to be answered; one before it was answered
+// with another rate limit. Either time unreadable reads as the second.
+function decide_after_retrigger(comments: ReadonlyArray<PullComment>): Decision {
+	const retrigger_ms = latest_ms(comments, is_retrigger) ?? NO_TIME
+	const notice_ms = latest_ms(comments, is_notice) ?? retrigger_ms
+
+	return retrigger_ms > notice_ms ? { kind: 'await' } : { kind: 'stop', note: AGAIN_NOTE }
+}
+
+function too_long_note(wait_ms: number): string {
+	const minutes = String(Math.ceil(wait_ms / MINUTE_MS))
+
+	return `CodeRabbit rate-limited for ${minutes} more minutes, over followup's ${String(WINDOW_CAP_MINUTES)} minute wait (kit#5289): no retrigger posted — ${BY_HAND}`
+}
+
+function decide(comments: ReadonlyArray<PullComment>, now_ms: number): Decision {
+	if (comments.some((comment) => is_retrigger(comment))) return decide_after_retrigger(comments)
+	const end_ms = window_end_ms(comments)
+	if (end_ms === undefined) return { kind: 'stop', note: UNREADABLE_NOTE }
+	const wait_ms = Math.max(NO_TIME, end_ms - now_ms) + MARGIN_MS
+
+	return wait_ms > WINDOW_CAP_MS
+		? { kind: 'stop', note: too_long_note(wait_ms) }
+		: { kind: 'retrigger', wait_ms }
+}
+
+async function read_comments(branch_name: string): Promise<Array<PullComment>> {
+	const raw = await git_gh_command.pr_get_comments(branch_name)
+
+	return parse_json_array_or_undefined(raw ?? '', ai_review_pull_comment_schema) ?? []
+}
+
+async function read_state(
+	branch_name: string,
+	observe: SnapshotObserver,
+): Promise<CodeRabbitState> {
+	const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
+	const snapshot = parse_pr_state_snapshot(checks.snapshot_json)
+
+	await observe(snapshot)
+
+	return followup_checks_event.coderabbit_of(snapshot)
+}
+
+// **A rate limit read before the review started is the old one**, so only one read after another
+// state is the second rate limit; a check that never moves off it is read as one at the budget's end.
+// One observer for the whole wait, so its polls are timed against one another.
+async function wait_for_review(branch_name: string, wait: CodeRabbitWait): Promise<Array<string>> {
+	const observe = followup_coderabbit_wait.observer_of(wait)
+	let is_started = false
+	let state: CodeRabbitState = RATE_LIMITED
+	const is_settled = await poll.poll_until(
+		async () => {
+			state = await read_state(branch_name, observe)
+			is_started ||= state !== RATE_LIMITED
+
+			return is_started && state !== 'running'
+		},
+		{ attempts: REVIEW_WAIT_ATTEMPTS, interval_ms: REVIEW_WAIT_INTERVAL_MS, sleeper: poll.sleep },
+	)
+	if (state === RATE_LIMITED) return [AGAIN_NOTE]
+
+	return is_settled ? [] : [UNFINISHED_NOTE]
+}
+
+async function retrigger(
+	branch_name: string,
+	wait: CodeRabbitWait,
+	wait_ms: number,
+): Promise<Retrigger> {
+	const seconds = String(Math.ceil(wait_ms / SECOND_MS))
+
+	console.info(`⏳ CodeRabbit rate-limited — waiting ${seconds}s, then \`${RETRIGGER_BODY}\``)
+	await poll.sleep(wait_ms)
+	await git_gh_command.pr_comment(branch_name, RETRIGGER_BODY)
+	await lane_ledger_write.record_stage({
+		stage: lane_ledger_write.CODERABBIT_RETRIGGER_STAGE,
+		elapsed_ms: wait_ms,
+	})
+
+	return { is_retriggered: true, notes: await wait_for_review(branch_name, wait) }
+}
+
+// Runs only when the check wait last saw CodeRabbit rate-limited; anything else is untouched.
+async function run(branch_name: string, wait: CodeRabbitWait): Promise<Retrigger> {
+	if (wait.last?.state !== RATE_LIMITED) return { is_retriggered: false, notes: [] }
+	const decision = decide(await read_comments(branch_name), Date.now())
+	if (decision.kind === 'stop') return { is_retriggered: false, notes: [decision.note] }
+
+	if (decision.kind === 'await') {
+		return { is_retriggered: true, notes: await wait_for_review(branch_name, wait) }
+	}
+
+	return await retrigger(branch_name, wait, decision.wait_ms)
+}
+
+// The checks after a retriggered review are read again, so the merge and the skip notes read the
+// snapshot that review left, not the rate-limited one.
+async function settle<T>(
+	snapshot: T,
+	wait_for_green: () => Promise<T>,
+	branch_name: string,
+	wait: CodeRabbitWait,
+): Promise<Settled<T>> {
+	const { is_retriggered, notes } = await run(branch_name, wait)
+	if (!is_retriggered) return { snapshot, is_retriggered, notes }
+
+	return { snapshot: await wait_for_green(), is_retriggered, notes }
+}
+
+const followup_coderabbit_retrigger = {
+	AGAIN_NOTE,
+	RETRIGGER_BODY,
+	UNFINISHED_NOTE,
+	UNREADABLE_NOTE,
+	decide,
+	parse_wait_ms,
+	run,
+	settle,
+}
+
+export type { PullComment, Retrigger, Settled }
+export { followup_coderabbit_retrigger }