@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,200 @@
+import path from 'node:path'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { time_shell } from '#scripts/time-runtime/time-shell'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_transcript_calls, type ToolCall } from './lane-transcript-calls'
+
+// The lane speed metrics only the lane sessions' transcripts hold, printed by `josh lane:stats` under the
+// ledger's tables so a speed check needs no ad-hoc aggregation (joshuafolkken/kit#4418): tool time per
+// session, the verification calls and the share that waited for the core budget, and the medians of
+// `lint:related` / `test:related`.
+//
+// **A chained call is counted apart from a solo one.** One Bash call that runs two verification
+// commands (`josh lint:related && josh test:related`) has one duration for both, so it would read as
+// either command's time; the per-command medians take solo calls only. **Only a foreground call is
+// timed** — `lane_transcript_calls` leaves a backgrounded one's duration out.
+//
+// **The period is cut at each call's own timestamp**, not a transcript's modification time, so a
+// fractional `--period` (since a merge) counts the same calls whichever session they sit in.
+
+const TIMED_COMMANDS: ReadonlyArray<string> = ['lint:related', 'test:related']
+// **The verification calls split by what ran them** (joshuafolkken/kit#4442): the scoped checks of the
+// implementation loop, a whole `gate` or `metrics` run by hand before the ship, and the `ship` call —
+// whose own gate runs inside it and is the ledger's to count — so a hand-run gate is never hidden in the
+// loop's volume. A call naming two classes counts in each.
+const CALL_CLASSES: ReadonlyArray<readonly [string, ReadonlySet<string>]> = [
+	['verification calls, scoped checks', new Set([...TIMED_COMMANDS, 'cspell:dot'])],
+	['verification calls, gate / metrics by hand', new Set(['gate', 'metrics'])],
+	['verification calls, ship', new Set(['ship'])],
+]
+const VERIFICATION_COMMANDS: ReadonlySet<string> = new Set(
+	CALL_CLASSES.flatMap(([, names]) => [...names]),
+)
+// A command is `josh <name>` at the start of a shell command — after a separator and the shell
+// keywords, then past what `time_shell` skips (env assignments, wrappers with their flags and operands,
+// a `pnpm` / `npx` runner) — so `josh lint:related; josh test:related`, `out=$(pnpm josh gate)` and
+// `CI=1 timeout 600 pnpm josh gate` name their commands. A heredoc body or a quoted string only
+// mentions a command, so `time_shell.unquoted` cuts both, keeping a `"$(…)"` that runs
+// (joshuafolkken/kit#4525).
+const SEPARATOR_PATTERN = /[;&|()\n]/u
+const WORD_PATTERN = /\s+/u
+const KEYWORDS: ReadonlySet<string> = new Set([
+	'if',
+	'elif',
+	'else',
+	'then',
+	'while',
+	'until',
+	'do',
+	'!',
+	'{',
+])
+// `scripts/gate/core-wait.ts` writes this into every wait line it prints.
+const CORE_WAIT_PHRASE = 'waits for the core budget'
+const PERCENT = 100
+const COLUMNS = ['transcript metric', 'value'] as const
+const { NOT_MEASURED } = lane_stage_stats
+
+// The josh command `segment` runs, or `''` when it runs none.
+function segment_command(segment: string): string {
+	const words = segment.trim().split(WORD_PATTERN)
+	const start = words.findIndex((word) => !KEYWORDS.has(word))
+	const named = time_shell.josh_command_of_segment(words.slice(start).join(' '))
+
+	return named.slice(time_shell.JOSH_PREFIX.length)
+}
+
+// Every josh command a shell `command` runs, in order.
+function josh_commands(command = ''): Array<string> {
+	const spoken = time_shell.unquoted(command)
+	const named = spoken.split(SEPARATOR_PATTERN).map((segment) => segment_command(segment))
+
+	return named.filter((name) => name !== '')
+}
+
+function verification_commands(command = ''): Array<string> {
+	return josh_commands(command).filter((name) => VERIFICATION_COMMANDS.has(name))
+}
+
+function seconds_cell(ms: number | undefined): string {
+	return ms === undefined ? NOT_MEASURED : (ms / MS_PER_SECOND).toFixed(1)
+}
+
+function is_timed(ms: number | undefined): ms is number {
+	return ms !== undefined
+}
+
+function durations(calls: ReadonlyArray<ToolCall>): Array<number> {
+	return calls.map((call) => call.duration_ms).filter((ms) => is_timed(ms))
+}
+
+// The lane sessions that made a call among `calls`, each once.
+function sessions_of(calls: ReadonlyArray<ToolCall>): Array<string> {
+	return [...new Set(calls.map((call) => call.session_id))]
+}
+
+// Each session's summed foreground tool time, for the sessions that made a call in the period.
+function session_times(calls: ReadonlyArray<ToolCall>): Array<number> {
+	return sessions_of(calls).map((session) =>
+		durations(calls.filter((call) => call.session_id === session)).reduce(
+			(sum, value) => sum + value,
+			0,
+		),
+	)
+}
+
+function share_cell(part: number, whole: number): string {
+	if (whole === 0) return NOT_MEASURED
+
+	return `${String(part)} of ${String(whole)} (${((part / whole) * PERCENT).toFixed(1)}%)`
+}
+
+// The calls that ran the verification command `name` and no other, so each one's time is its own.
+function solo_calls(calls: ReadonlyArray<ToolCall>, name: string): Array<ToolCall> {
+	return calls.filter((call) => {
+		const named = verification_commands(call.command)
+
+		return named.length === 1 && named[0] === name
+	})
+}
+
+function solo_median_row(verifying: ReadonlyArray<ToolCall>, name: string): Array<string> {
+	const solo = solo_calls(verifying, name)
+
+	return [`${name} median, solo (s)`, seconds_cell(lane_stats.median(durations(solo)))]
+}
+
+function class_rows(verifying: ReadonlyArray<ToolCall>): Array<Array<string>> {
+	return CALL_CLASSES.map(([metric, names]) => {
+		const named = verifying.filter((call) =>
+			verification_commands(call.command).some((name) => names.has(name)),
+		)
+
+		return [metric, String(named.length)]
+	})
+}
+
+function rows_of(calls: ReadonlyArray<ToolCall>): Array<Array<string>> {
+	const times = session_times(calls)
+	const verifying = calls.filter((call) => verification_commands(call.command).length > 0)
+	const chained = verifying.filter((call) => verification_commands(call.command).length > 1)
+	const waited = verifying.filter((call) => call.output.includes(CORE_WAIT_PHRASE))
+
+	return [
+		['lane sessions', String(times.length)],
+		['tool time per session, median (min)', lane_stage_stats.cell(lane_stats.median(times))],
+		['tool time per session, mean (min)', lane_stage_stats.cell(lane_stats.mean(times))],
+		['verification calls, solo', String(verifying.length - chained.length)],
+		['verification calls, chained', String(chained.length)],
+		...class_rows(verifying),
+		['waited for the core budget', share_cell(waited.length, verifying.length)],
+		...TIMED_COMMANDS.map((name) => solo_median_row(verifying, name)),
+	]
+}
+
+function in_period(calls: ReadonlyArray<ToolCall>, window: StatsWindow): Array<ToolCall> {
+	return calls.filter(
+		(call) => call.started_ms >= window.since_ms && call.started_ms <= window.until_ms,
+	)
+}
+
+// The period's table: `calls` is every lane session's calls, filtered here to `window`.
+function table(calls: ReadonlyArray<ToolCall>, window: StatsWindow): string {
+	const period = in_period(calls, window)
+
+	return [
+		lane_stats.to_row(COLUMNS),
+		lane_stats.to_row(COLUMNS.map(() => '---')),
+		...rows_of(period).map((row) => lane_stats.to_row(row)),
+	].join('\n')
+}
+
+// The tool calls of every lane session under `directories` that was still written to in `window` — a
+// transcript last modified before the period holds no call in it, so it is never read. A delegated
+// unit's transcript is not a lane session, and its time is already inside the parent's wait for it.
+// A session's own transcript sits directly in its lane's directory, so that directory is its lane.
+function read_calls(directories: ReadonlyArray<string>, window: StatsWindow): Array<ToolCall> {
+	return cost_transcript
+		.list_sessions_across(directories)
+		.filter((file) => !file.is_delegated && file.modified_ms >= window.since_ms)
+		.flatMap((file) =>
+			lane_transcript_calls.parse(
+				{ session_id: file.session_id, lane: path.dirname(file.path) },
+				cost_transcript.read_raw(file),
+			),
+		)
+}
+
+const lane_transcript_stats = {
+	durations,
+	in_period,
+	josh_commands,
+	read_calls,
+	solo_calls,
+	table,
+	verification_commands,
+}
+
+export { lane_transcript_stats }

