@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/lane/openai-lane-ship.ts

@@ -1,6 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
-import { run_ship_probe } from '#scripts/run/run-ship-probe'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { run_ship_probe } from '#scripts/run/ship/run-ship-probe'
 
 const POLL_MS = 250
 type ShipEnding = 'none' | 'success' | 'failed' | 'abnormal'

package/scripts/lane/openai-lane-supervisor-owner.ts

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto'
+import { linkSync, statSync, unlinkSync } from 'node:fs'
+import { process_identity } from '#scripts/josh/process-identity'
+import { process_owner_schema } from '#scripts/josh/process-owner'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { z } from 'zod'
+import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
+
+// The supervisor's owner and state stamps — who holds a lane, and which child it last launched —
+// split out of `openai-lane-supervisor.ts` when it reached its line limit (joshuafolkken/kit#3264).
+// `openai_lane_supervisor` re-exports each public one under the name it always had, so the move
+// changed no call site and no suite that spies on `openai_lane_supervisor`.
+
+const OWNER_PREFIX = 'josh-openai-lane-supervisor-'
+const STATE_PREFIX = 'josh-openai-lane-supervisor-state-'
+const CLAIM_POLL_MS = 50
+const CLAIM_POLL_LIMIT = 40
+// The shared owner pair, with the pid narrowed: this record is written only by a live supervisor, so a
+// pid that is not a real one marks it as corrupt rather than as a dead owner.
+const owner_schema = process_owner_schema.extend({
+	issue: z.string(),
+	nonce: z.string(),
+	pid: z.number().int().positive(),
+})
+const state_schema = z.object({
+	owner_nonce: z.string(),
+	child_pid: z.number().int().positive().optional(),
+	child_process_start: z.string().optional(),
+	epoch: z.number().int().nonnegative(),
+})
+
+type SupervisorOwner = z.infer<typeof owner_schema>
+type SupervisorState = z.infer<typeof state_schema>
+
+function marker_path(lane_directory: string): string {
+	return stamp_file.stamp_path(OWNER_PREFIX, lane_directory)
+}
+
+function state_path(lane_directory: string): string {
+	return stamp_file.stamp_path(STATE_PREFIX, lane_directory)
+}
+
+function parsed_stamp<T>(target: string, schema: z.ZodType<T>): T | undefined {
+	try {
+		const value: unknown = JSON.parse(stamp_file.read_stamp_text(target) ?? '')
+		const parsed = schema.safeParse(value)
+
+		return parsed.success ? parsed.data : undefined
+	} catch {
+		return undefined
+	}
+}
+
+function read(lane_directory: string): SupervisorOwner | undefined {
+	return parsed_stamp(marker_path(lane_directory), owner_schema)
+}
+
+function read_state(lane_directory: string, nonce: string): SupervisorState | undefined {
+	const state = parsed_stamp(state_path(lane_directory), state_schema)
+
+	return state?.owner_nonce === nonce ? state : undefined
+}
+
+function is_live(owner: SupervisorOwner): boolean {
+	return process_identity.is_same_process(owner.pid, owner.process_start) !== false
+}
+
+function active(lane_directory: string): SupervisorOwner | undefined {
+	const owner = read(lane_directory)
+
+	return owner !== undefined && is_live(owner) ? owner : undefined
+}
+
+async function wait_for_active(lane_directory: string): Promise<SupervisorOwner | undefined> {
+	for (let attempt = 0; attempt < CLAIM_POLL_LIMIT; attempt += 1) {
+		const owner = active(lane_directory)
+		if (owner !== undefined) return owner
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
+		await new Promise((resolve) => setTimeout(resolve, CLAIM_POLL_MS))
+	}
+
+	return undefined
+}
+
+// The hard link snapshots the exact owner inode. Several contenders may snapshot one stale owner,
+// but only one can unlink it; a contender arriving after a replacement sees different inodes and
+// cannot remove the new live owner.
+function remove_if_unchanged(target: string): void {
+	const snapshot = `${target}.${String(process.pid)}.${randomUUID()}`
+
+	try {
+		linkSync(target, snapshot)
+		const current = statSync(target)
+		const linked = statSync(snapshot)
+		if (current.dev === linked.dev && current.ino === linked.ino) unlinkSync(target)
+	} catch {
+		/* absence or replacement is resolved by the exclusive create below */
+	} finally {
+		stamp_file.remove_stamp(snapshot)
+	}
+}
+
+interface ChildIdentity {
+	pid: number
+	process_start?: string
+}
+
+function live_child(state: SupervisorState | undefined): ChildIdentity | undefined {
+	if (state?.child_pid === undefined) return undefined
+	const { child_pid, child_process_start } = state
+
+	if (process_identity.is_same_process(child_pid, child_process_start) === false) return undefined
+
+	return {
+		pid: child_pid,
+		...(child_process_start !== undefined && { process_start: child_process_start }),
+	}
+}
+
+function carried_child(
+	lane_directory: string,
+	owner: SupervisorOwner | undefined,
+): ChildIdentity | undefined {
+	if (owner === undefined) return undefined
+
+	return live_child(read_state(lane_directory, owner.nonce))
+}
+
+function remove_stale_owner(target: string, previous: SupervisorOwner | undefined): boolean {
+	if (previous !== undefined && is_live(previous)) return false
+	if (stamp_file.read_stamp_text(target) !== undefined) remove_if_unchanged(target)
+
+	return true
+}
+
+function claim(issue: string, lane_directory: string, nonce: string): SupervisorOwner | undefined {
+	const target = marker_path(lane_directory)
+	const previous = read(lane_directory)
+	if (!remove_stale_owner(target, previous)) return undefined
+	const child = carried_child(lane_directory, previous)
+	const owner = { issue, nonce, ...process_identity.own_fields() }
+	if (!stamp_file.create_stamp(target, owner)) return undefined
+	stamp_file.replace_stamp(state_path(lane_directory), {
+		owner_nonce: nonce,
+		epoch: 0,
+		...(child !== undefined && {
+			child_pid: child.pid,
+			...(child.process_start !== undefined && {
+				child_process_start: child.process_start,
+			}),
+		}),
+	})
+
+	return owner
+}
+
+function update(lane_directory: string, owner: SupervisorOwner, state: SupervisorState): void {
+	if (read(lane_directory)?.nonce !== owner.nonce) return
+	stamp_file.replace_stamp(state_path(lane_directory), state)
+}
+
+function release(lane_directory: string, nonce: string): void {
+	if (read(lane_directory)?.nonce !== nonce) return
+	stamp_file.remove_stamp(state_path(lane_directory))
+	stamp_file.remove_stamp(marker_path(lane_directory))
+	openai_lane_supervisor_decision.remove(lane_directory, nonce)
+}
+
+const openai_lane_supervisor_owner = {
+	active,
+	claim,
+	marker_path,
+	read_state,
+	release,
+	state_path,
+	update,
+	wait_for_active,
+}
+
+export { openai_lane_supervisor_owner, type SupervisorOwner }

