@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/gate/core-budget-timing.ts

@@ -0,0 +1,37 @@
+// How often a waiting reservation re-reads the ledger: short enough that a freed place is taken up
+// promptly, long enough that the wait itself burns no measurable CPU.
+const POLL_INTERVAL_MS = 50
+// The longest a reservation waits before it is admitted at minimum width regardless — a heavy step must
+// make progress even if the budget never clears, so a leaked or wedged sibling cannot stall the machine
+// for good. Two minutes is well past a unit suite's worst measured time under six-way load. A claim a
+// swap stall holds is the exception (`core_admission.is_swap_held`).
+const WAIT_CAP_MS = 120_000
+
+// 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.
+interface TimingConfig {
+	now: () => number
+	sleep: (ms: number) => Promise<void>
+	poll_interval_ms: number
+	wait_cap_ms: number
+}
+
+async function default_sleep(ms: number): Promise<void> {
+	await new Promise<void>((resolve) => {
+		setTimeout(resolve, ms)
+	})
+}
+
+function resolve_timing(options: Partial<TimingConfig>): TimingConfig {
+	return {
+		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,
+	}
+}
+
+const core_budget_timing = { resolve_timing }
+
+export type { TimingConfig }
+export { core_budget_timing }

package/scripts/gate/core-budget.ts

@@ -9,8 +9,12 @@ import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { z } from 'zod'
+import { busy_average, type BusySample } from './busy-average'
 import { core_admission, type Admission, type LedgerEntry, type Overflow } from './core-admission'
+import { core_budget_timing, type TimingConfig } from './core-budget-timing'
 import { core_wait, type BudgetWait, type WaitReason } from './core-wait'
+import { core_wait_record, type WaitSink } from './core-wait-record'
+import { core_weights } from './core-weights'
 import { held_mark } from './held-mark'
 import { machine_capacity, type MachineBudget, type MachineReading } from './machine-capacity'
 
@@ -25,8 +29,9 @@ import { machine_capacity, type MachineBudget, type MachineReading } from './mac
 //
 // **A solo run is bit-for-bit unchanged, and that is arithmetic rather than a branch.** The gate's
 // weights are its `reserved_cores` (the static checks) and its `unit_worker_cap` (the unit suite), and
-// `reserved(2 + 1 + 1) + unit_cap(cores - 4)` is exactly `cores` — so a single gate's four claims sum
-// to the whole budget and every one is admitted the instant it is made, with no poll and no wait. Under
+// `reserved(2 + 2 + 2) + unit_cap(cores - 6)` is exactly `cores` — so a single gate's four claims sum
+// to the whole budget and, while the busy cores stay within what the ledger holds, every one is
+// admitted the instant it is made, with no poll and no wait. Under
 // concurrency the same weights sum past the budget and the ledger is what holds the machine down.
 //
 // **Liveness is `process_identity`'s, reused rather than re-invented.** A run
@@ -41,66 +46,21 @@ import { machine_capacity, type MachineBudget, type MachineReading } from './mac
 
 const RESERVED_PREFIX = 'josh-core-reserved-'
 const RESERVED_SUFFIX = '.json'
-// How often a waiting reservation re-reads the ledger: short enough that a freed place is taken up
-// promptly, long enough that the wait itself burns no measurable CPU.
-const POLL_INTERVAL_MS = 50
-// The longest a reservation waits before it is admitted at minimum width regardless — a heavy step must
-// make progress even if the budget never clears, so a leaked or wedged sibling cannot stall the machine
-// for good. Two minutes is well past a unit suite's worst measured time under six-way load.
-const WAIT_CAP_MS = 120_000
-// The head of the ledger is always admitted, so the smallest budget worth planning against is one core.
+// The head of an unsaturated ledger is always admitted, so the smallest declared budget is one core.
 const MIN_BUDGET = 1
 
