@joshuafolkken/kit 1.1387.0 → 1.1453.0

package/scripts/fresh-machine/specs/kit-test-backlogrun.json

@@ -0,0 +1,31 @@
+{
+	"name": "kit-test-backlogrun",
+	"requires_github": true,
+	"package_source": "tarball",
+	"requires_claude": true,
+	"files": {
+		"index.html": "<!doctype html><html><body><h1>Hello</h1></body></html>\n"
+	},
+	"commands": [
+		"gh auth setup-git",
+		"git config --global user.name kit-test && git config --global user.email kit-test@example.com",
+		"printf '{ \"private\": true }\\n' > package.json",
+		"cp \"$PACKAGE_TARBALL\" . && pnpm add -D --allow-build=esbuild --allow-build=unrs-resolver \"./$(basename \"$PACKAGE_TARBALL\")\"",
+		"pnpm exec josh start --yes --github",
+		"gh label list --limit 100 --json name --jq '.[].name' > \"$HOME/labels.txt\"; grep -xE 'auto-ok|needs-decision|needs-human-review|already-done|review-round2-skipped|bug' \"$HOME/labels.txt\"; test \"$(grep -cxE 'auto-ok|needs-decision|needs-human-review|already-done|review-round2-skipped|bug' \"$HOME/labels.txt\")\" -eq 6",
+		"curl -fsSL https://claude.ai/install.sh | bash && export PATH=\"$HOME/.local/bin:$PATH\" && claude --version",
+		"gh issue create --title 'Add a heading to index.html' --body 'Add an h2 under the h1.' --label auto-ok --label run:lane",
+		"timeout 60 pnpm josh backlogrun > \"$HOME/backlogrun.out\" 2>&1; cat \"$HOME/backlogrun.out\"; grep -q '^backlogrun: started' \"$HOME/backlogrun.out\"",
+		"pnpm josh run:event --from 0 | grep 'starting session'",
+		"for i in $(seq 1 90); do pnpm josh run:event --from 0 | grep -q 'dispatching' && break; sleep 10; done; pnpm josh run:event --from 0 | grep 'dispatching'",
+		"for i in $(seq 1 120); do test \"$(gh pr list --state all --json number --jq length)\" -gt 0 && break; sleep 10; done; pnpm josh run:board --chat",
+		"pnpm josh backlogrun --stop"
+	],
+	"probes": [
+		"tail -n 40 \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\" | cut -c1-400",
+		"grep -c 'requires approval' \"$(sed -n 's/^backlogrun: started.*; log //p' \"$HOME/backlogrun.out\")\"",
+		"tail -n 40 /tmp/josh-lane-dispatch-*.log | cut -c1-400",
+		"cat /tmp/josh-lane-dispatch-*.log | grep -c 'requires approval'",
+		"gh pr list --state all"
+	]
+}

package/scripts/gate/gate-report.ts

@@ -2,6 +2,7 @@ import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { josh_verdict } from '#scripts/josh/josh-verdict'
 import { buffered_process, type BufferedProcessResult } from '#scripts/lib/buffered-process'
 import { status_icons } from '#scripts/lib/status-icons'
+import { NOT_USED_MARKER, NOTHING_TO_CHECK_MARKER } from '#scripts/test/skip-marker'
 import { test_unit_guard } from '#scripts/test/test-unit-guard'
 import { gate_log } from './gate-log'
 import { gate_plan } from './gate-plan'
@@ -11,7 +12,7 @@ import { gate_plan } from './gate-plan'
 // about what is printed changes in the move: the four blocks, the log notice and the verdict come out
 // exactly as before, with one addition — the per-failure action lines below.
 
