@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/gate/machine-capacity.ts

@@ -1,5 +1,5 @@
 import { readFile } from 'node:fs/promises'
-import { availableParallelism, cpus, totalmem } from 'node:os'
+import { availableParallelism, cpus, loadavg, totalmem } from 'node:os'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
@@ -32,12 +32,12 @@ import { execa } from 'execa'
 // The window the busy cores are measured over: long enough that one scheduler tick does not dominate it,
 // short enough that a solo admission is not visibly delayed.
 const SAMPLE_WINDOW_MS = 250
-// **The background a developer machine always carries, which the gate's weights were measured beside.**
-// On 2026-10-07 the 11-core machine idled at about 1.5 cores outside `josh` — Claude sessions 0.55, the
-// window server 0.47, a browser 0.5. The solo gate's weights sum to exactly the core count and were
-// measured with that load present, so only what exceeds it is load the budget must give way to;
-// counting the baseline would defer a solo gate's unit suite on every run.
-const BASELINE_CORES = 2
+// **Run-queue load outside the ledger past this many times the cores holds the first waiter too**
+// (joshuafolkken/kit#4361). The first waiter ignores outside load (joshuafolkken/kit#4313), and lanes took
+// the 11-core machine to a load average of 25–34. Twice the cores is loose on purpose: the one-core
+// editor load #4313 stopped holding a solo gate stays far below it, so neither its starvation nor the
+// lanes' speed comes back, while a machine whose queue beyond the ledger passes two per core waits.
+const OVERLOAD_FACTOR = 2
 const BYTES_PER_MB = 1_048_576
 const KB_PER_MB = 1024
 const PERCENT = 100
@@ -62,7 +62,10 @@ const PAGE_SIZE_NAME = 'hw.pagesize'
 // The kernel's memory-pressure verdict — 1 normal, 2 warning, 4 critical — the one Activity Monitor
 // colors its "memory pressure" graph by.
 const PRESSURE_NAME = 'kern.memorystatus_vm_pressure_level'
-const PRESSURE_WARNING = 2
+// **Only critical holds; warning is sticky** (joshuafolkken/kit#4199). On macOS the verdict can stay at
+// warning for hours after the pressure passed, so a hold on warning never lifts. What is pressured right
+// now shows in the free figure and the swap and compressor traffic; the verdict adds only critical.
+const PRESSURE_HOLD = 4
 // The swap traffic across one window that reads as pressure — 64 MB a second paged to disk. A machine
 // that swapped once still pages a few megabytes back in as old pages are touched.
 const SWAP_PRESSURE_MB = 16
