@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/gate/check-related.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { lint_related_scope } from '#scripts/lint/lint-related-scope'
+import { review_record_pinned } from '#scripts/review/review-record-pinned'
+import { execa } from 'execa'
+import run_parallel from 'run-parallel'
+import { check_related_pinned } from './check-related-pinned'
+import { check_related_reuse } from './check-related-reuse'
+import { check_related_section, type CheckResult } from './check-related-section'
+import { check_related_unplanned } from './check-related-unplanned'
+import { gate_labels } from './gate-labels'
+import { gate_log } from './gate-log'
+import { metrics_totals } from './metrics-totals'
+import { verification_tail } from './verification-tail'
+
+const COMMAND = 'check:related'
+// One file per checkout beside the gate's own log, overwritten by each run.
+const LOG_PATH = stamp_file.stamp_path(
+	'josh-check-related-log-',
+	PROJECT_ROOT,
+	gate_log.GATE_LOG_SUFFIX,
+)
+const LINT_RELATED = 'lint:related'
+// The verdict `lint:related` itself prints last, under its own label.
+const LINT_PASSED = verification_tail.format_verdict(lint_related_scope.COMMAND_LABEL, [])
+const CHECKS: ReadonlyArray<string> = [
+	LINT_RELATED,
+	'test:related',
+	gate_labels.TYPE_CHECK_TARGET,
+	'cspell:dot',
+]
+const REUSED = 'reused'
+const METRICS_STOP =
+	'`josh ship`\'s pre-detach stops on the metrics notice above unless the branch approval already names the total; settle it first (`pnpm josh metrics --accept --reason "<why>"`); the accept needs no `check:related` re-run, as the notice changed no exit code'
+
+type CheckExecutor = (command: string) => Promise<CheckResult>
+type ProcessRunner = (
+	file: string,
+	args: Array<string>,
+	options: { all: true; reject: false },
+) => Promise<{ all: string | null; exitCode?: number }>
+
+async function run_execa(
+	file: string,
+	args: Array<string>,
+	options: { all: true; reject: false },
+): Promise<{ all: string | null; exitCode?: number }> {
+	return await execa(file, args, options)
+}
+
+function failed_result(command: string, error: unknown): CheckResult {
+	return {
+		command,
+		exit_code: 1,
+		output: error instanceof Error ? error.message : String(error),
+	}
+}
+
+async function execute_check(
+	command: string,
+	run: ProcessRunner = run_execa,
+): Promise<CheckResult> {
+	try {
+		const result = await run('pnpm', ['josh', command], { all: true, reject: false })
+
+		return { command, exit_code: result.exitCode ?? 1, output: result.all ?? '' }
+	} catch (error) {
+		return failed_result(command, error)
+	}
+}
+
+async function start_check(
+	command: string,
+	execute: CheckExecutor,
+	complete: run_parallel.TaskCallback<CheckResult>,
+): Promise<void> {
+	try {
+		const result = await execute(command)
+
+		// eslint-disable-next-line unicorn/no-null -- run-parallel requires null for successful tasks.
+		complete(null, result)
+	} catch (error) {
+		// eslint-disable-next-line unicorn/no-null -- run-parallel requires null for successful tasks.
+		complete(null, failed_result(command, error))
+	}
+}
+
+async function run_checks(
+	execute: CheckExecutor = execute_check,
+	commands: ReadonlyArray<string> = CHECKS,
+): Promise<Array<CheckResult>> {
+	const tasks = commands.map((command): run_parallel.Task<CheckResult> => {
+		return (complete): void => {
+			void start_check(command, execute, complete)
+		}
+	})
+
+	return await new Promise<Array<CheckResult>>((resolve): void => {
+		run_parallel(tasks, (_error, results): void => {
+			resolve(results)
+		})
+	})
+}
+
+function failed_commands(results: ReadonlyArray<CheckResult>): ReadonlyArray<string> {
+	return results.filter((result) => result.exit_code !== 0).map((result) => result.command)
+}
+
+// The verdict is the last line, as every josh check prints it, so a reader of the tail sees every
+// check that failed rather than only the section that finished last (joshuafolkken/kit#4940).
+function checks_line(results: ReadonlyArray<CheckResult>): string {
+	return verification_tail.format_verdict(COMMAND, failed_commands(results))
+}
+
+// Each failed check and the command that reproduces it alone, above the log notice (joshuafolkken/kit#5162).
+function failure_lines(results: ReadonlyArray<CheckResult>): string {
+	const failed = failed_commands(results)
+	if (failed.length === 0) return ''
+
+	const lines = failed.map((command) =>
+		verification_tail.format_rerun(command, `pnpm josh ${command}`),
+	)
+
+	return `${COMMAND} — next:\n${lines.join('\n')}\n`
+}
+
+// Every check's whole output, kept where the console's size limit cannot reach, as `josh gate` keeps its own.
+function write_log(results: ReadonlyArray<CheckResult>, target: string): string | undefined {
+	const entries = results.map((result) => ({
+		header: `${result.command}: ${check_related_section.result_status(result)}`,
+		output: result.output,
+	}))
+
+	return gate_log.write_gate_log(entries, target)
+}
+
+function reused_suffix(reused: ReadonlySet<string>): string {
+	return reused.size === 0 ? '' : ` (reused: ${[...reused].join(', ')})`
+}
+
+// A notice is never a failure, so a passing verdict line alone hid it from a reader of the last lines,
+// and the ship's pre-detach stopped on it (joshuafolkken/kit#4987).
+function verdict_line(
+	results: ReadonlyArray<CheckResult>,
+	has_metrics_notice: boolean,
+	reused: ReadonlySet<string>,
+): string {
+	const line = `${checks_line(results)}${reused_suffix(reused)}`
+
+	return has_metrics_notice ? `${line} — ${METRICS_STOP}` : line
+}
+
+// `josh lint:related` ends its section with the metrics growth notice, which the sections after it
+// bury; it is repeated above the verdict so the tail still carries what stops `josh ship`
+// (joshuafolkken/kit#4939).
+function metrics_notice(results: ReadonlyArray<CheckResult>): string | undefined {
+	const output = results.find((result) => result.command === LINT_RELATED)?.output ?? ''
+	const start = output.indexOf(metrics_totals.NOTICE_HEADING)
+
+	if (start === -1) return undefined
+
+	// The lint's own verdict closes its section; it is not part of the notice.
+	return output.slice(start).replace(LINT_PASSED, '').trimEnd()
+}
+
+function report_reused(reused: ReadonlySet<string>): void {
+	for (const command of reused) {
+		process.stdout.write(`\n=== ${command}: ${REUSED} ===\n`)
+	}
+}
+
+interface ReportOptions {
+	pinned_notice?: string | undefined
+	unplanned_notice?: string | undefined
+	reused?: ReadonlySet<string>
+	log_target?: string
+	is_full?: boolean
+}
+
+function report_notices(notices: ReadonlyArray<string | undefined>): void {
+	for (const notice of notices) {
+		if (notice !== undefined) process.stdout.write(`\n${notice}\n`)
+	}
+}
+
+function report_results(results: ReadonlyArray<CheckResult>, options: ReportOptions = {}): void {
+	const { is_full, log_target = LOG_PATH, pinned_notice, reused = new Set<string>() } = options
+
+	report_reused(reused)
+
+	for (const result of results) {
+		process.stdout.write(check_related_section.format_section(result, is_full))
+	}
+
+	const metrics = metrics_notice(results)
+
+	report_notices([metrics, pinned_notice, options.unplanned_notice])
+
+	const log = { path: write_log(results, log_target) }
+	const verdict = verdict_line(results, metrics !== undefined, reused)
+
+	process.stdout.write(
+		`\n${verification_tail.format_tail({ failures: failure_lines(results), log, verdict })}`,
+	)
+}
+
+function exit_code(results: ReadonlyArray<CheckResult>): number {
+	return results.every((result: CheckResult): boolean => result.exit_code === 0) ? 0 : 1
+}
+
+// **The first check of a round-1 fix starts `josh test:pinned` again on the fixed tree**
+// (joshuafolkken/kit#4948): left to `josh review:record`, the restart came minutes before the ship, and
+// its pre-detach waited out a whole run. Started here, the check runs beside these four; a tree that did
+// not move, or a run outside a lane child, starts nothing. A verdict that check already reached on this
+// tree is printed above the verdict line, waited for when this run started it (`check-related-pinned.ts`).
+// A check whose green record still holds is not run (`check-related-reuse.ts`).
+async function run_all(
+	root?: string,
+	execute: CheckExecutor = execute_check,
+	is_full = false,
+): Promise<number> {
+	const is_started = await review_record_pinned.restart_in_lane(root)
+	const tree = await check_related_reuse.read_tree()
+	const reused = await check_related_reuse.reusable(CHECKS, tree)
+	const results = await run_checks(
+		execute,
+		CHECKS.filter((command) => !reused.has(command)),
+	)
+
+	await check_related_reuse.record(results, tree)
+	report_results(results, {
+		is_full,
+		pinned_notice: await check_related_pinned.notice(root, is_started),
+		unplanned_notice: await check_related_unplanned.notice(),
+		reused,
+	})
+
+	return exit_code(results)
+}
+
+const check_related = {
+	CHECKS,
+	METRICS_STOP,
+	REUSED,
+	execute_check,
+	exit_code,
+	report_results,
+	run_all,
+	run_checks,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await check_related.run_all(
+		undefined,
+		execute_check,
+		check_related_section.is_full_requested(process.argv),
+	)
+}
+
+export type { CheckExecutor }
+export { check_related }
+
+export { type CheckResult } from './check-related-section'

