@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/epic/epic-outside-blocker.ts

@@ -24,6 +24,10 @@ type DependencyVerdict = 'resolved' | 'time' | 'human' | 'inherit'
 // a closed blocker is a finished one.
 type ResolveDependency = (blocker: EpicChild, blocked: EpicChild) => DependencyVerdict
 
+// A notice's mark on `run:board`: ❗ rather than ⚠, a text symbol drawn two columns wide over the
+// blank after it.
+const NOTICE_ICON = '❗'
+
 type OutsideCategory = 'time' | 'human'
 
 // A line to announce once per invocation, keyed so the classifier's de-duplication can drop repeats.
@@ -62,7 +66,7 @@ function unread_answer(child: EpicChild, reference: IssueReference): OutsideAnsw
 		category: 'time',
 		notice: {
 			key: `unread:${epic_graph.key_of(child)}:${blocker}`,
-			message: `⚠ ${name_of(child)} is blocked by ${blocker}, whose state could not be read — it waits rather than runs`,
+			message: `${NOTICE_ICON} ${name_of(child)} is blocked by ${blocker}, whose state could not be read — it waits rather than runs`,
 		},
 	}
 }
@@ -80,7 +84,7 @@ function open_answer(
 		category: 'human',
 		notice: {
 			key: `outside:${epic_graph.key_of(child)}:${blocker}`,
-			message: `⚠ ${name_of(child)} waits on ${blocker}, which this run will not finish — withheld for a person`,
+			message: `${NOTICE_ICON} ${name_of(child)} waits on ${blocker}, which this run will not finish — withheld for a person`,
 		},
 	}
 }

package/scripts/epic/epic-parse.ts

@@ -16,7 +16,10 @@ const TASK_LIST_LINE_PATTERN = new RegExp(TASK_LIST_ISSUE_SOURCE, 'u')
 // `owner/repo#101` on its own. The row patterns below are built from this source, so what counts as
 // a cross-repository reference has one definition — a second copy would let a form the task list
 // accepts be refused where a person types it, or the reverse.
