@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/gate/core-admission.ts

@@ -1,7 +1,7 @@
 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).
+// 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
@@ -63,7 +63,7 @@ function exceeds(totals: LedgerLoad, budget: MachineBudget): boolean {
 // 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).
+// cores would not fit.
 function admitted_keys(
 	reservations: ReadonlyArray<LedgerEntry>,
 	budget: number,

package/scripts/gate/core-budget.ts

@@ -6,25 +6,20 @@ import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
 import { process_identity } from '#scripts/josh/process-identity'
 import { process_owner_schema } from '#scripts/josh/process-owner'
 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 { 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).
+// A machine-wide weighted core budget with admission control.
 //
-// **The gate's CPU budget used to be decided once, at the gate's start, and never revisited.**
-// `announce_gate_plan` counted the unit runs alive the instant it began and sized itself against that
-// one reading — so the common case (nothing else in a gate yet) had every gate conclude it was alone
-// and reserve the whole machine, and only a gate that *started* later deferred. Three overlapping gates
-// therefore demanded thirty cores of an eleven-core machine, which is the "usually fine, occasionally
-// saturates" this module removes.
-//
-// **The fix is admission rather than recomputation.** A heavy step declares the cores it needs, claims
-// a place in a machine-wide ledger, and waits while the ledger is full — so the peak cannot exceed the
-// budget by construction, and the asymmetry ("whoever started first took everything") disappears
-// because a place is claimed in claim order rather than seized at start. Waiting is what replaces the
-// recomputation `unit-worker-share.ts` did: a step that could not fit does not shrink, it defers.
+// **Admission rather than a budget sized once at the gate's start.** A budget read once at the start
+// has every gate that sees no sibling conclude it is alone and reserve the whole machine, so
+// overlapping gates oversubscribe it. Instead a heavy step declares the cores it needs, claims a place
+// in a machine-wide ledger, and waits while the ledger is full — so the peak cannot exceed the budget
+// by construction, and a place is claimed in claim order rather than seized at start. A step that
+// could not fit does not shrink, it defers.
 //
 // **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
@@ -32,12 +27,12 @@ import { machine_capacity, type MachineBudget, type MachineReading } from './mac
 // to the whole budget and 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** (joshuafolkken/kit#1245). A run
+// **Liveness is `process_identity`'s, reused rather than re-invented.** A run
 // 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
+// **The budget is what the machine has free, in cores and in memory.** 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.
@@ -55,7 +50,7 @@ const WAIT_CAP_MS = 120_000
 const MIN_BUDGET = 1
 
 // **The cores each heavy tool occupies, declared once for both places that reserve them**
-// (joshuafolkken/kit#3345). `gate-plan.ts`'s checks and the `josh` commands that run the same tools
+// `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
@@ -67,7 +62,7 @@ const CORE_WEIGHTS = {
 	eslint_scan: 1,
 } as const
 
-// **The memory each heavy tool holds, declared beside its cores** (joshuafolkken/kit#3371): peak
+// **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
@@ -81,7 +76,7 @@ const MEMORY_MB = {
 } 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
+// `josh gate` reserves per check and then spawns `pnpm josh lint`. Without
 // the mark, that child's own dispatch would claim a second place for the cores its parent already
 // holds. Every holder sets it, and every child inherits it through the environment and claims nothing.
 const HELD_KEY = 'JOSH_CORE_RESERVED'
@@ -135,13 +130,7 @@ function read_reservation(source: string): Reservation | undefined {
 
 	if (raw === undefined) return undefined
 
-	try {
-		const parsed = reservation_schema.safeParse(JSON.parse(raw))
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, reservation_schema)
 }
 
 // **A dead marker is removed, not merely skipped** — otherwise a reissued pid turns a leaked place into
@@ -369,7 +358,7 @@ async function with_held_mark<T>(run: () => Promise<T>): Promise<T> {
 }
 
 // **A command's reservation: the gate's claim, unless a parent already holds the cores**
-// (joshuafolkken/kit#3345). `josh-logic.ts` calls this around every command that declares a weight.
+// `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
 // release steps. A solo run is admitted on the first read, so a run with room on the machine starts
 // with no wait. A command inside a unit suite claims nothing either, for the reason `reserved-run.ts`

package/scripts/gate/gate-ledger.ts

@@ -0,0 +1,114 @@
+import { process_identity } from '#scripts/josh/process-identity'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { core_admission } from './core-admission'
+import { core_budget } from './core-budget'
+import { gate_plan } from './gate-plan'
+import type { GateStepResult } from './gate-report'
+import { machine_capacity } from './machine-capacity'
+
+// A finished gate's line in the lane ledger: its duration, its verdict, its
+// unit suite's duration, and the load it ran beside, so `josh metrics`
+// compares only gates the machine was quiet for. Another gate's span is not the only load: another
+// lane's lint, related tests or `ship` doubled a solo gate's duration within minutes.
+//
+// **The machine is read where none of the gate's own checks runs — before the first starts and after
+// the last ends.** The load average cannot tell the two apart: a solo gate started at 4 on the 11-core
+// machine ended at 21, its own load. The reading is the core budget's own, so "quiet" means what
+// admission means by it: no whole core busy beyond the baseline the gate's weights were measured beside.
+//
+// **Between the ends, the load is read off the core budget's ledger, not the CPU**.
+// Two readings missed every lane whose lint, tests or `ship` ran only while
+// the gate did: seven lanes moved the solo median from 50.5s to 60.9s with no commit between. The CPU
+// mid-gate holds this gate's own checks, whose declared weights are not what they burn, so the ledger
+// is what tells the two apart: another `josh` run's admitted claim is another process's place, and its
+// weight is the cores it holds. A claim still waiting holds none.
+
+const NO_LEDGER_CORES = 0
+// Often enough to catch another lane's shortest related lint, seldom enough that reading the markers —
+// a process probe each — costs the gate nothing it could measure.
+const SAMPLE_INTERVAL_MS = 3000
+
+// Where the line goes, the external load read so far — before the first check started, then every
+// sample since — and the timer taking the samples. No readings and no timer when no ledger was
+// resolved: a suite driving the gate reads the machine for nothing.
+interface GateLedgerStart {
+	ledger_path: string | undefined
+	readings: Array<number | undefined>
+	sampler: ReturnType<typeof setInterval> | undefined
+}
+
+interface GateOutcome {
+	elapsed_ms: number
+	is_passed: boolean
+}
+
+// `undefined` where the machine could not be read — a CI runner, a CPU quota narrower than the host.
+async function read_external_cores(): Promise<number | undefined> {
+	const { busy_cores } = await machine_capacity.read_machine()
+
+	if (busy_cores === undefined) return undefined
+
+	return machine_capacity.external_cores(busy_cores, NO_LEDGER_CORES)
+}
+
+// The cores other processes' admitted claims hold now. This gate's own claims are written by this
+// process, and its checks' dispatches claim nothing under its held mark.
+function read_foreign_cores(): number {
+	const foreign = core_budget
+		.live_reservations()
+		.filter(
+			({ reservation }) =>
+				!process_identity.is_own_process(reservation.pid, reservation.process_start),
+		)
+
+	return core_admission.ledger_load(foreign, Date.now()).cores
+}
+
+// The highest reading; one unread reading leaves the whole gate unread rather than half-quiet.
+function peak(readings: ReadonlyArray<number | undefined>): number | undefined {
+	const read = readings.filter((reading) => reading !== undefined)
+
+	if (read.length < readings.length) return undefined
+
+	return Math.max(...read)
+}
+
+// Unreferenced, so a gate that throws before `record` never holds the process open on the timer.
+function start_sampler(readings: Array<number | undefined>): ReturnType<typeof setInterval> {
+	return setInterval(() => {
+		readings.push(read_foreign_cores())
+	}, SAMPLE_INTERVAL_MS).unref()
+}
+
+async function start(ledger_path: string | undefined): Promise<GateLedgerStart> {
+	if (ledger_path === undefined) return { ledger_path, readings: [], sampler: undefined }
+
+	const readings = [await read_external_cores()]
+
+	return { ledger_path, readings, sampler: start_sampler(readings) }
+}
+
+// The caller measures the elapsed time before this, so the end's reading is never part of it.
+async function record(
+	begun: GateLedgerStart,
+	results: ReadonlyArray<GateStepResult>,
+	outcome: GateOutcome,
+): Promise<void> {
+	clearInterval(begun.sampler)
+
+	if (begun.ledger_path === undefined) return
+
+	const unit_ms = results.find((result) => result.label === gate_plan.UNIT_LABEL)?.elapsed_ms
+	const external_cores = peak([...begun.readings, await read_external_cores()])
+
+	await lane_ledger.record_gate(begun.ledger_path, { ...outcome, unit_ms, external_cores })
+}
+
+const gate_ledger = {
+	SAMPLE_INTERVAL_MS,
+	record,
+	start,
+}
+
+export type { GateLedgerStart }
+export { gate_ledger }

package/scripts/gate/gate-log.ts

@@ -1,16 +1,14 @@
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { stamp_file } from '#scripts/josh/stamp-file'
 
-// The verification gate's full output, kept somewhere the console's size limit cannot reach
-// (joshuafolkken/kit#1227).
+// The verification gate's full output, kept somewhere the console's size limit cannot reach.
 //
-// **The problem is that the only copy of a failure's detail was the console.** `josh gate` buffers
-// every check and prints the failing ones whole, and joshuafolkken/kit#1173 then declared
-// `BASH_MAX_OUTPUT_LENGTH` at 8,000 characters — a cap on what a command may carry into an agent's
-// context, with a measured p99 of 15,989 characters for a Bash call. The verdict is the last line and
-// so always survives, which is why a red gate can never read as green; what does not survive is the
-// middle, and the middle is where the failure says what it was. The escape hatch was to re-run one
-// check by hand, which is a judgement the reader has to make about output they cannot see.
+// **The console cannot be the only copy of a failure's detail.** `josh gate` buffers every check and
+// prints the failing ones whole, and `BASH_MAX_OUTPUT_LENGTH` caps what a command may carry into an
+// agent's context. The verdict is the last line and so always survives, which is why a red gate can
+// never read as green; what does not survive is the middle, and the middle is where the failure says
+// what it was. Re-running one check by hand is a judgement the reader would have to make about output
+// they cannot see.
 //
 // So the gate writes every check's output to a file and prints where it is. Nothing about the
 // verdict changes; what changes is that the detail behind it no longer exists only in a window that

package/scripts/gate/gate-plan.ts

@@ -4,7 +4,7 @@ import { unit_worker_share } from '#scripts/test/unit-worker-share'
 import { core_budget } from './core-budget'
 
 // How many of the gate's checks run at once, and how wide the one elastic check may fan out —
-// both derived from the machine rather than fixed at four (joshuafolkken/kit#1258).
+// both derived from the machine rather than fixed at four.
 //
 // **The measurement this table is built from.** Apple M3 Pro, 11 logical cores (5 performance +
 // 6 efficiency, about 9 cores of aggregate throughput on this workload), warm caches, each check
@@ -19,10 +19,8 @@ import { core_budget } from './core-budget'
 //
 // Two things follow. **The concurrent gate is already the faster shape** — 15.1s together against
 // 19.1s back to back, the median of three interleaved runs on the same tree, and the one pair
-// `verification-gate.ts` and `docs/josh-commands.md` quote too — so this is a widening of an
-// existing win, not a repair of the regression joshuafolkken/kit#1258 was filed for: that was
-// real when the type check and the spell check cost 6.9s and 3.6s of CPU, and joshuafolkken/kit#1256
-// removed it by giving both a cache. **And the unit suite is the only check worth sizing**: it
+// `docs/josh-commands.md` quotes too — so this is a widening of an existing win. **And the unit
+// suite is the only check worth sizing**: it
 // alone accounts for 107 of the 122 CPU-seconds, because vitest opens one worker per core while
 // the other three are one or two processes each.
 
@@ -30,6 +28,8 @@ interface GateCheck {
 	label: string
 	// The `josh` sub-command that defines the check, and the one an appended argument belongs to.
 	target: string
+	// Arguments the gate always hands the target, before any appended one.
+	args?: ReadonlyArray<string>
 	// Cores this check holds for as long as it runs — the measured ratio above, floored to whole
 	// cores and never below one. Floored rather than rounded because this is the share the *other*
 	// checks must give up: over-reserving costs the elastic check workers it would have used.
@@ -37,40 +37,46 @@ interface GateCheck {
 	// 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.
+	// none waited for. The unit suite's is per worker, so it is derived instead.
 	memory_mb?: number
+	// A check whose `josh` command is kit-only, so a consumer's gate leaves it out rather than running
+	// a command that is not in the published package. It restates the command
+	// entry's own `is_kit_only`, because the command map imports this module; `gate-plan.test.ts` pins
+	// that the two agree.
+	is_kit_only?: boolean
 }
 
 const LINT_LABEL = 'lint'
 const TYPE_CHECK_LABEL = 'check'
 const UNIT_LABEL = 'test:unit'
 const BEHAVIOR_LABEL = 'behavior'
+const METRICS_LABEL = 'metrics'
 
 // The checks whose warnings must survive the green record: eslint (the `lint` step) and svelte-check
 // (the `check` step) both exit 0 while reporting per-tree warnings a developer needs to see again, so
-// reusing a record taken from such a run would hide them (joshuafolkken/kit#1328). Every other step's
+// reusing a record taken from such a run would hide them. Every other step's
 // warning-shaped output — a Vite config deprecation printed by `test:unit`, say — is not a per-tree
-// finding and repeats every run, so it must not withhold the record. This is what `has_checker_warning`
-// narrows the withholding path down to (joshuafolkken/kit#2318).
+// finding and repeats every run, so it must not withhold the record. `has_checker_warning` narrows
+// the withholding path down to these.
 const WARNING_CHECKER_LABELS: ReadonlyArray<string> = [LINT_LABEL, TYPE_CHECK_LABEL]
 
 // The checks that do not fan out across every core, in the order their output is printed. They are
-// named apart from the unit suite because CI runs them on their own runner (joshuafolkken/kit#1226):
+// named apart from the unit suite because CI runs them on their own runner:
 // the unit suite is the only check that fans out across every core, so on a 4-core GitHub runner it
 // and the others spent the whole job taking cores off each other.
 //
-// **The behavior check belongs here, and it reserves no core** (joshuafolkken/kit#2365). It reads one
+// **The behavior check belongs here, and it reserves no core**. It reads one
 // recorded transcript rather than the tree, so it is I/O-bound and a zero reservation leaves
 // `RESERVED_CORES` and the unit worker cap exactly where the other three were measured. Being a static
 // check rather than one appended after the unit suite is what keeps the plan's shape intact: the
 // `--no-unit` set stays "the whole gate minus the unit suite", and a CI runner — which has no recorded
 // transcripts — runs it as a trivial green rather than skipping it.
 //
-// **The three reserving weights are `core_budget.CORE_WEIGHTS`** (joshuafolkken/kit#3345), the same
+// **The three reserving weights are `core_budget.CORE_WEIGHTS`**, the same
 // numbers the `josh lint`, `josh check` and `josh cspell:dot` commands claim when run directly.
 //
-// **The two zero weights were measured again for joshuafolkken/kit#3345, and they stay zero.** These are
-// warm runs on the 11-core machine on 2026-10-06. `behavior` took 0.6s of wall for 0.7s of CPU, which
+// **The two zero weights are measured, and they stay zero.** These are warm runs on the 11-core
+// machine. `behavior` took 0.6s of wall for 0.7s of CPU, which
 // is node starting up. `exports:unused` took 5.5s of wall for 9.0s of CPU, about 1.6 cores. Floored,
 // that would be one core, but a reservation lasts the whole gate's plan, not the check's five seconds.
 // It would lower `RESERVED_CORES` from 4 to 5 and cut the solo unit cap from 7 workers to 6 for the
@@ -96,11 +102,23 @@ const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
 		memory_mb: core_budget.MEMORY_MB.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
+	// **The unused-member check reserves no core**: it builds one TypeScript
 	// program and walks it for about 5s, and it is over well before lint and the type check. A
 	// reservation would only take a place from the four-core CI runner's fan-out and a worker from the
 	// unit suite for the whole gate.
 	{ label: 'exports', target: 'exports:unused', reserved_cores: 0 },
+	// **The metrics ratchet is kit's own**: it holds kit's repository-wide
+	// totals to the merge-base's. It is one in-process eslint pass with only `max-lines` enabled, over
+	// in a few seconds, so it reserves no core for the reason the unused-member check above does not.
+	// It times no startup here: beside the unit suite that reads the load, not josh.
+	{
+		label: METRICS_LABEL,
+		target: METRICS_LABEL,
+		args: ['--no-startup'],
+		reserved_cores: 0,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
+		is_kit_only: true,
+	},
 ]
 
 // The checks, in the order their output is printed — the static set, then the unit suite last (the
@@ -116,8 +134,15 @@ const GATE_CHECKS: ReadonlyArray<GateCheck> = [
 // set safe is that nothing downstream may mistake it for the full gate: `verification-gate.ts`
 // withholds both the green-gate record and the in-flight marker on a partial run, so a `--no-unit`
 // gate can never tell `josh review:brief` that the unit suite passed on this tree.
-function select_gate_checks(is_unit_included: boolean): ReadonlyArray<GateCheck> {
-	return is_unit_included ? GATE_CHECKS : STATIC_CHECKS
+//
+// A consumer's gate also drops the kit-only checks, whose commands its installed kit does not have.
+function select_gate_checks(
+	is_unit_included: boolean,
+	is_kit_repository = true,
+): ReadonlyArray<GateCheck> {
+	const checks = is_unit_included ? GATE_CHECKS : STATIC_CHECKS
+
+	return is_kit_repository ? checks : checks.filter((check) => check.is_kit_only !== true)
 }
 
 // Asked of the plan rather than of the flag, so the one question "did this gate run the unit suite"
@@ -169,7 +194,7 @@ interface GatePlan {
 }
 
 // This gate's share of the machine — the cores it may plan against once the other gates in flight
-// have theirs (joshuafolkken/kit#1547).
+// have theirs.
 //
 // **At one run this is the identity, and that is the whole argument that solo behavior is
 // unchanged.** `Math.floor(cores / 1)` is `cores`, so a solo gate and a CI runner hand the admission
@@ -197,8 +222,8 @@ function shared_cores(available_cores: number, concurrent_runs: number): number
 // difference between two checks sharing a core and four fighting over it.
 //
 // **Under concurrency it is the only lever there is, and that is a measurement rather than a
-// preference** (joshuafolkken/kit#1547). `josh gate` starts four checks at once and joshuafolkken/kit#1515
-// sized only the fourth, so six lanes put 18 unbounded checks on 11 cores: measured on that machine,
+// preference**. `josh gate` starts four checks at once and sizing only the unit suite let six lanes
+// put 18 unbounded checks on 11 cores: measured on that machine,
 // one gate took 254.1s with lint alone at 252.9s against the 5.2s the table above records for it
 // solo. The obvious repair — hand each of the other three a worker count the way the unit suite gets
 // one — **does not exist to be applied**: eslint 10's `--concurrency` defaults to `off` and is
@@ -235,7 +260,7 @@ function resolve_concurrency(
 // 107s). A machine smaller than the measured one is left uncapped; see `MEASURED_CORES`.
 //
 // **The table above is a measurement of one gate on an idle machine, and `concurrent_runs` is what
-// says whether that is the situation** (joshuafolkken/kit#1515). Six lanes each reading "11 cores,
+// says whether that is the situation**. Six lanes each reading "11 cores,
 // take 7" put 42 workers on 11 cores, at a load average of 14.97, and the gate had no way to know the
 // other five existed. Where more than one unit run is in flight the machine is divided between them
 // instead, by `unit-worker-share.ts`, which is the same answer `test-unit-guard.ts` gives the pre-push
@@ -251,11 +276,11 @@ function resolve_concurrency(
 // oversubscription for an unmeasured starvation is not an improvement anyone can defend. What *is*
 // measured is the unit half — six concurrent suites went from ten timeouts to none at this share.
 //
-// **joshuafolkken/kit#1547 narrowed `resolve_concurrency` and deliberately left this number alone.**
-// A narrowed gate no longer runs its three siblings *beside* its unit step, so the paragraph above
-// now over-states what the share is competing with — which is an argument for widening it, and
-// widening it is exactly the unmeasured move that paragraph refuses. The number #1515 measured stays
-// until something measures a better one on this machine.
+// **`resolve_concurrency` narrows the gate and leaves this number alone.** A narrowed gate no longer
+// runs its three siblings *beside* its unit step, so the paragraph above over-states what the share
+// is competing with — which is an argument for widening it, and widening it is exactly the
+// unmeasured move that paragraph refuses. The measured number stays until something measures a
+// better one on this machine.
 //
 // **The count is a parameter rather than a read.** This module stays a pure function of its inputs, so
 // its own assertions are about arithmetic and not about what happened to be running while they ran;
@@ -277,7 +302,7 @@ function solo_unit_weight(available_cores: number): number {
 	return Math.max(0, available_cores - RESERVED_CORES)
 }
 
-// The cores a check reserves from the machine-wide budget while it runs (joshuafolkken/kit#2351). The
+// The cores a check reserves from the machine-wide budget while it runs. The
 // static checks declare their measured reservation; the unit suite declares the pool it will open,
 // which `unit_worker_cap` has already sized against the runs in flight. **This is the same table, read
 // once**: no second set of weights is introduced, so a change to the measured reservation moves the
@@ -298,7 +323,7 @@ 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
+// The memory a check holds: 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
@@ -306,7 +331,7 @@ function check_memory(check: GateCheck, plan: GatePlan, available_cores: number)
 	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
+// The cores a unit run started directly reserves: 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
 // once the ledger is empty, so a one-file `josh test:related` would wait out every other lane's gate
@@ -329,6 +354,16 @@ function direct_unit_memory(): number {
 	return unit_memory(direct_unit_weight())
 }
 
+function unit_cap_for(
+	checks: ReadonlyArray<GateCheck>,
+	available_cores: number,
+	concurrent_runs: number,
+): number | undefined {
+	if (!has_unit_check(checks)) return undefined
+
+	return resolve_unit_worker_cap(available_cores, concurrent_runs)
+}
+
 // `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
@@ -351,29 +386,28 @@ function resolve_gate_plan(
 	available_cores: number = availableParallelism(),
 	concurrent_runs: number = unit_worker_share.SOLO_RUNS,
 	is_unit_included = true,
+	is_kit_repository = true,
 ): GatePlan {
-	const checks = select_gate_checks(is_unit_included)
+	const checks = select_gate_checks(is_unit_included, is_kit_repository)
 
 	return {
 		checks,
 		concurrency: resolve_concurrency(available_cores, concurrent_runs, checks),
-		unit_worker_cap: is_unit_included
-			? resolve_unit_worker_cap(available_cores, concurrent_runs)
-			: undefined,
+		unit_worker_cap: unit_cap_for(checks, available_cores, concurrent_runs),
 	}
 }
 
 // Printed once per run, so a gate that was slow on someone else's machine can be read without
 // re-deriving the plan from their core count.
 //
-// **The two fragments come from `josh-verdict.ts` since joshuafolkken/kit#1379.** `josh time` matches
+// **The two fragments come from `josh-verdict.ts`.** `josh time` matches
 // this line to tell where a gate run's output begins — it is the one line the gate prints before any
 // check body exists — so the printer and the detector build it from the same strings, exactly as they
 // already do for the verdict.
 // **The machine is described as shared only when it is.** A solo gate prints exactly the line it
 // always printed — which is what keeps `josh time`'s detector, and every reader used to the old
 // output, unaffected — while a narrowed one says why it is narrow, so a lane owner reading a slow
-// gate is not left deriving the reason from a worker count that looks wrong (joshuafolkken/kit#1515).
+// gate is not left deriving the reason from a worker count that looks wrong.
 function format_machine(available_cores: number, concurrent_runs: number): string {
 	const cores = `${String(available_cores)} cores`
 
@@ -409,6 +443,7 @@ const gate_plan = {
 	GATE_CHECKS,
 	LINT_LABEL,
 	MEASURED_CORES,
+	METRICS_LABEL,
 	RESERVED_CORES,
 	STATIC_CHECKS,
 	TYPE_CHECK_LABEL,

package/scripts/gate/gate-report.ts

@@ -7,7 +7,7 @@ import { gate_log } from './gate-log'
 import { gate_plan } from './gate-plan'
 
 // The gate's console reporting, split out of `verification-gate.ts` so that file stays under its line
-// ceiling while it grows the scoped pre-check and the failure summary (joshuafolkken/kit#2296). Nothing
+// ceiling while it grows the scoped pre-check and the failure summary. Nothing
 // about what is printed changes in the move: the four blocks, the log notice and the verdict come out
 // exactly as before, with one addition — the per-failure action lines below.
 
@@ -25,7 +25,7 @@ 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).
+	// Set when the check started past the machine-wide budget at the wait cap.
 	budget_note?: string | undefined
 }
 
@@ -36,8 +36,7 @@ function is_gate_step_failed(result: GateStepResult): boolean {
 // A passing check's output is not read. What a green gate has to say is "all four passed", and
 // `print_gate_summary` already says it in one line — while the four bodies, vitest's per-file
 // listing among them, run to tens of kilobytes that then sit in the conversation and are re-read on
-// every later turn. The gate runs more than once per Issue, so the cost is per run, not per Issue
-// (joshuafolkken/kit#967).
+// every later turn. The gate runs more than once per Issue, so the cost is per run, not per Issue.
 //
 // A failing check keeps its whole output: that is the one time the body is the answer. So does a
 // check that **passed without running** — `test-unit-guard` exits 0 with a notice when vitest is
@@ -61,8 +60,8 @@ function has_warnings(result: GateStepResult): boolean {
 	return WARNING_MARKERS.some((marker) => result.output.includes(marker))
 }
 
-// The withholding path's counterpart to `has_warnings`, and deliberately narrower than it
-// (joshuafolkken/kit#2318). `has_warnings` is read by `should_print_body`, where a false positive
+// The withholding path's counterpart to `has_warnings`, and deliberately narrower than it.
+// `has_warnings` is read by `should_print_body`, where a false positive
 // costs one printed body — the loose match above is right there. `record_green_gate` reads *this*
 // one, where a false positive is not one printed line but the whole green record withheld, which
 // turns a green gate's `run:review --join` red. So the record is withheld only for a warning from a
@@ -70,7 +69,7 @@ function has_warnings(result: GateStepResult): boolean {
 // from another tool that happens to contain the word — a Vite config deprecation on `test:unit` was
 // the line that stopped a green gate's commit chain.
 //
-// **The safe-chain shim's banner is not the checker's either** (joshuafolkken/kit#2447). Where
+// **The safe-chain shim's banner is not the checker's either**. Where
 // `setup-ci` installed the shims but the binary cannot be reached, every `pnpm` a check spawns prints
 // "Warning: safe-chain is not available …" into that check's output, so a green lint withheld the
 // record on every CI run. The banner's lines are dropped before the match; a real warning on any
@@ -97,7 +96,7 @@ function should_print_body(result: GateStepResult, is_verbose: boolean): boolean
 
 // Seconds to one decimal, which is the resolution the answer is read at: the question a gate's
 // timing answers is "which of the four is the long pole", and no check is ever separated from
-// another by less than a tenth of a second (joshuafolkken/kit#1248).
+// another by less than a tenth of a second.
 const MS_PER_SECOND = 1000
 const SECONDS_DECIMALS = 1
 
@@ -109,8 +108,8 @@ function format_seconds(elapsed_ms: number): string {
 // naming the one command to re-run while fixing (`docs/josh-commands.md` → `josh gate`), and a
 // number spliced in front of it would push that name out of the place a reader scans for it.
 //
-// Built rather than inlined because the log file names each section with the same string
-// (joshuafolkken/kit#1227): a header written twice is a header the two copies can disagree about,
+// Built rather than inlined because the log file names each section with the same string:
+// a header written twice is a header the two copies can disagree about,
 // and the log exists precisely to be read when the console's copy has been elided.
 function gate_step_header(result: GateStepResult): string {
 	const icon = is_gate_step_failed(result) ? FAIL_ICON : PASS_ICON
@@ -127,7 +126,7 @@ function print_gate_step(result: GateStepResult, is_verbose: boolean): void {
 }
 
 // **One line per failed check, naming the command that reproduces it, printed at the tail just above
-// the verdict** (joshuafolkken/kit#2296). A red gate used to report every failing check only in its
+// the verdict**. A red gate used to report every failing check only in its
 // bodies, which is where truncation lands: the run picked one failure at a time across separate gate
 // runs because it could not read the rest. The verdict names *which* checks failed; this names *what
 // to run* for each, and it sits in the same tail window the verdict and the log notice already
@@ -143,8 +142,8 @@ 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,
+// **A check that started past the core budget is said in the summary, not only in the log**.
+// 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 = '⚠'
@@ -163,7 +162,7 @@ function format_budget_notes(results: ReadonlyArray<GateStepResult>): string {
 // 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).
+// verdict line, which stays last for the reason `josh-verdict.ts` gives.
 function print_gate_summary(
 	results: ReadonlyArray<GateStepResult>,
 	report: GateReport,
@@ -191,7 +190,7 @@ interface GateReport {
 
 // Everything a finished run says, in the order a reader meets it: the four blocks, then the log the
 // blocks may have been elided out of, then the failure actions and the verdict. **Every check's whole
-// output goes into the log, the ones the console dropped included** (joshuafolkken/kit#967).
+// output goes into the log, the ones the console dropped included**.
 function report_gate_steps(
 	results: ReadonlyArray<GateStepResult>,
 	report: GateReport,