@joshuafolkken/kit 1.1471.0 → 1.1784.0

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,
 }
 

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

@@ -2,15 +2,14 @@
 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'
+import { acceptance_map_check } from '#scripts/review/acceptance-map-check'
 import { live_evidence } from '#scripts/review/live-evidence'
-import { review_attest } from '#scripts/review/review-attest'
-import { review_record } from '#scripts/review/review-record'
+import { removed_tests_check } from '#scripts/review/removed-tests-check'
 import { parse_issue_number_from_text } from './followup-issue-number'
+import { followup_review_gates } from './followup-review-gates'
 import { git_followup_finish } from './git-followup-finish'
 import { git_followup_flush } from './git-followup-flush'
 import { git_followup_merged, type MergePlan } from './git-followup-merged'
@@ -120,78 +119,48 @@ function is_merge_resolved(values: CliArguments['values']): boolean {
 	return values['no-merge'] !== true
 }
 
-// `/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): boolean {
-	return issue_number !== undefined && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
-}
+const { assert_review_attested, assert_review_recorded, is_valid_issue } = followup_review_gates
 
-async function assert_review_attested(should_merge: boolean): Promise<void> {
+// A runtime change merges only with its acceptance criteria run for real and
+// recorded in the pull request body — `live_evidence` carries the why. `exempt` (no runtime path
+// changed) merges as before, and a `--no-merge` run has not reached the gate at all.
+async function assert_live_evidence(should_merge: boolean, branch_name: string): Promise<void> {
 	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 verdict = await live_evidence.check(branch_name)
 
-	const refusal = await issue_watch_gate.review_refusal_here()
+	if (verdict !== 'required') return
 
-	if (refusal !== undefined) throw new Error(refusal)
+	throw new Error(live_evidence.refusal_message())
 }
 
-// Recording a review round as a prose request leaves the recurrence ledger blind whenever it is
-// skipped. **This is the seam where it is a gate instead**: a merge is refused unless the round left
-// a `- rf:` line for its issue, a zero-finding `none` line included.
-//
-// **Absence is a refusal, `missing` exactly as `assert_review_attested`'s is** — the defect this
-// exists for 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(
+// Every acceptance criterion the Issue carries at the merge maps to a row in the pull request body —
+// `acceptance_map` carries the why. Re-read here rather than at the commit, so a criterion added
+// during the review is refused too. A run whose issue it cannot identify has no criteria to read.
+async function assert_acceptance_mapped(
 	should_merge: boolean,
 	issue_number: string | undefined,
+	branch_name: string,
 ): 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)) return
+	const refusal = await acceptance_map_check.refusal(issue_number, branch_name)
 
-	throw new Error(review_record.refusal_message(issue))
+	if (refusal !== undefined) throw new Error(refusal)
 }
 