package/scripts/gate/command-memory.ts

@@ -186,7 +186,7 @@ function runs_multi_worker_eslint(
 	)
 }
 
-const command_memory = { estimated_memory_mb, runs_multi_worker_eslint, tool_calls_of }
+const command_memory = { estimated_memory_mb, runs_multi_worker_eslint, tool_calls_of, workers_of }
 
 export { command_memory }
 export type { ToolCall }

package/scripts/gate/core-admission.ts

@@ -1,4 +1,5 @@
 import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { core_budget_timing } from './core-budget-timing'
 import type { LedgerLoad, MachineBudget } from './machine-capacity'
 
 // The ledger's admission arithmetic, kept apart from the markers `core-budget.ts` reads and writes so
@@ -16,6 +17,11 @@ const RAMP_UP_MS = 30_000
 // 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
+// How long after a heavier waiting claim a lighter one may still pass it: half the wait cap
+// (`core-budget-timing.ts`), so the heavier claim still has the cap's second half to find its room before
+// it starts narrowed or past the budget.
+const WAIT_CAP_SHARE = 0.5
+const HEAVIER_BYPASS_WINDOW_MS = core_budget_timing.WAIT_CAP_MS * WAIT_CAP_SHARE
 // 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`).
@@ -128,15 +134,26 @@ function first_waiter_limit(budget: MachineBudget): LedgerLoad {
 	return { cores: budget.cores + (budget.busy_excess ?? 0), memory_mb: budget.memory_mb }
 }
 
