@joshuafolkken/kit 1.1383.0 → 1.1435.0

package/scripts/lane/lane-cache.ts

@@ -1,5 +1,13 @@
 import { randomUUID } from 'node:crypto'
-import { cpSync, existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import {
+	cpSync,
+	existsSync,
+	mkdirSync,
+	readFileSync,
+	renameSync,
+	rmSync,
+	writeFileSync,
+} from 'node:fs'
 import path from 'node:path'
 import { hook_launch } from '#scripts/init/hook-launch'
 import {
@@ -30,6 +38,8 @@ import {
 // 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.
 
+const STAGING_SEGMENTS = ['node_modules', '.cache', 'josh-lane-cache'] as const
+
 function replace_root(value: unknown, source_prefix: string, destination_root: string): unknown {
 	if (typeof value !== 'string') return value
 
@@ -61,19 +71,39 @@ function portable_content(
 	return content
 }
 
-function write_atomically(destination_path: string, content: string): void {
-	const temporary_path = `${destination_path}.${String(process.pid)}.${randomUUID()}.tmp`
+// The staging file lives under `node_modules/.cache`, never beside the cache it replaces: prettier
+// runs in parallel with the tool whose cache is being copied, and a temporary name in the checkout
+// root is listed by its tree walk and gone by the time it is read (#3763). `node_modules` is skipped
+// by every tree scan and sits on the checkout's own filesystem, so the rename stays atomic.
+function stage_path(destination_root: string, cache_file: string): string {
+	const staging_directory = path.join(destination_root, ...STAGING_SEGMENTS)
+
+	mkdirSync(staging_directory, { recursive: true })
+
+	return path.join(staging_directory, `${cache_file}.${String(process.pid)}.${randomUUID()}.tmp`)
+}
 
+function publish_staged(temporary_path: string, destination_path: string, content: string): void {
 	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 write_atomically(destination_root: string, cache_file: string, content: string): void {
+	if (!existsSync(destination_root)) return
+
+	try {
+		const temporary_path = stage_path(destination_root, cache_file)
+
+		publish_staged(temporary_path, path.join(destination_root, cache_file), content)
+	} catch {
+		// Best-effort: a cache that could not be published simply leaves the destination unchanged.
+	}
+}
+
 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
@@ -86,7 +116,7 @@ function copy_if_present(source_root: string, destination: string, spec: GateCac
 			destination,
 		)
 
-		write_atomically(path.join(destination, spec.cache_file), content)
+		write_atomically(destination, spec.cache_file, content)
 	} catch {
 		// A missing, changing, or malformed cache is a miss, never a failed lane or gate.
 	}
@@ -130,6 +160,6 @@ function sync_cache(source_root: string, destination: string, cache_file: string
 	copy_if_present(source_root, destination, spec)
 }
 
-const lane_cache = { seed_caches, seed_hook_bundles, sync_cache }
+const lane_cache = { STAGING_SEGMENTS, seed_caches, seed_hook_bundles, sync_cache }
 
 export { lane_cache }

package/scripts/lane/lane-capacity.ts

@@ -10,14 +10,16 @@ import { lane_seed_policy } from './lane-seed'
 // is what would have to be undone the first time two epics run together, which is why the scheduler
 // is epic-free.
 //
-// **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
+// **It is a ceiling, not a prediction.** Four lanes does not say four children will run at once; it
+// says a fifth 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
+// Four 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
+// never lands on "the ports ran out" as its first symptom. joshuafolkken/kit#3788 lowered it from
+// six: a week of `lane:stats` showed 1.5 effective lanes, while the hours at five or six lanes held
+// the swap peak, the slowest gates and most of the gate and commit failures.
+const DEFAULT_LANE_LIMIT = 4
 const LANE_LIMIT_KEY = 'JOSH_LANE_LIMIT'
 const POSITIVE_INTEGER = /^[1-9]\d*$/u
 const NO_LANES = 0
@@ -28,7 +30,7 @@ const NO_LANES = 0
 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
+// `PORT_SEED` already holds to. A typo that quietly becomes 4 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

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

@@ -85,4 +85,5 @@ const lane_child_invocation = {
 	ship_stop_invocation,
 }
 
+export type { ShipStop }
 export { lane_child_invocation }

package/scripts/lane/lane-cli.ts

@@ -18,6 +18,7 @@ import { lane_output, type ReadOutcome, type RecordOutcome } from './lane-output
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_report } from './lane-report'
 import { lane_seed_policy } from './lane-seed'
+import type { KeptLane } from './lane-spent'
 import { lane_stray } from './lane-stray'
 
 // `josh lane:open` / `lane:close` / `lane:list` / `lane:prune` — the lane's whole lifecycle.
@@ -263,10 +264,23 @@ async function list_command(rest: ReadonlyArray<string>): Promise<number> {
 	return code
 }
 
+// A lane left open is named with its reason, so a person can tell a lane somebody is in from one that
+// only waits on a push, a commit or an issue — and knows the command that discards it anyway.
+function report_kept(kept: ReadonlyArray<KeptLane>): void {
+	for (const lane of kept) {
+		console.error(
+			`Kept the lane for ${session_cite.issue(lane.issue)}: ${lane.reason}. \`pnpm josh lane:close ${lane.issue}\` discards it.`,
+		)
+	}
+}
+
 async function prune_command(rest: ReadonlyArray<string>): Promise<number> {
 	if (rest.length > 0) return report_usage()
 
-	const code = report_sweep(await lane_close.prune_lanes())
+	const outcome = await lane_close.prune_lanes()
+	const code = report_sweep(outcome)
+
+	report_kept(outcome.kept)
 
 	// After the closes, so a lane whose close left its directory behind is swept in the same run. A
 	// kept stray is reported, never a failure: it waits on a person, and a non-zero exit would stop

package/scripts/lane/lane-close.ts

@@ -5,6 +5,7 @@ import { error_text } from '#scripts/lib/error-message'
 import { lane_paths } from './lane-paths'
 import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_spent, type KeptLane } from './lane-spent'
 
 // Closing a lane: no work tree, no branch, no directory.
 //
@@ -42,6 +43,11 @@ interface SweepOutcome {
 	failed: Array<string>
 }
 
+interface PruneOutcome extends SweepOutcome {
+	// The live lanes left open, each with the reason it was not discarded.
+	kept: Array<KeptLane>
+}
+
 async function ignore_failure(action: () => Promise<string>): Promise<void> {
 	try {
 		await action()
@@ -171,14 +177,17 @@ async function close_each(issues: ReadonlyArray<string>): Promise<SweepOutcome>
 }
 
 /**
- * Close every lane whose work tree is no longer on disk — the route out of an interruption that took
- * the directory with it and left git's registration behind.
+ * Close every lane nothing needs any more: one whose work tree is no longer on disk — the route out of
+ * an interruption that took the directory with it and left git's registration behind — and one a past
+ * run left spent (`lane-spent.ts`). A live lane that is not spent is kept, and `kept` says why.
  */
-async function prune_lanes(): Promise<SweepOutcome> {
+async function prune_lanes(): Promise<PruneOutcome> {
 	const lanes = await lane_registry.list_lanes()
-	const stranded = lanes.filter((lane) => lane.is_stranded)
+	const { spent, kept } = await lane_spent.sort_lanes(lanes)
+	const doomed = lanes.filter((lane) => lane.is_stranded || spent.includes(lane))
+	const sweep = await close_each(doomed.map((lane) => lane.issue))
 
-	return await close_each(stranded.map((lane) => lane.issue))
+	return { ...sweep, kept }
 }
 
 async function close_all_lanes(): Promise<SweepOutcome> {
@@ -194,5 +203,5 @@ const lane_close = {
 	resolve_lane,
 }
 
-export type { CloseKind, CloseOutcome, ResolvedLane, SweepOutcome }
+export type { CloseKind, CloseOutcome, PruneOutcome, ResolvedLane, SweepOutcome }
 export { lane_close }

package/scripts/lane/lane-dispatch.ts

@@ -49,6 +49,7 @@ const WARNING_RECOVERY =
 // The discriminant for a dispatch refused because the `in-progress` marker could not be applied, named
 // once rather than inlined at each use.
 const LABEL_UNSET_KIND = 'label-unset'
+const RESTART_START = 'restart'
 // The role a lane child runs under, resolved once so the fresh and resume builders read the same one.
 const RESOLVED_ROLE = agent_role_profile.WORKER
 
@@ -281,13 +282,15 @@ function built_for(plan: ResumePlan, profile: AgentProfile, lane: LaneInfo): Age
 // **The re-dispatch decides resume-or-fresh from the lane's own exit record**.
 // The record is read from the log the previous dispatch of this lane wrote — a first dispatch finds
 // none and starts fresh, an `outage` ending with a session id resumes it. The provider is resolved
-// first because the resume mechanism is Claude Code's, and an OpenAI lane falls back to fresh.
-function prepared(lane: LaneInfo): Prepared {
+// first because the resume mechanism is Claude Code's, and an OpenAI lane falls back to fresh. **A
+// fresh dispatch never reads the record**: a person restarting a child (`lane:restart`) wants a new
+// session that reads the Issue from the start, whatever the previous one ended on.
+function prepared(lane: LaneInfo, is_fresh: boolean): Prepared {
 	const resolved = agent_role_profile.resolve(RESOLVED_ROLE)
 
 	if (resolved.kind === 'rejected') return resolved
 
-	const record = run_ending.read_exit(default_log_path(lane))
+	const record = is_fresh ? undefined : run_ending.read_exit(default_log_path(lane))
 	const plan = lane_resume.plan(lane.issue, record, resolved.profile.provider)
 	const built = built_for(plan, resolved.profile, lane)
 
@@ -333,8 +336,23 @@ async function record_started(issue: string): Promise<void> {
 	await lane_ledger.record_dispatch(Number(issue))
 }
 
-async function finish_dispatch(issue: string, request: StartRequest): Promise<DispatchOutcome> {
-	const mark = await mark_in_progress(issue)
+// How a dispatch begins. A `resumable` one claims the marker itself and resumes an `outage` session; a
+// `restart` is a person's (`lane:restart`): its caller claimed the marker before stopping the old child,
+// so no GitHub round-trip sits between that stop and this launch, and the session starts fresh.
+type DispatchStart = 'resumable' | typeof RESTART_START
+
+async function claimed(issue: string, start: DispatchStart): Promise<LabelWrite> {
+	if (start === RESTART_START) return { is_applied: true }
+
+	return await mark_in_progress(issue)
+}
+
+async function finish_dispatch(
+	issue: string,
+	request: StartRequest,
+	start: DispatchStart,
+): Promise<DispatchOutcome> {
+	const mark = await claimed(issue, start)
 
 	if (!mark.is_applied) return { kind: LABEL_UNSET_KIND, reason: mark.reason }
 	const outcome = await started(request)
@@ -346,14 +364,21 @@ async function finish_dispatch(issue: string, request: StartRequest): Promise<Di
 	return outcome
 }
 
-/** Start `fullrun #<N>` detached in the lane for `#<N>`, recording where it writes as it does so. */
-async function dispatch_child(issue: string): Promise<DispatchOutcome> {
+/**
+ * Start `fullrun #<N>` detached in the lane for `#<N>`, recording where it writes as it does so.
+ * A `restart` start expects the marker already claimed and starts a new session even where the lane's
+ * last ending would resume one.
+ */
+async function dispatch_child(
+	issue: string,
+	start: DispatchStart = 'resumable',
+): Promise<DispatchOutcome> {
 	issue_number_shape.require_issue_number(issue)
 
 	const lane = await lane_registry.find_open_lane(issue)
 
 	if (lane === undefined) return { kind: 'no-lane' }
-	const built = prepared(lane)
+	const built = prepared(lane, start === RESTART_START)
 	const log_path = default_log_path(lane)
 
 	if (built.kind === 'rejected') return { kind: 'failed', lane, log_path, note: built.note }
@@ -362,7 +387,7 @@ async function dispatch_child(issue: string): Promise<DispatchOutcome> {
 
 	if (log.kind !== 'ready') return log
 
-	return await finish_dispatch(issue, { lane, log_path: log.path, ...built })
+	return await finish_dispatch(issue, { lane, log_path: log.path, ...built }, start)
 }
 
 // **A launch whose log could not be opened is still a launch, and the reader has to hear both halves.**
@@ -438,6 +463,7 @@ async function warn_of_problem(outcome: DispatchOutcome, issue: string): Promise
 
 const lane_dispatch = {
 	child_invocation,
+	claim_marker: mark_in_progress,
 	default_log_path,
 	describe,
 	dispatch_child,
@@ -446,5 +472,5 @@ const lane_dispatch = {
 	warn_of_problem,
 }
 
-export type { DispatchOutcome }
+export type { DispatchOutcome, DispatchStart }
 export { lane_dispatch }

package/scripts/lane/lane-environment.ts

@@ -7,7 +7,7 @@ import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role
 // the nearest ancestor holding a `package.json` — which, inside a linked work tree, is the lane's
 // own directory — so a lane with no `.env` runs on seed 0 and a lane handed a verbatim copy of the
 // root's runs on the root's exact offset; either way every lane lands on one pair of ports, and a
-// busy port fails without retrying on another. At the default six lanes that turns E2E from "fails
+// busy port fails without retrying on another. At six lanes that turns E2E from "fails
 // sometimes" into "fails nearly always". So the lane's `.env` keeps the project's `PORT_SEED`
 // unchanged and adds `JOSH_LANE_SEAT`, and `ports/index.js` combines them as `seed × 10 + seat`:
 // the file plainly shows which number is the project's and which is the

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

@@ -6,6 +6,7 @@ import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { execa } from 'execa'
 
 // `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
@@ -73,8 +74,11 @@ async function install(directory: string): Promise<boolean> {
 
 // The first lane pops the shared stash and re-installs against the lock it brought in; a pop that
 // refused (`no-match` / `ambiguous`) stops the lane rather than dispatching onto an unprepared tree.
-// A caller without `--stash` skips both, which is every lane after the first.
-async function prepare(stash: string | undefined, directory: string): Promise<boolean> {
+// A caller without `--stash` skips both, which is every lane after the first. The re-install is a
+// stage of its own on the run's stream, as the install `lane:open` ran was.
+async function prepare(context: LaunchContext, directory: string): Promise<boolean> {
+	const { issue, stash } = context
+
 	if (stash === undefined) return true
 
 	const popped = await josh_command.josh_run(
@@ -84,6 +88,8 @@ async function prepare(stash: string | undefined, directory: string): Promise<bo
 
 	if (popped.code !== SUCCESS_EXIT_CODE) return false
 
+	await run_event_setup.emit(run_event_setup.installing(issue))
+
 	return await install(directory)
 }
 
@@ -124,13 +130,16 @@ async function lane_directory(issue: string): Promise<string | undefined> {
 }
 
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
-// chain.
+// chain. The dispatch is said on the run's stream before it starts, so the board draws a lane that is
+// ready apart from one still being filled.
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 	const directory = await lane_directory(context.issue)
 
 	if (directory === undefined) return UNOPENED
 
-	if (!(await prepare(context.stash, directory))) return FAILED
+	if (!(await prepare(context, directory))) return FAILED
+
+	await run_event_setup.emit(run_event_setup.dispatching(context.issue))
 
 	const dispatched = await josh_command.josh_run(
 		['lane:dispatch', context.issue],

package/scripts/lane/lane-ledger.ts

@@ -5,8 +5,8 @@ import { run_carry } from '#scripts/run/carry/run-carry'
 import { z } from 'zod'
 
 // The measurement ledger the lane limit is tuned against: one JSON line per
-// lane merge, per finished `josh gate`, per machine-load sample, per lane dispatch and per finished
-// `josh ship` stage, read back by `josh lane:stats`.
+// lane merge, per finished `josh gate`, per machine-load sample, per lane dispatch, per finished
+// `josh ship` stage and per stopped `josh ship`, read back by `josh lane:stats`.
 //
 // **Its own file rather than the run's event stream.** The stream is capped at 500 events and is
 // rewritten whole on every append, which is right for "where is the run" and wrong for a measurement
@@ -35,6 +35,7 @@ const KIND = {
 	LOAD: 'load',
 	DISPATCH: 'dispatch',
 	STAGE: 'stage',
+	STOP: 'stop',
 } as const
 
 const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
@@ -79,12 +80,22 @@ const stage_schema = z.object({
 	elapsed_ms: z.number(),
 	issue: z.number().optional(),
 })
+// A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the
+// retrospective's stop reason. How long it stayed stopped is derived from the next ship stage, not
+// recorded, so a resumed ship never has to know the stop it ends.
+const stop_schema = z.object({
+	kind: z.literal(KIND.STOP),
+	at: z.string(),
+	issue: z.number(),
+	reason: z.string(),
+})
 const entry_schema = z.discriminatedUnion('kind', [
 	merge_schema,
 	gate_schema,
 	load_schema,
 	dispatch_schema,
 	stage_schema,
+	stop_schema,
 ])
 
 type LedgerEntry = z.infer<typeof entry_schema>
@@ -93,9 +104,11 @@ type GateEntry = z.infer<typeof gate_schema>
 type LoadEntry = z.infer<typeof load_schema>
 type DispatchEntry = z.infer<typeof dispatch_schema>
 type StageEntry = z.infer<typeof stage_schema>
+type StopEntry = z.infer<typeof stop_schema>
 // What a finished gate reports; the ledger stamps the kind and the time.
 type GateRecord = Omit<GateEntry, 'kind' | 'at'>
 type StageRecord = Omit<StageEntry, 'kind' | 'at'>
+type StopRecord = Omit<StopEntry, 'kind' | 'at'>
 
 function target_of(repository: string): string {
 	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
@@ -168,6 +181,10 @@ async function record_stage(stage: StageRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.STAGE, at: now_iso(), ...stage }, path)
 }
 
+async function record_stop(stop: StopRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.STOP, at: now_iso(), ...stop }, path)
+}
+
 function parse_line(line: string): LedgerEntry | undefined {
 	return entry_schema.safeParse(json_value.parse_or_undefined(line)).data
 }
@@ -199,9 +216,10 @@ const lane_ledger = {
 	record_gate,
 	record_merge,
 	record_stage,
+	record_stop,
 	target,
 	target_of,
 }
 
-export type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry, StageEntry }
+export type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry, StageEntry, StopEntry }
 export { lane_ledger }

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

@@ -7,12 +7,14 @@ import { lane_ledger } from './lane-ledger'
 import { lane_sampler, type MeasureContext } from './lane-sampler'
 import { lane_stage_stats } from './lane-stage-stats'
 import { lane_stats } from './lane-stats'
+import { lane_stop_stats } from './lane-stop-stats'
 
 // `josh lane:sample` / `josh lane:stats` — the lane-limit measurement.
 //
 // `lane:sample` appends one machine-load sample to the ledger, or one every `--every <seconds>` until it
 // is stopped; `lane:stats` reduces a period of the ledger to the one table row #3347 records per lane
-// limit, and under it the per-stage durations of the period's lanes. Every entry writes itself during
+// limit, under it the per-stage durations of the period's lanes, and under those how long a stopped
+// ship waited for each stop reason. Every entry writes itself during
 // a `backlogrun` — the merges, the gates, the stages, and the load `backlog:drive` samples while it
 // runs — so a person only closes the period with `lane:stats`; `lane:sample` is for a load reading
 // outside one. The procedure is `docs/maintainers/lane-limit-measurement.md`.
@@ -112,7 +114,13 @@ async function stats_command(
 	const entries = await read_ledger(context)
 	const row = lane_stats.row(entries, window, label)
 
-	console.info(`${lane_stats.header()}\n${row}\n\n${lane_stage_stats.table(entries, window)}`)
+	console.info(
+		[
+			`${lane_stats.header()}\n${row}`,
+			lane_stage_stats.table(entries, window),
+			lane_stop_stats.table(entries, window),
+		].join('\n\n'),
+	)
 
 	return 0
 }

package/scripts/lane/lane-open.ts

@@ -4,6 +4,7 @@ import { ENV_FILE_NAME } from '#ports'
 import { git_worktree } from '#scripts/git/git-worktree'
 import { session_cite } from '#scripts/issue/session-cite'
 import { file_reader } from '#scripts/lib/read-file'
+import { run_event_setup } from '#scripts/run/event/run-event-setup'
 import { lane_cache } from './lane-cache'
 import { lane_environment } from './lane-environment'
 import { lane_install, type InstallResult } from './lane-install'
@@ -172,6 +173,13 @@ function guard_install(lane: LaneInfo, result: InstallResult): void {
 	)
 }
 
+// **The install is said on the run's stream as it starts**: it is the long part of opening a lane, and
+// `run:board` draws it apart from the work tree being made. Best-effort, as every stage is.
+async function fill(lane: LaneInfo): Promise<void> {
+	await run_event_setup.emit(run_event_setup.installing(lane.issue))
+	guard_install(lane, await lane_install.install_dependencies(lane.directory))
+}
+
 function build_plan(
 	repository_root: string,
 	root: string,
@@ -231,7 +239,7 @@ async function materialize(plan: LanePlan, source_root: string): Promise<void> {
 		release_seat_lock(plan.seat_lock)
 		lane_cache.seed_caches(source_root, plan.lane.directory)
 		lane_cache.seed_hook_bundles(source_root, plan.lane.directory)
-		guard_install(plan.lane, await lane_install.install_dependencies(plan.lane.directory))
+		await fill(plan.lane)
 	} finally {
 		release_seat_lock(plan.seat_lock)
 	}

package/scripts/lane/lane-preserve.ts

@@ -0,0 +1,49 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { git_stash } from '#scripts/git/stash/git-stash'
+
+// Keeping a lane's uncommitted work before something discards or restarts it — `run:merge` closing a
+// lane, `lane:restart` handing it to a fresh session. The stash stack outlives the tree, so the push is
+// the copy, and the comment on the Issue is where a person finds it again. One writer, so the message
+// `stash:pop` matches on and the recovery line the comment names cannot drift between the callers.
+
+function preserved_comment(message: string, cause: string): string {
+	return [
+		`The lane held uncommitted work when ${cause}, so it was stashed:`,
+		`- recover with \`pnpm josh stash:pop "${message}"\``,
+	].join('\n')
+}
+
+/**
+ * Push the lane's uncommitted work under `<issue>: uncommitted work at <occasion>`, and return the
+ * message. A push that fails throws, so the caller keeps the tree rather than losing it.
+ */
+async function push_work(issue: string, directory: string, occasion: string): Promise<string> {
+	const message = git_stash.work_message(issue, occasion)
+
+	await git_stash.push(message, directory)
+
+	return message
+}
+
+/** Say on the Issue where the stash `message` went, `cause` completing "when …". Never throws. */
+async function announce(issue: string, message: string, cause: string): Promise<void> {
+	await git_gh_issue_write.issue_try_comment(issue, preserved_comment(message, cause))
+}
+
+/** `push_work`, then `announce` — for a caller with no reason to separate the two. */
+async function stash_work(
+	issue: string,
+	directory: string,
+	occasion: string,
+	cause: string,
+): Promise<string> {
+	const message = await push_work(issue, directory, occasion)
+
+	await announce(issue, message, cause)
+
+	return message
+}
+
+const lane_preserve = { announce, push_work, stash_work }
+
+export { lane_preserve }

package/scripts/lane/lane-reap.ts

@@ -1,6 +1,7 @@
 import { execFileSync } from 'node:child_process'
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { lane_child_invocation } from './lane-child-invocation'
+import { process_tools } from './process-tools'
 
 // Ending a lane child that did not end itself.
 //
@@ -42,7 +43,9 @@ function parse_pids(printed: string): Array<number> {
 		.filter((pid) => Number.isSafeInteger(pid) && pid >= LOWEST_CHILD_PID)
 }
 
-// `pgrep` exits 1 when nothing matches, which `execFileSync` throws — the empty list either way.
+// `pgrep` exits 1 when nothing matches, which `execFileSync` throws — the empty list either way. A
+// probe that is not installed is refused by name: reading it as "nothing there" is how a missing `ps`
+// left the owner check answering `unknown`.
 function run_probe(command: string, args: ReadonlyArray<string>): string {
 	try {
 		return execFileSync(command, [...args], {
@@ -50,7 +53,9 @@ function run_probe(command: string, args: ReadonlyArray<string>): string {
 			timeout: PROBE_TIMEOUT_MS,
 			stdio: ['ignore', 'pipe', 'ignore'],
 		})
-	} catch {
+	} catch (error) {
+		process_tools.throw_if_missing(command, error)
+
 		return ''
 	}
 }
@@ -111,6 +116,12 @@ function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number
 	return tree
 }
 
+function roots_of(issue: string, own: Set<number>, probes: ReapProbes): Array<number> {
+	const pattern = lane_child_invocation.process_pattern(issue)
+
+	return probes.matching(pattern).filter((pid) => !own.has(pid))
+}
+
 /**
  * Terminate every process of the lane child for `issue` and everything under it, sparing the caller's
  * own ancestry. Returns the pids that were signalled — the empty list is the healthy case, a child
@@ -118,14 +129,18 @@ function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number
  */
 function reap_child(issue: string, probes: ReapProbes = SYSTEM_PROBES): Array<number> {
 	const own = own_ancestry(probes)
-	const pattern = lane_child_invocation.process_pattern(issue)
-	const roots = probes.matching(pattern).filter((pid) => !own.has(pid))
-	const doomed = tree_of(roots, probes).filter((pid) => !own.has(pid))
+	const doomed = tree_of(roots_of(issue, own, probes), probes).filter((pid) => !own.has(pid))
 
 	return doomed.filter((pid) => probes.terminate(pid))
 }
 
+/** Whether a lane child for `issue` is running, by the same match `reap_child` would end. */
+function is_child_running(issue: string, probes: ReapProbes = SYSTEM_PROBES): boolean {
+	return roots_of(issue, own_ancestry(probes), probes).length > 0
+}
+
 const lane_reap = {
+	is_child_running,
 	own_ancestry,
 	parse_pids,
 	reap_child,

package/scripts/lane/lane-registry.ts

@@ -236,6 +236,11 @@ async function has_lanes_in_flight(): Promise<boolean> {
 	return lanes.some((lane) => !lane.is_stranded)
 }
 
+/** The lanes in use: the open work trees an interruption has not stranded. */
+function live_count(lanes: ReadonlyArray<LaneInfo>): number {
+	return lanes.filter((lane) => !lane.is_stranded).length
+}
+
 /** 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)
@@ -267,6 +272,7 @@ const lane_registry = {
 	find_open_lane,
 	has_lanes_in_flight,
 	list_lanes,
+	live_count,
 	main_repository_root,
 	parse_block,
 	read_environment,