@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/gate/check-reuse.ts

@@ -1,34 +1,37 @@
 import { git_command } from '#scripts/git/git-command'
-import { git_spawn } from '#scripts/git/git-spawn'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
-import { file_map_stamp, type FileMapStamp } from '#scripts/josh/file-map-stamp'
+import {
+	file_map_stamp,
+	type FileMapStamp,
+	type FileMapStampAccess,
+} from '#scripts/josh/file-map-stamp'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { review_tree } from '#scripts/review/review-tree'
-import { check_inputs, type PrettierIgnored } from './check-inputs'
+import { check_inputs } from './check-inputs'
 import { gate_report, type GateStepResult } from './gate-report'
 import type { GateTree } from './gate-tree'
-
-// One green record per scoped check, so a gate re-run starts only the checks whose inputs moved
-// (`check-inputs.ts` decides what each reads). The whole-gate record (`gate-skip.ts`) is refused the
-// moment the merge base moves; a main sync that brought in only `.claude/**/*.md` then re-ran lint and
-// the type check over sources neither had a reason to read again.
-//
-// **What moved is the union of two diffs**, and together they are every path whose content can differ
-// from the tree the record was taken on. The changed-file map is a diff against the merge base, so a
-// path absent from both maps holds the merge base's content — and the base's own diff
-// (`git diff <recorded> <current>`) names every path that content moved for. A path in either map whose
-// digest differs is the other half (`file_map_stamp.changed_since`).
+import { moved_paths } from './moved-paths'
+import { verification_inputs, type PrettierIgnored } from './verification-inputs'
+
+// One green record per declared check, so a gate re-run starts only the checks whose inputs moved
+// (`verification-inputs.ts` declares what each reads). The whole-gate record (`gate-skip.ts`) is refused
+// the moment the merge base moves; a main sync that brought in only `.claude/**/*.md` then re-ran lint
+// and the type check over sources neither had a reason to read again. What moved since a record is
+// `moved-paths.ts`.
 //
 // **A record is reuse of a result, not a check dropped**: no base, an empty changed-file map, an
-// unreadable base diff or no root answers "not reusable", and a check with no scope is never reusable. The records are written and read
+// unreadable base diff, no root or a fingerprint of the check's tools and environment that moved
+// answers "not reusable", and an undeclared check is never reusable. The records are written and read
 // only where the CLI entry resolved their destination (`CheckRecords`), so a suite driving the gate
 // never plants a green record over the live tree.
 
 const CHECK_PREFIX = 'josh-gate-check-'
-const NAME_SEPARATOR = '\0'
-const BASE_DIFF = ['diff', '--name-only', '--no-renames', '-z'] as const
 
-const check_stamp = file_map_stamp.create(CHECK_PREFIX, PROJECT_ROOT)
+function check_stamp(label: string): FileMapStampAccess {
+	return file_map_stamp.create(CHECK_PREFIX, PROJECT_ROOT, () =>
+		verification_inputs.fingerprint([label]),
+	)
+}
 
 // Where each check's record lives — a parameter so a test plants records in a directory of its own.
 type CheckRecords = (label: string) => string
@@ -37,39 +40,11 @@ function default_records(label: string): string {
 	return stamp_file.stamp_path(`${CHECK_PREFIX}${label}-`, PROJECT_ROOT)
 }
 