package/scripts/lane/openai-lane-supervisor.ts

@@ -1,180 +1,22 @@
 import { randomUUID } from 'node:crypto'
-import { linkSync, statSync, unlinkSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { agent_argv } from '#scripts/agent/agent-argv'
 import type { AgentProfile } from '#scripts/agent/agent-role-profile'
 import { process_identity } from '#scripts/josh/process-identity'
-import { process_owner_schema } from '#scripts/josh/process-owner'
-import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_cut, type RunCut } from '#scripts/run/cut/run-cut'
 import { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
-import { run_cut, type RunCut } from '#scripts/run/run-cut'
-import { z } from 'zod'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import { lane_dispatch_log } from './lane-dispatch-log'
 import type { LaneInfo } from './lane-registry'
 import { openai_lane_ship } from './openai-lane-ship'
 import { openai_lane_supervisor_decision } from './openai-lane-supervisor-decision'
+import { openai_lane_supervisor_owner, type SupervisorOwner } from './openai-lane-supervisor-owner'
 import { openai_review_broker } from './openai-review-broker'
 
-const OWNER_PREFIX = 'josh-openai-lane-supervisor-'
-const STATE_PREFIX = 'josh-openai-lane-supervisor-state-'
+const { claim, read_state, release, update } = openai_lane_supervisor_owner
 const CHILD_POLL_MS = 250
-const CLAIM_POLL_MS = 50
-const CLAIM_POLL_LIMIT = 40
 const SUPERVISOR_SCRIPT = fileURLToPath(new URL('openai-lane-supervisor-cli.ts', import.meta.url))
-// The shared owner pair, with the pid narrowed: this record is written only by a live supervisor, so a
-// pid that is not a real one marks it as corrupt rather than as a dead owner.
-const owner_schema = process_owner_schema.extend({
-	issue: z.string(),
-	nonce: z.string(),
-	pid: z.number().int().positive(),
-})
-const state_schema = z.object({
-	owner_nonce: z.string(),
-	child_pid: z.number().int().positive().optional(),
-	child_process_start: z.string().optional(),
-	epoch: z.number().int().nonnegative(),
-})
-
-type SupervisorOwner = z.infer<typeof owner_schema>
-type SupervisorState = z.infer<typeof state_schema>
-
-function marker_path(lane_directory: string): string {
-	return stamp_file.stamp_path(OWNER_PREFIX, lane_directory)
-}
-
-function state_path(lane_directory: string): string {
-	return stamp_file.stamp_path(STATE_PREFIX, lane_directory)
-}
-
-function parsed_stamp<T>(target: string, schema: z.ZodType<T>): T | undefined {
-	try {
-		const value: unknown = JSON.parse(stamp_file.read_stamp_text(target) ?? '')
-		const parsed = schema.safeParse(value)
-
-		return parsed.success ? parsed.data : undefined
-	} catch {
-		return undefined
-	}
-}
-
-function read(lane_directory: string): SupervisorOwner | undefined {
-	return parsed_stamp(marker_path(lane_directory), owner_schema)
-}
-
-function read_state(lane_directory: string, nonce: string): SupervisorState | undefined {
-	const state = parsed_stamp(state_path(lane_directory), state_schema)
-
-	return state?.owner_nonce === nonce ? state : undefined
-}
-
-function is_live(owner: SupervisorOwner): boolean {
-	return process_identity.is_same_process(owner.pid, owner.process_start) !== false
-}
-
-function active(lane_directory: string): SupervisorOwner | undefined {
-	const owner = read(lane_directory)
-
-	return owner !== undefined && is_live(owner) ? owner : undefined
-}
-
-async function wait_for_active(lane_directory: string): Promise<SupervisorOwner | undefined> {
-	for (let attempt = 0; attempt < CLAIM_POLL_LIMIT; attempt += 1) {
-		const owner = active(lane_directory)
-		if (owner !== undefined) return owner
-		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
-		await new Promise((resolve) => setTimeout(resolve, CLAIM_POLL_MS))
-	}
-
-	return undefined
-}
-
-// The hard link snapshots the exact owner inode. Several contenders may snapshot one stale owner,
-// but only one can unlink it; a contender arriving after a replacement sees different inodes and
-// cannot remove the new live owner.
-function remove_if_unchanged(target: string): void {
-	const snapshot = `${target}.${String(process.pid)}.${randomUUID()}`
-
-	try {
-		linkSync(target, snapshot)
-		const current = statSync(target)
-		const linked = statSync(snapshot)
-		if (current.dev === linked.dev && current.ino === linked.ino) unlinkSync(target)
-	} catch {
-		/* absence or replacement is resolved by the exclusive create below */
-	} finally {
-		stamp_file.remove_stamp(snapshot)
-	}
-}
-
-interface ChildIdentity {
-	pid: number
-	process_start?: string
-}
-
-function live_child(state: SupervisorState | undefined): ChildIdentity | undefined {
-	if (state?.child_pid === undefined) return undefined
-	const { child_pid, child_process_start } = state
-
-	if (process_identity.is_same_process(child_pid, child_process_start) === false) {
-		return undefined
-	}
-
-	return {
-		pid: child_pid,
-		...(child_process_start !== undefined && { process_start: child_process_start }),
-	}
-}
-
-function carried_child(
-	lane_directory: string,
-	owner: SupervisorOwner | undefined,
-): ChildIdentity | undefined {
-	if (owner === undefined) return undefined
-
-	return live_child(read_state(lane_directory, owner.nonce))
-}
-
-function remove_stale_owner(target: string, previous: SupervisorOwner | undefined): boolean {
-	if (previous !== undefined && is_live(previous)) return false
-	if (stamp_file.read_stamp_text(target) !== undefined) remove_if_unchanged(target)
-
-	return true
-}
-
-function claim(issue: string, lane_directory: string, nonce: string): SupervisorOwner | undefined {
-	const target = marker_path(lane_directory)
-	const previous = read(lane_directory)
-	if (!remove_stale_owner(target, previous)) return undefined
-	const child = carried_child(lane_directory, previous)
-	const owner = { issue, nonce, ...process_identity.own_fields() }
-	if (!stamp_file.create_stamp(target, owner)) return undefined
-	stamp_file.replace_stamp(state_path(lane_directory), {
-		owner_nonce: nonce,
-		epoch: 0,
-		...(child !== undefined && {
-			child_pid: child.pid,
-			...(child.process_start !== undefined && {
-				child_process_start: child.process_start,
-			}),
-		}),
-	})
-
-	return owner
-}
-
-function update(lane_directory: string, owner: SupervisorOwner, state: SupervisorState): void {
-	if (read(lane_directory)?.nonce !== owner.nonce) return
-	stamp_file.replace_stamp(state_path(lane_directory), state)
-}
-
-function release(lane_directory: string, nonce: string): void {
-	if (read(lane_directory)?.nonce !== nonce) return
-	stamp_file.remove_stamp(state_path(lane_directory))
-	stamp_file.remove_stamp(marker_path(lane_directory))
-	openai_lane_supervisor_decision.remove(lane_directory, nonce)
-}
 
 function handed_off(cut: RunCut | undefined, issue: string): boolean {
 	return (
@@ -350,17 +192,17 @@ function supervisor_argv(issue: string, nonce: string): LaunchArgv {
 }
 
 const openai_lane_supervisor = {
-	active,
+	active: openai_lane_supervisor_owner.active,
 	approve: openai_lane_supervisor_decision.approve,
 	cancel: openai_lane_supervisor_decision.cancel,
 	claim,
-	marker_path,
+	marker_path: openai_lane_supervisor_owner.marker_path,
 	new_nonce: randomUUID,
 	release,
-	state_path,
+	state_path: openai_lane_supervisor_owner.state_path,
 	supervise,
 	supervisor_argv,
-	wait_for_active,
+	wait_for_active: openai_lane_supervisor_owner.wait_for_active,
 }
 
 export { openai_lane_supervisor }

package/scripts/lane/openai-review-broker.ts

@@ -8,7 +8,7 @@ import { git_common_directory } from '#scripts/git/git-common-directory'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { error_text } from '#scripts/lib/error-message'
 import { detached_launch } from '#scripts/run/detached-launch'
-import { run_ship_review } from '#scripts/run/run-ship-review'
+import { run_ship_review } from '#scripts/run/ship/run-ship-review'
 import { z } from 'zod'
 import type { LaneInfo } from './lane-registry'
 
@@ -249,9 +249,7 @@ async function request(directory: string, issue: string, round: ReviewRound): Pr
 	if (target === undefined) return false
 	const response = read_record(target, response_schema)
 
-	if (response === undefined || !is_live_response(response, response.session)) {
-		return false
-	}
+	if (response === undefined || !is_live_response(response, response.session)) return false
 
 	const nonce = randomUUID()
 	const body: ReviewRequest = { session: response.session, nonce, round }

package/scripts/lib/ancestor-directories.ts

@@ -0,0 +1,35 @@
+import path from 'node:path'
+
+// One parent-directory walk, in one place (joshuafolkken/kit#3260). Five modules had each written
+// their own — the josh package-root lookup, the gate's project root, the effective-upstream version
+// read, the local-bin shim search and the progress-interval read — and they had drifted to three
+// different stop conditions. The walk stops at the filesystem root (where `dirname` answers itself)
+// or at the first match, and is bounded so a path that never reaches a root — a broken mount, a
+// mocked `dirname` — cannot spin.
+const MAX_DEPTH = 64
+
+// The directory itself and each of its ancestors up to the filesystem root, nearest-first.
+function list(start_directory: string): ReadonlyArray<string> {
+	const directories: Array<string> = []
+	let current = path.resolve(start_directory)
+
+	while (directories.length < MAX_DEPTH && !directories.includes(current)) {
+		directories.push(current)
+		current = path.dirname(current)
+	}
+
+	return directories
+}
+
+// The nearest directory, the start included, that `is_match` accepts — undefined when the walk
+// reaches the root without one.
+function nearest(
+	start_directory: string,
+	is_match: (directory: string) => boolean,
+): string | undefined {
+	return list(start_directory).find((directory) => is_match(directory))
+}
+
+const ancestor_directories = { list, nearest }
+
+export { ancestor_directories }

package/scripts/lib/animation-helpers.ts

@@ -6,8 +6,8 @@ interface AnimationOptions<T> {
 	result_formatter?: (result: T) => string
 }
 
-function get_error_message(error_message: string | undefined): string {
-	return error_message ?? 'Operation failed'
+function get_error_message(error_message: string | undefined = 'Operation failed'): string {
+	return error_message
 }
 
 function get_display_result<T>(result: T, formatter?: (result: T) => string): string {

package/scripts/lib/buffered-process.ts

@@ -1,4 +1,5 @@
 import { execa } from 'execa'
+import { SUITE_TIMEOUT_MS } from './timeouts'
 
 // One definition of "run a check, keep its output, never throw".
 //
@@ -12,11 +13,6 @@ import { execa } from 'execa'
 const PNPM = 'pnpm'
 const FORCE_COLOR = '1'
 const FAIL_EXIT_CODE = 1
-// Long enough for a cold unit suite on a large consumer, short enough that a check which never
-// exits ends the run instead of holding it open with nothing printed — the same hazard
-// `propagate-steps.ts` bounds with its own step timeout. Because output is buffered until the
-// child finishes, a hung child shows nothing at all until this fires.
-const PROCESS_TIMEOUT_MS = 1_800_000
 
 interface BufferedProcessResult {
 	output: string
@@ -60,7 +56,7 @@ async function run_buffered_process(
 		all: true,
 		reject: false,
 		...(options.cwd !== undefined && { cwd: options.cwd }),
-		timeout: options.timeout_ms ?? PROCESS_TIMEOUT_MS,
+		timeout: options.timeout_ms ?? SUITE_TIMEOUT_MS,
 	})
 
 	return {
@@ -79,4 +75,4 @@ function is_process_failed(result: Pick<BufferedProcessResult, 'exit_code'>): bo
 const buffered_process = { is_process_failed, run_buffered_process }
 
 export type { BufferedProcessResult }
-export { buffered_process, FAIL_EXIT_CODE, PROCESS_TIMEOUT_MS }
+export { buffered_process, FAIL_EXIT_CODE }

package/scripts/lib/cli-flags.ts

@@ -61,6 +61,76 @@ function string_of(value: unknown): string | undefined {
 	return typeof value === 'string' ? value : undefined
 }
 
-const cli_flags = { refuse_unknown_flags, parse_or_undefined, values_of, arguments_of, string_of }
+const LONG_FLAG_PREFIX = '--'
+const SHORT_FLAG_PREFIX = '-'
+
+// The key `parseArgs` files a `--long-flag` under.
+function option_name(flag: string): string {
+	return flag.slice(LONG_FLAG_PREFIX.length)
+}
+
+// `parseArgs`'s own rule for a value it calls ambiguous: a dash and more. A lone `-` is a value — the
+// stdin spelling `--body-file -` and `--decision-file -` rely on.
+function is_unusable_value(value: string | boolean): boolean {
+	if (typeof value === 'boolean' || value.length === 0) return true
+
+	return value !== SHORT_FLAG_PREFIX && value.startsWith(SHORT_FLAG_PREFIX)
+}
+
+// Every value one value-taking flag was given, `true` standing for one given none. Read leniently, so an
+// unknown flag elsewhere on the line does not hide the answer: a strict read only answers `undefined`
+// for the whole line, and this is what lets a command name the one flag that went wrong.
+function given_values(argv: ReadonlyArray<string>, flag: string): ReadonlyArray<string | boolean> {
+	const name = option_name(flag)
+	const given = parse_or_undefined({
+		args: [...argv],
+		options: { [name]: { type: 'string', multiple: true } },
+		strict: false,
+		allowPositionals: true,
+	})?.values[name]
+
+	return Array.isArray(given) ? given : []
+}
+
+// Whether a value-taking flag was given without a usable value — last on the line, followed by
+// another flag, or empty — so a command can say which value a shell ate rather than print its
+// generic usage.
+function is_value_unusable(argv: ReadonlyArray<string>, flag: string): boolean {
+	return given_values(argv, flag).some((value) => is_unusable_value(value))
+}
+
+function attach_one(attached: Array<string>, argument: string, flags: ReadonlyArray<string>): void {
+	const previous = attached.at(-1)
+
+	if (previous !== undefined && flags.includes(previous)) {
+		attached[attached.length - 1] = `${previous}=${argument}`
+	} else attached.push(argument)
+}
+
+// Joins each listed free-text flag to the token after it (`--body -x` → `--body=-x`), so a value that
+// opens with a dash — a Markdown bullet — reaches the command instead of being refused by `parseArgs` as
+// ambiguous. Only the listed flags are joined: anywhere else a dash-led token is still the next flag.
+function attach_values(
+	argv: ReadonlyArray<string>,
+	flags: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+	const attached: Array<string> = []
+
+	for (const argument of argv) attach_one(attached, argument, flags)
+
+	return attached
+}
+
+const cli_flags = {
+	attach_values,
+	refuse_unknown_flags,
+	parse_or_undefined,
+	values_of,
+	arguments_of,
+	string_of,
+	option_name,
+	given_values,
+	is_value_unusable,
+}
 
 export { cli_flags }

package/scripts/lib/spawn-exit.ts

@@ -26,13 +26,13 @@ function resolve_spawn_exit(executable: string, result: SpawnResult): number {
 // covers for `exitCode`. Reading it through a signature that admits the real shape keeps the guard
 // honest: a plain `result.stdout ?? ''` is reported as an unnecessary condition against the lying
 // type, and dereferencing it unguarded crashes the caller.
-function read_spawn_stdout(result: { stdout?: string }): string {
+function read_spawn_stdout(result: { stdout?: string | undefined }): string {
 	return result.stdout ?? ''
 }
 
 // Same declared-vs-actual gap as `read_spawn_stdout`, for the stream that carries git's and gh's
 // failure messages.
-function read_spawn_stderr(result: { stderr?: string }): string {
+function read_spawn_stderr(result: { stderr?: string | undefined }): string {
 	return result.stderr ?? ''
 }
 

package/scripts/lib/timeouts.ts

@@ -3,11 +3,44 @@
 // limit stays stuck where it stopped and never comes back (joshuafolkken/kit#2981), so every such
 // call takes one of these, and a value used in more than one place is named once here.
 
+// A probe that only asks the local machine (`ps`, `lsof`, `git config`) on a path something else is
+// waiting on. Failing answers "cannot tell", which every caller handles, so anything slower is a fault.
+const PROBE_TIMEOUT_MS = 2000
 // One HTTP request to a registry, an API or a webhook.
 const FETCH_TIMEOUT_MS = 10_000
+// One local `git` command. Generous for a `rev-parse`; a call that talks to a remote needs its own.
+const GIT_TIMEOUT_MS = 10_000
+// A hook's spawned formatter or spell check, which holds the edit's turn open while it runs. Read it
+// against the worst-case run, not one spawn: an edit to a config input plans eslint, prettier and
+// `eslint_d restart`, the first and last each with a second route behind the daemon — five spawns.
+// The hook entry in `.claude/settings.json` declares 90 seconds, so five of these must fit under it,
+// or the harness kill lands at a moment the hook did not choose — possibly inside `prettier --write`,
+// which rewrites in place and can leave the file truncated. 15s × 5 = 75s. It is still two orders of
+// magnitude beyond the 0.84s a warm run takes, so reaching it means something is already wrong.
+const HOOK_PROCESS_TIMEOUT_MS = 15_000
+// One `gh api` read whose answer only shapes a report or a classification.
+const GH_API_TIMEOUT_MS = 20_000
 // A short command that only answers a question (`gh --version`, `pnpm config get`).
 const COMMAND_TIMEOUT_MS = 30_000
-// A `pnpm install`, which can download the whole dependency tree on a cold store.
+// A type-aware ESLint run over a few files. A cold one is seconds; this is two orders beyond that.
+const LINT_TIMEOUT_MS = 180_000
+// A `pnpm install` or a global install, which can download the whole dependency tree on a cold
+// store. Ten minutes covers that fetch and still ends the command when a registry never answers. It
+// is well under `SUITE_TIMEOUT_MS` because it blocks a command a person is waiting on.
 const INSTALL_TIMEOUT_MS = 600_000
+// A check or step that can run a consumer's full unit suite or a `pnpm add` — long enough for a cold
+// suite on a large consumer, short enough that a hung child ends the run instead of holding it open
+// with nothing printed (buffered output shows nothing at all until this fires).
+const SUITE_TIMEOUT_MS = 1_800_000
 
-export { COMMAND_TIMEOUT_MS, FETCH_TIMEOUT_MS, INSTALL_TIMEOUT_MS }
+export {
+	COMMAND_TIMEOUT_MS,
+	FETCH_TIMEOUT_MS,
+	GH_API_TIMEOUT_MS,
+	GIT_TIMEOUT_MS,
+	HOOK_PROCESS_TIMEOUT_MS,
+	INSTALL_TIMEOUT_MS,
+	LINT_TIMEOUT_MS,
+	PROBE_TIMEOUT_MS,
+	SUITE_TIMEOUT_MS,
+}

package/scripts/lines/line-budget.ts

@@ -3,6 +3,7 @@ import { statSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { LINT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { z } from 'zod'
 import { effective_limit, type LineRuleOptions } from './effective-limit'
@@ -95,9 +96,6 @@ const RULE_FLAG = '--rule'
 const CACHE_PREFIX = 'josh-lines-eslint-cache-'
 const CACHE_LOCATION_FLAG = '--cache-location'
 const CACHE_KEY_LENGTH = 8
-// Bounded so a hung child ends the call rather than holding it open. A cold type-aware lint of a few
-// files is seconds; this is two orders of magnitude beyond that.
-const PROCESS_TIMEOUT_MS = 180_000
 
 // Only the two fields this reads. `ruleId` is nullable on a parse error or an ignore warning, and
 // both of those are answers — "no count for this path" — rather than failures.
@@ -200,7 +198,7 @@ async function run_probe(group: ProbeGroup, project_root: string): Promise<strin
 			reject: false,
 			stdout: 'pipe',
 			stderr: 'ignore',
-			timeout: PROCESS_TIMEOUT_MS,
+			timeout: LINT_TIMEOUT_MS,
 		})
 
 		return result.stdout
@@ -239,9 +237,9 @@ function count_or_zero(
 
 // Keyed by the absolute path eslint reports, so the caller's spelling of a path does not have to
 // match it. A path eslint refused is simply absent, and the caller reports that rather than a number.
-function counts_in(raw_output: string | undefined): ReadonlyMap<string, number> {
+function counts_in(raw_output: string | undefined = 'null'): ReadonlyMap<string, number> {
 	const counts = new Map<string, number>()
-	const parsed = results_schema.safeParse(JSON.parse(raw_output ?? 'null'))
+	const parsed = results_schema.safeParse(JSON.parse(raw_output))
 
 	if (!parsed.success) return counts