@joshuafolkken/kit 1.1229.0 → 1.1240.0

package/scripts/issue/issue-release.ts

@@ -0,0 +1,58 @@
+import { DEPTH_0_LABEL, RELEASE_LABEL } from './issue-labels'
+
+// The decisions behind `josh issue:release` (joshuafolkken/kit#3360), kept apart from the command
+// that reads the network so each is a pure answer a test can pin. An Issue whose change reaches a
+// consumer only once published used to surface the release only at the end of `followup`'s report;
+// it is now linked to the repository's release Issue, which it blocks until it merges.
+
+interface ListingRow {
+	number: number
+}
+
+function is_listing_row(value: unknown): value is ListingRow {
+	if (typeof value !== 'object' || value === null) return false
+
+	return Number.isSafeInteger(Reflect.get(value, 'number'))
+}
+
+// The open release Issue a listing of `release`-labelled Issues names, or `undefined` when it names
+// none or is unreadable. One release publishes every merge since the last, so a repository holds one
+// release Issue at a time; were a person to open a second, the oldest is the one the next release
+// closes, so it is the one every new blocker joins.
+function open_release_of(json: string): number | undefined {
+	try {
+		const parsed: unknown = JSON.parse(json)
+		const rows = Array.isArray(parsed) ? parsed.filter((row) => is_listing_row(row)) : []
+
+		return rows.length === 0 ? undefined : Math.min(...rows.map((row) => row.number))
+	} catch {
+		return undefined
+	}
+}
+
+function title_of(repo: string): string {
+	return `Release ${repo} (next version)`
+}
+
+// Plain English with no classification declaration: the Issue is not filed through `issue:file`, and
+// its labels are `RELEASE_LABELS` rather than read off the body.
+function body_of(repo: string): string {
+	return [
+		`Tracks the next release of ${repo}.`,
+		'',
+		'Every Issue this one is blocked by changes something a consumer can use only once it is published. Once they have merged, a person runs `pnpm josh release` in the primary checkout.',
+		'',
+		'Close this Issue once that release is published: the next blocker files a new one, so an open release Issue names only unreleased work.',
+		'',
+		'`auto-ok` is never applied to this Issue by a run; a person may apply it.',
+		'',
+	].join('\n')
+}
+
+// The release label and a depth: the subject of a release is what a consumer touches.
+// Never `auto-ok`.
+const RELEASE_LABELS: ReadonlyArray<string> = [RELEASE_LABEL, DEPTH_0_LABEL]
+
+const issue_release = { RELEASE_LABELS, open_release_of, title_of, body_of }
+
+export { issue_release }

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

@@ -71,6 +71,9 @@ interface CommandEntry {
 	// under a second, so a wait for room on the machine would stall every edit for the length of
 	// another lane's check.
 	core_weight?: number | (() => number)
+	// The memory the command's tools hold, claimed with its cores (joshuafolkken/kit#3371); read like
+	// `core_weight`, and none declared is none waited for.
+	memory_mb?: number | (() => number)
 }
 
 // The name `josh gate` registers under. It lives here rather than in `verification-gate.ts` so a

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