+// Whether `own` may pass one waiter ahead: any waiter claimed within the window before it, and a heavier
+// one within the longer window (joshuafolkken/kit#4595) — a two-core `lint:related` queued for most of the
+// cap behind a unit claim of five cores that the running claims had no room for.
+function may_pass_waiter(own: LedgerReservation, waiter: LedgerReservation): boolean {
+	const since_ms = own.claimed_at - waiter.claimed_at
+
+	if (since_ms < BYPASS_WINDOW_MS) return true
+
+	return waiter.weight > own.weight && since_ms < HEAVIER_BYPASS_WINDOW_MS
+}
+
 // **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.
+// fit it; a claim made more than the window after a waiter — the heavier window after a heavier one
+// (`may_pass_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)
+	const is_passable = ahead.every((entry) => may_pass_waiter(own.reservation, entry.reservation))
 
-	return is_recent && fits([...running, own], budget)
+	return is_passable && fits([...running, own], budget)
 }
 
 function fits_in_order({ own, ahead, running }: Placement, budget: MachineBudget): boolean {
@@ -252,7 +269,7 @@ 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
+// **The weight a unit claim admitted past its wait (the cap, or outside load that does not ease) 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.
@@ -335,6 +352,7 @@ function describe_overflow(admission: Admission): string | undefined {
 
 const core_admission = {
 	BYPASS_WINDOW_MS,
+	HEAVIER_BYPASS_WINDOW_MS,
 	RAMP_UP_MS,
 	admitted_keys,
 	admitted_load,

package/scripts/gate/core-budget-timing.ts

@@ -6,14 +6,21 @@ const POLL_INTERVAL_MS = 50
 // for good. Two minutes is well past a unit suite's worst measured time under six-way load. A claim a
 // swap stall holds is the exception (`core_admission.is_swap_held`).
 const WAIT_CAP_MS = 120_000
+// How long the load may go without easing before a held reservation is admitted at minimum width ahead
+// of the cap (`busy_average.is_unrelieved`): ten of the busy average's windows.
+const EASE_WINDOW_MS = 30_000
+
+interface Cadence {
+	poll_interval_ms: number
+	wait_cap_ms: number
+	ease_window_ms: number
+}
 
 // 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 {
+interface TimingConfig extends Cadence {
 	now: () => number
 	sleep: (ms: number) => Promise<void>
-	poll_interval_ms: number
-	wait_cap_ms: number
 }
 
 async function default_sleep(ms: number): Promise<void> {
@@ -22,16 +29,23 @@ async function default_sleep(ms: number): Promise<void> {
 	})
 }
 
+function resolve_cadence(options: Partial<Cadence>): Cadence {
+	return {
+		poll_interval_ms: options.poll_interval_ms ?? POLL_INTERVAL_MS,
+		wait_cap_ms: options.wait_cap_ms ?? WAIT_CAP_MS,
+		ease_window_ms: options.ease_window_ms ?? EASE_WINDOW_MS,
+	}
+}
+
 function resolve_timing(options: Partial<TimingConfig>): 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,
+		...resolve_cadence(options),
 	}
 }
 
