@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/gate/core-admission.ts

@@ -0,0 +1,162 @@
+import type { LedgerLoad, MachineBudget } from './machine-capacity'
+
+// The ledger's admission arithmetic, kept apart from the markers `core-budget.ts` reads and writes so
+// that file stays under its line ceiling as the budget grew a memory side (joshuafolkken/kit#3371).
+// Everything here is a pure function of the ledger it is handed.
+
+const MS_PER_SECOND = 1000
+// **How long an admitted claim's tool takes to reach its declared peak.** The machine reading holds only
+// what a tool has already allocated, so a claim admitted moments ago is not in it yet: adding its
+// declared memory back would admit the next claim into memory about to be taken — the concurrent start
+// this ledger exists to stop. Until the window passes, the claim's memory counts only in the FIFO walk; a
+// tool partway up is then counted twice, which costs a slower admission, never a swap. Its cores are in
+// the reading from the start, so the window does not apply to them.
+const RAMP_UP_MS = 30_000
+
+// What admission reads from a marker. `memory_mb` and `admitted_at` are optional because a marker an
+// older `josh` wrote has neither: it declares no memory, and it counts as load from outside the ledger.
+interface LedgerReservation {
+	weight: number
+	claimed_at: number
+	memory_mb?: number | undefined
+	admitted_at?: number | undefined
+}
+
+interface LedgerEntry {
+	// The marker's filename, which is its identity in the ledger and the tiebreak when two reservations
+	// share a claim time.
+	key: string
+	reservation: LedgerReservation
+}
+
+// A claim admitted at the wait cap rather than by room in the budget — the run went ahead past the
+// budget, and the gate's summary says so.
+interface Overflow {
+	waited_ms: number
+	ledger: LedgerLoad
+	budget: MachineBudget
+}
+
+interface Admission {
+	overflow: Overflow | undefined
+}
+
+// Claim order, with the filename as the tiebreak so every reader agrees on the same ledger order
+// however the wall clock rounded two near-simultaneous claims.
+function compare_claim(left: LedgerEntry, right: LedgerEntry): number {
+	const by_time = left.reservation.claimed_at - right.reservation.claimed_at
+
+	return by_time === 0 ? left.key.localeCompare(right.key) : by_time
+}
+
+function add_load(totals: LedgerLoad, reservation: LedgerReservation): void {
+	totals.cores += reservation.weight
+	totals.memory_mb += reservation.memory_mb ?? 0
+}
+
+function exceeds(totals: LedgerLoad, budget: MachineBudget): boolean {
+	return totals.cores > budget.cores || totals.memory_mb > budget.memory_mb
+}
+
+// **The keys admitted under FIFO.** The head always runs — a single check heavier than the whole
+// machine must not wait for room that will never come — and each later reservation runs while the
+// cumulative weight ahead of it still fits the budget. The first that does not fit stops the walk, so a
+// place is never jumped: admission is in claim order, which is what removes the start-time asymmetry.
+// Memory is walked the same way, so a claim whose tool would not fit in free memory waits like one whose
+// cores would not fit (joshuafolkken/kit#3371).
+function admitted_keys(
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: number,
+	memory_budget = Infinity,
+): Set<string> {
+	const limit = { cores: budget, memory_mb: memory_budget }
+	const totals = { cores: 0, memory_mb: 0 }
+	const admitted = new Set<string>()
+
+	for (const [index, entry] of reservations.toSorted(compare_claim).entries()) {
+		add_load(totals, entry.reservation)
+
+		if (index !== 0 && exceeds(totals, limit)) break
+
+		admitted.add(entry.key)
+	}
+
+	return admitted
+}
+
+function is_admitted(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: MachineBudget,
+): boolean {
+	return admitted_keys(reservations, budget.cores, budget.memory_mb).has(key)
+}
+
+function sum_load(reservations: ReadonlyArray<LedgerEntry>): LedgerLoad {
+	const load = { cores: 0, memory_mb: 0 }
+
+	for (const entry of reservations) add_load(load, entry.reservation)
+
+	return load
+}
+
+function is_ramped(reservation: LedgerReservation, now: number): boolean {
+	const { admitted_at } = reservation
+
+	return admitted_at !== undefined && now - admitted_at >= RAMP_UP_MS
+}
+
+// **The load the ledger already accounts for.** CPU use shows in the reading the moment a tool starts,
+// so every admitted claim's cores count at once; memory grows as the tool allocates, so only the claims
+// admitted long enough ago to be in the reading count their memory.
+function ledger_load(reservations: ReadonlyArray<LedgerEntry>, now: number): LedgerLoad {
+	const admitted = reservations.filter((entry) => entry.reservation.admitted_at !== undefined)
+	const ramped = admitted.filter((entry) => is_ramped(entry.reservation, now))
+
+	return { cores: sum_load(admitted).cores, memory_mb: sum_load(ramped).memory_mb }
+}
+
+function total_weight(reservations: ReadonlyArray<LedgerEntry>): number {
+	return sum_load(reservations).cores
+}
+
+// The weight actually running at once — what the reproduction test asserts stays within the budget.
+function admitted_load(reservations: ReadonlyArray<LedgerEntry>, budget: number): number {
+	const admitted = admitted_keys(reservations, budget)
+
+	return total_weight(reservations.filter((entry) => admitted.has(entry.key)))
+}
+
+// The memory side of an overflow, so a claim held back by memory is not reported as a core shortfall.
+// A budget that read no memory set no memory limit, and says nothing.
+function describe_memory(ledger: LedgerLoad, budget: MachineBudget): string {
+	if (!Number.isFinite(budget.memory_mb)) return ''
+
+	return ` and ${String(Math.round(ledger.memory_mb))} MB of memory against ${String(Math.round(budget.memory_mb))} MB`
+}
+
+// The summary line for a claim admitted past the budget, or undefined for one that fitted.
+function describe_overflow(admission: Admission): string | undefined {
+	const { overflow } = admission
+
+	if (overflow === undefined) return undefined
+
+	const { ledger, budget } = overflow
+	const waited = String(Math.round(overflow.waited_ms / MS_PER_SECOND))
+	const cores = `the ledger held ${String(ledger.cores)} cores against a budget of ${String(budget.cores)}`
+
+	return `started past the core budget after ${waited}s — ${cores}${describe_memory(ledger, budget)}`
+}
+
+const core_admission = {
+	RAMP_UP_MS,
+	admitted_keys,
+	admitted_load,
+	describe_overflow,
+	is_admitted,
+	ledger_load,
+	sum_load,
+}
+
+export type { Admission, LedgerEntry, Overflow }
+export { core_admission }

