@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/test/test-related.ts

@@ -1,11 +1,17 @@
-#!/usr/bin/env tsx
-import { existsSync } from 'node:fs'
-import { fileURLToPath } from 'node:url'
+import { existsSync, readFileSync } from 'node:fs'
+import path from 'node:path'
+import { gate_plan } from '#scripts/gate/gate-plan'
 import type { GateTree } from '#scripts/gate/gate-tree'
+import { input_fingerprint } from '#scripts/gate/input-fingerprint'
+import { moved_paths } from '#scripts/gate/moved-paths'
 import { scoped_green } from '#scripts/gate/scoped-green'
+import { since_green } from '#scripts/gate/since-green'
 import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { changed_paths } from '#scripts/git/changed-paths'
 import { review_stamps } from '#scripts/review/review-stamps'
-import { related_scope } from './test-related-scope'
+import { test_read_map, type ReadMap } from './test-read-map'
+import { test_related_record, type RunInput } from './test-related-record'
+import { related_scope, type RelatedScope, type ScopeRequest } from './test-related-scope'
 import { test_unit_guard } from './test-unit-guard'
 
 // `josh test:related` — the unit check an implementation loop runs between edits.
@@ -30,27 +36,303 @@ function conclusive_tree(before: GateTree | undefined): GateTree | undefined {
 	return test_unit_guard.is_running(process.cwd()) ? before : undefined
 }
 