@@ -81,10 +84,13 @@ const SYSCTL_ARGUMENTS = [
 const SYSCTL_LINE = /^(?<name>[\w.]+): (?<value>\d+)$/gmu
 
 // `memory_pressured` says why `available_mb` read none, so a claim that waits can name the pressure.
+// `run_queue` is the one-minute load average: the busy cores stop at the core count, so only the queue
+// tells a machine at twice its cores from one at once (`is_overloaded`).
 interface MachineReading {
 	busy_cores: number | undefined
 	available_mb: number | undefined
 	memory_pressured?: boolean | undefined
+	run_queue?: number | undefined
 }
 
 // The memory half of a reading. `swapped_mb` is a counter — every page swapped in or out since boot —
@@ -103,10 +109,15 @@ interface LedgerLoad {
 	memory_mb: number
 }
 
+// `busy_excess` is the measured cores beyond what the ledger declares — what `cores` gave up to load the
+// ledger does not hold, so a claim that waits on it can name the CPU as saturated. `is_overloaded` lifts
+// the first waiter's exemption from that load (`core_admission.is_admitted`).
 interface MachineBudget {
 	cores: number
 	memory_mb: number
 	memory_pressured?: boolean | undefined
+	busy_excess?: number | undefined
+	is_overloaded?: boolean | undefined
 }
 
 interface CpuTimes {
@@ -287,22 +298,23 @@ function moved_over(from: number | undefined, to: number | undefined, limit: num
 
 function is_pressured(before: MemoryReading, after: MemoryReading): boolean {
 	return (
-		(after.pressure_level ?? 0) >= PRESSURE_WARNING ||
+		(after.pressure_level ?? 0) >= PRESSURE_HOLD ||
 		moved_over(before.swapped_mb, after.swapped_mb, SWAP_PRESSURE_MB) ||
 		moved_over(before.compressed_mb, after.compressed_mb, COMPRESSION_PRESSURE_MB)
 	)
 }
 
-// **Memory under compression and swap pressure has nothing free to admit against.** The level counts
-// compressible pages as available, so on 2026-10-16 it read 5.4 GB free while the compressor held
-// 5.9 GB and compressed and decompressed about 3.3 GB every three seconds, and 5.2 GB of reservations
-// were admitted on top. A reading the kernel calls pressured, or one with swap or compressor traffic
-// across the window, answers no free memory: what the ledger holds keeps running and a heavy claim waits
-// for the pressure to pass.
-function pressured_available(before: MemoryReading, after: MemoryReading): number | undefined {
+// **Only a reading the kernel calls critical has nothing free to admit against.** Swap and compressor
+// traffic across the window used to answer no free memory too (joshuafolkken/kit#3943), but this machine
+// swaps out 0.4–1.3 TB a day as a matter of course, so that traffic held about a third of every wait
+// with memory to spare (joshuafolkken/kit#4313). A claim now waits on memory only when the free figure
+// falls short of what it declares; the traffic still names the wait as pressure (`memory_pressured`),
+// and holds a claim past the shortfall that running alone or the wait cap would otherwise start
+// (`core_admission.is_swap_held`, joshuafolkken/kit#4451).
+function pressured_available(after: MemoryReading): number | undefined {
 	if (after.available_mb === undefined) return undefined
 
-	return is_pressured(before, after) ? 0 : after.available_mb
+	return (after.pressure_level ?? 0) >= PRESSURE_HOLD ? 0 : after.available_mb
 }
 
 // Memory is read at both ends of the window, so the swap counter's difference is the activity during it.
@@ -312,13 +324,13 @@ async function read_machine(
 	const before = cpu_times()
 	const [memory_before] = await Promise.all([read_memory(), sleep(SAMPLE_WINDOW_MS)])
 	const memory_after = await read_memory()
-	const busy_cores = is_unquoted()
-		? busy_cores_between(before, cpu_times(), cpus().length)
-		: undefined
+	const is_host = is_unquoted()
+	const busy_cores = is_host ? busy_cores_between(before, cpu_times(), cpus().length) : undefined
 
 	return {
 		busy_cores,
-		available_mb: pressured_available(memory_before, memory_after),
+		run_queue: is_host ? loadavg()[0] : undefined,
+		available_mb: pressured_available(memory_after),
 		memory_pressured: is_pressured(memory_before, memory_after),
 	}
 }
@@ -327,31 +339,52 @@ async function read_sample(): Promise<MachineSample> {
 	return { cpu: cpu_times(), memory: await read_memory(), total_mb: totalmem() / BYTES_PER_MB }
 }
 
-// The busy cores the ledger does not account for, beyond the baseline the weights were measured beside,
-// in whole cores — the budget is in whole cores, and a fraction of a core is not a core to give up.
+// The busy cores the ledger does not account for, in whole cores — the budget is in whole cores, and a
+// fraction of a core is not a core to give up.
+//
+// **Every busy core counts, the background included** (joshuafolkken/kit#4238). A baseline of two cores
+// used to be exempt, so with 10 cores reserved and all 11 busy the reading saw no excess and admitted
+// another claim onto a saturated CPU.
 function external_cores(busy_cores: number | undefined, ledger_cores: number): number {
 	if (busy_cores === undefined) return 0
 
-	return Math.floor(Math.max(0, busy_cores - ledger_cores - BASELINE_CORES))
+	return Math.floor(Math.max(0, busy_cores - ledger_cores))
 }
 
-// **The budget the ledger admits against: what is free plus what the ledger itself already holds.**
-// The admitted reservations' load is inside the reading, and the admission walk counts their declared
-// weight again, so it is added back — what is subtracted is only the load from outside the ledger. The
-// caller passes every admitted claim's cores but only the memory of claims past
-// `core_admission.RAMP_UP_MS`, whose tools have had time to allocate.
+// The run queue beyond what the ledger declares, past `OVERLOAD_FACTOR` times the cores. The ledger's own
+// claims running past their weight count as outside load. The load average trails by a minute, so a
+// first waiter held here waits out the decay — only at a load already this far past the machine. A queue
+// that could not be read, and Windows' constant zero, never hold.
+function is_overloaded(
+	run_queue: number | undefined,
+	ledger_cores: number,
+	cores: number,
+): boolean {
+	if (run_queue === undefined) return false
+
+	return run_queue - ledger_cores > cores * OVERLOAD_FACTOR
+}
+
+// **The budget the ledger admits against: `cores − max(ledger, busy)` free, plus what the ledger itself
+// already holds.** The admission walk counts the ledger's declared weight again, so it is added back —
+// what is subtracted is only the busy load beyond it. A claim admitted moments ago is not busy yet, and
+// the ledger's declared cores cover it. The caller passes every admitted claim's cores but only the
+// memory of claims past `core_admission.RAMP_UP_MS`, whose tools have had time to allocate.
 // Memory that could not be read is no limit at all, the behavior before memory was read.
 function machine_budget(cores: number, reading: MachineReading, ledger: LedgerLoad): MachineBudget {
+	const busy_excess = external_cores(reading.busy_cores, ledger.cores)
+
 	return {
-		cores: cores - external_cores(reading.busy_cores, ledger.cores),
+		cores: Math.max(0, cores - busy_excess),
 		memory_mb:
 			reading.available_mb === undefined ? Infinity : reading.available_mb + ledger.memory_mb,
 		memory_pressured: reading.memory_pressured,
+		busy_excess,
+		is_overloaded: is_overloaded(reading.run_queue, ledger.cores, cores),
 	}
 }
 
 const machine_capacity = {
-	BASELINE_CORES,
 	busy_cores_between,
 	busy_share_between,
 	COMPRESSION_PRESSURE_MB,
@@ -360,6 +393,7 @@ const machine_capacity = {
 	parse_darwin_memory,
 	parse_linux_available,
 	parse_linux_swapped,
+	PRESSURE_HOLD,
 	pressured_available,
 	read_machine,
 	read_memory,

package/scripts/gate/moved-paths.ts

@@ -0,0 +1,67 @@
+import { git_spawn } from '#scripts/git/git-spawn'
+import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import type { GateTree } from './gate-tree'
+
+// Every path whose content can differ from the tree a green record was taken on — the one reading the
+// gate's per-check reuse (`check-reuse.ts`) and the scoped checks' since-green narrowing
+// (`since-green.ts`) both act on, so the two can never disagree about what moved.
+//
+// **What moved is the union of two diffs**. The changed-file map is a diff against the merge base, so a
+// path absent from both maps holds the merge base's content — and the base's own diff
+// (`git diff <recorded> <current>`) names every path that content moved for, which is what a main sync
+// brought in. A path in either map whose digest differs is the other half
+// (`file_map_stamp.changed_since`).
+
+const NAME_SEPARATOR = '\0'
+const BASE_DIFF = ['diff', '--name-only', '--no-renames', '-z'] as const
+
+async function base_diff(from: string, to: string): Promise<ReadonlyArray<string> | undefined> {
+	if (from === to) return []
+
+	try {
+		const names = await git_spawn.read([...BASE_DIFF, from, to])
+
+		return names.split(NAME_SEPARATOR).filter((name) => name !== '')
+	} catch {
+		return undefined
+	}
+}
+
+// The two diffs apart: `synced` is what a main sync brought in, `changed` the paths whose digest moved.
+// A path can be in both.
+interface MovedParts {
+	changed: ReadonlyArray<string>
+	synced: ReadonlyArray<string>
+}
+
+// `undefined` when the record cannot be compared: no base on either side, or a tree map that came back
+// empty — also what `gate-tree.ts` answers when git could not be read, so it describes no tree.
+async function moved_parts(stamp: FileMapStamp, tree: GateTree): Promise<MovedParts | undefined> {
+	const is_unread = Object.keys(tree.files).length === 0
+
+	if (is_unread || stamp.base === undefined || tree.base === undefined) return undefined
+
+	const synced = await base_diff(stamp.base, tree.base)
+
+	if (synced === undefined) return undefined
+
+	return { changed: file_map_stamp.changed_since(stamp, tree.files), synced }
+}
+
+function union_of(parts: MovedParts): ReadonlyArray<string> {
+	return [...new Set([...parts.changed, ...parts.synced])]
+}
+
+async function moved_since(
+	stamp: FileMapStamp,
+	tree: GateTree,
+): Promise<ReadonlyArray<string> | undefined> {
+	const parts = await moved_parts(stamp, tree)
+
+	return parts === undefined ? undefined : union_of(parts)
+}
+
+const moved_paths = { moved_parts, moved_since, union_of }
+
+export type { MovedParts }
+export { moved_paths }

package/scripts/gate/project-checks.ts

@@ -1,4 +1,4 @@
-import { existsSync, globSync, readFileSync } from 'node:fs'
+import { existsSync, globSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
@@ -6,10 +6,10 @@ import { own_formatter } from '#scripts/init/own-formatter'
 import { project_profile } from '#scripts/init/project-profile'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { NOT_USED_MARKER, SKIP_MARKER } from '#scripts/test/skip-marker'
 import { z } from 'zod'
 
-const PACKAGE_JSON = 'package.json'
 const IGNORED_DIRS = new Set([
 	'node_modules',
 	'.git',
@@ -48,7 +48,7 @@ const object_schema = z.record(z.string(), z.unknown())
 function project_root(directory: string): string {
 	return (
 		ancestor_directories.nearest(directory, (candidate) =>
-			existsSync(path.join(candidate, PACKAGE_JSON)),
+			existsSync(package_manifest.manifest_path(candidate)),
 		) ?? directory
 	)
 }
@@ -86,16 +86,9 @@ function is_basic_manifest(manifest: unknown): boolean {
 	return project_profile.parse_profile(josh['profile']) === 'basic'
 }
 
-// The try covers the read alone — a missing or unreadable manifest — since the parse already answers
-// `undefined` for text that is not JSON.
+// A missing, unreadable or non-JSON manifest answers `undefined`; the shape is each caller's question.
 function read_manifest(directory: string): unknown {
-	try {
-		const manifest_path = path.join(project_root(directory), PACKAGE_JSON)
-
-		return json_value.parse_or_undefined(readFileSync(manifest_path, 'utf8'))
-	} catch {
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(project_root(directory), z.unknown())
 }
 
 function is_basic(directory: string): boolean {

package/scripts/gate/scoped-green.ts

@@ -12,14 +12,14 @@ import { gate_tree, type GateTree } from './gate-tree'
 // tree neither check has read return their findings one round trip at a time; one call running both
 // checks first returns most of them at once.
 //
-// **It fixes when the checks run, never whether they run, and never what they check.** Nothing here
-// skips a check, narrows one, or reinterprets its output — a green record buys ordering and nothing
-// else, and `josh gate` still runs its four checks exactly as before. It never *reuses* a scoped
-// check's result in place of re-running it.
+// **It fixes when the checks run, never whether they run.** Nothing here skips a check or
+// reinterprets its output, and `josh gate` still runs its four checks exactly as before. The one other
+// reader is the checks' own re-run, which narrows to what moved since this record (`since-green.ts`).
 //
 // **The judgement is the gate's own, not a second one.** "There is a record and nothing it covers has
 // moved" is `review_brief.matching_stamp` plus the base equality `gate_skip.reusable_green_gate`
-// already compares, over the same `FileMapStamp` shape written to the same kind of file. A second
+// already compares and the inputs fingerprint each record carries (`verification-inputs.ts`), over the
+// same `FileMapStamp` shape written to the same kind of file. A second
 // definition of "this tree is unchanged" is the clone `CLAUDE.md` prohibits, and it is exactly where
 // two commands would start disagreeing about one working tree.
 //
@@ -95,7 +95,11 @@ function checks_of(sources: ScopedSources): ReadonlyArray<ScopedCheck> {
 function describes_tree(check: ScopedCheck, tree: Record<string, string>, base: string): boolean {
 	const stamp = review_brief.matching_stamp(check.stamp.read(check.source), tree)
 
-	return stamp !== undefined && file_map_stamp.describes_base(stamp, base)
+	return (
+		stamp !== undefined &&
+		file_map_stamp.describes_base(stamp, base) &&
+		check.stamp.describes_inputs(stamp)
+	)
 }
 
 // **Whether there is a tree to speak about at all**, asked once and used from both ends: the reader
@@ -161,8 +165,8 @@ function refusal(missing: ReadonlyArray<string>): string {
 		'282 seconds, 31% of the run, picking up one lint rule and one failing test at a time after its ' +
 		'review had already started. Run them in one call — ' +
 		`\`${LINT_COMMAND} && ${TEST_COMMAND}\`, measured at 13.8 seconds — and reissue this command. ` +
-		'The record fixes when the checks run and never whether they run: nothing is skipped, narrowed ' +
-		'or reused because of it. `prompts/review.md` → "The scoped checks answer on the last edit".'
+		'The record fixes when the checks run and never whether they run: nothing is skipped or reused ' +
+		'because of it. `prompts/review.md` → "The scoped checks answer on the last edit".'
 	)
 }
 

package/scripts/gate/since-green.ts

@@ -0,0 +1,62 @@
+import type { FileMapStampAccess } from '#scripts/josh/file-map-stamp'
+import { gate_tree } from './gate-tree'
+import { moved_paths, type MovedParts } from './moved-paths'
+import { verification_inputs } from './verification-inputs'
+
+// **A scoped check re-run reads only what moved since its last green run on this checkout**
+// (joshuafolkken/kit#4393). A lane's ship retry — after a review fix or a preflight stop — re-ran
+// `josh lint:related` and `josh test:related` (the gate's unit step too) over the whole branch diff,
+// though everything outside the fix had been green on the tree before it.
+//
+// **The check is no weaker.** The green record (`scoped-green.ts`) vouches that the check passed over
+// the branch diff of the tree it names; what moved since is every path whose content can differ from
+// that tree (`moved-paths.ts`), a main sync's own changes included. A record written by a narrowed run
+// vouches for the same thing, by the same argument one run earlier.
+//
+// **Whatever cannot be narrowed answers `undefined`**, and the caller reads the whole branch change as
+// before: no record, one that cannot be compared, one written under other tools or environment, or a
+// moved file the check's declaration names a configuration — a file green under the old configuration
+// says nothing under the new one. An empty list is
+// the positive fact that nothing moved: the gate's unit step on the tree the preflight just passed.
+
+// The narrowing line each command prints before it runs, so a since-green run is never read as one
+// over the whole branch.
+function describe(label: string, moved: ReadonlyArray<string>): string {
+	return `${label}: reading only the ${String(moved.length)} file(s) changed since its last green run on this checkout.`
+}
+
+function is_narrowable(label: string, parts: MovedParts | undefined): parts is MovedParts {
+	return parts !== undefined && !verification_inputs.configures(label, moved_paths.union_of(parts))
+}
+
+// What moved with a main sync's part kept apart, for a caller that records how much of its input the
+// sync brought in (`josh test:related`, joshuafolkken/kit#4465). `label` names the gate check whose
+// declaration (`verification-inputs.ts`) the record vouches for.
+async function read_moved_parts(
+	stamp: FileMapStampAccess,
+	label: string,
+	source?: string,
+): Promise<MovedParts | undefined> {
+	const record = stamp.read(source)
+
+	if (record === undefined || !stamp.describes_inputs(record)) return undefined
+
+	const parts = await moved_paths.moved_parts(record, await gate_tree.read_gate_tree())
+
+	return is_narrowable(label, parts) ? parts : undefined
+}
+
+// Repository-root-relative paths, or `undefined` when the caller has to read the whole branch change.
+async function read_moved(
+	stamp: FileMapStampAccess,
+	label: string,
+	source?: string,
+): Promise<ReadonlyArray<string> | undefined> {
+	const parts = await read_moved_parts(stamp, label, source)
+
+	return parts === undefined ? undefined : moved_paths.union_of(parts)
+}
+
+const since_green = { describe, read_moved, read_moved_parts }
+
+export { since_green }

package/scripts/gate/toolchain-inputs.ts

@@ -0,0 +1,115 @@
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// **The toolchain's inputs, listed once** (joshuafolkken/kit#4496): the files whose content moves what
+// a tool answers while every source stays byte-identical — the installed packages, the eslint config
+// and the TypeScript program's options. Every result kept across runs is discarded when they move:
+// the metrics base cache (`metrics-base-cache.ts`), the hook bundles (`hook-bundle-stamp.ts`), the
+// warm ESLint daemon (`eslint-daemon.ts`) and the gate's verdicts (`verification-inputs.ts`). A file
+// added here reaches all of them.
+//
+// Loaded by plain `node` on every hook launch (`tools/hooks/hook-bundle-ready.ts`), so this module
+// imports `node:` built-ins alone.
+
+// The package manager's manifest, lock and settings files, and the record pnpm rewrites on every
+// install — a consumer's eslint config imports its rules from installed packages.
+const PACKAGE_FILES: ReadonlyArray<string> = [
+	'package.json',
+	'pnpm-lock.yaml',
+	'pnpm-workspace.yaml',
+	'package-lock.json',
+	'yarn.lock',
+	'bun.lock',
+	'bun.lockb',
+	'.npmrc',
+	'node_modules/.modules.yaml',
+]
+// The root entries of the eslint flat config and of the TypeScript program, and the directories of
+// the rule modules and the shared compiler options they import.
+const CONFIG_ENTRIES: ReadonlyArray<RegExp> = [
+	/^eslint\.config\.[cm]?[jt]s$/u,
+	/^tsconfig(?:\.[\w-]+)?\.json$/u,
+]
+const CONFIG_DIRECTORIES: ReadonlySet<string> = new Set(['eslint', 'tsconfig'])
+// A test beside the rule modules configures nothing.
+const TEST_MARKER = '.test.'
+const SEPARATOR = '/'
+const DIGEST_ALGORITHM = 'sha256'
+
+// Code-unit order, so the digest does not depend on the locale of the machine that computes it.
+function by_code_unit(left: string, right: string): number {
+	if (left === right) return 0
+
+	return left < right ? -1 : 1
+}
+
+function to_posix(relative: string): string {
+	return relative.split(path.sep).join(SEPARATOR)
+}
+
+function is_config_entry(name: string): boolean {
+	return CONFIG_ENTRIES.some((entry) => entry.test(name))
+}
+
+function is_config_module(relative: string): boolean {
+	const [top = ''] = relative.split(SEPARATOR, 1)
+
+	return CONFIG_DIRECTORIES.has(top) && !path.basename(relative).includes(TEST_MARKER)
+}
+
+// Whether the root-relative `relative` is a toolchain input.
+function is_input(relative: string): boolean {
+	const posix = to_posix(relative)
+	if (PACKAGE_FILES.includes(posix)) return true
+
+	return is_config_entry(posix) || is_config_module(posix)
+}
+
+// Files only: a directory moves on every entry created in it, an editor's temp file too.
+function modules_under(root: string, directory: string): ReadonlyArray<string> {
+	const absolute = path.join(root, directory)
+	if (!existsSync(absolute)) return []
+
+	return readdirSync(absolute, { recursive: true, withFileTypes: true })
+		.filter((entry) => entry.isFile())
+		.map((entry) => to_posix(path.relative(root, path.join(entry.parentPath, entry.name))))
+		.filter((relative) => is_config_module(relative))
+}
+
+// The root-relative toolchain inputs present under `root`, in code-unit order.
+function paths(root: string): ReadonlyArray<string> {
+	const present = PACKAGE_FILES.filter((relative) => existsSync(path.join(root, relative)))
+	const entries = readdirSync(root).filter((name) => is_config_entry(name))
+	const modules = [...CONFIG_DIRECTORIES].flatMap((directory) => modules_under(root, directory))
+
+	return [...present, ...entries, ...modules].toSorted(by_code_unit)
+}
+
+function read_or_empty(file: string): Uint8Array {
+	try {
+		return readFileSync(file)
+	} catch {
+		return new Uint8Array()
+	}
+}
+
+// **The fingerprint of the toolchain under `root`**: each input's path and content, in code-unit
+// order, so an added, removed, renamed or edited input changes it. A file gone between the listing
+// and its read hashes as empty.
+function digest(root: string): string {
+	const hash = createHash(DIGEST_ALGORITHM)
+
+	for (const relative of paths(root)) {
+		hash
+			.update(`${relative}\0`)
+			.update(read_or_empty(path.join(root, relative)))
+			.update('\0')
+	}
+
+	return hash.digest('hex')
+}
+
+const toolchain_inputs = { digest, is_input, PACKAGE_FILES, paths }
+
+export { toolchain_inputs }

package/scripts/gate/verification-gate.ts

@@ -9,7 +9,6 @@ import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { check_reuse, type CheckRecords } from './check-reuse'
-import { free_cores } from './free-cores'
 import { gate_ledger, type GateLedgerStart } from './gate-ledger'
 import { gate_plan, type GatePlan } from './gate-plan'
 import { gate_report, type GateStepResult } from './gate-report'
@@ -165,21 +164,19 @@ async function run_marked_gate<T>(
 // The concurrent-run count is read here rather than inside `gate-plan.ts` for the reason the core
 // count already is: that module stays a pure function of its inputs, and the machine is asked once and
 // handed to both calls. Counted *before* the unit step writes its own marker, so `+ 1` is this gate.
-// `free` bounds the unit cap the run count produced (`gate_plan.bound_by_free`).
-function announce_gate_plan(
-	is_unit_included: boolean,
-	available_cores: number,
-	free: number | undefined,
-): GatePlan {
+//
+// **The free cores do not cap the plan** (joshuafolkken/kit#4167). The unit claim's admission narrows it
+// to the room the outside load leaves, read over its wait rather than once at the gate's start — a
+// width fixed off one busy instant held for the whole suite (`core_admission.is_too_narrow`).
+function announce_gate_plan(is_unit_included: boolean, available_cores: number): GatePlan {
 	const concurrent_runs = unit_worker_share.live_run_count() + unit_worker_share.SOLO_RUNS
 	const is_kit_repository = project_checks.is_kit_repository(process.cwd())
-	const resolved = gate_plan.resolve_gate_plan(
+	const plan = gate_plan.resolve_gate_plan(
 		available_cores,
 		concurrent_runs,
 		is_unit_included,
 		is_kit_repository,
 	)
-	const plan = gate_plan.bound_by_free(resolved, available_cores, free)
 
 	process.stdout.write(`${gate_plan.format_gate_plan(plan, available_cores, concurrent_runs)}\n`)
 
@@ -217,10 +214,6 @@ interface GateOptions {
 	// Where each check's own green record lives (`check-reuse.ts`). Only the CLI entry resolves it, for
 	// the ledger's reason: a suite whose checks never ran must not record them green on the live tree.
 	check_records?: CheckRecords | undefined
-	// The cores free of load from outside the core budget's ledger (`free-cores.ts`). Only the CLI entry
-	// resolves it, for the ledger's reason: a suite driving the gate never reads the machine, so its plan
-	// does not depend on what else happened to be running.
-	read_free_cores?: ((available_cores: number) => Promise<number | undefined>) | undefined
 }
 
 // **Per-check records belong to the full local gate alone**: CI's `--no-unit` gate is the safety net
@@ -325,9 +318,7 @@ async function run_checked_gate(
 	// Resolved at the gate's entry, before this gate sets `JOSH_UNIT_RUN_MARKED`, so a gate nested in the
 	// unit suite reads the flag as set and reserves nothing.
 	const budget = gate_run_steps.default_budget()
-	// Read before the count for the ledger's reason: the reading waits out a sample window.
-	const free = await options.read_free_cores?.(budget.available_cores)
-	const plan = announce_gate_plan(is_unit_included, budget.available_cores, free)
+	const plan = announce_gate_plan(is_unit_included, budget.available_cores)
 	const reused = await checks_to_reuse(plan, tree, options)
 
 	// **The gate holds the unit-run marker for its whole run, not just its unit step.** The step that
@@ -353,17 +344,30 @@ function reusable_stamp(tree: GateTree, options: GateOptions): FileMapStamp | un
 	return gate_skip.reusable_green_gate(tree.files, tree.base, options.stamp_path)
 }
 
+// The reuse leaves its line in the ledger too, so `josh lane:stats` counts the gates it saved
+// (joshuafolkken/kit#4397).
+async function reuse_gate(
+	stamp: FileMapStamp,
+	options: GateOptions,
+	started_at: number,
+): Promise<number> {
+	process.stdout.write(`${gate_skip.format_skip(stamp.taken_at)}\n`)
+	await gate_ledger.record_reused(options.ledger_path, performance.now() - started_at)
+
+	return 0
+}
+
 // The two ways a gate ends before it runs a check: a green record it can reuse (exit 0), and the
 // scoped pre-check refusing a tree the pair has not been green on (exit 1). `undefined` means neither
 // fired and the checks run. **Nothing else stands between the skip and the checks.**
-function short_circuit_gate(tree: GateTree, options: GateOptions): number | undefined {
+async function short_circuit_gate(
+	tree: GateTree,
+	options: GateOptions,
+	started_at: number,
+): Promise<number | undefined> {
 	const reusable = reusable_stamp(tree, options)
 
-	if (reusable !== undefined) {
-		process.stdout.write(`${gate_skip.format_skip(reusable.taken_at)}\n`)
-
-		return 0
-	}
+	if (reusable !== undefined) return await reuse_gate(reusable, options, started_at)
 
 	const scoped_refusal = scoped_precheck_refusal(tree, options)
 
@@ -379,7 +383,7 @@ async function run_verification_gate(options: GateOptions = {}): Promise<number>
 	// four checks alone took — the gate's own bookkeeping is part of the wait either way.
 	const started_at = performance.now()
 	const tree = await gate_tree.read_gate_tree()
-	const short_circuit = short_circuit_gate(tree, options)
+	const short_circuit = await short_circuit_gate(tree, options, started_at)
 
 	if (short_circuit !== undefined) return short_circuit
 
@@ -438,7 +442,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX), {
 		ledger_path: await lane_ledger.target(),
 		check_records: check_reuse.DEFAULT_RECORDS,
-		read_free_cores: async (available_cores) => await free_cores.read({ available_cores }),
 	})
 }