package/scripts/gate/core-budget.ts

@@ -6,7 +6,10 @@ 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'
+import { core_admission, type Admission, type LedgerEntry, type Overflow } from './core-admission'
+import { machine_capacity, type MachineBudget, type MachineReading } from './machine-capacity'
 
 // A machine-wide weighted core budget with admission control (joshuafolkken/kit#2351).
 //
@@ -33,6 +36,11 @@ import { z } from 'zod'
 // killed outright leaves its marker behind, and a ledger that trusted the file alone would fill forever
 // and admit nothing. The pid-and-start-time pair a marker carries is the same identity the unit-run
 // marker keeps, swept on read the moment its process is gone.
+//
+// **The budget is what the machine has free, in cores and in memory** (joshuafolkken/kit#3371). The
+// core count stays the ceiling, but load from outside the ledger is subtracted from it, and a claim
+// waits while the memory its tool holds is not free — `machine-capacity.ts` reads both. A claim marks
+// its marker admitted once it runs, so the reading's load is split into the ledger's and the rest.
 
 const RESERVED_PREFIX = 'josh-core-reserved-'
 const RESERVED_SUFFIX = '.json'
@@ -46,22 +54,60 @@ 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 memory each heavy tool holds, declared beside its cores** (joshuafolkken/kit#3371): peak
+// resident size in MB, rounded up. Measured with `/usr/bin/time -l` on the 11-core / 18 GB machine on
+// 2026-10-07: the type check 1,244 MB, the spell check 330 MB, and one unit worker 319 MB over 54 test
+// files. Typed eslint was 1,207 MB over one directory and was observed at 1.6–2.4 GB per whole-tree
+// `eslint .` with three lanes running the same day, so lint and the whole-tree scan take that peak.
+const MEMORY_MB = {
+	lint: 2400,
+	type_check: 1300,
+	spell_check: 350,
+	eslint_scan: 2400,
+	unit_worker: 350,
+} 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'
+
+// `memory_mb` and `admitted_at` are optional so a marker an older `josh` wrote still reads: it holds no
+// declared memory, and it counts as load from outside the ledger until it is gone.
 const reservation_schema = process_owner_schema.extend({
 	weight: z.number(),
 	claimed_at: z.number(),
+	memory_mb: z.number().optional(),
+	admitted_at: z.number().optional(),
 })
 
 type Reservation = z.infer<typeof reservation_schema>
 
-interface LiveReservation {
-	// The marker's filename, which is its identity in the ledger and the tiebreak when two reservations
-	// share a claim time.
-	key: string
+type ReservationFields = Pick<Reservation, 'weight' | 'claimed_at' | 'memory_mb' | 'admitted_at'>
+
+interface LiveReservation extends LedgerEntry {
 	reservation: Reservation
 }
 
 interface ReserveOptions {
 	budget?: number
+	memory_mb?: number | undefined
+	read_machine?: () => Promise<MachineReading>
 	wait_cap_ms?: number
 	poll_interval_ms?: number
 	directory?: string
@@ -71,6 +117,7 @@ interface ReserveOptions {
 
 interface Handle {
 	target: string
+	admission: Admission
 }
 
 function marker_name(key: string): string {
@@ -120,10 +167,13 @@ function live_reservation(source: string): Reservation | undefined {
 }
 
 // An unreadable temp directory answers "no other reservation", the direction that admits rather than
-// stalls a run on a guess.
+// stalls a run on a guess. The suffix leaves out `replace_stamp`'s in-flight temporary copy of a marker,
+// which would otherwise count one place twice.
 function marker_files(directory: string): Array<string> {
 	try {
-		return readdirSync(directory).filter((name) => name.startsWith(RESERVED_PREFIX))
+		return readdirSync(directory).filter(
+			(name) => name.startsWith(RESERVED_PREFIX) && name.endsWith(RESERVED_SUFFIX),
+		)
 	} catch {
 		return []
 	}
@@ -133,54 +183,10 @@ 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 }
 	})
 }
 
-// Claim order, with the filename as the tiebreak so every reader agrees on the same ledger order
-// however the wall clock rounded two near-simultaneous claims.
-function compare_claim(left: LiveReservation, right: LiveReservation): number {
-	const by_time = left.reservation.claimed_at - right.reservation.claimed_at
-
-	return by_time === 0 ? left.key.localeCompare(right.key) : by_time
-}
-
-// **The keys admitted under FIFO.** The head always runs — a single check heavier than the whole
-// machine must not wait for room that will never come — and each later reservation runs while the
-// cumulative weight ahead of it still fits the budget. The first that does not fit stops the walk, so a
-// place is never jumped: admission is in claim order, which is what removes the start-time asymmetry.
-function admitted_keys(reservations: ReadonlyArray<LiveReservation>, budget: number): Set<string> {
-	const admitted = new Set<string>()
-	let cumulative = 0
-
-	for (const [index, entry] of reservations.toSorted(compare_claim).entries()) {
-		cumulative += entry.reservation.weight
-
-		if (index !== 0 && cumulative > budget) break
-
-		admitted.add(entry.key)
-	}
-
-	return admitted
-}
-
-function is_admitted(
-	key: string,
-	reservations: ReadonlyArray<LiveReservation>,
-	budget: number,
-): boolean {
-	return admitted_keys(reservations, budget).has(key)
-}
-
-// The weight actually running at once — what the reproduction test asserts stays within the budget.
-function admitted_load(reservations: ReadonlyArray<LiveReservation>, budget: number): number {
-	const admitted = admitted_keys(reservations, budget)
-
-	return reservations
-		.filter((entry) => admitted.has(entry.key))
-		.reduce((total, entry) => total + entry.reservation.weight, 0)
-}
-
 // `Math.max` propagates `NaN` rather than clamping it, so an unusable budget is caught before it could
 // make every comparison false and admit everything — the hole `gate-plan.ts` closes for the same reason.
 function normalize_budget(budget: number): number {
@@ -193,23 +199,30 @@ async function default_sleep(ms: number): Promise<void> {
 	})
 }
 
-function write_reservation(target: string, weight: number, claimed_at: number): void {
-	stamp_file.write_stamp(target, { ...process_identity.own_fields(), weight, claimed_at })
+// **Replaced atomically, never unlinked and recreated**: the admitted rewrite lands on a marker other
+// lanes are polling, and a reader that hit the gap between an unlink and its create would see the ledger
+// without this place and admit past it.
+function write_reservation(target: string, fields: ReservationFields): void {
+	stamp_file.replace_stamp(target, { ...process_identity.own_fields(), ...fields })
 }
 
 // The clock and cadence a wait runs on, resolved apart from the ledger fields so `reserve` stays under
-// the complexity limit — each default is a branch, and six in one function is past it.
+// the complexity limit — each default is a branch.
 interface TimingConfig {
 	now: () => number
 	sleep: (ms: number) => Promise<void>
 	poll_interval_ms: number
+	wait_cap_ms: number
 }
 
 interface WaitContext extends TimingConfig {
+	read_machine: () => Promise<MachineReading>
 	key: string
+	target: string
 	directory: string
 	budget: number
 	deadline: number
+	fields: ReservationFields
 }
 
 function resolve_timing(options: ReserveOptions): TimingConfig {
@@ -217,39 +230,96 @@ function resolve_timing(options: ReserveOptions): TimingConfig {
 		now: options.now ?? Date.now,
 		sleep: options.sleep ?? default_sleep,
 		poll_interval_ms: options.poll_interval_ms ?? POLL_INTERVAL_MS,
+		wait_cap_ms: options.wait_cap_ms ?? WAIT_CAP_MS,
+	}
+}
+
+// **A claim alone in the ledger reads nothing from the machine**: the head is admitted whatever the
+// budget says, so a solo run pays no sampling window and starts exactly as it did before.
+async function current_budget(
+	context: WaitContext,
+	reservations: ReadonlyArray<LiveReservation>,
+): Promise<MachineBudget> {
+	if (reservations.length <= 1) return { cores: context.budget, memory_mb: Infinity }
+
+	const reading = await context.read_machine()
+	const ledger = core_admission.ledger_load(reservations, context.now())
+	const budget = machine_capacity.machine_budget(context.budget, reading, ledger)
+
+	return { ...budget, cores: normalize_budget(budget.cores) }
+}
+
+// The claim is admitted: its marker records when, which moves its load from "load outside the ledger"
+// to "load the ledger holds" for every later reader — its cores at once, its memory once its tool has
+// had time to ramp up.
+function admit(context: WaitContext, overflow?: Overflow): Admission {
+	write_reservation(context.target, { ...context.fields, admitted_at: context.now() })
+
+	return { overflow }
+}
+
+function overflow_of(
+	context: WaitContext,
+	reservations: ReadonlyArray<LiveReservation>,
+	budget: MachineBudget,
+): Overflow {
+	return {
+		waited_ms: context.now() - context.fields.claimed_at,
+		ledger: core_admission.sum_load(reservations),
+		budget,
 	}
 }
 
+async function poll_admission(context: WaitContext): Promise<Admission | undefined> {
+	const reservations = live_reservations(context.directory)
+	const budget = await current_budget(context, reservations)
+
+	if (core_admission.is_admitted(context.key, reservations, budget)) return admit(context)
+
+	if (context.now() >= context.deadline) {
+		return admit(context, overflow_of(context, reservations, budget))
+	}
+
+	return undefined
+}
+
 // Poll the ledger until this reservation is admitted, or until the wait cap admits it at minimum width.
 // A solo run is admitted on the first read — its own claim is the ledger's head — so the loop body never
 // runs and the wait costs nothing.
-async function await_admission(context: WaitContext): Promise<void> {
-	while (!is_admitted(context.key, live_reservations(context.directory), context.budget)) {
-		if (context.now() >= context.deadline) return
+async function await_admission(context: WaitContext): Promise<Admission> {
+	let admission = await poll_admission(context)
 
+	while (admission === undefined) {
 		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await context.sleep(context.poll_interval_ms)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
+		admission = await poll_admission(context)
 	}
+
+	return admission
 }
 
 async function reserve(weight: number, options: ReserveOptions = {}): Promise<Handle> {
 	const timing = resolve_timing(options)
 	const directory = options.directory ?? PLATFORM_TEMP_ROOT
-	const budget = normalize_budget(options.budget ?? availableParallelism())
 	const claimed_at = timing.now()
 	const name = marker_name(randomUUID())
 	const target = path.join(directory, name)
+	const fields = { weight, claimed_at, memory_mb: options.memory_mb }
 
-	write_reservation(target, weight, claimed_at)
-	await await_admission({
+	write_reservation(target, fields)
+	const admission = await await_admission({
 		...timing,
 		key: name,
+		target,
 		directory,
-		budget,
-		deadline: claimed_at + (options.wait_cap_ms ?? WAIT_CAP_MS),
+		budget: normalize_budget(options.budget ?? availableParallelism()),
+		deadline: claimed_at + timing.wait_cap_ms,
+		fields,
+		read_machine: options.read_machine ?? machine_capacity.read_machine,
 	})
 
-	return { target }
+	return { target, admission }
 }
 
 function release(handle: Handle): void {
@@ -257,30 +327,82 @@ function release(handle: Handle): void {
 }
 
 // The whole reservation lifetime around a step: claim a place, wait for admission, run, and free the
-// place on any exit. `finally`, so a step that threw still releases its cores.
+// place on any exit. `finally`, so a step that threw still releases its cores. The step is told how it was
+// admitted, so the gate can report one that started past the budget.
 async function with_core_reservation<T>(
 	weight: number,
-	run: () => Promise<T>,
+	run: (admission: Admission) => Promise<T>,
 	options: ReserveOptions = {},
 ): Promise<T> {
 	const handle = await reserve(weight, options)
 
 	try {
-		return await run()
+		return await run(handle.admission)
 	} finally {
 		release(handle)
 	}
 }
 
+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,
+	MEMORY_MB,
 	RESERVED_PREFIX,
-	admitted_keys,
-	admitted_load,
+	admitted_keys: core_admission.admitted_keys,
+	admitted_load: core_admission.admitted_load,
+	describe_overflow: core_admission.describe_overflow,
+	is_held,
 	live_reservations,
 	release,
 	reserve,
+	with_command_reservation,
 	with_core_reservation,
+	with_held_mark,
 }
 
 export type { LiveReservation, Reservation, ReserveOptions }
 export { core_budget }
+
+export { type Admission } from './core-admission'

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).
@@ -35,6 +36,9 @@ 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
+	// none waited for (joshuafolkken/kit#3371). The unit suite's is per worker, so it is derived instead.
+	memory_mb?: number
 }
 
 const LINT_LABEL = 'lint'
@@ -61,15 +65,41 @@ 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,
+		memory_mb: core_budget.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,
+	},
+	{
+		label: 'cspell',
+		target: 'cspell:dot',
+		reserved_cores: core_budget.CORE_WEIGHTS.spell_check,
+		memory_mb: core_budget.MEMORY_MB.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 +272,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 +291,42 @@ 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)
+}
+
+function unit_memory(workers: number): number {
+	return workers * core_budget.MEMORY_MB.unit_worker
+}
+
+// The memory a check holds (joshuafolkken/kit#3371): its declared figure, or for the unit suite one
+// worker's peak for each core it reserves — its weight is its worker count.
+function check_memory(check: GateCheck, plan: GatePlan, available_cores: number): number {
+	if (check.label !== UNIT_LABEL) return check.memory_mb ?? 0
+
+	return unit_memory(check_weight(check, plan, 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)
+}
+
+// What a unit run started directly holds: one worker's peak for each worker `direct_unit_weight` gives it.
+function direct_unit_memory(): number {
+	return unit_memory(direct_unit_weight())
 }
 
 // `availableParallelism()` rather than `cpus().length`: it reports what this process may actually
@@ -344,7 +414,10 @@ const gate_plan = {
 	TYPE_CHECK_LABEL,
 	UNIT_LABEL,
 	WARNING_CHECKER_LABELS,
+	check_memory,
 	check_weight,
+	direct_unit_memory,
+	direct_unit_weight,
 	format_gate_plan,
 	format_machine,
 	has_unit_check,