@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/test/unit-count-file.ts

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs'
+import { writeFile } from 'node:fs/promises'
+
+// How many test files a unit run ran, handed from the unit reporter to the caller that named a file to
+// receive it — `josh test:related`, which records it beside the scope it handed vitest
+// (joshuafolkken/kit#4465). Its own shipped module: the reporter is kit-only and the setup-file list
+// names files only, so neither can own a protocol a shipped reader shares.
+
+// Names the file the run's test-file count is written to.
+const COUNT_FILE_ENVIRONMENT = 'JOSH_UNIT_COUNT_FILE'
+
+// Best-effort like the ledger: a run is never failed by the file it reports into.
+async function write_count(count: number, target: string | undefined): Promise<void> {
+	if (target === undefined || target === '') return
+
+	try {
+		await writeFile(target, String(count))
+	} catch {
+		// The caller reads a missing count as unknown.
+	}
+}
+
+// A missing, empty or non-integer file is an unknown count, never zero.
+function read_count(file: string): number | undefined {
+	try {
+		const text = readFileSync(file, 'utf8').trim()
+		const count = Number(text)
+
+		return text !== '' && Number.isSafeInteger(count) ? count : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const unit_count_file = { COUNT_FILE_ENVIRONMENT, read_count, write_count }
+
+export { unit_count_file }

package/scripts/test/unit-durations.ts

@@ -0,0 +1,41 @@
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+
+// The per-file unit durations the CI shards are balanced by (joshuafolkken/kit#4467), read here so
+// the published `josh test:related` can weigh them too (joshuafolkken/kit#5105) — the reporter that
+// refreshes the record is kit-only (`tools/test/unit-duration-record.ts`). A project without the
+// record reads an empty one.
+
+type Durations = Readonly<Record<string, number>>
+
+const RECORD_FILE = 'tools/test/unit-durations.json'
+
+function parse(text: string): Durations {
+	const parsed: unknown = JSON.parse(text)
+
+	if (typeof parsed !== 'object' || parsed === null) return {}
+
+	return Object.fromEntries(
+		Object.entries(parsed).filter(
+			(entry): entry is [string, number] => typeof entry[1] === 'number',
+		),
+	)
+}
+
+// A missing or unreadable record is an empty one: every file then weighs the same fallback.
+function read(root: string): Durations {
+	try {
+		return parse(readFileSync(path.join(root, RECORD_FILE), 'utf8'))
+	} catch {
+		return {}
+	}
+}
+
+const unit_durations = {
+	RECORD_FILE,
+	parse,
+	read,
+}
+
+export type { Durations }
+export { unit_durations }

package/scripts/test/unit-run-marker.ts

@@ -0,0 +1,162 @@
+import { readdirSync } from 'node:fs'
+import path from 'node:path'
+import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
+import { process_identity } from '#scripts/josh/process-identity'
+import { process_owner_schema, type ProcessOwner } from '#scripts/josh/process-owner'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+
+// The run markers that count the unit runs in flight, and the division of the machine by that count —
+// the part of the worker share `vitest.config.ts` reads (`vitest-config-workers.ts`).
+//
+// **Kept apart from `unit-worker-share.ts` because the config imports it** (joshuafolkken/kit#4572).
+// Every module the vitest config imports is a whole-suite file (`whole-suite-files.ts`), and the
+// capacity and claim bounds of the share change often; held here, only this stable part is one.
+
+// A record that means something only while it exists, in the shape `stamp-file.ts` already keeps for
+// the in-flight gate marker. Keyed by pid rather than by checkout: `josh gate`'s unit step and a
+// `josh test:related` can be in flight in one checkout at once, and both of them are load.
+const RUN_PREFIX = 'josh-unit-running-'
+// Never below one: a share of zero would run no test at all and report the suite green.
+const MIN_WORKERS = 1
+// One run in flight is this run alone, which is the case that changes nothing.
+const SOLO_RUNS = 1
+
+// A marker is the writing process's identity and nothing else; a pid-only marker has an answer of its
+// own below (`is_running`) rather than being rejected here.
+type RunMarker = ProcessOwner
+
+function marker_path(pid: number = process.pid): string {
+	return stamp_file.stamp_path(RUN_PREFIX, String(pid))
+}
+
+// **A marker is evidence, and the process behind it is the test.** A run killed outright leaves its
+// file behind, and a count that trusted the file alone would hold every later run down to one worker
+// for good — the failure mode `run-hold.ts` answers with an expiry, which cannot be sized here because
+// a unit suite under six-way load already takes minutes. The process that writes this marker is the
+// long-lived one, so unlike a `run:hold` record its identity is a liveness test rather than a note for
+// the reader.
+//
+// **The pid alone was not that identity**. The section below already named
+// what goes wrong — a reissued pid turns a leaked marker into a permanent phantom — and answered it by
+// sweeping, which only ever collected the markers whose pid had *not* yet been reissued. Since the
+// record now carries the writing process's start time beside its pid, a reissued pid is recognized as
+// a different process and swept like any other dead one. A pid that is not positive is caught by the
+// same check, inside `process_identity`: `process.kill(0, …)` addresses the caller's own process group
+// rather than a process, so a truncated or hand-edited marker would otherwise answer "alive" forever.
+//
+// **"Cannot tell" counts as live here, which is the opposite of what the in-flight gate marker's
+// readers do with it, and deliberately so.** A marker with no recorded start time — written before the
+// field existed, or on a platform where it cannot be read — resolves toward *more* sharing: being
+// wrong that way costs this run a narrower share of the machine, while being wrong the other way puts
+// six unit suites on eleven cores, an oversubscription measured at a load
+// average of 209.
+function is_running(marker: RunMarker): boolean {
+	return process_identity.is_same_process(marker.pid, marker.process_start) !== false
+}
+
+function read_marker(source: string): RunMarker | undefined {
+	const raw = stamp_file.read_stamp_text(source)
+
+	if (raw === undefined) return undefined
+
+	const parsed = process_owner_schema.safeParse(json_value.parse_or_undefined(raw))
+
+	return parsed.success ? parsed.data : undefined
+}
+
+// An unreadable temp directory answers "no other run", which is the direction that leaves behavior
+// as it was rather than throttling a run on a guess. Unlike the network guard, being wrong here costs
+// wall time and never a false result.
+function marker_files(directory: string = PLATFORM_TEMP_ROOT): Array<string> {
+	try {
+		return readdirSync(directory).filter((name) => name.startsWith(RUN_PREFIX))
+	} catch {
+		return []
+	}
+}
+
+// **A marker whose process is gone is removed, not merely skipped.** Skipping it is correct only until
+// the operating system reissues that pid to something else, which on a machine left running for days
+// it will — and from then on the phantom is counted as a live run for good, with every solo run held
+// at one worker and `josh gate` announcing lanes that do not exist. `finally` in `with_run_marker`
+// cannot prevent the leak, because the interrupt that produces it (Ctrl-C reaching the whole foreground
+// group) does not unwind. Sweeping on read is what bounds it: the first later run collects it.
+function sweep_marker(source: string): void {
+	try {
+		stamp_file.remove_stamp(source)
+	} catch {
+		/* not ours to remove; counting it out is the whole requirement */
+	}
+}
+
+// **Only a marker that parsed to a dead pid is swept, and the unlink still cannot throw.** A marker
+// this account may not read — another user's file on a sticky `/tmp` — is `undefined` here, and
+// deleting on that answer would raise `EPERM` from a path with no `catch` between it and
+// `announce_gate_plan`: an unreadable file belonging to somebody else would abort the gate outright,
+// which is worse than the leak this sweep exists for. Unreadable therefore counts as not-live and is
+// left alone, exactly as it was before the sweep existed.
+function is_marker_live(source: string): boolean {
+	const marker = read_marker(source)
+
+	if (marker === undefined) return false
+	if (is_running(marker)) return true
+
+	sweep_marker(source)
+
+	return false
+}
+
+// Every marker in the temp directory whose process is still alive. This run's own is deliberately not
+// among them: both callers count *before* writing theirs, so the `+ 1` at the call site adds it.
+function live_run_count(directory: string = PLATFORM_TEMP_ROOT): number {
+	return marker_files(directory).filter((name) => is_marker_live(path.join(directory, name))).length
+}
+
+// **The gate claims its place before its unit step exists, and the child must not claim a second
+// one.** `josh gate` counts the runs in flight and then spawns `josh test:unit`, so without this the
+// marker appears a second or so after the count that needed it — and two lanes launched together, the
+// shape `epicrun` produces, both read "nothing else is running" and both take the whole machine. The
+// gate therefore marks itself around the whole run and passes this down through the environment; the
+// guard inside the child sees it and marks nothing, because the two processes are one run.
+const NESTED_KEY = 'JOSH_UNIT_RUN_MARKED'
+const NESTED_VALUE = '1'
+
+function is_nested_run(): boolean {
+	return process.env[NESTED_KEY] === NESTED_VALUE
+}
+
+// **`undefined` at one run means "leave the choice where it was".** The gate then applies its own
+// core reservation and the hook passes no flag at all, which is what both did before this existed.
+function resolve_unit_workers(available_cores: number, runs: number): number | undefined {
+	if (runs <= SOLO_RUNS) return undefined
+
+	return Math.max(MIN_WORKERS, Math.floor(available_cores / runs))
+}
+
+// **The write failing is not a reason to fail the run.** A marker that could not be written costs the
+// next run a wider share than it should have — the behavior that was there before — while a thrown
+// error here would fail a unit suite over bookkeeping.
+function mark_run_started(target: string): void {
+	try {
+		stamp_file.write_stamp(target, process_identity.own_fields())
+	} catch {
+		/* a missing marker costs a wide share, never a wrong result */
+	}
+}
+
+const unit_run_marker = {
+	MIN_WORKERS,
+	NESTED_KEY,
+	NESTED_VALUE,
+	RUN_PREFIX,
+	SOLO_RUNS,
+	is_nested_run,
+	live_run_count,
+	mark_run_started,
+	marker_path,
+	read_marker,
+	resolve_unit_workers,
+}
+
+export { unit_run_marker }

package/scripts/test/unit-setup-files.ts

@@ -0,0 +1,51 @@
+// The state guard runs on the pure project alone. isolate:false is what lets one file see the git
+// branch, working tree or GIT_* variables a sibling left changed, so that is the only run where a leak
+// is a correctness problem rather than a latent one — and the isolated project keeps exactly the guards
+// the single-project suite had. The network guard is armed once at the root instead, since it arms
+// `PATH` before any worker of either project forks.
+const STATE_GUARD: ReadonlyArray<string> = ['./tools/test/test-state-guard.ts']
+
+// Runs in every worker of both projects, before each test, and silences the real streams for the test
+// body so a fixture's direct `process.stdout` write cannot leak into `pnpm josh test:unit`'s output.
+// `setupFiles` rather than `globalSetup` because it must run inside the
+// worker where the test's writes happen, not once in the main process.
+const STDOUT_GUARD: ReadonlyArray<string> = ['./tools/test/test-stdout-guard.ts']
+
+// Runs in every worker for the same reason: it wraps that worker's own `fetch`, refusing a real
+// Telegram send and recording which test tried.
+const TELEGRAM_GUARD: ReadonlyArray<string> = ['./tools/test/test-telegram-guard.ts']
+
+// Runs in every worker too: it replaces that worker's machine reading, so a suite that drives the gate
+// admits the same way on every platform and every load.
+const MACHINE_GUARD: ReadonlyArray<string> = ['./tools/test/test-machine-guard.ts']
+
+// The guards every run of the suite arms, whichever config starts it: the network guard once in the
+// main process, the stdout, Telegram and machine guards in every worker. Named here so `vitest.config.ts` and
+// `vitest.harness.config.ts` read one definition — the harness once ran with none of them.
+const NETWORK_GUARD: ReadonlyArray<string> = ['./tools/test/test-network-guard.ts']
+const WORKER_GUARDS: ReadonlyArray<string> = [...STDOUT_GUARD, ...TELEGRAM_GUARD, ...MACHINE_GUARD]
+
+// Runs in every worker of the unit suite, idle unless a whole-suite `josh test:unit` asked it to
+// record which repository paths each test reads (`test-read-recorder.ts`). Not a guard, and not
+// the harness config's: only this suite's runs feed the test-read map.
+const READ_RECORDER: ReadonlyArray<string> = ['./tools/test/test-read-recorder.ts']
+
+// The unit suite's own reporter, which vitest loads by this path in its own process. Named rather
+// than imported so neither it nor the ledger it writes joins the config's import graph
+// (joshuafolkken/kit#4465).
+const UNIT_FILE_REPORTER = './vitest.reporter.config.ts'
+
+// Kept apart from `unit-projects.ts` so the shipped `josh test:related` can name every setup file
+// without loading the kit-internal project partition.
+const unit_setup_files = {
+	MACHINE_GUARD,
+	NETWORK_GUARD,
+	READ_RECORDER,
+	STATE_GUARD,
+	STDOUT_GUARD,
+	UNIT_FILE_REPORTER,
+	TELEGRAM_GUARD,
+	WORKER_GUARDS,
+}
+
+export { unit_setup_files }

package/scripts/test/unit-worker-share.ts

@@ -1,11 +1,6 @@
-import { readdirSync } from 'node:fs'
 import { availableParallelism } from 'node:os'
-import path from 'node:path'
-import { PLATFORM_TEMP_ROOT } from '#scripts/josh/platform-temporary'
-import { process_identity } from '#scripts/josh/process-identity'
-import { process_owner_schema, type ProcessOwner } from '#scripts/josh/process-owner'
 import { stamp_file } from '#scripts/josh/stamp-file'
-import { json_value } from '#scripts/lib/json-value'
+import { unit_run_marker } from './unit-run-marker'
 
 // How wide one vitest run may fan out when it is not the only one on the machine.
 //
@@ -24,134 +19,24 @@ import { json_value } from '#scripts/lib/json-value'
 // worker.
 //
 // **The division activates only under concurrency.** One run in flight — every solo run, CI included
-// — gets exactly the number the gate and the hook produced before this module existed, so a quiet
-// machine behaves bit for bit as it did and only the condition that was measured broken changes.
+// — gets no share from it; what bounds a solo run is the claim it was admitted on (`cap_to_claim`),
+// which for a direct run is vitest's own default on a small machine such as a four-core CI runner
+// (`gate_plan.direct_unit_weight`, joshuafolkken/kit#4607).
+//
+// **The run markers and their division of the machine are `unit-run-marker.ts`**, the part the vitest
+// config imports (joshuafolkken/kit#4572); the capacity and claim bounds and the flag handling are here.
+const { MIN_WORKERS, NESTED_KEY, NESTED_VALUE, SOLO_RUNS } = unit_run_marker
+const { is_nested_run, live_run_count, mark_run_started, marker_path, resolve_unit_workers } =
+	unit_run_marker
 
-// A record that means something only while it exists, in the shape `stamp-file.ts` already keeps for
-// the in-flight gate marker. Keyed by pid rather than by checkout: `josh gate`'s unit step and a
-// `josh test:related` can be in flight in one checkout at once, and both of them are load.
-const RUN_PREFIX = 'josh-unit-running-'
 // Vitest's own flag, in both spellings its CLI accepts — it normalizes `--max-workers` to the same
 // option, so a run that recognized only one of them would replace a number the caller typed with the
 // share and contradict the promise below. The camel-case one is what gets written.
 const WORKER_FLAG = '--maxWorkers'
 const WORKER_FLAGS: ReadonlyArray<string> = [WORKER_FLAG, '--max-workers']
-// Never below one: a share of zero would run no test at all and report the suite green.
-const MIN_WORKERS = 1
-// One run in flight is this run alone, which is the case that changes nothing.
-const SOLO_RUNS = 1
-
-// A marker is the writing process's identity and nothing else; a pid-only marker has an answer of its
-// own below (`is_running`) rather than being rejected here.
-type RunMarker = ProcessOwner
-
-function marker_path(pid: number = process.pid): string {
-	return stamp_file.stamp_path(RUN_PREFIX, String(pid))
-}
-
-// **A marker is evidence, and the process behind it is the test.** A run killed outright leaves its
-// file behind, and a count that trusted the file alone would hold every later run down to one worker
-// for good — the failure mode `run-hold.ts` answers with an expiry, which cannot be sized here because
-// a unit suite under six-way load already takes minutes. The process that writes this marker is the
-// long-lived one, so unlike a `run:hold` record its identity is a liveness test rather than a note for
-// the reader.
-//
-// **The pid alone was not that identity**. The section below already named
-// what goes wrong — a reissued pid turns a leaked marker into a permanent phantom — and answered it by
-// sweeping, which only ever collected the markers whose pid had *not* yet been reissued. Since the
-// record now carries the writing process's start time beside its pid, a reissued pid is recognized as
-// a different process and swept like any other dead one. A pid that is not positive is caught by the
-// same check, inside `process_identity`: `process.kill(0, …)` addresses the caller's own process group
-// rather than a process, so a truncated or hand-edited marker would otherwise answer "alive" forever.
-//
-// **"Cannot tell" counts as live here, which is the opposite of what the in-flight gate marker's
-// readers do with it, and deliberately so.** A marker with no recorded start time — written before the
-// field existed, or on a platform where it cannot be read — resolves toward *more* sharing: being
-// wrong that way costs this run a narrower share of the machine, while being wrong the other way puts
-// six unit suites on eleven cores, an oversubscription measured at a load
-// average of 209.
-function is_running(marker: RunMarker): boolean {
-	return process_identity.is_same_process(marker.pid, marker.process_start) !== false
-}
-
-function read_marker(source: string): RunMarker | undefined {
-	const raw = stamp_file.read_stamp_text(source)
-
-	if (raw === undefined) return undefined
-
-	const parsed = process_owner_schema.safeParse(json_value.parse_or_undefined(raw))
-
-	return parsed.success ? parsed.data : undefined
-}
-
-// An unreadable temp directory answers "no other run", which is the direction that leaves behavior
-// as it was rather than throttling a run on a guess. Unlike the network guard, being wrong here costs
-// wall time and never a false result.
-function marker_files(directory: string = PLATFORM_TEMP_ROOT): Array<string> {
-	try {
-		return readdirSync(directory).filter((name) => name.startsWith(RUN_PREFIX))
-	} catch {
-		return []
-	}
-}
-
-// **A marker whose process is gone is removed, not merely skipped.** Skipping it is correct only until
-// the operating system reissues that pid to something else, which on a machine left running for days
-// it will — and from then on the phantom is counted as a live run for good, with every solo run held
-// at one worker and `josh gate` announcing lanes that do not exist. `finally` in `with_run_marker`
-// cannot prevent the leak, because the interrupt that produces it (Ctrl-C reaching the whole foreground
-// group) does not unwind. Sweeping on read is what bounds it: the first later run collects it.
-function sweep_marker(source: string): void {
-	try {
-		stamp_file.remove_stamp(source)
-	} catch {
-		/* not ours to remove; counting it out is the whole requirement */
-	}
-}
-
-// **Only a marker that parsed to a dead pid is swept, and the unlink still cannot throw.** A marker
-// this account may not read — another user's file on a sticky `/tmp` — is `undefined` here, and
-// deleting on that answer would raise `EPERM` from a path with no `catch` between it and
-// `announce_gate_plan`: an unreadable file belonging to somebody else would abort the gate outright,
-// which is worse than the leak this sweep exists for. Unreadable therefore counts as not-live and is
-// left alone, exactly as it was before the sweep existed.
-function is_marker_live(source: string): boolean {
-	const marker = read_marker(source)
-
-	if (marker === undefined) return false
-	if (is_running(marker)) return true
-
-	sweep_marker(source)
-
-	return false
-}
-
-// Every marker in the temp directory whose process is still alive. This run's own is deliberately not
-// among them: both callers count *before* writing theirs, so the `+ 1` at the call site adds it.
-function live_run_count(directory: string = PLATFORM_TEMP_ROOT): number {
-	return marker_files(directory).filter((name) => is_marker_live(path.join(directory, name))).length
-}
-
-// **The gate claims its place before its unit step exists, and the child must not claim a second
-// one.** `josh gate` counts the runs in flight and then spawns `josh test:unit`, so without this the
-// marker appears a second or so after the count that needed it — and two lanes launched together, the
-// shape `epicrun` produces, both read "nothing else is running" and both take the whole machine. The
-// gate therefore marks itself around the whole run and passes this down through the environment; the
-// guard inside the child sees it and marks nothing, because the two processes are one run.
-const NESTED_KEY = 'JOSH_UNIT_RUN_MARKED'
-const NESTED_VALUE = '1'
-
-function is_nested_run(): boolean {
-	return process.env[NESTED_KEY] === NESTED_VALUE
-}
-
-// **`undefined` at one run means "leave the choice where it was".** The gate then applies its own
-// core reservation and the hook passes no flag at all, which is what both did before this existed.
-function resolve_unit_workers(available_cores: number, runs: number): number | undefined {
-	if (runs <= SOLO_RUNS) return undefined
-
-	return Math.max(MIN_WORKERS, Math.floor(available_cores / runs))
-}
+// The core vitest's own process — the pool, the reporter and Vite's transforms — keeps busy beside its
+// workers (joshuafolkken/kit#4362). A direct run's claim holds it above its worker count.
+const MAIN_PROCESS_CORES = 1
 
 // **The run count divides the machine; the free cores bound what that division hands out.** The
 // share counts only unit runs, so load from outside the core budget's ledger — Claude sessions, other
@@ -169,6 +54,50 @@ function cap_to_free(
 	return Math.max(MIN_WORKERS, Math.floor(free_cores))
 }
 
+// What the machine has free for this run's workers, both from `free-cores.ts`'s one reading: the free
+// cores, and the workers the free memory holds. Either is `undefined` where it could not be read.
+interface FreeCapacity {
+	cores: number | undefined
+	memory_workers: number | undefined
+}
+
+const UNREAD_CAPACITY: FreeCapacity = { cores: undefined, memory_workers: undefined }
+
+// **The free memory bounds the share as the free cores do** (joshuafolkken/kit#4528). Lanes running
+// their suites at once each sized workers from the cores alone, so their workers' memory piled up
+// until the batch stopped opening lanes. Both bounds go through `cap_to_free`, so an unread one leaves
+// the share as it was.
+function cap_to_capacity(
+	workers: number | undefined,
+	free: FreeCapacity,
+	available_cores: number,
+): number | undefined {
+	const core_capped = cap_to_free(workers, free.cores, available_cores)
+
+	return cap_to_free(core_capped, free.memory_workers, available_cores)
+}
+
+// The core-budget claim a unit run holds: the weight it reserved, and the narrower one it was admitted
+// at past the wait cap.
+interface UnitClaim {
+	weight: number
+	granted?: number | undefined
+}
+
+// **The share never exceeds the claim the run was admitted on** (joshuafolkken/kit#4235). The share is
+// read after admission, when fewer runs may be in flight than when the weight was sized, and a share
+// wider than the claim puts workers on the machine the ledger does not hold. The claim bounds a solo
+// share too: vitest's own choice is one worker per core but one, wider than the weight the ledger
+// reserves for a unit run from seven cores up, so leaving it in place would open workers no claim holds. The claim holds
+// vitest's own process as well, so its workers are the claim less that core.
+function cap_to_claim(share: number | undefined, claim: UnitClaim | undefined): number | undefined {
+	if (claim === undefined) return share
+
+	const bound = Math.max(MIN_WORKERS, (claim.granted ?? claim.weight) - MAIN_PROCESS_CORES)
+
+	return Math.min(share ?? bound, bound)
+}
+
 // The share this run may take, read from the machine. Separate from `resolve_unit_workers` so that
 // one stays a pure function of two numbers and every test of it can pass them.
 //
@@ -179,12 +108,12 @@ function cap_to_free(
 function current_share(
 	available_cores: number = availableParallelism(),
 	live_runs: number = live_run_count(),
-	free_cores?: number,
+	free: FreeCapacity = UNREAD_CAPACITY,
 ): number | undefined {
 	const own_run = is_nested_run() ? 0 : SOLO_RUNS
 	const share = resolve_unit_workers(available_cores, live_runs + own_run)
 
-	return cap_to_free(share, free_cores, available_cores)
+	return cap_to_capacity(share, free, available_cores)
 }
 
 function is_worker_flag(argument: string): boolean {
@@ -213,17 +142,6 @@ function worker_arguments(
 	return [`${WORKER_FLAG}=${String(share)}`]
 }
 
-// **The write failing is not a reason to fail the run.** A marker that could not be written costs the
-// next run a wider share than it should have — the behavior that was there before — while a thrown
-// error here would fail a unit suite over bookkeeping.
-function mark_run_started(target: string): void {
-	try {
-		stamp_file.write_stamp(target, process_identity.own_fields())
-	} catch {
-		/* a missing marker costs a wide share, never a wrong result */
-	}
-}
-
 // `finally`, so a suite that threw still clears its marker — and so does the nested branch, which
 // restores nothing because it wrote nothing.
 async function with_run_marker<T>(run: () => Promise<T>): Promise<T> {
@@ -245,21 +163,16 @@ async function with_run_marker<T>(run: () => Promise<T>): Promise<T> {
 }
 
 const unit_worker_share = {
-	MIN_WORKERS,
-	NESTED_KEY,
-	NESTED_VALUE,
-	RUN_PREFIX,
-	SOLO_RUNS,
+	...unit_run_marker,
+	MAIN_PROCESS_CORES,
+	cap_to_capacity,
+	cap_to_claim,
 	cap_to_free,
 	current_share,
 	has_worker_flag,
-	is_nested_run,
-	live_run_count,
-	marker_path,
-	read_marker,
-	resolve_unit_workers,
 	with_run_marker,
 	worker_arguments,
 }
 
+export type { FreeCapacity, UnitClaim }
 export { unit_worker_share }

package/scripts/test/vitest-cache-directory.ts

@@ -0,0 +1,19 @@
+// The Vite cache directory `vitest.config.ts` hands a vitest run in a throwaway tree (joshuafolkken/kit#4770).
+//
+// **A tree from `base-tree.ts` borrows this checkout's `node_modules`**, and vitest keys its dependency
+// optimizer's cache by project name alone, so a `josh test:red` / `josh test:pinned` run beside the gate
+// re-bundled the same `node_modules/.vite/vitest/<hash>/deps_ssr` the gate was importing from, and a gate
+// file failed on a deleted `execa.js`. The tree's run names a directory of its own through
+// `CACHE_DIRECTORY_KEY`; any other run leaves it unset and keeps Vite's default.
+
+const CACHE_DIRECTORY_KEY = 'JOSH_VITEST_CACHE_DIR'
+
+function config_cache_directory(environment: NodeJS.ProcessEnv = process.env): string | undefined {
+	const directory = environment[CACHE_DIRECTORY_KEY] ?? ''
+
+	return directory === '' ? undefined : directory
+}
+
+const vitest_cache_directory = { CACHE_DIRECTORY_KEY, config_cache_directory }
+
+export { vitest_cache_directory }

package/scripts/test/vitest-cli-excludes.ts

@@ -0,0 +1,14 @@
+// **A command line's `--exclude` reaches both unit projects** (joshuafolkken/kit#5105): vitest applies
+// the flag to the root config alone, which the inline projects of `tools/test/unit-projects.ts` do not
+// inherit, so without this it excluded nothing. `josh test:related` passes it to leave the heavy files
+// out of a scoped run. A leaf module, since `vitest.config.ts` imports it.
+
+const EXCLUDE_FLAG = '--exclude'
+
+function cli_excludes(argv: ReadonlyArray<string>): Array<string> {
+	return argv.slice(1).filter((_argument, index) => argv[index] === EXCLUDE_FLAG)
+}
+
+const vitest_cli_excludes = { EXCLUDE_FLAG, cli_excludes }
+
+export { vitest_cli_excludes }