-const core_budget_timing = { resolve_timing }
+const core_budget_timing = { WAIT_CAP_MS, resolve_timing }
 
 export type { TimingConfig }
 export { core_budget_timing }

package/scripts/gate/core-budget.ts

@@ -9,7 +9,7 @@ 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 { 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'
@@ -29,7 +29,7 @@ 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 + 2 + 2) + unit_cap(cores - 6)` is exactly `cores` — so a single gate's four claims sum
+// `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.
@@ -53,7 +53,7 @@ const MIN_BUDGET = 1
 // 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`).
+// 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(),
@@ -86,6 +86,7 @@ interface ReserveOptions {
 	report?: (line: string) => void
 	read_machine?: () => Promise<MachineReading>
 	wait_cap_ms?: number
+	ease_window_ms?: number
 	poll_interval_ms?: number
 	directory?: string
 	now?: () => number
@@ -188,6 +189,8 @@ interface WaitContext extends TimingConfig {
 	deadline: number
 	fields: ReservationFields
 	busy_samples: Array<BusySample>
+	// Unset until the first reading of the machine (`busy_average.with_ease`).
+	ease?: LoadEase | undefined
 }
 
 // **A claim alone in the ledger reads the machine too** (joshuafolkken/kit#4238): load outside the
@@ -211,6 +214,8 @@ async function current_budget(
 
 	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)
 }
 
@@ -250,21 +255,37 @@ 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 past the wait cap.
+	// 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)
 
-	// 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)
-	) {
+	if (is_wait_spent(context, reservations, budget)) {
 		const held = core_admission.with_grant(context.key, reservations, granted)
 
 		return admit(context, overflow_of(context, held, budget), granted)
@@ -275,7 +296,8 @@ async function poll_admission(context: WaitContext): Promise<Admission | undefin
 	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> {
@@ -370,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
@@ -381,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,
@@ -413,6 +441,7 @@ const core_budget = {
 	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

@@ -1,4 +1,5 @@
-import { lane_ledger, type CoreWaitRecord } from '#scripts/lane/lane-ledger'
+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
@@ -21,7 +22,7 @@ interface AdmittedClaim {
 type WaitSink = (wait: CoreWaitRecord) => Promise<void>
 
 async function to_ledger(wait: CoreWaitRecord): Promise<void> {
-	await lane_ledger.record_core_wait(wait)
+	await lane_ledger_write.record_core_wait(wait)
 }
 
 function wait_of(claim: AdmittedClaim, now: number): CoreWaitRecord | undefined {

package/scripts/gate/core-wait.ts

@@ -95,6 +95,25 @@ function hold_reason(
 	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]}`
@@ -102,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
@@ -152,6 +174,7 @@ function waits_of(
 const core_wait = {
 	WAIT_REASONS,
 	hold_reason,
+	is_outside_held,
 	wait_line,
 	wait_reason,
 	waits_of,

package/scripts/gate/core-weights.ts

@@ -10,15 +10,19 @@ interface Measurement {
 // **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 and the spell 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.
+// 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: 6, wall_s: 5.6 },
+	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 },
@@ -57,9 +61,13 @@ const CORE_WEIGHTS = {
 // 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.
+// 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,