@joshuafolkken/kit 1.1178.0 → 1.1229.0

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

@@ -0,0 +1,142 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
+import {
+	DEFAULT_STABLE_READS,
+	git_pr_checks,
+	WATCH_CONFIRMED_STABLE_READS,
+} 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 { 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
+// reached its line limit (joshuafolkken/kit#3264). `git-pr-followup` re-exports each name it always
+// exported, so the move changed no call site and no suite that imports from it.
+
+// Named so a test can pin the note without restating it (joshuafolkken/kit#999).
+const WATCH_FAILED_NOTE = 'pr checks --watch failed; falling through to polling'
+
+// The watch is a look ahead, not a gate. It fails when **any** check has failed — CodeRabbit
+// included — and letting that escape ended the run before `evaluate_pr_state` could apply kit#753's
+// CodeRabbit exemption at all. It only ever bit where every check finished inside the two-minute
+// window, so a repository with a slow E2E never saw it and a fast one always would
+// (joshuafolkken/kit#999). What the watch is has since changed — `gh pr checks --watch` went through
+// GraphQL, so joshuafolkken/kit#1028 replaced it with the same poll loop bounded to two minutes —
+// but its place here has not.
+//
+// Falling through costs nothing: whether the merge may proceed is decided in one place below, and a
+// genuinely failing non-CodeRabbit check still ends the wait on the first poll by kit#990's
+// fast-fail rather than by that failure.
+// The watch fails for two different reasons — "a check failed" and "no checks reported on this
+// branch" — and its own error does not say which. The pull request itself can: a failed check leaves
+// a rollup, and a branch with no checks leaves it empty. Falling through on the empty case would
+// trade a failure reported in seconds for the whole budget spent waiting on a required check that is
+// missing rather than pending, so that one is rethrown and the old behavior kept.
+//
+// **Read from the raw payload, not from `parse_pr_state_snapshot`.** That parser never throws: a
+// malformed answer or a schema mismatch degrades to `rollup: []`, which is indistinguishable there
+// from a branch that genuinely has no checks. Rethrowing on it would put an unreadable answer back
+// on the path this whole change exists to remove. So the question asked here is the narrow one —
+// *is this definitely an empty rollup* — and every other outcome falls through.
+function reads_as_empty_rollup(raw_json: string): boolean {
+	const parsed = json_value.parse_or_undefined(raw_json)
+
+	if (typeof parsed !== 'object' || parsed === null || !('statusCheckRollup' in parsed)) {
+		return false
+	}
+
+	const { statusCheckRollup: rollup } = parsed
+
+	return Array.isArray(rollup) && rollup.length === 0
+}
+
+// The read throws rather than answering `undefined`, so the `catch` is its only failure path.
+//
+// The **checks** half, not the whole snapshot: the question here is about `statusCheckRollup` alone,
+// and reading the review listing to answer it paged a whole conversation for nothing
+// (joshuafolkken/kit#1043).
+async function has_no_checks(branch_name: string): Promise<boolean> {
+	try {
+		const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
+
+		return reads_as_empty_rollup(checks.snapshot_json)
+	} catch {
+		// The read refines the swallow; it is not a gate of its own. An answer it cannot get is not
+		// evidence of anything, so prefer falling through — the poll below reads the same state.
+		return false
+	}
+}
+
+async function handle_watch_failure(branch_name: string, error: unknown): Promise<void> {
+	if (await has_no_checks(branch_name)) throw error
+
+	// Swallowed, but never silently: the reason a run stopped early used to be this line, so it
+	// stays visible even though it no longer decides anything.
+	console.info(`⚠️ ${WATCH_FAILED_NOTE}: ${git_gh_helpers.get_error_message_with_stderr(error)}`)
+}
+
+// **Returns whether the watch confirmed completion** (joshuafolkken/kit#2029): `true` only when
+// `pr_checks_watch` saw every check finish, `false` when it timed out with checks still pending or
+// fell through to polling on a swallowed failure. `run_checks` reads it to decide how many stable poll
+// 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> {
+	console.info('')
+	console.info('📊 Watching PR checks...')
+
+	try {
+		const result = await git_gh_command.pr_checks_watch(branch_name)
+
+		return !result.timed_out
+	} catch (error) {
+		await handle_watch_failure(branch_name, error)
+
+		return false
+	}
+}
+
+// **A confirmed watch lowers the poll's stable-read requirement to one** (joshuafolkken/kit#2029). The
+// watch is the first confirmation that every check settled, so the poll that follows need only agree
+// 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.
+async function run_checks(input: {
+	branch_name: string
+	is_skip_watch: boolean
+}): Promise<PrStateSnapshot> {
+	const is_watch_confirmed = !input.is_skip_watch && (await watch_before_polling(input.branch_name))
+	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)
+}
+
+// Temporary (kit#753): record every CodeRabbit check that was not passing when the merge gate
+// opened, so a merge shipped without CodeRabbit review stays auditable.
+function read_coderabbit_skip_notes(snapshot: PrStateSnapshot): Array<string> {
+	return snapshot.rollup
+		.filter((check) => is_coderabbit_check(check.name))
+		.filter((check) => check.status !== CHECK_STATUS_PASS)
+		.map(
+			(check) =>
+				`CodeRabbit check skipped (kit#753): ${check.name} was ${check.status} at merge time`,
+		)
+}
+
+// The skip is printed where the run is being watched, not only carried into the Telegram body it
+// ends up in. A merge that went ahead while CodeRabbit had not come back is the one thing kit#753's
+// exemption trades away, and it used to be invisible in `followup`'s own output
+// (joshuafolkken/kit#1217).
+function log_skip_notes(notes: ReadonlyArray<string>): void {
+	for (const note of notes) {
+		console.info(`⏭ ${note}`)
+	}
+}
+
+const git_pr_followup_checks = {
+	run_checks,
+	read_coderabbit_skip_notes,
+	log_skip_notes,
+}
+
+export { git_pr_followup_checks, WATCH_FAILED_NOTE }

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

