@joshuafolkken/kit 1.1784.0 → 1.2116.0

package/scripts/gate/gate-labels.ts

@@ -0,0 +1,46 @@
+// **The gate's check names, in a module that imports nothing** (joshuafolkken/kit#5177). Most readers of
+// `gate-plan.ts` wanted only these strings, and importing the plan for them tied every such reader into
+// the plan's own imports — so a change to the plan reached most of the test suite. The plan builds its
+// checks from these; a reader that needs only a name imports this leaf.
+
+const LINT_LABEL = 'lint'
+const TYPE_CHECK_LABEL = 'check'
+// The `josh` command the gate's type check runs, shared with `check:related` so the scoped check runs the same one.
+const TYPE_CHECK_TARGET = 'check'
+const SPELL_CHECK_LABEL = 'cspell'
+const SPELL_CHECK_TARGET = 'cspell:dot'
+const UNIT_LABEL = 'test:unit'
+const UNIT_TARGET = 'test:related'
+// **The gate's unit leg runs the whole suite for a changed file every test imports**
+// (joshuafolkken/kit#5122), which every other `josh test:related` narrows to its direct importers.
+const KEEP_WHOLE_SUITE_FLAG = '--keep-whole-suite'
+const BEHAVIOR_LABEL = 'behavior'
+const METRICS_LABEL = 'metrics'
+const EXPORTS_LABEL = 'exports'
+const LOCKFILE_LABEL = 'lockfile'
+
+// The checks whose warnings must survive the green record: eslint (the `lint` step) and svelte-check
+// (the `check` step) both exit 0 while reporting per-tree warnings a developer needs to see again, so
+// reusing a record taken from such a run would hide them. Every other step's
+// warning-shaped output — a Vite config deprecation printed by `test:unit`, say — is not a per-tree
+// finding and repeats every run, so it must not withhold the record. `has_checker_warning` narrows
+// the withholding path down to these.
+const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LABEL]
+
+const gate_labels = {
+	BEHAVIOR_LABEL,
+	EXPORTS_LABEL,
+	KEEP_WHOLE_SUITE_FLAG,
+	LINT_LABEL,
+	LOCKFILE_LABEL,
+	METRICS_LABEL,
+	SPELL_CHECK_LABEL,
+	SPELL_CHECK_TARGET,
+	TYPE_CHECK_LABEL,
+	TYPE_CHECK_TARGET,
+	UNIT_LABEL,
+	UNIT_TARGET,
+	WARNING_CHECKER_LABELS,
+}
+
+export { gate_labels }

package/scripts/gate/gate-ledger.ts

@@ -1,9 +1,11 @@
 import { process_identity } from '#scripts/josh/process-identity'
-import { lane_ledger, type GateCheckRecord } from '#scripts/lane/lane-ledger'
+import type { GateCheckRecord } from '#scripts/lane/lane-ledger-schema'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+import { lane_paths } from '#scripts/lane/lane-paths'
 import { related_scope } from '#scripts/test/test-related-scope'
 import { core_admission } from './core-admission'
 import { core_budget } from './core-budget'
-import { gate_plan } from './gate-plan'
+import { gate_labels } from './gate-labels'
 import { gate_report, type GateStepResult } from './gate-report'
 import { machine_capacity } from './machine-capacity'
 
