@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/scripts/issue/issue-watch.ts

@@ -0,0 +1,240 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_conditional } from '#scripts/gh/git-gh-conditional'
+import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
+import { git_command } from '#scripts/git/git-command'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { issue_watch_diff, type WatchSnapshot } from './issue-watch-diff'
+
+// The record of what a run last read of its issue, and the poll that compares the issue against it.
+//
+// **The baseline is written where the run reads the issue** — `josh run:entry`, which prints the body
+// and every comment — so it is the same for a dispatched lane child and a `fullrun` in a person's own
+// checkout, and a resume that prints nothing keeps the baseline it had. One record per checkout,
+// keyed on its root like the review attestation, carries the issue number, so the hook needs no other
+// way to learn which issue the session works on.
+//
+// **A poll is a conditional request.** The issue object's ETag changes with its body and with its
+// comment count, so a 304 there means neither moved and the comments are not read at all.
+
+const RECORD_PREFIX = 'josh-issue-watch-'
+const CLOSED_STATE = 'closed'
+
+const record_schema = z.object({
+	issue: z.string(),
+	body: z.string(),
+	last_comment_id: z.number(),
+	acknowledged_at: z.string(),
+	checked_at: z.string(),
+	etag: z.string().optional(),
+	pending: z.string().optional(),
+	shown: z.string().optional(),
+})
+
+const issue_schema = z.looseObject({ body: z.string().nullish(), state: z.string() })
+
+type WatchRecord = z.infer<typeof record_schema>
+
+type Fetched =
+	| { kind: 'unchanged' }
+	| { kind: 'unreadable' }
+	| { kind: 'closed' }
+	| { kind: 'read'; snapshot: WatchSnapshot; etag: string | undefined }
+
+const UNREADABLE: Fetched = { kind: 'unreadable' }
+
+function record_path(root: string = PROJECT_ROOT): string {
+	return stamp_file.stamp_path(RECORD_PREFIX, root)
+}
+
+function read_record(root?: string): WatchRecord | undefined {
+	const raw = stamp_file.read_stamp_text(record_path(root))
+
+	return raw === undefined ? undefined : json_value.parse_with(raw, record_schema)
+}
+
+function write_record(record: WatchRecord, root?: string): WatchRecord {
+	stamp_file.replace_stamp(record_path(root), record)
+
+	return record
+}
+
+function clear(root?: string): void {
+	stamp_file.remove_stamp(record_path(root))
+}
+
+interface FetchRequest {
+	issue: string
+	etag?: string | undefined
+	timeout_ms?: number | undefined
+}
+
+async function read_snapshot(
+	request: FetchRequest,
+	body: string,
+	etag: string | undefined,
+): Promise<Fetched> {
+	const comments = issue_watch_diff.parse_comments(
+		await git_gh_issue_read.issue_list_comments(request.issue, request.timeout_ms),
+	)
+
+	return comments === undefined ? UNREADABLE : { kind: 'read', snapshot: { body, comments }, etag }
+}
+
+async function fetch_issue(request: FetchRequest): Promise<Fetched> {
+	const read = await git_gh_conditional.read_conditional(
+		git_gh_api_path.issue_api_path(request.issue),
+		request.etag,
+		request.timeout_ms,
+	)
+
+	if (read.kind !== 'changed') return read
+
+	const fields = json_value.parse_with(read.body, issue_schema)
+
+	if (fields === undefined) return UNREADABLE
+	if (fields.state === CLOSED_STATE) return { kind: 'closed' }
+
+	return await read_snapshot(request, fields.body ?? '', read.etag)
+}
+
+// `acknowledged_at` is when a person's update was last taken in — the baseline's own read, or an
+// acknowledgement that had something to take in. The review attestation compares it with the brief.
+function fresh_record(
+	issue: string,
+	fetched: Extract<Fetched, { kind: 'read' }>,
+	now: Date,
+	acknowledged_at: string = now.toISOString(),
+): WatchRecord {
+	const baseline = issue_watch_diff.baseline_of(fetched.snapshot)
+	const checked_at = now.toISOString()
+
+	return { issue, ...baseline, acknowledged_at, checked_at, etag: fetched.etag }
+}
+
+// Called by `josh run:entry` once it has printed the issue. `false` when the issue could not be read,
+// which leaves no record — a watch with no baseline would call the whole issue unread.
+async function record_baseline(
+	issue: string,
+	root?: string,
+	now: Date = new Date(),
+): Promise<boolean> {
+	const fetched = await fetch_issue({ issue })
+
+	if (fetched.kind !== 'read') return false
+
+	write_record(fresh_record(issue, fetched, now), root)
+
+	return true
+}
+
+// The `_here` forms key the record on the repository root rather than `process.cwd()`, the same reason
+// `review_attest.check_here` does: a run started from a subdirectory must find the record it wrote.
+async function record_baseline_here(issue: string): Promise<boolean> {
+	return await record_baseline(issue, await git_command.repository_root())
+}
+
+async function clear_here(): Promise<void> {
+	clear(await git_command.repository_root())
+}
+
+function with_fetched(record: WatchRecord, fetched: Fetched, checked_at: string): WatchRecord {
+	if (fetched.kind !== 'read') return { ...record, checked_at }
+
+	const pending = issue_watch_diff.unread_diff(record, fetched.snapshot)
+
+	return { ...record, checked_at, etag: fetched.etag, pending }
+}
+
+interface PollOptions {
+	interval_ms: number
+	timeout_ms?: number
+	now?: Date
+}
+
+function is_due(record: WatchRecord, options: PollOptions, now: Date): boolean {
+	return now.getTime() - Date.parse(record.checked_at) >= options.interval_ms
+}
+
+async function refresh(
+	record: WatchRecord,
+	options: PollOptions,
+	now: Date,
+	root?: string,
+): Promise<WatchRecord | undefined> {
+	const fetched = await fetch_issue({
+		issue: record.issue,
+		etag: record.etag,
+		timeout_ms: options.timeout_ms,
+	})
+
+	if (fetched.kind === 'closed') {
+		clear(root)
+
+		return undefined
+	}
+
+	return write_record(with_fetched(record, fetched, now.toISOString()), root)
+}
+
+// The checkout's record, polled when the last poll is at least `interval_ms` old. `undefined` when no
+// run recorded a baseline here, or the issue has closed — a closed issue ends its watch.
+async function poll(options: PollOptions, root?: string): Promise<WatchRecord | undefined> {
+	const record = read_record(root)
+	const now = options.now ?? new Date()
+
+	if (record === undefined || !is_due(record, options, now)) return record
+
+	return await refresh(record, options, now, root)
+}
+
+// Marks a pending update shown, so the hook stops once per update rather than on every call.
+function mark_shown(record: WatchRecord, root?: string): WatchRecord {
+	return write_record({ ...record, shown: record.pending }, root)
+}
+
+interface Acknowledged {
+	issue: string
+	diff: string | undefined
+}
+
+// `josh issue:ack`: read the issue as it is now, return what changed since the baseline, and make
+// that the new baseline. **What is returned is exactly what is acknowledged** — the read and the new
+// baseline are the same snapshot, so an update landing between the two cannot be acknowledged unseen.
+async function acknowledge(
+	root?: string,
+	now: Date = new Date(),
+): Promise<Acknowledged | undefined> {
+	const record = read_record(root)
+
+	if (record === undefined) return undefined
+
+	const fetched = await fetch_issue({ issue: record.issue })
+
+	if (fetched.kind !== 'read') return undefined
+
+	const diff = issue_watch_diff.unread_diff(record, fetched.snapshot)
+
+	const acknowledged_at = diff === undefined ? record.acknowledged_at : now.toISOString()
+
+	write_record(fresh_record(record.issue, fetched, now, acknowledged_at), root)
+
+	return { issue: record.issue, diff }
+}
+
+const issue_watch = {
+	acknowledge,
+	clear,
+	clear_here,
+	mark_shown,
+	poll,
+	read_record,
+	record_baseline,
+	record_baseline_here,
+	record_path,
+}
+
+export type { Acknowledged, PollOptions, WatchRecord }
+export { issue_watch }