-// A runtime change merges only with its acceptance criteria run for real and
-// recorded in the pull request body — `live_evidence` carries the why. `exempt` (no runtime path
-// changed) merges as before, and a `--no-merge` run has not reached the gate at all.
-async function assert_live_evidence(should_merge: boolean, branch_name: string): Promise<void> {
+// Every test the change removes is disposed of in the pull request body — `removed_tests` carries the
+// why. It reads this checkout's diff, which `assert_live_evidence` has already refused to read for a
+// branch other than the one checked out.
+async function assert_removed_tests_disposed(
+	should_merge: boolean,
+	branch_name: string,
+): Promise<void> {
 	if (!should_merge) return
 
-	const verdict = await live_evidence.check(branch_name)
-
-	if (verdict !== 'required') return
+	const refusal = await removed_tests_check.refusal(branch_name)
 
-	throw new Error(live_evidence.refusal_message())
+	if (refusal !== undefined) throw new Error(refusal)
 }
 
 // Every pre-merge refusal, in order — each one throws, so nothing merges past the first that fails.
@@ -203,6 +172,8 @@ async function assert_merge_gates(
 	await assert_review_attested(should_merge)
 	await assert_review_recorded(should_merge, issue_number)
 	await assert_live_evidence(should_merge, branch_name)
+	await assert_acceptance_mapped(should_merge, issue_number, branch_name)
+	await assert_removed_tests_disposed(should_merge, branch_name)
 }
 
 // After the gates, before the CI wait: a line appended since the run's commit rides the pull request
@@ -261,9 +232,9 @@ try {
 }
 
 const git_followup_workflow = {
+	assert_acceptance_mapped,
 	assert_live_evidence,
-	assert_review_attested,
-	assert_review_recorded,
+	assert_removed_tests_disposed,
 	parse_issue_number_from_text,
 	prepare_merge,
 	resolve_branch_name,

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

@@ -1,5 +1,8 @@
 import { epic_close } from '#scripts/epic/epic-close'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { PrStateSnapshot } from '#scripts/gh/git-pr-checks'
+import { git_pr_merge_checked, type WaitForGreen } from '#scripts/gh/git-pr-merge-checked'
+import { issue_body_or_comment } from '#scripts/issue/issue-body-or-comment'
 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'
@@ -40,6 +43,10 @@ interface WrapupInput {
 	// already on the issue does not post it twice (`git-followup-merged.ts`).
 	is_merged?: boolean | undefined
 	is_completion_recorded?: boolean | undefined
+	// The snapshot the merge gate passed, whose head the merge names, and the wait to go back to when
+	// that head moved before the merge (`git-pr-merge-checked.ts`, #4036).
+	checked?: PrStateSnapshot | undefined
+	wait_for_green: WaitForGreen
 }
 
 function build_notify_body(input: {
@@ -57,12 +64,6 @@ function build_notify_body(input: {
 	})
 }
 
-function is_blank_issue_body(body: string | undefined): boolean {
-	if (body === undefined) return true
-
-	return body.trim().length === 0
-}
-
 async function post_notify_issue(input: {
 	issue_number: string | undefined
 	body: string
@@ -71,12 +72,7 @@ async function post_notify_issue(input: {
 		throw new Error('Issue number is required for issue notification.')
 	}
 
-	const current_body = await git_gh_command.issue_get_body(input.issue_number)
-	const should_edit_body = current_body !== undefined && is_blank_issue_body(current_body)
-
-	await (should_edit_body
-		? git_gh_command.issue_edit_body(input.issue_number, input.body)
-		: git_gh_command.issue_comment(input.issue_number, input.body))
+	await issue_body_or_comment.post(input.issue_number, input.body)
 }
 
 function should_notify_pr(target: GitNotifyConfig['target']): boolean {
@@ -239,7 +235,7 @@ async function run_tail_steps(input: WrapupInput): Promise<void> {
 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)
+		await git_pr_merge_checked.merge_checked(input)
 		lap(log, STAGE.merge)
 	}
 
@@ -256,7 +252,6 @@ export {
 	git_pr_followup_wrapup,
 	post_notify_issue,
 	post_completion_notification,
-	is_blank_issue_body,
 	build_notify_body,
 }
 export type { WrapupInput }

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

@@ -1,7 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_pr_ai_review, type TelegramContext } from '#scripts/gh/git-pr-ai-review'
+import type { PrStateSnapshot } from '#scripts/gh/git-pr-checks'
 import { git_pr_coderabbit } from '#scripts/gh/git-pr-coderabbit'
 import { git_pr_managed_config } from '#scripts/gh/git-pr-managed-config'
+import type { WaitForGreen } from '#scripts/gh/git-pr-merge-checked'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
 import type { GitNotifyConfig } from '#scripts/notify/git-notify'
@@ -11,6 +13,7 @@ import {
 	type TelegramTaskType,
 } from '#scripts/notify/telegram-notify'
 import { followup_checks_event } from './followup-checks-event'
+import { followup_coderabbit_wait } from './followup-coderabbit-wait'
 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'
@@ -226,22 +229,45 @@ async function run_comment_scans(
 // different destinations: every note reaches the completion notification, and this one alone also
 // reaches the completion report posted to the Issue. Returning it twice is
 // what lets `run_stages` hand each destination what belongs to it without re-deriving the answer.
+//
+// **The snapshot travels on to the merge**, which names its head, and the same wait is what the merge
+// goes back to when that head moved before it (#4036).
+interface ReviewChecks {
+	notes: Array<string>
+	managed: Array<string>
+	snapshot?: PrStateSnapshot
+}
+
+function wait_for_green_of(
+	input: FollowupInput,
+	context: TelegramContext,
+	issue_number: string | undefined,
+	log: StageLog,
+): WaitForGreen {
+	return async function wait_for_green(): Promise<PrStateSnapshot> {
+		return await run_checks({
+			branch_name: input.branch_name,
+			is_skip_watch: input.is_skip_watch,
+			observe: followup_coderabbit_wait.both(
+				followup_checks_event.observer_of(issue_number, context.pr_url),
+				followup_coderabbit_wait.observer_of(log.coderabbit),
+			),
+		})
+	}
+}
+
 async function run_review_checks(
 	input: FollowupInput,
 	context: TelegramContext,
 	log: StageLog,
 	issue_number: string | undefined,
-): Promise<{ notes: Array<string>; managed: Array<string> }> {
+): Promise<ReviewChecks> {
 	if (input.is_merged === true) return { notes: [], managed: [] }
 
 	const managed = await git_pr_managed_config.handle_managed_config_changes({
 		should_merge: input.should_merge,
 	})
-	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),
-	})
+	const snapshot = await wait_for_green_of(input, context, issue_number, log)()
 
 	lap(log, STAGE.checks_wait)
 	const check_notes = read_coderabbit_skip_notes(snapshot)
@@ -249,7 +275,7 @@ async function run_review_checks(
 	log_skip_notes(check_notes)
 	const scan_notes = await run_comment_scans(input, context, log)
 
-	return { notes: [...managed, ...check_notes, ...scan_notes], managed }
+	return { notes: [...managed, ...check_notes, ...scan_notes], managed, snapshot }
 }
 
 // **A tail re-run after a merge does not report twice**: where the issue
@@ -296,6 +322,8 @@ async function run_stages(input: FollowupInput, log: StageLog): Promise<string |
 			managed_notes: checks.managed,
 			is_merged: input.is_merged,
 			is_completion_recorded,
+			checked: checks.snapshot,
+			wait_for_green: wait_for_green_of(input, context, issue_number, log),
 		},
 		log,
 	)
@@ -319,7 +347,7 @@ async function run(input: FollowupInput): Promise<string | undefined> {
 		throw error
 	} finally {
 		git_followup_stages.print_stages(log)
-		await git_followup_stages.record_ci_wait(log)
+		await git_followup_stages.record_waits(log)
 	}
 }
 