-const { FAIL_ICON, PASS_ICON } = status_icons
+const { FAIL_ICON, PASS_ICON, WARN_ICON } = status_icons
 
 interface GateStep {
 	label: string
@@ -76,16 +77,56 @@ function has_warnings(result: GateStepResult): boolean {
 // other line still withholds.
 const SAFE_CHAIN_BANNER = 'safe-chain is not available'
 
+function checker_lines(result: GateStepResult): ReadonlyArray<string> {
+	return result.output.split('\n').filter((line) => !line.includes(SAFE_CHAIN_BANNER))
+}
+
 function has_checker_warning(result: GateStepResult): boolean {
 	if (!gate_plan.WARNING_CHECKER_LABELS.includes(result.label)) return false
 
-	return result.output
-		.split('\n')
-		.some(
-			(line) =>
-				!line.includes(SAFE_CHAIN_BANNER) &&
-				WARNING_MARKERS.some((marker) => line.includes(marker)),
-		)
+	return checker_lines(result).some((line) =>
+		WARNING_MARKERS.some((marker) => line.includes(marker)),
+	)
+}
+
+// The record's counterpart to `is_skip_notice`, narrower for the reason `has_checker_warning` is
+// narrower than `has_warnings`: a skip of a tool the project does not use (`NOT_USED_MARKER`) left
+// nothing unverified, so only another skip line withholds the green record.
+function is_unverified_skip(result: GateStepResult): boolean {
+	return checker_lines(result).some(
+		(line) => line.includes(test_unit_guard.SKIP_MARKER) && !line.includes(NOT_USED_MARKER),
+	)
+}
+
+// **A check the verdict counts as skipped said nothing but that it checked nothing.** `is_skip_notice`
+// asks whether a check carries a skip notice, which is the right question for printing its body; it is
+// the wrong one for a count, twice over. A check can skip half of
+// itself — a `basic` project's `lint` runs Prettier and skips eslint — and calling it skipped would
+// have the verdict say nothing ran on a gate that checked the formatting. And a check can run with
+// nothing of the project's to look at — `exports` in a consumer, `behavior` with no transcript — which
+// is no skip, and still left an empty `basic` project reading `2 ran`. A line that is neither notice is
+// something a tool printed, so the check ran. A tool that ran clean and silent beside a skipped one is
+// given a line of its own by the check (`project_checks.ran_notice`), so the reading holds for it too.
+//
+// **pnpm's script header is not something the check printed.** Every check is spawned as
+// `pnpm josh <target>`, and where the project declares a `josh` script — `josh init` writes one — pnpm
+// opens the captured output with `$ josh <target>`. Counted as a line, it made every spawned check one
+// that ran, and `not verified` unreachable in the very project it was written for.
+const IDLE_MARKERS: ReadonlyArray<string> = [test_unit_guard.SKIP_MARKER, NOTHING_TO_CHECK_MARKER]
+const PNPM_SCRIPT_HEADER = '$ '
+
+function is_idle_line(line: string): boolean {
+	return IDLE_MARKERS.some((marker) => line.includes(marker))
+}
+
+function is_tool_line(line: string): boolean {
+	return line.trim() !== '' && !line.startsWith(PNPM_SCRIPT_HEADER)
+}
+
+function is_idle(result: GateStepResult): boolean {
+	const lines = checker_lines(result).filter((line) => is_tool_line(line))
+
+	return lines.length > 0 && lines.every((line) => is_idle_line(line))
 }
 
 function should_print_body(result: GateStepResult, is_verbose: boolean): boolean {
@@ -144,10 +185,7 @@ function format_failure_actions(failed: ReadonlyArray<GateStepResult>): string {
 
 // **A check that started past the core budget is said in the summary, not only in the log**.
 // The wait cap admits a check that waited two minutes whatever the budget says,
-// so a gate that ran over-subscribed would otherwise look exactly like one that fitted. The icon is
-// local rather than in `status-icons.ts` because nothing reads this line back.
-const WARN_ICON = '⚠'
-
+// so a gate that ran over-subscribed would otherwise look exactly like one that fitted.
 function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
 	const lines = results.flatMap((result) =>
 		result.budget_note === undefined
@@ -158,6 +196,24 @@ function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
 	return lines.length === 0 ? '' : `${lines.join('\n')}\n`
 }
 
+// **The verdict counts what ran apart from what was skipped, and a gate that ran nothing does not say
+// `passed`.** It printed the planned number of checks whatever happened to them, so a `basic` project
+// whose every check skipped read `passed (6 checks)` — the same last line as a gate that ran them all,
+// and the skip this module keeps visible in the bodies was invisible in the one line a `tail` keeps.
+//
+// **A gate with no skip keeps the line it always printed.** A check with nothing to check is counted
+// apart only beside a skip: `exports` says so in every consumer, and counting it alone would reword the
+// verdict of every gate that skipped nothing.
+function format_green_verdict(results: ReadonlyArray<GateStepResult>, total: string): string {
+	const has_skip = results.some((result) => is_skip_notice(result))
+	const skipped = has_skip ? results.filter((result) => is_idle(result)).length : 0
+	const ran = results.length - skipped
+
+	if (ran === 0) return josh_verdict.format_gate_unverified(skipped, total)
+
+	return josh_verdict.format_gate_passed({ ran, skipped }, total)
+}
+
 // The total is wall-clock for the whole command, not the sum of the four — they run concurrently,
 // so a sum would report about three times what the caller waited.
 //
@@ -172,7 +228,7 @@ function print_gate_summary(
 	const total = format_seconds(report.elapsed_ms)
 	const verdict =
 		failed.length === 0
-			? josh_verdict.format_gate_passed(report.step_count, total)
+			? format_green_verdict(results, total)
 			: josh_verdict.format_gate_failed(failed.map((result) => result.label).join(', '), total)
 	const notes = format_budget_notes(results)
 
@@ -185,7 +241,6 @@ interface GateReport {
 	is_verbose: boolean
 	log_path: string | undefined
 	elapsed_ms: number
-	step_count: string
 }
 
 // Everything a finished run says, in the order a reader meets it: the four blocks, then the log the
@@ -213,7 +268,7 @@ const gate_report = {
 	format_failure_actions,
 	has_checker_warning,
 	is_gate_step_failed,
-	is_skip_notice,
+	is_unverified_skip,
 	report_gate_steps,
 }
 

package/scripts/gate/project-checks.ts

@@ -2,10 +2,11 @@ import { existsSync, globSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { own_formatter } from '#scripts/init/own-formatter'
 import { project_profile } from '#scripts/init/project-profile'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
-import { SKIP_MARKER } from '#scripts/test/skip-marker'
+import { NOT_USED_MARKER, SKIP_MARKER } from '#scripts/test/skip-marker'
 import { z } from 'zod'
 
 const PACKAGE_JSON = 'package.json'
@@ -126,8 +127,17 @@ function missing_tool_reason(
 	return `${package_name} is not installed`
 }
 
+// Every skip reason here names a tool the project does not use — undeclared, or with no files or no
+// configuration to read — so the notice says so (`NOT_USED_MARKER`).
 function skip_notice(check: string, reason: string): string {
-	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}.`
+	return `josh ${check}: ${reason} ${SKIP_MARKER} ${check}, ${NOT_USED_MARKER}.`
+}
+
+// **A tool that ran clean beside a skipped one says that it ran.** A clean eslint prints nothing, so a
+// `lint` whose Prettier was skipped read as nothing but a skip notice — the same output as a `lint`
+// that ran neither — and the gate's verdict counted a check that linted the whole tree as skipped.
+function ran_notice(check: string): string {
+	return `josh ${check}: ran and reported no problems.`
 }
 
 // Shared by `josh check` and the gate's type-check step, so neither reaches `tsc` on a basic
@@ -141,10 +151,12 @@ function type_check_skip_reason(directory: string): string | undefined {
 }
 
 // Shared by `josh lint`, `josh lint:related` and `josh format`, so a basic project without Web
-// files — a Python or Rust project, which `josh init` gives no Prettier — is skipped for the same
-// reason by all three.
+// files — a Python or Rust project, which `josh init` gives no Prettier — or with a formatter of its
+// own is skipped for the same reason by all three.
 function prettier_skip_reason(directory: string): string | undefined {
 	if (!is_basic(directory)) return undefined
+	const formatter = own_formatter.find_config(project_root(directory))
+	if (formatter !== undefined) return `${formatter} configures the project's own formatter`
 	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
 
 	return missing_tool_reason(directory, 'prettier', 'prettier')
@@ -173,6 +185,8 @@ const project_checks = {
 	is_kit_repository,
 	prettier_skip_reason,
 	project_root,
+	ran_notice,
+	read_manifest,
 	skip_notice,
 	type_check_skip_reason,
 }

package/scripts/gate/scoped-green.ts

@@ -64,7 +64,8 @@ interface ScopedSources {
 }
 
 // **`test:related` is required only where it can ever answer**. In a project
-// whose unit guard skips — vitest absent, or a basic project with no test file — `test:related` runs
+// whose unit guard skips — vitest absent with no project test script to run in its place, or a basic
+// project with no test file — `test:related` runs
 // nothing and so writes no record, and requiring one refused the gate forever with no way through.
 // The guard's own decision is asked rather than re-derived, so the writer and this reader agree; a
 // project with a unit suite still needs the record, and a run that executed nothing still writes none.

package/scripts/gate/verification-gate.ts

@@ -63,7 +63,9 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // passed *without running* — `test-unit-guard` exits 0 with a notice when vitest is absent or the
 // project has no tests — must not become "the unit tests all passed": the gate keeps that skip
 // visible on the console, and a record erasing it would have the brief tell a review agent not to
-// re-run tests that never ran. A step that passed **with a checker's warnings** is withheld for the
+// re-run tests that never ran. A skip of a tool the project does not use (`NOT_USED_MARKER` — eslint
+// with no ESLint configuration) is not one: nothing went unverified, so it withholds nothing
+// (`gate_report.is_unverified_skip`). A step that passed **with a checker's warnings** is withheld for the
 // same reason one place further on: since the record is reused instead of the checks being re-run, a
 // warning printed once would never be printed again on that tree, and hiding an eslint or
 // svelte-check finding is the same failure as hiding a skip. It is `has_checker_warning`, not
@@ -80,7 +82,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // The destination is a parameter so a test can exercise the record without overwriting the one a
 // real run may be relying on — `josh gate` and `josh review:brief` share one path by design.
 function has_nothing_to_say(result: GateStepResult): boolean {
-	return !gate_report.is_skip_notice(result) && !gate_report.has_checker_warning(result)
+	return !gate_report.is_unverified_skip(result) && !gate_report.has_checker_warning(result)
 }
 
 async function record_green_gate(
@@ -362,7 +364,6 @@ async function settle_gate(
 		is_verbose: options.is_verbose ?? false,
 		log_path: options.log_path,
 		elapsed_ms,
-		step_count: String(plan.checks.length),
 	})
 	const is_passed = failed_labels.length === 0
 

package/scripts/gh/gh-author-association.ts

@@ -0,0 +1,14 @@
+// Whose words kit acts on: the `author_association` REST reports with an issue or a comment, and the
+// ones that can write to the repository. On a public repository anyone can file an issue or comment,
+// so a body kit runs (`josh measure:rerun`) or copies into the ledger (`review:record`) is taken only
+// from an author with write access — and an unknown author is not a trusted one.
+const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
+const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
+
+function is_trusted(association: string | null | undefined): boolean {
+	return typeof association === 'string' && TRUSTED_ASSOCIATIONS.has(association)
+}
+
+const gh_author_association = { TRUSTED_LIST, is_trusted }
+
+export { gh_author_association }

package/scripts/gh/git-gh-conditional.ts

@@ -0,0 +1,66 @@
+import { git_gh_exec, has_stdout_field } from './git-gh-exec'
+
+// A `gh api` GET that sends the ETag of the previous answer, so a resource polled every few minutes
+// costs nothing when it has not changed: GitHub answers `304 Not Modified` to a matching
+// `If-None-Match`, and a conditional request answered 304 does not count against the rate limit.
+//
+// **`gh` exits non-zero on a 304** (it prints `gh: HTTP 304`), so the "unchanged" answer arrives as
+// a thrown failure. The status is read off the `--include` status line the failure still carries in
+// its stdout — the same reading `exec_gh_api_status` makes — never off the stderr wording.
+
+const NOT_MODIFIED_STATUS = 304
+const OK_STATUS = 200
+const INCLUDE_FLAG = '--include'
+const HEADER_FLAG = '-H'
+const IF_NONE_MATCH = 'If-None-Match: '
+const HEADER_BODY_SEPARATOR = /\r?\n\r?\n/u
+const ETAG_HEADER = /^etag: *(?<etag>[^\r\n]+)/imu
+
+type ConditionalRead =
+	| { kind: 'unchanged' }
+	| { kind: 'changed'; etag: string | undefined; body: string }
+	| { kind: 'unreadable' }
+
+const UNCHANGED: ConditionalRead = { kind: 'unchanged' }
+const UNREADABLE: ConditionalRead = { kind: 'unreadable' }
+
+function to_args(path: string, etag: string | undefined): Array<string> {
+	const header = etag === undefined ? [] : [HEADER_FLAG, `${IF_NONE_MATCH}${etag}`]
+
+	return ['api', INCLUDE_FLAG, ...header, path]
+}
+
+// The headers and the body of an `--include` answer, split at the first blank line.
+function to_changed(output: string): ConditionalRead {
+	const [headers = '', ...rest] = output.split(HEADER_BODY_SEPARATOR)
+	const etag = ETAG_HEADER.exec(headers)?.groups?.['etag']
+
+	return { kind: 'changed', etag, body: rest.join('\n\n') }
+}
+
+function to_read(output: string): ConditionalRead {
+	return git_gh_exec.parse_status_line(output) === OK_STATUS ? to_changed(output) : UNREADABLE
+}
+
+function failure_status(error: unknown): number | undefined {
+	const cause = error instanceof Error ? error.cause : undefined
+
+	return has_stdout_field(cause) ? git_gh_exec.parse_status_line(cause.stdout) : undefined
+}
+
+async function read_conditional(
+	path: string,
+	etag: string | undefined,
+	timeout_ms?: number,
+): Promise<ConditionalRead> {
+	try {
+		return to_read(await git_gh_exec.exec_gh_command(to_args(path, etag), timeout_ms))
+	} catch (error) {
+		return failure_status(error) === NOT_MODIFIED_STATUS ? UNCHANGED : UNREADABLE
+	}
+}
+
+const git_gh_conditional = { read_conditional, to_args }
+
+export type { ConditionalRead }
+export { git_gh_conditional }

package/scripts/gh/git-gh-exec.ts

@@ -288,7 +288,7 @@ interface GhApiRequest {
 	// second argument for the reason recorded beside that constant. `0` is
 	// execa's own "no budget", kept for the one reader whose caller's writes depend on the answer
 	// (`gh-spawn.ts`).
-	timeout_ms?: number
+	timeout_ms?: number | undefined
 	// The checkout gh runs in, which is what `{owner}/{repo}` in `path` resolves against. Absent means
 	// the process's own directory.
 	cwd?: string

package/scripts/gh/git-gh-issue-read.ts

@@ -350,11 +350,14 @@ async function issue_get_labels_and_body(issue_number: string): Promise<string |
 // No `repo` parameter, unlike the reads above: the auto-close lists its candidate epics from the
 // repository it runs in, so the epic whose comments are read is always a local one. The path builder
 // takes one when a caller that needs it appears.
-async function issue_list_comments(issue_number: string): Promise<string | undefined> {
+async function issue_list_comments(
+	issue_number: string,
+	timeout_ms?: number,
+): Promise<string | undefined> {
 	const path = `${git_gh_api_path.issue_comments_api_path(issue_number)}${git_gh_api_path.FULL_PAGE_QUERY}`
 
 	try {
-		return await git_gh_exec.exec_gh_api({ path, should_paginate: true })
+		return await git_gh_exec.exec_gh_api({ path, should_paginate: true, timeout_ms })
 	} catch {
 		return undefined
 	}
@@ -436,5 +439,5 @@ const git_gh_issue_read = {
 	issue_list_comments,
 }
 
-export type { IssueRead, IssueReadFailure }
+export type { IssueRead, IssueReadFailure, IssueReadReason }
 export { git_gh_issue_read, read_blocked_by, NOT_FOUND_STATUS }

package/scripts/gh/git-gh-issue-rest.ts

@@ -71,6 +71,7 @@ const REST_FIELD_NAMES = new Map<string, string>([
 	['url', 'html_url'],
 	['createdAt', 'created_at'],
 	['closedAt', 'closed_at'],
+	['updatedAt', 'updated_at'],
 ])
 
 const NOT_AN_ISSUE_MESSAGE = 'gh api answered something other than an issue object'

package/scripts/gh/git-gh-issue-write.ts

@@ -1,3 +1,4 @@
+import { issue_watch_diff } from '#scripts/issue/issue-watch-diff'
 import { session_cite } from '#scripts/issue/session-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { git_gh_api_path } from './git-gh-api-path'
@@ -64,10 +65,13 @@ async function issue_edit_body(issue_number: string, body: string): Promise<stri
 	})
 }
 
+// **Every comment josh posts carries `RUN_MARKER`**, an HTML comment GitHub does not render. A run
+// posts under the person's own `gh` login, so the marker is the only thing that tells the issue watch
+// (`issue-watch-diff.ts`) a run's comment from a person's update.
 async function issue_comment(issue_number: string, body: string): Promise<string> {
 	return await git_gh_exec.exec_gh_api({
 		path: `${git_gh_api_path.issue_api_path(issue_number)}${COMMENTS_SEGMENT}`,
-		body: JSON.stringify({ body }),
+		body: JSON.stringify({ body: `${body}\n\n${issue_watch_diff.RUN_MARKER}` }),
 		jq_filter: HTML_URL_FILTER,
 	})
 }

package/scripts/gh/git-gh-issue.ts

@@ -14,7 +14,10 @@ const NUMBER_AND_BODY_FIELDS = 'number,body'
 // tell a row with no blockers from one with some **before** deciding whether that row is worth a
 // per-issue read, which would otherwise be made for every open issue in the repository. Absent on a
 // row whose summary is missing, which must not be read as zero; `git-gh-issue-rest.ts` states why.
-const BACKLOG_SCAN_FIELDS = `number,title,body,${BLOCKED_BY_COUNT_FIELD}`
+//
+// `labels` rides along on the same response too: `epic:bundle` reads the release label off it,
+// because the release issue's blockers are recorded mechanically and signal no shared work.
+const BACKLOG_SCAN_FIELDS = `number,title,body,labels,${BLOCKED_BY_COUNT_FIELD}`
 // The recently-closed scan's fields. It compares titles like the scan above
 // and never reads a body, and it needs the labels to tell an epic from a deliverable — the open half
 // gets that from the epic listing, which by construction holds no closed epic.
@@ -147,6 +150,14 @@ async function issue_list_by_label_in_repo(
 	return await issue_list({ json_fields: SUMMARY_FIELDS, limit, label, repo })
 }
 
+// Every open issue with what `josh auto-ok:judge` judges it by — its labels and body — and `updatedAt`,
+// so the backlog driver's resident check reads an issue's comments again only once it has moved.
+const JUDGEMENT_FIELDS = 'number,title,body,labels,updatedAt'
+
+async function issue_list_open_for_judgement(limit: number): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: JUDGEMENT_FIELDS, limit })
+}
+
 const git_gh_issue = {
 	...git_gh_issue_read,
 	...git_gh_issue_write,
@@ -156,6 +167,7 @@ const git_gh_issue = {
 	issue_list_by_label_summary,
 	issue_search_body,
 	issue_list_open_bodies,
+	issue_list_open_for_judgement,
 	issue_list_recently_closed,
 }
 

package/scripts/gh/git-pr-checks-eval.ts

@@ -119,6 +119,18 @@ function is_coderabbit_check(check_name: string): boolean {
 	return is_required_match(check_name, CODERABBIT_CHECK_NAME)
 }
 
+// CodeRabbit reports a rate-limited review as a *passing* status whose description says so
+// (`Review rate limited`), so only the description tells it from a finished review
+// (joshuafolkken/kit#3770).
+const CODERABBIT_RATE_LIMIT_DESCRIPTION = /rate limit/iu
+
+function is_coderabbit_rate_limited(check: RollupCheck): boolean {
+	return (
+		is_coderabbit_check(check.name) &&
+		CODERABBIT_RATE_LIMIT_DESCRIPTION.test(check.description ?? '')
+	)
+}
+
 // Temporary: a pending or failing CodeRabbit check makes GitHub report UNSTABLE even
 // though CodeRabbit is not required. Accept that state only when CodeRabbit checks are the
 // sole non-passing ones — any other non-passing check keeps the gate strict.
@@ -249,6 +261,7 @@ export {
 	is_review_decision_decisive,
 	read_required_statuses,
 	is_coderabbit_check,
+	is_coderabbit_rate_limited,
 	collect_blocking_failures,
 	describe_pr_failure,
 	REQUIRED_CHECKS,

package/scripts/gh/git-pr-checks-parse.ts

@@ -31,10 +31,14 @@ const KEY_STATUS = 'status'
 const KEY_CONCLUSION = 'conclusion'
 const KEY_NAME = 'name'
 const KEY_CONTEXT = 'context'
+const KEY_DESCRIPTION = 'description'
 
 interface RollupCheck {
 	name: string
 	status: string
+	// A status context's own words — CodeRabbit says `Review rate limited` under a `success` state
+	// (joshuafolkken/kit#3770). Absent where the check carries none.
+	description?: string
 }
 
 interface PrStateSnapshot {
@@ -95,7 +99,10 @@ function parse_rollup_item(item: RollupItemData): RollupCheck | undefined {
 	const name = read_string(item[KEY_NAME]) ?? read_string(item[KEY_CONTEXT])
 	if (name === undefined) return undefined
 
-	return { name, status: parse_rollup_status(item) }
+	const check = { name, status: parse_rollup_status(item) }
+	const description = read_string(item[KEY_DESCRIPTION])
+
+	return description === undefined ? check : { ...check, description }
 }
 
 function parse_rollup_checks(raw_json: string): Array<RollupCheck> {

package/scripts/gh/git-pr-checks-watch.ts

@@ -4,9 +4,11 @@ import {
 	default_fetch_pr_state,
 	DEFAULT_STABLE_READS,
 	is_pr_checks_timeout,
+	observed_fetcher,
 	SECONDS_TO_MS,
 	wait_for_pr_success,
 	type PrStateEvaluator,
+	type SnapshotObserver,
 } from './git-pr-checks'
 import { is_coderabbit_check, is_required_check, type PrEvaluation } from './git-pr-checks-eval'
 import {
@@ -125,10 +127,12 @@ const CHECKS_SETTLED_EVALUATOR: PrStateEvaluator = {
 	should_read_review_decision: should_never_read_review_decision,
 }
 
-async function watch_until_settled(branch_name: string): Promise<void> {
+// `observe` sees the watch's polls too, so a red wait's checks line is replaced while the new CI is
+// still pending rather than only after the watch (joshuafolkken/kit#3770).
+async function watch_until_settled(branch_name: string, observe?: SnapshotObserver): Promise<void> {
 	await wait_for_pr_success({
 		branch_name,
-		fetcher: default_fetch_pr_state,
+		fetcher: observed_fetcher(observe),
 		interval_ms: CHECK_WAIT_INTERVAL_MS,
 		max_attempts: compute_max_attempts(
 			PR_CHECKS_WATCH_TIMEOUT_MS / SECONDS_TO_MS,
@@ -154,9 +158,12 @@ async function fail_when_no_checks(branch_name: string): Promise<void> {
 // Everything else — a failing check, an unreadable read, a branch with no checks — is rethrown, which
 // is what the caller already handles: `git-pr-followup.ts` swallows it and falls through to its own
 // poll.
-async function pr_checks_watch(branch_name: string): Promise<WatchResult> {
+async function pr_checks_watch(
+	branch_name: string,
+	observe?: SnapshotObserver,
+): Promise<WatchResult> {
 	try {
-		await watch_until_settled(branch_name)
+		await watch_until_settled(branch_name, observe)
 
 		return { timed_out: false }
 	} catch (error) {

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

@@ -128,6 +128,9 @@ interface WaitForPrSuccessOptions {
 	max_attempts: number
 	required_stable_reads: number
 	evaluator?: PrStateEvaluator
+	// Asked before every poll; a throw ends the wait with that error. `josh followup` stops here on a
+	// person's unread issue update (`issue-watch-gate.ts`).
+	before_poll?: (() => Promise<void>) | undefined
 }
 
 function parse_repo_name_from_package(package_json_content: string): string {
@@ -272,6 +275,8 @@ async function wait_for_pr_success(options: WaitForPrSuccessOptions): Promise<Pr
 
 	for (let attempt = 0; attempt < options.max_attempts; attempt += 1) {
 		console.info(`Checking PR status… (${String(attempt + 1)}/${String(options.max_attempts)})`)
+		// eslint-disable-next-line no-await-in-loop -- polling: the check belongs to this poll, not to all of them at once
+		await options.before_poll?.()
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		carried = await attempt_pr_success_poll({
 			options,
@@ -311,16 +316,38 @@ async function default_fetch_pr_state(
 // **`required_stable_reads` is a parameter, not a constant, so the caller can lower it** — `run_checks`
 // passes `WATCH_CONFIRMED_STABLE_READS` when the watch already confirmed completion. It defaults to
 // `DEFAULT_STABLE_READS`, so every caller that names only the branch is exactly where it was.
+// What a caller is shown of each poll it waits on — `followup` reports the checks to the run's event
+// stream from it (joshuafolkken/kit#3770). It decides nothing: the wait reads the same snapshot.
+type SnapshotObserver = (snapshot: PrStateSnapshot) => Promise<void>
+
+function observed_fetcher(observe: SnapshotObserver | undefined): PrStateFetcher {
+	if (observe === undefined) return default_fetch_pr_state
+
+	return async function fetch_observed(
+		branch_name: string,
+		should_read_review_decision: ReviewDecisionPredicate,
+	): Promise<PrStateSnapshot> {
+		const snapshot = await default_fetch_pr_state(branch_name, should_read_review_decision)
+
+		await observe(snapshot)
+
+		return snapshot
+	}
+}
+
 async function wait_for_pr_success_default(
 	branch_name: string,
 	required_stable_reads: number = DEFAULT_STABLE_READS,
+	before_poll?: () => Promise<void>,
+	observe?: SnapshotObserver,
 ): Promise<PrStateSnapshot> {
 	return await wait_for_pr_success({
 		branch_name,
-		fetcher: default_fetch_pr_state,
+		fetcher: observed_fetcher(observe),
 		interval_ms: CHECK_WAIT_INTERVAL_MS,
 		max_attempts: CHECK_MAX_ATTEMPTS,
 		required_stable_reads,
+		before_poll,
 	})
 }
 
@@ -383,10 +410,17 @@ export {
 	SECONDS_TO_MS,
 	is_pr_checks_timeout,
 	default_fetch_pr_state,
+	observed_fetcher,
 	MERGE_GATE_EVALUATOR,
 	should_always_read_review_decision,
 }
-export type { MergeProgress, PrStateFetcher, PrStateEvaluator, ReviewDecisionPredicate }
+export type {
+	MergeProgress,
+	PrStateFetcher,
+	PrStateEvaluator,
+	ReviewDecisionPredicate,
+	SnapshotObserver,
+}
 export {
 	collect_blocking_failures,
 	describe_pr_failure,