-async function base_diff(from: string, to: string): Promise<ReadonlyArray<string> | undefined> {
-	if (from === to) return []
-
-	try {
-		const names = await git_spawn.read([...BASE_DIFF, from, to])
-
-		return names.split(NAME_SEPARATOR).filter((name) => name !== '')
-	} catch {
-		return undefined
-	}
-}
-
-async function moved_since(
-	stamp: FileMapStamp,
-	tree: GateTree,
-): Promise<ReadonlyArray<string> | undefined> {
-	// An empty map is also what `gate-tree.ts` answers when git could not be read, so it describes no
-	// tree to diff against — the reading `gate_skip.gate_reuse` refuses too.
-	const is_unread = Object.keys(tree.files).length === 0
-
-	if (is_unread || stamp.base === undefined || tree.base === undefined) return undefined
-
-	const moved_base = await base_diff(stamp.base, tree.base)
-
-	if (moved_base === undefined) return undefined
-
-	return [...file_map_stamp.changed_since(stamp, tree.files), ...moved_base]
-}
-
 interface ReuseContext {
 	tree: GateTree
 	records: CheckRecords
 	is_ignored: PrettierIgnored
+	root: string
 }
 
 async function is_stamp_reusable(
@@ -77,16 +52,18 @@ async function is_stamp_reusable(
 	stamp: FileMapStamp,
 	context: ReuseContext,
 ): Promise<boolean> {
-	const moved = await moved_since(stamp, context.tree)
+	const moved = await moved_paths.moved_since(stamp, context.tree)
 
-	if (moved === undefined) return false
+	if (moved === undefined || !check_stamp(label).describes_inputs(stamp)) return false
 
-	return !(await check_inputs.touches_inputs(label, moved, context.is_ignored))
+	return !(await check_inputs.touches_inputs(label, moved, context.is_ignored, context.root))
 }
 
 // The time the check's record was taken, or `undefined` when the check has to run.
 async function reused_at(label: string, context: ReuseContext): Promise<string | undefined> {
-	const stamp = check_inputs.is_scoped(label) ? check_stamp.read(context.records(label)) : undefined
+	const stamp = verification_inputs.is_declared(label)
+		? check_stamp(label).read(context.records(label))
+		: undefined
 
 	if (stamp === undefined) return undefined
 
@@ -111,7 +88,7 @@ async function reusable_checks(
 
 	if (root === undefined) return new Map()
 
-	const context = { tree, records, is_ignored: check_inputs.prettier_ignored(root) }
+	const context = { tree, records, root, is_ignored: check_inputs.prettier_ignored(root) }
 	const answers = await Promise.all(
 		labels.map(async (label) => [label, await reused_at(label, context)] as const),
 	)
@@ -121,7 +98,7 @@ async function reusable_checks(
 
 function is_recordable(result: GateStepResult): boolean {
 	return (
-		check_inputs.is_scoped(result.label) &&
+		verification_inputs.is_declared(result.label) &&
 		!gate_report.is_gate_step_failed(result) &&
 		gate_report.has_nothing_to_say(result)
 	)
@@ -134,7 +111,9 @@ function write_records(
 ): void {
 	const recordable = results.filter((result) => is_recordable(result))
 
-	for (const result of recordable) check_stamp.write(tree.files, records(result.label), tree.base)
+	for (const { label } of recordable) {
+		check_stamp(label).write(tree.files, records(label), tree.base)
+	}
 }
 
 // Every scoped check that passed silently, recorded against the tree it read — a red gate's green

package/scripts/gate/command-memory.ts

@@ -0,0 +1,192 @@
+import os from 'node:os'
+import { bash_triggers } from '#scripts/rules/bash-triggers'
+import { git_argv, type ProgramCall } from '#scripts/rules/git-argv'
+import { shell_segments } from '#scripts/rules/shell-segments'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { core_weights } from './core-weights'
+
+// The heavy tools a shell line launches, and the memory they hold (joshuafolkken/kit#4582).
+//
+// **`reserved-run` counted a wrapped command's cores and no memory**: a lane ran
+// `reserved-run 4 -- sh -c '… eslint . --concurrency 4 …'`, typed eslint held a TypeScript program per
+// worker, and the 12 GB process was admitted beside four other lanes until the machine swapped. The
+// estimate here is what the wrapper now reserves, and the same reading is what `lane-direct-tool`
+// refuses a multi-worker eslint on.
+//
+// **Every spelling is read down to the program.** `git_argv.program_of` skips the wrapper words, a
+// quoted script handed to a shell is read as its own line (`bash_triggers.shell_script_of`), and the
+// command after `pnpm josh reserved-run <weight> --` is read as the call it wraps, marked reserved. A
+// heredoc body is text, so it is dropped before the line is cut — unless a shell reads it
+// (`bash <<'EOF'`), when it is read as a line of its own, the `sh -c` escape spelled another way.
+//
+// **The estimate is the largest tool's, not the sum**: the commands of one line run one after another,
+// so only one of them is resident at a time. A line with no known tool is `undefined`, the 0 MB it
+// counted before — `reserved-run 1 -- pnpm josh audit` reserves its own, and is not counted twice.
+
+interface ToolCall extends ProgramCall {
+	// Inside a `pnpm josh reserved-run … --`, the budgeted path.
+	is_reserved: boolean
+}
+
+// A line still to be cut into its programs.
+interface PendingLine {
+	line: string
+	is_reserved: boolean
+}
+
+const JOSH_PROGRAM = 'josh'
+const RESERVED_RUN = 'reserved-run'
+const COMMAND_SEPARATOR = '--'
+const ESLINT = 'eslint'
+const VITEST = 'vitest'
+const AUTO_WORKERS = 'auto'
+const LINE_BREAK = '\n'
+// A heredoc fed to a shell — `bash <<'EOF'`, `sh -s <<EOF` — whose body the shell runs.
+const SHELL_HEREDOC = /\b(?:ba|z|da|k)?sh(?:\s+-\w+)*\s*<<-?\s*(['"]?)(\w+)\1/u
+const HEREDOC_DELIMITER_GROUP = 2
+// ESLint 10's `auto` caps its workers at half the available cores (`eslint/lib/eslint/eslint.js`).
+const AUTO_CORE_SHARE = 2
+const SINGLE_WORKER = 1
+// The flag each multi-worker tool takes its worker count from.
+const WORKER_FLAGS: Readonly<Partial<Record<string, string>>> = {
+	[ESLINT]: '--concurrency',
+	[VITEST]: '--maxWorkers',
+}
+
+// The command `pnpm josh reserved-run <weight> [--memory <MB>] -- <command>` wraps, or `undefined`.
+function wrapped_command_of(call: ProgramCall): string | undefined {
+	if (call.name !== JOSH_PROGRAM || call.args[0] !== RESERVED_RUN) return undefined
+
+	const separator = call.args.indexOf(COMMAND_SEPARATOR)
+
+	return separator === -1 ? undefined : call.args.slice(separator + 1).join(' ')
+}
+
+// One command of a line: the program it launches, or the line it hands on — a `reserved-run`'s
+// wrapped command, or a shell's quoted script.
+function reading_of(segment: string, is_reserved: boolean): ToolCall | PendingLine | undefined {
+	const call = git_argv.program_of(segment)
+	const wrapped = call === undefined ? undefined : wrapped_command_of(call)
+
+	if (wrapped !== undefined) return { line: wrapped, is_reserved: true }
+
+	const script = bash_triggers.shell_script_of(segment)
+
+	if (script !== undefined) return { line: script, is_reserved }
+
+	return call === undefined ? undefined : { ...call, is_reserved }
+}
+
+// The lines up to the delimiter alone on its line, or to the end when it never closes.
+function body_until(lines: ReadonlyArray<string>, delimiter: string): string {
+	const end = lines.findIndex((body_line) => body_line.trim() === delimiter)
+
+	return (end === -1 ? lines : lines.slice(0, end)).join(LINE_BREAK)
+}
+
+// The body of every heredoc the line feeds to a shell, each as a line of its own: `bash <<'EOF'` runs
+// its body, where `cat <<EOF` only prints it.
+function shell_heredoc_bodies(line: string): Array<string> {
+	const lines = line.split(LINE_BREAK)
+
+	return lines.flatMap((opening, index) => {
+		const delimiter = SHELL_HEREDOC.exec(opening)?.[HEREDOC_DELIMITER_GROUP]
+
+		return delimiter === undefined ? [] : body_until(lines.slice(index + 1), delimiter)
+	})
+}
+
+function is_tool_call(reading: ToolCall | PendingLine): reading is ToolCall {
+	return 'name' in reading
+}
+
+function is_pending_line(reading: ToolCall | PendingLine): reading is PendingLine {
+	return !is_tool_call(reading)
+}
+
+// Every program the line launches, a shell's quoted script and a `reserved-run`'s command included.
+// A queue rather than recursion: each handed-on line is shorter than the one it came from.
+function tool_calls_of(line: string): Array<ToolCall> {
+	const pending: Array<PendingLine> = [{ line, is_reserved: false }]
+	const calls: Array<ToolCall> = []
+
+	for (let next = pending.shift(); next !== undefined; next = pending.shift()) {
+		const { is_reserved } = next
+		const readings = shell_segments
+			.quote_aware_commands_of(time_shell.without_heredoc_bodies(next.line))
+			.flatMap((segment) => reading_of(segment, is_reserved) ?? [])
+
+		const bodies = shell_heredoc_bodies(next.line).map((body) => ({ line: body, is_reserved }))
+
+		calls.push(...readings.filter((reading) => is_tool_call(reading)))
+		pending.push(...readings.filter((reading) => is_pending_line(reading)), ...bodies)
+	}
+
+	return calls
+}
+
+// `--flag <value>` or `--flag=<value>`.
+function flag_value(args: ReadonlyArray<string>, flag: string): string | undefined {
+	const prefix = `${flag}=`
+	const index = args.findIndex((argument) => argument === flag || argument.startsWith(prefix))
+	const argument = args[index]
+
+	if (argument === undefined) return undefined
+
+	return argument === flag ? args[index + 1] : argument.slice(prefix.length)
+}
+
+// The workers a tool opens when its flag is missing. **vitest's default is the machine less one**
+// (`maxWorkers`, run mode): `vitest.config.ts` shares the machine only between marked runs, so a lone
+// direct run opens them all. ESLint's `--concurrency` defaults to `off`, one worker.
+function default_workers(name: string, cores: number): number {
+	return name === VITEST ? Math.max(SINGLE_WORKER, cores - 1) : SINGLE_WORKER
+}
+
+// A worker flag's count: half the cores for `auto`, else the number — one for `off` and an unreadable
+// value alike.
+function count_of(value: string, cores: number): number {
+	if (value === AUTO_WORKERS) return Math.max(SINGLE_WORKER, Math.floor(cores / AUTO_CORE_SHARE))
+
+	const count = Number(value)
+
+	return Number.isSafeInteger(count) && count > SINGLE_WORKER ? count : SINGLE_WORKER
+}
+
+function workers_of(call: ToolCall, cores: number = os.availableParallelism()): number {
+	const flag = WORKER_FLAGS[call.name]
+	const value = flag === undefined ? undefined : flag_value(call.args, flag)
+
+	return value === undefined ? default_workers(call.name, cores) : count_of(value, cores)
+}
+
+function memory_of(call: ToolCall, cores: number): number | undefined {
+	const row = core_weights.TOOL_MEMORY[call.name]
+
+	return row === undefined ? undefined : core_weights.MEMORY_MB[row] * workers_of(call, cores)
+}
+
+// The MB the line's largest tool holds, or `undefined` when it launches none the table knows.
+function estimated_memory_mb(
+	line: string,
+	cores: number = os.availableParallelism(),
+): number | undefined {
+	const amounts = tool_calls_of(line).flatMap((call) => memory_of(call, cores) ?? [])
+
+	return amounts.length === 0 ? undefined : Math.max(...amounts)
+}
+
+// True when the line runs eslint with more than one worker, wrapped or not.
+function runs_multi_worker_eslint(
+	line: string,
+	cores: number = os.availableParallelism(),
+): boolean {
+	return tool_calls_of(line).some(
+		(call) => call.name === ESLINT && workers_of(call, cores) > SINGLE_WORKER,
+	)
+}
+
+const command_memory = { estimated_memory_mb, runs_multi_worker_eslint, tool_calls_of }
+
+export { command_memory }
+export type { ToolCall }

package/scripts/gate/core-admission.ts

@@ -1,25 +1,37 @@
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 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
+// this ledger exists to stop. Until the window passes, the claim's memory counts only in `is_admitted`; 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
+// How long after a waiting claim's own claim a lighter claim may still pass it (`may_pass`): long
+// enough for the related checks an edit triggers together, short enough that a heavy claim waits only
+// for the claims already in flight.
+const BYPASS_WINDOW_MS = 30_000
+// A narrowed unit claim still runs one worker: zero would run no test and report the suite green.
+const MIN_GRANT = 1
+// A unit claim narrowed to less than its asked weight over this waits rather than starts (`is_too_narrow`).
+const NARROW_DIVISOR = 2
 
 // 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.
+// `granted` is the narrower weight a unit claim was admitted at past the wait cap; once set, it is the
+// load the claim holds.
 interface LedgerReservation {
 	weight: number
 	claimed_at: number
 	memory_mb?: number | undefined
 	admitted_at?: number | undefined
+	granted?: number | undefined
+	is_unit?: boolean | undefined
 }
 
 interface LedgerEntry {
@@ -37,8 +49,13 @@ interface Overflow {
 	budget: MachineBudget
 }
 
+// `granted` is set only when a unit claim was narrowed to the room left at the wait cap. `waited_ms` is
+// how long the claim waited, about one machine read's window for one admitted on its first read
+// (joshuafolkken/kit#4451).
 interface Admission {
 	overflow: Overflow | undefined
+	granted?: number | undefined
+	waited_ms?: number | undefined
 }
 
 // Claim order, with the filename as the tiebreak so every reader agrees on the same ledger order
@@ -50,54 +67,169 @@ function compare_claim(left: LedgerEntry, right: LedgerEntry): number {
 }
 
 function add_load(totals: LedgerLoad, reservation: LedgerReservation): void {
-	totals.cores += reservation.weight
+	totals.cores += reservation.granted ?? reservation.weight
 	totals.memory_mb += reservation.memory_mb ?? 0
 }
 
-function exceeds(totals: LedgerLoad, budget: MachineBudget): boolean {
+function exceeds(totals: LedgerLoad, budget: LedgerLoad): 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>()
+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_waiting(entry: LedgerEntry): boolean {
+	return entry.reservation.admitted_at === undefined
+}
+
+function fits(entries: ReadonlyArray<LedgerEntry>, limit: LedgerLoad): boolean {
+	return !exceeds(sum_load(entries), limit)
+}
+
+// Where a claim stands in the ledger: the claims already running, whatever their place, and the
+// claims still waiting ahead of it in claim order.
+interface Placement {
+	own: LedgerEntry
+	is_oldest: boolean
+	ahead: Array<LedgerEntry>
+	running: Array<LedgerEntry>
+}
 
-	for (const [index, entry] of reservations.toSorted(compare_claim).entries()) {
-		add_load(totals, entry.reservation)
+function place(key: string, reservations: ReadonlyArray<LedgerEntry>): Placement | undefined {
+	const ordered = reservations.toSorted(compare_claim)
+	const index = ordered.findIndex((entry) => entry.key === key)
+	const own = ordered[index]
 
-		if (index !== 0 && exceeds(totals, limit)) break
+	if (own === undefined) return undefined
 
-		admitted.add(entry.key)
+	return {
+		own,
+		is_oldest: index === 0,
+		ahead: ordered.slice(0, index).filter((entry) => is_waiting(entry)),
+		running: ordered.filter((entry) => entry.key !== key && !is_waiting(entry)),
 	}
+}
 
-	return admitted
+// **The first waiting claim is held by the ledger, never by load from outside it**
+// (joshuafolkken/kit#4313). Holding it on `busy_excess` (joshuafolkken/kit#4238) made a solo gate's unit
+// claim wait out the cap behind one core of Claude sessions or editor load — work deferred, not removed.
+// It is admitted against the cores the ledger leaves, and a unit claim narrows to the room the outside
+// load leaves (`narrowed_weight`), so that load bounds its workers instead of its start. **On an
+// overloaded machine it waits like any claim** (`is_overloaded`, joshuafolkken/kit#4361): every poll reads
+// the load afresh, so it runs once the load falls back under the cap.
+function first_waiter_limit(budget: MachineBudget): LedgerLoad {
+	if (budget.is_overloaded === true) return budget
+
+	return { cores: budget.cores + (budget.busy_excess ?? 0), memory_mb: budget.memory_mb }
+}
+
+// **A light claim passes a waiting one only within a window of that one's claim** (#4313). A claim that
+// fits the room the running claims leave runs instead of queueing behind a heavier claim that does not
+// fit it; a claim made more than the window after a waiter queues behind it, so a waiter is passed by a
+// bounded set of claims and is never starved.
+function may_pass({ own, ahead, running }: Placement, budget: MachineBudget): boolean {
+	const latest = own.reservation.claimed_at - BYPASS_WINDOW_MS
+	const is_recent = ahead.every((entry) => entry.reservation.claimed_at > latest)
+
+	return is_recent && fits([...running, own], budget)
+}
+
+function fits_in_order({ own, ahead, running }: Placement, budget: MachineBudget): boolean {
+	const limit = ahead.length === 0 ? first_waiter_limit(budget) : budget
+
+	return fits([...running, ...ahead, own], limit)
+}
+
+// **A host-wide swap stall holds the oldest claim too** (joshuafolkken/kit#4451). Running alone skipped
+// the memory test, so a lone gate started a 2.4 GB lint into a stall with 1.7 GB free and swapped it
+// for 830 s. Only both together hold: traffic alone is this machine's daily norm (#4313), and a claim
+// heavier than free memory on a calm machine would wait for room that never comes.
+function is_swap_stalled({ own, running }: Placement, budget: MachineBudget): boolean {
+	const needed_mb = sum_load([...running, own]).memory_mb
+
+	return budget.memory_pressured === true && needed_mb > budget.memory_mb
+}
+
+// **The wait cap does not release a swap-stall hold, for any claim** (joshuafolkken/kit#4451): the cap
+// exists so a wedged sibling cannot stall the machine for good, but a stall ends when its traffic stops
+// or its memory is free, so the hold cannot outlive it. Released at the cap, a 2.4 GB lint started into
+// the stall it waited on and swapped for the same 830 s — and holding only a lone claim let a gate's
+// later claims start into the stall at their own caps, after which the lint was no longer alone.
+function is_swap_held(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: MachineBudget,
+): boolean {
+	const placement = place(key, reservations)
+
+	return placement !== undefined && is_swap_stalled(placement, budget)
+}
+
+// The oldest claim runs alone once nothing else does — unless the machine is overloaded, where it waits
+// like the first waiter (`first_waiter_limit`) until a poll reads the load back under the cap, or stalled
+// on swap (`is_swap_stalled`), where it waits until the traffic stops or its memory is free.
+function runs_alone(placement: Placement, budget: MachineBudget): boolean {
+	if (!placement.is_oldest || placement.running.length > 0) return false
+
+	return budget.is_overloaded !== true && !is_swap_stalled(placement, budget)
 }
 
+// **Admission: the oldest claim runs once nothing else does, then claim order, then a bounded pass.**
+// The oldest runs because a single check heavier than the whole machine must not wait for room that will
+// never come — except into a swap stall (`is_swap_stalled`), which passes. Claims that passed it are
+// still running beside it, and their room does come back, so it waits for them rather than starting on
+// top of their cores and memory. A later claim runs when every running claim, every claim waiting
+// ahead of it and its own load fit the budget — the first waiter against the ledger alone
+// (`first_waiter_limit`) — or when it may pass the waiters ahead (`may_pass`).
 function is_admitted(
 	key: string,
 	reservations: ReadonlyArray<LedgerEntry>,
 	budget: MachineBudget,
 ): boolean {
-	return admitted_keys(reservations, budget.cores, budget.memory_mb).has(key)
+	const placement = place(key, reservations)
+
+	if (placement === undefined) return false
+	if (runs_alone(placement, budget)) return true
+
+	return fits_in_order(placement, budget) || may_pass(placement, budget)
 }
 
-function sum_load(reservations: ReadonlyArray<LedgerEntry>): LedgerLoad {
-	const load = { cores: 0, memory_mb: 0 }
+function mark_admitted(entries: Array<LedgerEntry>, key: string): void {
+	const index = entries.findIndex((entry) => entry.key === key)
+	const entry = entries[index]
 
-	for (const entry of reservations) add_load(load, entry.reservation)
+	if (entry === undefined) return
 
-	return load
+	entries[index] = {
+		...entry,
+		reservation: { ...entry.reservation, admitted_at: entry.reservation.claimed_at },
+	}
+}
+
+// **The keys one round of polls admits**, each claim polling in claim order and reading the ledger the
+// claims before it left — an admitted claim is running for every claim after it, as its marker is.
+function admitted_keys(
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: number,
+	memory_budget = Infinity,
+): Set<string> {
+	const limit = { cores: budget, memory_mb: memory_budget }
+	const ledger = [...reservations]
+	const admitted = new Set<string>()
+
+	for (const { key } of reservations.toSorted(compare_claim)) {
+		if (!is_admitted(key, ledger, limit)) continue
+
+		admitted.add(key)
+		mark_admitted(ledger, key)
+	}
+
+	return admitted
 }
 
 function is_ramped(reservation: LedgerReservation, now: number): boolean {
@@ -120,6 +252,59 @@ function total_weight(reservations: ReadonlyArray<LedgerEntry>): number {
 	return sum_load(reservations).cores
 }
 
+// **The weight a unit claim admitted past the wait cap may take: the cores the admitted claims leave
+// free, never below one worker and never above what it asked for.** Admitting it at full width put the
+// ledger past the machine (joshuafolkken/kit#4235); a unit suite is the one tool whose width follows a
+// number, so it narrows instead. `undefined` for any other claim, and for one that fits as asked.
+function narrowed_weight(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	budget: number,
+): number | undefined {
+	const own = reservations.find((entry) => entry.key === key)?.reservation
+
+	if (own?.is_unit !== true) return undefined
+
+	const others = reservations.filter(
+		(entry) => entry.key !== key && entry.reservation.admitted_at !== undefined,
+	)
+	const room = Math.max(MIN_GRANT, Math.floor(budget - total_weight(others)))
+
+	return room >= own.weight ? undefined : room
+}
+
+// **A unit claim narrowed below half its asked width waits for room instead, until the wait cap**
+// (joshuafolkken/kit#4167). vitest fixes its pool at start, so a width read off one busy instant holds for
+// the whole suite after the cores come back: over seven days a run at three workers or fewer took a
+// median 197 s against 76–90 s at seven, and 14 of the 18 slowest unit runs started that narrow. The
+// wait costs at most the cap, past which the claim narrows as before; a narrowing to half or more — a
+// core of editor load beside a solo gate — still starts at once (joshuafolkken/kit#4313).
+function is_too_narrow(
+	key: string,
+	reservations: ReadonlyArray<LedgerEntry>,
+	granted: number | undefined,
+): boolean {
+	if (granted === undefined) return false
+
+	const own = reservations.find((entry) => entry.key === key)?.reservation
+
+	return own !== undefined && granted * NARROW_DIVISOR < own.weight
+}
+
+// The ledger as it stands once `key` is admitted at `granted`, so the overflow it reports counts the
+// narrowed weight rather than the one the claim asked for.
+function with_grant<T extends LedgerEntry>(
+	key: string,
+	reservations: ReadonlyArray<T>,
+	granted: number | undefined,
+): Array<T> {
+	if (granted === undefined) return [...reservations]
+
+	return reservations.map((entry) =>
+		entry.key === key ? { ...entry, reservation: { ...entry.reservation, granted } } : entry,
+	)
+}
+
 // 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)
@@ -149,13 +334,18 @@ function describe_overflow(admission: Admission): string | undefined {
 }
 
 const core_admission = {
+	BYPASS_WINDOW_MS,
 	RAMP_UP_MS,
 	admitted_keys,
 	admitted_load,
 	describe_overflow,
 	is_admitted,
+	is_swap_held,
+	is_too_narrow,
 	ledger_load,
+	narrowed_weight,
 	sum_load,
+	with_grant,
 }
 
 export type { Admission, LedgerEntry, Overflow }