@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/lane/lane-test-related-stats.ts

@@ -0,0 +1,127 @@
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { lane_ledger, type LedgerEntry, type TestRelatedEntry } from './lane-ledger'
+import { lane_stage_stats } from './lane-stage-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// What widened a `josh test:related` run (joshuafolkken/kit#4465): one row per scope it settled on —
+// `related`, `none` or the full-suite fallback kind — with the medians of its input (the change
+// itself, what a main sync brought in, what the change since the test-read map's tree joined, the
+// readers the map added), of the test files vitest
+// ran and of its duration. A `related` row whose test files far outrun its input is vitest widening the
+// run on its own.
+
+const DECIMALS = 1
+const RUNS_COLUMN = 'runs'
+const SECONDS_COLUMN = 'median (s)'
+const COLUMNS = [
+	'test:related scope',
+	RUNS_COLUMN,
+	'changed',
+	'synced',
+	'since map',
+	'readers',
+	'test files',
+	SECONDS_COLUMN,
+] as const
+const TRIGGER_COLUMNS = ['test:related whole-suite trigger', RUNS_COLUMN, SECONDS_COLUMN] as const
+
+type CountField = 'changed' | 'synced' | 'since_map' | 'readers'
+
+function is_test_related(entry: LedgerEntry): entry is TestRelatedEntry {
+	return entry.kind === lane_ledger.KIND.TEST_RELATED
+}
+
+function count_cell(values: ReadonlyArray<number>): string {
+	const median = lane_stats.median(values)
+
+	return median === undefined ? lane_stage_stats.NOT_MEASURED : String(median)
+}
+
+function seconds_cell(values: ReadonlyArray<number>): string {
+	const median = lane_stats.median(values)
+
+	return median === undefined
+		? lane_stage_stats.NOT_MEASURED
+		: (median / MS_PER_SECOND).toFixed(DECIMALS)
+}
+
+function median_of(runs: ReadonlyArray<TestRelatedEntry>, field: CountField): string {
+	return count_cell(runs.map((run) => run[field]))
+}
+
+function scope_row(scope: string, entries: ReadonlyArray<TestRelatedEntry>): string {
+	const runs = entries.filter((entry) => entry.scope === scope)
+	const test_files = runs.map((run) => run.test_files).filter((files) => files !== undefined)
+
+	return lane_stats.to_row([
+		scope,
+		String(runs.length),
+		median_of(runs, 'changed'),
+		median_of(runs, 'synced'),
+		median_of(runs, 'since_map'),
+		median_of(runs, 'readers'),
+		count_cell(test_files),
+		seconds_cell(runs.map((run) => run.elapsed_ms)),
+	])
+}
+
+function rows_under(columns: ReadonlyArray<string>, rows: ReadonlyArray<string>): string {
+	return [lane_stats.to_row(columns), lane_stats.to_row(columns.map(() => '---')), ...rows].join(
+		'\n',
+	)
+}
+
+function runs_in(
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+): Array<TestRelatedEntry> {
+	return lane_stats.in_window(entries, window).filter(is_test_related)
+}
+
+// The period's table: `entries` is the whole ledger, filtered here to `window`.
+function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const runs = runs_in(entries, window)
+	const scopes = [...new Set(runs.map((run) => run.scope))]
+
+	return rows_under(
+		COLUMNS,
+		scopes.map((scope) => scope_row(scope, runs)),
+	)
+}
+
+interface TriggerRuns {
+	file: string
+	runs: ReadonlyArray<TestRelatedEntry>
+}
+
+function runs_sent_by(file: string, runs: ReadonlyArray<TestRelatedEntry>): TriggerRuns {
+	return { file, runs: runs.filter((run) => run.trigger_files?.includes(file) === true) }
+}
+
+function trigger_row({ file, runs }: TriggerRuns): string {
+	return lane_stats.to_row([
+		file,
+		String(runs.length),
+		seconds_cell(runs.map((run) => run.elapsed_ms)),
+	])
+}
+
+// Which changed file sent a run to the whole suite, most runs first (joshuafolkken/kit#4510): the
+// table `WHOLE_SUITE_FILES` and the test-read map are trimmed from. A row written before the files
+// were recorded names none, and so counts under no file.
+function trigger_table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
+	const runs = runs_in(entries, window)
+	const files = [...new Set(runs.flatMap((run) => run.trigger_files ?? []))]
+	const triggers = files
+		.map((file) => runs_sent_by(file, runs))
+		.toSorted((left, right) => right.runs.length - left.runs.length)
+
+	return rows_under(
+		TRIGGER_COLUMNS,
+		triggers.map((trigger) => trigger_row(trigger)),
+	)
+}
+
+const lane_test_related_stats = { table, trigger_table }
+
+export { lane_test_related_stats }

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

