@joshuafolkken/kit 1.1229.0 → 1.1370.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.
+// 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.
+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,23 +6,20 @@ 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 { json_value } from '#scripts/lib/json-value'
 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).
+// A machine-wide weighted core budget with admission control.
 //
-// **The gate's CPU budget used to be decided once, at the gate's start, and never revisited.**
-// `announce_gate_plan` counted the unit runs alive the instant it began and sized itself against that
-// one reading — so the common case (nothing else in a gate yet) had every gate conclude it was alone
-// and reserve the whole machine, and only a gate that *started* later deferred. Three overlapping gates
-// therefore demanded thirty cores of an eleven-core machine, which is the "usually fine, occasionally
-// saturates" this module removes.
-//
-// **The fix is admission rather than recomputation.** A heavy step declares the cores it needs, claims
-// a place in a machine-wide ledger, and waits while the ledger is full — so the peak cannot exceed the
-// budget by construction, and the asymmetry ("whoever started first took everything") disappears
-// because a place is claimed in claim order rather than seized at start. Waiting is what replaces the
-// recomputation `unit-worker-share.ts` did: a step that could not fit does not shrink, it defers.
+// **Admission rather than a budget sized once at the gate's start.** A budget read once at the start
+// has every gate that sees no sibling conclude it is alone and reserve the whole machine, so
+// overlapping gates oversubscribe it. Instead a heavy step declares the cores it needs, claims a place
+// in a machine-wide ledger, and waits while the ledger is full — so the peak cannot exceed the budget
+// by construction, and a place is claimed in claim order rather than seized at start. A step that
+// could not fit does not shrink, it defers.
 //
 // **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
@@ -30,10 +27,15 @@ import { z } from 'zod'
 // to the whole budget and 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** (joshuafolkken/kit#1245). A run
+// **Liveness is `process_identity`'s, reused rather than re-invented.** A run
 // 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.** 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'
@@ -48,7 +50,7 @@ const WAIT_CAP_MS = 120_000
 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
+// `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
@@ -60,29 +62,47 @@ const CORE_WEIGHTS = {
 	eslint_scan: 1,
 } 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.
+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
+// `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
@@ -92,6 +112,7 @@ interface ReserveOptions {
 
 interface Handle {
 	target: string
+	admission: Admission
 }
 
 function marker_name(key: string): string {
@@ -109,13 +130,7 @@ function read_reservation(source: string): Reservation | undefined {
 
 	if (raw === undefined) return undefined
 
-	try {
-		const parsed = reservation_schema.safeParse(JSON.parse(raw))
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, reservation_schema)
 }
 
 // **A dead marker is removed, not merely skipped** — otherwise a reissued pid turns a leaked place into
@@ -141,10 +156,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 []
 	}
@@ -158,50 +176,6 @@ function live_reservations(directory: string = PLATFORM_TEMP_ROOT): Array<LiveRe
 	})
 }
 
-// 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 {
@@ -214,23 +188,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 {
@@ -238,39 +219,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 {
@@ -278,16 +316,17 @@ 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)
 	}
@@ -319,7 +358,7 @@ async function with_held_mark<T>(run: () => Promise<T>): Promise<T> {
 }
 
 // **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.
