@joshuafolkken/kit 1.1229.0 → 1.1370.0

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,63 +28,97 @@ 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.
 	// The unit suite reserves nothing: it sizes its own pool from the machine, so it is capped
 	// instead of reserved, and counting it here would reserve cores against itself.
 	reserved_cores: number
+	// The memory this check holds while it runs, `core_budget.MEMORY_MB`'s measured peak; none declared is
+	// none waited for. 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
 // full length of the unit suite, to cover a burst that ends before lint does. Nothing has measured
 // that trade, so the measured shape stays.
 const STATIC_CHECKS: ReadonlyArray<GateCheck> = [
-	{ label: LINT_LABEL, target: 'lint', reserved_cores: core_budget.CORE_WEIGHTS.lint },
+	{
+		label: LINT_LABEL,
+		target: 'lint',
+		reserved_cores: core_budget.CORE_WEIGHTS.lint,
+		memory_mb: core_budget.MEMORY_MB.lint,
+	},
 	{
 		label: TYPE_CHECK_LABEL,
 		target: 'check',
 		reserved_cores: core_budget.CORE_WEIGHTS.type_check,
+		memory_mb: core_budget.MEMORY_MB.type_check,
+	},
+	{
+		label: 'cspell',
+		target: 'cspell:dot',
+		reserved_cores: core_budget.CORE_WEIGHTS.spell_check,
+		memory_mb: core_budget.MEMORY_MB.spell_check,
 	},
-	{ label: 'cspell', target: 'cspell:dot', reserved_cores: core_budget.CORE_WEIGHTS.spell_check },
 	{ label: BEHAVIOR_LABEL, target: BEHAVIOR_LABEL, reserved_cores: 0 },
-	// **The unused-member check reserves no core** (joshuafolkken/kit#2987): it builds one TypeScript
+	// **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
@@ -102,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"
@@ -155,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
@@ -183,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
@@ -221,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
@@ -237,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;
@@ -263,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
@@ -280,7 +319,19 @@ function check_weight(check: GateCheck, plan: GatePlan, available_cores: number)
 	return plan.unit_worker_cap ?? solo_unit_weight(available_cores)
 }
 
-// The cores a unit run started directly reserves (joshuafolkken/kit#3345): the share it will pass to
+function unit_memory(workers: number): number {
+	return workers * core_budget.MEMORY_MB.unit_worker
+}
+
+// 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
+
+	return unit_memory(check_weight(check, plan, available_cores))
+}
+
+// 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
@@ -298,6 +349,21 @@ function direct_unit_weight(
 	return Math.max(unit_worker_share.MIN_WORKERS, weight)
 }
 