-const EXTERNAL_REFERENCE_SOURCE = String.raw`([\w.-]+)\/([\w.-]+)#(\d+)`
+// A segment starts with a word character, so `.`, `..` and a leading `-` never become an owner or a
+// repository — `../..#1` would otherwise be read as one and walk the API path out of `repos/`.
+const REPOSITORY_SEGMENT_SOURCE = String.raw`\w[\w.-]*`
+const EXTERNAL_REFERENCE_SOURCE = String.raw`(${REPOSITORY_SEGMENT_SOURCE})\/(${REPOSITORY_SEGMENT_SOURCE})#(\d+)`
 const EXTERNAL_REFERENCE_PATTERN = new RegExp(`^${EXTERNAL_REFERENCE_SOURCE}$`, 'u')
 const TASK_LIST_ROW_SOURCE = String.raw`^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+`
 const EXTERNAL_TASK_LIST_PATTERN = new RegExp(
@@ -29,8 +32,10 @@ const EXTERNAL_SHORTHAND_PATTERN = new RegExp(
 	'gmu',
 )
 // `- [ ] https://github.com/owner/repo/issues/101`
-const EXTERNAL_URL_PATTERN =
-	/^[ \t]*[-*+][ \t]+\[[ xX]\][ \t]+https?:\/\/github\.com\/([\w.-]+)\/([\w.-]+)\/issues\/(\d+)\b/gmu
+const EXTERNAL_URL_PATTERN = new RegExp(
+	String.raw`${TASK_LIST_ROW_SOURCE}https?:\/\/github\.com\/(${REPOSITORY_SEGMENT_SOURCE})\/(${REPOSITORY_SEGMENT_SOURCE})\/issues\/(\d+)\b`,
+	'gmu',
+)
 
 // Fenced blocks are stripped before matching. An epic body may quote the body template itself, and
 // its sample rows (`- [ ] #101 <title>`) are illustrations, not tracked children — counting them
@@ -345,4 +350,5 @@ export {
 	is_state_closed,
 	UNORDERED_DEPENDENCIES,
 	DECLARED_CHAIN_LINE,
+	REPOSITORY_SEGMENT_SOURCE,
 }

package/scripts/epic/epic-read.ts

@@ -67,6 +67,7 @@ async function read_epic(epic_number: number): Promise<EpicReading | { error: st
 }
 
 const epic_read = {
+	read_subject,
 	read_epic,
 }
 

package/scripts/epic/epic-reconcile.ts

@@ -235,11 +235,50 @@ async function reconcile_epic(epic_number: number): Promise<number> {
 	return await apply_plan(epic_number, plan)
 }
 
+function with_recorded(
+	recorded: ReadonlyArray<EpicChild>,
+	link: DependencyLink,
+	repo: string,
+): Array<EpicChild> {
+	return recorded.map((child) =>
+		child.number === link.blocked && child.repo === repo
+			? { ...child, blocked_by: [...child.blocked_by, to_blocker(link, repo)] }
+			: child,
+	)
+}
+
+// The plan the epic would reconcile to once `link` is recorded, so a caller about to record it can
+// refuse first — a relation recorded and then refused leaves an order the declaration never carries.
+function build_plan_after(input: ReconcilePlanInput, link: DependencyLink): ReconcilePlan {
+	return build_reconcile_plan({
+		...input,
+		recorded: with_recorded(input.recorded, link, input.repo),
+	})
+}
+
+// Why reconciling after recording `link` would refuse, read before anything is written. An epic that
+// cannot be read throws: a failed read is no answer about whether the reconcile would refuse.
+async function refusal_after(
+	epic_number: number,
+	link: DependencyLink,
+): Promise<string | undefined> {
+	const epic = await epic_read.read_epic(epic_number)
+	if ('error' in epic) throw new Error(epic.error)
+
+	const input = { body: epic.subject.body, recorded: epic.recorded, repo: epic.repo }
+	const plan = build_plan_after(input, link)
+	if (plan.kind === 'cycle') return plan.message
+
+	return plan.kind === 'error' ? plan.error : undefined
+}
+
 const epic_reconcile = {
 	NOTHING_TO_RECONCILE,
 	RECONCILED,
+	build_plan_after,
 	build_reconcile_plan,
 	reconcile_epic,
+	refusal_after,
 }
 
 export { epic_reconcile }

package/scripts/epic/epic-run.ts

@@ -84,7 +84,9 @@ async function fill_run_command(
 	}
 }
 
