@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/gate/core-budget.ts

@@ -9,7 +9,13 @@ 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'
 
 // A machine-wide weighted core budget with admission control.
@@ -23,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
@@ -39,61 +46,31 @@ 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.
-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**: 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**
-// `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.
+// `command`, `checkout`, `lane`, `lanes_root` and `wait_reason` name a waiting claim on `run:board`
+// (`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(),
+	lanes_root: z.string().optional(),
+	wait_reason: z.enum(core_wait.WAIT_REASONS).optional(),
 })
 
 type Reservation = z.infer<typeof reservation_schema>
 
-type ReservationFields = Pick<Reservation, 'weight' | 'claimed_at' | 'memory_mb' | 'admitted_at'>
+type ReservationFields = Omit<Reservation, 'pid' | 'process_start'>
 
 interface LiveReservation extends LedgerEntry {
 	reservation: Reservation
@@ -102,12 +79,19 @@ interface LiveReservation extends LedgerEntry {
 interface ReserveOptions {
 	budget?: number
 	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
 	poll_interval_ms?: number
 	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 {
@@ -119,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
@@ -135,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)
@@ -182,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.
@@ -195,56 +173,56 @@ 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.
-interface TimingConfig {
-	now: () => number
-	sleep: (ms: number) => Promise<void>
-	poll_interval_ms: number
-	wait_cap_ms: number
+function report_wait(line: string): void {
+	process.stderr.write(`${line}\n`)
 }
 
 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()
+
+	write_reservation(context.target, { ...context.fields, admitted_at, granted })
 
-	return { overflow }
+	return { overflow, granted, waited_ms: admitted_at - context.fields.claimed_at }
 }
 
 function overflow_of(
@@ -259,16 +237,41 @@ function overflow_of(
 	}
 }
 
+// The marker records why the claim waits, rewritten only when the reason changes, and the command says
+// so once, when its wait starts.
+function mark_waiting(context: WaitContext, reason: WaitReason): void {
+	const previous = context.fields.wait_reason
+
+	if (previous === reason) return
+
+	context.fields = { ...context.fields, wait_reason: reason }
+	write_reservation(context.target, context.fields)
+
+	if (previous === undefined) context.report(core_wait.wait_line(context.fields.command, reason))
+}
+
 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, reason)
+
 	return undefined
 }
 
@@ -285,16 +288,41 @@ 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, 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,
+	}
+}
+
+// The checkout the claim runs in, so `run:board` can say whose claim waits. The ledger is the
+// machine's, so the checkout may be another repository's (`core-wait.ts` → `where_of`).
+function claim_fields(
+	weight: number,
+	claimed_at: number,
+	options: ReserveOptions,
+): ReservationFields {
+	const { memory_mb, command, is_unit } = options
+
+	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())
 	const target = path.join(directory, name)
-	const fields = { weight, claimed_at, memory_mb: options.memory_mb }
+	const fields = claim_fields(weight, claimed_at, options)
 
 	write_reservation(target, fields)
 	const admission = await await_admission({
@@ -305,58 +333,43 @@ async function reserve(weight: number, options: ReserveOptions = {}): Promise<Ha
 		budget: normalize_budget(options.budget ?? availableParallelism()),
 		deadline: claimed_at + timing.wait_cap_ms,
 		fields,
-		read_machine: options.read_machine ?? machine_capacity.read_machine,
+		busy_samples: [],
+		...resolve_ports(options),
 	})
 
 	return { target, admission }
 }
 
+// The claims waiting in the ledger now, for a `run:board` running in `home`.
+function budget_waits(
+	directory: string = PLATFORM_TEMP_ROOT,
+	now: number = Date.now(),
+	home: string = process.cwd(),
+): Array<BudgetWait> {
+	return core_wait.waits_of(live_reservations(directory), now, home)
+}
+
 function release(handle: Handle): void {
 	sweep_marker(handle.target)
 }
 
 // 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. The step is told how it was
-// admitted, so the gate can report one that started past the budget.
+// admitted, so the gate can report one that started past the budget, and the claim's ledger key.
 async function with_core_reservation<T>(
 	weight: number,
-	run: (admission: Admission) => Promise<T>,
+	run: (admission: Admission, key: string) => Promise<T>,
 	options: ReserveOptions = {},
 ): Promise<T> {
 	const handle = await reserve(weight, options)
 
 	try {
-		return await run(handle.admission)
+		return await run(handle.admission, path.basename(handle.target))
 	} 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**
 // `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
@@ -368,27 +381,45 @@ async function with_command_reservation<T>(
 	run: () => Promise<T>,
 	options: ReserveOptions = {},
 ): Promise<T> {
-	if (is_held() || unit_worker_share.is_nested_run()) return await run()
+	if (held_mark.is_held() || unit_worker_share.is_nested_run()) return await run()
+
+	return await with_core_reservation(
+		weight,
+		async (_admission, key) => await held_mark.with_held_mark(run, key),
+		options,
+	)
+}
+
+// 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 await with_core_reservation(weight, async () => await with_held_mark(run), options)
+	return held?.reservation.is_unit === true ? held.reservation : undefined
 }
 
 const core_budget = {
-	CORE_WEIGHTS,
-	HELD_KEY,
-	HELD_VALUE,
-	MEMORY_MB,
+	CORE_WEIGHTS: core_weights.CORE_WEIGHTS,
+	HELD_KEY: held_mark.HELD_KEY,
+	HELD_VALUE: held_mark.HELD_VALUE,
+	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,
-	is_held,
+	held_unit_claim,
+	is_held: held_mark.is_held,
 	live_reservations,
 	release,
 	reserve,
 	with_command_reservation,
 	with_core_reservation,
-	with_held_mark,
+	with_held_mark: held_mark.with_held_mark,
 }
 
 export type { LiveReservation, Reservation, ReserveOptions }

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

