@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,251 @@
+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 { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+
+// How wide one vitest run may fan out when it is not the only one on the machine
+// (joshuafolkken/kit#1515).
+//
+// **`gate-plan.ts` sizes the unit suite from the core count and nothing else**, so six lanes running
+// `josh gate` at once each concluded "11 cores, take 7 workers" and put 42 workers on 11 cores. The
+// pre-push hook once passed no cap at all; it now runs the suite through `test_unit_guard.run_guarded_unit`
+// (joshuafolkken/kit#1334), the same guard `josh test:unit` uses, so the share below applies there too.
+// Measured on the machine this was found on — load average 14.97 in the field, and 209 in a deliberate
+// reproduction of six concurrent suites, against 22 once the share below was applied.
+//
+// **What it fixes, and what it does not.** Six concurrent copies of the full suite produced ten
+// `Test timed out in 10000ms` failures across six runs; at the share this module hands out, the same
+// six runs produced **none**. It is the *second* multiplicand of joshuafolkken/kit#1515 — the first
+// was a live `git fetch` inside two test files, which is fixed in `test-network-guard.ts` and its
+// callers, and which no worker count would have repaired: that one failed on an idle machine at one
+// 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.
+
+// 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
+
+// `process_start` is optional because a marker written before joshuafolkken/kit#1245, or on a platform
+// whose start time cannot be read, carries only the pid — and that case has an answer of its own
+// below rather than being rejected here.
+const run_marker_schema = z.object({ pid: z.number(), process_start: z.string().optional() })
+
+type RunMarker = z.infer<typeof run_marker_schema>
+
+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** (joshuafolkken/kit#1245). 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, which is the oversubscription joshuafolkken/kit#1515 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
+
+	try {
+		const parsed = run_marker_schema.safeParse(JSON.parse(raw))
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return 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 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.
+//
+// **A nested run is already counted, and adding one for it would be wrong rather than cautious.**
+// Inside `josh gate` the marker was written by the parent before this process started, so `+ 1` here
+// would count one run twice — and on a machine the gate leaves uncapped, a four-core CI runner among
+// them, that alone would halve a solo run nothing was sharing.
+function current_share(
+	available_cores: number = availableParallelism(),
+	live_runs: number = live_run_count(),
+): number | undefined {
+	const own_run = is_nested_run() ? 0 : SOLO_RUNS
+
+	return resolve_unit_workers(available_cores, live_runs + own_run)
+}
+
+function is_worker_flag(argument: string): boolean {
+	return WORKER_FLAGS.some((flag) => argument === flag || argument.startsWith(`${flag}=`))
+}
+
+// **A number the caller typed is never overridden.** `pnpm josh test:unit --maxWorkers=4` is a person
+// saying what they want, and `josh gate` passes its own cap for a reason this module cannot see — the
+// three sibling checks it has to leave cores for. Both already account for the share: the gate through
+// `gate-plan.ts`, which is handed the same count.
+//
+// **`share` is required rather than defaulted to `current_share()`.** A default reading the machine
+// would make this function's own answer depend on what happened to be running while it was asked, and
+// `f(args, undefined)` takes the default rather than the value — so the case that matters most, "this
+// run is alone", would be the one case no test could express.
+function worker_arguments(
+	vitest_arguments: ReadonlyArray<string>,
+	share: number | undefined,
+): Array<string> {
+	if (share === undefined) return []
+	if (vitest_arguments.some((argument) => is_worker_flag(argument))) return []
+
+	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> {
+	if (is_nested_run()) return await run()
+
+	const target = marker_path()
+
+	mark_run_started(target)
+	process.env[NESTED_KEY] = NESTED_VALUE
+
+	try {
+		return await run()
+	} finally {
+		// Emptied rather than deleted: this project bans deleting a computed key, and an empty string is
+		// not `NESTED_VALUE`, so `is_nested_run` reads it as cleared either way.
+		process.env[NESTED_KEY] = ''
+		stamp_file.remove_stamp(target)
+	}
+}
+
+const unit_worker_share = {
+	MIN_WORKERS,
+	NESTED_KEY,
+	RUN_PREFIX,
+	SOLO_RUNS,
+	WORKER_FLAG,
+	current_share,
+	is_nested_run,
+	is_running,
+	live_run_count,
+	marker_files,
+	marker_path,
+	read_marker,
+	resolve_unit_workers,
+	with_run_marker,
+	worker_arguments,
+}
+
+export { unit_worker_share }

package/scripts/test/vitest-include-globs.ts

@@ -0,0 +1,12 @@
+const VITEST_INCLUDE_GLOBS: ReadonlyArray<string> = [
+	'*.test.ts',
+	'scripts/**/*.test.ts',
+	'scripts-ai/**/*.test.ts',
+	'env/**/*.test.ts',
+	'eslint/**/*.test.ts',
+	'ports/**/*.test.ts',
+	'prettier/**/*.test.ts',
+	'templates/**/*.test.ts',
+]
+
+export { VITEST_INCLUDE_GLOBS }

package/scripts/time-runtime/time-agent-bundles.ts

@@ -0,0 +1,128 @@
+import { time_bundle_call } from './time-bundle-call'
+import { time_round_trips } from './time-round-trips'
+import { time_spans, type Span } from './time-spans'
+
+// Independent subagent launches that went out one per turn, when they could have fanned out in one
+// (joshuafolkken/kit#1854).
+//
+// **This is a second series, deliberately kept apart from the consecutive one in `time-bundles.ts`.**
+// That one reads *consecutive* single-call turns, so a launch fired minutes apart with implementation
+// and investigation calls between it and the next never enters a sequence — and a launch is not
+// bundleable either, so it could not extend one even if it were adjacent. Loosening the consecutive
+// definition to reach these would fold dependent calls into it; a separate series with its own
+// dependency test is the only way to count the spread-apart shape without that cost.
+//
+// **It returns the group sizes and nothing more**, so `time-bundles.ts` prices them with the very
+// helpers it prices its own sequences with — `recoverable_of`, `longest_of`, the row count — rather
+// than a second copy of that arithmetic living here. The two series then fold in identically, which is
+// what keeps `unattributed_round_trips` at zero.
+//
+// **What the shape costs.** Run #1839 launched three investigation subagents at 1.7 / 7.3 / 11.4
+// minutes, in three separate turns, whose three questions — the lane machinery, the API signatures,
+// the registry and log paths — needed nothing from one another and could have gone out at once. The
+// consecutive detector counted none of them. The three review finders it launched at 36.7 minutes, by
+// contrast, went out *in one turn* and cost nothing, which is the shape this series must not charge.
+//
+// ## When two launches could have been one
+//
+// A launch turn joins the group before it unless one of two things says the later turn depended on
+// what came since the earlier one:
+//
+// **A certain write since the last launch.** Implementation between two launches means the later one
+// may read what was produced — the review finders name the files the implementation wrote, which is a
+// read-after-write dependency exactly as `time-bundles.ts` treats one. Run #1839 wrote nothing before
+// its third investigation launch and forty-odd files before its review launch, so this alone places
+// the investigation trio in one group and the review turn in another.
+//
+// **A prompt that references a prior finding** (`has_prior_reference`, from `time-bundle-call.ts`). A
+// read-only investigation chain — the second question only askable once the first is answered — writes
+// nothing between its links, so the write test cannot see it; the marker scan is what does, and it is
+// the caveat joshuafolkken/kit#1847 recorded.
+//
+// **Parallel launches are one turn and cost nothing.** Launches sharing a non-empty message id were
+// issued together, so they collapse to a single turn here — the review trio is one turn, not three —
+// and a group of one turn is dropped, exactly as a consecutive sequence of one is.
+
+const NONE = 0
+const ONE = 1
+// A group of one is a lone launch that had nothing to fan out with — not a finding, exactly as a
+// consecutive sequence of one is not. Only groups of two or more are kept, so a returned size is
+// always `>= 2` and prices the same way a consecutive sequence's does.
+const MIN_GROUP = 2
+
+function is_launch(span: Span): boolean {
+	return (
+		span.category === time_spans.TOOL_CATEGORY &&
+		!span.is_continuation &&
+		time_bundle_call.is_launch_tool(span.label)
+	)
+}
+
+// The walk's running pieces: the sizes of the groups already closed, the count of launch turns in the
+// open group, whether a certain write has landed since that group's last launch, and the message id of
+// that last launch so a parallel sibling is not counted as a second turn.
+interface Walk {
+	closed: Array<number>
+	open: number
+	wrote_since: boolean
+	turn_id: string
+}
+
+function new_walk(): Walk {
+	return { closed: [], open: NONE, wrote_since: false, turn_id: time_spans.NO_MESSAGE_ID }
+}
+
+// A group is worth keeping only at two turns or more, exactly as a consecutive sequence is.
+function close_group(walk: Walk): void {
+	if (walk.open >= MIN_GROUP) walk.closed.push(walk.open)
+
+	walk.open = NONE
+}
+
+// A launch sharing the open turn's non-empty id was issued beside it, so it is the same turn. An
+// absent id cannot make that claim, so it always opens a new turn — the conservative reading, matching
+// `is_same_turn` in `time-bundles.ts`.
+function is_same_turn(walk: Walk, span: Span): boolean {
+	return span.message_id !== time_spans.NO_MESSAGE_ID && span.message_id === walk.turn_id
+}
+
+// A dependent launch closes the open group and starts a new one at itself, exactly as a target
+// conflict does for the consecutive series — everything after it may still fan out with it. The
+// `wrote_since` flag is reset here, so it always means "a write since *this* group's last launch".
+function open_turn(walk: Walk, span: Span): void {
+	if (walk.wrote_since || span.has_prior_reference) close_group(walk)
+
+	walk.open += ONE
+	walk.turn_id = span.message_id
+	walk.wrote_since = false
+}
+
+function step(walk: Walk, span: Span): void {
+	if (span.is_writing) {
+		walk.wrote_since = true
+
+		return
+	}
+
+	if (!is_launch(span) || is_same_turn(walk, span)) return
+
+	open_turn(walk, span)
+}
+
+// The fan-out group sizes, each `>= 2` — the shape `time-bundles.ts` already prices a sequence list in.
+//
+// **Ordered before it is walked, for the reason `time-bundles.ts` gives**: a run's spans do not arrive
+// in time order once a delegated unit's are appended after the parent's, and two launches from
+// different sessions read as adjacent otherwise.
+function agent_bundles(spans: ReadonlyArray<Span>): ReadonlyArray<number> {
+	const walk = new_walk()
+
+	for (const span of time_round_trips.in_time_order(spans)) step(walk, span)
+	close_group(walk)
+
+	return walk.closed
+}
+
+const time_agent_bundles = { agent_bundles }
+
+export { time_agent_bundles }