package/scripts/issue/measure-rerun-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { execSync } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -24,8 +25,6 @@ import { session_cite } from './session-cite'
 const FAILURE_EXIT_CODE = 1
 const ARGV_OFFSET = 2
 const ISSUE_FIELDS = 'body,author_association'
-const TRUSTED_ASSOCIATIONS: ReadonlySet<string> = new Set(['OWNER', 'MEMBER', 'COLLABORATOR'])
-const TRUSTED_LIST = [...TRUSTED_ASSOCIATIONS].join(' / ')
 const UNKNOWN_ASSOCIATION = 'unknown'
 const USAGE = 'Usage: josh measure:rerun <issue-number>'
 const NO_BASELINE = 'no `command → value` baseline found in ## ベースライン — nothing to re-run'
@@ -100,10 +99,10 @@ async function read_trusted_body(issue_number: string): Promise<BodyRead> {
 
 	const association = issue.author_association ?? UNKNOWN_ASSOCIATION
 
-	if (!TRUSTED_ASSOCIATIONS.has(association)) {
+	if (!gh_author_association.is_trusted(association)) {
 		return {
 			kind: 'refused',
-			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${TRUSTED_LIST}`,
+			reason: `refusing to run the baseline of ${session_cite.issue(issue_number)}: its author is ${association}, not ${gh_author_association.TRUSTED_LIST}`,
 		}
 	}
 

package/scripts/josh/josh-command-map.ts

@@ -54,6 +54,7 @@ const ALIASES: Record<string, string> = {
 	pf: 'profile',
 	st: 'start',
 	sy: 'sync',
+	un: 'uninstall',
 	rmi: 'registry:migrate',
 	g: 'git',
 	gp: 'pr',
@@ -79,9 +80,12 @@ const ALIASES: Record<string, string> = {
 	rvf: 'review:findings',
 	ruv: 'rule:value',
 	ev: 'eval',
+	fr: 'fresh:run',
+	as: 'auth:setup',
 	lsm: 'lane:sample',
 	lst: 'lane:stats',
 	lli: 'lane:limit',
+	lrs: 'lane:restart',
 	blr: 'backlogrun',
 }
 

package/scripts/josh/josh-commands-backlog.ts

@@ -11,10 +11,10 @@ const BACKLOG_COMMANDS: Record<string, CommandEntry> = {
 	backlogrun: {
 		script: 'scripts/backlog/backlogrun-cli.ts',
 		description:
-			'Start a backlogrun in the background and show its board; with one already running, only show the board',
+			'Start a backlogrun in the background and show its board; with one already running, only show the board, or replace it when it is idle and the invocation differs; --stop stops it',
 		category: 'AI tools',
 		reference: [
-			'[#<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex]',
+			'[<n>...] [--only] [--max <n>] [--idle <minutes>] [--agent claude|codex] | --stop',
 			'developer',
 			['files', 'network', 'processes'],
 		],

package/scripts/josh/josh-commands-development.ts

@@ -181,7 +181,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 	'test:unit': {
 		script: 'scripts/test/test-unit-guard.ts',
 		description:
-			'Run unit tests with Vitest (skips when Vitest is absent; fails when it has no tests)',
+			'Run unit tests with Vitest (without Vitest: a basic project runs its own test script, others skip; fails when Vitest has no tests)',
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,

package/scripts/josh/josh-commands-issue.ts

@@ -11,6 +11,13 @@ const ISSUES_WITH_REPO = '<issue...> [--repo <owner/repo>]'
 
 /* eslint-disable @typescript-eslint/naming-convention */
 const ISSUE_COMMANDS: Record<string, CommandEntry> = {
+	'issue:ack': {
+		script: 'scripts/issue/issue-ack-cli.ts',
+		description:
+			"Record that the run read a person's update to its issue, printing the update it acknowledges",
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
 	'issue:read': {
 		script: 'scripts/issue/issue-read-cli.ts',
 		description: "Print each issue's title, body and every comment on it, in one call",

package/scripts/josh/josh-commands-lane.ts

@@ -40,7 +40,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:prune': {
 		...LANE_ARGUMENTS,
 		description:
-			'Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root',
+			'Close every lane an interruption left without its work tree and every spent lane, then sweep unregistered leftovers under the lanes root',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],
@@ -74,6 +74,15 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 		category: 'AI tools',
 		reference: ['<issue> [--stash <message>]', 'automation', ['files', 'git', 'processes']],
 	},
+	// `.env` is read for `JOSH_LANE_ROOT`, as every lane command reads it, so the lane is found.
+	'lane:restart': {
+		script: 'scripts/lane/lane-restart-cli.ts',
+		tsx_arguments: OPTIONAL_ENV_FILE_FLAGS,
+		description:
+			'Stop a running lane child, stash its uncommitted work and re-dispatch its issue in a fresh session — not counted as an outage or a failure',
+		category: 'AI tools',
+		reference: ['<issue>', 'developer', ['files', 'git', 'processes', 'network']],
+	},
 	// A live run's lane limit: `.env` is read so the bare form reports the
 	// `JOSH_LANE_LIMIT` a person set there when no override stands.
 	'lane:limit': {
@@ -97,7 +106,7 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	'lane:stats': {
 		...MEASURE_ARGUMENTS,
 		description:
-			'Print one table row of lane throughput, gate duration and machine load over a period, and the per-stage durations of a lane under it',
+			'Print one table row of lane throughput, gate duration and machine load over a period, the per-stage durations of a lane under it, and the wait after each ship stop reason under those',
 		category: 'AI tools',
 		reference: ['--period <days> [--limit <lane-limit>]', 'maintainer', ['none']],
 		default_script_arguments: ['stats'],

package/scripts/josh/josh-commands-project.ts

@@ -17,7 +17,7 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		description: 'Set a project up for the GitHub Issue workflow, from git init to the setup PR',
 		category: 'Project',
 		reference: [
-			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>]`,
+			`${PROFILE_ARGUMENTS} [--yes] [--github] [--public] [--init-command <command>] [--push-preflight-command <command>]`,
 			'developer',
 			['files', 'git', 'network', 'processes'],
 		],
@@ -29,6 +29,24 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		reference: ['<dir>', 'automation', ['files', 'git']],
 		is_kit_only: true,
 	},
+	'fresh:run': {
+		script: 'scripts/fresh-machine/fresh-machine-cli.ts',
+		description:
+			'Run an install scenario in a Docker container of a machine with nothing installed, and keep the log',
+		category: 'Project',
+		reference: [
+			'<pattern> | --spec <file.json> [--package-version <version>] [--log-dir <dir>] [--rebuild] | --list',
+			'maintainer',
+			['files', 'network', 'processes'],
+		],
+	},
+	'auth:setup': {
+		script: 'scripts/auth/auth-setup-cli.ts',
+		description:
+			'Save the long-lived Claude Code token `claude setup-token` prints in the macOS keychain, for josh fresh:run',
+		category: 'Project',
+		reference: ['[--check]', 'maintainer', ['network', 'processes']],
+	},
 	init: {
 		script: 'scripts/init/init.ts',
 		description: 'Initialize config in a new project',
@@ -45,6 +63,12 @@ const PROJECT_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Project',
 		reference: ['', 'developer', ['files']],
 	},
+	uninstall: {
+		script: 'scripts/uninstall/uninstall.ts',
+		description: 'Remove what kit added to a project and list what is left to review by hand',
+		category: 'Project',
+		reference: [`${PROFILE_ARGUMENTS} [--yes]`, 'developer', ['files', 'processes']],
+	},
 	'registry:migrate': {
 		script: 'scripts/registry-migration/migrate.ts',
 		description: 'Migrate a project from GitHub Packages to public npm',

package/scripts/josh/josh-verdict.ts

@@ -35,7 +35,7 @@ import { status_icons } from '#scripts/lib/status-icons'
 // gate's plan line is what says "the gate starts here", and it is single-sourced for the reason the
 // verdict is: the printer builds it and the detector matches it from one place.
 
-const { FAIL_ICON, PASS_ICON } = status_icons
+const { FAIL_ICON, PASS_ICON, WARN_ICON } = status_icons
 const GATE_SUBJECT = 'verification gate'
 
 // The prefixes are what the detector matches **and** what the printer builds its line from, so a
@@ -43,16 +43,41 @@ const GATE_SUBJECT = 'verification gate'
 // this module exists to prevent.
 const GATE_PASSED_PREFIX = `${PASS_ICON} ${GATE_SUBJECT} passed`
 const GATE_FAILED_PREFIX = `${FAIL_ICON} ${GATE_SUBJECT} failed`
+// **A gate that ran no check has not passed, and it has not failed either.** Every check of a `basic`
+// project with nothing to check exits 0 with a skip notice, which is a legitimate state — the exit code
+// stays 0, or such a project could never commit — but a line reading `passed` made it indistinguishable
+// from a gate that ran every check. It opens with neither icon and neither word, so no reader of the
+// other two prefixes can take it for one of them.
+const GATE_UNVERIFIED_PREFIX = `${WARN_ICON} ${GATE_SUBJECT} not verified`
 
-type JoshVerdict = 'passed' | 'failed'
+type JoshVerdict = 'passed' | 'failed' | 'unverified'
 
 // Typed rather than left to inference: the namespace object widens a bare literal to `string`, and a
 // caller comparing `read_verdict(line)` against it would then be comparing two unrelated types.
 const PASSED_VERDICT: JoshVerdict = 'passed'
 const FAILED_VERDICT: JoshVerdict = 'failed'
+const UNVERIFIED_VERDICT: JoshVerdict = 'unverified'
 
-function format_gate_passed(step_count: string, total: string): string {
-	return `${GATE_PASSED_PREFIX} (${step_count} checks) in ${total}.`
+// How many of a gate's checks ran, and how many passed without running.
+interface GateCounts {
+	ran: number
+	skipped: number
+}
+
+// The split is printed only when there is one. A gate that skipped nothing — kit's own, and an ordinary
+// consumer's — keeps the line it always printed.
+function format_counts(counts: GateCounts): string {
+	if (counts.skipped === 0) return `${String(counts.ran)} checks`
+
+	return `${String(counts.ran)} ran, ${String(counts.skipped)} skipped`
+}
+
+function format_gate_passed(counts: GateCounts, total: string): string {
+	return `${GATE_PASSED_PREFIX} (${format_counts(counts)}) in ${total}.`
+}
+
+function format_gate_unverified(skipped: number, total: string): string {
+	return `${GATE_UNVERIFIED_PREFIX} (0 ran, ${String(skipped)} skipped) in ${total}.`
 }
 
 function format_gate_failed(failed_labels: string, total: string): string {
@@ -91,14 +116,18 @@ function read_verdict(line: string): JoshVerdict | undefined {
 
 	if (trimmed.startsWith(GATE_PASSED_PREFIX)) return PASSED_VERDICT
 
+	if (trimmed.startsWith(GATE_UNVERIFIED_PREFIX)) return UNVERIFIED_VERDICT
+
 	return undefined
 }
 
 const josh_verdict = {
 	PASSED_VERDICT,
 	FAILED_VERDICT,
+	UNVERIFIED_VERDICT,
 	format_gate_passed,
 	format_gate_failed,
+	format_gate_unverified,
 	GATE_OPENING_MARK,
 	GATE_OPENING_PREFIX,
 	is_gate_opening,

package/scripts/lane/claude-lane-broker.ts

@@ -0,0 +1,142 @@
+import { error_text } from '#scripts/lib/error-message'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_relaunch } from './lane-relaunch'
+import { lane_session_broker } from './lane-session-broker'
+
+// The lane broker for every open Claude lane, run inside the `run:wake` supervisor for as long as the
+// supervisor runs, so nobody has to start or stop it.
+//
+// **It lives in the supervisor because the supervisor is what holds the token.** `josh backlogrun`
+// starts it from the terminal (joshuafolkken/kit#3804), so every session it starts can sign in with a
+// token-only credential. A lane child's detached `josh ship` cannot: it descends from the child's Bash
+// tool, which Claude Code starts without the token (joshuafolkken/kit#3817). Its reviewer and its relaunch
+// are asked of this broker instead (`lane-session-broker.ts`).
+//
+// **Not inside one `backlog:drive`**: the supervisor runs a drive per pass, and a lane's ship reaches its
+// review whenever it does — while the drive has handed back to a session too, when no drive runs.
+//
+// An OpenAI lane is left to its own supervisor, which serves the same broker for that lane's lifetime;
+// two servers for one lane would overwrite each other's response.
+
+const SCAN_INTERVAL_MS = 5000
+
+type ListLanes = () => Promise<ReadonlyArray<LaneInfo>>
+
+interface Served {
+	stop: () => void
+	done: Promise<void>
+}
+
+function is_served(lane: LaneInfo): boolean {
+	return !lane.is_stranded && !lane_relaunch.is_openai_lane(lane)
+}
+
+// One lane's server, held open until `stop` — a lane that could not be served is traced, never thrown,
+// so it costs the supervisor nothing but that lane's broker.
+async function hold_server(lane: LaneInfo, held: Promise<void>): Promise<void> {
+	try {
+		await lane_session_broker.with_server(lane, async () => {
+			await held
+		})
+	} catch (error) {
+		error_text.trace_swallowed('claude_lane_broker.hold_server', error)
+	}
+}
+
+function serve_lane(lane: LaneInfo): Served {
+	const release = { stop: (): void => undefined }
+	const held = new Promise<void>((resolve) => {
+		release.stop = resolve
+	})
+
+	return { stop: release.stop, done: hold_server(lane, held) }
+}
+
+// **A closed lane's entry stays until its server has finished.** A server still answering a reviewer
+// keeps writing its response, so a server opened beside it for a re-listed lane would have the two
+// overwrite each other — the lane is reopened only by the scan after the old one is gone.
+async function forget_when_done(
+	served: Map<string, Served>,
+	issue: string,
+	entry: Served,
+): Promise<void> {
+	await entry.done
+	if (served.get(issue) === entry) served.delete(issue)
+}
+
+function close_gone(served: Map<string, Served>, open: ReadonlySet<string>): void {
+	for (const [issue, entry] of served) {
+		if (open.has(issue)) {
+			continue
+		}
+
+		entry.stop()
+		void forget_when_done(served, issue, entry)
+	}
+}
+
+function open_new(served: Map<string, Served>, lanes: ReadonlyArray<LaneInfo>): void {
+	for (const lane of lanes) {
+		if (!served.has(lane.issue)) served.set(lane.issue, serve_lane(lane))
+	}
+}
+
+async function scan(served: Map<string, Served>, list: ListLanes): Promise<void> {
+	try {
+		const listed = await list()
+		const lanes = listed.filter((lane) => is_served(lane))
+
+		close_gone(served, new Set(lanes.map((lane) => lane.issue)))
+		open_new(served, lanes)
+	} catch (error) {
+		error_text.trace_swallowed('claude_lane_broker.scan', error)
+	}
+}
+
+// Each scan starts only once the previous one has finished, so two never race over the same map.
+async function scan_after(
+	previous: Promise<void>,
+	served: Map<string, Served>,
+	list: ListLanes,
+): Promise<void> {
+	await previous
+	await scan(served, list)
+}
+
+// Starts serving now and on every interval; the returned stop closes every server and waits for them.
+function start(list: ListLanes = lane_registry.list_lanes): () => Promise<void> {
+	const served = new Map<string, Served>()
+	const state = { scanning: scan(served, list) }
+	const timer = setInterval(() => {
+		state.scanning = scan_after(state.scanning, served, list)
+	}, SCAN_INTERVAL_MS).unref()
+
+	return async () => {
+		clearInterval(timer)
+		await state.scanning
+		close_gone(served, new Set())
+		await Promise.all(
+			[...served.values()].map(async (entry) => {
+				await entry.done
+			}),
+		)
+	}
+}
+
+// Serves every open Claude lane for exactly as long as `run` runs.
+async function serve_during<T>(
+	run: () => Promise<T>,
+	list: ListLanes = lane_registry.list_lanes,
+): Promise<T> {
+	const stop = start(list)
+
+	try {
+		return await run()
+	} finally {
+		await stop()
+	}
+}
+
+const claude_lane_broker = { SCAN_INTERVAL_MS, serve_during, start }
+
+export { claude_lane_broker }

package/scripts/lane/lane-await.ts

@@ -12,6 +12,7 @@ import {
 } from '#scripts/run/run-liveness'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_handoff } from './lane-handoff'
+import { process_tools } from './process-tools'
 
 // 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
@@ -30,6 +31,7 @@ const NEVER_APPEARED_TIMEOUT_MS = 600_000
 const MS_PER_SECOND = 1000
 const PROCESS_FOUND = 0
 const PROCESS_NOT_FOUND = 1
+const PGREP_COMMAND = 'pgrep'
 
 // `is_settled` is read once, when the wait starts: a child that ended between two `lane:await` calls
 // never appears in the second one, and only its settled issue tells it apart from one not yet
@@ -77,14 +79,16 @@ interface RunConfig extends CheckConfig {
 
 // Three answers, not two: only pgrep's own "no match" exit is `none`. A pgrep that failed or hit its
 // timeout never looked, and `run:liveness` answers `undetermined` for it rather than booking a live
-// child as stopped.
+// child as stopped. A pgrep that is not installed could never look, so it is refused by name.
 function process_trace_default(issue: string): ProcessTrace {
 	const pattern = lane_child_invocation.process_pattern(issue)
-	const result = spawnSync('pgrep', ['-f', pattern], {
+	const result = spawnSync(PGREP_COMMAND, ['-f', pattern], {
 		encoding: 'utf8',
 		timeout: PROBE_TIMEOUT_MS,
 	})
 
+	process_tools.throw_if_missing(PGREP_COMMAND, result.error)
+
 	if (result.status === PROCESS_FOUND) return PROCESS_ALIVE
 	if (lane_handoff.is_ship_running(issue, process.cwd())) return PROCESS_ALIVE