package/scripts/fresh-machine/fresh-machine-cli.ts

@@ -24,7 +24,7 @@ const USAGE =
 	'Usage: josh fresh:run <pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list'
 // The scratch directory kit's distributed `.gitignore` already ignores, so a log is never committed
 // from kit or from a consumer toolkit.
-const DEFAULT_LOG_DIRECTORY = '.claude/tmp/fresh-machine'
+const DEFAULT_LOG_DIRECTORY = '.josh/tmp/fresh-machine'
 const NO_GITHUB_TOKEN =
 	'This scenario uses GitHub and `gh auth token` printed no token. Run `gh auth login` on this machine first.'
 const NO_CLAUDE_TOKEN = `This scenario uses Claude Code and neither the macOS keychain nor ${claude_token.VARIABLE} holds a token. ${claude_token.SETUP_HINT}`

package/scripts/fresh-machine/fresh-machine-run.ts

@@ -4,13 +4,14 @@ import {
 	mkdirSync,
 	mkdtempSync,
 	readdirSync,
-	readFileSync,
 	rmSync,
 	writeFileSync,
 } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { package_manifest } from '#scripts/lib/package-manifest'
+import { npm_registry } from '#scripts/version/npm-registry'
 import { execa, type Options } from 'execa'
 import { z } from 'zod'
 import { fresh_machine_docker, type ContainerRun } from './fresh-machine-docker'
