@joshuafolkken/kit 1.872.0

package/scripts/lane/lane-await.ts

@@ -0,0 +1,165 @@
+import { spawnSync } from 'node:child_process'
+import { setTimeout as sleep } from 'node:timers/promises'
+import { lane_child_invocation } from './lane-child-invocation'
+
+// Detached lane children are not harness-tracked processes, so their completion fires no
+// re-invocation event in the parent's session. Without a blocking wait the parent notices only
+// on the next heartbeat interval -- up to 15 minutes after the fact in the measured case
+// (joshuafolkken/kit#2113).
+//
+// **The re-confirm delay is the one value the caller must not be left to choose.** A process that
+// disappears briefly and reappears (the pre-gate boundary cut, where one process exits and a
+// resume process takes over in the same lane) looks exactly like a completion to a bare `pgrep`
+// poll. The re-confirm window must be long enough to survive the cut's handoff time and short
+// enough to not add observable delay after a genuine completion. Both constraints are measured
+// rather than guessed and neither belongs in an agent prompt.
+
+const RECONFIRM_MS = 15_000
+const DEFAULT_POLL_MS = 5000
+const NEVER_APPEARED_TIMEOUT_MS = 600_000
+const MS_PER_SECOND = 1000
+const ISSUE_PATTERN = /^[1-9]\d*$/u
+const PROCESS_FOUND = 0
+
+interface AwaitState {
+	appeared: boolean
+	disappeared_at: number | undefined
+	first_polled_at: number | undefined
+}
+
+// Injectable for testing -- the CLI never overrides these.
+interface AwaitOptions {
+	is_running?: (issue: string) => boolean
+	poll_ms?: number
+	reconfirm_ms?: number
+	never_appeared_timeout_ms?: number
+}
+
+interface CheckConfig {
+	is_running: (issue: string) => boolean
+	reconfirm_ms: number
+	never_appeared_timeout_ms: number
+}
+
+interface RunConfig extends CheckConfig {
+	poll_ms: number
+}
+
+function is_process_running_default(issue: string): boolean {
+	const pattern = lane_child_invocation.process_pattern(issue)
+	const result = spawnSync('pgrep', ['-f', pattern], { encoding: 'utf8' })
+
+	return result.status === PROCESS_FOUND
+}
+
+function make_initial_state(): AwaitState {
+	return { appeared: false, disappeared_at: undefined, first_polled_at: undefined }
+}
+
+function make_states(issues: ReadonlyArray<string>): Map<string, AwaitState> {
+	return new Map(issues.map((issue) => [issue, make_initial_state()]))
+}
+
+function resolve_options(options: AwaitOptions): RunConfig {
+	return {
+		is_running: options.is_running ?? is_process_running_default,
+		poll_ms: options.poll_ms ?? DEFAULT_POLL_MS,
+		reconfirm_ms: options.reconfirm_ms ?? RECONFIRM_MS,
+		never_appeared_timeout_ms: options.never_appeared_timeout_ms ?? NEVER_APPEARED_TIMEOUT_MS,
+	}
+}
+
+function update_liveness(state: AwaitState, is_live: boolean): void {
+	if (!is_live) return
+
+	state.appeared = true
+	state.disappeared_at = undefined
+}
+
+// Throws if the issue never appeared within the timeout window; otherwise records the first-seen time.
+function check_not_appeared(
+	issue: string,
+	state: AwaitState,
+	now_ms: number,
+	timeout_ms: number,
+): void {
+	state.first_polled_at ??= now_ms
+	const elapsed_ms = now_ms - state.first_polled_at
+
+	if (elapsed_ms >= timeout_ms) {
+		throw new Error(
+			`lane child ${issue} never appeared within ${String(timeout_ms / MS_PER_SECOND)}s`,
+		)
+	}
+}
+
+// Returns the issue that has confirmed-completed this tick, `undefined` if none yet.
+// The `appeared` guard prevents a process that never showed up from being declared done.
+function check_issue(
+	issue: string,
+	state: AwaitState,
+	now_ms: number,
+	config: CheckConfig,
+): string | undefined {
+	const is_live = config.is_running(issue)
+
+	update_liveness(state, is_live)
+
+	if (is_live) return undefined
+
+	if (!state.appeared) {
+		check_not_appeared(issue, state, now_ms, config.never_appeared_timeout_ms)
+
+		return undefined
+	}
+
+	if (state.disappeared_at === undefined) {
+		state.disappeared_at = now_ms
+
+		return undefined
+	}
+
+	return now_ms - state.disappeared_at >= config.reconfirm_ms ? issue : undefined
+}
+
+function check_any(
+	states: Map<string, AwaitState>,
+	now_ms: number,
+	config: CheckConfig,
+): string | undefined {
+	for (const [issue, state] of states) {
+		const result = check_issue(issue, state, now_ms, config)
+
+		if (result !== undefined) return result
+	}
+
+	return undefined
+}
+
+async function wait_for_any(
+	issues: ReadonlyArray<string>,
+	options: AwaitOptions = {},
+): Promise<string> {
+	const config = resolve_options(options)
+	const states = make_states(issues)
+
+	for (;;) {
+		const completed = check_any(states, Date.now(), config)
+
+		if (completed !== undefined) return completed
+
+		await sleep(config.poll_ms)
+	}
+}
+
+const lane_await = {
+	ISSUE_PATTERN,
+	NEVER_APPEARED_TIMEOUT_MS,
+	RECONFIRM_MS,
+	check_issue,
+	is_process_running_default,
+	wait_for_any,
+}
+
+export type { AwaitState, CheckConfig }
+export { lane_await }

