@joshuafolkken/kit 1.1229.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

@@ -8,6 +8,8 @@ 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).
 //
@@ -34,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'
@@ -60,6 +67,19 @@ const CORE_WEIGHTS = {
 	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
@@ -67,22 +87,27 @@ const CORE_WEIGHTS = {
 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 +117,7 @@ interface ReserveOptions {
 
 interface Handle {
 	target: string
+	admission: Admission
 }
 
 function marker_name(key: string): string {
@@ -141,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 []
 	}
@@ -158,50 +187,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 +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 {
@@ -238,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 {
@@ -278,16 +327,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)
 	}
@@ -338,9 +388,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 +404,5 @@ const core_budget = {
 
 export type { LiveReservation, Reservation, ReserveOptions }
 export { core_budget }
+
+export { type Admission } from './core-admission'

package/scripts/gate/gate-plan.ts

@@ -36,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'
@@ -74,13 +77,24 @@ const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LA
 // 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: core_budget.CORE_WEIGHTS.lint },
+	{
+		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: 'cspell', target: 'cspell:dot', reserved_cores: core_budget.CORE_WEIGHTS.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 for about 5s, and it is over well before lint and the type check. A
@@ -280,6 +294,18 @@ function check_weight(check: GateCheck, plan: GatePlan, available_cores: number)
 	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
@@ -298,6 +324,11 @@ function direct_unit_weight(
 	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
 // use, so a container with a CPU quota is sized by the quota rather than by the host.
 // The three fields together, for a caller that has already decided the numbers. The gate's own
@@ -383,7 +414,9 @@ 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,

package/scripts/gate/gate-report.ts

@@ -25,6 +25,8 @@ interface GateStepResult extends BufferedProcessResult {
 	// What was actually run. The type check's command is resolved per project, so a failure on the
 	// `check` step is only reproducible if the header names the command rather than the label.
 	command: string
+	// Set when the check started past the machine-wide budget at the wait cap (joshuafolkken/kit#3371).
+	budget_note?: string | undefined
 }
 
 function is_gate_step_failed(result: GateStepResult): boolean {
@@ -141,25 +143,42 @@ function format_failure_actions(failed: ReadonlyArray<GateStepResult>): string {
 	return `${GATE_COMMAND} — next:\n${lines.join('\n')}\n`
 }
 
+// **A check that started past the core budget is said in the summary, not only in the log**
+// (joshuafolkken/kit#3371). The wait cap admits a check that waited two minutes whatever the budget says,
+// so a gate that ran over-subscribed would otherwise look exactly like one that fitted. The icon is
+// local rather than in `status-icons.ts` because nothing reads this line back.
+const WARN_ICON = '⚠'
+
+function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
+	const lines = results.flatMap((result) =>
+		result.budget_note === undefined
+			? []
+			: `  ${WARN_ICON} ${result.label} — ${result.budget_note}`,
+	)
+
+	return lines.length === 0 ? '' : `${lines.join('\n')}\n`
+}
+
 // The total is wall-clock for the whole command, not the sum of the four — they run concurrently,
 // so a sum would report about three times what the caller waited.
 //
 // The failure actions and the log path are printed with the summary and immediately **above** the
 // verdict line, which stays last for the reason `josh-verdict.ts` gives (joshuafolkken/kit#1227).
 function print_gate_summary(
-	failed: ReadonlyArray<GateStepResult>,
-	elapsed_ms: number,
-	step_count: string,
+	results: ReadonlyArray<GateStepResult>,
+	report: GateReport,
 	log_path?: string,
 ): void {
-	const total = format_seconds(elapsed_ms)
+	const failed = results.filter((result) => is_gate_step_failed(result))
+	const total = format_seconds(report.elapsed_ms)
 	const verdict =
 		failed.length === 0
-			? josh_verdict.format_gate_passed(step_count, total)
+			? josh_verdict.format_gate_passed(report.step_count, total)
 			: josh_verdict.format_gate_failed(failed.map((result) => result.label).join(', '), total)
+	const notes = format_budget_notes(results)
 
 	process.stdout.write(
-		`\n${format_failure_actions(failed)}${gate_log.format_log_notice(log_path)}${verdict}\n`,
+		`\n${notes}${format_failure_actions(failed)}${gate_log.format_log_notice(log_path)}${verdict}\n`,
 	)
 }
 
@@ -183,15 +202,15 @@ function report_gate_steps(
 		header: gate_step_header(result),
 		output: result.output,
 	}))
-	const failed = results.filter((result) => is_gate_step_failed(result))
 	const written_log = gate_log.write_gate_log(entries, report.log_path)
 
-	print_gate_summary(failed, report.elapsed_ms, report.step_count, written_log)
+	print_gate_summary(results, report, written_log)
 
-	return failed.map((result) => result.label)
+	return results.filter((result) => is_gate_step_failed(result)).map((result) => result.label)
 }
 
 const gate_report = {
+	format_budget_notes,
 	format_failure_actions,
 	has_checker_warning,
 	is_gate_step_failed,