package/scripts/lane/lane-vacant.ts

@@ -1,5 +1,6 @@
 import { git_command } from '#scripts/git/git-command'
 import { run_hold } from '#scripts/run/hold/run-hold'
+import { PROCESS_NONE } from '#scripts/run/run-liveness'
 import { lane_await } from './lane-await'
 import type { LaneInfo } from './lane-registry'
 
@@ -9,7 +10,7 @@ import type { LaneInfo } from './lane-registry'
 // 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
+// dirty, a process probe that could not look reads as occupied, 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 {
@@ -21,8 +22,10 @@ async function has_no_commits(lane: LaneInfo): Promise<boolean> {
 	}
 }
 
+// Only pgrep's own "no match" clears a lane: a probe that failed or timed out never looked, and a
+// freshly launched child with no commit yet must not read vacant on it (joshuafolkken/kit#4028).
 function is_occupied(lane: LaneInfo): boolean {
-	return lane.is_stranded || lane_await.is_process_running_default(lane.issue)
+	return lane.is_stranded || lane_await.process_trace_default(lane.issue) !== PROCESS_NONE
 }
 
 async function is_vacant(lane: LaneInfo): Promise<boolean> {
@@ -31,6 +34,13 @@ async function is_vacant(lane: LaneInfo): Promise<boolean> {
 	return await has_no_commits(lane)
 }
 
-const lane_vacant = { is_vacant }
+// The issues of the lanes that hold nothing worth keeping, read in parallel.
+async function vacant_issues(lanes: ReadonlyArray<LaneInfo>): Promise<Array<string>> {
+	const answers = await Promise.all(lanes.map(async (lane) => await is_vacant(lane)))
+
+	return lanes.filter((_lane, index) => answers[index] === true).map((lane) => lane.issue)
+}
+
+const lane_vacant = { is_vacant, vacant_issues }
 
 export { lane_vacant }

package/scripts/lane/lane-value-cell.ts

@@ -0,0 +1,72 @@
+// `josh lane:value cell --table <title> --row <label> --column <header>` — one cell of a table
+// `josh lane:stats` prints, as one number (joshuafolkken/kit#5144). The tables are read as printed, so
+// every new `lane:stats` table is declarable without a new metric and no aggregation is copied.
+//
+// A table is named by its first header cell and a row by its first cell. **The address must name one
+// cell** — two tables share the `check` title, so an address that matches more than one numeric cell
+// answers `undefined`, as a missing or non-numeric one does, never a guess.
+
+const ROW_OPEN = '| '
+const ROW_CLOSE = ' |'
+const CELL_SEPARATOR = ' | '
+const BLOCK_SEPARATOR = /\n\s*\n/u
+const NUMBER_PATTERN = /^-?\d+(?:\.\d+)?$/u
+const HEADER_ROWS = 2
+
+interface CellAddress {
+	table: string
+	row: string
+	column: string
+}
+
+type Cells = ReadonlyArray<string>
+
+function cells_of(line: string): Cells | undefined {
+	const text = line.trim()
+
+	if (!text.startsWith(ROW_OPEN) || !text.endsWith(ROW_CLOSE)) return undefined
+
+	return text.slice(ROW_OPEN.length, -ROW_CLOSE.length).split(CELL_SEPARATOR)
+}
+
+function rows_of(block: string): ReadonlyArray<Cells> {
+	return block
+		.split('\n')
+		.map((line) => cells_of(line))
+		.filter((row) => row !== undefined)
+}
+
+// Every printed table as its rows of cells, the header first; a block with no row is dropped.
+function blocks_of(tables: ReadonlyArray<string>): ReadonlyArray<ReadonlyArray<Cells>> {
+	return tables
+		.flatMap((table) => table.split(BLOCK_SEPARATOR))
+		.map((block) => rows_of(block))
+		.filter((rows) => rows.length > 0)
+}
+
+// The cell texts at the address in one table — none when its title or column differs.
+function texts_in(rows: ReadonlyArray<Cells>, address: CellAddress): ReadonlyArray<string> {
+	const [header = []] = rows
+	const column = header.indexOf(address.column)
+
+	if (header[0] !== address.table || column < 1) return []
+
+	return rows
+		.slice(HEADER_ROWS)
+		.filter((cells) => cells[0] === address.row)
+		.map((cells) => cells[column] ?? '')
+}
+
+// The one numeric cell at `address` across `tables`, or `undefined` for none, many or a non-number.
+function value(tables: ReadonlyArray<string>, address: CellAddress): number | undefined {
+	const numbers = blocks_of(tables)
+		.flatMap((rows) => texts_in(rows, address))
+		.filter((text) => NUMBER_PATTERN.test(text))
+
+	return numbers.length === 1 ? Number(numbers[0]) : undefined
+}
+
+const lane_value_cell = { value }
+
+export type { CellAddress }
+export { lane_value_cell }

package/scripts/lane/lane-value.ts

@@ -0,0 +1,118 @@
+import { metrics_totals } from '#scripts/gate/metrics-totals'
+import { since_green } from '#scripts/gate/since-green'
+import { MS_PER_MINUTE, MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { run_ship_pre_detach } from '#scripts/run/ship/run-ship-pre-detach'
+import { lane_ledger, type CoreWaitEntry, type LedgerEntry } from './lane-ledger'
+import { lane_stats, type StatsWindow } from './lane-stats'
+import type { ToolCall } from './lane-transcript-calls'
+import { lane_transcript_stats } from './lane-transcript-stats'
+
+// `josh lane:value <metric> --since <instant>` — one lane measurement as one number, so a follow-up
+// measurement Issue can declare it (its measurement declaration line) and `backlog:drive` closes it without a lane
+// (joshuafolkken/kit#4630). Each metric is one an Issue measured by hand from the lane transcripts or
+// the ledger; `lane:stats` prints the tables they were read from.
+//
+// **Per lane is per lane, not per session** — every lane runs at least a child and a ship-reviewer
+// session, so the divisor is the lanes whose sessions made a tool call in the period. A metric with no
+// sample answers `undefined`, never a zero that would pass.
+
+const LINT_RELATED = 'lint:related'
+const SHIP = 'ship'
+const EDIT_TOOL = 'Edit'
+// Both pre-detach forms: a `--since` window from before joshuafolkken/kit#4716 holds the bare form's.
+const METRICS_STOPS: ReadonlyArray<string> = [
+	metrics_totals.METRICS_RERECORD_COMMAND,
+	metrics_totals.METRICS_TOTALS_COMMAND,
+].map((list) => run_ship_pre_detach.failure_prefix(list))
+
+interface LaneRecords {
+	entries: ReadonlyArray<LedgerEntry>
+	calls: ReadonlyArray<ToolCall>
+}
+
+type Metric = (records: LaneRecords) => number | undefined
+
+function seconds_of(ms: number | undefined): number | undefined {
+	return ms === undefined ? undefined : ms / MS_PER_SECOND
+}
+
+// `count` spread over the period's lanes, or `undefined` when no lane ran.
+function per_lane(count: number, calls: ReadonlyArray<ToolCall>): number | undefined {
+	const lanes = new Set(calls.map((call) => call.lane)).size
+
+	return lanes === 0 ? undefined : count / lanes
+}
+
+// #4599: the median time of a `lint:related` that found nothing moved since its last green run.
+function lint_unmoved({ calls }: LaneRecords): number | undefined {
+	const unmoved = lane_transcript_stats
+		.solo_calls(calls, LINT_RELATED)
+		.filter((call) => call.output.includes(since_green.UNMOVED_REASON))
+
+	return seconds_of(lane_stats.median(lane_transcript_stats.durations(unmoved)))
+}
+
+// #4600: the `ship` calls whose pre-detach check the metrics totals stopped, per lane.
+function metrics_stops({ calls }: LaneRecords): number | undefined {
+	const stops = calls.filter(
+		(call) =>
+			lane_transcript_stats.verification_commands(call.command).includes(SHIP) &&
+			METRICS_STOPS.some((stop) => call.output.includes(stop)),
+	)
+
+	return per_lane(stops.length, calls)
+}
+
+// A lane's `lint:related` wait — one outside a lane (the main checkout's) has no `issue` and no lane
+// session to be divided among.
+function is_lint_wait(entry: LedgerEntry): entry is CoreWaitEntry {
+	return (
+		entry.kind === lane_ledger.KIND.CORE_WAIT &&
+		entry.command === LINT_RELATED &&
+		entry.issue !== undefined
+	)
+}
+
+// #4601: the minutes `lint:related` waited for the core budget, per lane.
+function lint_core_wait({ entries, calls }: LaneRecords): number | undefined {
+	const waited = entries.filter((entry) => is_lint_wait(entry))
+	const total_ms = waited.reduce((sum, wait) => sum + wait.waited_ms, 0)
+
+	return per_lane(total_ms / MS_PER_MINUTE, calls)
+}
+
+// #4602: the median time of one `Edit` call, hooks included.
+function edit({ calls }: LaneRecords): number | undefined {
+	const edits = calls.filter((call) => call.tool === EDIT_TOOL)
+
+	return seconds_of(lane_stats.median(lane_transcript_stats.durations(edits)))
+}
+
+const METRICS: Readonly<Record<string, Metric>> = {
+	'lint-unmoved': lint_unmoved,
+	'metrics-stops': metrics_stops,
+	'lint-core-wait': lint_core_wait,
+	edit,
+}
+
+const NAMES: ReadonlyArray<string> = Object.keys(METRICS)
+
+function is_metric(name: string): boolean {
+	return Object.hasOwn(METRICS, name)
+}
+
+// The value of `name` over `window`; `records` are the whole ledger and every lane call, cut here.
+function value(name: string, records: LaneRecords, window: StatsWindow): number | undefined {
+	const metric = is_metric(name) ? METRICS[name] : undefined
+	const period = {
+		entries: lane_stats.in_window(records.entries, window),
+		calls: lane_transcript_stats.in_period(records.calls, window),
+	}
+
+	return metric === undefined ? undefined : metric(period)
+}
+
+const lane_value = { NAMES, is_metric, value }
+
+export type { LaneRecords }
+export { lane_value }

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

@@ -4,8 +4,9 @@ import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { lane_withdraw, type WithdrawOutcome } from './lane-withdraw'
 
-// `josh lane:withdraw <issue> --reason <text>` — every explanation on standard error, and a withdrawal
-// that did not end with the Issue closed exits non-zero, so a caller never takes a half-done one as done.
+// `josh lane:withdraw <issue> --reason <text>` — every explanation on standard error, and anything but a
+// finished withdrawal exits non-zero, so a caller never takes a half-done one as done. The Issue stays
+// open on success.
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
@@ -24,7 +25,7 @@ function issue_of(positionals: ReadonlyArray<string>): string | undefined {
 	return rest.length === 0 && issue_number_shape.is_issue_number(issue ?? '') ? issue : undefined
 }
 
-// A reason of only whitespace is no reason: the Issue would close with an empty `Why:` line.
+// A reason of only whitespace is no reason: the Issue would carry an empty `Why:` line.
 function reason_of(value: unknown): string | undefined {
 	const reason = cli_flags.string_of(value)?.trim()
 
@@ -41,7 +42,7 @@ function parse_request(argv: ReadonlyArray<string>): Request | undefined {
 }
 
 function exit_code_of(outcome: WithdrawOutcome): number {
-	return outcome.kind === 'withdrawn' && outcome.is_closed ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+	return outcome.kind === 'withdrawn' ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
 async function run(argv: ReadonlyArray<string>): Promise<number> {

package/scripts/lane/lane-withdraw-closed.ts

@@ -0,0 +1,124 @@
+import { git_command } from '#scripts/git/git-command'
+import { session_cite } from '#scripts/issue/session-cite'
+import { error_text } from '#scripts/lib/error-message'
+import { run_board_closed, type ClosedIssue } from '#scripts/run/board/run-board-closed'
+import { run_event_scope } from '#scripts/run/event/run-event-scope'
+import type { RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_withdraw, type Withdrawer } from './lane-withdraw'
+
+// Every open lane whose issue was closed on GitHub as not planned is withdrawn through `lane:withdraw`'s
+// own path (joshuafolkken/kit#4915): its child is stopped, its work stashed and the lane closed, so the
+// lane leaves the count and no cut resumes it. Nothing else ends such a lane: the child keeps working on
+// an issue no one wants, and the lane limit counts it while the board draws no lane for it.
+//
+// **Only a not-planned close is swept.** A merged issue's lane is ended by the merge path, where a
+// detached ship may still be running its tail; an issue closed as completed by hand is left to
+// `lane:prune` and `run:merge`, which books it withdrawn when no merged pull request closed it
+// (joshuafolkken/kit#4916). An issue that could not be read is
+// asked again on the next pass, and a lane whose withdrawal is already on the event stream is not
+// withdrawn twice.
+//
+// **A branch with commits on no remote is kept**: the close deletes the branch and the stash keeps only
+// uncommitted work, so a person decides with `lane:withdraw` by hand. `run:merge` withdraws through the
+// same guard (`withdraw_lane`).
+
+const SWEEP_REASON = 'its issue was closed as not planned while the lane was still open'
+
+function is_not_planned(read: ClosedIssue | undefined): boolean {
+	return read !== undefined && read.is_not_planned && !read.is_merged
+}
+
+/** The open lanes whose issue is closed as not planned. */
+async function closed_lanes(): Promise<Array<LaneInfo>> {
+	const listed = await lane_registry.list_lanes()
+	const lanes = listed.filter((lane) => !lane.is_stranded)
+	const { closed } = await run_board_closed.read_all(lanes.map((lane) => Number(lane.issue)))
+
+	return lanes.filter((lane) => is_not_planned(closed.get(Number(lane.issue))))
+}
+
+// An unreadable count keeps the branch, as unpushed commits would.
+async function has_unpushed(branch: string): Promise<boolean> {
+	try {
+		return (await git_command.commit_count_unpushed(branch)) > 0
+	} catch (error) {
+		error_text.trace_swallowed('lane_withdraw_closed.has_unpushed', error)
+
+		return true
+	}
+}
+
+function kept_note(issue: string, by: Withdrawer): string {
+	const settled = by === 'yield' ? 'gave its lane back' : 'is closed without a merge'
+
+	return `${session_cite.issue(issue)} ${settled}, but its branch has commits on no remote, so its lane is kept — run \`pnpm josh lane:withdraw ${issue}\` by hand.`
+}
+
+interface UnattendedWithdrawal {
+	note: string
+	// The withdrawal could not read the issue, so nothing was stopped or closed.
+	is_retry: boolean
+}
+
+/** Withdraw a closed issue's open lane with no person present, keeping a branch with unpushed commits. */
+async function withdraw_lane(
+	lane: LaneInfo,
+	reason: string,
+	by: Withdrawer,
+): Promise<UnattendedWithdrawal> {
+	if (await has_unpushed(lane.branch)) return { note: kept_note(lane.issue, by), is_retry: false }
+	const outcome = await lane_withdraw.withdraw(lane.issue, reason, by)
+
+	return {
+		note: lane_withdraw.describe(outcome, lane.issue),
+		is_retry: outcome.kind === 'unreadable',
+	}
+}
+
+async function sweep_lane(
+	lane: LaneInfo,
+	events: ReadonlyArray<RunEvent>,
+): Promise<string | undefined> {
+	if (run_event_scope.is_withdrawn(events, lane.issue)) return undefined
+	const { note } = await withdraw_lane(lane, SWEEP_REASON, 'supervisor')
+
+	return note
+}
+
+// One lane's failure does not stop the sweep: the rest are still withdrawn, and this one is asked again.
+async function try_sweep_lane(
+	lane: LaneInfo,
+	events: ReadonlyArray<RunEvent>,
+): Promise<string | undefined> {
+	try {
+		return await sweep_lane(lane, events)
+	} catch (error) {
+		error_text.trace_swallowed('lane_withdraw_closed.sweep_lane', error)
+
+		return `${session_cite.issue(lane.issue)} could not be withdrawn (${error_text.message_of(error)}); the next pass tries again.`
+	}
+}
+
+/** Withdraw every open lane whose issue is closed as not planned — the supervisor's pass; one note each. */
+async function withdraw_closed(): Promise<Array<string>> {
+	const lanes = await closed_lanes()
+	const events = await run_event_stream_emit.current_events()
+	const notes: Array<string> = []
+
+	// Sequential, as `lane_close.close_each` is: two worktree removals at once contend for git's
+	// registration directory.
+	for (const lane of lanes) {
+		// eslint-disable-next-line no-await-in-loop -- worktree writes contend for the same registration directory
+		const note = await try_sweep_lane(lane, events)
+
+		if (note !== undefined) notes.push(note)
+	}
+
+	return notes
+}
+
+const lane_withdraw_closed = { SWEEP_REASON, withdraw_closed, withdraw_lane }
+
+export { lane_withdraw_closed }