-// **The cores each heavy tool occupies, declared once for both places that reserve them**
-// `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.
-//
-// The rest ran outside the ledger until joshuafolkken/kit#3944, measured with `/usr/bin/time -l` on the
-// same machine on 2026-10-17 under a load average of 16. Every one stays under one core, so each takes
-// one: `prettier --check` over 40 staged files 2.1s of CPU over 1.7s of wall (`format`), `josh
-// retrospective` 16.5s over 19.8s, and a fresh lane's `pnpm install --frozen-lockfile` 1.9s over 6.1s.
-// `e2e` is the Playwright worker count `josh test:e2e` passes locally — the two-worker run CI already
-// sizes for its four-core runner — since kit has no e2e suite of its own to time.
-const CORE_WEIGHTS = {
-	lint: 2,
-	type_check: 1,
-	spell_check: 1,
-	eslint_scan: 1,
-	format: 1,
-	retrospective: 1,
-	install: 1,
-	e2e: 2,
-} as const
-
-// **The memory each heavy tool holds, declared beside its cores**: 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.
-// On 2026-10-17: prettier 260 MB, the retrospective 862 MB and a lane install 65 MB.
-const MEMORY_MB = {
-	lint: 2400,
-	type_check: 1300,
-	spell_check: 350,
-	eslint_scan: 2400,
-	unit_worker: 350,
-	format: 300,
-	retrospective: 900,
-	install: 100,
-} as const
-
 // `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.
 // `command`, `checkout`, `lane`, `lanes_root` and `wait_reason` name a waiting claim on `run:board`