-async function run_related_tests(command_arguments: ReadonlyArray<string>): Promise<number> {
-	const root = await changed_file_scope.repository_root_or_cwd()
-	const scope = await changed_file_scope.resolve_command_scope({
-		command_arguments,
+// The change a narrowing reads, and the map it reads it against. `is_unmoved` is the since-green
+// reading's positive fact that nothing moved since this command was last green on this checkout.
+// `synced` is the part of the change a main sync brought in, kept for the run's ledger record, and
+// `since_map` the part the change since the map's tree joined to what this change moved.
+type ChangeReading = Pick<ScopeRequest, 'changed' | 'map' | 'since_map'> & {
+	is_unmoved?: true
+	synced?: ReadonlyArray<string>
+}
+
+// A failure answers `undefined` rather than an empty list: the two are opposite inputs to
+// `resolve_scope`, and only one of them means "could not tell".
+async function read_or_undefined(
+	read: () => Promise<ReadonlyArray<string>>,
+): Promise<ReadonlyArray<string> | undefined> {
+	try {
+		return await read()
+	} catch {
+		return undefined
+	}
+}
+
+async function branch_change(): Promise<ReadonlyArray<string> | undefined> {
+	return await read_or_undefined(async () => await changed_paths.read_changed_paths(false))
+}
+
+// **The change a map answers for is the change since the tree it was recorded on** — its commit and
+// the content its dirty files held then (`test_read_map.changed_since_tree`). A commit git can no
+// longer resolve — a pruned or foreign map — leaves the branch change with no map, which runs the
+// whole suite on any non-code file.
+async function change_since(
+	root: string,
+	map: ReadMap,
+): Promise<ReadonlyArray<string> | undefined> {
+	const since = await read_or_undefined(
+		async () => await changed_paths.read_changed_since(map.commit),
+	)
+
+	if (since === undefined) return undefined
+
+	return test_read_map.changed_since_tree(
+		map,
+		since,
+		input_fingerprint.of_files(root, Object.keys(map.dirty)),
+	)
+}
+
+// **The map's tree is whichever lane last ran the whole suite green**, so the change since it holds that
+// lane's own branch change too (joshuafolkken/kit#4527). What this branch did not change is marked
+// `since_map`: it still reaches its readers — a source file only when it names what moved — but only
+// this branch's change can send the run to the whole suite. A branch change git cannot read marks nothing.
+async function map_change(root: string, map: ReadMap): Promise<ChangeReading> {
+	const changed = await change_since(root, map)
+
+	if (changed === undefined) return { changed: await branch_change(), map: undefined }
+
+	const branch = await branch_change()
+
+	if (branch === undefined) return { changed, map }
+
+	return { changed, map, since_map: changed.filter((file) => !branch.includes(file)) }
+}
+
+// Explicit file arguments win over the git reading, which is what makes the narrowing testable by
+// hand and usable from a hook that already knows which file it just wrote. **The map still answers
+// only for the change since its tree**, so that change joins the arguments: a test added since the
+// map was recorded is in no entry, and only its own appearance in the change runs it — a source file
+// there only when it names a file the arguments moved (`naming_moved`).
+async function explicit_change(
+	root: string,
+	explicit: ReadonlyArray<string>,
+	map: ReadMap | undefined,
+): Promise<ChangeReading> {
+	const since = map === undefined ? undefined : await change_since(root, map)
+
+	if (since === undefined) return { changed: explicit, map: undefined }
+
+	const named = new Set(explicit)
+	const since_map = since.filter((file) => !named.has(file))
+
+	return { changed: [...named, ...since_map], map, since_map }
+}
+
+// **A non-code file a main sync brought in is not this branch's change** (joshuafolkken/kit#4572), so it
+// joins `since_map`: it still reaches the tests reading it, but never sends the run to the whole suite —
+// main's CI verified it. A synced module stays a moved file, so `vitest related` still walks to the
+// tests importing it, a branch-only one among them. A branch change git cannot read marks nothing.
+async function synced_data(synced: ReadonlyArray<string>): Promise<ReadonlyArray<string>> {
+	const data = synced.filter((file) => !related_scope.is_relatable(file))
+
+	if (data.length === 0) return []
+
+	const branch = (await branch_change()) ?? data
+
+	return data.filter((file) => !branch.includes(file))
+}
+
+// **What moved since this command's last green run** (`since-green.ts`), read as explicit arguments
+// are. A moved file — code or not — reaches the tests reading it as data through the map, whose
+// entries hold no module that started reading it after the map's tree; the change since that tree
+// joins the list — its test files, and a source file only when it names a moved file
+// (`naming_moved`) — so such a module runs the tests importing it. Nothing moved runs nothing; no map,
+// or one git can no longer diff against, answers `undefined`, which reads the whole branch change.
+async function since_green_change(
+	root: string,
+	map: ReadMap | undefined,
+): Promise<ChangeReading | undefined> {
+	const parts = await since_green.read_moved_parts(
+		review_stamps.test_related_stamp,
+		gate_plan.UNIT_LABEL,
+	)
+
+	if (parts === undefined) return undefined
+
+	const moved = moved_paths.union_of(parts)
+
+	if (moved.length === 0) return { changed: [], map, is_unmoved: true }
+
+	const change = await explicit_change(root, moved, map)
+
+	if (change.map === undefined) return undefined
+
+	process.stdout.write(`${since_green.describe(related_scope.COMMAND_LABEL, moved)}\n`)
+
+	const since_map = [...(change.since_map ?? []), ...(await synced_data(parts.synced))]
+
+	return { ...change, since_map, synced: parts.synced }
+}
+
+async function whole_change(root: string, map: ReadMap | undefined): Promise<ChangeReading> {
+	const since = await since_green_change(root, map)
+
+	if (since !== undefined) return since
+
+	return map === undefined ? { changed: await branch_change(), map } : await map_change(root, map)
+}
+
+async function read_change(
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+): Promise<ChangeReading> {
+	const map = test_read_map.read_map(root)
+	const explicit = command_arguments
+		.filter((argument) => !changed_file_scope.is_flag(argument))
+		.map((file) => path.relative(root, path.resolve(file)))
+
+	return explicit.length > 0
+		? await explicit_change(root, explicit, map)
+		: await whole_change(root, map)
+}
+
+// **The changed non-code files the map's tree held and that did not already differ from it** — the
+// ones whose having no reader in the map means no test reads them. A file that was dirty when the
+// map was recorded is left out, since the tree the tests read then was not the commit's. A git
+// failure holds none, which runs the whole suite on any of them.
+async function recorded_files(change: ChangeReading): Promise<ReadonlySet<string>> {
+	const { changed, map } = change
+
+	if (changed === undefined || map === undefined) return new Set()
+
+	const dirty = new Set(Object.keys(map.dirty))
+	const candidates = changed.filter((file) => !related_scope.is_relatable(file) && !dirty.has(file))
+
+	return new Set(
+		await read_or_undefined(async () => await changed_paths.read_held_at(map.commit, candidates)),
+	)
+}
+
+function text_of(file_path: string): string {
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+// Each file's text is read once, however many names it is checked for.
+function names_any(text: string, names: ReadonlyArray<string>): boolean {
+	return names.some((name) => text.includes(name))
+}
+
+// **The code files of the change since the map that name a file this change moved** — read off their
+// text, the one place a file-system read added since the map's tree shows (`is_code_input` in
+// `test-related-scope.ts`, joshuafolkken/kit#4532). A file the tree no longer holds names nothing.
+function naming_moved(root: string, change: ChangeReading): ReadonlySet<string> {
+	const { changed = [], since_map = [] } = change
+	const names = changed
+		.filter((file) => !since_map.includes(file))
+		.map((file) => path.basename(file))
+	const code = since_map.filter((file) => related_scope.is_relatable(file))
+
+	return new Set(code.filter((file) => names_any(text_of(path.join(root, file)), names)))
+}
+
+async function scope_of(root: string, change: ChangeReading): Promise<RelatedScope> {
+	const recorded = await recorded_files(change)
+	const naming = naming_moved(root, change)
+
+	return related_scope.resolve_scope({
 		root,
-		inputs: related_scope.scope_inputs(existsSync),
+		...change,
+		recorded,
+		naming_moved: naming,
+		is_present: existsSync,
 	})
+}
 
-	changed_file_scope.report_unusable_arguments(
-		command_arguments,
-		scope,
-		related_scope.COMMAND_LABEL,
-	)
+// **Whether a set of changed files can reach any test**, answered by the decision this command
+// narrows with, so the gate's reuse of a green unit step (`check-inputs.ts`) can never trust a change
+// this command would have run tests for. Unknown reaches: no map, or one recorded on a tree git can
+// no longer diff against. The change since the map joins the paths as it does for explicit
+// arguments, so a test added or edited after the map was recorded still reaches.
+async function reaches_tests(root: string, paths: ReadonlyArray<string>): Promise<boolean> {
+	if (paths.length === 0) return false
 
-	const before = await scoped_green.read_before(command_arguments)
-	const exit_code = await test_unit_guard.run_guarded_vitest(
+	const change = await explicit_change(root, paths, test_read_map.read_map(root))
+
+	if (change.map === undefined) return true
+
+	const scope = await scope_of(root, change)
+
+	return scope.mode !== 'none'
+}
+
+// A change known to reach no test succeeds without starting vitest, and says why.
+async function run_scope(
+	scope: RelatedScope,
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const description = related_scope.describe_scope(scope, root)
+
+	if (scope.mode === 'none') {
+		process.stdout.write(`${description}\n`)
+
+		return 0
+	}
+
+	return await test_unit_guard.run_guarded_vitest(
 		process.cwd(),
 		related_scope.vitest_arguments(scope, changed_file_scope.flags_of(command_arguments)),
 		related_scope.COMMAND_NAME,
-		related_scope.describe_scope(scope, root),
+		description,
 	)
+}
+
+async function resolve_change(root: string, change: ChangeReading): Promise<RelatedScope> {
+	const { UNMOVED_REASON } = related_scope
+
+	if (change.is_unmoved === true) return { mode: 'none', files: [], reason: UNMOVED_REASON }
+
+	return await scope_of(root, change)
+}
+
+async function read_run_input(
+	root: string,
+	command_arguments: ReadonlyArray<string>,
+): Promise<RunInput> {
+	const change = await read_change(root, command_arguments)
+	const scope = await resolve_change(root, change)
+
+	const { changed, synced = [], since_map = [] } = change
+
+	return { scope, root, changed, synced, since_map }
+}
+
+// Every run is timed and counted into the lane ledger (joshuafolkken/kit#4465).
+async function run_and_record(
+	input: RunInput,
+	command_arguments: ReadonlyArray<string>,
+): Promise<number> {
+	const started = performance.now()
+	const { exit_code, test_files } = await test_related_record.with_test_count(
+		async () => await run_scope(input.scope, input.root, command_arguments),
+	)
+
+	await test_related_record.record_run(input, {
+		elapsed_ms: performance.now() - started,
+		test_files,
+	})
+
+	return exit_code
+}
+
+async function run_related_tests(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const input = await read_run_input(root, command_arguments)
+
+	// A non-code argument is resolved through the map rather than handed to vitest, so only the
+	// code arguments can be ones vitest was not given.
+	changed_file_scope.report_unusable_arguments(
+		command_arguments.filter((argument) => related_scope.is_relatable(argument)),
+		input.scope,
+		related_scope.COMMAND_LABEL,
+	)
+
+	const before = await scoped_green.read_before(command_arguments)
+	const exit_code = await run_and_record(input, command_arguments)
 
 	await scoped_green.record_if_green(review_stamps.test_related_stamp, {
 		before: conclusive_tree(before),
@@ -60,10 +342,6 @@ async function run_related_tests(command_arguments: ReadonlyArray<string>): Prom
 	return exit_code
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	process.exitCode = await run_related_tests(process.argv.slice(changed_file_scope.ARGV_START))
-}
-
-const test_related = { run_related_tests }
+const test_related = { reaches_tests, run_related_tests }
 
 export { test_related }

package/scripts/test/test-unit-guard-main.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { test_unit_guard } from './test-unit-guard'
+
+// The `josh test:unit` entry, kept apart from `test-unit-guard.ts` because the gate and the pre-push
+// hook import that one: a bundle is one file, so a main guard there would fire for every command that
+// carries it (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await test_unit_guard.run_guarded_unit(
+		process.cwd(),
+		process.argv.slice(ARGV_OFFSET),
+	)
+}

package/scripts/test/test-unit-guard.ts

@@ -1,19 +1,19 @@
-#!/usr/bin/env tsx
 import { existsSync, globSync } from 'node:fs'
 import { availableParallelism } from 'node:os'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { PROJECT_ENVIRONMENT_KEYS } from '#ports'
+import { core_budget } from '#scripts/gate/core-budget'
 import { free_cores } from '#scripts/gate/free-cores'
 import { project_checks } from '#scripts/gate/project-checks'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
 import { execa } from 'execa'
 import { project_test_script, type ProjectScriptState } from './project-test-script'
 import { SKIP_MARKER } from './skip-marker'
+import { test_read_recording, type RecordingEnvironment } from './test-read-recording'
 import { unit_worker_share } from './unit-worker-share'
 
 const PNPM = 'pnpm'
 const FAIL_EXIT_CODE = 1
-const ARGV_START = 2
 const VITEST_PACKAGE = path.join('node_modules', 'vitest')
 const UNIT_GLOB = '**/*.{test,spec}.{ts,js}'
 const NODE_MODULES = 'node_modules'
@@ -178,32 +178,56 @@ function isolated_unit_environment(
 // both count "alone" and both run uncapped. Inside the marker the number is identical — this run's own
 // record is now on disk and `is_nested_run` therefore contributes nothing — and the window is gone.
 //
+// **The share is bounded by the claim the run was admitted on** (`unit_worker_share.cap_to_claim`), so
+// a share read after admission never opens more workers than the ledger holds for it
+// (joshuafolkken/kit#4235).
+//
 // **The machine is read only when no count was typed.** The reading waits out a sample window, and a
-// caller's `--maxWorkers` — the gate's cap among them, already bounded by the same reading — wins
-// whatever it says.
+// caller's `--maxWorkers` wins whatever it says. The gate's cap is one: its admission narrows it to the
+// free cores, and its unit step bounds it by the free memory once admitted (`gate-run-steps.ts`).
 async function vitest_share(vitest_arguments: ReadonlyArray<string>): Promise<number | undefined> {
 	if (unit_worker_share.has_worker_flag(vitest_arguments)) return undefined
 
 	const available_cores = availableParallelism()
+	// The cores and the memory free right now (joshuafolkken/kit#4528), from one reading.
 	const free = await free_cores.read({ available_cores })
+	const share = unit_worker_share.current_share(
+		available_cores,
+		unit_worker_share.live_run_count(),
+		free,
+	)
 
-	return unit_worker_share.current_share(available_cores, unit_worker_share.live_run_count(), free)
+	return unit_worker_share.cap_to_claim(share, core_budget.held_unit_claim())
 }
 
+async function execute_vitest(
+	vitest_arguments: ReadonlyArray<string>,
+	recording: RecordingEnvironment,
+): Promise<number> {
+	const result = await execa(PNPM, ['exec', 'vitest', ...vitest_arguments], {
+		env: { ...isolated_unit_environment(), ...recording },
+		extendEnv: false,
+		stdio: 'inherit',
+		reject: false,
+	})
+
+	return result.exitCode ?? FAIL_EXIT_CODE
+}
+
+// A whole-suite run also records the test-read map `josh test:related` narrows by.
 async function run_vitest(vitest_arguments: ReadonlyArray<string>): Promise<number> {
 	return await unit_worker_share.with_run_marker(async () => {
-		const sized = unit_worker_share.worker_arguments(
-			vitest_arguments,
-			await vitest_share(vitest_arguments),
+		const sized = [
+			...vitest_arguments,
+			...unit_worker_share.worker_arguments(vitest_arguments, await vitest_share(vitest_arguments)),
+		]
+		const root = await changed_file_scope.repository_root_or_cwd()
+
+		return await test_read_recording.with_read_recording(
+			root,
+			sized,
+			async (recording) => await execute_vitest(sized, recording),
 		)
-		const result = await execa(PNPM, ['exec', 'vitest', ...vitest_arguments, ...sized], {
-			env: isolated_unit_environment(),
-			extendEnv: false,
-			stdio: 'inherit',
-			reject: false,
-		})
-
-		return result.exitCode ?? FAIL_EXIT_CODE
 	})
 }
 
@@ -262,13 +286,6 @@ async function run_guarded_unit(
 	return await run_guarded_vitest(project_directory, ['run', ...extra_arguments])
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-	const extra_arguments = process.argv.slice(ARGV_START)
-	const exit_code = await run_guarded_unit(process.cwd(), extra_arguments)
-
-	process.exit(exit_code)
-}
-
 const test_unit_guard = {
 	SKIP_MARKER,
 	guard_action,
@@ -280,6 +297,7 @@ const test_unit_guard = {
 	isolated_unit_environment,
 	run_guarded_unit,
 	run_guarded_vitest,
+	vitest_share,
 }
 
 export type { GuardAction }

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-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 }