@@ -96,7 +98,7 @@ async function start(ledger_path: string | undefined): Promise<GateLedgerStart>
 // The unit leg's own facts: the whole-suite fallback it took, or the since-green no-op that ran no
 // test (joshuafolkken/kit#4457) — the two `josh lane:stats` must not time as an ordinary run.
 function unit_facts(result: GateStepResult): Pick<GateCheckRecord, 'fallback' | 'is_unmoved'> {
-	if (result.label !== gate_plan.UNIT_LABEL) return {}
+	if (result.label !== gate_labels.UNIT_LABEL) return {}
 
 	return {
 		fallback: related_scope.fallback_kind(result.output),
@@ -120,7 +122,12 @@ function check_records(results: ReadonlyArray<GateStepResult>): Array<GateCheckR
 async function record_reused(ledger_path: string | undefined, elapsed_ms: number): Promise<void> {
 	if (ledger_path === undefined) return
 
-	await lane_ledger.record_gate(ledger_path, { elapsed_ms, is_passed: true, is_reused: true })
+	await lane_ledger_write.record_gate(ledger_path, {
+		elapsed_ms,
+		is_passed: true,
+		is_reused: true,
+		issue: lane_paths.issue_here(),
+	})
 }
 
 // The caller measures the elapsed time before this, so the end's reading is never part of it.
@@ -133,14 +140,15 @@ async function record(
 
 	if (begun.ledger_path === undefined) return
 
-	const unit_ms = results.find((result) => result.label === gate_plan.UNIT_LABEL)?.elapsed_ms
+	const unit_ms = results.find((result) => result.label === gate_labels.UNIT_LABEL)?.elapsed_ms
 	const external_cores = peak([...begun.readings, await read_external_cores()])
 
-	await lane_ledger.record_gate(begun.ledger_path, {
+	await lane_ledger_write.record_gate(begun.ledger_path, {
 		...outcome,
 		unit_ms,
 		external_cores,
 		checks: check_records(results),
+		issue: lane_paths.issue_here(),
 	})
 }
 

package/scripts/gate/gate-plan.ts

@@ -1,7 +1,8 @@
 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'
+import { core_weights } from './core-weights'
+import { gate_labels } from './gate-labels'
 
 // 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.
@@ -36,7 +37,7 @@ interface GateCheck {
 	// The unit suite reserves nothing: it sizes its own pool from the machine, so it is capped
 	// instead of reserved, and counting it here would reserve cores against itself.
 	reserved_cores: number
-	// The memory this check holds while it runs, `core_budget.MEMORY_MB`'s measured peak; none declared is
+	// The memory this check holds while it runs, `core_weights.MEMORY_MB`'s measured peak; none declared is
 	// none waited for. The unit suite's is per worker, so it is derived instead.
 	memory_mb?: number
 	// A check whose `josh` command is kit-only, so a consumer's gate leaves it out rather than running
@@ -46,21 +47,20 @@ interface GateCheck {
 	is_kit_only?: boolean
 }
 
-const LINT_LABEL = 'lint'
-const TYPE_CHECK_LABEL = 'check'
-const UNIT_LABEL = 'test:unit'
-const UNIT_TARGET = 'test:related'
-const BEHAVIOR_LABEL = 'behavior'
-const METRICS_LABEL = 'metrics'
-const EXPORTS_LABEL = 'exports'
-
-// The checks whose warnings must survive the green record: eslint (the `lint` step) and svelte-check
-// (the `check` step) both exit 0 while reporting per-tree warnings a developer needs to see again, so
-// reusing a record taken from such a run would hide them. Every other step's
-// warning-shaped output — a Vite config deprecation printed by `test:unit`, say — is not a per-tree
-// finding and repeats every run, so it must not withhold the record. `has_checker_warning` narrows
-// the withholding path down to these.
-const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LABEL]
+const {
+	BEHAVIOR_LABEL,
+	EXPORTS_LABEL,
+	KEEP_WHOLE_SUITE_FLAG,
+	LINT_LABEL,
+	LOCKFILE_LABEL,
+	METRICS_LABEL,
+	SPELL_CHECK_LABEL,
+	SPELL_CHECK_TARGET,
+	TYPE_CHECK_LABEL,
+	TYPE_CHECK_TARGET,
+	UNIT_LABEL,
+	UNIT_TARGET,
+} = gate_labels
 
 // The checks that do not fan out across every core, in the order their output is printed. They are
 // named apart from the unit suite because CI runs them on their own runner:
@@ -74,14 +74,14 @@ const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LA
 // `--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`**, the same
+// **The three reserving weights are `core_weights.CORE_WEIGHTS`**, the same
 // numbers the `josh lint`, `josh check` and `josh cspell:dot` commands claim when run directly.
 //
 // **The two zero weights are measured, and they stay zero.** These are warm runs on the 11-core
 // machine. `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. Rounded
 // up, that would be two cores, but a reservation lasts the whole gate's plan, not the check's five
-// seconds. It would raise `RESERVED_CORES` from 6 to 8 and cut the solo unit cap from 5 workers to 3
+// seconds. It would raise `RESERVED_CORES` from 5 to 7 and cut the solo unit cap from 6 workers to 4
 // 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> = [
@@ -91,20 +91,20 @@ const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
 		label: LINT_LABEL,
 		target: 'lint',
 		args: ['--changed'],
-		reserved_cores: core_budget.CORE_WEIGHTS.lint,
-		memory_mb: core_budget.MEMORY_MB.lint,
+		reserved_cores: core_weights.CORE_WEIGHTS.lint,
+		memory_mb: core_weights.MEMORY_MB.lint,
 	},
 	{
 		label: TYPE_CHECK_LABEL,
-		target: 'check',
-		reserved_cores: core_budget.CORE_WEIGHTS.type_check,
-		memory_mb: core_budget.MEMORY_MB.type_check,
+		target: TYPE_CHECK_TARGET,
+		reserved_cores: core_weights.CORE_WEIGHTS.type_check,
+		memory_mb: core_weights.MEMORY_MB.type_check,
 	},
 	{
-		label: 'cspell',
-		target: 'cspell:dot',
-		reserved_cores: core_budget.CORE_WEIGHTS.spell_check,
-		memory_mb: core_budget.MEMORY_MB.spell_check,
+		label: SPELL_CHECK_LABEL,
+		target: SPELL_CHECK_TARGET,
+		reserved_cores: core_weights.CORE_WEIGHTS.spell_check,
+		memory_mb: core_weights.MEMORY_MB.spell_check,
 	},
 	{ label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
 	// **The unused-member check reserves no core**: it builds one TypeScript
@@ -121,13 +121,13 @@ const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
 		target: METRICS_LABEL,
 		args: ['--no-startup'],
 		reserved_cores: 0,
-		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		memory_mb: core_weights.MEMORY_MB.metrics,
 		is_kit_only: true,
 	},
 	// The lockfile policy check is network-bound and usually instant: it verifies only when the
 	// lockfile or `pnpm-workspace.yaml` moved from the merge-base (joshuafolkken/kit#4090), so it
 	// reserves no core. Kit's own until a consumer's private-registry entries are known to verify.
-	{ label: 'lockfile', target: 'lockfile:policy', reserved_cores: 0, is_kit_only: true },
+	{ label: LOCKFILE_LABEL, target: 'lockfile:policy', reserved_cores: 0, is_kit_only: true },
 ]
 
 // The checks, in the order their output is printed — the static set, then the unit suite last (the
@@ -140,7 +140,7 @@ const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
 // sharded suite regardless.
 const GATE_CHECKS: ReadonlyArray<GateCheck> = [
 	...STATIC_CHECKS,
-	{ label: UNIT_LABEL, target: UNIT_TARGET, reserved_cores: 0 },
+	{ label: UNIT_LABEL, target: UNIT_TARGET, args: [KEEP_WHOLE_SUITE_FLAG], reserved_cores: 0 },
 ]
 
 // **Selecting is not skipping, and the difference is where the unit suite runs rather than whether
@@ -166,7 +166,7 @@ function has_unit_check(checks: ReadonlyArray<GateCheck>): boolean {
 	return checks.some((check) => check.label === UNIT_LABEL)
 }
 
-// What the non-elastic checks hold between them: 2 + 2 + 2. Reduced over `STATIC_CHECKS`
+// What the non-elastic checks hold between them: 2 + 2 + 1. Reduced over `STATIC_CHECKS`
 // rather than over every check, because that is the set the sentence above names: `resolve_unit_worker_cap`
 // spends this as the cores the unit suite must leave to its siblings, so summing the unit check into
 // it would have the suite subtract its own reservation from its own budget the day that reservation
@@ -223,6 +223,15 @@ interface GatePlan {
 // the exact opposite of what this function is for. `bounded-pool.ts` closes the same hole for the
 // same reason. A count below one is nonsense too and is read as one run, which is the direction
 // that leaves behavior where it was rather than throttling a gate on a bad input.
+// The order the gate both counts and starts its checks in. `toSorted` is stable, so checks of one
+// weight keep their declaration order.
+function lightest_first<Item>(
+	items: ReadonlyArray<Item>,
+	reserved_cores_of: (item: Item) => number,
+): Array<Item> {
+	return items.toSorted((left, right) => reserved_cores_of(left) - reserved_cores_of(right))
+}
+
 function shared_cores(available_cores: number, concurrent_runs: number): number {
 	const runs = Number.isFinite(concurrent_runs)
 		? Math.max(unit_worker_share.SOLO_RUNS, concurrent_runs)
@@ -231,9 +240,9 @@ function shared_cores(available_cores: number, concurrent_runs: number): number
 	return Math.max(MIN_SHARED_CORES, Math.floor(available_cores / runs))
 }
 
-// Admit checks in declaration order while the running set's reserved cores still fit **this run's
+// Admit checks, lightest first, while the running set's reserved cores still fit **this run's
 // share** of the machine. On a machine running one gate that share is the machine, so this bites
-// only below six cores — the three reserving checks want six between them — and there it is the
+// only below five cores — the three reserving checks want five between them — and there it is the
 // difference between two checks sharing a core and four fighting over it.
 //
 // **Under concurrency it is the only lever there is, and that is a measurement rather than a
@@ -250,16 +259,23 @@ function shared_cores(available_cores: number, concurrent_runs: number): number
 // the gate still reports every failure in one pass — `bounded_pool` queues what it does not start,
 // and no check ever rejects (see `run_gate_steps`). What changes is how many are in flight at
 // once, which is scheduling and never coverage.
+//
+// **The checks are counted lightest first, and `run_gate_steps` starts them in the same order**
+// (joshuafolkken/kit#4609). Counted in declaration order, the first check over the share ended the
+// count, so on CI's four cores lint and the type check filled it and every zero-weight check after
+// the spell check queued behind a check that was only waiting for cores. Lightest first, the `break`
+// is exact: once one check does not fit, no heavier one after it can.
 function resolve_concurrency(
 	available_cores: number,
 	concurrent_runs: number = unit_worker_share.SOLO_RUNS,
 	checks: ReadonlyArray<GateCheck> = GATE_CHECKS,
 ): number {
 	const share = shared_cores(available_cores, concurrent_runs)
+	const ordered = lightest_first(checks, (check) => check.reserved_cores)
 	let admitted = 0
 	let reserved = 0
 
-	for (const check of checks) {
+	for (const check of ordered) {
 		reserved += check.reserved_cores
 
 		if (reserved > share) break
@@ -283,8 +299,8 @@ function resolve_concurrency(
 //
 // **The shared branch drops `RESERVED_CORES`, knowingly, and it is not a strict improvement.** Each
 // concurrent gate still runs lint, the type check and the spell check beside its unit step, and the
-// share below does not subtract them: on 12 cores a solo gate takes 8 unit workers plus 3 siblings —
-// 11 processes for 12 cores — while two concurrent gates take 6 each plus 3 siblings each, which is 18.
+// share below does not subtract them: on 12 cores a solo gate takes 7 unit workers plus 3 siblings —
+// 10 processes for 12 cores — while two concurrent gates take 6 each plus 3 siblings each, which is 18.
 // The obvious correction, `⌊(cores − RESERVED_CORES × runs) ÷ runs⌋`, is **not** applied because
 // nothing has measured it: it hands two gates on an 11-core machine one worker apiece, against the
 // 11.7s-at-8-workers / 16.7s-at-4 curve the table above was built from, and trading a measured
@@ -323,8 +339,8 @@ function solo_unit_weight(available_cores: number): number {
 // once**: no second set of weights is introduced, so a change to the measured reservation moves the
 // admission with it.
 //
-// **A solo gate's four weights sum to exactly the core count** — `reserved(2 + 2 + 2) +
-// unit_cap(cores - 6)` is `cores` — which is what lets every check of a lone gate on a machine with room
+// **A solo gate's four weights sum to exactly the core count** — `reserved(2 + 2 + 1) +
+// unit_cap(cores - 5)` is `cores` — which is what lets every check of a lone gate on a machine with room
 // (its busy cores within what the ledger holds, `core-budget.ts`) be admitted at once,
 // its concurrency unchanged. A machine below the measured one leaves the unit suite uncapped and reads
 // its weight from the same identity, `cores - RESERVED_CORES` clamped at zero, so the sum is the core
@@ -336,7 +352,7 @@ function check_weight(check: GateCheck, plan: GatePlan, available_cores: number)
 }
 
 function unit_memory(workers: number): number {
-	return workers * core_budget.MEMORY_MB.unit_worker
+	return workers * core_weights.MEMORY_MB.unit_worker
 }
 
 // The memory a check holds: its declared figure, or for the unit suite one
@@ -347,34 +363,66 @@ function check_memory(check: GateCheck, plan: GatePlan, available_cores: number)
 	return unit_memory(check_weight(check, plan, available_cores))
 }
 
+// The workers a lone direct run opens below the gate's solo weight: vitest's own default, one per core
+// but one, bounded by the gate's solo workers on the measured machine. **A direct run has no siblings**,
+// so subtracting `RESERVED_CORES` for them sized a four-core CI runner to zero and its suite to one
+// worker (joshuafolkken/kit#4607); vitest's default is what that runner ran before the claim bounded it.
+// The bound keeps a mid-sized machine from claiming more than the measured one does.
+function direct_solo_workers(available_cores: number): number {
+	const vitest_default = available_cores - unit_worker_share.MAIN_PROCESS_CORES
+	const floor = Math.min(vitest_default, solo_unit_weight(MEASURED_CORES))
+
+	return Math.max(solo_unit_weight(available_cores), floor)
+}
+
 // The cores a unit run started directly reserves: 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
+// vitest while other runs are live, and otherwise `direct_solo_workers`. **Not the whole
+// machine where there is room to leave**: 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. **Plus vitest's own process** (joshuafolkken/kit#4362): the workers are the share,
-// and the claim holds the process that drives them on top (`unit_worker_share.cap_to_claim` takes it
-// back off).
+// and hold every later claim behind it — the solo bound stops below the core count from seven cores up.
+// One weight for the suite however it is started. **Plus vitest's own process** (joshuafolkken/kit#4362):
+// the workers are the share, and the claim holds the process that drives them on top
+// (`unit_worker_share.cap_to_claim` takes it back off).
 function direct_unit_weight(
 	available_cores: number = availableParallelism(),
 	live_runs: number = unit_worker_share.live_run_count(),
 ): number {
 	const workers =
-		unit_worker_share.current_share(available_cores, live_runs) ?? solo_unit_weight(available_cores)
+		unit_worker_share.current_share(available_cores, live_runs) ??
+		direct_solo_workers(available_cores)
 
 	return Math.max(unit_worker_share.MIN_WORKERS, workers) + unit_worker_share.MAIN_PROCESS_CORES
 }
 
+// The related files one vitest worker clears in about 30 seconds: `tools/test/unit-durations.json`'s
+// median file takes 105 ms (2077 files), and 30 000 ÷ 105 ≈ 285 (joshuafolkken/kit#5135).
+const FILES_PER_WORKER = 285
+
+// The cores a narrowed `josh test:related` reserves once its scope is known: one worker for each
+// `FILES_PER_WORKER` related files, at least `MIN_WORKERS` and at most the share `direct_unit_weight`
+// gives the whole suite, plus vitest's own process. **A small scope no longer claims the whole width**,
+// so the other lanes' unit claims stop waiting behind a twenty-second run (joshuafolkken/kit#5135).
+function scoped_unit_weight(
+	files: number,
+	available_cores: number = availableParallelism(),
+	live_runs: number = unit_worker_share.live_run_count(),
+): number {
+	const { MAIN_PROCESS_CORES, MIN_WORKERS } = unit_worker_share
+	const share = direct_unit_weight(available_cores, live_runs) - MAIN_PROCESS_CORES
+	const wanted = Math.max(MIN_WORKERS, Math.ceil(files / FILES_PER_WORKER))
+
+	return Math.min(wanted, share) + MAIN_PROCESS_CORES
+}
+
 // What a unit run started directly holds: one worker's peak for each core `direct_unit_weight` gives
 // it, vitest's own process counted as one more.
 function direct_unit_memory(): number {
 	return unit_memory(direct_unit_weight())
 }
 
-// The claim every unit run started directly declares — `josh test:unit`, `josh test:related` and the
-// pre-push hook — declared once so the three cannot drift apart.
+// The claim every unit run started directly declares — `josh test:unit` and the pre-push hook —
+// declared once so the two cannot drift apart. `josh test:related` claims in its body instead, once
+// its scope is known (`scoped_unit_weight`).
 const DIRECT_UNIT_CLAIM = {
 	core_weight: direct_unit_weight,
 	memory_mb: direct_unit_memory,
@@ -468,28 +516,25 @@ function format_gate_plan(
 
 const gate_plan = {
 	DIRECT_UNIT_CLAIM,
-	EXPORTS_LABEL,
+	FILES_PER_WORKER,
 	GATE_CHECKS,
-	LINT_LABEL,
 	MEASURED_CORES,
-	METRICS_LABEL,
 	RESERVED_CORES,
 	STATIC_CHECKS,
-	TYPE_CHECK_LABEL,
-	UNIT_LABEL,
-	UNIT_TARGET,
-	WARNING_CHECKER_LABELS,
 	check_memory,
 	check_weight,
 	direct_unit_weight,
 	format_gate_plan,
 	format_machine,
 	has_unit_check,
+	lightest_first,
 	plan_of,
 	resolve_concurrency,
 	resolve_gate_plan,
 	resolve_unit_worker_cap,
+	scoped_unit_weight,
 	select_gate_checks,
+	unit_memory,
 }
 
 export type { GateCheck, GatePlan }

package/scripts/gate/gate-report.ts

@@ -5,8 +5,9 @@ import { status_icons } from '#scripts/lib/status-icons'
 import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 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_labels } from './gate-labels'
 import { gate_log } from './gate-log'
-import { gate_plan } from './gate-plan'
+import { verification_tail } from './verification-tail'
 
 // The gate's console reporting, split out of `verification-gate.ts` so that file stays under its line
 // ceiling while it grows the scoped pre-check and the failure summary. Nothing
@@ -98,7 +99,7 @@ function checker_lines(result: GateStepResult): ReadonlyArray<string> {
 }
 
 function has_checker_warning(result: GateStepResult): boolean {
-	if (!gate_plan.WARNING_CHECKER_LABELS.includes(result.label)) return false
+	if (!gate_labels.WARNING_CHECKER_LABELS.includes(result.label)) return false
 
 	return checker_lines(result).some((line) =>
 		WARNING_MARKERS.some((marker) => line.includes(marker)),
@@ -201,15 +202,16 @@ function print_gate_step(result: GateStepResult, is_verbose: boolean): void {
 function format_failure_actions(failed: ReadonlyArray<GateStepResult>): string {
 	if (failed.length === 0) return ''
 
-	const lines = failed.map(
-		(result) => `  ${FAIL_ICON} ${result.label} — re-run: pnpm ${result.command}`,
+	const lines = failed.map((result) =>
+		verification_tail.format_rerun(result.label, `pnpm ${result.command}`),
 	)
 
 	return `${GATE_COMMAND} — next:\n${lines.join('\n')}\n`
 }
 
 // **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,
+// The wait cap admits a check that waited two minutes whatever the budget says — sooner where outside
+// load holds it and does not ease —
 // 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) =>
@@ -255,10 +257,10 @@ function print_gate_summary(
 		failed.length === 0
 			? format_green_verdict(results, total)
 			: josh_verdict.format_gate_failed(failed.map((result) => result.label).join(', '), total)
-	const notes = format_budget_notes(results)
+	const failures = `${format_budget_notes(results)}${format_failure_actions(failed)}`
 
 	process.stdout.write(
-		`\n${notes}${format_failure_actions(failed)}${gate_log.format_log_notice(log_path)}${verdict}\n`,
+		`\n${verification_tail.format_tail({ failures, log: { path: log_path }, verdict })}`,
 	)
 }
 

package/scripts/gate/gate-run-steps.ts

@@ -5,6 +5,7 @@ import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { check_cpu, type CheckCpu } from './check-cpu'
 import { core_budget, type Admission } from './core-budget'
 import { free_cores } from './free-cores'
+import { gate_labels } from './gate-labels'
 import { gate_plan, type GatePlan } from './gate-plan'
 import type { CheckClaim, GateStep, GateStepResult } from './gate-report'
 import { build_gate_step, with_granted_workers } from './gate-steps'
@@ -61,6 +62,8 @@ function default_budget(): BudgetContext {
 interface ReservedStep {
 	step: GateStep
 	weight: number
+	// The check's own `reserved_cores`, the key `gate_plan.lightest_first` orders the pool's queue by.
+	reserved_cores: number
 	memory_mb: number
 	// The plan's `--maxWorkers` for the unit suite, the width the free memory bounds once it is admitted.
 	worker_cap: number | undefined
@@ -80,6 +83,7 @@ async function build_reserved_steps(
 		plan.checks.map(async (check) => ({
 			step: await build_gate_step(check, process.cwd(), plan),
 			weight: gate_plan.check_weight(check, plan, available_cores),
+			reserved_cores: check.reserved_cores,
 			memory_mb: gate_plan.check_memory(check, plan, available_cores),
 			worker_cap: plan.unit_worker_cap,
 			reused_at: reused.get(check.label),
@@ -119,7 +123,7 @@ async function admitted_step(
 	admission: Admission,
 	available_cores: number,
 ): Promise<GateStep> {
-	if (reserved.step.label !== gate_plan.UNIT_LABEL) return reserved.step
+	if (reserved.step.label !== gate_labels.UNIT_LABEL) return reserved.step
 
 	const { memory_workers } = await free_cores.read({ available_cores })
 	const asked = admission.granted ?? reserved.worker_cap
@@ -155,11 +159,30 @@ async function run_reserved_step(
 			budget: budget.available_cores,
 			memory_mb: reserved.memory_mb,
 			command: `gate ${reserved.step.label}`,
-			is_unit: reserved.step.label === gate_plan.UNIT_LABEL,
+			is_unit: reserved.step.label === gate_labels.UNIT_LABEL,
 		},
 	)
 }
 
+// The pool's queue in the order `resolve_concurrency` counted it (joshuafolkken/kit#4609), so the
+// checks its width admitted are the ones that start, and one over the share waits for a slot rather
+// than taking one ahead of a zero-weight check. Each result goes back to its check's declaration
+// position, so the printed sections keep their order.
+async function run_lightest_first(
+	reserved: ReadonlyArray<ReservedStep>,
+	concurrency: number,
+	run: (entry: ReservedStep) => Promise<GateStepResult>,
+): Promise<ReadonlyArray<GateStepResult>> {
+	const indexed = reserved.map((entry, index) => ({ entry, index }))
+	const queue = gate_plan.lightest_first(indexed, ({ entry }) => entry.reserved_cores)
+	const finished = await bounded_pool.bounded_map(queue, concurrency, async ({ entry, index }) => ({
+		index,
+		result: await run(entry),
+	}))
+
+	return finished.toSorted((left, right) => left.index - right.index).map(({ result }) => result)
+}
+
 // `bounded_pool` rather than a bare `Promise.all`, so the plan's `concurrency` is what decides how
 // many run at once. **The all-failures-in-one-pass property survives the
 // change** because no check ever rejects: `buffered_process` reports a non-zero exit as a value, so
@@ -181,7 +204,7 @@ async function run_gate_steps(
 	// sets the mark too, since its checks are covered by the outer gate's reservation.
 	return await core_budget.with_held_mark(
 		async () =>
-			await bounded_pool.bounded_map(
+			await run_lightest_first(
 				reserved,
 				plan.concurrency,
 				async (entry) => await run_reserved_step(entry, budget, cpu),

package/scripts/gate/gate-skip.ts

@@ -1,4 +1,4 @@
-import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { review_brief } from '#scripts/review/review-brief'
 import { review_stamps } from '#scripts/review/review-stamps'
 
@@ -64,11 +64,15 @@ const FORCE_FLAG = '--force'
 // rewritten by the hook's own install each cost minutes before anyone could tell them apart.
 type GateReuse = { stamp: FileMapStamp } | { miss: string }
 
+const NO_BASE = 'the merge base could not be read'
+const NO_CHANGE = 'no file differs from the merge base'
+
 // The fingerprint of every declared check's tools and environment (`verification-inputs.ts`).
 const INPUTS_MOVED = 'a checked tool or environment variable changed since the green gate'
+const BASE_MOVED = 'the merge base moved since the green gate'
 
 function base_moved(recorded: string | undefined, base: string): string {
-	return `the merge base moved since the green gate (${recorded ?? 'none'} → ${base})`
+	return `${BASE_MOVED} (${recorded ?? 'none'} → ${base})`
 }
 
 function stamp_miss(stamp: FileMapStamp, base: string): string | undefined {
@@ -77,23 +81,57 @@ function stamp_miss(stamp: FileMapStamp, base: string): string | undefined {
 	return review_stamps.gate_stamp.describes_inputs(stamp) ? undefined : INPUTS_MOVED
 }
 
+const NO_MATCHING_RECORD = 'no green gate record matches the changed files'
+
+// joshuafolkken/kit#5214: a record that exists but covers other files is told apart from no record
+// at all, with the sizes of the two maps, so a log shows how far the tree had moved past it.
+function record_miss(recorded: FileMapStamp | undefined, tree: Record<string, string>): string {
+	if (recorded === undefined) return NO_MATCHING_RECORD
+
+	const changed = String(Object.keys(tree).length)
+	const covered = String(Object.keys(recorded.files).length)
+	const differing = String(file_map_stamp.changed_since(recorded, tree).length)
+
+	return `${NO_MATCHING_RECORD} (${changed} changed, record covers ${covered}, ${differing} differ)`
+}
+
 function gate_reuse(
 	tree: Record<string, string>,
 	base: string | undefined,
 	source?: string,
 ): 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' }
+	if (base === undefined) return { miss: NO_BASE }
+	if (Object.keys(tree).length === 0) return { miss: NO_CHANGE }
 
-	const stamp = review_brief.matching_stamp(review_stamps.gate_stamp.read(source), tree)
+	const recorded = review_stamps.gate_stamp.read(source)
+	const stamp = review_brief.matching_stamp(recorded, tree)
 
-	if (stamp === undefined) return { miss: 'no green gate record matches the changed files' }
+	if (stamp === undefined) return { miss: record_miss(recorded, tree) }
 
 	const miss = stamp_miss(stamp, base)
 
 	return miss === undefined ? { stamp } : { miss }
 }
 
+// joshuafolkken/kit#5234: the kind of a miss, read off the sentence `gate_reuse` wrote, so a ledger
+// counts the reasons without a second wording of them. A record that covers other files is checked
+// before no record at all, since its sentence starts with the other's. A miss no prefix names is
+// `other`; a hook's own refusals are told apart first, by `hook_gate_reuse.miss_kind`.
+const MISS_KINDS: ReadonlyArray<readonly [string, string]> = [
+	[NO_BASE, 'no-base'],
+	[NO_CHANGE, 'no-change'],
+	[`${NO_MATCHING_RECORD} (`, 'record-differs'],
+	[NO_MATCHING_RECORD, 'no-record'],
+	[BASE_MOVED, 'base-moved'],
+	[INPUTS_MOVED, 'inputs-moved'],
+]
+
+const OTHER_MISS = 'other'
+
+function miss_kind(miss: string): string {
+	return MISS_KINDS.find(([prefix]) => miss.startsWith(prefix))?.[1] ?? OTHER_MISS
+}
+
 function stamp_of(reuse: GateReuse): FileMapStamp | undefined {
 	return 'stamp' in reuse ? reuse.stamp : undefined
 }
@@ -153,6 +191,7 @@ const gate_skip = {
 	format_reuse_notice,
 	format_skip,
 	gate_reuse,
+	miss_kind,
 	reusable_green_gate,
 	stamp_of,
 }