-// (`core-wait.ts`).
+// (`core-wait.ts`). `is_unit` marks a unit suite's claim, which may be admitted narrowed to `granted`
+// past the wait cap (`core_admission.narrowed_weight`).
 const reservation_schema = process_owner_schema.extend({
 	weight: z.number(),
 	claimed_at: z.number(),
 	memory_mb: z.number().optional(),
 	admitted_at: z.number().optional(),
+	is_unit: z.boolean().optional(),
+	granted: z.number().optional(),
 	command: z.string().optional(),
 	checkout: z.string().optional(),
 	lane: z.string().optional(),
@@ -121,6 +81,8 @@ interface ReserveOptions {
 	memory_mb?: number | undefined
 	// What the claim is for, named on the waiting line and on `run:board`.
 	command?: string | undefined
+	// A unit suite's claim, whose weight is its worker count.
+	is_unit?: boolean | undefined
 	report?: (line: string) => void
 	read_machine?: () => Promise<MachineReading>
 	wait_cap_ms?: number
@@ -128,6 +90,8 @@ interface ReserveOptions {
 	directory?: string
 	now?: () => number
 	sleep?: (ms: number) => Promise<void>
+	// Where a claim that waited records how long, once admitted (`core-wait-record.ts`).
+	record_wait?: WaitSink
 }
 
 interface Handle {
@@ -139,7 +103,7 @@ function marker_name(key: string): string {
 	return `${RESERVED_PREFIX}${key}${RESERVED_SUFFIX}`
 }
 
-// **"Cannot tell" counts as live**, the same direction `unit-worker-share.ts` takes: being wrong that
+// **"Cannot tell" counts as live**, the same direction `unit-run-marker.ts` takes: being wrong that
 // way costs a reservation a slower admission, while the other way admits past a run that is still there.
 function is_running(reservation: Reservation): boolean {
 	return process_identity.is_same_process(reservation.pid, reservation.process_start) !== false
@@ -155,7 +119,7 @@ function read_reservation(source: string): Reservation | undefined {
 
 // **A dead marker is removed, not merely skipped** — otherwise a reissued pid turns a leaked place into
 // a phantom that fills the budget for good. The unlink never throws: a marker this account may not
-// remove is left alone, exactly as `unit-worker-share.ts` leaves it.
+// remove is left alone, exactly as `unit-run-marker.ts` leaves it.
 function sweep_marker(source: string): void {
 	try {
 		stamp_file.remove_stamp(source)
@@ -202,12 +166,6 @@ function normalize_budget(budget: number): number {
 	return Number.isFinite(budget) ? Math.max(MIN_BUDGET, Math.floor(budget)) : MIN_BUDGET
 }
 
-async function default_sleep(ms: number): Promise<void> {
-	await new Promise<void>((resolve) => {
-		setTimeout(resolve, ms)
-	})
-}
-
 // **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.
@@ -219,57 +177,52 @@ function report_wait(line: string): void {
 	process.stderr.write(`${line}\n`)
 }
 
-// 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.
-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>
 	report: (line: string) => void
+	record_wait: WaitSink | undefined
 	key: string
 	target: string
 	directory: string
 	budget: number
 	deadline: number
 	fields: ReservationFields
+	busy_samples: Array<BusySample>
 }
 
-function resolve_timing(options: ReserveOptions): TimingConfig {
-	return {
-		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.
+// **A claim alone in the ledger reads the machine too** (joshuafolkken/kit#4238): load outside the
+// ledger saturates the CPU whether or not another claim is in it. The busy cores are the mean of this
+// wait's recent readings of load outside the ledger (`busy-average.ts`). That load holds every claim but
+// the first waiter, which it narrows instead (`core_admission.is_admitted`, joshuafolkken/kit#4313) unless
+// the run queue reads the machine overloaded (`machine_capacity.machine_budget`, joshuafolkken/kit#4361).
 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) }
+	context.busy_samples = busy_average.with_reading(
+		context.busy_samples,
+		reading,
+		ledger.cores,
+		context.now(),
+	)
+
+	const mean = busy_average.averaged(reading, context.busy_samples, ledger.cores)
+
+	return machine_capacity.machine_budget(context.budget, mean, ledger)
 }
 
 // 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() })
+function admit(context: WaitContext, overflow?: Overflow, granted?: number): Admission {
+	const admitted_at = context.now()
 
-	return { overflow }
+	write_reservation(context.target, { ...context.fields, admitted_at, granted })
+
+	return { overflow, granted, waited_ms: admitted_at - context.fields.claimed_at }
 }
 
 function overflow_of(
@@ -300,14 +253,24 @@ function mark_waiting(context: WaitContext, reason: WaitReason): void {
 async function poll_admission(context: WaitContext): Promise<Admission | undefined> {
 	const reservations = live_reservations(context.directory)
 	const budget = await current_budget(context, reservations)
+	// A unit claim is admitted at the room the budget leaves rather than at full width — the first
+	// waiter, which load outside the ledger does not hold, as well as one past the wait cap.
+	const granted = core_admission.narrowed_weight(context.key, reservations, budget.cores)
+	const reason = core_wait.hold_reason(context.key, reservations, budget, granted)
+
+	if (reason === undefined) return admit(context, undefined, granted)
 
-	if (core_admission.is_admitted(context.key, reservations, budget)) return admit(context)
+	// Past the cap a held claim runs regardless, except one a swap stall holds.
+	if (
+		context.now() >= context.deadline &&
+		!core_admission.is_swap_held(context.key, reservations, budget)
+	) {
+		const held = core_admission.with_grant(context.key, reservations, granted)
 
-	if (context.now() >= context.deadline) {
-		return admit(context, overflow_of(context, reservations, budget))
+		return admit(context, overflow_of(context, held, budget), granted)
 	}
 
-	mark_waiting(context, core_wait.wait_reason(context.key, reservations, budget))
+	mark_waiting(context, reason)
 
 	return undefined
 }
@@ -325,14 +288,19 @@ async function await_admission(context: WaitContext): Promise<Admission> {
 		admission = await poll_admission(context)
 	}
 
+	await core_wait_record.record_admitted(context.fields, context.now(), context.record_wait)
+
 	return admission
 }
 
-// What a wait reads the machine through and reports its start to.
-function resolve_ports(options: ReserveOptions): Pick<WaitContext, 'read_machine' | 'report'> {
+// What a wait reads the machine through, reports its start to and records its length in.
+function resolve_ports(
+	options: ReserveOptions,
+): Pick<WaitContext, 'read_machine' | 'report' | 'record_wait'> {
 	return {
 		read_machine: options.read_machine ?? machine_capacity.read_machine,
 		report: options.report ?? report_wait,
+		record_wait: options.record_wait,
 	}
 }
 
@@ -343,13 +311,13 @@ function claim_fields(
 	claimed_at: number,
 	options: ReserveOptions,
 ): ReservationFields {
-	const { memory_mb, command } = options
+	const { memory_mb, command, is_unit } = options
 
-	return { weight, claimed_at, memory_mb, command, ...core_wait.where_of(process.cwd()) }
+	return { weight, claimed_at, memory_mb, command, is_unit, ...core_wait.where_of(process.cwd()) }
 }
 
 async function reserve(weight: number, options: ReserveOptions = {}): Promise<Handle> {
-	const timing = resolve_timing(options)
+	const timing = core_budget_timing.resolve_timing(options)
 	const directory = options.directory ?? PLATFORM_TEMP_ROOT
 	const claimed_at = timing.now()
 	const name = marker_name(randomUUID())
@@ -365,6 +333,7 @@ async function reserve(weight: number, options: ReserveOptions = {}): Promise<Ha
 		budget: normalize_budget(options.budget ?? availableParallelism()),
 		deadline: claimed_at + timing.wait_cap_ms,
 		fields,
+		busy_samples: [],
 		...resolve_ports(options),
 	})
 
@@ -421,16 +390,29 @@ async function with_command_reservation<T>(
 	)
 }
 
+// The unit claim the parent command holds for this process (`with_command_reservation`), or
+// `undefined` where none does. A held claim that is not a unit suite's says nothing about workers.
+function held_unit_claim(directory: string = PLATFORM_TEMP_ROOT): Reservation | undefined {
+	const key = held_mark.held_reservation()
+
+	if (key === undefined) return undefined
+
+	const held = live_reservations(directory).find((entry) => entry.key === key)
+
+	return held?.reservation.is_unit === true ? held.reservation : undefined
+}
+
 const core_budget = {
-	CORE_WEIGHTS,
+	CORE_WEIGHTS: core_weights.CORE_WEIGHTS,
 	HELD_KEY: held_mark.HELD_KEY,
 	HELD_VALUE: held_mark.HELD_VALUE,
-	MEMORY_MB,
+	MEMORY_MB: core_weights.MEMORY_MB,
 	RESERVED_PREFIX,
 	admitted_keys: core_admission.admitted_keys,
 	admitted_load: core_admission.admitted_load,
 	budget_waits,
 	describe_overflow: core_admission.describe_overflow,
+	held_unit_claim,
 	is_held: held_mark.is_held,
 	live_reservations,
 	release,

package/scripts/gate/core-wait-record.ts

@@ -0,0 +1,48 @@
+import { lane_ledger, type CoreWaitRecord } from '#scripts/lane/lane-ledger'
+
+// How long a claim waited for the core budget, written to the lane ledger once it is admitted, so
+// `josh lane:stats` can split a lane's time into work and waiting (joshuafolkken/kit#4382). The
+// waiting line on stderr says a wait started; this says what it cost.
+//
+// **Only a claim that waited is recorded** — one admitted on its first read cost nothing, and a line per
+// command would bury the waits a lane's time is split by. The lane is the claim's own checkout's, the
+// one `run:board` names the waiting claim by.
+
+const UNNAMED_COMMAND = 'a step'
+
+// What `core-budget.ts` knows of the claim when it is admitted.
+interface AdmittedClaim {
+	command?: string | undefined
+	lane?: string | undefined
+	wait_reason?: string | undefined
+	claimed_at: number
+}
+
+type WaitSink = (wait: CoreWaitRecord) => Promise<void>
+
+async function to_ledger(wait: CoreWaitRecord): Promise<void> {
+	await lane_ledger.record_core_wait(wait)
+}
+
+function wait_of(claim: AdmittedClaim, now: number): CoreWaitRecord | undefined {
+	if (claim.wait_reason === undefined) return undefined
+
+	const wait = { command: claim.command ?? UNNAMED_COMMAND, waited_ms: now - claim.claimed_at }
+
+	return claim.lane === undefined ? wait : { ...wait, issue: Number(claim.lane) }
+}
+
+async function record_admitted(
+	claim: AdmittedClaim,
+	now: number,
+	sink: WaitSink = to_ledger,
+): Promise<void> {
+	const wait = wait_of(claim, now)
+
+	if (wait !== undefined) await sink(wait)
+}
+
+const core_wait_record = { record_admitted, wait_of }
+
+export type { WaitSink }
+export { core_wait_record }

package/scripts/gate/core-wait.ts

@@ -9,13 +9,15 @@ import type { MachineBudget } from './machine-capacity'
 // says it once on its own output; `run:board` draws every marker still waiting. Everything here is a
 // pure function of the ledger and the budget it is handed.
 
-const WAIT_REASONS = ['cores', 'memory', 'pressure'] as const
+const WAIT_REASONS = ['cores', 'cpu', 'memory', 'pressure'] as const
 
 type WaitReason = (typeof WAIT_REASONS)[number]
 
-// The one wording of each reason, shared by the waiting command's line and the board's.
+// The one wording of each reason, on the waiting command's own line; the board draws the reason as the
+// header's icon instead (joshuafolkken/kit#4052).
 const REASON_TEXT: Record<WaitReason, string> = {
 	cores: 'not enough free cores',
+	cpu: 'CPU saturated',
 	memory: 'not enough free memory',
 	pressure: 'memory under pressure',
 }
@@ -49,6 +51,18 @@ interface BudgetWait extends BudgetPlace {
 	reason: WaitReason
 }
 
+// A claim short of cores waits on the CPU when it would fit on what the ledger declares — the cores it
+// lacks are taken by busy load beyond the ledger (joshuafolkken/kit#4238) — and on the ledger otherwise.
+function core_reason(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: MachineBudget,
+): WaitReason {
+	const declared = { cores: budget.cores + (budget.busy_excess ?? 0), memory_mb: Infinity }
+
+	return core_admission.is_admitted(key, reservations, declared) ? 'cpu' : 'cores'
+}
+
 // **The cores decide first**: a claim that would not fit even with unlimited memory waits for cores;
 // one that fits on cores waits for memory, named as pressure when the reading saw compression or swap.
 function wait_reason(
@@ -56,13 +70,31 @@ function wait_reason(
 	reservations: ReadonlyArray<LedgerEntry>,
 	budget: MachineBudget,
 ): WaitReason {
-	const cores_only = { cores: budget.cores, memory_mb: Infinity }
+	const cores_only = { ...budget, memory_mb: Infinity }
 
-	if (!core_admission.is_admitted(key, reservations, cores_only)) return 'cores'
+	if (!core_admission.is_admitted(key, reservations, cores_only)) {
+		return core_reason(key, reservations, budget)
+	}
 
 	return budget.memory_pressured === true ? 'pressure' : 'memory'
 }
 
+// Why a claim is not admitted yet, or `undefined` once it is: a unit claim the budget admits only too
+// narrow (`core_admission.is_too_narrow`) still waits, on the CPU — admitted, it fits what the ledger
+// declares, so only busy load beyond the ledger narrowed it (`core_reason`).
+function hold_reason(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: MachineBudget,
+	granted: number | undefined,
+): WaitReason | undefined {
+	if (!core_admission.is_admitted(key, reservations, budget)) {
+		return wait_reason(key, reservations, budget)
+	}
+
+	return core_admission.is_too_narrow(key, reservations, granted) ? 'cpu' : undefined
+}
+
 // The line a waiting command prints once, when its wait starts.
 function wait_line(command: string | undefined, reason: WaitReason): string {
 	return `⏳ ${command ?? 'a step'} waits for the core budget — ${REASON_TEXT[reason]}`
@@ -118,8 +150,8 @@ function waits_of(
 }
 
 const core_wait = {
-	REASON_TEXT,
 	WAIT_REASONS,
+	hold_reason,
 	wait_line,
 	wait_reason,
 	waits_of,

package/scripts/gate/core-weights.ts

@@ -0,0 +1,86 @@
+// The weights heavy tools declare to the core budget (`core-budget.ts`), in their own module so the
+// ledger's file stays under its line ceiling.
+
+// One tool's measured run: its CPU seconds over its wall seconds, the cores it kept busy on average.
+interface Measurement {
+	cpu_s: number
+	wall_s: number
+}
+
+// **What each heavy tool was measured at, on the 11-core machine.** The whole-tree eslint scan behind
+// `josh lines` and `josh refactor:scan`, cold on 2026-10-06. eslint over 40 staged files
+// (`pre-commit-lint.ts`), which the gate's lint also runs beside its sibling linters, so it is the
+// lint's floor; whole runs were observed at 124–147% CPU. The type check and the spell check with
+// `/usr/bin/time -l` on 2026-10-21 under a load average of 14. `prettier --check` over 40 staged
+// files, `josh retrospective` and a fresh lane's `pnpm install --frozen-lockfile` with
+// `/usr/bin/time -l` on 2026-10-17 under a load average of 16. The gate ledger records each check's
+// CPU beside its duration (`check-cpu.ts`), so these can be re-measured from it.
+const MEASURED = {
+	lint: { cpu_s: 16.9, wall_s: 14 },
+	type_check: { cpu_s: 31.2, wall_s: 27.3 },
+	spell_check: { cpu_s: 6, wall_s: 5.6 },
+	eslint_scan: { cpu_s: 113, wall_s: 98 },
+	format: { cpu_s: 2.1, wall_s: 1.7 },
+	retrospective: { cpu_s: 16.5, wall_s: 19.8 },
+	install: { cpu_s: 1.9, wall_s: 6.1 },
+} as const satisfies Readonly<Record<string, Measurement>>
+
+// **Rounded up, never down** (joshuafolkken/kit#4362): a weight is a whole number of cores, and the
+// floored table of joshuafolkken/kit#3354 let a 1.15-core eslint scan claim one, so the budget admitted
+// more than the machine had.
+function rounded_up(measurement: Measurement): number {
+	return Math.ceil(measurement.cpu_s / measurement.wall_s)
+}
+
+// **The cores each heavy tool occupies, declared once for both places that reserve them**
+// `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. Each is its
+// measurement rounded up. `e2e` is the Playwright worker count `josh test:e2e` passes locally — the
+// two-worker run CI already sizes for its four-core runner — since kit has no e2e suite of its own to
+// time.
+const CORE_WEIGHTS = {
+	lint: rounded_up(MEASURED.lint),
+	type_check: rounded_up(MEASURED.type_check),
+	spell_check: rounded_up(MEASURED.spell_check),
+	eslint_scan: rounded_up(MEASURED.eslint_scan),
+	format: rounded_up(MEASURED.format),
+	retrospective: rounded_up(MEASURED.retrospective),
+	install: rounded_up(MEASURED.install),
+	e2e: 2,
+} as const
+
+// **The memory each heavy tool holds, declared beside its cores**: 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.
+// On 2026-10-17: prettier 260 MB, the retrospective 862 MB and a lane install 65 MB. On 2026-10-22
+// (joshuafolkken/kit#4528) the whole suite, 1,830 files at `--maxWorkers=3` beside four lanes, sampled
+// each worker's resident size once a second: the largest peaked at 381 MB, so the 54-file
+// measurement had read a worker short of the files it lives through.
+const MEMORY_MB = {
+	lint: 2400,
+	type_check: 1300,
+	spell_check: 350,
+	eslint_scan: 2400,
+	unit_worker: 400,
+	format: 300,
+	retrospective: 900,
+	install: 100,
+} as const
+
+// **The program a command launches, mapped to the `MEMORY_MB` row it holds** — the one table
+// `command-memory.ts` reads a wrapped command's memory off. `install` is `pnpm install` read past its
+// `pnpm` wrapper (`git_argv.program_of`).
+const TOOL_MEMORY: Readonly<Partial<Record<string, keyof typeof MEMORY_MB>>> = {
+	eslint: 'lint',
+	tsc: 'type_check',
+	cspell: 'spell_check',
+	vitest: 'unit_worker',
+	prettier: 'format',
+	install: 'install',
+}
+
+const core_weights = { CORE_WEIGHTS, MEASURED, MEMORY_MB, TOOL_MEMORY }
+
+export { core_weights }

package/scripts/gate/free-cores.ts

@@ -1,12 +1,14 @@
 import { availableParallelism } from 'node:os'
+import type { FreeCapacity } from '#scripts/test/unit-worker-share'
 import { core_admission } from './core-admission'
 import { core_budget, type LiveReservation } from './core-budget'
+import { core_weights } from './core-weights'
 import { held_mark } from './held-mark'
 import { machine_capacity, type MachineReading } from './machine-capacity'
 
 // The cores a unit suite may open workers on: the core count less the load from outside the core
 // budget's ledger, the figure the ledger admits against (`machine_capacity.machine_budget`). The run
-// count in `unit-worker-share.ts` divides the machine between unit runs; this is what bounds that
+// count in `unit-run-marker.ts` divides the machine between unit runs; this is what bounds that
 // division when something else holds the cores.
 //
 // Its own module because the reading needs the ledger, and `core-budget.ts` already imports
@@ -29,9 +31,7 @@ function running_claims(directory: string | undefined): Array<LiveReservation> {
 
 // `undefined` where the machine could not be read — a CI runner, a CPU quota narrower than the host —
 // which `unit_worker_share.cap_to_free` reads as the share as it was.
-async function read(options: FreeCoresOptions = {}): Promise<number | undefined> {
-	const reading = await (options.read_machine ?? machine_capacity.read_machine)()
-
+function free_of(reading: MachineReading, options: FreeCoresOptions): number | undefined {
 	if (reading.busy_cores === undefined) return undefined
 
 	const ledger = core_admission.ledger_load(running_claims(options.directory), Date.now())
@@ -43,6 +43,29 @@ async function read(options: FreeCoresOptions = {}): Promise<number | undefined>
 	).cores
 }
 
+// **The workers the free memory holds** (joshuafolkken/kit#4528): the free memory over one worker's
+// peak (`core_weights.MEMORY_MB.unit_worker`, where its measurement is recorded). Divided here, not in
+// `unit-run-marker.ts`, which the vitest config imports — `core-weights.ts` there would widen every
+// related run on it to the whole suite. The memory is the reading's own available figure, not the
+// budget's: the ledger's held memory is added back there for admission's walk, and it is not free for
+// this run's workers. `undefined` — a platform `machine-capacity.ts` reads no memory on — leaves the
+// share as it was; a Linux CI runner reads `/proc/meminfo`, whose memory holds more workers than cores.
+function workers_in_memory(available_mb: number | undefined): number | undefined {
+	if (available_mb === undefined) return undefined
+
+	return available_mb / core_weights.MEMORY_MB.unit_worker
+}
+
+// One reading answers both halves: the sample window is waited out once.
+async function read(options: FreeCoresOptions = {}): Promise<FreeCapacity> {
+	const reading = await (options.read_machine ?? machine_capacity.read_machine)()
+
+	return {
+		cores: free_of(reading, options),
+		memory_workers: workers_in_memory(reading.available_mb),
+	}
+}
+
 const free_cores = { read }
 
 export type { FreeCoresOptions }