@joshuafolkken/kit 1.1035.0 → 1.1094.0

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

@@ -1,4 +1,10 @@
 import { run_issue_number } from '#scripts/run/run-issue-number'
+import { run_ship_next, type ShipResume } from '#scripts/run/run-ship-next'
+import type { Stage } from '#scripts/run/run-ship-stage'
+
+interface ShipStop extends ShipResume {
+	stage: Stage
+}
 
 const CHILD_INVOCATION = 'fullrun'
 const RESUME_GUIDE = '.claude/skills/workflow-commands/pre-gate-cut.md'
@@ -52,17 +58,24 @@ function outage_resume_invocation(issue: string): string {
 
 // 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.`
+// ended at the hand-off, so this is how control comes back to one: it reads the stopped report, 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.
+//
+// **A known stage puts the next command in the prompt** (joshuafolkken/kit#2964), so the relaunched
+// session runs it rather than re-deriving it from `chain-rule.md`. An OpenAI lane's supervisor sees only
+// that the ship failed, not where, so without a stage the prompt points at `run:step` as before.
+function ship_stop_invocation(issue: string, stop?: ShipStop): string {
+	const opening = `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).`
+	const next =
+		stop === undefined
+			? `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.`
+			: run_ship_next.next_step(issue, stop.stage, stop)
 
-	return `${preamble} ${child_invocation(issue)}`
+	return `${opening} ${next} Do not re-plan or re-implement what is already on the branch. ${child_invocation(issue)}`
 }
 
 const lane_child_invocation = {
-	CHILD_INVOCATION,
 	child_invocation,
 	outage_resume_invocation,
 	process_pattern,

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

@@ -19,6 +19,15 @@ import { lane_paths } from './lane-paths'
 // `.claude/skills/workflow-commands/pre-gate-cut.md`.
 const KEY = 'JOSH_LANE_CHILD'
 
+// **A dispatched child also asks for the five-minute prompt-cache TTL** (joshuafolkken/kit#2944). A
+// headless `claude -p` session on a subscription defaults to the one-hour TTL, whose writes bill at 2x
+// the input rate against 1.25x for five minutes. A replay of 1,953 lane transcripts (about 57,000
+// requests) found 0.3% of request gaps over five minutes, so the shorter TTL — re-writing the prefix on
+// those few gaps — still costs 12-13% less. Every launcher of a child composes its environment here,
+// so this is the one place the choice is made.
+const CACHE_TTL_KEY = 'CLAUDE_CODE_PROMPT_CACHE_TTL'
+const CACHE_TTL = '5m'
+
 type MarkerSource = Readonly<Record<string, string | undefined>>
 
 // The environment fragment that marks a child dispatched for `#<issue>`. Composed from a digits-only
@@ -27,7 +36,7 @@ type MarkerSource = Readonly<Record<string, string | undefined>>
 function environment_for(issue: string): Record<string, string> {
 	run_issue_number.require_issue_number(issue)
 
-	return { [KEY]: issue }
+	return { [KEY]: issue, [CACHE_TTL_KEY]: CACHE_TTL }
 }
 
 // The issue a child was dispatched for, or `undefined` when the mark is absent or malformed. A blank
@@ -52,7 +61,12 @@ function is_child_of(directory: string, source: MarkerSource = process.env): boo
 	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 }
+const lane_child_marker = {
+	KEY,
+	env_for: environment_for,
+	is_child_of,
+	marked_issue,
+}
 
 export type { MarkerSource }
 export { lane_child_marker }

package/scripts/lane/lane-cli.ts

@@ -1,7 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { epic_busy } from '#scripts/epic/epic-busy'
-import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { OpenIssueData } from '#scripts/git/schemas'
+import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
 import { run_carry } from '#scripts/run/run-carry'
 import { lane_await } from './lane-await'
@@ -150,10 +152,10 @@ function report_sweep(outcome: SweepOutcome): number {
 
 // `none` on standard output for the empty case as well, so `lane:list` keeps the contract the rest
 // of the commands follow — the prose belongs on standard error with every other explanation.
-function report_lanes(lanes: ReadonlyArray<LaneInfo>): number {
+function report_lanes(lanes: ReadonlyArray<LaneInfo>, cite: IssueCiter): number {
 	if (lanes.length === 0) console.error(lane_report.NO_LANES)
 
-	console.info(lanes.length === 0 ? NONE_TOKEN : lane_report.describe_lanes(lanes))
+	console.info(lanes.length === 0 ? NONE_TOKEN : lane_report.describe_lanes(lanes, cite))
 
 	return SUCCESS_EXIT_CODE
 }
@@ -192,23 +194,39 @@ const OCCUPANCY_UNREADABLE =
 // The `in-progress` issues this repository shows running, read the way `epic:next` reads lane
 // occupancy — never rebuilt (joshuafolkken/kit#2235). A read that could not see the whole listing is
 // `undefined`, so the difference is skipped rather than computed against a set known to be partial.
-async function to_holder_numbers(repo: string): Promise<ReadonlyArray<number> | undefined> {
+async function to_holders(repo: string): Promise<ReadonlyArray<OpenIssueData> | undefined> {
 	const read = await epic_busy.read_repository(repo)
 	if (read.kind === 'idle') return []
 
-	return read.kind === 'busy' ? read.issues.map((issue) => issue.number) : undefined
+	return read.kind === 'busy' ? read.issues : undefined
 }
 
-async function read_in_progress(): Promise<ReadonlyArray<number> | undefined> {
+// The repository and its running issues, read once: the listing cites each lane from the titles here
+// (joshuafolkken/kit#2943) and the occupancy check compares against the same set.
+interface InProgress {
+	repo: string | undefined
+	holders: ReadonlyArray<OpenIssueData> | undefined
+}
+
+async function read_in_progress(): Promise<InProgress> {
 	try {
 		const repo = await git_gh_command.repo_get_name_with_owner()
 
-		return repo === undefined ? undefined : await to_holder_numbers(repo)
+		return { repo, holders: repo === undefined ? undefined : await to_holders(repo) }
 	} catch {
-		return undefined
+		return { repo: undefined, holders: undefined }
 	}
 }
 
+function citer_of(in_progress: InProgress): IssueCiter {
+	const holders = in_progress.holders ?? []
+
+	return issue_cite.citer(
+		in_progress.repo,
+		new Map(holders.map((issue) => [String(issue.number), issue.title])),
+	)
+}
+
 // A stranded lane's work tree is gone, so it holds no issue: it counts as no lane rather than a live
 // one, which is what turns its surviving `in-progress` label into a `stopped` anomaly.
 function live_lane_issues(lanes: ReadonlyArray<LaneInfo>): Array<number> {
@@ -217,16 +235,15 @@ function live_lane_issues(lanes: ReadonlyArray<LaneInfo>): Array<number> {
 
 // The lane/label difference, printed to standard error beside the listing. Wrapped so a GitHub read
 // that fails skips only this section — `lane:list`'s job is to list the lanes it already read.
-async function report_occupancy(lanes: ReadonlyArray<LaneInfo>): Promise<void> {
-	const in_progress = await read_in_progress()
-
-	if (in_progress === undefined) {
+function report_occupancy(lanes: ReadonlyArray<LaneInfo>, in_progress: InProgress): void {
+	if (in_progress.holders === undefined) {
 		console.error(OCCUPANCY_UNREADABLE)
 
 		return
 	}
 
-	const report = lane_occupancy.classify(in_progress, {
+	const holders = in_progress.holders.map((issue) => issue.number)
+	const report = lane_occupancy.classify(holders, {
 		kind: 'lanes',
 		issues: live_lane_issues(lanes),
 	})
@@ -239,9 +256,10 @@ async function list_command(rest: ReadonlyArray<string>): Promise<number> {
 	if (rest.length > 0) return report_usage()
 
 	const lanes = await lane_registry.list_lanes()
-	const code = report_lanes(lanes)
+	const in_progress = await read_in_progress()
+	const code = report_lanes(lanes, citer_of(in_progress))
 
-	await report_occupancy(lanes)
+	report_occupancy(lanes, in_progress)
 
 	return code
 }
@@ -399,9 +417,6 @@ const lane_cli = {
 	ALL_FLAG,
 	NONE_TOKEN,
 	USAGE,
-	main,
-	parse_issue,
-	parse_lane_issue,
 	refusal_message,
 	run,
 }

package/scripts/lane/lane-close.ts

@@ -158,6 +158,7 @@ async function close_each(issues: ReadonlyArray<string>): Promise<SweepOutcome>
 	const sweep: SweepOutcome = { closed: [], failed: [] }
 
 	for (const issue of issues) {
+		// eslint-disable-next-line no-await-in-loop -- worktree writes contend for the same registration directory
 		const bucket = (await try_close(issue)) ? sweep.closed : sweep.failed
 
 		bucket.push(issue)
@@ -186,10 +187,7 @@ async function close_all_lanes(): Promise<SweepOutcome> {
 const lane_close = {
 	close_all_lanes,
 	close_lane,
-	lane_root_directory,
-	lane_targets,
 	prune_lanes,
-	remove_lane,
 	resolve_lane,
 }
 

package/scripts/lane/lane-dispatch.ts

@@ -1,8 +1,8 @@
 import { agent_argv, type AgentArgv, type AgentArgvResult } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
-import { git_gh_command } from '#scripts/git/git-gh-command'
-import { IN_PROGRESS_LABEL } from '#scripts/git/issue-labels'
-import { telegram_notify } from '#scripts/git/telegram-notify'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { detached_launch } from '#scripts/run/detached-launch'
 import { run_ending } from '#scripts/run/run-ending'
 import { run_event_stream } from '#scripts/run/run-event-stream'
@@ -444,7 +444,6 @@ async function warn_of_problem(outcome: DispatchOutcome, issue: string): Promise
 }
 
 const lane_dispatch = {
-	CHILD_INVOCATION: lane_child_invocation.CHILD_INVOCATION,
 	child_invocation,
 	default_log_path,
 	describe,

package/scripts/lane/lane-environment.ts

@@ -58,10 +58,6 @@ function is_key_line(line: string, key: string): boolean {
 	return body.slice(key.length).trimStart().startsWith(ASSIGNMENT_SEPARATOR)
 }
 
-function is_seed_line(line: string): boolean {
-	return is_key_line(line, PORT_SEED_KEY)
-}
-
 function is_seat_line(line: string): boolean {
 	return is_key_line(line, LANE_SEAT_KEY)
 }
@@ -235,12 +231,7 @@ function with_lane_output(content: string, output: string, profile?: AgentProfil
 }
 
 const lane_environment = {
-	LANE_OUTPUT_KEY,
-	LANE_PROVIDER_KEY,
-	LANE_ROLE_KEY,
-	is_output_line,
 	is_seat_line,
-	is_seed_line,
 	lane_file_content,
 	read_lane_output,
 	read_lane_profile,

package/scripts/lane/lane-handoff.ts

@@ -0,0 +1,38 @@
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { lane_child_marker, type MarkerSource } from './lane-child-marker'
+
+// Whether a lane has handed its post-implementation region to the detached ship (joshuafolkken/kit#2962).
+//
+// **A child that ran `pnpm josh ship --detach` waits on nobody when it ends.** The supervisor drives the
+// gate, the review and the merge, and notifies on its own outcome, so the `Stop` hook's demand for a
+// `confirmation` notify and `lane-park`'s refusal of that notify only bought a "nothing needed"
+// Telegram and a wasted turn — measured on 2026-10-02 as 43 demands, 21 refusals and ~94 extra turns.
+// Both hooks read this one predicate, so they cannot disagree about whether the lane was handed off.
+//
+// **Running, never merely recorded.** A ship that failed hands its region back to the child, whose
+// record then reads `failed`; that child is waiting again and owes the notify, so only a live
+// supervisor counts as a hand-off.
+
+// A detached ship for `issue` is live in the repository `directory` belongs to — the single reading
+// `lane:await`, `run:merge` and the two stop hooks share.
+function is_ship_running(issue: string, directory: string): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	return (
+		repository !== undefined && run_ship_detach.read_result(repository, issue)?.result === 'running'
+	)
+}
+
+// This session is the dispatched lane child for `directory` and its own ship is running.
+function is_handed_off(directory: string, source: MarkerSource = process.env): boolean {
+	const issue = lane_child_marker.marked_issue(source)
+
+	if (issue === undefined || !lane_child_marker.is_child_of(directory, source)) return false
+
+	return is_ship_running(issue, directory)
+}
+
+const lane_handoff = { is_handed_off, is_ship_running }
+
+export { lane_handoff }

package/scripts/lane/lane-launch-cli.ts

@@ -2,6 +2,7 @@
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from 'node:util'
 import { josh_command } from '#scripts/josh/josh-run'
+import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
 // `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
@@ -57,6 +58,7 @@ function read_context(argv: ReadonlyArray<string>): LaunchContext | undefined {
 async function install(directory: string): Promise<boolean> {
 	const result = await execa(PNPM, ['--dir', directory, 'install', '--frozen-lockfile'], {
 		reject: false,
+		timeout: INSTALL_TIMEOUT_MS,
 	})
 
 	if ((result.exitCode ?? FAILURE_EXIT_CODE) === SUCCESS_EXIT_CODE) return true
@@ -82,29 +84,37 @@ async function prepare(stash: string | undefined, directory: string): Promise<bo
 	return await install(directory)
 }
 
-// The launch chain in-process: the dispatched child's pid, or `undefined` when a step refused. The CLI
-// prints the pid; `backlog:drive` launches through this same chain (joshuafolkken/kit#2508).
-async function launch_lane(context: LaunchContext): Promise<string | undefined> {
+// Where the chain ended. `unopened` is a `lane:open` refusal — no lane was taken; `failed` is a step
+// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike
+// (joshuafolkken/kit#3027).
+type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } | { kind: 'failed' }
+
+const UNOPENED: LaunchOutcome = { kind: 'unopened' }
+const FAILED: LaunchOutcome = { kind: 'failed' }
+
+// The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
+// chain (joshuafolkken/kit#2508).
+async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 	const opened = await josh_command.josh_run(['lane:open', context.issue], should_forward_stderr)
 
-	if (opened.code !== SUCCESS_EXIT_CODE) return undefined
+	if (opened.code !== SUCCESS_EXIT_CODE) return UNOPENED
 
-	if (!(await prepare(context.stash, opened.out))) return undefined
+	if (!(await prepare(context.stash, opened.out))) return FAILED
 
 	const dispatched = await josh_command.josh_run(
 		['lane:dispatch', context.issue],
 		should_forward_stderr,
 	)
 
-	return dispatched.code === SUCCESS_EXIT_CODE ? dispatched.out : undefined
+	return dispatched.code === SUCCESS_EXIT_CODE ? { kind: 'launched', pid: dispatched.out } : FAILED
 }
 
 async function launch(context: LaunchContext): Promise<number> {
-	const pid = await launch_lane(context)
+	const outcome = await launch_lane(context)
 
-	if (pid === undefined) return FAILURE_EXIT_CODE
+	if (outcome.kind !== 'launched') return FAILURE_EXIT_CODE
 
-	console.info(pid)
+	console.info(outcome.pid)
 
 	return SUCCESS_EXIT_CODE
 }
@@ -125,9 +135,9 @@ async function main(argv: ReadonlyArray<string>): Promise<void> {
 	process.exitCode = await run(argv)
 }
 
-const lane_launch_cli = { USAGE, install, launch, launch_lane, prepare, read_context, run }
+const lane_launch_cli = { launch_lane, read_context, run }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
 
-export type { LaunchContext }
+export type { LaunchContext, LaunchOutcome }
 export { lane_launch_cli }

package/scripts/lane/lane-open.ts

@@ -279,10 +279,7 @@ async function open_lane(issue: string): Promise<OpenOutcome> {
 }
 
 const lane_open = {
-	build_plan,
-	guard_unreadable,
 	open_lane,
-	read_root_environment,
 }
 
 export type { OpenOutcome }

package/scripts/lane/lane-output.ts

@@ -115,7 +115,6 @@ function describe_refusal(refusal: Refusal, issue: string): string {
 const lane_output = {
 	NO_OUTPUT,
 	describe_refusal,
-	invalid_reason,
 	read_output,
 	record_output,
 }

package/scripts/lane/lane-registry.ts

@@ -217,6 +217,14 @@ async function list_lanes(): Promise<Array<LaneInfo>> {
 	return lanes.toSorted((left, right) => Number(left.issue) - Number(right.issue))
 }
 
+// The lanes a parent is still waiting on. A stranded lane has no child working in it, so it is not
+// in-flight — the one definition the watcher guard and the headless stop rule both read.
+async function has_lanes_in_flight(): Promise<boolean> {
+	const lanes = await list_lanes()
+
+	return lanes.some((lane) => !lane.is_stranded)
+}
+
 /** The seats live lanes hold — what a new lane's seat has to avoid. */
 function used_seats(lanes: ReadonlyArray<LaneInfo>): Array<number> {
 	return lanes.map((lane) => lane.seat).filter((seat): seat is number => seat !== undefined)
@@ -246,6 +254,7 @@ async function find_open_lane(issue: string): Promise<LaneInfo | undefined> {
 const lane_registry = {
 	find_lane,
 	find_open_lane,
+	has_lanes_in_flight,
 	list_lanes,
 	main_repository_root,
 	parse_block,

package/scripts/lane/lane-report.ts

@@ -1,4 +1,5 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
 import { run_liveness } from '#scripts/run/run-liveness'
 import type { LaneInfo } from './lane-registry'
 
@@ -48,9 +49,14 @@ function event_column(lane: LaneInfo): string {
 	return state ?? 'agent -'
 }
 
-function describe_lane(lane: LaneInfo): string {
+// The plain `#N`, for a caller that could not read the repository the issue would link into.
+const PLAIN_CITE: IssueCiter = issue_cite.citer(undefined, new Map())
+
+// The issue leads as a citation (joshuafolkken/kit#2943): a lane status report copies this row, and a
+// bare `#N` copied into it is what the Stop guard sends back.
+function describe_lane(lane: LaneInfo, cite: IssueCiter = PLAIN_CITE): string {
 	return [
-		`#${lane.issue}`,
+		cite(lane.issue),
 		`seat ${value_or_unknown(lane.seat)}`,
 		`dev ${value_or_unknown(lane.development_port)}`,
 		`preview ${value_or_unknown(lane.preview_port)}`,
@@ -63,10 +69,10 @@ function describe_lane(lane: LaneInfo): string {
 	].join(COLUMN_SEPARATOR)
 }
 
-function describe_lanes(lanes: ReadonlyArray<LaneInfo>): string {
+function describe_lanes(lanes: ReadonlyArray<LaneInfo>, cite: IssueCiter = PLAIN_CITE): string {
 	if (lanes.length === 0) return NO_LANES
 
-	return lanes.map((lane) => describe_lane(lane)).join('\n')
+	return lanes.map((lane) => describe_lane(lane, cite)).join('\n')
 }
 
 function describe_ports(lane: LaneInfo): string {

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

@@ -17,7 +17,9 @@ async function wait_for_ship(issue: string, prior_launch: string | undefined): P
 	if (read === undefined || read.launch_id === prior_launch) return 'none'
 
 	while (read.result === 'running') {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_MS)
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		read = await current(issue)
 		if (read === undefined) return 'abnormal'
 	}

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

@@ -48,6 +48,7 @@ async function is_approved(lane_directory: string, nonce: string): Promise<boole
 		const decision = read(lane_directory, nonce)?.decision
 		if (decision !== undefined) return decision === 'approved'
 
+		// 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, APPROVAL_POLL_MS))
 	}
 
@@ -58,6 +59,6 @@ function remove(lane_directory: string, nonce: string): void {
 	stamp_file.remove_stamp(target(lane_directory, nonce))
 }
 
-const openai_lane_supervisor_decision = { approve, cancel, is_approved, remove, target }
+const openai_lane_supervisor_decision = { approve, cancel, is_approved, remove }
 
 export { openai_lane_supervisor_decision }

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

@@ -4,6 +4,7 @@ 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 { detached_launch, type LaunchArgv } from '#scripts/run/detached-launch'
 import { run_cut, type RunCut } from '#scripts/run/run-cut'
@@ -22,11 +23,12 @@ 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))
-const owner_schema = z.object({
+// 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(),
-	process_start: z.string().optional(),
 })
 const state_schema = z.object({
 	owner_nonce: z.string(),
@@ -81,6 +83,7 @@ async function wait_for_active(lane_directory: string): Promise<SupervisorOwner
 	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))
 	}
 
@@ -298,6 +301,7 @@ async function wait_for_inherited_child(
 	child_process_start: string | undefined,
 ): Promise<void> {
 	while (process_identity.is_same_process(child_pid, child_process_start) !== false) {
+		// 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, CHILD_POLL_MS))
 	}
 }
@@ -350,10 +354,8 @@ const openai_lane_supervisor = {
 	approve: openai_lane_supervisor_decision.approve,
 	cancel: openai_lane_supervisor_decision.cancel,
 	claim,
-	decision_path: openai_lane_supervisor_decision.target,
 	marker_path,
 	new_nonce: randomUUID,
-	read,
 	release,
 	state_path,
 	supervise,

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

@@ -138,9 +138,11 @@ async function serve(
 
 		if (received?.session === session && received.nonce !== last_nonce) {
 			last_nonce = received.nonce
+			// eslint-disable-next-line no-await-in-loop -- requests are served one at a time, in arrival order
 			await process_request(lane, response, received, state)
 		}
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_MS)
 	}
 }
@@ -232,6 +234,7 @@ async function wait_response(target: string, session: string, nonce: string): Pr
 		const verdict = response_verdict(read_record(target, response_schema), session, nonce)
 		if (verdict !== 'wait') return verdict === 'success'
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await sleep(POLL_MS)
 	}
 

package/scripts/lib/bounded-pool.ts

@@ -70,6 +70,7 @@ async function drain<Item, Result>(
 		const [index, item] = entry
 
 		try {
+			// eslint-disable-next-line no-await-in-loop -- one consumer runs one task at a time; the pool's width is the concurrency
 			pool.results.push({ index, value: await worker(item, index) })
 		} catch (error) {
 			pool.failures.push(error)

package/scripts/lib/json-value.ts

@@ -1,9 +1,10 @@
 // Reading JSON that may not be JSON (joshuafolkken/kit#1151).
 //
-// Four readers under `scripts/` parse text that a defect, a truncated write or an older format can
-// make unparseable — a transcript line, a settings file, an MCP declaration — and every one of them
-// answers "could not read this" rather than throwing, because a single bad line must not fail a
-// whole report. They had begun to carry a copy of the same try/catch each; this is the one copy.
+// Readers under `scripts/` parse text that a defect, a truncated write or an older format can make
+// unparseable — a transcript line, a settings file, an MCP declaration, a lock record, CLI output —
+// and every one of them answers "could not read this" rather than throwing, because a single bad line
+// must not fail a whole report. They had begun to carry a copy of the same try/catch each; this is the
+// one copy, and `is_record` beside it is the one object test (joshuafolkken/kit#2986).
 
 function parse_or_undefined(text: string): unknown {
 	try {

package/scripts/lib/poll.ts

@@ -1,6 +1,6 @@
 // One bounded polling loop and one sleep, in one place.
 //
-// **Three modules had already written the same three-line `sleep`** — `git/git-pr-checks.ts`,
+// **Three modules had already written the same three-line `sleep`** — `gh/git-pr-checks.ts`,
 // `eval/eval-run.ts` and `propagate/propagate-publish.ts` — and the release command's tag watch
 // (joshuafolkken/kit#1169) would have been the fourth. `CLAUDE.md` → "No clones — single-source"
 // reads an existing duplication as the signal to single-source it rather than as a license to add to
@@ -43,8 +43,10 @@ async function poll_until(is_done: () => Promise<boolean>, options: PollOptions)
 	const wait = options.sleeper ?? sleep
 
 	for (let attempt = 0; attempt < options.attempts; attempt += 1) {
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		if (await is_done()) return true
 
+		// eslint-disable-next-line no-await-in-loop -- polling: each read waits on the state the previous one saw
 		await wait_between(wait, options.interval_ms, attempt, options.attempts)
 	}
 

package/scripts/lib/timed-fetch.ts

@@ -0,0 +1,15 @@
+import { FETCH_TIMEOUT_MS } from './timeouts'
+
+// **The one place in `scripts/` that calls the global `fetch`** (joshuafolkken/kit#2981). Every request
+// carries a time limit, so a stalled connection rejects instead of holding an unattended run forever;
+// `timed-fetch-usage.test.ts` refuses a direct `fetch` call anywhere else. The signal also bounds the
+// body read, because the response stream aborts with it.
+async function timed_fetch(
+	url: string,
+	init: Omit<RequestInit, 'signal'> = {},
+	timeout_ms: number = FETCH_TIMEOUT_MS,
+): Promise<Response> {
+	return await fetch(url, { ...init, signal: AbortSignal.timeout(timeout_ms) })
+}
+
+export { timed_fetch }

package/scripts/lib/timeouts.ts

@@ -0,0 +1,13 @@
+// Shared time limits for the calls that leave the process — a network request or a spawned command.
+// An unattended run (a lane, `followup`, a backlog drain) that waits on a request or a command with no
+// 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.
+
+// One HTTP request to a registry, an API or a webhook.
+const FETCH_TIMEOUT_MS = 10_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.
+const INSTALL_TIMEOUT_MS = 600_000
+
+export { COMMAND_TIMEOUT_MS, FETCH_TIMEOUT_MS, INSTALL_TIMEOUT_MS }

package/scripts/{yaml → lib}/yaml-document.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { json_object_schema } from '#scripts/lib/schemas'
 import { load, loadAll, YAMLException } from 'js-yaml'
 
@@ -25,8 +26,9 @@ function parse_yaml(content: string): Record<string, unknown> {
 	return json_object_schema.parse(raw)
 }
 
+// A YAML mapping parses to the same plain object a JSON object does, so the test is `json_value`'s.
 function is_mapping_document(value: unknown): value is Record<string, unknown> {
-	return typeof value === 'object' && value !== null && !Array.isArray(value)
+	return json_value.is_record(value)
 }
 
 // pnpm 11 writes pnpm-lock.yaml as a multi-document stream (the package-manager document, then the