@joshuafolkken/kit 1.1178.0 → 1.1240.0

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env tsx
+import { setInterval as every } from 'node:timers/promises'
+import { fileURLToPath } from 'node:url'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { lane_capacity } from './lane-capacity'
+import { lane_ledger } from './lane-ledger'
+import { lane_load } from './lane-load'
+import { lane_stats } from './lane-stats'
+
+// `josh lane:sample` / `josh lane:stats` — the lane-limit measurement (joshuafolkken/kit#3355).
+//
+// `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. The merges and the gates write themselves (`run:merge`, `josh gate`), so a person runs only
+// the sampler beside a `backlogrun` and closes the period with `lane:stats`. The procedure is
+// `docs/maintainers/lane-limit-measurement.md`.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const MS_PER_SECOND = 1000
+const SAMPLE_VERB = 'sample'
+const STATS_VERB = 'stats'
+const USAGE = [
+	'Usage: josh lane:sample [--every <seconds>]',
+	'       josh lane:stats --period <days> [--limit <lane-limit>]',
+].join('\n')
+
+const SAMPLE_OPTIONS = { every: { type: 'string' } } as const
+const STATS_OPTIONS = { period: { type: 'string' }, limit: { type: 'string' } } as const
+
+// 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
+}
+
+function refuse(): number {
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+// A positive finite number, or `undefined` for anything else — a typo must not become a zero period.
+function positive(text: string | undefined): number | undefined {
+	const value = Number(text)
+
+	return text !== undefined && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+async function take_sample(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)
+}
+
+// The `--every` interval: `{ seconds: undefined }` for a single sample, `undefined` for a refusal.
+function sample_interval(rest: ReadonlyArray<string>): { seconds: number | undefined } | undefined {
+	const values = cli_flags.values_of(rest, SAMPLE_OPTIONS)
+
+	if (values === undefined) return undefined
+
+	if (values.every === undefined) return { seconds: undefined }
+
+	const seconds = positive(values.every)
+
+	return seconds === undefined ? undefined : { seconds }
+}
+
+// A sample every `seconds` until a person stops the process, which is how a measurement period is held
+// open; it never returns.
+async function keep_sampling(context: MeasureContext, seconds: number): Promise<void> {
+	const ticks = every(seconds * MS_PER_SECOND, context)
+
+	for await (const tick_context of ticks) await take_sample(tick_context)
+}
+
+// One sample now, then — with `--every` — one per interval.
+async function sample_command(
+	rest: ReadonlyArray<string>,
+	context: MeasureContext,
+): Promise<number> {
+	const interval = sample_interval(rest)
+
+	if (interval === undefined) return refuse()
+
+	await take_sample(context)
+
+	if (interval.seconds !== undefined) await keep_sampling(context, interval.seconds)
+
+	return 0
+}
+
+// The label defaults to the limit this process reads, which is the period's limit only when nobody
+// changed it since — `--limit` names it outright.
+function limit_label(given: string | undefined): string {
+	if (given !== undefined) return given
+
+	const choice = lane_capacity.lane_limit()
+
+	return choice.kind === 'limit' ? String(choice.limit) : lane_stats.MISSING
+}
+
+async function read_ledger(
+	context: MeasureContext,
+): Promise<ReturnType<typeof lane_ledger.read_entries>> {
+	const path = context.ledger_path ?? (await lane_ledger.target())
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+async function stats_command(
+	rest: ReadonlyArray<string>,
+	context: MeasureContext,
+): Promise<number> {
+	const values = cli_flags.values_of(rest, STATS_OPTIONS)
+	const period_days = positive(values?.period)
+
+	if (values === undefined || period_days === undefined) return refuse()
+
+	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
+	const label = { limit: limit_label(values.limit), period_days }
+	const row = lane_stats.row(await read_ledger(context), window, label)
+
+	console.info(`${lane_stats.header()}\n${row}`)
+
+	return 0
+}
+
+async function run(argv: ReadonlyArray<string>, context: MeasureContext = {}): Promise<number> {
+	const [verb, ...rest] = argv
+
+	if (verb === SAMPLE_VERB) return await sample_command(rest, context)
+
+	return verb === STATS_VERB ? await stats_command(rest, context) : refuse()
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_measure_cli = {
+	USAGE,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { MeasureContext }
+export { lane_measure_cli }

package/scripts/lane/lane-occupancy.ts

@@ -82,7 +82,10 @@ function without_label_line(issue: number): string {
 
 function labelled_lines(labelled: ReadonlyArray<LabelledIssue>): Array<string> {
 	return labelled.flatMap((entry) => {
+		// One return type across the branches (sonarjs/function-return-type) keeps the array wrappers.
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
 		if (entry.liveness === 'stopped') return [stopped_line(entry.issue)]
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
 		if (entry.liveness === 'unknown') return [unknown_line(entry.issue)]
 
 		return []

package/scripts/lane/lane-open.ts

@@ -37,14 +37,13 @@ type OpenOutcome =
 
 const FULL_OUTCOME: OpenOutcome = { kind: 'full' }
 
-// The seat a lane will take is claimed by exclusively creating its lock directory here, under the
-// lanes root and clear of the lanes themselves (which are numbered, never dot-prefixed). The claim
+// The seat a lane will take is claimed by exclusively creating its lock directory under
+// `lane_paths.SEAT_LOCK_DIR`, in the lanes root and clear of the lanes themselves (which are numbered, never dot-prefixed). The claim
 // is what closes the gap between reading the free seats and writing the lane's `.env`: two
 // `lane:open` runs that both saw seat 1 free cannot both create the same lock, so the loser steps to
 // the next free seat (joshuafolkken/kit#1494). The lock is released once the lane's `.env` is on
 // disk and the seat is discoverable — or on any failure — so only a hard crash mid-open can strand
 // one, which removing the lanes-root `.seat-locks` directory clears.
-const SEAT_LOCK_DIR = '.seat-locks'
 const SEAT_LOCK_PREFIX = 'seat-'
 
 // A root with no `.env` is the normal state of a fresh clone and of CI, and it means seed 0 — the
@@ -79,7 +78,7 @@ function build_lane(
 }
 
 function seat_lock_path(root: string, seat: number): string {
-	return path.join(root, SEAT_LOCK_DIR, `${SEAT_LOCK_PREFIX}${String(seat)}`)
+	return path.join(root, lane_paths.SEAT_LOCK_DIR, `${SEAT_LOCK_PREFIX}${String(seat)}`)
 }
 
 // Release the seat lock — idempotent (`force`), so calling it after the `.env` write and again in the
@@ -93,7 +92,7 @@ function release_seat_lock(lock: string): void {
 // being created. A missing directory is none held — the normal state when no open is running.
 function open_in_flight_count(root: string): number {
 	try {
-		return readdirSync(path.join(root, SEAT_LOCK_DIR)).filter((entry) =>
+		return readdirSync(path.join(root, lane_paths.SEAT_LOCK_DIR)).filter((entry) =>
 			entry.startsWith(SEAT_LOCK_PREFIX),
 		).length
 	} catch {
@@ -279,6 +278,7 @@ async function open_lane(issue: string): Promise<OpenOutcome> {
 }
 
 const lane_open = {
+	open_in_flight_count,
 	open_lane,
 }
 

package/scripts/lane/lane-paths.ts

@@ -82,10 +82,23 @@ function lane_branch(issue: string): string {
 	return `${issue}${LANE_BRANCH_SUFFIX}`
 }
 
+// The lanes root's own bookkeeping, beside the lanes and never one of them: `lane:open` claims a seat
+// by creating a lock directory under it (joshuafolkken/kit#1494).
+const SEAT_LOCK_DIR = '.seat-locks'
+
+// A name the lane machinery writes into a lanes root: a lane's issue number, or a lanes root of its
+// own — the nested one a lane opened from inside a lane once put there. Anything else in the root
+// was put there by someone else (joshuafolkken/kit#3370).
+function is_lane_entry(name: string): boolean {
+	return LANE_ISSUE_PATTERN.test(name) || DEFAULT_LANE_ROOT_PATTERN.test(name)
+}
+
 const lane_paths = {
 	LANE_BRANCH_SUFFIX,
 	LANE_ROOT_KEY,
+	SEAT_LOCK_DIR,
 	default_lane_root,
+	is_lane_entry,
 	lane_branch,
 	lane_directory,
 	lane_issue_of,

package/scripts/lane/lane-reap.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { lane_child_invocation } from './lane-child-invocation'
 
 // Ending a lane child that did not end itself (joshuafolkken/kit#2421).
@@ -24,9 +25,6 @@ const CHILDREN_OF_FLAG = '-P'
 const PS_COMMAND = '/bin/ps'
 const PARENT_FORMAT = ['-o', 'ppid=', '-p']
 const TERMINATE_SIGNAL = 'SIGTERM'
-// A probe that hung would hang the close it runs inside; failing answers "no process", which leaves
-// the lane exactly as it was before this module existed.
-const PROBE_TIMEOUT_MS = 2000
 // `0` addresses the caller's own process group and `1` is init — neither is ever a lane child.
 const LOWEST_CHILD_PID = 2
 

package/scripts/lane/lane-registry.ts

@@ -217,6 +217,16 @@ async function list_lanes(): Promise<Array<LaneInfo>> {
 	return lanes.toSorted((left, right) => Number(left.issue) - Number(right.issue))
 }
 
+/**
+ * Every directory git registers as a work tree, lane or not — what a sweep of the lanes root must
+ * never touch, including a work tree at a lane's path whose branch does not read as a lane's.
+ */
+async function registered_directories(): Promise<Array<string>> {
+	const blocks = await worktree_blocks()
+
+	return blocks.flatMap((block) => line_value(block.split('\n'), WORKTREE_PREFIX) ?? [])
+}
+
 // 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> {
@@ -259,6 +269,7 @@ const lane_registry = {
 	main_repository_root,
 	parse_block,
 	read_environment,
+	registered_directories,
 	unreadable_lanes,
 	used_seats,
 }

package/scripts/lane/lane-relaunch.ts

@@ -1,6 +1,6 @@
 import { agent_argv } from '#scripts/agent/agent-argv'
 import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import { lane_dispatch_log } from './lane-dispatch-log'

package/scripts/lane/lane-stats.ts

@@ -0,0 +1,224 @@
+import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
+
+// The lane-limit measurement's one table row (joshuafolkken/kit#3355): 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.
+//
+// **A column with no samples prints `—`, never `0`.** A period nobody ran the sampler through has no
+// load, which is not a load of zero; a zero would be read as an idle machine.
+//
+// **Throughput is per active hour** — the time load samples saw a lane child working — rather than per
+// calendar hour, so the nights between runs in a several-day period do not dilute the rate. The gaps
+// between work entries cannot stand in for it: at a low limit the gap from one merge to the next child's
+// first gate is a whole implementation, which a gap cap drops, inflating exactly the low limits' rate.
+// Only a period no sample saw working falls back to the gaps of up to an hour between merges and gates.
+//
+// **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.
+
+const MS_PER_MINUTE = 60_000
+const MS_PER_HOUR = 3_600_000
+// A busy lane pool finishes a gate well within this; a longer silence is time nobody was running work.
+const ACTIVE_GAP_MS = MS_PER_HOUR
+const MS_PER_DAY = 86_400_000
+const MB_PER_GB = 1024
+const HALF = 2
+const DECIMALS = 1
+const MISSING = '—'
+const CELL_SEPARATOR = ' | '
+
+const COLUMNS = [
+	'JOSH_LANE_LIMIT',
+	'period (days)',
+	'merges',
+	'merges / hour',
+	'effective lanes',
+	'gate median (min)',
+	'gate max (min)',
+	'load peak',
+	'load mean',
+	'swap peak (GB)',
+	'swap mean (GB)',
+	'free memory min (GB)',
+	'free memory mean (GB)',
+	'load samples',
+] as const
+
+interface StatsWindow {
+	since_ms: number
+	until_ms: number
+}
+
+interface RowLabel {
+	limit: string
+	period_days: number
+}
+
+function window_of(period_days: number, now_ms: number): StatsWindow {
+	return { since_ms: now_ms - period_days * MS_PER_DAY, until_ms: now_ms }
+}
+
+function in_window(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): Array<LedgerEntry> {
+	return entries.filter((entry) => {
+		const at = Date.parse(entry.at)
+
+		return at >= window.since_ms && at <= window.until_ms
+	})
+}
+
+function is_gate(entry: LedgerEntry): entry is GateEntry {
+	return entry.kind === 'gate'
+}
+
+function is_load(entry: LedgerEntry): entry is LoadEntry {
+	return entry.kind === 'load'
+}
+
+function is_number(value: number | undefined): value is number {
+	return value !== undefined
+}
+
+function mean(values: ReadonlyArray<number>): number | undefined {
+	if (values.length === 0) return undefined
+
+	return values.reduce((sum, value) => sum + value, 0) / values.length
+}
+
+function median(values: ReadonlyArray<number>): number | undefined {
+	if (values.length === 0) return undefined
+
+	const sorted = values.toSorted((left, right) => left - right)
+	const middle = Math.floor(sorted.length / HALF)
+
+	return sorted.length % HALF === 0 ? mean(sorted.slice(middle - 1, middle + 1)) : sorted[middle]
+}
+
+function peak(values: ReadonlyArray<number>): number | undefined {
+	return values.length === 0 ? undefined : Math.max(...values)
+}
+
+function lowest(values: ReadonlyArray<number>): number | undefined {
+	return values.length === 0 ? undefined : Math.min(...values)
+}
+
+type WorkingEntry = LoadEntry & { lanes: number }
+
+function is_working(sample: LoadEntry): sample is WorkingEntry {
+	return (sample.lanes ?? 0) > 0
+}
+
+function sum_hours(gaps: ReadonlyArray<number>): number | undefined {
+	const active = gaps.filter((gap) => gap <= ACTIVE_GAP_MS).reduce((sum, gap) => sum + gap, 0)
+
+	return active > 0 ? active / MS_PER_HOUR : undefined
+}
+
+// The fallback for a period no sampler saw working: the gaps between consecutive work entries (merges
+// and gates) no longer than `ACTIVE_GAP_MS`.
+function gap_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
+	const instants = entries
+		.filter((entry) => !is_load(entry))
+		.map((entry) => Date.parse(entry.at))
+		.toSorted((left, right) => left - right)
+
+	return sum_hours(
+		instants.slice(1).map((instant, index) => instant - (instants[index] ?? instant)),
+	)
+}
+
+// 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 }))
+		.filter(({ sample }) => is_working(sample))
+		.map(({ sample, next }) => Date.parse(next.at) - Date.parse(sample.at))
+
+	return sum_hours(gaps)
+}
+
+// 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)
+
+	return samples.some((sample) => is_working(sample)) ? sampled_hours(samples) : gap_hours(entries)
+}
+
+function gigabytes(megabytes: number | undefined): number | undefined {
+	return megabytes === undefined ? undefined : megabytes / MB_PER_GB
+}
+
+function cell(value: number | undefined): string {
+	return value === undefined ? MISSING : value.toFixed(DECIMALS)
+}
+
+function throughput_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
+	const merges = entries.filter((entry) => entry.kind === 'merge').length
+	const hours = active_hours(entries)
+	const lanes = entries
+		.filter(is_load)
+		.filter(is_working)
+		.map((entry) => entry.lanes)
+	const per_hour = hours === undefined ? undefined : merges / hours
+
+	return [String(merges), cell(per_hour), cell(mean(lanes))]
+}
+
+function gate_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
+	const minutes = entries.filter(is_gate).map((entry) => entry.elapsed_ms / MS_PER_MINUTE)
+
+	return [cell(median(minutes)), cell(peak(minutes))]
+}
+
+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)
+
+	return [
+		cell(peak(samples.map((sample) => sample.load))),
+		cell(mean(working.map((sample) => sample.load))),
+		cell(gigabytes(peak(swap))),
+		cell(gigabytes(mean(working_swap))),
+		cell(gigabytes(lowest(free))),
+		cell(gigabytes(mean(working_free))),
+		String(samples.length),
+	]
+}
+
+function to_row(cells: ReadonlyArray<string>): string {
+	return `| ${cells.join(CELL_SEPARATOR)} |`
+}
+
+function header(): string {
+	return [to_row(COLUMNS), to_row(COLUMNS.map(() => '---'))].join('\n')
+}
+
+// The period's row: `entries` is the whole ledger, filtered here to `window`.
+function row(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow, label: RowLabel): string {
+	const period = in_window(entries, window)
+
+	return to_row([
+		label.limit,
+		String(label.period_days),
+		...throughput_cells(period),
+		...gate_cells(period),
+		...load_cells(period.filter(is_load)),
+	])
+}
+
+const lane_stats = {
+	COLUMNS,
+	MISSING,
+	header,
+	median,
+	row,
+	window_of,
+}
+
+export type { RowLabel, StatsWindow }
+export { lane_stats }

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 (joshuafolkken/kit#3370).
+//
+// **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

@@ -0,0 +1,36 @@
+import { git_command } from '#scripts/git/git-command'
+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
+// 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.
+//
+// **Every unreadable answer is "not vacant"**: `is_tree_dirty` already reads an unreadable status as
+// dirty, and a branch whose commits cannot be counted is kept rather than closed, because closing it
+// deletes the branch and anything on it.
+async function has_no_commits(lane: LaneInfo): Promise<boolean> {
+	try {
+		const base = await git_command.default_branch_reference()
+
+		return (await git_command.commit_count_beyond(base, lane.branch)) === 0
+	} catch {
+		return false
+	}
+}
+
+function is_occupied(lane: LaneInfo): boolean {
+	return lane.is_stranded || lane_await.is_process_running_default(lane.issue)
+}
+
+async function is_vacant(lane: LaneInfo): Promise<boolean> {
+	if (is_occupied(lane) || (await run_hold.is_tree_dirty(lane.directory))) return false
+
+	return await has_no_commits(lane)
+}
+
+const lane_vacant = { is_vacant }
+
+export { lane_vacant }