+// `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`
@@ -338,9 +377,11 @@ 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,
@@ -352,3 +393,5 @@ const core_budget = {
 
 export type { LiveReservation, Reservation, ReserveOptions }
 export { core_budget }
+
+export { type Admission } from './core-admission'

package/scripts/gate/gate-ledger.ts

@@ -0,0 +1,114 @@
+import { process_identity } from '#scripts/josh/process-identity'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { core_admission } from './core-admission'
+import { core_budget } from './core-budget'
+import { gate_plan } from './gate-plan'
+import type { GateStepResult } from './gate-report'
+import { machine_capacity } from './machine-capacity'
+
+// A finished gate's line in the lane ledger: its duration, its verdict, its
+// unit suite's duration, and the load it ran beside, so `josh metrics`
+// compares only gates the machine was quiet for. Another gate's span is not the only load: another
+// lane's lint, related tests or `ship` doubled a solo gate's duration within minutes.
+//
+// **The machine is read where none of the gate's own checks runs — before the first starts and after
+// the last ends.** The load average cannot tell the two apart: a solo gate started at 4 on the 11-core
+// machine ended at 21, its own load. The reading is the core budget's own, so "quiet" means what
+// admission means by it: no whole core busy beyond the baseline the gate's weights were measured beside.
+//
+// **Between the ends, the load is read off the core budget's ledger, not the CPU**.
+// Two readings missed every lane whose lint, tests or `ship` ran only while
+// the gate did: seven lanes moved the solo median from 50.5s to 60.9s with no commit between. The CPU
+// mid-gate holds this gate's own checks, whose declared weights are not what they burn, so the ledger
+// is what tells the two apart: another `josh` run's admitted claim is another process's place, and its
+// weight is the cores it holds. A claim still waiting holds none.
+
+const NO_LEDGER_CORES = 0
+// Often enough to catch another lane's shortest related lint, seldom enough that reading the markers —
+// a process probe each — costs the gate nothing it could measure.
+const SAMPLE_INTERVAL_MS = 3000
+
+// Where the line goes, the external load read so far — before the first check started, then every
+// sample since — and the timer taking the samples. No readings and no timer when no ledger was
+// resolved: a suite driving the gate reads the machine for nothing.
+interface GateLedgerStart {
+	ledger_path: string | undefined
+	readings: Array<number | undefined>
+	sampler: ReturnType<typeof setInterval> | undefined
+}
+
+interface GateOutcome {
+	elapsed_ms: number
+	is_passed: boolean
+}
+
+// `undefined` where the machine could not be read — a CI runner, a CPU quota narrower than the host.
+async function read_external_cores(): Promise<number | undefined> {
+	const { busy_cores } = await machine_capacity.read_machine()
+
+	if (busy_cores === undefined) return undefined
+
+	return machine_capacity.external_cores(busy_cores, NO_LEDGER_CORES)
+}
+
+// The cores other processes' admitted claims hold now. This gate's own claims are written by this
+// process, and its checks' dispatches claim nothing under its held mark.
+function read_foreign_cores(): number {
+	const foreign = core_budget
+		.live_reservations()
+		.filter(
+			({ reservation }) =>
+				!process_identity.is_own_process(reservation.pid, reservation.process_start),
+		)
+
+	return core_admission.ledger_load(foreign, Date.now()).cores
+}
+
+// The highest reading; one unread reading leaves the whole gate unread rather than half-quiet.
+function peak(readings: ReadonlyArray<number | undefined>): number | undefined {
+	const read = readings.filter((reading) => reading !== undefined)
+
+	if (read.length < readings.length) return undefined
+
+	return Math.max(...read)
+}
+
+// Unreferenced, so a gate that throws before `record` never holds the process open on the timer.
+function start_sampler(readings: Array<number | undefined>): ReturnType<typeof setInterval> {
+	return setInterval(() => {
+		readings.push(read_foreign_cores())
+	}, SAMPLE_INTERVAL_MS).unref()
+}
+
+async function start(ledger_path: string | undefined): Promise<GateLedgerStart> {
+	if (ledger_path === undefined) return { ledger_path, readings: [], sampler: undefined }
+
+	const readings = [await read_external_cores()]
+
+	return { ledger_path, readings, sampler: start_sampler(readings) }
+}
+
+// The caller measures the elapsed time before this, so the end's reading is never part of it.
+async function record(
+	begun: GateLedgerStart,
+	results: ReadonlyArray<GateStepResult>,
+	outcome: GateOutcome,
+): Promise<void> {
+	clearInterval(begun.sampler)
+
+	if (begun.ledger_path === undefined) return
+
+	const unit_ms = results.find((result) => result.label === gate_plan.UNIT_LABEL)?.elapsed_ms
+	const external_cores = peak([...begun.readings, await read_external_cores()])
+
+	await lane_ledger.record_gate(begun.ledger_path, { ...outcome, unit_ms, external_cores })
+}
+
+const gate_ledger = {
+	SAMPLE_INTERVAL_MS,
+	record,
+	start,
+}
+
+export type { GateLedgerStart }
+export { gate_ledger }