@@ -0,0 +1,145 @@
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// One lane session's transcript reduced to its tool calls: each `tool_use` an `assistant` line carries,
+// joined by its id to the `tool_result` a later `user` line carries, so `josh lane:stats` can time a
+// call as the gap between the two lines (joshuafolkken/kit#4418).
+//
+// **A backgrounded call is kept but not timed.** Its result line is the immediate "running in the
+// background" notice, so the gap measures nothing the run waited on; `duration_ms` is `undefined` for
+// it, as for a call whose result never arrived (an interrupted turn).
+
+interface ToolCall {
+	session_id: string
+	started_ms: number
+	duration_ms: number | undefined
+	background: boolean
+	command: string | undefined
+	output: string
+}
+
+interface ToolUse {
+	started_ms: number
+	background: boolean
+	command: string | undefined
+}
+
+interface ToolResult {
+	ended_ms: number
+	output: string
+}
+
+interface TextPart {
+	text?: string | null | undefined
+}
+
+function join_parts(parts: ReadonlyArray<TextPart>): string {
+	return parts.map((part) => part.text ?? '').join('\n')
+}
+
+interface RawInput {
+	command?: unknown
+	run_in_background?: unknown
+}
+
+interface CallInput {
+	background: boolean
+	command: string | undefined
+}
+
+function to_input(input: RawInput | null | undefined): CallInput {
+	const command = input?.command
+
+	return {
+		background: input?.run_in_background === true,
+		command: typeof command === 'string' ? command : undefined,
+	}
+}
+
+const TEXT_PARTS_SCHEMA = z.array(z.object({ text: z.string().nullish() }))
+// A result's text: a string, or the text parts of a block list; anything else reads as no output.
+const RESULT_CONTENT_SCHEMA = z
+	.union([z.string(), TEXT_PARTS_SCHEMA.transform(join_parts)])
+	.catch('')
+const INPUT_SCHEMA = z.object({ command: z.unknown(), run_in_background: z.unknown() }).partial()
+
+const BLOCK_SCHEMA = z.object({
+	type: z.string(),
+	id: z.string().nullish(),
+	input: INPUT_SCHEMA.nullish().transform(to_input),
+	tool_use_id: z.string().nullish(),
+	content: RESULT_CONTENT_SCHEMA.optional(),
+})
+
+type Block = z.infer<typeof BLOCK_SCHEMA>
+
+function blocks_of(message: { content: Array<Block> } | null | undefined): Array<Block> {
+	return message?.content ?? []
+}
+
+// A line that is not JSON, not a message, or carries no readable timestamp fails the parse.
+const LINE_SCHEMA = z.object({
+	timestamp: z.string().transform(Date.parse).pipe(z.number()),
+	message: z
+		.object({ content: z.array(BLOCK_SCHEMA).catch([]) })
+		.nullish()
+		.transform(blocks_of),
+})
+
+interface Pairs {
+	uses: Map<string, ToolUse>
+	results: Map<string, ToolResult>
+}
+
+function record_use(pairs: Pairs, block: Block, started_ms: number): void {
+	if (block.type !== 'tool_use' || !block.id) return
+
+	pairs.uses.set(block.id, { started_ms, ...block.input })
+}
+
+function record_result(pairs: Pairs, block: Block, ended_ms: number): void {
+	if (block.type !== 'tool_result' || !block.tool_use_id) return
+
+	pairs.results.set(block.tool_use_id, { ended_ms, output: block.content ?? '' })
+}
+
+function record_line(pairs: Pairs, line: string): void {
+	const parsed = LINE_SCHEMA.safeParse(json_value.parse_or_undefined(line))
+
+	if (!parsed.success) return
+
+	const { timestamp, message } = parsed.data
+
+	for (const block of message) {
+		record_use(pairs, block, timestamp)
+		record_result(pairs, block, timestamp)
+	}
+}
+
+function to_call(session_id: string, use: ToolUse, result: ToolResult | undefined): ToolCall {
+	const is_timed = result !== undefined && !use.background
+
+	return {
+		session_id,
+		started_ms: use.started_ms,
+		duration_ms: is_timed ? result.ended_ms - use.started_ms : undefined,
+		background: use.background,
+		command: use.command,
+		output: result?.output ?? '',
+	}
+}
+
+// Every tool call `raw` — one transcript's text — records, in the order the calls were made.
+function parse(session_id: string, raw: string): Array<ToolCall> {
+	const pairs: Pairs = { uses: new Map(), results: new Map() }
+	const lines = raw.split('\n')
+
+	for (const line of lines) record_line(pairs, line)
+
+	return [...pairs.uses].map(([id, use]) => to_call(session_id, use, pairs.results.get(id)))
+}
+
+const lane_transcript_calls = { parse }
+
+export type { ToolCall }
+export { lane_transcript_calls }

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