package/scripts/lane/lane-cache-run.ts

@@ -0,0 +1,39 @@
+import path from 'node:path'
+import { lane_cache } from './lane-cache'
+import { lane_registry } from './lane-registry'
+
+async function resolve_main_root(): Promise<string | undefined> {
+	try {
+		return await lane_registry.main_repository_root()
+	} catch {
+		return undefined
+	}
+}
+
+// Each tool owns its cache for exactly its process lifetime (#2060): refresh immediately before it
+// starts and publish in `finally` immediately after it settles. Other gate failures therefore cannot
+// discard completed work, while the main checkout pays no copy or rewrite at all. Root discovery is
+// best-effort too: a consumer outside Git still runs the requested tool without cache sharing.
+async function run<T>(
+	cache_file: string,
+	work: () => Promise<T>,
+	current_root: string = process.cwd(),
+): Promise<T> {
+	const main_root = await resolve_main_root()
+
+	if (main_root === undefined || path.resolve(current_root) === path.resolve(main_root)) {
+		return await work()
+	}
+
+	lane_cache.sync_cache(main_root, current_root, cache_file)
+
+	try {
+		return await work()
+	} finally {
+		lane_cache.sync_cache(current_root, main_root, cache_file)
+	}
+}
+
+const lane_cache_run = { run }
+
+export { lane_cache_run }

package/scripts/lane/lane-cache.ts