@@ -0,0 +1,162 @@
+import path from 'node:path'
+import { lane_paths } from '#scripts/lane/lane-paths'
+import { core_admission, type LedgerEntry } from './core-admission'
+import type { MachineBudget } from './machine-capacity'
+
+// **Why a claim waits, and who is waiting** (joshuafolkken/kit#3943). A claim held back by the budget
+// used to wait in silence: the command printed nothing and no board showed it, so a lane stalled on
+// memory pressure read the same as one stuck. The waiting claim records its reason on its marker and
+// 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', 'cpu', 'memory', 'pressure'] as const
+
+type WaitReason = (typeof WAIT_REASONS)[number]
+
+// 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',
+}
+
+// What the board reads off a marker. Every field but the claim time is optional, so a marker an older
+// `josh` wrote still reads, and one that never waited is not drawn.
+interface WhereFields {
+	checkout?: string | undefined
+	lane?: string | undefined
+	lanes_root?: string | undefined
+}
+
+interface WaitMarker extends WhereFields {
+	claimed_at: number
+	admitted_at?: number | undefined
+	command?: string | undefined
+	wait_reason?: WaitReason | undefined
+}
+
+// Where a waiting claim runs: `lane` is the board's own repository's lane number, which the board
+// links; `elsewhere` names another repository's checkout, which it cannot link. Neither is the board's
+// own main checkout.
+interface BudgetPlace {
+	lane: string | undefined
+	elsewhere: string | undefined
+}
+
+interface BudgetWait extends BudgetPlace {
+	command: string | undefined
+	waited_ms: number
+	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(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: MachineBudget,
+): WaitReason {
+	const cores_only = { ...budget, memory_mb: Infinity }
+
+	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]}`
+}
+
+// The lanes root a checkout belongs to: a lane's parent, or the root beside a main checkout. Two
+// checkouts of one repository share it; the ledger is machine-wide, so another repository's do not.
+function lanes_root_of(checkout: string): string {
+	if (lane_paths.lane_issue_of(checkout) === undefined) return lane_paths.lane_root(checkout)
+
+	return path.dirname(path.resolve(checkout))
+}
+
+// Where a claim runs, read by the claimer under its own environment: `JOSH_LANE_ROOT` is a
+// per-project setting, so a board cannot derive another repository's lanes root from its own.
+function where_of(checkout: string): Required<WhereFields> {
+	return { checkout, lane: lane_paths.lane_issue_of(checkout), lanes_root: lanes_root_of(checkout) }
+}
+
+// Another repository's checkout is named by its lanes root and lane, or its directory, so its lane
+// number is never linked to the board's repository's issue of that number.
+function place_of(marker: WhereFields, home_root: string): BudgetPlace {
+	const { checkout, lane, lanes_root } = marker
+
+	if (checkout === undefined || lanes_root === undefined || lanes_root === home_root) {
+		return { lane, elsewhere: undefined }
+	}
+
+	const name = lane === undefined ? path.basename(checkout) : `${path.basename(lanes_root)}/${lane}`
+
+	return { lane: undefined, elsewhere: name }
+}
+
+function wait_of(marker: WaitMarker, now: number, home_root: string): Array<BudgetWait> {
+	const { command, wait_reason: reason } = marker
+
+	if (reason === undefined || marker.admitted_at !== undefined) return []
+
+	return [{ command, ...place_of(marker, home_root), waited_ms: now - marker.claimed_at, reason }]
+}
+
+// The claims still waiting, longest first, placed against the board's checkout `home`.
+function waits_of(
+	entries: ReadonlyArray<{ reservation: WaitMarker }>,
+	now: number,
+	home: string,
+): Array<BudgetWait> {
+	const home_root = lanes_root_of(home)
+
+	return entries
+		.flatMap((entry) => wait_of(entry.reservation, now, home_root))
+		.toSorted((left, right) => right.waited_ms - left.waited_ms)
+}
+
+const core_wait = {
+	WAIT_REASONS,
+	hold_reason,
+	wait_line,
+	wait_reason,
+	waits_of,
+	where_of,
+}
+
+export type { BudgetWait, WaitReason }
+export { core_wait }