@joshuafolkken/kit 1.1471.0 → 1.1514.0

package/scripts/gate/verification-gate.ts

@@ -1,19 +1,19 @@
 #!/usr/bin/env tsx
-import { availableParallelism } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import type { FileMapStamp } from '#scripts/josh/file-map-stamp'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { lane_ledger } from '#scripts/lane/lane-ledger'
-import { bounded_pool } from '#scripts/lib/bounded-pool'
-import { buffered_process, FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
+import { FAIL_EXIT_CODE } from '#scripts/lib/buffered-process'
 import { review_stamps } from '#scripts/review/review-stamps'
 import { review_tree } from '#scripts/review/review-tree'
 import { unit_worker_share } from '#scripts/test/unit-worker-share'
-import { core_budget } from './core-budget'
+import { check_reuse, type CheckRecords } from './check-reuse'
+import { free_cores } from './free-cores'
 import { gate_ledger, type GateLedgerStart } from './gate-ledger'
 import { gate_plan, type GatePlan } from './gate-plan'
-import { gate_report, type GateStep, type GateStepResult } from './gate-report'
+import { gate_report, type GateStepResult } from './gate-report'
+import { gate_run_steps, type ReusedChecks } from './gate-run-steps'
 import { gate_skip } from './gate-skip'
 import { build_gate_step, build_gate_steps, UNIT_WORKER_FLAG } from './gate-steps'
 import { gate_tree, type GateTree } from './gate-tree'
@@ -35,25 +35,6 @@ const { GATE_CHECKS } = gate_plan
 
 const GATE_TARGETS: ReadonlyArray<string> = GATE_CHECKS.map((check) => check.target)
 
-async function run_gate_step(step: GateStep): Promise<GateStepResult> {
-	if (step.skip_reason !== undefined) {
-		return {
-			label: step.label,
-			command: step.command_args.join(' '),
-			output: project_checks.skip_notice('check', step.skip_reason),
-			exit_code: 0,
-			elapsed_ms: 0,
-		}
-	}
-
-	const result = await buffered_process.run_buffered_process(
-		step.command_args,
-		step.cwd === undefined ? {} : { cwd: step.cwd },
-	)
-
-	return { label: step.label, command: step.command_args.join(' '), ...result }
-}
-
 // The record `josh review:brief` reads, written only on a fully green run and only with the tree it
 // was green on. `/code-review` runs in a forked process that reads none of
 // this repository's documents, so "the unit tests already passed" reaches it only if the invocation
@@ -65,7 +46,7 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 // visible on the console, and a record erasing it would have the brief tell a review agent not to
 // re-run tests that never ran. A skip of a tool the project does not use (`NOT_USED_MARKER` — eslint
 // with no ESLint configuration) is not one: nothing went unverified, so it withholds nothing
-// (`gate_report.is_unverified_skip`). A step that passed **with a checker's warnings** is withheld for the
+// (`gate_report.has_nothing_to_say`). A step that passed **with a checker's warnings** is withheld for the
 // same reason one place further on: since the record is reused instead of the checks being re-run, a
 // warning printed once would never be printed again on that tree, and hiding an eslint or
 // svelte-check finding is the same failure as hiding a skip. It is `has_checker_warning`, not
@@ -81,17 +62,13 @@ async function run_gate_step(step: GateStep): Promise<GateStepResult> {
 //
 // The destination is a parameter so a test can exercise the record without overwriting the one a
 // real run may be relying on — `josh gate` and `josh review:brief` share one path by design.
-function has_nothing_to_say(result: GateStepResult): boolean {
-	return !gate_report.is_unverified_skip(result) && !gate_report.has_checker_warning(result)
-}
-
 async function record_green_gate(
 	results: ReadonlyArray<GateStepResult>,
 	before: Record<string, string>,
 	target?: string,
 	base?: string,
 ): Promise<void> {
-	if (results.some((result) => !has_nothing_to_say(result))) return
+	if (results.some((result) => !gate_report.has_nothing_to_say(result))) return
 
 	try {
 		const after = await review_tree.read_changed_tree()
@@ -153,94 +130,6 @@ async function with_gate_marker<T>(
 	}
 }
 
-// This gate's share of the machine, resolved once at the gate's entry and carried down as one value.
-// `available_cores` is the budget every check reserves against; `is_reserved`
-// is false for a gate nested inside another gate's unit suite — this repository's own gate tests — so
-// the outer gate reserves and every gate beneath it does not. Captured before this gate sets
-// `JOSH_UNIT_RUN_MARKED`, which is why it is read at entry rather than re-derived here.
-interface BudgetContext {
-	available_cores: number
-	is_reserved: boolean
-}
-
-function default_budget(): BudgetContext {
-	return {
-		available_cores: availableParallelism(),
-		is_reserved: !unit_worker_share.is_nested_run() && !core_budget.is_held(),
-	}
-}
-
-// A gate step paired with the cores it reserves from the machine-wide budget while it runs.
-// The weight travels with the step so `run_gate_steps` never has to re-pair a
-// step with its check by index.
-interface ReservedStep {
-	step: GateStep
-	weight: number
-	memory_mb: number
-}
-
-async function build_reserved_steps(
-	start_directory: string,
-	plan: GatePlan,
-	available_cores: number,
-): Promise<ReadonlyArray<ReservedStep>> {
-	return await Promise.all(
-		plan.checks.map(async (check) => ({
-			step: await build_gate_step(check, start_directory, plan),
-			weight: gate_plan.check_weight(check, plan, available_cores),
-			memory_mb: gate_plan.check_memory(check, plan, available_cores),
-		})),
-	)
-}
-
-// **A nested gate takes no reservation, and the budget is what makes that necessary rather than
-// merely tidy**. The unit step spawns the suite, which runs this repository's
-// own gate tests; each of those is a gate inside the outer gate's unit reservation, and a place it
-// claimed would wait for cores the outer gate cannot free until the suite — this test included —
-// finishes.
-async function run_reserved_step(
-	reserved: ReservedStep,
-	budget: BudgetContext,
-): Promise<GateStepResult> {
-	if (!budget.is_reserved) return await run_gate_step(reserved.step)
-
-	return await core_budget.with_core_reservation(
-		reserved.weight,
-		async (admission) => ({
-			...(await run_gate_step(reserved.step)),
-			budget_note: core_budget.describe_overflow(admission),
-		}),
-		{ budget: budget.available_cores, memory_mb: reserved.memory_mb },
-	)
-}
-
-// `bounded_pool` rather than a bare `Promise.all`, so the plan's `concurrency` is what decides how
-// many run at once. **The all-failures-in-one-pass property survives the
-// change** because no check ever rejects: `buffered_process` reports a non-zero exit as a value, so
-// the pool's first-failure abort — written for callers that spawn real Claude sessions — never
-// fires here and every queued check still runs. Results come back in input order however they
-// finished, which is what keeps the printed sections in declaration order. Each step first claims its
-// place in the machine-wide budget and waits while the budget is full.
-async function run_gate_steps(
-	plan: GatePlan,
-	budget: BudgetContext = default_budget(),
-): Promise<ReadonlyArray<GateStepResult>> {
-	const reserved = await build_reserved_steps(process.cwd(), plan, budget.available_cores)
-
-	// **The checks run under the held mark, so a check's own dispatch claims nothing**.
-	// Each check is a `pnpm josh <target>` child, and a target that declares
-	// a weight would otherwise claim a second place for the cores reserved for it here. A nested gate
-	// sets the mark too, since its checks are covered by the outer gate's reservation.
-	return await core_budget.with_held_mark(
-		async () =>
-			await bounded_pool.bounded_map(
-				reserved,
-				plan.concurrency,
-				async (entry) => await run_reserved_step(entry, budget),
-			),
-	)
-}
-
 // **Both markers are claims about the unit suite, so a gate that is not running it makes neither**.
 // The in-flight marker tells the next `josh review:brief` that a gate is
 // covering this tree right now, which is what stops a review agent re-running the suite; the
@@ -276,15 +165,21 @@ async function run_marked_gate<T>(
 // The concurrent-run count is read here rather than inside `gate-plan.ts` for the reason the core
 // count already is: that module stays a pure function of its inputs, and the machine is asked once and
 // handed to both calls. Counted *before* the unit step writes its own marker, so `+ 1` is this gate.
-function announce_gate_plan(is_unit_included: boolean, available_cores: number): GatePlan {
+// `free` bounds the unit cap the run count produced (`gate_plan.bound_by_free`).
+function announce_gate_plan(
+	is_unit_included: boolean,
+	available_cores: number,
+	free: number | undefined,
+): GatePlan {
 	const concurrent_runs = unit_worker_share.live_run_count() + unit_worker_share.SOLO_RUNS
 	const is_kit_repository = project_checks.is_kit_repository(process.cwd())
-	const plan = gate_plan.resolve_gate_plan(
+	const resolved = gate_plan.resolve_gate_plan(
 		available_cores,
 		concurrent_runs,
 		is_unit_included,
 		is_kit_repository,
 	)
+	const plan = gate_plan.bound_by_free(resolved, available_cores, free)
 
 	process.stdout.write(`${gate_plan.format_gate_plan(plan, available_cores, concurrent_runs)}\n`)
 
@@ -319,6 +214,35 @@ interface GateOptions {
 	// The lane ledger a finished gate's duration is appended to. Only the CLI
 	// entry resolves it, so a suite driving the gate never writes a measurement of checks that never ran.
 	ledger_path?: string | undefined
+	// Where each check's own green record lives (`check-reuse.ts`). Only the CLI entry resolves it, for
+	// the ledger's reason: a suite whose checks never ran must not record them green on the live tree.
+	check_records?: CheckRecords | undefined
+	// The cores free of load from outside the core budget's ledger (`free-cores.ts`). Only the CLI entry
+	// resolves it, for the ledger's reason: a suite driving the gate never reads the machine, so its plan
+	// does not depend on what else happened to be running.
+	read_free_cores?: ((available_cores: number) => Promise<number | undefined>) | undefined
+}
+
+// **Per-check records belong to the full local gate alone**: CI's `--no-unit` gate is the safety net
+// under the local reuse and stays as it was, so it neither reads nor writes one.
+function check_records_of(plan: GatePlan, options: GateOptions): CheckRecords | undefined {
+	return gate_plan.has_unit_check(plan.checks) ? options.check_records : undefined
+}
+
+async function checks_to_reuse(
+	plan: GatePlan,
+	tree: GateTree,
+	options: GateOptions,
+): Promise<ReusedChecks> {
+	const records = check_records_of(plan, options)
+
+	if (records === undefined || options.is_forced === true) return new Map()
+
+	return await check_reuse.reusable_checks(
+		plan.checks.map((check) => check.label),
+		tree,
+		records,
+	)
 }
 
 // **The gate refuses to start when the scoped pair has not been green on this tree**
@@ -374,6 +298,10 @@ async function settle_gate(
 
 	await gate_ledger.record(options.ledger, results, { elapsed_ms, is_passed })
 
+	const records = check_records_of(plan, options)
+
+	if (records !== undefined) await check_reuse.record_green_checks(results, tree, records)
+
 	if (!is_passed) return FAIL_EXIT_CODE
 
 	await record_whole_gate(plan, results, tree, options)
@@ -396,8 +324,11 @@ async function run_checked_gate(
 	const ledger = await gate_ledger.start(options.ledger_path)
 	// Resolved at the gate's entry, before this gate sets `JOSH_UNIT_RUN_MARKED`, so a gate nested in the
 	// unit suite reads the flag as set and reserves nothing.
-	const budget = default_budget()
-	const plan = announce_gate_plan(is_unit_included, budget.available_cores)
+	const budget = gate_run_steps.default_budget()
+	// Read before the count for the ledger's reason: the reading waits out a sample window.
+	const free = await options.read_free_cores?.(budget.available_cores)
+	const plan = announce_gate_plan(is_unit_included, budget.available_cores, free)
+	const reused = await checks_to_reuse(plan, tree, options)
 
 	// **The gate holds the unit-run marker for its whole run, not just its unit step.** The step that
 	// would write it is a subprocess started a second or so after the count above, so two lanes launched
@@ -406,7 +337,7 @@ async function run_checked_gate(
 	// the next lane asks; the guard inside the spawned `josh test:unit` sees the handoff and adds no
 	// second marker for the same run.
 	async function run_and_settle(): Promise<number> {
-		const results = await run_gate_steps(plan, budget)
+		const results = await gate_run_steps.run_gate_steps(plan, budget, reused)
 
 		return await settle_gate(plan, results, tree, { ...options, started_at, ledger })
 	}
@@ -506,6 +437,8 @@ async function run_gate_command(
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await run_gate_command(process.argv.slice(FIRST_ARGUMENT_INDEX), {
 		ledger_path: await lane_ledger.target(),
+		check_records: check_reuse.DEFAULT_RECORDS,
+		read_free_cores: async (available_cores) => await free_cores.read({ available_cores }),
 	})
 }
 
@@ -519,11 +452,11 @@ const verification_gate = {
 	clear_gate_running,
 	mark_gate_running,
 	record_green_gate,
-	run_gate_steps,
+	run_gate_steps: gate_run_steps.run_gate_steps,
 	scoped_precheck_refusal,
 	with_gate_marker,
 	run_gate_command,
-	run_gate_step,
+	run_gate_step: gate_run_steps.run_gate_step,
 	run_verification_gate,
 }
 

package/scripts/gh/git-gh-issue-rest.ts

@@ -71,6 +71,7 @@ const REST_FIELD_NAMES = new Map<string, string>([
 	['url', 'html_url'],
 	['createdAt', 'created_at'],
 	['closedAt', 'closed_at'],
+	['stateReason', 'state_reason'],
 	['updatedAt', 'updated_at'],
 ])
 

package/scripts/gh/git-gh-issue-write.ts

@@ -36,6 +36,7 @@ const LABEL_NAMES_FILTER = '.[].name'
 const LABELS_SEGMENT = '/labels'
 const COMMENTS_SEGMENT = '/comments'
 const CLOSED_STATE = 'closed'
+const NOT_PLANNED_REASON = 'not_planned'
 const COLOR_HASH = '#'
 const UNPROCESSABLE_STATUS = 422
 const ALREADY_EXISTS_CODE = 'already_exists'
@@ -99,17 +100,37 @@ async function issue_try_comment(issue_number: string, body: string): Promise<bo
 // It is a required parameter that may be `undefined` rather than an optional one: skipping the
 // announcement is a decision the caller makes from what it read, never something a call site can
 // fall into by leaving an argument off.
-async function issue_close(issue_number: string, comment: string | undefined): Promise<boolean> {
+async function close_with(
+	issue_number: string,
+	comment: string | undefined,
+	state: Readonly<Record<string, string>>,
+): Promise<boolean> {
 	return await did_write_succeed(async () => {
 		if (comment !== undefined) await issue_comment(issue_number, comment)
 		await git_gh_exec.exec_gh_api({
 			path: git_gh_api_path.issue_api_path(issue_number),
 			method: PATCH_METHOD,
-			body: JSON.stringify({ state: CLOSED_STATE }),
+			body: JSON.stringify(state),
 		})
 	})
 }
 
+async function issue_close(issue_number: string, comment: string | undefined): Promise<boolean> {
+	return await close_with(issue_number, comment, { state: CLOSED_STATE })
+}
+
+// The same close as "not planned" — the reason `issue-merged.ts` reads as no merge, so a closed issue
+// that was withdrawn is never taken for one whose work landed.
+async function issue_close_not_planned(
+	issue_number: string,
+	comment: string | undefined,
+): Promise<boolean> {
+	return await close_with(issue_number, comment, {
+		state: CLOSED_STATE,
+		state_reason: NOT_PLANNED_REASON,
+	})
+}
+
 // REST answers 422 `{"resource":"Label","code":"invalid","field":"color"}` for a color carrying a
 // leading `#`. The one caller passes the hash form (`EPIC_LABEL_COLOR`), so dropping it here is what
 // keeps that call site unchanged.
@@ -336,6 +357,7 @@ const git_gh_issue_write = {
 	issue_comment,
 	issue_try_comment,
 	issue_close,
+	issue_close_not_planned,
 	label_ensure,
 	issue_create_request,
 	issue_create_with_label,

package/scripts/gh/git-pr.ts

@@ -5,6 +5,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { session_cite } from '#scripts/issue/session-cite'
 import { animation_helpers, type AnimationOptions } from '#scripts/lib/animation-helpers'
 import { json_value } from '#scripts/lib/json-value'
+import { acceptance_map } from '#scripts/review/acceptance-map'
 import { git_gh_command } from './git-gh-command'
 import { git_pr_error } from './git-pr-error'
 import { git_pr_messages } from './git-pr-messages'
@@ -172,6 +173,17 @@ function build_body(issue_info: IssueInfo, extra_body?: string): string {
 	return `${closes}\n\n${extra_body}`
 }
 
+// A body without the acceptance-criteria table gets one pending row per criterion, so the author fills
+// in rows that already carry their identifiers — `josh followup` refuses the merge until they do.
+async function body_with_map(issue_info: IssueInfo, extra_body?: string): Promise<string> {
+	const body = build_body(issue_info, extra_body)
+
+	if (acceptance_map.has_map(body)) return body
+	const map = acceptance_map.skeleton(await git_gh_command.issue_get_body(issue_info.number))
+
+	return map === undefined ? body : `${body}\n\n${map}`
+}
+
 async function existing_pr_label(branch_name: string): Promise<ReleaseClassification | undefined> {
 	if (
 		!(await git_gh_command.pr_exists(branch_name)) ||
@@ -190,7 +202,7 @@ async function create_for_issue(
 ): Promise<void> {
 	await create(
 		build_title(issue_info),
-		build_body(issue_info, extra_body),
+		await body_with_map(issue_info, extra_body),
 		issue_info.branch_name,
 		{
 			label,

package/scripts/git/main-merge-regenerate.ts

@@ -0,0 +1,78 @@
+import { SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
+import { git_command } from './git-command'
+import { git_spawn } from './git-spawn'
+
+// A merge of the default branch that stops only on generated files is finished here rather than by a
+// resumed session: each such file is the output of a command, so running that command on the merged
+// tree writes the one correct resolution, with no conflict marker for anyone to read.
+//
+// **This table is the single list of what is resolved that way** — a file a person writes never
+// belongs in it, because regenerating would discard that person's side of the merge. A conflict on any
+// path not listed here still stops as `conflict`. A file belongs here only once its committed content
+// is exactly what its command writes: `scripts/test/pure-files.ts` is not, so regenerating it would
+// rewrite far more than the conflict.
+
+interface RegeneratedFile {
+	path: string
+	command: ReadonlyArray<string>
+}
+
+const REGENERATED_FILES: ReadonlyArray<RegeneratedFile> = [
+	{
+		path: 'docs/josh-command-catalog.md',
+		command: ['pnpm', 'exec', 'tsx', 'scripts/document/generate-catalog.ts'],
+	},
+]
+
+function regenerated_for(
+	files: ReadonlyArray<string>,
+	table: ReadonlyArray<RegeneratedFile>,
+): ReadonlyArray<RegeneratedFile> {
+	const entries = files.map((file) => table.find((entry) => entry.path === file))
+
+	return entries.every((entry) => entry !== undefined) ? entries : []
+}
+
+// Each generator writes only its own file, so they run side by side.
+async function regenerate(entries: ReadonlyArray<RegeneratedFile>, cwd: string): Promise<void> {
+	await Promise.all(
+		entries.map(async (entry) => {
+			const [binary = '', ...command_arguments] = entry.command
+
+			await execa(binary, command_arguments, { cwd })
+		}),
+	)
+}
+
+// `--no-edit` keeps the message the merge was started with — the one carrying the issue number the
+// `commit-msg` hook asks for.
+async function conclude_merge(entries: ReadonlyArray<RegeneratedFile>): Promise<void> {
+	await git_spawn.with_output('add', ['--', ...entries.map((entry) => entry.path)])
+	await git_spawn.with_output('commit', ['--no-edit'], { timeout_ms: SUITE_TIMEOUT_MS })
+}
+
+// Whether the merge that stopped on `files` was finished. A command that fails leaves the merge in
+// progress and answers `false`, so the stop is the `conflict` it would have been without this table.
+async function resolve(
+	files: ReadonlyArray<string>,
+	table: ReadonlyArray<RegeneratedFile> = REGENERATED_FILES,
+): Promise<boolean> {
+	const entries = regenerated_for(files, table)
+
+	if (entries.length === 0) return false
+
+	try {
+		await regenerate(entries, await git_command.repository_root())
+		await conclude_merge(entries)
+	} catch {
+		return false
+	}
+
+	return true
+}
+
+const main_merge_regenerate = { REGENERATED_FILES, resolve }
+
+export type { RegeneratedFile }
+export { main_merge_regenerate }

package/scripts/git/main-merge.ts

@@ -6,6 +6,7 @@ import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-c
 import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
 import { main_merge_guard } from './main-merge-guard'
+import { main_merge_regenerate } from './main-merge-regenerate'
 
 // `josh main:merge` (`josh mm`) — bring the default branch into the branch this checkout is on.
 //
@@ -62,18 +63,26 @@ interface MergeTarget {
 }
 
 // A failure that left no unmerged path — a remote that cannot be reached, a hook that refused — is not
-// a conflict, so it is rethrown rather than reported as one with nothing to resolve.
+// a conflict, so it is rethrown rather than reported as one with nothing to resolve. A conflict only on
+// generated files is regenerated and committed (`main-merge-regenerate.ts`), so it answers `undefined`
+// and the merge reads as finished.
+async function unresolved_conflict(error: unknown): Promise<MergeOutcome | undefined> {
+	const files = main_merge_guard.unmerged_paths(await git_command.status())
+
+	if (files.length === 0) throw error
+
+	return (await main_merge_regenerate.resolve(files)) ? undefined : { kind: 'conflict', files }
+}
+
 async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
 	const { default_branch, current_branch } = target
 
 	try {
 		await git_command.merge_branch(default_branch, merge_message(default_branch, current_branch))
 	} catch (error) {
-		const files = main_merge_guard.unmerged_paths(await git_command.status())
-
-		if (files.length === 0) throw error
+		const conflict = await unresolved_conflict(error)
 
-		return { kind: 'conflict', files }
+		if (conflict !== undefined) return conflict
 	}
 
 	return { kind: target.is_current ? 'current' : 'merged', branch: default_branch }

package/scripts/hooks/batch-guard.ts

@@ -54,16 +54,14 @@ function batching_mode(): LaneGuardMode {
 	return lane_guard_policy.mode_here('batching')
 }
 
-// A guard the enumeration turns fully `off` says nothing at all. Batching is `notice` in a lane child
-// since kit#2276, so a candidate call is reached there; only a guard some future enumeration sets to
-// `off` is skipped. On the main line the mode is `refuse`.
+// A guard the enumeration turns fully `off` says nothing at all. The lane-child mode and its reason
+// live in `lane-guard-policy.ts`; on the main line the mode is `refuse`.
 function is_candidate(call: GuardedCall): boolean {
 	return is_batch_candidate(call) && batching_mode() !== 'off'
 }
 
-// A refusable call is refused only where the mode is `refuse`. A lane child is `notice` (kit#2276), so
-// it reaches here and is withheld the refusal — the notice branch below carries the guidance instead,
-// because a refusal ends a headless child's turn (kit#2138).
+// A refusable call is refused only where the mode is `refuse`. Under any other mode it is withheld the
+// refusal; why a lane child takes that mode is its `because` in `lane-guard-policy.ts`.
 function should_block_here(tail: string, call: GuardedCall, refused_at_ms: number): boolean {
 	if (batching_mode() !== 'refuse') return false
 
@@ -71,8 +69,7 @@ function should_block_here(tail: string, call: GuardedCall, refused_at_ms: numbe
 }
 
 // The whole-file write earns a notice on every run. The second branch turns a
-// refusable call into a notice under a `notice`-mode guard, which is the mode batching takes in a lane
-// child again since kit#2276. Both read the notice's own record, so a notice never spends the refusal's
+// refusable call into a notice under a `notice`-mode guard. Both read the notice's own record, so a notice never spends the refusal's
 // stamp and re-fires on the notice's own `NOTICE_REFIRE_EVERY` cadence.
 function should_notify_here(tail: string, call: GuardedCall, notified_at_ms: number): boolean {
 	if (time_batch_guard.should_notify(tail, call, notified_at_ms)) return true

package/scripts/hooks/pre-commit-lint.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { core_budget } from '#scripts/gate/core-budget'
+import {
+	CSPELL_COMMIT_CACHE_FLAGS,
+	ESLINT_COMMIT_CACHE_FLAGS,
+	PRETTIER_CACHE_FLAGS,
+} from '#scripts/josh/josh-command-types'
+import { resolve_spawn_exit } from '#scripts/lib/spawn-exit'
+import { execa } from 'execa'
+
+// The pre-commit hook's cspell, prettier and eslint runs over the staged files. They go through here
+// rather than a bare `pnpm exec` in `lefthook/base.yml` so each cache location comes from the
+// constant its ignore rules are asserted against (joshuafolkken/kit#3948) — a YAML copy would keep
+// writing the old file the day that constant moves.
+//
+// cspell and eslint write the hook's own files: a staged-files cspell run prunes every entry it did
+// not visit, and `--quiet` stores eslint reports without their warnings. Prettier does neither, so
+// it shares the gate's file and a commit right after a green gate checks nothing twice.
+
+const ARGV_OFFSET = 2
+const USAGE_ERROR_EXIT_CODE = 2
+const PNPM = 'pnpm'
+
+const TOOL_ARGUMENTS: Readonly<Record<string, ReadonlyArray<string>>> = {
+	cspell: [
+		'exec',
+		'cspell',
+		'lint',
+		'--no-must-find-files',
+		'--no-progress',
+		...CSPELL_COMMIT_CACHE_FLAGS,
+	],
+	prettier: ['exec', 'prettier', '--check', '--ignore-unknown', ...PRETTIER_CACHE_FLAGS],
+	eslint: ['exec', 'eslint', '--quiet', ...ESLINT_COMMIT_CACHE_FLAGS],
+}
+
+// **Each tool claims its place in the core budget** (joshuafolkken/kit#3944): lefthook starts the three
+// in parallel, and off the ledger every other lane's admission saw them only as foreign load. Each is
+// one process over the staged files — eslint over 40 of them took 16.9s of CPU over 14.0s of wall at
+// 1,225 MB, the one-process shape the whole-tree scan's weight already names.
+// The key is the one `CORE_WEIGHTS` and `MEMORY_MB` both declare the tool under.
+const TOOL_BUDGETS: Readonly<Record<string, 'spell_check' | 'format' | 'eslint_scan'>> = {
+	cspell: 'spell_check',
+	prettier: 'format',
+	eslint: 'eslint_scan',
+}
+
+const USAGE = `Usage: josh pre-commit-lint <${Object.keys(TOOL_ARGUMENTS).join('|')}> [files...]`
+
+function build_arguments(
+	tool: string,
+	staged_files: ReadonlyArray<string>,
+): ReadonlyArray<string> | undefined {
+	const tool_arguments = TOOL_ARGUMENTS[tool]
+	if (tool_arguments === undefined) return undefined
+
+	return [...tool_arguments, ...staged_files]
+}
+
+async function run_tool(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const result = await execa(PNPM, command_arguments, { stdio: 'inherit', reject: false })
+
+	return resolve_spawn_exit(PNPM, result)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [tool = '', ...staged_files] = argv
+	const command_arguments = build_arguments(tool, staged_files)
+	const budget = TOOL_BUDGETS[tool]
+
+	if (command_arguments === undefined || budget === undefined) {
+		console.error(USAGE)
+
+		return USAGE_ERROR_EXIT_CODE
+	}
+
+	return await core_budget.with_command_reservation(
+		core_budget.CORE_WEIGHTS[budget],
+		async () => await run_tool(command_arguments),
+		{ memory_mb: core_budget.MEMORY_MB[budget], command: `pre-commit ${tool}` },
+	)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run(process.argv.slice(ARGV_OFFSET))
+}
+
+const pre_commit_lint = { build_arguments, run, USAGE_ERROR_EXIT_CODE }
+
+export { pre_commit_lint }

package/scripts/hooks/pre-push-unit.ts

@@ -133,7 +133,7 @@ async function run_reserved_suite(vitest_arguments: ReadonlyArray<string>): Prom
 	return await core_budget.with_command_reservation(
 		gate_plan.direct_unit_weight(),
 		async () => await test_unit_guard.run_guarded_unit(process.cwd(), vitest_arguments),
-		{ memory_mb: gate_plan.direct_unit_memory() },
+		{ memory_mb: gate_plan.direct_unit_memory(), command: 'pre-push test:unit' },
 	)
 }