@joshuafolkken/kit 1.1387.0 → 1.1435.0

package/scripts/doctor/doctor-io.ts

@@ -1,8 +1,9 @@
 import { existsSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { pnpm_reach } from '#scripts/lib/pnpm-reach'
 import { read_spawn_stdout } from '#scripts/lib/spawn-exit'
-import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { COMMAND_TIMEOUT_MS, PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execaSync } from 'execa'
 import { doctor_logic } from './doctor-logic'
 
@@ -19,22 +20,45 @@ const AUTO_MERGE_WORKFLOW_PATH = '.github/workflows/dependabot-auto-merge.yml'
 // consumer's own auto-merge workflow which does creates the same one kit's does.
 const AUTO_MERGE_COMMAND = 'gh pr merge --auto'
 const YAML_COMMENT_PREFIX = '#'
+const UNKNOWN_PNPM: PnpmProbe = { state: 'unknown' }
 
-// Resolve the `josh` that the shell would run — the first match on PATH, via the platform's
-// lookup command (`where` on Windows, `which` elsewhere). Undefined when the lookup fails or
-// prints nothing (no `josh` on PATH, e.g. inside the kit repo where only `pnpm josh` runs).
-function resolve_path_josh(): string | undefined {
+// What the platform's lookup command said about a name: whether the command itself could be
+// started, and the first match it printed.
+interface PathLookup {
+	did_run: boolean
+	first_path: string | undefined
+}
+
+// Ask the platform's lookup command (`where` on Windows, `which` elsewhere) for `bin` on PATH.
+function look_up_on_path(bin: string): PathLookup {
 	const lookup = doctor_logic.path_lookup_command(process.platform)
-	const result = execaSync(lookup, [JOSH_BIN], { reject: false })
+	const result = execaSync(lookup, [bin], { reject: false })
+
+	return {
+		did_run: !pnpm_reach.is_not_found(result),
+		first_path: doctor_logic.first_path_line(read_spawn_stdout(result)),
+	}
+}
+
+// Resolve the `josh` that the shell would run — the first match on PATH. Undefined when the lookup
+// fails or prints nothing (no `josh` on PATH, e.g. inside the kit repo where only `pnpm josh` runs).
+function resolve_path_josh(): string | undefined {
+	return look_up_on_path(JOSH_BIN).first_path
+}
+
+// Whether the lookup command ran and found no `bin`. A lookup command that is itself absent proves
+// nothing about `bin`, so it is not an answer.
+function is_off_path(bin: string): boolean {
+	const { did_run, first_path } = look_up_on_path(bin)
 
-	return doctor_logic.first_path_line(read_spawn_stdout(result))
+	return did_run && first_path === undefined
 }
 
 // Resolve the pnpm-global `josh` bin path. Undefined when pnpm is missing or the global bin does
 // not contain a `josh` (kit not installed globally). `pnpm bin -g` prepends a `[WARN]` line to
 // stdout inside a project, so the bin directory is extracted via first_path_line.
 function resolve_pnpm_global_josh(): string | undefined {
-	const result = execaSync('pnpm', ['bin', '-g'], { reject: false })
+	const result = execaSync(pnpm_reach.PNPM, ['bin', '-g'], { reject: false })
 	const bin_directory = doctor_logic.first_path_line(read_spawn_stdout(result))
 	if (bin_directory === undefined) return undefined
 	const candidate = path.join(bin_directory, JOSH_BIN)
@@ -42,6 +66,29 @@ function resolve_pnpm_global_josh(): string | undefined {
 	return existsSync(candidate) ? candidate : undefined
 }
 
+// A spawn that found no executable proves pnpm is off PATH, but Windows never reports one: an
+// unresolved `pnpm` is handed to `cmd.exe`, which starts, prints "'pnpm' is not recognized" and exits
+// 1. So a pnpm that did not answer is also looked up by name, which says the same thing everywhere.
+function is_pnpm_missing(result: { code?: string | undefined }): boolean {
+	return pnpm_reach.is_not_found(result) || is_off_path(pnpm_reach.PNPM)
+}
+
+// Whether this process can start `pnpm`, and which one answers. `josh` runs its checks as
+// `pnpm josh <check>` children, so a `pnpm` this process cannot see fails every one of them before
+// it starts; asking here is what lets a user learn it before a gate does. `missing` is
+// kept apart from `unknown`: a pnpm that is on PATH and failed is a different fault with a
+// different fix.
+function probe_pnpm(): PnpmProbe {
+	const result = execaSync(pnpm_reach.PNPM, ['--version'], {
+		reject: false,
+		timeout: COMMAND_TIMEOUT_MS,
+	})
+	const version = read_spawn_stdout(result).trim()
+	if (version !== '' && result.exitCode === 0) return { state: 'found', version }
+
+	return is_pnpm_missing(result) ? { state: 'missing' } : UNKNOWN_PNPM
+}
+
 // Whether the working directory is provably *outside* a git work tree. Purely local — no network,
 // and it does not depend on `gh` being installed or authenticated, which is what makes it usable to
 // decide whether a repository-scoped check applies at all.
@@ -192,7 +239,11 @@ function has_auto_merge_workflow(start: string, boundary?: string): boolean {
 type GitTopLevel =
 	{ state: 'inside'; top_level: string } | { state: 'outside' } | { state: 'undetermined' }
 
+// What asking `pnpm --version` from this process established.
+type PnpmProbe = { state: 'found'; version: string } | { state: 'missing' } | { state: 'unknown' }
+
 const doctor_io = {
+	probe_pnpm,
 	resolve_path_josh,
 	resolve_pnpm_global_josh,
 	has_distributed_dependabot_config,
@@ -200,5 +251,5 @@ const doctor_io = {
 	resolve_git_top_level,
 }
 
-export type { GitTopLevel }
+export type { GitTopLevel, PnpmProbe }
 export { doctor_io }

package/scripts/doctor/doctor.ts

@@ -5,12 +5,13 @@ import { fileURLToPath } from 'node:url'
 import { repo_discovery } from '#scripts/discovery/repo-discovery'
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { pnpm_reach } from '#scripts/lib/pnpm-reach'
 import { auto_merge_setting } from '#scripts/repo/auto-merge-setting'
 import { ruleset_check } from '#scripts/repo/ruleset-check'
 import { security_updates } from '#scripts/security/security-updates'
 import { running_binary } from '#scripts/version/running-binary'
 import { doctor_consumer } from './doctor-consumer'
-import { doctor_io, type GitTopLevel } from './doctor-io'
+import { doctor_io, type GitTopLevel, type PnpmProbe } from './doctor-io'
 import { doctor_logic } from './doctor-logic'
 import { doctor_ports } from './doctor-ports'
 
@@ -43,10 +44,12 @@ interface DoctorContext {
 	running_path: string
 	path_josh: string | undefined
 	global_josh: string | undefined
+	pnpm: PnpmProbe
 }
 
 function gather_context(): DoctorContext {
 	return {
+		pnpm: doctor_io.probe_pnpm(),
 		running_version: running_binary.read_running_version(SELF_DIR),
 		running_path: running_binary.running_package_directory(SELF_DIR),
 		path_josh: doctor_io.resolve_path_josh(),
@@ -54,13 +57,28 @@ function gather_context(): DoctorContext {
 	}
 }
 
+function describe_pnpm(probe: PnpmProbe): string {
+	if (probe.state === 'found') return probe.version
+
+	return probe.state === 'missing' ? NOT_ON_PATH : UNKNOWN
+}
+
 function print_report(ctx: DoctorContext): void {
 	console.info('josh doctor')
 	console.info(`  Running:     ${ctx.running_version ?? UNKNOWN}  (${ctx.running_path})`)
 	console.info(`  On PATH:     ${ctx.path_josh ?? NOT_ON_PATH}`)
+	console.info(`  pnpm:        ${describe_pnpm(ctx.pnpm)}`)
 	console.info(`  pnpm global: ${ctx.global_josh ?? UNKNOWN}`)
 }
 
+// Said here rather than left to the gate: every check `josh` runs is a `pnpm` child, so without
+// pnpm on this process's PATH each of them fails before it starts.
+function report_pnpm_reach(ctx: DoctorContext): void {
+	if (ctx.pnpm.state !== 'missing') return
+	console.info('')
+	console.info(`⚠ ${pnpm_reach.NOT_ON_PATH_NOTICE}`)
+}
+
 // Remove a confirmed stale kit shim so the pnpm-global josh reclaims PATH precedence. Any other
 // shadowing binary is left in place and reported for manual review.
 function reclaim_shim(path_josh: string, global_josh: string): void {
@@ -207,6 +225,7 @@ function consumer_root(git: GitTopLevel): string {
 function run_reports(ctx: DoctorContext, git: GitTopLevel, options: DoctorOptions): void {
 	print_report(ctx)
 	report_path_diagnosis(ctx, options.is_fix)
+	report_pnpm_reach(ctx)
 	doctor_consumer.report_consumer_setup(consumer_root(git))
 	report_repository_map(git)
 	if (options.show_ports) report_port_seeds(git)

package/scripts/document/document-byte-budget.ts

@@ -74,9 +74,9 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: '.claude/skills/workflow-commands/target-repository.md', bytes: 4096 },
 	{ path: '.claude/skills/workflow-commands/working-tree-hold.md', bytes: 8192 },
 	{ path: 'docs/josh-commands-automation.md', bytes: 53_248 },
-	{ path: 'docs/josh-commands-run.md', bytes: 69_632 },
-	{ path: 'docs/josh-commands-backlog.md', bytes: 57_344 },
-	{ path: 'docs/josh-commands.md', bytes: 49_152 },
+	{ path: 'docs/josh-commands-run.md', bytes: 77_824 },
+	{ path: 'docs/josh-commands-backlog.md', bytes: 61_440 },
+	{ path: 'docs/josh-commands.md', bytes: 53_248 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
 import { cutoff_of, type ScanCutoff } from '#scripts/git/listing-cutoff'
 import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_cite } from '#scripts/issue/issue-cite'
@@ -14,6 +15,7 @@ import {
 	type BacklogIssue,
 	type BundleAction,
 	type BundleDecision,
+	type MembershipContext,
 } from './epic-bundle'
 import { epic_bundle_evidence } from './epic-bundle-evidence'
 import { epic_bundle_gaps } from './epic-bundle-gaps'
@@ -53,6 +55,7 @@ const UNKNOWN_REPO_MESSAGE =
 // describing one it does.
 const backlog_schema = epic_schema.extend({
 	title: z.string().nullable(),
+	labels: z.array(issue_label_schema).default([]),
 	blocked_by_count: z.number().nullish(),
 })
 
@@ -62,10 +65,6 @@ type BacklogRow = z.infer<typeof backlog_schema>
 // task-list read would answer differently the first time that shape moved.
 const { build_epic_index } = epic_index
 
-function to_epic_field(epic: number | undefined): { epic?: number } {
-	return epic === undefined ? {} : { epic }
-}
-
 // Undefined when the read failed, which the caller reports — as opposed to an issue that genuinely
 // declares no relations, which is an empty array.
 async function epic_issue_relations(
@@ -139,18 +138,19 @@ interface FetchedBacklog {
 // One listing row as the bundler reads it. Split from the fetch so that function stays a list of
 // requests rather than a request list plus a row mapping.
 function to_backlog_issue(
-	row: { number: number; title?: string | null; body?: string | null },
-	context: { repo: string; epics: Map<number, number>; epic_numbers: ReadonlySet<number> },
+	row: Pick<BacklogRow, 'number' | 'title' | 'body' | 'labels'>,
+	context: MembershipContext & { repo: string },
 	blocked_by: ReadonlyArray<IssueReference>,
 ): BacklogIssue {
+	const labels = row.labels.map((label) => label.name)
+
 	return {
 		number: row.number,
 		repo: context.repo,
 		title: row.title ?? '',
 		body: row.body ?? '',
 		blocked_by,
-		is_epic: context.epic_numbers.has(row.number),
-		...to_epic_field(context.epics.get(row.number)),
+		...epic_bundle.membership_of(row.number, labels, context),
 	}
 }
 

package/scripts/epic/epic-bundle-referenced.ts

@@ -1,7 +1,7 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
 import { epic_audit_logic } from './epic-audit'
-import type { BacklogIssue } from './epic-bundle'
+import { epic_bundle, type BacklogIssue } from './epic-bundle'
 import { epic_issue, type EpicIssue } from './epic-issue'
 
 // Candidates the open backlog cannot show, read from the subject's own prose.
@@ -64,15 +64,12 @@ interface ReferencedContext {
 }
 
 function to_backlog_issue(issue: EpicIssue, context: ReferencedContext): BacklogIssue {
-	const epic = context.epics.get(issue.number)
-
 	return {
 		number: issue.number,
 		repo: context.repo,
 		body: issue.body,
 		blocked_by: epic_issue.blocker_references_of(issue, context.repo),
-		is_epic: context.epic_numbers.has(issue.number),
-		...(epic !== undefined && { epic }),
+		...epic_bundle.membership_of(issue.number, epic_issue.label_names(issue), context),
 	}
 }
 

package/scripts/epic/epic-bundle.ts

@@ -1,4 +1,5 @@
 import { issue_cite } from '#scripts/issue/issue-cite'
+import { has_label_name, RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { epic_audit_logic } from './epic-audit'
 import { epic_graph } from './epic-graph'
 import type { DependencyLink } from './epic-parse'
@@ -31,6 +32,11 @@ interface BacklogIssue {
 	// its parent, so without this every child would find its own epic as a candidate and be told to
 	// bundle with it.
 	is_epic?: boolean
+	// Whether this issue is the release issue. `issue:file --release` records every change awaiting
+	// publication as its blocker, so the relation is mechanical and says nothing about the work
+	// belonging together — read as a signal, it proposed one epic for the release and every
+	// unrelated change waiting on it.
+	is_release?: boolean
 	// Repository-qualified, not bare numbers. Issue numbers are unique per
 	// repository, so a blocker read as `40` alone matched any candidate numbered 40 — including one in
 	// a different repository entirely. That produced a bundle nobody's data supported, and, through
@@ -79,6 +85,36 @@ function has_recorded_dependency(subject: BacklogIssue, other: BacklogIssue): bo
 	return names_as_blocker(subject, other) || names_as_blocker(other, subject)
 }
 
+// The epic view an issue is placed against: which epic tracks each issue, and the epics themselves.
+interface MembershipContext {
+	epics: ReadonlyMap<number, number>
+	epic_numbers: ReadonlySet<number>
+}
+
+type Membership = Pick<BacklogIssue, 'epic' | 'is_epic' | 'is_release'>
+
+// The fields that decide whether and where an issue takes part in a bundle. Single-sourced so the
+// listing read and the per-reference read cannot disagree about which issue is an epic or the
+// release one.
+function membership_of(
+	number: number,
+	labels: ReadonlyArray<string>,
+	context: MembershipContext,
+): Membership {
+	const epic = context.epics.get(number)
+
+	return {
+		is_epic: context.epic_numbers.has(number),
+		is_release: has_label_name(labels, RELEASE_LABEL),
+		...(epic !== undefined && { epic }),
+	}
+}
+
+// Neither an epic nor the release issue takes part in a bundle, on either side.
+function is_excluded(issue: BacklogIssue): boolean {
+	return issue.is_epic === true || issue.is_release === true
+}
+
 // A strong signal, and only a strong signal.
 //
 // Similar titles are deliberately not one. "Related" expands without limit, and a threshold is what
@@ -87,9 +123,7 @@ function has_recorded_dependency(subject: BacklogIssue, other: BacklogIssue): bo
 function is_strong_signal(subject: BacklogIssue, other: BacklogIssue): boolean {
 	// Neither side. Asked about an epic, the one-sided check found every one of its children through
 	// their own `parent: #N` line and proposed bundling a container with its contents.
-	if (subject.number === other.number || subject.is_epic === true || other.is_epic === true) {
-		return false
-	}
+	if (subject.number === other.number || is_excluded(subject) || is_excluded(other)) return false
 
 	return has_mutual_reference(subject, other) || has_recorded_dependency(subject, other)
 }
@@ -295,10 +329,11 @@ const epic_bundle = {
 	already_tracked_reason,
 	has_recorded_dependency,
 	is_strong_signal,
+	membership_of,
 	decide_bundle,
 	bundle_dependency_links,
 	bundle_children,
 }
 
-export type { BacklogIssue, BundleAction, BundleDecision }
+export type { BacklogIssue, BundleAction, BundleDecision, MembershipContext }
 export { epic_bundle }

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

@@ -3,6 +3,7 @@ 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 './namespace-members'
 
 const CHECK = 'exports'
@@ -13,7 +14,7 @@ const FAIL_EXIT_CODE = 1
 // **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 in a consumer project.`
+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}`

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

@@ -0,0 +1,82 @@
+import type { SnapshotObserver } from '#scripts/gh/git-pr-checks'
+import { is_coderabbit_check, is_coderabbit_rate_limited } from '#scripts/gh/git-pr-checks-eval'
+import {
+	CHECK_STATUS_FAIL,
+	CHECK_STATUS_PASS,
+	CHECK_STATUS_PENDING,
+	type PrStateSnapshot,
+	type RollupCheck,
+} from '#scripts/gh/git-pr-checks-parse'
+import {
+	run_event_checks,
+	type CodeRabbitState,
+	type PrChecks,
+} from '#scripts/run/event/run-event-checks'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+
+// What `followup`'s check wait tells the run's event stream (joshuafolkken/kit#3770): the CI counts and
+// CodeRabbit's state, one `pr-checks` line each time they change, so `run:board` draws a child waiting
+// in followup from the stream alone. CodeRabbit is counted apart — it has a state of its own and does
+// not gate the merge.
+
+const PR_NUMBER_PATTERN = /\/pull\/(?<number>\d+)/u
+const { PR_CHECKS } = run_event_stream.EVENT_KIND
+
+function count_of(checks: ReadonlyArray<RollupCheck>, status: string): number {
+	return checks.filter((check) => check.status === status).length
+}
+
+function coderabbit_state_of(check: RollupCheck | undefined): CodeRabbitState {
+	if (check === undefined) return 'none'
+	if (check.status === CHECK_STATUS_PENDING) return 'running'
+	if (check.status !== CHECK_STATUS_PASS) return 'failed'
+
+	return is_coderabbit_rate_limited(check) ? 'rate-limited' : 'done'
+}
+
+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),
+	}
+}
+
+function pr_number_of(pr_url = ''): number | undefined {
+	const number = PR_NUMBER_PATTERN.exec(pr_url)?.groups?.['number']
+
+	return number === undefined ? undefined : Number(number)
+}
+
+async function skip_snapshot(): Promise<void> {
+	// Nothing names the child or its pull request, so there is no row to report to.
+}
+
+// An observer that writes a line only when it differs from the one this wait last wrote; one that
+// does nothing where the issue or the pull request is unknown.
+function observer_of(issue: string | undefined, pr_url: string | undefined): SnapshotObserver {
+	const pr = pr_number_of(pr_url)
+
+	if (issue === undefined || pr === undefined) return skip_snapshot
+
+	let last_text = ''
+
+	return async function report_snapshot(snapshot: PrStateSnapshot): Promise<void> {
+		const text = run_event_checks.text_of(issue, summary_of(snapshot, pr))
+
+		if (text === last_text) return
+
+		last_text = text
+		await run_event_stream_emit.emit(PR_CHECKS, text)
+	}
+}
+
+const followup_checks_event = { observer_of, summary_of }
+
+export { followup_checks_event }

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

@@ -1,4 +1,5 @@
 import { git_next_issues } from '#scripts/issue/git-next-issues'
+import { issue_watch } from '#scripts/issue/issue-watch'
 import { review_attest } from '#scripts/review/review-attest'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { run_hold } from '#scripts/run/hold/run-hold'
@@ -67,11 +68,24 @@ async function clear_review_target(should_merge: boolean): Promise<void> {
 	}
 }
 
-// The two review records are one step of the tail: both are cleared by a merged run and neither is
-// worth reporting on its own.
+// The issue watch ends with the run it watched: a record left behind would make the next run's hook
+// poll an issue that is no longer its own.
+async function clear_issue_watch(should_merge: boolean): Promise<void> {
+	if (!should_merge) return
+
+	try {
+		await issue_watch.clear_here()
+	} catch {
+		/* the next `josh run:entry` replaces the record */
+	}
+}
+
+// The review records and the issue watch are one step of the tail: all are cleared by a merged run
+// and none is worth reporting on its own.
 async function clear_review_records(should_merge: boolean): Promise<void> {
 	clear_round_one_snapshot(should_merge)
 	await clear_review_target(should_merge)
+	await clear_issue_watch(should_merge)
 }
 
 // The working-tree hold a typed entry point claims before it starts is released here, on the one seam every `fullrun` — and every child of an `epicrun` or a `queue` —

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

@@ -3,6 +3,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 { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 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'
@@ -151,9 +152,11 @@ async function assert_review_attested(should_merge: boolean): Promise<void> {
 
 	const verdict = await review_attest.check_here()
 
-	if (is_merge_permitted(verdict.status)) return
+	if (!is_merge_permitted(verdict.status)) throw new Error(review_attest.refusal_message(verdict))
+
+	const refusal = await issue_watch_gate.review_refusal_here()
 
-	throw new Error(review_attest.refusal_message(verdict))
+	if (refusal !== undefined) throw new Error(refusal)
 }
 
 // Recording a review round as a prose request leaves the recurrence ledger blind whenever it is

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

@@ -4,9 +4,11 @@ import {
 	DEFAULT_STABLE_READS,
 	git_pr_checks,
 	WATCH_CONFIRMED_STABLE_READS,
+	type SnapshotObserver,
 } from '#scripts/gh/git-pr-checks'
 import { is_coderabbit_check } from '#scripts/gh/git-pr-checks-eval'
 import { CHECK_STATUS_PASS, type PrStateSnapshot } from '#scripts/gh/git-pr-checks-parse'
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 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
@@ -75,12 +77,15 @@ async function handle_watch_failure(branch_name: string, error: unknown): Promis
 // reads the wait still needs. A timed-out watch (`timed_out: true`) never spanned the pending→settled
 // window, so it must keep the full stable-read window rather than claim the confirmation. A rethrown
 // failure — the empty-rollup case — never reaches a caller, so it needs no answer here.
-async function watch_before_polling(branch_name: string): Promise<boolean> {
+async function watch_before_polling(
+	branch_name: string,
+	observe: SnapshotObserver | undefined,
+): Promise<boolean> {
 	console.info('')
 	console.info('📊 Watching PR checks...')
 
 	try {
-		const result = await git_gh_command.pr_checks_watch(branch_name)
+		const result = await git_gh_command.pr_checks_watch(branch_name, observe)
 
 		return !result.timed_out
 	} catch (error) {
@@ -95,14 +100,23 @@ async function watch_before_polling(branch_name: string): Promise<boolean> {
 // 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
 // caught: the poll evaluates the full merge gate and throws on failure before any stable read counts.
+// `observe` is shown each poll's snapshot, the watch's included — the run's `pr-checks` line
+// (joshuafolkken/kit#3770).
 async function run_checks(input: {
 	branch_name: string
 	is_skip_watch: boolean
+	observe?: SnapshotObserver
 }): Promise<PrStateSnapshot> {
-	const is_watch_confirmed = !input.is_skip_watch && (await watch_before_polling(input.branch_name))
+	const is_watch_confirmed =
+		!input.is_skip_watch && (await watch_before_polling(input.branch_name, input.observe))
 	const stable_reads = is_watch_confirmed ? WATCH_CONFIRMED_STABLE_READS : DEFAULT_STABLE_READS
 
-	return await git_pr_checks.wait_for_pr_success(input.branch_name, stable_reads)
+	return await git_pr_checks.wait_for_pr_success(
+		input.branch_name,
+		stable_reads,
+		issue_watch_gate.assert_read_here,
+		input.observe,
+	)
 }
 
 // Temporary: record every CodeRabbit check that was not passing when the merge gate

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

@@ -1,5 +1,6 @@
 import { epic_close } from '#scripts/epic/epic-close'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_watch_gate } from '#scripts/issue/issue-watch-gate'
 import { git_notify, type GitNotifyConfig } from '#scripts/notify/git-notify'
 import { git_followup_cleanup } from './git-followup-cleanup'
 import { git_followup_issue_close } from './git-followup-issue-close'
@@ -232,8 +233,12 @@ async function run_tail_steps(input: WrapupInput): Promise<void> {
 	])
 }
 
+// The last look at the issue before the merge: the CI poll checked it on every iteration, but a
+// person's update can land between that poll and this step, and only the seconds after this read are
+// left unwatched.
 async function run_wrapup(input: WrapupInput, log: StageLog): Promise<void> {
 	if (input.should_merge && input.is_merged !== true) {
+		await issue_watch_gate.assert_read_here()
 		await git_gh_command.pr_merge(input.branch_name)
 		lap(log, STAGE.merge)
 	}

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

@@ -10,6 +10,7 @@ import {
 	type TelegramSendInput,
 	type TelegramTaskType,
 } from '#scripts/notify/telegram-notify'
+import { followup_checks_event } from './followup-checks-event'
 import { git_followup_merged } from './git-followup-merged'
 import { git_followup_pending } from './git-followup-pending'
 import { git_followup_stages, type StageLog } from './git-followup-stages'
@@ -229,6 +230,7 @@ async function run_review_checks(
 	input: FollowupInput,
 	context: TelegramContext,
 	log: StageLog,
+	issue_number: string | undefined,
 ): Promise<{ notes: Array<string>; managed: Array<string> }> {
 	if (input.is_merged === true) return { notes: [], managed: [] }
 
@@ -238,6 +240,7 @@ async function run_review_checks(
 	const snapshot = await run_checks({
 		branch_name: input.branch_name,
 		is_skip_watch: input.is_skip_watch,
+		observe: followup_checks_event.observer_of(issue_number, context.pr_url),
 	})
 
 	lap(log, STAGE.checks_wait)
@@ -278,7 +281,7 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 	const { issue_number, closes_number, context } = await read_run_context(input)
 
 	lap(log, STAGE.closes_and_context)
-	const checks = await run_review_checks(input, context, log)
+	const checks = await run_review_checks(input, context, log, issue_number)
 	const is_completion_recorded = await notify_unless_recorded(input, issue_number, context, checks)
 
 	lap(log, STAGE.telegram)