@@ -1,18 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { git_gh_helpers } from '#scripts/gh/git-gh-helpers'
 import { git_pr_ai_review, type TelegramContext } from '#scripts/gh/git-pr-ai-review'
-import {
-	DEFAULT_STABLE_READS,
-	git_pr_checks,
-	WATCH_CONFIRMED_STABLE_READS,
-} 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 { git_pr_coderabbit } from '#scripts/gh/git-pr-coderabbit'
 import { git_pr_managed_config } from '#scripts/gh/git-pr-managed-config'
 import { github_issue_url } from '#scripts/gh/github-issue-url'
 import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
-import { json_value } from '#scripts/lib/json-value'
 import type { GitNotifyConfig } from '#scripts/notify/git-notify'
 import {
 	telegram_notify,
@@ -22,12 +13,12 @@ import {
 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'
+import { git_pr_followup_checks } from './git-pr-followup-checks'
 import { git_pr_followup_wrapup } from './git-pr-followup-wrapup'
 
 const { STAGE, lap } = git_followup_stages
+const { run_checks, read_coderabbit_skip_notes, log_skip_notes } = git_pr_followup_checks
 
-// Named so a test can pin the note without restating it (joshuafolkken/kit#999).
-const WATCH_FAILED_NOTE = 'pr checks --watch failed; falling through to polling'
 const REPO_NAME_SEPARATOR = '/'
 
 function parse_repo_name(name_with_owner: string | undefined): string | undefined {
@@ -107,123 +98,6 @@ async function warn_if_missing_closes(branch_name: string): Promise<string | und
 	return undefined
 }
 
-// The watch is a look ahead, not a gate. It fails when **any** check has failed — CodeRabbit
-// included — and letting that escape ended the run before `evaluate_pr_state` could apply kit#753's
-// CodeRabbit exemption at all. It only ever bit where every check finished inside the two-minute
-// window, so a repository with a slow E2E never saw it and a fast one always would
-// (joshuafolkken/kit#999). What the watch is has since changed — `gh pr checks --watch` went through
-// GraphQL, so joshuafolkken/kit#1028 replaced it with the same poll loop bounded to two minutes —
-// but its place here has not.
-//
-// Falling through costs nothing: whether the merge may proceed is decided in one place below, and a
-// genuinely failing non-CodeRabbit check still ends the wait on the first poll by kit#990's
-// fast-fail rather than by that failure.
-// The watch fails for two different reasons — "a check failed" and "no checks reported on this
-// branch" — and its own error does not say which. The pull request itself can: a failed check leaves
-// a rollup, and a branch with no checks leaves it empty. Falling through on the empty case would
-// trade a failure reported in seconds for the whole budget spent waiting on a required check that is
-// missing rather than pending, so that one is rethrown and the old behavior kept.
-//
-// **Read from the raw payload, not from `parse_pr_state_snapshot`.** That parser never throws: a
-// malformed answer or a schema mismatch degrades to `rollup: []`, which is indistinguishable there
-// from a branch that genuinely has no checks. Rethrowing on it would put an unreadable answer back
-// on the path this whole change exists to remove. So the question asked here is the narrow one —
-// *is this definitely an empty rollup* — and every other outcome falls through.
-function reads_as_empty_rollup(raw_json: string): boolean {
-	const parsed = json_value.parse_or_undefined(raw_json)
-
-	if (typeof parsed !== 'object' || parsed === null || !('statusCheckRollup' in parsed)) {
-		return false
-	}
-
-	const { statusCheckRollup: rollup } = parsed
-
-	return Array.isArray(rollup) && rollup.length === 0
-}
-
-// The read throws rather than answering `undefined`, so the `catch` is its only failure path.
-//
-// The **checks** half, not the whole snapshot: the question here is about `statusCheckRollup` alone,
-// and reading the review listing to answer it paged a whole conversation for nothing
-// (joshuafolkken/kit#1043).
-async function has_no_checks(branch_name: string): Promise<boolean> {
-	try {
-		const checks = await git_gh_command.pr_get_checks_snapshot(branch_name)
-
-		return reads_as_empty_rollup(checks.snapshot_json)
-	} catch {
-		// The read refines the swallow; it is not a gate of its own. An answer it cannot get is not
-		// evidence of anything, so prefer falling through — the poll below reads the same state.
-		return false
-	}
-}
-
-async function handle_watch_failure(branch_name: string, error: unknown): Promise<void> {
-	if (await has_no_checks(branch_name)) throw error
-
-	// Swallowed, but never silently: the reason a run stopped early used to be this line, so it
-	// stays visible even though it no longer decides anything.
-	console.info(`⚠️ ${WATCH_FAILED_NOTE}: ${git_gh_helpers.get_error_message_with_stderr(error)}`)
-}
-
-// **Returns whether the watch confirmed completion** (joshuafolkken/kit#2029): `true` only when
-// `pr_checks_watch` saw every check finish, `false` when it timed out with checks still pending or
-// fell through to polling on a swallowed failure. `run_checks` reads it to decide how many stable poll
-// 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> {
-	console.info('')
-	console.info('📊 Watching PR checks...')
-
-	try {
-		const result = await git_gh_command.pr_checks_watch(branch_name)
-
-		return !result.timed_out
-	} catch (error) {
-		await handle_watch_failure(branch_name, error)
-
-		return false
-	}
-}
-
-// **A confirmed watch lowers the poll's stable-read requirement to one** (joshuafolkken/kit#2029). The
-// watch is the first confirmation that every check settled, so the poll that follows need only agree
-// 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.
-async function run_checks(input: {
-	branch_name: string
-	is_skip_watch: boolean
-}): Promise<PrStateSnapshot> {
-	const is_watch_confirmed = !input.is_skip_watch && (await watch_before_polling(input.branch_name))
-	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)
-}
-
-// Temporary (kit#753): record every CodeRabbit check that was not passing when the merge gate
-// opened, so a merge shipped without CodeRabbit review stays auditable.
-function read_coderabbit_skip_notes(snapshot: PrStateSnapshot): Array<string> {
-	return snapshot.rollup
-		.filter((check) => is_coderabbit_check(check.name))
-		.filter((check) => check.status !== CHECK_STATUS_PASS)
-		.map(
-			(check) =>
-				`CodeRabbit check skipped (kit#753): ${check.name} was ${check.status} at merge time`,
-		)
-}
-
-// The skip is printed where the run is being watched, not only carried into the Telegram body it
-// ends up in. A merge that went ahead while CodeRabbit had not come back is the one thing kit#753's
-// exemption trades away, and it used to be invisible in `followup`'s own output
-// (joshuafolkken/kit#1217).
-function log_skip_notes(notes: ReadonlyArray<string>): void {
-	for (const note of notes) {
-		console.info(`⏭ ${note}`)
-	}
-}
-
 // **The one read of the four that can depend on another.** Without an issue number on the command
 // line it is the pull request body that names it (joshuafolkken/kit#1539), so the title read waits
 // for exactly that one and for nothing else. With a number in hand the `??` short-circuits and the