-async function create_epic(input: CreateEpicInput): Promise<number> {
+// The created epic's number, or `undefined` when its URL could not be read — for a caller that writes
+// to the epic next (`epic:bundle --apply` reconciling a recorded order).
+async function create_epic_number(input: CreateEpicInput): Promise<number | undefined> {
 	await git_gh_command.label_ensure({
 		name: EPIC_LABEL,
 		color: EPIC_LABEL_COLOR,
@@ -110,6 +112,12 @@ async function create_epic(input: CreateEpicInput): Promise<number> {
 	await fill_run_command(epic_number, input)
 	console.info(`▶ Run the children with: ${epic_body.format_run_command(epic_number)}`)
 
+	return epic_number
+}
+
+async function create_epic(input: CreateEpicInput): Promise<number> {
+	await create_epic_number(input)
+
 	return SUCCESS_EXIT_CODE
 }
 
@@ -215,6 +223,7 @@ async function check_epic(epic_number: number): Promise<number> {
 
 const epic_run = {
 	create_epic,
+	create_epic_number,
 	promote_epic,
 	check_epic,
 }

package/scripts/epic/epic-solo.ts

@@ -1,5 +1,5 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
-import { has_any_label, has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
+import { has_label_name, RUN_SOLO_LABEL } from '#scripts/issue/issue-labels'
 import { issue_citation } from '#scripts/rules/issue-citation'
 import { epic_busy, type BusyRead } from './epic-busy'
 import type { EpicChild } from './epic-graph'
@@ -28,8 +28,6 @@ import { epic_report, type EpicNextResult } from './epic-report'
 // them goes first is the ranking's question — `issue-rank.ts` puts a verification-path defect at the head — so an idle
 // repository takes the candidates in rank order like any other.
 
-const SOLO_LABELS: ReadonlySet<string> = new Set([RUN_SOLO_LABEL])
-
 // Which of the ordered candidates may start, which are held back, and why when a reason is worth
 // saying. `offered` keeps the candidates' own order.
 interface SoloSelection {
@@ -38,35 +36,65 @@ interface SoloSelection {
 	notice?: string
 }
 
+interface SoloQueue {
+	solo: EpicChild
+	index: number
+	behind: ReadonlyArray<EpicChild>
+}
+
 interface SoloGate {
 	result: EpicNextResult
 	notice?: string
 }
 
-function is_solo(child: EpicChild): boolean {
+// An issue as its number and its label names — a candidate, or a running issue `run:board` reads.
+type Labelled = Pick<EpicChild, 'number' | 'labels'>
+
+function is_solo(child: Labelled): boolean {
 	return has_label_name(child.labels, RUN_SOLO_LABEL)
 }
 
+// The running `run:solo` issue that lets nothing new start, if any — the one reading `select` and
+// `run:board`'s 🔒 rows share (joshuafolkken/kit#4391).
+function holder_of(running: ReadonlyArray<Labelled>): number | undefined {
+	return running.find((issue) => is_solo(issue))?.number
+}
+
 function solo_holder(read: BusyRead): number | undefined {
 	if (read.kind !== 'busy') return undefined
+	const running = read.issues.map((issue) => ({
+		number: issue.number,
+		labels: (issue.labels ?? []).map((label) => label.name),
+	}))
 
-	return read.issues.find((issue) => has_any_label(issue.labels, SOLO_LABELS))?.number
+	return holder_of(running)
 }
 
+// The words each of the gate's wait notices carries, so `backlog:offer` tells a `run:solo` wait from any
+// other `wait` off the notice `backlog:next` printed (joshuafolkken/kit#4396). Each names its verb:
+// `epic_solo_stale`'s release notice also opens "carries `run:solo` and", and is no wait.
+const HELD_MARK = `carries \`${RUN_SOLO_LABEL}\` and is running in`
+const WAITING_MARK = `carries \`${RUN_SOLO_LABEL}\` and waits for`
+
 function held_message(holder: number, repo: string): string {
 	return issue_citation.linkify(
-		`${issue_cite.plain(holder)} carries \`${RUN_SOLO_LABEL}\` and is running in ${repo}; nothing else starts until it merges or is parked.`,
+		`${issue_cite.plain(holder)} ${HELD_MARK} ${repo}; nothing else starts until it merges or is parked.`,
 		repo,
 	)
 }
 
 function waiting_message(solo: number, repo: string): string {
 	return issue_citation.linkify(
-		`${issue_cite.plain(solo)} carries \`${RUN_SOLO_LABEL}\` and waits for ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
+		`${issue_cite.plain(solo)} ${WAITING_MARK} ${repo}'s running lanes to finish; nothing ranked below it is offered past it.`,
 		repo,
 	)
 }
 
+// Whether `text` — what an offer printed on stderr — says the `run:solo` gate held the candidates.
+function is_solo_wait(text: string): boolean {
+	return text.includes(HELD_MARK) || text.includes(WAITING_MARK)
+}
+
 function first_of(children: ReadonlyArray<EpicChild>, keep: number): SoloSelection {
 	return { offered: children.slice(0, keep), withheld: children.slice(keep) }
 }
@@ -75,6 +103,15 @@ function none_of(children: ReadonlyArray<EpicChild>, notice: string): SoloSelect
 	return { offered: [], withheld: [...children], notice }
 }
 
+// The first `run:solo` candidate, where it sits, and the candidates ranked behind it, which nothing
+// offers past it. `run:board` draws the same reading on its queued rows (joshuafolkken/kit#4294).
+function queue_of(children: ReadonlyArray<EpicChild>): SoloQueue | undefined {
+	const index = children.findIndex((child) => is_solo(child))
+	const solo = children[index]
+
+	return solo === undefined ? undefined : { solo, index, behind: children.slice(index + 1) }
+}
+
 // Where the first `run:solo` candidate sits decides what starts: everything when there is none, the
 // candidates ahead of it when it is not first, and it alone once it heads an idle repository's ranking.
 function select_candidates(
@@ -82,14 +119,13 @@ function select_candidates(
 	read: BusyRead,
 	repo: string,
 ): SoloSelection {
-	const index = children.findIndex((child) => is_solo(child))
-	const solo = children[index]
+	const queue = queue_of(children)
 
-	if (solo === undefined) return first_of(children, children.length)
-	if (index > 0) return first_of(children, index)
+	if (queue === undefined) return first_of(children, children.length)
+	if (queue.index > 0) return first_of(children, queue.index)
 	if (read.kind === 'idle') return first_of(children, 1)
 
-	return none_of(children, waiting_message(solo.number, repo))
+	return none_of(children, waiting_message(queue.solo.number, repo))
 }
 
 // An unreadable or truncated listing keeps nothing: without it a running `run:solo` issue cannot be
@@ -143,7 +179,7 @@ function gate(
 		: { result: gated, notice: selection.notice }
 }
 
-const epic_solo = { gate, is_solo, select }
+const epic_solo = { gate, holder_of, is_solo, is_solo_wait, queue_of, select }
 
-export type { SoloGate, SoloSelection, SoloSelector }
+export type { Labelled, SoloGate, SoloQueue, SoloSelection, SoloSelector }
 export { epic_solo }

package/scripts/epic/epic.ts

@@ -8,11 +8,13 @@
  *        tsx scripts/epic/epic.ts --add <E> <N1> <N2> ... [--before <M> | --after <M>]
  *                                                      [--decision-file <path|->]
  *        tsx scripts/epic/epic.ts --remove <E> <M> <N> ... [--decision-file <path|->]
+ *        tsx scripts/epic/epic.ts --decide <E> <N1> <N2> ... --decision-file <path|->
  */
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { error_text } from '#scripts/lib/error-message'
 import { epic_add, type AddChildrenInput } from './epic-add'
 import { epic_cli, type AddArguments, type CrossRepoAddTarget } from './epic-cli'
+import { epic_decide } from './epic-decide'
 import { epic_reconcile } from './epic-reconcile'
 import { epic_remove } from './epic-remove'
 import { epic_run } from './epic-run'
@@ -26,6 +28,7 @@ const USAGE = [
 	'       josh epic --add <E> <N1> <N2> ... [--order-before <M> | --order-after <M>] [--decision-file <path|->]',
 	'       josh epic --remove <E> <M> <N> ... [--decision-file <path|->]',
 	'       josh epic --reconcile <E>',
+	'       josh epic --decide <E> <N1> <N2> ... --decision-file <path|->',
 ].join('\n')
 const FAILURE_EXIT_CODE = 1
 
@@ -134,6 +137,26 @@ async function run_removal(argv: ReadonlyArray<string>): Promise<number> {
 	})
 }
 
+// A decision about children the epic already tracks — the half `--add --decision-file` cannot write,
+// since an insertion with nothing to add is refused.
+async function run_decision(argv: ReadonlyArray<string>): Promise<number> {
+	const parsed = epic_cli.parse_decide_arguments(argv)
+
+	if (parsed === undefined) {
+		console.error(
+			`✖ An epic number, at least one child issue number, and exactly one readable \`--decision-file\` path (\`-\` reads stdin) are required.\n${USAGE}`,
+		)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await epic_decide.decide({
+		epic_number: parsed.epic_number,
+		children: parsed.children,
+		decision: epic_cli.read_decision(parsed.decision_path) ?? '',
+	})
+}
+
 // Reconcile an epic's declaration with its recorded relations. No decision file and no children: the
 // repair reads what the epic already records rather than being told an order.
 async function run_reconciliation(argv: ReadonlyArray<string>): Promise<number> {
@@ -166,15 +189,26 @@ async function run_creation(argv: ReadonlyArray<string>): Promise<number> {
 	})
 }
 
-// `--add` is checked before `--promote`: both name an existing issue first, and only the flag
-// distinguishes "insert into this epic" from "turn this issue into one".
+type EpicForm = readonly [
+	(argv: ReadonlyArray<string>) => boolean,
+	(argv: ReadonlyArray<string>) => Promise<number>,
+]
+
+// Checked in this order. `--add` comes before `--promote`: both name an existing issue first, and only
+// the flag distinguishes "insert into this epic" from "turn this issue into one".
+const FLAGGED_FORMS: ReadonlyArray<EpicForm> = [
+	[epic_cli.is_reconciliation, run_reconciliation],
+	[epic_cli.is_removal, run_removal],
+	[epic_cli.is_decision_entry, run_decision],
+	[epic_cli.is_addition, run_addition],
+	[epic_cli.is_promotion, run_promotion],
+]
+
 async function run(argv: ReadonlyArray<string>): Promise<number> {
-	if (epic_cli.is_reconciliation(argv)) return await run_reconciliation(argv)
-	if (epic_cli.is_removal(argv)) return await run_removal(argv)
-	if (epic_cli.is_addition(argv)) return await run_addition(argv)
-	if (epic_cli.is_promotion(argv)) return await run_promotion(argv)
+	const form = FLAGGED_FORMS.find(([is_form]) => is_form(argv))
+	const run_form = form === undefined ? run_creation : form[1]
 
-	return await run_creation(argv)
+	return await run_form(argv)
 }
 
 async function main(): Promise<void> {

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

@@ -4,7 +4,7 @@ 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 './namespace-members'
+import type { NamespaceMember } from '#tools/exports/namespace-members'
 
 const CHECK = 'exports'
 const FAIL_EXIT_CODE = 1
@@ -39,7 +39,7 @@ async function run_unused_members(root: string): Promise<number> {
 	// 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('./unused-members')
+	const { unused_members } = await import('#tools/exports/unused-members')
 	const members = unused_members.find_unused_members(root)
 	const output = report(root, members)
 

package/scripts/followup/followup-checks-event.ts

@@ -35,16 +35,21 @@ function coderabbit_state_of(check: RollupCheck | undefined): CodeRabbitState {
 	return is_coderabbit_rate_limited(check) ? 'rate-limited' : 'done'
 }
 
+// CodeRabbit's state on one poll — the reading `run:board` draws and `followup` times
+// (`followup-coderabbit-wait.ts`).
+function coderabbit_of(snapshot: PrStateSnapshot): CodeRabbitState {
+	return coderabbit_state_of(snapshot.rollup.find((check) => is_coderabbit_check(check.name)))
+}
+
 function summary_of(snapshot: PrStateSnapshot, pr: number): PrChecks {
 	const ci = snapshot.rollup.filter((check) => !is_coderabbit_check(check.name))
-	const coderabbit = snapshot.rollup.find((check) => is_coderabbit_check(check.name))
 
 	return {
 		pr,
 		pass: count_of(ci, CHECK_STATUS_PASS),
 		pending: count_of(ci, CHECK_STATUS_PENDING),
 		fail: count_of(ci, CHECK_STATUS_FAIL),
-		coderabbit: coderabbit_state_of(coderabbit),
+		coderabbit: coderabbit_of(snapshot),
 	}
 }
 
@@ -77,6 +82,6 @@ function observer_of(issue: string | undefined, pr_url: string | undefined): Sna
 	}
 }
 
-const followup_checks_event = { observer_of, summary_of }
+const followup_checks_event = { coderabbit_of, observer_of, summary_of }
 
 export { followup_checks_event }

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

@@ -0,0 +1,82 @@
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import type { PrStateSnapshot } from '#scripts/gh/git-pr-checks-parse'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import type { CodeRabbitState } from '#scripts/run/event/run-event-checks'
+import { followup_checks_event } from './followup-checks-event'
+
+// How long `followup`'s check waits spent with CodeRabbit still running or rate-limited
+// (joshuafolkken/kit#4574). CodeRabbit does not gate the merge, so the wait never names it; without
+// this, a followup that sat for half an hour beside a rate-limited CodeRabbit leaves nothing in the
+// lane ledger but a long `ci-wait`.
+//
+// **The time between two polls is the state the earlier poll saw** — the observer sees snapshots, not
+// transitions, so the clock is read at each one and the interval since the last is charged to the
+// state that held over it. The clock is `performance.now()`'s, monotonic for the reason
+// `git-followup-stages.ts` states.
+
+const NO_TIME = 0
+const RATE_LIMITED: CodeRabbitState = 'rate-limited'
+const WAITING_STATES: ReadonlySet<CodeRabbitState> = new Set(['running', RATE_LIMITED])
+
+interface Poll {
+	state: CodeRabbitState
+	at_ms: number
+}
+
+// Mutable for the reason `StageLog` is: the observer adds to it as the wait polls.
+interface CodeRabbitWait {
+	wait_ms: number
+	rate_limited_ms: number
+	last?: Poll
+}
+
+function new_wait(): CodeRabbitWait {
+	return { wait_ms: NO_TIME, rate_limited_ms: NO_TIME }
+}
+
+function charge(wait: CodeRabbitWait, last: Poll, now_ms: number): void {
+	const elapsed_ms = now_ms - last.at_ms
+
+	if (WAITING_STATES.has(last.state)) wait.wait_ms += elapsed_ms
+	if (last.state === RATE_LIMITED) wait.rate_limited_ms += elapsed_ms
+}
+
+function observe(wait: CodeRabbitWait, snapshot: PrStateSnapshot, now_ms: number): void {
+	if (wait.last !== undefined) charge(wait, wait.last, now_ms)
+
+	wait.last = { state: followup_checks_event.coderabbit_of(snapshot), at_ms: now_ms }
+}
+
+// **Each check wait is timed from its own first poll**: the time between two waits — the comment scans,
+// the merge that found the head moved — is not CodeRabbit's, whatever the earlier wait last saw.
+function observer_of(wait: CodeRabbitWait): SnapshotObserver {
+	delete wait.last
+
+	return async function time_snapshot(snapshot: PrStateSnapshot): Promise<void> {
+		observe(wait, snapshot, performance.now())
+	}
+}
+
+// Both observers on every poll — the board's event line and this timer.
+function both(first: SnapshotObserver, second: SnapshotObserver): SnapshotObserver {
+	return async function observe_both(snapshot: PrStateSnapshot): Promise<void> {
+		await first(snapshot)
+		await second(snapshot)
+	}
+}
+
+async function record_part(stage: string, elapsed_ms: number): Promise<void> {
+	if (elapsed_ms > NO_TIME) await lane_ledger.record_stage({ stage, elapsed_ms })
+}
+
+// **A run that never saw CodeRabbit waiting records nothing**, so a row's run count is how many
+// followups CodeRabbit held up, and its median is over those.
+async function record(wait: CodeRabbitWait): Promise<void> {
+	await record_part(lane_ledger.CODERABBIT_WAIT_STAGE, wait.wait_ms)
+	await record_part(lane_ledger.CODERABBIT_RATE_LIMIT_STAGE, wait.rate_limited_ms)
+}
+
+const followup_coderabbit_wait = { both, new_wait, observe, observer_of, record }
+
+export type { CodeRabbitWait }
+export { followup_coderabbit_wait }

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

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

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

@@ -1,6 +1,7 @@
 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'
+import { followup_coderabbit_wait, type CodeRabbitWait } from './followup-coderabbit-wait'
 
 // Where `pnpm josh followup` spends its own wall clock.
 //
@@ -90,13 +91,17 @@ interface FollowupStage {
 // `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.
+//
+// `coderabbit` rides on the log because every check wait of the run — the merge gate's and the one the
+// merge goes back to (#4036) — adds to the same CodeRabbit time.
 interface StageLog {
 	stages: Array<FollowupStage>
 	last_ms: number
+	coderabbit: CodeRabbitWait
 }
 
 function new_log(): StageLog {
-	return { stages: [], last_ms: performance.now() }
+	return { stages: [], last_ms: performance.now(), coderabbit: followup_coderabbit_wait.new_wait() }
 }
 
 function lap(log: StageLog, name: string): void {
@@ -140,7 +145,7 @@ function print_stages(log: StageLog): void {
 
 // 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.
+// `interrupted` lap and records nothing here. CodeRabbit's part of the waits goes beside it.
 async function record_ci_wait(log: StageLog): Promise<void> {
 	const wait = log.stages.find((stage) => stage.name === STAGE.checks_wait)
 
@@ -152,6 +157,11 @@ async function record_ci_wait(log: StageLog): Promise<void> {
 	})
 }
 
+async function record_waits(log: StageLog): Promise<void> {
+	await record_ci_wait(log)
+	await followup_coderabbit_wait.record(log.coderabbit)
+}
+
 const git_followup_stages = {
 	STAGE,
 	STAGE_LINE_PREFIX,
@@ -161,7 +171,7 @@ const git_followup_stages = {
 	total_ms,
 	format_stages,
 	print_stages,
-	record_ci_wait,
+	record_waits,
 	stopped_lap,
 }