@@ -133,19 +134,18 @@ async function pack(pack_directory: string, write: Write): Promise<string> {
 }
 
 function package_name(): string {
-	const manifest = readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8')
-
-	return MANIFEST_SCHEMA.parse(JSON.parse(manifest)).name
+	return package_manifest.read_manifest(PROJECT_ROOT, MANIFEST_SCHEMA).name
 }
 
 // The published version is always written out in the log and the install command, so a run can be
 // repeated against the same release; without `--package-version` it is the registry's latest.
-async function published_version(requested: string | undefined): Promise<string> {
+function published_version(requested: string | undefined): string {
 	if (requested !== undefined) return requested
 
-	const { stdout } = await execa(PNPM, ['view', package_name(), 'version'], { cwd: PROJECT_ROOT })
+	const answer = npm_registry.view(package_name(), 'version')
+	if (answer.exit_code !== 0) throw new Error('the registry did not answer the latest version')
 
-	return stdout.trim()
+	return answer.stdout.trim()
 }
 
 async function container_run(
@@ -163,7 +163,7 @@ async function container_run(
 		seed_directory: staged.seed_directory,
 		pack_directory: staged.pack_directory,
 		tarball: is_tarball ? await pack(staged.pack_directory, write) : undefined,
-		package_version: is_tarball ? undefined : await published_version(request.package_version),
+		package_version: is_tarball ? undefined : published_version(request.package_version),
 		secret_names: Object.keys(request.secrets),
 	}
 }

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

@@ -12,7 +12,7 @@
 		"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",
+		"gh label list --limit 100 --json name --jq '.[].name' > \"$HOME/labels.txt\"; grep -xE 'auto-ok|needs-decision|needs-human-review|already-done|bug' \"$HOME/labels.txt\"; test \"$(grep -cxE 'auto-ok|needs-decision|needs-human-review|already-done|bug' \"$HOME/labels.txt\")\" -eq 5",
 		"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\"",

package/scripts/gate/busy-average.ts

@@ -0,0 +1,58 @@
+import type { MachineReading } from './machine-capacity'
+
+// **The busy cores a waiting claim admits against are the mean of its last few seconds of readings**
+// (joshuafolkken/kit#4238). One reading covers a 250 ms window, and a CPU near saturation swings across
+// the threshold from one window to the next, so a claim judged on each reading alone would be admitted
+// on a dip into load that is still there. A claim's readings are its own: each poll of one wait adds
+// one, and its first poll judges on the one it has.
+//
+// **What is averaged is the load outside the ledger, each sample against the ledger of its own
+// moment.** Averaging the raw busy cores and subtracting the ledger of now would count a claim released
+// inside the window as external load: its cores would linger in the mean after leaving the ledger.
+
+// Long enough to hold about ten polls of a waiting claim, short enough that a CPU freed a moment ago is
+// admitted against within seconds.
+const AVERAGE_WINDOW_MS = 3000
+
+interface BusySample {
+	at: number
+	external_cores: number
+}
+
+// The samples still inside the window once `reading` taken at `now`, against a ledger holding
+// `ledger_cores`, is added. An unread reading adds nothing: where the machine cannot be read, nothing
+// is averaged.
+function with_reading(
+	samples: ReadonlyArray<BusySample>,
+	reading: MachineReading,
+	ledger_cores: number,
+	now: number,
+): Array<BusySample> {
+	const kept = samples.filter((sample) => now - sample.at < AVERAGE_WINDOW_MS)
+	const { busy_cores } = reading
+
+	if (busy_cores === undefined) return kept
+
+	return [...kept, { at: now, external_cores: Math.max(0, busy_cores - ledger_cores) }]
+}
+
+// `reading` with its busy cores replaced by the mean load outside the ledger on top of the ledger's
+// `ledger_cores` now, or unchanged when none were read.
+function averaged(
+	reading: MachineReading,
+	samples: ReadonlyArray<BusySample>,
+	ledger_cores: number,
+): MachineReading {
+	if (reading.busy_cores === undefined || samples.length === 0) return reading
+
+	let total = 0
+
+	for (const sample of samples) total += sample.external_cores
+
+	return { ...reading, busy_cores: ledger_cores + total / samples.length }
+}
+
+const busy_average = { AVERAGE_WINDOW_MS, averaged, with_reading }
+
+export type { BusySample }
+export { busy_average }