@@ -0,0 +1,135 @@
+import { randomUUID } from 'node:crypto'
+import { cpSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { hook_launch } from '#scripts/init/hook-launch'
+import {
+	GATE_CACHE_SPECS,
+	SHARED_CACHE_SPECS,
+	type GateCacheSpec,
+} from '#scripts/josh/josh-command-types'
+
+// Warming a fresh lane's verification caches from the main checkout (joshuafolkken/kit#1849).
+//
+// `git worktree add` writes a checkout and nothing beside it, and the three caches the gate reads —
+// `.eslintcache`, `.tsbuildinfo`, `.cspellcache` — are all git-ignored, so a new lane has none of
+// them and only its *first* `josh gate` runs fully cold (measured at 353.9 s against 27.5 s warm,
+// joshuafolkken/kit#1839). The initial seed warms that run; the per-tool sync below keeps the
+// portable ESLint and CSpell caches current afterwards (#2060).
+//
+// Content hashes make stale entries safe, but do not by themselves make a cache portable (#2060).
+// ESLint keys entries by absolute file path, so its JSON is rebased while cspell's relative keys and
+// TypeScript's build info move raw. The spec in `josh-command-types.ts` is the one declaration of
+// which treatment and which continuous sharing each gate cache receives.
+//
+// **Each tool runs against its lane's own file, never a shared live file.** A completed tool then
+// atomically publishes its whole cache to main; when lanes overlap, the last completion wins as an
+// intentional best-effort policy. ESLint and CSpell keep separate files and separate life cycles, so
+// one tool finishing cannot publish the other's in-progress state.
+//
+// **Warming is best-effort: a lane with a cold cache is still a usable lane.** A cache the main
+// checkout never produced is skipped, and a copy that fails is skipped rather than thrown — so
+// seeding can never be the reason an open fails, unlike the `.env` write the lane cannot run without.
+
+function replace_root(value: unknown, source_prefix: string, destination_root: string): unknown {
+	if (typeof value !== 'string') return value
+
+	if (!value.startsWith(source_prefix)) return value
+
+	return path.join(destination_root, value.slice(source_prefix.length))
+}
+
+function rebase_json(content: string, source_root: string, destination_root: string): string {
+	const parsed: unknown = JSON.parse(content)
+	const source_prefix = `${path.resolve(source_root)}${path.sep}`
+	const resolved_destination = path.resolve(destination_root)
+
+	return JSON.stringify(parsed, function replace_path(_key: string, value: unknown): unknown {
+		return replace_root(value, source_prefix, resolved_destination)
+	})
+}
+
+function portable_content(
+	content: string,
+	spec: GateCacheSpec,
+	source_root: string,
+	destination_root: string,
+): string {
+	if (spec.portability === 'rooted-json') return rebase_json(content, source_root, destination_root)
+
+	JSON.parse(content)
+
+	return content
+}
+
+function write_atomically(destination_path: string, content: string): void {
+	const temporary_path = `${destination_path}.${String(process.pid)}.${randomUUID()}.tmp`
+
+	try {
+		writeFileSync(temporary_path, content, { flag: 'wx' })
+		renameSync(temporary_path, destination_path)
+	} catch {
+		// Best-effort: a cache that could not be published simply leaves the destination unchanged.
+	} finally {
+		rmSync(temporary_path, { force: true })
+	}
+}
+
+function copy_if_present(source_root: string, destination: string, spec: GateCacheSpec): void {
+	const source_path = path.join(source_root, spec.cache_file)
+	if (!existsSync(source_path)) return
+
+	try {
+		const content = portable_content(
+			readFileSync(source_path, 'utf8'),
+			spec,
+			source_root,
+			destination,
+		)
+
+		write_atomically(path.join(destination, spec.cache_file), content)
+	} catch {
+		// A missing, changing, or malformed cache is a miss, never a failed lane or gate.
+	}
+}
+
+/**
+ * Copy the gate's verification caches from `source_root` into `destination`, skipping any the
+ * source does not have. Warming is best-effort and never throws.
+ */
+function seed_caches(source_root: string, destination: string): void {
+	for (const spec of GATE_CACHE_SPECS) copy_if_present(source_root, destination, spec)
+}
+
+/**
+ * Copy the pre-built hook bundles (`dist/hooks/`) from `source_root` into `destination`, so a fresh
+ * lane's child runs each Claude Code hook off `node dist/hooks/<name>.js` rather than the slower
+ * `pnpm josh …` fallback (joshuafolkken/kit#2160). The bundles are git-ignored, so a lane's work tree
+ * never carries them and every hook falls back without this seed.
+ *
+ * Best-effort, exactly like `seed_caches`: a source with no bundles (a checkout that never ran
+ * `pnpm build`) is skipped so the lane opens on the fallback path, and a copy that fails is swallowed
+ * rather than thrown — seeding is never the reason an open fails.
+ */
+function seed_hook_bundles(source_root: string, destination: string): void {
+	const source = path.join(source_root, hook_launch.HOOK_DIST_DIR)
+	if (!existsSync(source)) return
+
+	try {
+		cpSync(source, path.join(destination, hook_launch.HOOK_DIST_DIR), { recursive: true })
+	} catch {
+		// A source that vanished mid-copy or a destination that could not be written leaves the lane on
+		// the `pnpm josh` fallback, never a failed open.
+	}
+}
+
+function sync_cache(source_root: string, destination: string, cache_file: string): void {
+	const spec = SHARED_CACHE_SPECS.find((candidate) => candidate.cache_file === cache_file)
+
+	if (spec === undefined) return
+
+	copy_if_present(source_root, destination, spec)
+}
+
+const lane_cache = { seed_caches, seed_hook_bundles, sync_cache }
+
+export { lane_cache }

package/scripts/lane/lane-capacity.ts

@@ -0,0 +1,69 @@
+import type { LaneEnvironment } from './lane-paths'
+
+// How many lanes one repository may run at once, and how many of them are free
+// (joshuafolkken/kit#1491).
+//
+// **Nothing here knows what a lane holds.** The limit is a number, the occupancy is a number, and
+// the answer is a number — so the same pool serves an epic's children, several epics' children at
+// once, or anything else a scheduler decides to put in a lane. Threading an epic through this module
+// is what would have to be undone the first time two epics run together, and the whole reason
+// joshuafolkken/kit#1491 built the scheduler epic-free from the start.
+//
+// **It is a ceiling, not a prediction.** Six lanes does not say six children will run at once; it
+// says a seventh will not start. What actually runs is bounded by what is runnable, by the port
+// seats `lane-seed.ts` can allocate, and by the machine.
+
+// Six rather than the nine seats `lane_seed_policy` can allocate: the seats are the hard structural
+// bound, this is the one a person tunes, and leaving headroom between them means raising the limit
+// never lands on "the ports ran out" as its first symptom.
+const DEFAULT_LANE_LIMIT = 6
+const LANE_LIMIT_KEY = 'JOSH_LANE_LIMIT'
+const POSITIVE_INTEGER = /^[1-9]\d*$/u
+const NO_LANES = 0
+
+// The limit, or why it could not be read. A problem rather than a throw, for the reason
+// `eval-runner.ts` records for `JOSH_EVAL_CONCURRENCY`: the caller decides whether a bad setting
+// ends the command or is reported and worked around, and only it knows which.
+type LimitChoice = { kind: 'limit'; limit: number } | { kind: 'problem'; problem: string }
+
+// **An invalid value is a hard error, never a silent fall back to the default** — the rule
+// `PORT_SEED` already holds to. A typo that quietly becomes 6 is a limit nobody set, and the whole
+// point of the setting is that the number is the one a person chose.
+//
+// Blank is unset, not invalid: an `.env` line left as `JOSH_LANE_LIMIT=` is a variable nobody
+// configured, exactly as `lane_paths.lane_root` reads a blank root.
+function read_limit(raw: string | undefined): LimitChoice {
+	const trimmed = raw?.trim() ?? ''
+
+	if (trimmed === '') return { kind: 'limit', limit: DEFAULT_LANE_LIMIT }
+
+	if (!POSITIVE_INTEGER.test(trimmed)) {
+		return {
+			kind: 'problem',
+			problem: `${LANE_LIMIT_KEY} must be a positive integer, not "${trimmed}"`,
+		}
+	}
+
+	return { kind: 'limit', limit: Number(trimmed) }
+}
+
+function lane_limit(environment: LaneEnvironment = process.env): LimitChoice {
+	return read_limit(environment[LANE_LIMIT_KEY])
+}
+
+// Never negative: a repository holding more `in-progress` issues than the limit allows — the limit
+// was lowered, or a stale label outlived its run — has no free lane, and a negative count read as
+// "how many to offer" would be a slice nobody meant.
+function free_lanes(limit: number, occupied: number): number {
+	return Math.max(NO_LANES, limit - occupied)
+}
+
+const lane_capacity = {
+	DEFAULT_LANE_LIMIT,
+	LANE_LIMIT_KEY,
+	read_limit,
+	lane_limit,
+	free_lanes,
+}
+
+export { lane_capacity }

package/scripts/lane/lane-child-invocation.ts

@@ -0,0 +1,73 @@
+import { run_issue_number } from '#scripts/run/run-issue-number'
+
+const CHILD_INVOCATION = 'fullrun'
+const RESUME_GUIDE = '.claude/skills/workflow-commands/pre-gate-cut.md'
+// What a detached `josh ship --detach` supervisor's command line carries (joshuafolkken/kit#2428). It ends
+// with the `"<title> #<N>"` title on purpose, so the liveness pattern below finds it by the same trailing
+// anchor it finds a child by. **The script path alone is not enough**: where the dispatcher is TypeScript
+// (kit itself) `josh ship` runs in-process, so no process ever carries `run-ship-cli.ts` — the `pnpm josh
+// ship …` process and the `josh.ts ship …` / `josh.js ship …` dispatcher are what `pgrep` sees there.
+const SHIP_PROCESS = String.raw`(josh(\.[jt]s)? ship|run-ship-cli\.ts)`
+
+function child_invocation(issue: string): string {
+	run_issue_number.require_issue_number(issue)
+
+	return `${CHILD_INVOCATION} #${issue}`
+}
+
+// The `pgrep -f` pattern that finds a running child: the invocation is always the last argument of
+// its command line — the resume prompts below end with it on purpose — so the anchor matches every
+// launch of `#<N>` and never `#<N>0` (joshuafolkken/kit#2421).
+//
+// **A detached ship supervisor counts as the child** (joshuafolkken/kit#2428). The agent ends once it has
+// handed the post-implementation region to `josh ship --detach`, and the parent books a lane whose
+// pattern stopped matching as finished — parking an issue that was still shipping. The supervisor's
+// command line ends with its `#<N>` title, so the one extended pattern covers both, and the wait, the
+// liveness read and the reaper keep searching with a single pattern.
+function process_pattern(issue: string): string {
+	run_issue_number.require_issue_number(issue)
+
+	return `(${CHILD_INVOCATION}|${SHIP_PROCESS} .*) #${issue}$`
+}
+
+function resume_invocation(issue: string): string {
+	const preamble = `Resuming the lane child for issue #${issue} — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Run \`pnpm josh run:cut --resume ${issue}\` before anything else and follow the matching verdict in ${RESUME_GUIDE}: \`resume\` goes to the gate, \`resume-impl\` continues implementation. Only on \`fresh\` proceed as an ordinary`
+
+	return `${preamble} ${child_invocation(issue)}`
+}
+
+// The prompt an `outage` re-dispatch gives a resumed child (joshuafolkken/kit#2317). Its session was
+// relaunched with `--resume`, so its full context is already loaded — the preamble tells it not to
+// re-read the entry documents and to find where it stopped with `run:step`, redoing only the last
+// action if it did not complete.
+//
+// **It ends with `child_invocation` on purpose, not as decoration** — for the same reason
+// `resume_invocation` does: the parent's liveness poll is `pgrep -laf "<invocation>$"`, so the trailing
+// `fullrun #<N>` keeps the relaunched process matching, and it is the ordinary run the child carries on.
+function outage_resume_invocation(issue: string): string {
+	const preamble = `Resuming the lane child for issue #${issue} after an API disconnection — your session was restored with its full context, so do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Continue the run from where it stopped: run \`pnpm josh run:step ${issue}\` to find the next action, redoing only the last step if it did not complete.`
+
+	return `${preamble} ${child_invocation(issue)}`
+}
+
+// The prompt a lane child is relaunched with when its detached ship supervisor stopped at a failed
+// stage (joshuafolkken/kit#2428) — a red gate, a High/Medium review, a failed push or red CI. The agent
+// ended at the hand-off, so this is how control comes back to one: it reads the stopped report through
+// the command `run:step` names, fixes it and hands the region back. It ends with `child_invocation` for
+// the reason `resume_invocation` does — the parent's poll keeps matching the relaunched process.
+function ship_stop_invocation(issue: string): string {
+	const preamble = `Resuming the lane child for issue #${issue} after its detached ship supervisor stopped at a failed stage — do not re-read the workflow-commands entry documents (SKILL.md, fullrun.md). Run \`pnpm josh run:step ${issue}\` and read the stopped report it names, fix what stopped the ship, then hand the region back per chain-rule.md. Do not re-plan or re-implement what is already on the branch.`
+
+	return `${preamble} ${child_invocation(issue)}`
+}
+
+const lane_child_invocation = {
+	CHILD_INVOCATION,
+	child_invocation,
+	outage_resume_invocation,
+	process_pattern,
+	resume_invocation,
+	ship_stop_invocation,
+}
+
+export { lane_child_invocation }

package/scripts/lane/lane-child-marker.ts

@@ -0,0 +1,58 @@
+import { run_issue_number } from '#scripts/run/run-issue-number'
+import { lane_paths } from './lane-paths'
+
+// The mark a dispatched lane child carries, so the pre-gate cut and a resume are decided from the
+// environment rather than from the model's reading of the prompt (joshuafolkken/kit#1904).
+//
+// **A dispatched child used to be indistinguishable from a person's own session.** `lane:dispatch`
+// and the `run:cut` relaunch both start the child with `claude -p "fullrun #<N>"` and a copied
+// environment, and nothing in the argv, the environment or a file said "this session was launched, not
+// typed". So `pre-gate-cut.ts` left the human-or-child question to the model, which read its own prompt
+// and — across the six children joshuafolkken/kit#1850 measured — decided "person" every time and
+// declined the cut. This variable is that missing fact, made mechanical.
+//
+// **Its value is the issue number, because a mark that only said "a child" could not be told from one
+// that leaked.** A person's shell, or a parent session that was itself a dispatched child, can carry
+// this variable into a checkout it does not belong to; `marked_issue` is trusted only where its value
+// equals the lane's own issue, so a leaked mark for another issue is read as absent. The name, the
+// meaning and the lifetime are documented once in
+// `.claude/skills/workflow-commands/pre-gate-cut.md`.
+const KEY = 'JOSH_LANE_CHILD'
+
+type MarkerSource = Readonly<Record<string, string | undefined>>
+
+// The environment fragment that marks a child dispatched for `#<issue>`. Composed from a digits-only
+// issue number rather than from text read anywhere — the same discipline `lane-dispatch.ts` applies to
+// the invocation it builds — so a malformed number fails here rather than reaching a child.
+function environment_for(issue: string): Record<string, string> {
+	run_issue_number.require_issue_number(issue)
+
+	return { [KEY]: issue }
+}
+
+// The issue a child was dispatched for, or `undefined` when the mark is absent or malformed. A blank
+// or non-numeric value is read as absent rather than trusted, so neither a leaked variable nor a
+// hand-set one can stand in for a real dispatch.
+function marked_issue(source: MarkerSource = process.env): string | undefined {
+	const value = source[KEY]
+
+	if (value === undefined) return undefined
+
+	return run_issue_number.ISSUE_NUMBER_PATTERN.test(value) ? value : undefined
+}
+
+// True when this session is a dispatched lane child for the checkout it is running in: the mark is
+// present and names this lane's own issue, read from the checkout path. A numeric mark naming a
+// *different* issue leaked in from a parent session into a checkout it does not belong to, so it is
+// read as a person's run — the trust condition the header describes, applied the same way
+// `pre-gate-cut.ts` applies it to the resume decision (joshuafolkken/kit#1947).
+function is_child_of(directory: string, source: MarkerSource = process.env): boolean {
+	const marked = marked_issue(source)
+
+	return marked !== undefined && marked === lane_paths.lane_issue_of(directory, { ...source })
+}
+
+const lane_child_marker = { KEY, env_for: environment_for, is_child_of, marked_issue }
+
+export type { MarkerSource }
+export { lane_child_marker }