@joshuafolkken/kit 1.1514.0 → 1.2114.0

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, type LoadEase } 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 + 1) + unit_cap(cores - 5)` 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, or once outside load holding it does not ease (`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,13 +81,18 @@ 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
+	ease_window_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 {
@@ -139,7 +104,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 +120,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 +167,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 +178,56 @@ 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>
+	// Unset until the first reading of the machine (`busy_average.with_ease`).
+	ease?: LoadEase | undefined
 }
 
-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)
+
+	context.ease = busy_average.with_ease(context.ease, mean.busy_cores, context.now())
+
+	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(
@@ -297,22 +255,49 @@ function mark_waiting(context: WaitContext, reason: WaitReason): void {
 	if (previous === undefined) context.report(core_wait.wait_line(context.fields.command, reason))
 }
 
+// Past the cap a held claim runs regardless, and so does one only load outside the ledger holds once
+// that load has not eased for a window of the wait — waiting on gains it nothing. A claim a swap stall
+// holds is the exception to both.
+function is_wait_spent(
+	context: WaitContext,
+	reservations: ReadonlyArray<LiveReservation>,
+	budget: MachineBudget,
+): boolean {
+	if (core_admission.is_swap_held(context.key, reservations, budget)) return false
+
+	const now = context.now()
+
+	if (now >= context.deadline) return true
+
+	return (
+		busy_average.is_unrelieved(context.ease, now, context.ease_window_ms) &&
+		core_wait.is_outside_held(context.key, reservations, budget)
+	)
+}
+
 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 whose wait is spent.
+	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)
+	if (is_wait_spent(context, 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
 }
 
-// Poll the ledger until this reservation is admitted, or until the wait cap admits it at minimum width.
+// Poll the ledger until this reservation is admitted, or until the wait cap — or, for a claim only load
+// outside the ledger holds, that load not easing — 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<Admission> {
@@ -325,14 +310,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 +333,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 +355,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),
 	})
 
@@ -401,6 +392,12 @@ async function with_core_reservation<T>(
 	}
 }
 
+// Whether a parent's claim already covers this process — a held parent command, or a unit suite this
+// runs inside — so a command claims nothing, and one that sizes its claim need not size it.
+function is_covered(): boolean {
+	return held_mark.is_held() || unit_worker_share.is_nested_run()
+}
+
 // **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
@@ -412,7 +409,7 @@ async function with_command_reservation<T>(
 	run: () => Promise<T>,
 	options: ReserveOptions = {},
 ): Promise<T> {
-	if (held_mark.is_held() || unit_worker_share.is_nested_run()) return await run()
+	if (is_covered()) return await run()
 
 	return await with_core_reservation(
 		weight,
@@ -421,16 +418,30 @@ 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_covered,
 	is_held: held_mark.is_held,
 	live_reservations,
 	release,

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

@@ -0,0 +1,49 @@
+import type { CoreWaitRecord } from '#scripts/lane/lane-ledger-schema'
+import { lane_ledger_write } from '#scripts/lane/lane-ledger-write'
+
+// 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_write.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,50 @@ 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
+}
+
+// **Whether only load from outside the ledger holds the claim** (joshuafolkken/kit#4982): with that load
+// gone — its busy cores handed back and no run-queue overload — the claim would be admitted at a width
+// that is not too narrow. A claim the ledger or memory holds is not, and waits for its room to come back.
+function is_outside_held(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: MachineBudget,
+): boolean {
+	const unloaded = {
+		...budget,
+		cores: budget.cores + (budget.busy_excess ?? 0),
+		busy_excess: 0,
+		is_overloaded: false,
+	}
+	const granted = core_admission.narrowed_weight(key, reservations, unloaded.cores)
+
+	return hold_reason(key, reservations, unloaded, granted) === 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]}`
@@ -70,10 +121,13 @@ function wait_line(command: string | undefined, reason: WaitReason): string {
 
 // 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.
+// A Claude Code worktree under a checkout reads as that checkout (`lane_paths.checkout_of`).
 function lanes_root_of(checkout: string): string {
-	if (lane_paths.lane_issue_of(checkout) === undefined) return lane_paths.lane_root(checkout)
+	const resolved = lane_paths.checkout_of(path.resolve(checkout))
+
+	if (lane_paths.lane_issue_of(resolved) === undefined) return lane_paths.lane_root(resolved)
 
-	return path.dirname(path.resolve(checkout))
+	return path.dirname(resolved)
 }
 
 // Where a claim runs, read by the claimer under its own environment: `JOSH_LANE_ROOT` is a
@@ -118,8 +172,9 @@ function waits_of(
 }
 
 const core_wait = {
-	REASON_TEXT,
 	WAIT_REASONS,
+	hold_reason,
+	is_outside_held,
 	wait_line,
 	wait_reason,
 	waits_of,

package/scripts/gate/core-weights.ts

@@ -0,0 +1,94 @@
+// 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 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. The spell check was re-measured from it
+// (joshuafolkken/kit#5140): its median CPU and median wall over the lane ledger's 413 gate `cspell`
+// runs that were not reused, from 2026-10-24 to 2026-10-27, whose per-run cores had a median of 0.91
+// and a p90 of 1.31 — one core rounded up, where the single 2026-10-21 run of 6.0s over 5.6s had
+// rounded up to two.
+const MEASURED = {
+	lint: { cpu_s: 16.9, wall_s: 14 },
+	type_check: { cpu_s: 31.2, wall_s: 27.3 },
+	spell_check: { cpu_s: 5.7, wall_s: 6.2 },
+	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. On 2026-10-23
+// (joshuafolkken/kit#4595) `josh metrics`, its process tree sampled four times a second, peaked at
+// 1,176 MB on a merge-base cache hit and 1,851 MB on a miss, where its own untyped `max-lines`-only
+// eslint pass still holds its heap beside the `--json` child measuring the merge-base. It takes the miss.
+const MEMORY_MB = {
+	lint: 2400,
+	metrics: 1900,
+	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 }