@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/lane/lane-report.ts

@@ -1,9 +1,10 @@
 import { agent_role_profile } from '#scripts/agent/agent-role-profile'
 import { issue_cite, type IssueCiter } from '#scripts/issue/issue-cite'
+import { session_cite } from '#scripts/issue/session-cite'
 import { run_liveness } from '#scripts/run/run-liveness'
 import type { LaneInfo } from './lane-registry'
 
-// What a person reads when they ask what is open (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+// What a person reads when they ask what is open.
 //
 // The dev and preview ports are the ones the registry already resolved through `ports/index.js`
 // when it read each lane's `.env`, so the numbers printed here are the same ones `josh port` and
@@ -31,7 +32,7 @@ function value_or_unknown(value: number | undefined): string {
 }
 
 // The recorded output path goes last and is labelled, so it is told apart from the directory beside
-// it (joshuafolkken/kit#1713). A lane that records none prints `output -` rather than nothing at
+// it. A lane that records none prints `output -` rather than nothing at
 // all: a session that did not open the lane has to be able to see that the record is missing, not
 // read a shorter row as one field it failed to notice.
 function output_column(output: string | undefined): string {
@@ -52,7 +53,7 @@ function event_column(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
+// The issue leads as a citation: 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 [
@@ -84,7 +85,7 @@ function describe_ports(lane: LaneInfo): string {
 // The one-line confirmation a person reads on standard error while standard output carries the
 // directory alone, so `dir=$(pnpm josh lane:open 1490)` stays usable.
 function describe_opened(lane: LaneInfo): string {
-	return `Opened a lane for #${lane.issue} on ${lane.branch}: ${describe_ports(lane)}.`
+	return `Opened a lane for ${session_cite.issue(lane.issue)} on ${lane.branch}: ${describe_ports(lane)}.`
 }
 
 const lane_report = {

package/scripts/lane/lane-resume.ts

@@ -3,8 +3,8 @@ import { api_outage } from '#scripts/agent/api-outage'
 import type { ClaudeResultEvent } from '#scripts/agent/claude-result-event'
 import { lane_child_invocation } from './lane-child-invocation'
 
-// How a lane re-dispatch chooses between resuming the disconnected child's session and starting fresh
-// (joshuafolkken/kit#2317). The premise the whole issue rests on: a child that could not reach the API
+// How a lane re-dispatch chooses between resuming the disconnected child's session and starting fresh.
+// The premise the whole issue rests on: a child that could not reach the API
 // left a `session_id` in its exit record, and re-dispatching it as a bare `fullrun #<N>` threw that
 // context away — a resumed child keeps it and loses only the last round-trip.
 //

package/scripts/lane/lane-sampler.ts

@@ -0,0 +1,55 @@
+import { lane_ledger } from './lane-ledger'
+import { lane_load } from './lane-load'
+
+// The machine-load sampler: one `load` entry appended to the lane ledger, once or on a timer.
+//
+// **`start` is how a `backlogrun` samples itself.** `backlog:drive` starts it for as long as its loop
+// runs, so a period needs nobody to remember a second terminal — the sampler `josh lane:sample` offers
+// was started by hand, and a run nobody started it beside recorded no load at all. The timer lives in
+// the drive's own process and is unreferenced: it ends with the drive, never holds it open, and leaves
+// no process or pid file behind to stop.
+
+const SAMPLE_INTERVAL_MS = 60_000
+
+// Where the ledger is and what "now" is, overridable so a test reads a fixed ledger at a fixed instant.
+interface MeasureContext {
+	ledger_path?: string
+	now_ms?: number
+}
+
+async function take(context: MeasureContext = {}): Promise<void> {
+	const at = new Date(context.now_ms ?? Date.now()).toISOString()
+
+	await lane_ledger.record(await lane_load.sample(at), context.ledger_path)
+}
+
+// A timer tick has no caller to raise into, and a sample that could not be read must never end the run
+// it measures.
+async function take_quietly(context: MeasureContext): Promise<void> {
+	try {
+		await take(context)
+	} catch {
+		// Best-effort: an unread sample is a gap in the measurement, not a failure of the run.
+	}
+}
+
+/** Sample now and then every minute; the returned function stops it. */
+function start(context: MeasureContext = {}): () => void {
+	void take_quietly(context)
+	const timer = setInterval(() => {
+		void take_quietly(context)
+	}, SAMPLE_INTERVAL_MS).unref()
+
+	return () => {
+		clearInterval(timer)
+	}
+}
+
+const lane_sampler = {
+	SAMPLE_INTERVAL_MS,
+	start,
+	take,
+}
+
+export type { MeasureContext }
+export { lane_sampler }

package/scripts/lane/lane-seed.ts

@@ -1,13 +1,13 @@
-// Which seat a lane gets (joshuafolkken/kit#1490, joshuafolkken/kit#1494).
+// Which seat a lane gets.
 
 // **The main work tree is seat 0, and nothing here can move it.** Lanes take seats 1..9, so a
 // project that has never opened one stays on exactly the ports `ports/index.js` already gives it —
 // `seed × 10` for its seed, the bases themselves for an unset seed, which is what CI runs on.
 const FIRST_LANE_SEAT = 1
-// **Nine seats, because the seat is the units digit of the offset `seed × 10 + lane`.** The seat no
-// longer carries the whole port band — the seed does, multiplied by ten — so a lane holds a single
-// seat number rather than an absolute seed, and there is no ceiling to check and no "multiple of
-// ten" convention for anyone to break (joshuafolkken/kit#1494 removed the band mechanism).
+// **Nine seats, because the seat is the units digit of the offset `seed × 10 + lane`.** The seed,
+// multiplied by ten, carries the port band rather than the seat, so a lane holds a single seat number
+// rather than an absolute seed, and there is no ceiling to check and no "multiple of ten" convention
+// for anyone to break.
 const LAST_LANE_SEAT = 9
 
 /**
@@ -20,8 +20,8 @@ const LAST_LANE_SEAT = 9
  * wrapped, because wrapping is that same collision under a friendlier name.
  *
  * The whole ascending list is returned rather than only the lowest, because the caller claims each
- * seat atomically and steps to the next when a concurrent `lane:open` claimed it first
- * (joshuafolkken/kit#1494): reading a free set and picking from it are two moments, and the gap
+ * seat atomically and steps to the next when a concurrent `lane:open` claimed it first:
+ * reading a free set and picking from it are two moments, and the gap
  * between them is where two opens once chose the same seat.
  */
 function free_seats(used: ReadonlyArray<number>): Array<number> {

package/scripts/lane/lane-stage-stats.ts

@@ -0,0 +1,135 @@
+import { run_ship_stage } from '#scripts/run/ship/run-ship-stage'
+import { lane_ledger, type DispatchEntry, type LedgerEntry, type StageEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// Where a lane's time goes: the ledger's `stage` and `dispatch` entries of one period reduced to one
+// row per stage — median, maximum and how many runs — printed by `josh lane:stats` under the lane-limit
+// row. The rows are in the order a lane passes them.
+//
+// **A stage nothing recorded prints `not measured`, never `0`.** A period that ran no second review
+// round has no `round-2` duration, which is not a round that took no time.
+//
+// **`implement` is derived, not recorded**: from a lane's dispatch to the start of the first ship stage
+// of the same issue that followed it. Nothing has to know, at the hand-off, when the child was
+// dispatched, and a ship resumed after a fix cannot record the implementation twice.
+//
+// **`ci-wait` is `followup`'s own lap, inside the `followup` stage** — a row of its own so the wait for
+// CI reads beside `review`, the round-one review it would overlap.
+
+const MS_PER_MINUTE = 60_000
+const DECIMALS = 1
+const NOT_MEASURED = 'not measured'
+const IMPLEMENT = 'implement'
+const COLUMNS = ['stage', 'median (min)', 'max (min)', 'runs'] as const
+const { STAGE } = run_ship_stage
+const STAGES = [
+	IMPLEMENT,
+	STAGE.PREFLIGHT,
+	STAGE.REVIEW,
+	STAGE.SYNC,
+	STAGE.GATE,
+	STAGE.COMMIT,
+	STAGE.ROUND_TWO,
+	STAGE.FOLLOWUP,
+	lane_ledger.CI_WAIT_STAGE,
+	STAGE.REPORT,
+] as const
+
+interface Measured {
+	implement: ReadonlyArray<number>
+	stages: ReadonlyArray<StageEntry>
+}
+
+function is_stage(entry: LedgerEntry): entry is StageEntry {
+	return entry.kind === lane_ledger.KIND.STAGE
+}
+
+function is_dispatch(entry: LedgerEntry): entry is DispatchEntry {
+	return entry.kind === lane_ledger.KIND.DISPATCH
+}
+
+function is_number(value: number | undefined): value is number {
+	return value !== undefined
+}
+
+function started_ms(stage: StageEntry): number {
+	return Date.parse(stage.at) - stage.elapsed_ms
+}
+
+// When the same issue was dispatched again, or never: a child that died before its ship must not have
+// its implementation stretched to the ship of the child that replaced it.
+function next_dispatch_ms(sorted: ReadonlyArray<DispatchEntry>, index: number): number {
+	const next = sorted.slice(index + 1).find((entry) => entry.issue === sorted[index]?.issue)
+
+	return next === undefined ? Infinity : Date.parse(next.at)
+}
+
+function implement_ms(
+	dispatch: DispatchEntry,
+	until_ms: number,
+	stages: ReadonlyArray<StageEntry>,
+): number | undefined {
+	const from_ms = Date.parse(dispatch.at)
+	const starts = stages
+		.filter((stage) => stage.issue === dispatch.issue)
+		.map((stage) => started_ms(stage))
+		.filter((start) => start >= from_ms && start < until_ms)
+
+	return starts.length === 0 ? undefined : Math.min(...starts) - from_ms
+}
+
+function implement_durations(
+	dispatches: ReadonlyArray<DispatchEntry>,
+	stages: ReadonlyArray<StageEntry>,
+): Array<number> {
+	const sorted = dispatches.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+
+	return sorted
+		.map((dispatch, index) => implement_ms(dispatch, next_dispatch_ms(sorted, index), stages))
+		.filter(is_number)
+}
+
+function durations_of(stage: string, measured: Measured): ReadonlyArray<number> {
+	if (stage === IMPLEMENT) return measured.implement
+
+	return measured.stages.filter((entry) => entry.stage === stage).map((entry) => entry.elapsed_ms)
+}
+
+function cell(milliseconds: number | undefined): string {
+	return milliseconds === undefined
+		? NOT_MEASURED
+		: (milliseconds / MS_PER_MINUTE).toFixed(DECIMALS)
+}
+
+function stage_row(stage: string, measured: Measured): string {
+	const durations = durations_of(stage, measured)
+
+	return lane_stats.to_row([
+		stage,
+		cell(lane_stats.median(durations)),
+		cell(lane_stats.peak(durations)),
+		String(durations.length),
+	])
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const period = lane_stats.in_window(entries, window)
+	const stages = period.filter(is_stage)
+	const measured = { implement: implement_durations(period.filter(is_dispatch), stages), stages }
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...STAGES.map((stage) => stage_row(stage, measured)),
+	].join('\n')
+}
+
+const lane_stage_stats = {
+	IMPLEMENT,
+	NOT_MEASURED,
+	STAGES,
+	table,
+}
+
+export { lane_stage_stats }

package/scripts/lane/lane-start-point.ts

@@ -1,15 +1,14 @@
 import { git_command } from '#scripts/git/git-command'
 import { git_remote_branch } from '#scripts/git/git-remote-branch'
 
-// Where a lane is cut from (joshuafolkken/kit#1535).
+// Where a lane is cut from.
 //
 // **The bare default-branch name is the wrong start point, because git resolves it to the *local*
 // `refs/heads/<default>` — a ref nothing in this workflow ever advances.** Merges happen on GitHub
 // through `pnpm josh followup`, and this repository's main work tree does not have the
 // default branch checked out, so there is no fast-forward for it to receive. It falls one commit
 // further behind on every merge, and a lane opened from it starts without the work that was just
-// merged. Measured on 2026-09-07: `refs/heads/main` was `e3a68c04` while `refs/remotes/origin/main`
-// was `78f746f9`.
+// merged.
 //
 // **The remote-tracking ref is the one that is current**, because a fetch updates it without anyone
 // checking anything out — which is exactly the property the local branch lacks. It is named in full
@@ -20,9 +19,9 @@ const REFS_REMOTES_ORIGIN_PREFIX = 'refs/remotes/origin/'
 
 // A fetch *failure* is reported and stepped over rather than raised. `lane:open` has to keep working
 // with no network at all — offline, and on a clone with no `origin` — and what it degrades to is
-// whatever `origin/<default>` already holds, which is still never *behind* the local branch. Note
-// what this does not cover: `fetch_branch` runs through `git_spawn.read`, which sets no
-// timeout, so a connection that hangs rather than failing blocks here instead of degrading.
+// whatever `origin/<default>` already holds, which is still never *behind* the local branch. A
+// connection that hangs rather than failing degrades the same way: `fetch_branch` runs through
+// `git_spawn.read_remote`, whose budget ends the wait as a failure.
 async function refresh_default_branch(default_branch: string): Promise<void> {
 	try {
 		await git_command.fetch_branch(default_branch)
@@ -65,7 +64,7 @@ async function resolve(): Promise<string> {
 	return start_point
 }
 
-// **A branch that already exists is attached to, never cut afresh** (joshuafolkken/kit#1627). Its
+// **A branch that already exists is attached to, never cut afresh**. Its
 // commits are a child's finished work: `epicrun` leaves a lane's branch behind whenever a child is
 // parked after pushing, and `lane:close` deletes the local branch while the remote one and the pull
 // request stay. Cutting a new `<N>-lane` from the default branch there orphans both — and it did so
@@ -130,8 +129,7 @@ async function present_reference(branch_name: string): Promise<string> {
 
 // `absent` is the one answer that refuses the ref: the branch is gone from origin, so a ref still
 // pointing at it is stale and the lane is cut from the default branch as any new one is. Why origin
-// itself is asked rather than the remote-tracking ref is `git_remote_branch`'s own comment
-// (joshuafolkken/kit#1641 moved the asking there, so `pnpm josh release` could reuse it).
+// itself is asked rather than the remote-tracking ref is `git_remote_branch`'s own comment.
 async function remote_reference_for(branch_name: string): Promise<string | undefined> {
 	const answer = await git_remote_branch.ask(branch_name)
 
@@ -148,8 +146,7 @@ async function remote_reference_for(branch_name: string): Promise<string | undef
  *
  * `undefined` means **attach**: the branch is already here, so the work tree is put on it and no
  * branch is created. Every other answer is a commit-ish a new branch is cut from — the remote-tracking
- * ref of the lane branch when only the remote has it, and the default branch's when neither does,
- * which is the behavior every lane had before joshuafolkken/kit#1627.
+ * ref of the lane branch when only the remote has it, and the default branch's when neither does.
  *
  * **Nothing here deletes a branch to simplify the call.** That is what would lose the commits this
  * function exists to keep.

package/scripts/lane/lane-stats.ts

@@ -1,6 +1,8 @@
+import { machine_capacity } from '#scripts/gate/machine-capacity'
 import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
+import { lane_sampler } from './lane-sampler'
 
-// The lane-limit measurement's one table row (joshuafolkken/kit#3355): the ledger entries of one period
+// The lane-limit measurement's one table row: the ledger entries of one period
 // reduced to throughput, gate duration and machine load, in the column order
 // `docs/maintainers/lane-limit-measurement.md` documents, so the row pastes into #3347's table as is.
 //
@@ -15,6 +17,9 @@ import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
 //
 // **The means take working samples only** for the same reason: the sampler runs through the nights,
 // and their idle samples would read four busy lanes as about one. Peaks and minima take every sample.
+//
+// **Swap is a rate, not a level.** A sample carries `machine_capacity`'s counter — every page swapped
+// since boot — so the swap columns are what was swapped between consecutive samples, per hour.
 
 const MS_PER_MINUTE = 60_000
 const MS_PER_HOUR = 3_600_000
@@ -23,6 +28,8 @@ const ACTIVE_GAP_MS = MS_PER_HOUR
 const MS_PER_DAY = 86_400_000
 const MB_PER_GB = 1024
 const HALF = 2
+// Half the sampler's interval: two samples closer than this are not one interval apart.
+const MIN_RATE_GAP_MS = lane_sampler.SAMPLE_INTERVAL_MS / HALF
 const DECIMALS = 1
 const MISSING = '—'
 const CELL_SEPARATOR = ' | '
@@ -37,8 +44,8 @@ const COLUMNS = [
 	'gate max (min)',
 	'load peak',
 	'load mean',
-	'swap peak (GB)',
-	'swap mean (GB)',
+	'swapped peak (GB/h)',
+	'swapped mean (GB/h)',
 	'free memory min (GB)',
 	'free memory mean (GB)',
 	'load samples',
@@ -107,6 +114,22 @@ function is_working(sample: LoadEntry): sample is WorkingEntry {
 	return (sample.lanes ?? 0) > 0
 }
 
+interface SamplePair {
+	sample: LoadEntry
+	next: LoadEntry
+}
+
+// Each sample beside the one that followed it, in time order.
+function sample_pairs(samples: ReadonlyArray<LoadEntry>): Array<SamplePair> {
+	const sorted = samples.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+
+	return sorted.slice(1).map((next, index) => ({ sample: sorted[index] ?? next, next }))
+}
+
+function elapsed_ms({ sample, next }: SamplePair): number {
+	return Date.parse(next.at) - Date.parse(sample.at)
+}
+
 function sum_hours(gaps: ReadonlyArray<number>): number | undefined {
 	const active = gaps.filter((gap) => gap <= ACTIVE_GAP_MS).reduce((sum, gap) => sum + gap, 0)
 
@@ -117,7 +140,7 @@ function sum_hours(gaps: ReadonlyArray<number>): number | undefined {
 // and gates) no longer than `ACTIVE_GAP_MS`.
 function gap_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
 	const instants = entries
-		.filter((entry) => !is_load(entry))
+		.filter((entry) => entry.kind === 'merge' || is_gate(entry))
 		.map((entry) => Date.parse(entry.at))
 		.toSorted((left, right) => left - right)
 
@@ -129,16 +152,27 @@ function gap_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
 // The time from each working sample to the next sample. The cap still applies, so a sampler stopped
 // mid-run does not count its silence as work.
 function sampled_hours(samples: ReadonlyArray<LoadEntry>): number | undefined {
-	const sorted = samples.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
-	const gaps = sorted
-		.slice(1)
-		.map((next, index) => ({ sample: sorted[index] ?? next, next }))
+	const gaps = sample_pairs(samples)
 		.filter(({ sample }) => is_working(sample))
-		.map(({ sample, next }) => Date.parse(next.at) - Date.parse(sample.at))
+		.map((pair) => elapsed_ms(pair))
 
 	return sum_hours(gaps)
 }
 
+// The GB swapped per hour from one sample to the next. `swapped_mb` is a counter, so only a difference
+// says anything; a gap past `ACTIVE_GAP_MS` is a stopped sampler, whose silence is no rate. A gap under
+// `MIN_RATE_GAP_MS` is no rate either: a drive restarted seconds after its last sample, or a second
+// sampler beside it, would stretch a few seconds' burst to an hour and own the peak.
+function swap_rate(pair: SamplePair): number | undefined {
+	const swapped = machine_capacity.swapped_between(pair.sample.swapped_mb, pair.next.swapped_mb)
+	const elapsed = elapsed_ms(pair)
+	const is_one_interval = elapsed >= MIN_RATE_GAP_MS && elapsed <= ACTIVE_GAP_MS
+
+	if (swapped === undefined || !is_one_interval) return undefined
+
+	return swapped / MB_PER_GB / (elapsed / MS_PER_HOUR)
+}
+
 // The hours work was under way; `undefined` when nothing leaves any active time.
 function active_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
 	const samples = entries.filter(is_load)
@@ -172,18 +206,26 @@ function gate_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
 	return [cell(median(minutes)), cell(peak(minutes))]
 }
 
+function swap_cells(samples: ReadonlyArray<LoadEntry>): Array<string> {
+	const pairs = sample_pairs(samples)
+	const rates = pairs.map((pair) => swap_rate(pair)).filter(is_number)
+	const working_rates = pairs
+		.filter(({ sample }) => is_working(sample))
+		.map((pair) => swap_rate(pair))
+		.filter(is_number)
+
+	return [cell(peak(rates)), cell(mean(working_rates))]
+}
+
 function load_cells(samples: ReadonlyArray<LoadEntry>): Array<string> {
 	const working = samples.filter(is_working)
-	const swap = samples.map((sample) => sample.swap_mb).filter(is_number)
-	const working_swap = working.map((sample) => sample.swap_mb).filter(is_number)
-	const free = samples.map((sample) => sample.free_mb)
-	const working_free = working.map((sample) => sample.free_mb)
+	const free = samples.map((sample) => sample.available_mb).filter(is_number)
+	const working_free = working.map((sample) => sample.available_mb).filter(is_number)
 
 	return [
 		cell(peak(samples.map((sample) => sample.load))),
 		cell(mean(working.map((sample) => sample.load))),
-		cell(gigabytes(peak(swap))),
-		cell(gigabytes(mean(working_swap))),
+		...swap_cells(samples),
 		cell(gigabytes(lowest(free))),
 		cell(gigabytes(mean(working_free))),
 		String(samples.length),
@@ -215,8 +257,11 @@ const lane_stats = {
 	COLUMNS,
 	MISSING,
 	header,
+	in_window,
 	median,
+	peak,
 	row,
+	to_row,
 	window_of,
 }
 

package/scripts/lane/lane-stray.ts

@@ -0,0 +1,140 @@
+import { existsSync, lstatSync, readdirSync, rmSync } from 'node:fs'
+import path from 'node:path'
+import { error_text } from '#scripts/lib/error-message'
+import { lane_leftover } from './lane-leftover'
+import { lane_open } from './lane-open'
+import { lane_paths } from './lane-paths'
+import { lane_registry } from './lane-registry'
+
+// What the lanes root holds that no registered work tree accounts for.
+//
+// **Every other sweep starts from `git worktree list`**, so a directory whose registration is gone —
+// a lane whose `rmSync` stopped half-way, one whose `.git` points at a registration git pruned, an
+// empty lanes root a lane once nested inside itself — is invisible to all of them, and stays on disk
+// for good. This reads the root itself.
+//
+// **A stray is removed only when removing it loses nothing** — `lane_leftover.foreign_paths`, the one
+// test `lane:open`'s reclaim also applies. One that holds anything else is kept and reported with what
+// it holds; so is every entry whose name the lane machinery never writes, because nothing here knows
+// who put it there. The root's own `.seat-locks` and every registered work tree are not strays.
+
+type StrayVerdict = 'foreign' | 'not-a-lane' | 'opening' | 'removed' | 'stuck' | 'unreadable'
+
+interface Stray {
+	path: string
+	verdict: StrayVerdict
+	// The paths inside it whose removal would lose something — only on `foreign`.
+	foreign: Array<string>
+}
+
+function stray_names(root: string, registered: ReadonlySet<string>): Array<string> {
+	if (!existsSync(root)) return []
+
+	return readdirSync(root).filter(
+		(name) => name !== lane_paths.SEAT_LOCK_DIR && !registered.has(path.join(root, name)),
+	)
+}
+
+function is_lane_directory(directory: string): boolean {
+	return lane_paths.is_lane_entry(path.basename(directory)) && lstatSync(directory).isDirectory()
+}
+
+// A removal that stops part-way is judged by what is left, exactly as `lane:close` judges its own —
+// and what is left is a stray the next sweep reads again.
+function remove(directory: string): StrayVerdict {
+	try {
+		rmSync(directory, { force: true, recursive: true })
+	} catch (error) {
+		error_text.trace_swallowed('lane_stray.remove', error)
+	}
+
+	return existsSync(directory) ? 'stuck' : 'removed'
+}
+
+// **A `lane:open` in flight holds a seat lock from before its `worktree add` until after the
+// registration**, so while any lock is held a numbered directory may be a lane being created, not a
+// leftover — it is kept, and the next sweep reads it again.
+interface SweepContext {
+	recoverable: ReadonlySet<string>
+	is_opening: boolean
+}
+
+function judge(directory: string, context: SweepContext): Stray {
+	if (!is_lane_directory(directory)) return { path: directory, verdict: 'not-a-lane', foreign: [] }
+	if (context.is_opening) return { path: directory, verdict: 'opening', foreign: [] }
+
+	const foreign = lane_leftover.foreign_paths(directory, context.recoverable)
+
+	if (foreign.length > 0) return { path: directory, verdict: 'foreign', foreign }
+
+	return { path: directory, verdict: remove(directory), foreign: [] }
+}
+
+// One stray that cannot be read — a permission, a file vanishing mid-walk — is kept and reported
+// rather than thrown, so it never stops the sweep of the rest.
+function judge_safely(directory: string, context: SweepContext): Stray {
+	try {
+		return judge(directory, context)
+	} catch (error) {
+		error_text.trace_swallowed('lane_stray.judge', error)
+
+		return { path: directory, verdict: 'unreadable', foreign: [] }
+	}
+}
+
+/** Remove the lanes root's unregistered leftovers that hold nothing worth keeping; report the rest. */
+async function sweep_strays(): Promise<Array<Stray>> {
+	const root = lane_paths.lane_root(await lane_registry.main_repository_root())
+	const registered = new Set(await lane_registry.registered_directories())
+	const names = stray_names(root, registered)
+
+	if (names.length === 0) return []
+
+	const context: SweepContext = {
+		recoverable: await lane_leftover.recoverable_objects(),
+		is_opening: lane_open.open_in_flight_count(root) > 0,
+	}
+
+	return names.map((name) => judge_safely(path.join(root, name), context))
+}
+
+// The foreign paths a report names before it summarizes the rest as a count.
+const NAMED_PATH_LIMIT = 5
+
+function named_paths(foreign: ReadonlyArray<string>): string {
+	const rest = foreign.length - NAMED_PATH_LIMIT
+	const more = rest > 0 ? ` and ${String(rest)} more` : ''
+
+	return `${foreign.slice(0, NAMED_PATH_LIMIT).join(', ')}${more}`
+}
+
+const KEPT_REASONS: Record<Exclude<StrayVerdict, 'foreign' | 'removed'>, string> = {
+	'not-a-lane': 'not a name the lane machinery writes, so it was left alone',
+	opening:
+		'a `lane:open` holds a seat lock and this may be its lane; the next sweep reads it again — if no `lane:open` is running, the lock outlived a crash: remove the lanes root `.seat-locks` directory',
+	stuck: 'the removal did not finish; the next `pnpm josh lane:prune` tries again',
+	unreadable: 'it could not be read, so it was left in place',
+}
+
+/** One line per stray, for standard error. */
+function describe(stray: Stray): string {
+	if (stray.verdict === 'removed') return `Removed unregistered lane leftover ${stray.path}.`
+
+	if (stray.verdict === 'foreign') {
+		return `Kept ${stray.path}: it holds files git cannot restore (${named_paths(stray.foreign)}). Move them out and delete the directory.`
+	}
+
+	return `Kept ${stray.path}: ${KEPT_REASONS[stray.verdict]}.`
+}
+
+/** Sweep, and say on standard error what was removed and what was kept. */
+async function sweep_and_report(): Promise<void> {
+	const strays = await sweep_strays()
+
+	for (const stray of strays) console.error(describe(stray))
+}
+
+const lane_stray = { describe, sweep_and_report, sweep_strays }
+
+export type { Stray, StrayVerdict }
+export { lane_stray }

package/scripts/lane/lane-vacant.ts

@@ -3,7 +3,7 @@ import { run_hold } from '#scripts/run/hold/run-hold'
 import { lane_await } from './lane-await'
 import type { LaneInfo } from './lane-registry'
 
-// Whether an open lane holds nothing worth keeping (joshuafolkken/kit#3289): no commit on its branch
+// Whether an open lane holds nothing worth keeping: no commit on its branch
 // beyond the default branch, a clean work tree, and no child or ship supervisor alive for its issue. A
 // `backlogrun` cut between `lane:open` and `lane:dispatch` leaves exactly such a lane, and `lane:open`
 // refuses it as `already-open` — so the next launch of that issue failed on a lane with nothing in it.

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

@@ -1,4 +1,5 @@
 import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
 
 const DECISION_PREFIX = 'josh-openai-lane-supervisor-decision-'
@@ -16,14 +17,9 @@ function target(lane_directory: string, nonce: string): string {
 }
 
 function read(lane_directory: string, nonce: string): Decision | undefined {
-	try {
-		const raw = stamp_file.read_stamp_text(target(lane_directory, nonce)) ?? ''
-		const value: unknown = JSON.parse(raw)
+	const raw = stamp_file.read_stamp_text(target(lane_directory, nonce)) ?? ''
 
-		return schema.parse(value)
-	} catch {
-		return undefined
-	}
+	return json_value.parse_with(raw, schema)
 }
 
 function decide(lane_directory: string, nonce: string, decision: Decision['decision']): boolean {