+// What a unit run started directly holds: one worker's peak for each worker `direct_unit_weight` gives it.
+function direct_unit_memory(): number {
+	return unit_memory(direct_unit_weight())
+}
+
+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
@@ -320,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`
 
@@ -378,12 +443,15 @@ const gate_plan = {
 	GATE_CHECKS,
 	LINT_LABEL,
 	MEASURED_CORES,
+	METRICS_LABEL,
 	RESERVED_CORES,
 	STATIC_CHECKS,
 	TYPE_CHECK_LABEL,
 	UNIT_LABEL,
 	WARNING_CHECKER_LABELS,
+	check_memory,
 	check_weight,
+	direct_unit_memory,
 	direct_unit_weight,
 	format_gate_plan,
 	format_machine,

package/scripts/gate/gate-report.ts

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

package/scripts/gate/gate-skip.ts

@@ -2,13 +2,12 @@ import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { review_brief } from '#scripts/review/review-brief'
 import { review_stamps } from '#scripts/review/review-stamps'
 
-// Whether `josh gate` already has the answer it is about to spend 47–50 seconds computing again
-// (joshuafolkken/kit#1328).
+// Whether `josh gate` already has the answer it is about to spend 47–50 seconds computing again.
 //
-// The record has existed since joshuafolkken/kit#1241: `record_green_gate` writes the digest of every
-// changed file the four checks were green on, and `josh review:brief` reads it back to print
-// `Already verified`. The gate itself never read it, so a second run over an unedited tree started
-// four processes to reach a conclusion already on disk. **This is reuse of a result, not a check
+// `record_green_gate` writes the digest of every changed file the four checks were green on, and
+// `josh review:brief` reads it back to print `Already verified`. The gate reads it too, so a second
+// run over an unedited tree does not start four processes to reach a conclusion already on disk.
+// **This is reuse of a result, not a check
 // dropped**: the bytes the skip answers for are the bytes the record was written from, compared one
 // by one.
 //
@@ -17,8 +16,7 @@ import { review_stamps } from '#scripts/review/review-stamps'
 // differently from the brief printed beside it would be two commands disagreeing about the same tree.
 //
 // **A file map does not describe a tree on its own, because it is a diff.** It lists what differs
-// from the commit the branch was cut from — its merge base with the default branch since
-// joshuafolkken/kit#1527 — so everything the record says stays true while that base moves underneath
+// from the commit the branch was cut from — its merge base with the default branch — so everything the record says stays true while that base moves underneath
 // it. Two shapes of that, one obvious and one not:
 //
 // - Straight after `git switch main && git pull` the map is **empty**, and an empty map compares
@@ -29,8 +27,8 @@ import { review_stamps } from '#scripts/review/review-stamps'
 //   every other file has been replaced by code no check has read. The rebase moves `HEAD`, so it
 //   moves the merge base with it, and the base check still catches this.
 //
-// **What no longer refuses a reuse is another lane merging into the shared default branch**
-// (joshuafolkken/kit#1527). In a linked work tree the default branch's ref is shared, but the merge
+// **What no longer refuses a reuse is another lane merging into the shared default branch**.
+// In a linked work tree the default branch's ref is shared, but the merge
 // base is a commit: an advance this branch is an ancestor of does not move it, and nothing this
 // checkout's four checks read has changed — so refusing there would have discarded a record that
 // still describes the tree exactly.
@@ -40,7 +38,7 @@ import { review_stamps } from '#scripts/review/review-stamps'
 // worth the argument: a tree with no changed file is not where a run spends its gate time.
 //
 // Two refusals need no code here. A gate that went red writes no record at all, so the re-verification
-// after a fix finds nothing to reuse; and joshuafolkken/kit#1261's join before the commit follows a
+// after a fix finds nothing to reuse; and the join before the commit follows a
 // `josh bump`, which edits `package.json` into the map.
 //
 // **What is reused is a silent green run.** `record_green_gate` withholds the record from a run that
@@ -61,7 +59,7 @@ const FORCE_FLAG = '--force'
 // A `base` that could not be read is `undefined`, and an older record carries none: both compare
 // unequal to anything, so the gate runs its checks. No base means no reuse, never reuse without one.
 //
-// **A refusal carries its reason** (joshuafolkken/kit#3307): a pre-push hook that fell back to the
+// **A refusal carries its reason**: a pre-push hook that fell back to the
 // whole unit suite said nothing about why, so a merge base moved by ship's main sync and a lock file
 // rewritten by the hook's own install each cost minutes before anyone could tell them apart.
 type GateReuse = { stamp: FileMapStamp } | { miss: string }
@@ -103,7 +101,7 @@ function reusable_green_gate(
 // goes on to a commit on the strength of it. So the line says what passed, on which tree and when,
 // and names the flag or the variable that runs the checks anyway.
 //
-// **One sentence, every reader of the record** (joshuafolkken/kit#1381). The gate says it, the
+// **One sentence, every reader of the record**. The gate says it, the
 // pre-push hook says it and the pre-commit hook says it, and three copies of a claim this load-bearing
 // would not have stayed the same sentence — the clone `CLAUDE.md` prohibits. What differs between them
 // is four fragments and nothing else, so those are the parameters and the shape is not.

package/scripts/gate/gate-steps.ts

@@ -13,6 +13,10 @@ function unit_worker_args(check: GateCheck, plan: GatePlan): ReadonlyArray<strin
 	return [`${UNIT_WORKER_FLAG}=${String(plan.unit_worker_cap)}`]
 }
 
+function check_args(check: GateCheck, plan: GatePlan): ReadonlyArray<string> {
+	return [...(check.args ?? []), ...unit_worker_args(check, plan)]
+}
+
 // Resolve the type checker per project and run every static check from its package root.
 async function build_gate_step(
 	check: GateCheck,
@@ -26,7 +30,7 @@ async function build_gate_step(
 	if (check.label !== TYPE_CHECK_LABEL) {
 		return {
 			label: check.label,
-			command_args: [JOSH, check.target, ...unit_worker_args(check, plan)],
+			command_args: [JOSH, check.target, ...check_args(check, plan)],
 			cwd,
 		}
 	}

package/scripts/gate/gate-tree.ts

@@ -2,12 +2,11 @@ import { change_base } from '#scripts/git/change-base'
 import { review_tree } from '#scripts/review/review-tree'
 
 // The two readings a green-gate record is written from and compared against: the digest of every
-// changed file, and the commit that map is a diff against (joshuafolkken/kit#1241,
-// joshuafolkken/kit#1328).
+// changed file, and the commit that map is a diff against.
 //
 // They live here rather than inside `verification-gate.ts` because there are now two readers — the
 // gate, which reuses a green record instead of re-running its four checks, and the pre-push hook,
-// which reuses the same record instead of re-running the unit suite (joshuafolkken/kit#1334). A
+// which reuses the same record instead of re-running the unit suite. A
 // second copy of the pair would be the clone `CLAUDE.md` prohibits, and it would not have stayed
 // identical: what these functions really encode is which failure direction is safe, and a copy is
 // where that decision gets made twice.
@@ -30,7 +29,7 @@ async function read_changed_files(): Promise<Record<string, string>> {
 	}
 }
 
-// The resolver lives in `git/change-base.ts` since joshuafolkken/kit#1537, because the review brief
+// The resolver lives in `git/change-base.ts`, because the review brief
 // needs exactly this reading and a second copy of it is the clone `CLAUDE.md` prohibits.
 async function read_base(): Promise<string | undefined> {
 	return await change_base.resolved()