@@ -0,0 +1,168 @@
+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)
+}
+
+function verification_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) => 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))
+}
+
+// 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> {
+	const sessions = [...new Set(calls.map((call) => call.session_id))]
+
+	return sessions.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)}%)`
+}
+
+function solo_median_row(verifying: ReadonlyArray<ToolCall>, name: string): Array<string> {
+	const solo = verifying.filter((call) => {
+		const named = verification_commands(call.command)
+
+		return named.length === 1 && named[0] === 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)),
+	]
+}
+
+// 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 = calls.filter(
+		(call) => call.started_ms >= window.since_ms && call.started_ms <= window.until_ms,
+	)
+
+	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.
+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(file.session_id, cost_transcript.read_raw(file)))
+}
+
+const lane_transcript_stats = { read_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-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.ts

@@ -10,22 +10,21 @@ import { lane_close, type CloseKind } from './lane-close'
 import { lane_preserve, type KeptWork } from './lane-preserve'
 import { lane_reap } from './lane-reap'
 import { lane_registry, type LaneInfo } from './lane-registry'
+import { lane_residents } from './lane-residents'
+import { lane_state } from './lane-state'
 
-// `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the run
-// for good: the child is stopped, its work stashed, the Issue closed as not planned and the lane closed.
+// `josh lane:withdraw <N> --reason <text>` — a person takes a running lane child's issue out of the
+// current run: the child is stopped, its work stashed and the lane closed. **The Issue stays open** —
+// a withdrawal ends this run's attempt, not the work — so a later run offers it again; this run does
+// not (`backlog-drive-restore.ts` → `offer_exclude`, and the drive's own exclusion).
 //
 // **The `withdraw` event is written first, before anything is stopped.** Killing the child alone would
 // let `lane:await` book it stopped and `run:merge` classify it from GitHub — an open issue resumed as an
-// `outage` or parked `needs-decision`. `run:merge` reads the event stream before GitHub, so a child whose
-// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads
-// at that moment, and the race between the kill and the close cannot book it as anything else.
+// `outage` or parked `run:stalled`. `run:merge` reads the event stream before GitHub, so a child whose
+// newest launch-or-withdraw event is a withdraw is booked `withdrawn` whatever the Issue's state reads.
 //
-// **The issue is read again once the child is stopped.** It may merge between the first read and the
-// reap; the reap stopped it, so the second read is final, and an issue it already closed keeps
-// GitHub's close — `run:merge` books a merged close as merged whatever the event stream says.
-//
-// A tree that could not be stashed is left in place with the Issue open: closing the lane would delete
-// the work, and the person decides what to keep.
+// A tree that could not be stashed is left in place: closing the lane would delete the work, and the
+// person decides what to keep.
 
 const WITHDRAW_OCCASION = 'lane withdraw'
 const WITHDRAW_CAUSE = 'a person withdrew it with `lane:withdraw`'
@@ -41,22 +40,21 @@ interface Withdrawn {
 	// How many of the child's processes the withdrawal stopped — 0 for a child that had already ended.
 	reaped: number
 	stash: string | undefined
-	is_closed: boolean
-	// The issue had closed on its own — merged — before the withdrawal reached it, so it was left as is.
-	had_closed: boolean
+	// Whether the comment saying the issue stays open reached it.
+	is_noted: boolean
 	lane: CloseKind
+	// What else the close ended from the checkout; `undefined` where it could not be read.
+	residents: ReadonlyArray<number> | undefined
 }
 
-type IssueSettled = Pick<Withdrawn, 'had_closed' | 'is_closed'>
-
 type Refused =
 	{ kind: typeof CLOSED_KIND } | { kind: typeof NO_LANE_KIND } | { kind: typeof UNREADABLE_KIND }
 type WithdrawOutcome = Withdrawn | Unsaved | Refused
 