@@ -451,7 +325,6 @@ const git_pr_followup = {
 
 export {
 	git_pr_followup,
-	WATCH_FAILED_NOTE,
 	run_checks,
 	build_issue_url,
 	parse_repo_name,
@@ -464,3 +337,5 @@ export {
 }
 export type { FollowupInput }
 export type { TelegramContext } from '#scripts/gh/git-pr-ai-review'
+
+export { WATCH_FAILED_NOTE } from './git-pr-followup-checks'

package/scripts/gate/core-budget.ts

@@ -6,6 +6,7 @@ import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { z } from 'zod'
 
 // A machine-wide weighted core budget with admission control (joshuafolkken/kit#2351).
@@ -46,6 +47,26 @@ const WAIT_CAP_MS = 120_000
 // The head of the ledger is always admitted, so the smallest budget worth planning against is one core.
 const MIN_BUDGET = 1
 
+// **The cores each heavy tool occupies, declared once for both places that reserve them**
+// (joshuafolkken/kit#3345). `gate-plan.ts`'s checks and the `josh` commands that run the same tools
+// directly read these, so a direct `josh lint` claims what the gate's lint claims. The lint, type check
+// and spell check numbers are `gate-plan.ts`'s measured table, floored. The whole-tree eslint scan
+// behind `josh lines` and `josh refactor:scan` runs in one process: measured cold on the 11-core
+// machine on 2026-10-06, 113s of CPU over 98s of wall, so it gets one core.
+const CORE_WEIGHTS = {
+	lint: 2,
+	type_check: 1,
+	spell_check: 1,
+	eslint_scan: 1,
+} as const
+
+// **The environment mark that says a parent already holds this process's cores**
+// (joshuafolkken/kit#3345). `josh gate` reserves per check and then spawns `pnpm josh lint`. Without
+// the mark, that child's own dispatch would claim a second place for the cores its parent already
+// holds. Every holder sets it, and every child inherits it through the environment and claims nothing.
+const HELD_KEY = 'JOSH_CORE_RESERVED'
+const HELD_VALUE = '1'
+
 const reservation_schema = process_owner_schema.extend({
 	weight: z.number(),
 	claimed_at: z.number(),
@@ -133,7 +154,7 @@ function live_reservations(directory: string = PLATFORM_TEMP_ROOT): Array<LiveRe
 	return marker_files(directory).flatMap((name) => {
 		const reservation = live_reservation(path.join(directory, name))
 
-		return reservation === undefined ? [] : [{ key: name, reservation }]
+		return reservation === undefined ? [] : { key: name, reservation }
 	})
 }
 
@@ -272,14 +293,61 @@ async function with_core_reservation<T>(
 	}
 }
 
+function is_held(): boolean {
+	return process.env[HELD_KEY] === HELD_VALUE
+}
+
+// A function of its own so the restoring write does not sit after an `await`, where
+// `require-atomic-updates` reads any write to `process` as a possible race — the reason `josh.ts`
+// gives `record_exit_code`.
+function set_held_mark(value: string): void {
+	process.env[HELD_KEY] = value
+}
+
+// Marks this process, and every child it spawns, as running inside a held reservation. The previous
+// value comes back afterwards, so a nested holder never clears the mark its outer holder set.
+async function with_held_mark<T>(run: () => Promise<T>): Promise<T> {
+	const previous = process.env[HELD_KEY] ?? ''
+
+	set_held_mark(HELD_VALUE)
+
+	try {
+		return await run()
+	} finally {
+		set_held_mark(previous)
+	}
+}
+
+// **A command's reservation: the gate's claim, unless a parent already holds the cores**
+// (joshuafolkken/kit#3345). `josh-logic.ts` calls this around every command that declares a weight.
+// Each command then only declares its weight, and no command carries a copy of the claim, run and
+// release steps. A solo run is admitted on the first read, so a run with room on the machine starts
+// with no wait. A command inside a unit suite claims nothing either, for the reason `reserved-run.ts`
+// gives: the suite's own reservation already covers it, and a place claimed there would wait on it.
+async function with_command_reservation<T>(
+	weight: number,
+	run: () => Promise<T>,
+	options: ReserveOptions = {},
+): Promise<T> {
+	if (is_held() || unit_worker_share.is_nested_run()) return await run()
+
+	return await with_core_reservation(weight, async () => await with_held_mark(run), options)
+}
+
 const core_budget = {
+	CORE_WEIGHTS,
+	HELD_KEY,
+	HELD_VALUE,
 	RESERVED_PREFIX,
 	admitted_keys,
 	admitted_load,
+	is_held,
 	live_reservations,
 	release,
 	reserve,
+	with_command_reservation,
 	with_core_reservation,
+	with_held_mark,
 }
 
 export type { LiveReservation, Reservation, ReserveOptions }

package/scripts/gate/gate-plan.ts

@@ -1,6 +1,7 @@
 import { availableParallelism } from 'node:os'
 import { josh_verdict } from '#scripts/josh/josh-verdict'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
+import { core_budget } from './core-budget'
 
 // How many of the gate's checks run at once, and how wide the one elastic check may fan out —
 // both derived from the machine rather than fixed at four (joshuafolkken/kit#1258).
@@ -61,15 +62,30 @@ const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LA
 // check rather than one appended after the unit suite is what keeps the plan's shape intact: the
 // `--no-unit` set stays "the whole gate minus the unit suite", and a CI runner — which has no recorded
 // transcripts — runs it as a trivial green rather than skipping it.
+//
+// **The three reserving weights are `core_budget.CORE_WEIGHTS`** (joshuafolkken/kit#3345), the same
+// numbers the `josh lint`, `josh check` and `josh cspell:dot` commands claim when run directly.
+//
+// **The two zero weights were measured again for joshuafolkken/kit#3345, and they stay zero.** These are
+// warm runs on the 11-core machine on 2026-10-06. `behavior` took 0.6s of wall for 0.7s of CPU, which
+// is node starting up. `exports:unused` took 5.5s of wall for 9.0s of CPU, about 1.6 cores. Floored,
+// that would be one core, but a reservation lasts the whole gate's plan, not the check's five seconds.
+// It would lower `RESERVED_CORES` from 4 to 5 and cut the solo unit cap from 7 workers to 6 for the
+// full length of the unit suite, to cover a burst that ends before lint does. Nothing has measured
+// that trade, so the measured shape stays.
 const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
-	{ label: LINT_LABEL, target: 'lint', reserved_cores: 2 },
-	{ label: TYPE_CHECK_LABEL, target: 'check', reserved_cores: 1 },
-	{ label: 'cspell', target: 'cspell:dot', reserved_cores: 1 },
+	{ label: LINT_LABEL, target: 'lint', reserved_cores: core_budget.CORE_WEIGHTS.lint },
+	{
+		label: TYPE_CHECK_LABEL,
+		target: 'check',
+		reserved_cores: core_budget.CORE_WEIGHTS.type_check,
+	},
+	{ label: 'cspell', target: 'cspell:dot', reserved_cores: core_budget.CORE_WEIGHTS.spell_check },
 	{ label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
 	// **The unused-member check reserves no core** (joshuafolkken/kit#2987): it builds one TypeScript
-	// program and walks it single-threaded for about 5s — over well before lint and the type check, so
-	// a reservation would only take a place from the four-core CI runner's fan-out and a worker from
-	// the unit suite for the whole gate.
+	// program and walks it for about 5s, and it is over well before lint and the type check. A
+	// reservation would only take a place from the four-core CI runner's fan-out and a worker from the
+	// unit suite for the whole gate.
 	{ label: 'exports', target: 'exports:unused', reserved_cores: 0 },
 ]
 
@@ -242,6 +258,11 @@ function resolve_unit_worker_cap(
 	return available_cores - RESERVED_CORES
 }
 
+// The unit suite's weight when nothing caps its pool: the cores left once the static checks have theirs.
+function solo_unit_weight(available_cores: number): number {
+	return Math.max(0, available_cores - RESERVED_CORES)
+}
+
 // The cores a check reserves from the machine-wide budget while it runs (joshuafolkken/kit#2351). The
 // static checks declare their measured reservation; the unit suite declares the pool it will open,
 // which `unit_worker_cap` has already sized against the runs in flight. **This is the same table, read
@@ -256,7 +277,25 @@ function resolve_unit_worker_cap(
 function check_weight(check: GateCheck, plan: GatePlan, available_cores: number): number {
 	if (check.label !== UNIT_LABEL) return check.reserved_cores
 
-	return plan.unit_worker_cap ?? Math.max(0, available_cores - RESERVED_CORES)
+	return plan.unit_worker_cap ?? solo_unit_weight(available_cores)
+}
+
+// The cores a unit run started directly reserves (joshuafolkken/kit#3345): the share it will pass to
+// vitest while other runs are live, and otherwise the gate's own solo unit weight. **Not the whole
+// machine**, though a lone vitest sizes its own pool: FIFO admission lets a claim of every core in only
+// once the ledger is empty, so a one-file `josh test:related` would wait out every other lane's gate
+// and hold every later claim behind it. One weight for the suite however it is started. **Floored at one
+// worker**: on a machine the static checks fill, a four-core CI runner among them, the gate's solo
+// weight is zero because its siblings hold every core — a direct run has no siblings, and vitest still
+// occupies a core.
+function direct_unit_weight(
+	available_cores: number = availableParallelism(),
+	live_runs: number = unit_worker_share.live_run_count(),
+): number {
+	const weight =
+		unit_worker_share.current_share(available_cores, live_runs) ?? solo_unit_weight(available_cores)
+
+	return Math.max(unit_worker_share.MIN_WORKERS, weight)
 }
 
 // `availableParallelism()` rather than `cpus().length`: it reports what this process may actually
@@ -345,6 +384,7 @@ const gate_plan = {
 	UNIT_LABEL,
 	WARNING_CHECKER_LABELS,
 	check_weight,
+	direct_unit_weight,
 	format_gate_plan,
 	format_machine,
 	has_unit_check,

package/scripts/gate/gate-skip.ts

@@ -60,18 +60,42 @@ const FORCE_FLAG = '--force'
 //
 // A `base` that could not be read is `undefined`, and an older record carries none: both compare
 // unequal to anything, so the gate runs its checks. No base means no reuse, never reuse without one.
-function reusable_green_gate(
+//
+// **A refusal carries its reason** (joshuafolkken/kit#3307): a pre-push hook that fell back to the
+// whole unit suite said nothing about why, so a merge base moved by ship's main sync and a lock file
+// rewritten by the hook's own install each cost minutes before anyone could tell them apart.
+type GateReuse = { stamp: FileMapStamp } | { miss: string }
+
+function base_moved(recorded: string | undefined, base: string): string {
+	return `the merge base moved since the green gate (${recorded ?? 'none'} → ${base})`
+}
+
+function gate_reuse(
 	tree: Record<string, string>,
 	base: string | undefined,
 	source?: string,
-): FileMapStamp | undefined {
-	if (base === undefined || Object.keys(tree).length === 0) return undefined
+): GateReuse {
+	if (base === undefined) return { miss: 'the merge base could not be read' }
+	if (Object.keys(tree).length === 0) return { miss: 'no file differs from the merge base' }
 
 	const stamp = review_brief.matching_stamp(review_stamps.gate_stamp.read(source), tree)
 
-	if (stamp?.base !== base) return undefined
+	if (stamp === undefined) return { miss: 'no green gate record matches the changed files' }
+	if (stamp.base !== base) return { miss: base_moved(stamp.base, base) }
+
+	return { stamp }
+}
+
+function stamp_of(reuse: GateReuse): FileMapStamp | undefined {
+	return 'stamp' in reuse ? reuse.stamp : undefined
+}
 
-	return stamp
+function reusable_green_gate(
+	tree: Record<string, string>,
+	base: string | undefined,
+	source?: string,
+): FileMapStamp | undefined {
+	return stamp_of(gate_reuse(tree, base, source))
 }
 
 // **The sentence claims the result, and never merely the omission.** "verification skipped" on its
@@ -116,8 +140,15 @@ function format_skip(taken_at: string): string {
 	})
 }
 
-const gate_skip = { FORCE_FLAG, format_reuse_notice, format_skip, reusable_green_gate }
+const gate_skip = {
+	FORCE_FLAG,
+	format_reuse_notice,
+	format_skip,
+	gate_reuse,
+	reusable_green_gate,
+	stamp_of,
+}
 
-export type { ReuseNotice }
+export type { GateReuse, ReuseNotice }
 
 export { gate_skip }

package/scripts/gate/hook-gate-reuse.ts

@@ -1,7 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
-import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { observation_ledger } from '#scripts/observations/observation-ledger'
-import { gate_skip } from './gate-skip'
+import { gate_skip, type GateReuse } from './gate-skip'
 import type { GateTree } from './gate-tree'
 
 // What the two git hooks share when they decline to re-run a check `pnpm josh gate` already passed on
@@ -94,6 +93,8 @@ interface HookReuse {
 	// The hook-specific narrowing: whether what this git operation carries is the tree the record
 	// describes. `is_worktree_clean` for a push, `is_index_matching_worktree` for a commit.
 	is_tree_carried: boolean
+	// The reason a refusal on that narrowing reports, in the hook's own words (joshuafolkken/kit#3307).
+	carry_miss: string
 	extra_arguments: ReadonlyArray<string>
 	force_env: string
 	// The record to read, so a test can plant one without overwriting the record a live run relies on.
@@ -102,27 +103,28 @@ interface HookReuse {
 	source?: string | undefined
 }
 
-// The stamp rather than a boolean, for the same reason `gate_skip.reusable_green_gate` hands one back:
-// the caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
-// printing.
+// The stamp rather than a boolean, for the same reason `gate_skip.gate_reuse` hands one back: the
+// caller prints `taken_at`, and a record that does not describe this tree has no timestamp worth
+// printing. A refusal carries its reason instead (joshuafolkken/kit#3307).
 //
 // **Any argument at all refuses the reuse**, not only the force flag. A caller who narrowed the run
 // asked for that run rather than for a recorded result about a whole tree, and a hook's own line passes
 // none, so this costs it nothing.
-function reusable_green_hook(input: HookReuse): FileMapStamp | undefined {
-	if (input.extra_arguments.length > 0 || is_force_requested(input.force_env)) return undefined
-	if (!input.is_tree_carried) return undefined
+function hook_reuse(input: HookReuse): GateReuse {
+	if (input.extra_arguments.length > 0) return { miss: 'arguments were passed to the hook' }
+	if (is_force_requested(input.force_env)) return { miss: `${input.force_env} is set` }
+	if (!input.is_tree_carried) return { miss: input.carry_miss }
 
-	return gate_skip.reusable_green_gate(input.tree.files, input.tree.base, input.source)
+	return gate_skip.gate_reuse(input.tree.files, input.tree.base, input.source)
 }
 
 const hook_gate_reuse = {
 	GATE_REUSING_TARGETS,
+	hook_reuse,
 	is_force_requested,
 	is_index_matching_worktree,
 	is_worktree_clean,
 	read_status_lines,
-	reusable_green_hook,
 }
 
 export type { HookReuse }

package/scripts/gate/pre-commit-type-check.ts

@@ -96,14 +96,17 @@ async function reusable_green_commit(
 	source?: string,
 	start_directory: string = process.cwd(),
 ): Promise<FileMapStamp | undefined> {
-	const reusable = hook_gate_reuse.reusable_green_hook({
+	const reuse = hook_gate_reuse.hook_reuse({
 		tree,
 		is_tree_carried: tree.is_index_matching_worktree,
+		carry_miss: 'the index differs from the working tree',
 		extra_arguments,
 		force_env: FORCE_ENV,
 		source,
 	})
 
+	const reusable = gate_skip.stamp_of(reuse)
+
 	if (reusable === undefined) return undefined
 
 	return (await is_recorded_check_this_check(start_directory)) ? reusable : undefined