@@ -28,6 +28,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.lint,
+		memory_mb: core_budget.MEMORY_MB.lint,
 	},
 	'lint:related': {
 		script: 'scripts/lint/lint-related.ts',
@@ -35,6 +36,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.lint,
+		memory_mb: core_budget.MEMORY_MB.lint,
 	},
 	lines: {
 		script: 'scripts/lines/lines-command.ts',
@@ -42,6 +44,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [REQUIRED_FILE_ARGUMENTS, 'developer', ['none']],
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 	},
 	'refactor:scan': {
 		script: 'scripts/refactor/refactor-scan-cli.ts',
@@ -50,6 +53,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'automation', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.eslint_scan,
+		memory_mb: core_budget.MEMORY_MB.eslint_scan,
 	},
 	bytes: {
 		script: 'scripts/lines/bytes-command.ts',
@@ -137,6 +141,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.spell_check,
+		memory_mb: core_budget.MEMORY_MB.spell_check,
 	},
 	behavior: {
 		script: 'scripts/behavior/behavior-cli.ts',
@@ -159,6 +164,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [FILTER_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,
+		memory_mb: gate_plan.direct_unit_memory,
 	},
 	'test:related': {
 		script: 'scripts/test/test-related.ts',
@@ -166,6 +172,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: [FILE_ARGUMENTS, 'developer', ['processes']],
 		core_weight: gate_plan.direct_unit_weight,
+		memory_mb: gate_plan.direct_unit_memory,
 	},
 	'test:declared': {
 		script: 'scripts/test/test-declared.ts',
@@ -213,6 +220,7 @@ const DEV_COMMANDS: Record<string, CommandEntry> = {
 		category: 'Development',
 		reference: ['[arguments...]', 'developer', ['processes']],
 		core_weight: core_budget.CORE_WEIGHTS.type_check,
+		memory_mb: core_budget.MEMORY_MB.type_check,
 	},
 	port: {
 		script: 'scripts/ports/port-command.ts',

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

@@ -69,11 +69,18 @@ const ISSUE_COMMANDS: Record<string, CommandEntry> = {
 			'File an Issue with every filing step: lint, Origin, WIP cap, duplicate scout, labels, then epic:bundle',
 		category: 'AI tools',
 		reference: [
-			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok]',
+			'<title> --body-file <path> --depth <0|1|2> [--route <route>] [--label <name>] [--repo <owner/repo>] [--distinct <N,…>] [--over-cap] [--no-auto-ok] [--release]',
 			'automation',
 			['network'],
 		],
 	},
+	'issue:release': {
+		script: 'scripts/issue/issue-release-cli.ts',
+		description:
+			"Link an Issue to the repository's open release Issue as its blocker, filing one when none is open",
+		category: 'AI tools',
+		reference: ['<issue>', 'automation', ['network']],
+	},
 }
 /* eslint-enable @typescript-eslint/naming-convention */
 

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

@@ -39,7 +39,8 @@ const LANE_COMMANDS: Record<string, CommandEntry> = {
 	},
 	'lane:prune': {
 		...LANE_ARGUMENTS,
-		description: 'Close every lane an interruption left without its work tree',
+		description:
+			'Close every lane an interruption left without its work tree, then sweep unregistered leftovers under the lanes root',
 		category: 'AI tools',
 		reference: ['', 'automation', ['files', 'git']],
 		default_script_arguments: ['prune'],

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

@@ -45,9 +45,9 @@ const MAINTENANCE_COMMANDS: Record<string, CommandEntry> = {
 		shell: [
 			'sh',
 			'-c',
-			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:corepack && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:scope --record',
+			'export NODE_AUTH_TOKEN=$(gh auth token) && pnpm josh latest:guard && pnpm josh latest:update && pnpm josh ranges && pnpm josh audit && pnpm josh latest:corepack && pnpm josh latest:scope --record',
 		],
-		description: 'Update pnpm, dependencies, and run security audit',
+		description: 'Update dependencies, run security audit, then update pnpm',
 		category: 'Maintenance',
 		reference: ['', 'developer', ['files', 'network', 'processes']],
 		argument_targets: ['latest:corepack', 'latest:update', 'audit'],

package/scripts/josh/josh-logic.ts

@@ -279,8 +279,8 @@ async function run_entry(
 	return await run_script_entry(entry, subcommand_arguments)
 }
 
-function command_weight(entry: CommandEntry): number | undefined {
-	return typeof entry.core_weight === 'function' ? entry.core_weight() : entry.core_weight
+function declared(value: number | (() => number) | undefined): number | undefined {
+	return typeof value === 'function' ? value() : value
 }
 
 // **Every command passes through here, so this is where a declared weight is reserved**
@@ -291,13 +291,14 @@ async function dispatch_entry(
 	entry: CommandEntry,
 	subcommand_arguments: Array<string>,
 ): Promise<number> {
-	const weight = command_weight(entry)
+	const weight = declared(entry.core_weight)
 
 	if (weight === undefined) return await run_entry(entry, subcommand_arguments)
 
 	return await core_budget.with_command_reservation(
 		weight,
 		async () => await run_entry(entry, subcommand_arguments),
+		{ memory_mb: declared(entry.memory_mb) },
 	)
 }
 

package/scripts/lane/lane-cli.ts

@@ -16,6 +16,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 { lane_stray } from './lane-stray'
 
 // `josh lane:open` / `lane:close` / `lane:list` / `lane:prune` — the lane's whole lifecycle
 // (joshuafolkken/kit#1490).
@@ -268,7 +269,14 @@ async function list_command(rest: ReadonlyArray<string>): Promise<number> {
 async function prune_command(rest: ReadonlyArray<string>): Promise<number> {
 	if (rest.length > 0) return report_usage()
 
-	return report_sweep(await lane_close.prune_lanes())
+	const code = report_sweep(await lane_close.prune_lanes())
+
+	// 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
+	// every `backlogrun` preparation until one came (joshuafolkken/kit#3370).
+	await lane_stray.sweep_and_report()
+
+	return code
 }
 
 // The recorded path goes to standard output on both arms, so

package/scripts/lane/lane-leftover.ts

@@ -1,7 +1,9 @@
 import { createHash } from 'node:crypto'
 import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, rmSync } from 'node:fs'
 import path from 'node:path'
+import { ENV_FILE_NAME } from '#ports'
 import { git_spawn } from '#scripts/git/git-spawn'
+import { IGNORED_CACHE_FILES } from '#scripts/josh/josh-command-types'
 
 // A lane directory git no longer registers as a work tree (joshuafolkken/kit#2857).
 //
@@ -11,31 +13,38 @@ import { git_spawn } from '#scripts/git/git-spawn'
 // here before it adds the tree.
 //
 // **The test for removing it is that removing it loses nothing**, not a list of names. Every file in
-// it has to be one the repository already holds with the same content, so it is a checkout git would
-// write again; the one exception is the `.git` file, a pointer to the registration that is gone. A
-// list of generated names would break the next time a file is generated, and would delete whatever
-// shares one of those names.
-
-// `git ls-tree -r -z`: `<mode> <type> <object>\t<path>`, entries separated by NUL — the `-z` form
-// leaves a path with an unusual character unquoted, so it can be compared to the path on disk.
-const TREE_ENTRY_PATTERN = /^\d+ blob (?<object>[\da-f]+)\t(?<path>.+)$/su
+// it has to hold content the repository's history already stores — a blob some ref reaches — so git
+// can write it again; the one exception is the `.git` file, a pointer to the registration that is
+// gone. **Any commit's content, not only `HEAD`'s at the same path** (joshuafolkken/kit#3370): a
+// leftover is a checkout of whatever commit its lane was on, and measured against `HEAD` the
+// leftovers that issue found differed in 167 to 1,431 files each while every one of them was in the
+// history. A list of generated names would break the next time a file is generated, and would delete
+// whatever shares one of those names.
+//
+// **The one list of names is what `lane:open` and the gate regenerate**, and only at the top level:
+// the install's `node_modules`, the build's `dist`, the `.env` `lane:open` writes from the root's, and
+// the gate's caches. A lane carries them on top of its checkout, none is in the history, and walking
+// `node_modules` alone would hash tens of thousands of files.
+const REGENERATED_PATHS: ReadonlySet<string> = new Set([
+	'node_modules',
+	'dist',
+	ENV_FILE_NAME,
+	...IGNORED_CACHE_FILES,
+])
 const GIT_POINTER = '.git'
 const GITDIR_PREFIX = 'gitdir: '
 // The foreign paths a refusal names before it summarizes the rest as a count.
 const NAMED_PATH_LIMIT = 10
 
-// One blob entry as `[path, object id]`; a tree, a commit (a submodule) or the trailing empty entry is
-// none.
-function tree_entry(entry: string): Array<[string, string]> {
-	const { path: entry_path, object } = TREE_ENTRY_PATTERN.exec(entry)?.groups ?? {}
-
-	if (entry_path === undefined || object === undefined) return []
-
-	return [[entry_path, object]]
+// `git rev-list --objects --all`: one `<object>[ <path>]` line per object any ref reaches — commits,
+// trees and blobs alike, which costs nothing here, because only a blob id can equal a file's.
+function parse_objects(listing: string): Set<string> {
+	return new Set(listing.split('\n').map((line) => line.split(' ', 1)[0] ?? ''))
 }
 
-function parse_tree(listing: string): Map<string, string> {
-	return new Map(listing.split('\0').flatMap((entry) => tree_entry(entry)))
+/** Every object id the repository's refs reach — the content a leftover can be restored from. */
+async function recoverable_objects(): Promise<Set<string>> {
+	return parse_objects(await git_spawn.read(['rev-list', '--objects', '--all']))
 }
 
 // The object id git gives this file — a symbolic link's is that of its target string, as git stores it.
@@ -63,9 +72,14 @@ function walk_files(directory: string, relative: string): Array<string> {
 	})
 }
 
-// Every file under `directory` as a repository path, symbolic links included and never followed.
+// Every file under `directory` as a repository path, symbolic links included and never followed —
+// less the regenerated top-level entries, which are neither walked nor listed.
 function list_files(directory: string): Array<string> {
-	return walk_files(directory, '')
+	return readdirSync(directory)
+		.filter((name) => !REGENERATED_PATHS.has(name))
+		.flatMap((name) =>
+			lstatSync(path.join(directory, name)).isDirectory() ? walk_files(directory, name) : name,
+		)
 }
 
 // The `.git` file is disposable only while the registration it points to is gone: one that still
@@ -85,25 +99,25 @@ function is_dangling_pointer(directory: string): boolean {
 function is_reclaimable_file(
 	directory: string,
 	relative: string,
-	tracked: ReadonlyMap<string, string>,
+	recoverable: ReadonlySet<string>,
 ): boolean {
 	if (relative === GIT_POINTER) return is_dangling_pointer(directory)
 
-	return tracked.get(relative) === blob_id(path.join(directory, relative))
+	return recoverable.has(blob_id(path.join(directory, relative)))
 }
 
 /**
  * The paths under `directory` whose removal would lose something — empty when it holds nothing but
- * the repository's own files and the `.git` pointer. A `.git` directory is a repository of its own,
- * so it is foreign as a whole rather than walked.
+ * content the history stores, the regenerated entries and the `.git` pointer. A `.git` directory is a
+ * repository of its own, so it is foreign as a whole rather than walked.
  */
-function foreign_paths(directory: string, tracked: ReadonlyMap<string, string>): Array<string> {
+function foreign_paths(directory: string, recoverable: ReadonlySet<string>): Array<string> {
 	const pointer = lstatSync(path.join(directory, GIT_POINTER), { throwIfNoEntry: false })
 
 	if (pointer?.isDirectory() === true) return [GIT_POINTER]
 
 	return list_files(directory).filter(
-		(relative) => !is_reclaimable_file(directory, relative, tracked),
+		(relative) => !is_reclaimable_file(directory, relative, recoverable),
 	)
 }
 
@@ -125,8 +139,7 @@ function refusal(directory: string, foreign: ReadonlyArray<string>): Error {
 async function reclaim(directory: string): Promise<void> {
 	if (!existsSync(directory)) return
 
-	const tracked = parse_tree(await git_spawn.read(['ls-tree', '-r', '-z', '--full-tree', 'HEAD']))
-	const foreign = foreign_paths(directory, tracked)
+	const foreign = foreign_paths(directory, await recoverable_objects())
 
 	if (foreign.length > 0) throw refusal(directory, foreign)
 
@@ -136,8 +149,9 @@ async function reclaim(directory: string): Promise<void> {
 const lane_leftover = {
 	blob_id,
 	foreign_paths,
-	parse_tree,
+	parse_objects,
 	reclaim,
+	recoverable_objects,
 }
 
 export { lane_leftover }

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-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-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/release/github-release-environment.ts

@@ -38,6 +38,7 @@ function read_release_input(environment: Environment): ReleaseInput {
 			workflow: optional(environment['RELEASE_WORKFLOW']),
 			jobs: job_names(environment['RELEASE_JOBS']),
 			await_publish: environment['RELEASE_AWAIT_PUBLISH'] === 'true',
+			release_run_workflow: optional(environment['RELEASE_RUN_WORKFLOW']),
 		},
 	}
 }