-function close_comment(reason: string): string {
+function withdraw_comment(reason: string): string {
 	return [
-		'Withdrawn by a person with `pnpm josh lane:withdraw`.',
-		'Its lane child was stopped and the lane closed.',
+		'Withdrawn from the current run by a person with `pnpm josh lane:withdraw`.',
+		'Its lane child was stopped and the lane closed. The Issue stays open: this run does not resume it, and the next run offers it again.',
 		`- Why: ${reason}`,
 	].join('\n')
 }
@@ -78,47 +76,45 @@ async function refusal_of(issue: string): Promise<Refused | undefined> {
 	return undefined
 }
 
-async function close_open_issue(issue: string, reason: string): Promise<IssueSettled> {
-	const refusal = await refusal_of(issue)
-
-	// An unread issue may have merged during the reap, so it is left open for a person to close.
-	if (refusal !== undefined) {
-		const is_closed = refusal.kind === CLOSED_KIND
-
-		return { is_closed, had_closed: is_closed }
-	}
-
-	const is_closed = await git_gh_issue_write.issue_close_not_planned(issue, close_comment(reason))
-
-	return { is_closed, had_closed: false }
-}
-
-async function close_issue(
+async function note_issue(
 	issue: string,
 	reason: string,
 	stash: string | undefined,
-): Promise<IssueSettled> {
-	const settled = await close_open_issue(issue, reason)
+): Promise<boolean> {
+	const is_noted = await git_gh_issue_write.issue_try_comment(issue, withdraw_comment(reason))
 
 	if (stash !== undefined) await lane_preserve.announce(issue, stash, WITHDRAW_CAUSE)
 	await run_label.unmark(issue)
 
-	return settled
+	return is_noted
 }
 
 async function stop_and_close(lane: LaneInfo, reason: string): Promise<WithdrawOutcome> {
 	await record_withdraw(lane.issue, reason)
-	const reaped = lane_reap.reap_child(lane.issue).length
+	const reaped = lane_reap.reap_child(lane).length
 	const saved = await lane_preserve.keep_work(lane.issue, lane.directory, WITHDRAW_OCCASION)
 
 	if (saved.kind === 'unsaved') return saved
-	const settled = await close_issue(lane.issue, reason, saved.stash)
+	const is_noted = await note_issue(lane.issue, reason, saved.stash)
 	const closed = await lane_close.close_lane(lane.issue)
 
-	return { kind: 'withdrawn', reaped, stash: saved.stash, ...settled, lane: closed.kind }
+	// After the close, so the record names the withdrawal rather than the close it ran. An `incomplete`
+	// close is not `ended`: the supervisor closes the lane again until its last process is gone.
+	if (closed.kind !== 'incomplete') {
+		await lane_state.record_change({ issue: lane.issue, state: 'ended', command: 'lane:withdraw' })
+	}
+
+	return {
+		kind: 'withdrawn',
+		reaped,
+		stash: saved.stash,
+		is_noted,
+		lane: closed.kind,
+		residents: closed.residents,
+	}
 }
 
-/** Stop `#<N>`'s lane child, stash its work, close the Issue as not planned and close the lane. */
+/** Stop `#<N>`'s lane child, stash its work and close the lane, leaving the Issue open. */
 async function withdraw(issue: string, reason: string): Promise<WithdrawOutcome> {
 	issue_number_shape.require_issue_number(issue)
 	const refusal = await refusal_of(issue)
@@ -137,21 +133,26 @@ function stash_sentence(stash: string | undefined): string {
 	return `Its uncommitted work was stashed — recover with \`pnpm josh stash:pop "${stash}"\`.`
 }
 
+// What the lane's close left or ended, as a suffix.
+function lane_suffix(outcome: Withdrawn, cited: string): string {
+	const removed = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
+	const residents = lane_residents.residents_sentence(outcome.residents, cited)
+
+	return residents === undefined ? removed : `${removed} ${residents}`
+}
+
 function withdrawn_text(outcome: Withdrawn, issue: string): string {
 	const cited = session_cite.issue(issue)
 	const stopped = outcome.reaped === 0 ? 'Its child had already ended.' : 'Stopped its child.'
 	const head = `Withdrew ${cited}. ${stopped} ${stash_sentence(outcome.stash)}`
-	const lane = outcome.lane === 'incomplete' ? ' The lane could not be fully removed.' : ''
-
-	if (outcome.had_closed) return `${head} The Issue had already closed and was left as is.${lane}`
-
-	if (outcome.is_closed) return `${head} The Issue is closed as not planned.${lane}`
+	const lane = lane_suffix(outcome, cited)
+	const noted = outcome.is_noted ? '' : ' The comment saying so could not be posted.'
 
-	return `${head} The Issue could not be closed — close ${cited} by hand; \`run:merge\` books it withdrawn either way.${lane}`
+	return `${head} The Issue stays open: this run does not offer it again, the next run does.${noted}${lane}`
 }
 
 function unsaved_text(outcome: Unsaved, issue: string): string {
-	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the Issue is left open and the lane at ${outcome.directory}; \`run:merge\` books it withdrawn.`
+	return `The child for ${session_cite.issue(issue)} was stopped, but its uncommitted work could not be stashed (${outcome.reason}), so the lane is left at ${outcome.directory}; \`run:merge\` books it withdrawn.`
 }
 
 function refused_text(outcome: Refused, issue: string): string {