@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lane/lane-pause.ts

@@ -0,0 +1,158 @@
+import { lane_reap, type LaneProcesses, type ReapProbes } from './lane-reap'
+import { lane_registry } from './lane-registry'
+import { lane_residents } from './lane-residents'
+
+// Suspending a lane child in place, and letting it carry on from the same point.
+//
+// **Nothing but the processes is touched here.** The work tree, the branch and the issue stay as they
+// are, so a paused lane is resumed rather than rebuilt — the one way to halt a lane that `lane:close`
+// (which deletes it) and `lane:withdraw` (which takes its issue out of the run) are not. The command
+// (`lane-pause-cli.ts`) records the change in the lane's state and on the run's event stream.
+//
+// **The tree is `lane_reap`'s** — the same match, the same descendants, the caller's own ancestry
+// spared — so a pause and a reap never disagree on which processes are the lane's.
+//
+// **A pause reads the tree again until no new process turns up.** A parent signalled after it had
+// already forked leaves a child that was not in the first read running; each round stops what the
+// last one did not see, up to `PAUSE_ROUNDS`.
+//
+// **A process detached from the tree is stopped and continued with it** (joshuafolkken/kit#4300): the
+// edit hook's `eslint_d`, a detached `ship`, found by its working directory or mark as `lane:close`
+// finds it (`lane-residents.ts`), so a resume reaches every process the pause stopped. A pause with no
+// child in the tree stops none of them: it pauses no lane and records nothing, so nothing would resume
+// them. A read of them that failed is `is_unread`, never "none", so a caller can say they were missed.
+
+const STOP_SIGNAL = 'SIGSTOP'
+const CONTINUE_SIGNAL = 'SIGCONT'
+const PAUSE_ROUNDS = 5
+
+type LaneSignal = typeof STOP_SIGNAL | typeof CONTINUE_SIGNAL
+
+interface PauseProbes extends ReapProbes {
+	signal: (pid: number, name: LaneSignal) => boolean
+	// What runs from the lane outside the tree (`lane-residents.ts`); `undefined` when unreadable.
+	residents: (lane: LaneProcesses) => ReadonlyArray<number> | undefined
+}
+
+// What a pause or a resume reached: the lane's processes signalled, and those of them in the child's
+// tree. Only `child` says the lane is running — a resident outlives the child it served (`eslint_d`
+// idles on), so signalling it alone pauses no lane. `is_unread`: the residents could not be read, so
+// any of them may have been missed.
+interface LaneSignalled {
+	signalled: Array<number>
+	child: Array<number>
+	is_unread: boolean
+}
+
+// One read of the lane: the child's tree, and the tree with what runs from the lane outside it.
+interface LaneRead {
+	tree: Array<number>
+	all: Array<number>
+	is_unread: boolean
+}
+
+function signal(pid: number, name: LaneSignal): boolean {
+	try {
+		process.kill(pid, name)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+const SYSTEM_PROBES: PauseProbes = {
+	...lane_reap.SYSTEM_PROBES,
+	signal,
+	residents: (lane) => lane_residents.residents(lane),
+}
+
+// The lane child's tree and what runs from the lane outside it, each once. The residents are read only
+// beside a child, unless `is_resident_read_forced`.
+function lane_processes(
+	lane: LaneProcesses,
+	probes: PauseProbes,
+	is_resident_read_forced: boolean,
+): LaneRead {
+	const tree = lane_reap.lane_tree(lane.issue, probes)
+	if (!is_resident_read_forced && tree.length === 0) return { tree, all: tree, is_unread: false }
+	const residents = probes.residents(lane)
+
+	return {
+		tree,
+		all: [...new Set([...tree, ...(residents ?? [])])],
+		is_unread: residents === undefined,
+	}
+}
+
+function signalled_of(
+	signalled: Array<number>,
+	tree: ReadonlySet<number>,
+	is_unread: boolean,
+): LaneSignalled {
+	return { signalled, child: signalled.filter((pid) => tree.has(pid)), is_unread }
+}
+
+// Every pid read is `seen`, so a process the signal could not reach is not retried each round; only the
+// ones the signal reached are `stopped`. Every tree pid read is `tree`.
+interface PauseProgress {
+	seen: Set<number>
+	tree: Set<number>
+	stopped: Array<number>
+	is_unread: boolean
+}
+
+function stop_unseen(lane: LaneProcesses, progress: PauseProgress, probes: PauseProbes): number {
+	const read = lane_processes(lane, probes, progress.tree.size > 0)
+	const unseen = read.all.filter((pid) => !progress.seen.has(pid))
+
+	for (const pid of read.tree) progress.tree.add(pid)
+	progress.is_unread ||= read.is_unread
+
+	for (const pid of unseen) {
+		progress.seen.add(pid)
+		if (probes.signal(pid, STOP_SIGNAL)) progress.stopped.push(pid)
+	}
+
+	return unseen.length
+}
+
+/** SIGSTOP every process of the lane; returns the pids stopped. */
+function pause_lane(lane: LaneProcesses, probes: PauseProbes = SYSTEM_PROBES): LaneSignalled {
+	const progress: PauseProgress = {
+		seen: new Set(),
+		tree: new Set(),
+		stopped: [],
+		is_unread: false,
+	}
+
+	for (let round = 0; round < PAUSE_ROUNDS; round += 1) {
+		if (stop_unseen(lane, progress, probes) === 0) break
+	}
+
+	return signalled_of(progress.stopped, progress.tree, progress.is_unread)
+}
+
+/** SIGCONT every process of the lane; returns the pids continued. */
+function resume_lane(lane: LaneProcesses, probes: PauseProbes = SYSTEM_PROBES): LaneSignalled {
+	const read = lane_processes(lane, probes, true)
+	const continued = read.all.filter((pid) => probes.signal(pid, CONTINUE_SIGNAL))
+
+	return signalled_of(continued, new Set(read.tree), read.is_unread)
+}
+
+// Only what a pause reads: a lane is matched by its issue and its directory, nothing else.
+function processes_of(lane: LaneProcesses): LaneProcesses {
+	return { issue: lane.issue, directory: lane.directory }
+}
+
+async function open_lanes(): Promise<Array<LaneProcesses>> {
+	const lanes = await lane_registry.list_lanes()
+
+	return lanes.map((lane) => processes_of(lane))
+}
+
+const lane_pause = { PAUSE_ROUNDS, open_lanes, pause_lane, resume_lane }
+
+export { lane_pause }
+export type { LaneSignal, LaneSignalled, PauseProbes }

package/scripts/lane/lane-preserve.ts

@@ -1,5 +1,6 @@
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { git_stash } from '#scripts/git/stash/git-stash'
+import { error_text } from '#scripts/lib/error-message'
 
 // Keeping a lane's uncommitted work before something discards or restarts it — `run:merge` closing a
 // lane, `lane:restart` handing it to a fresh session. The stash stack outlives the tree, so the push is
@@ -30,6 +31,32 @@ async function announce(issue: string, message: string, cause: string): Promise<
 	await git_gh_issue_write.issue_try_comment(issue, preserved_comment(message, cause))
 }
 
+// The tree's work kept before a stopped child's lane is reused or closed: `saved` with the stash, or
+// none for a clean tree, and `unsaved` with the reason when the tree could not be read or pushed — the
+// caller then leaves the tree as it is rather than handing it on or deleting it.
+type KeptWork =
+	| { kind: 'saved'; stash: string | undefined }
+	| { kind: 'unsaved'; directory: string; reason: string }
+
+async function stash_of(
+	issue: string,
+	directory: string,
+	occasion: string,
+): Promise<string | undefined> {
+	if (!(await git_stash.has_changes(directory))) return undefined
+
+	return await push_work(issue, directory, occasion)
+}
+
+/** Stash the tree's uncommitted work, if any, answering `unsaved` rather than throwing. */
+async function keep_work(issue: string, directory: string, occasion: string): Promise<KeptWork> {
+	try {
+		return { kind: 'saved', stash: await stash_of(issue, directory, occasion) }
+	} catch (error) {
+		return { kind: 'unsaved', directory, reason: error_text.message_of(error) }
+	}
+}
+
 /** `push_work`, then `announce` — for a caller with no reason to separate the two. */
 async function stash_work(
 	issue: string,
@@ -44,6 +71,7 @@ async function stash_work(
 	return message
 }
 
-const lane_preserve = { announce, push_work, stash_work }
+const lane_preserve = { announce, keep_work, stash_work }
 
+export type { KeptWork }
 export { lane_preserve }

package/scripts/lane/lane-process-table.ts

@@ -0,0 +1,166 @@
+import { process_identity } from '#scripts/josh/process-identity'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
+import { lane_reap, type TreeProbes } from './lane-reap'
+import { process_tools } from './process-tools'
+
+// Every process on the machine at one instant, read by one asynchronous `ps`, answering the probes a
+// lane's tree is read through (joshuafolkken/kit#4241), and the listing `run:board`'s
+// usage columns are read from (joshuafolkken/kit#4246).
+//
+// **Why one snapshot.** `lane_reap`'s probes start one synchronous `ps` / `pgrep` per ancestor and per
+// descendant, so a reader that asks about every lane each few seconds — `run:board`, the backlogrun
+// drive — blocked its event loop for over a second with seven lanes under load. The snapshot costs one
+// spawn whatever the lane and process counts, and never blocks. `run:board` takes one per refresh and
+// hands it to both the lane count and the usage columns (`shared`), so the two read the same instant.
+//
+// **The walk is not re-implemented.** `lane_reap` still walks the tree; the
+// snapshot only answers the questions it asks. `matching` reads the full command line the way
+// `pgrep -f` does, and `-ww` keeps `ps` from cutting it at a terminal width. The command is the full
+// line rather than `comm`: `ps` cuts any column but the last, so the two cannot share one listing.
+//
+// **The start time is `process_identity`'s own reading.** A detached ship's record names its process by
+// start time (`run-ship-detach.ts`), and the `lstart` column under `process_identity`'s environment
+// prints it exactly as that module's own `ps` does, so a ship is told alive from these rows without
+// starting another `ps` (joshuafolkken/kit#4245).
+
+const COLUMNS = ['pid=', 'ppid=', 'time=', 'rss=', 'stat=', process_identity.START_TIME_FORMAT]
+const PS_ARGUMENTS = ['-A', '-ww', '-o', [...COLUMNS, 'command='].join(',')]
+// `ps` labels nothing locale-dependent here, and the C locale keeps its columns stable; the time zone
+// fixes how the start time prints.
+const PS_ENVIRONMENT = process_identity.PROBE_ENVIRONMENT
+const FIELD_SEPARATOR = /\s+/u
+// `lstart` prints `Tue Sep  8 08:39:04 2026`: five fields, the day of the month padded to two places.
+const START_FIELDS = 5
+const DAY_FIELD = 2
+const DAY_WIDTH = 2
+
+interface ProcessRow {
+	pid: number
+	parent: number
+	// `ps`'s cumulative CPU time as printed, `[DD-][HH:]MM:SS[.ss]`.
+	time: string
+	rss_kb: number
+	stat: string
+	// The start time as `process_identity`'s `ps` prints it.
+	start: string
+	command: string
+}
+
+// One snapshot's rows.
+type ProcessTable = ReadonlyArray<ProcessRow>
+// A snapshot read on demand, `undefined` where `ps` did not answer.
+type TableRead = () => Promise<ProcessTable | undefined>
+
+function is_row(row: ProcessRow): boolean {
+	const { pid, parent, rss_kb, command } = row
+
+	return Number.isSafeInteger(pid + parent) && Number.isFinite(rss_kb) && command !== ''
+}
+
+// The split fields put back with the day's padding the split dropped.
+function start_of(fields: ReadonlyArray<string>): string {
+	return fields
+		.map((field, index) => (index === DAY_FIELD ? field.padStart(DAY_WIDTH) : field))
+		.join(' ')
+}
+
+// The command's own runs of white space read as one space, which no lane pattern tells apart.
+function row_of(line: string): ProcessRow | undefined {
+	const [pid, parent, time = '', rss, stat = '', ...rest] = line.trim().split(FIELD_SEPARATOR)
+	const numbers = { pid: Number(pid), parent: Number(parent), rss_kb: Number(rss) }
+	const start = start_of(rest.slice(0, START_FIELDS))
+	const row = { ...numbers, time, stat, start, command: rest.slice(START_FIELDS).join(' ') }
+
+	return is_row(row) ? row : undefined
+}
+
+/** Each `ps` line as a row; a line that does not read as one is left out. */
+function parse(printed: string): Array<ProcessRow> {
+	return printed
+		.split('\n')
+		.map((line) => row_of(line))
+		.filter((row) => row !== undefined)
+}
+
+function matching_in(rows: ProcessTable, pattern: string): Array<number> {
+	const expression = new RegExp(pattern, 'u')
+
+	return rows.filter((row) => expression.test(row.command)).map((row) => row.pid)
+}
+
+// Each parent's children, indexed once so a walk does not rescan every row per process.
+function children_index(rows: ProcessTable): Map<number, Array<number>> {
+	const children = new Map<number, Array<number>>()
+
+	for (const { pid, parent } of rows) {
+		const siblings = children.get(parent) ?? []
+
+		siblings.push(pid)
+		children.set(parent, siblings)
+	}
+
+	return children
+}
+
+/** The probes a lane's tree is read through, answered from `rows` alone. */
+function probes_of(rows: ProcessTable): TreeProbes {
+	const by_pid = new Map(rows.map((row) => [row.pid, row]))
+	const children = children_index(rows)
+
+	return {
+		matching: (pattern) => matching_in(rows, pattern),
+		children_of: (pid) => children.get(pid) ?? [],
+		parent_of: (pid) => by_pid.get(pid)?.parent,
+	}
+}
+
+/** `process_identity.read_start` with its `ps` answered from `rows`: `/proc` first, as there. */
+function start_reader(rows: ProcessTable): (pid: number) => string | undefined {
+	const starts = new Map(rows.map((row) => [row.pid, row.start]))
+	const probes = {
+		...process_identity.START_PROBES,
+		read_ps_start: (pid: number) => starts.get(pid),
+	}
+
+	return (pid) => process_identity.read_start(pid, probes)
+}
+
+/** The snapshot, `undefined` where `ps` did not answer; a missing `ps` is refused by name. */
+async function read_table(): Promise<ProcessTable | undefined> {
+	try {
+		const { stdout } = await execa(lane_reap.PS_COMMAND, PS_ARGUMENTS, {
+			env: PS_ENVIRONMENT,
+			timeout: PROBE_TIMEOUT_MS,
+		})
+
+		return parse(stdout)
+	} catch (error) {
+		process_tools.throw_if_missing(lane_reap.PS_COMMAND, error)
+
+		return undefined
+	}
+}
+
+/** `read`, run on the first call alone; every later call answers that same snapshot. */
+function shared(read: TableRead): TableRead {
+	const taken: { table?: ReturnType<TableRead> } = {}
+
+	return async function table() {
+		taken.table ??= read()
+
+		return await taken.table
+	}
+}
+
+const lane_process_table = {
+	PS_ARGUMENTS,
+	parse,
+	probes_of,
+	read_table,
+	shared,
+	start_reader,
+}
+
+export { lane_process_table }
+export type { ProcessRow, ProcessTable, TableRead }

package/scripts/lane/lane-reap-settle.ts

@@ -0,0 +1,124 @@
+import { userInfo } from 'node:os'
+import { lane_reap } from './lane-reap'
+import { lane_residents, type ResidentLane } from './lane-residents'
+
+// What a close does about the lane's processes once the SIGTERM went out (joshuafolkken/kit#4300).
+//
+// **A SIGTERM is a request, so the close looks again.** After a grace window the lane's directory is
+// read again; whatever is still there gets a SIGKILL, and after a short wait the directory is read a
+// last time. What survives that is reported, each with why it could — another account owns it, or it
+// is stuck in the kernel — so `lane:close` answers `incomplete` and `run:board` can say what is wrong
+// rather than only that something is left.
+
+// Long enough for a node process to run its exit handlers.
+const GRACE_MS = 3000
+// A SIGKILL is not handled, so what still answers after this is not going to go.
+const KILL_WAIT_MS = 1000
+const KILL_SIGNAL = 'SIGKILL'
+const STATE_FORMAT = ['-o', 'user=,stat=', '-p']
+const FIELD_SEPARATOR = /\s+/u
+const UNREADABLE_TEXT = "the lane's processes (lsof or ps failed)"
+
+interface SettleProbes {
+	// `undefined` where the lane's processes could not be read (`lane_residents.residents`).
+	residents: (lane: ResidentLane) => Array<number> | undefined
+	kill: (pid: number) => boolean
+	wait: (milliseconds: number) => Promise<void>
+	// Why a process outlived the SIGKILL.
+	reason_of: (pid: number) => string
+}
+
+interface Survivor {
+	pid: number
+	reason: string
+}
+
+function kill(pid: number): boolean {
+	try {
+		process.kill(pid, KILL_SIGNAL)
+
+		return true
+	} catch {
+		return false
+	}
+}
+
+async function wait(milliseconds: number): Promise<void> {
+	await new Promise((resolve) => setTimeout(resolve, milliseconds))
+}
+
+// Another account's process is the usual survivor — a SIGKILL from this one is refused; otherwise
+// `ps`'s state says it, `U` for an uninterruptible wait.
+function reason_from(user: string, state: string): string {
+	if (user !== userInfo().username) return `owned by ${user}`
+
+	return `state ${state}`
+}
+
+function reason_of(pid: number): string {
+	const printed = lane_reap.run_probe(lane_reap.PS_COMMAND, [...STATE_FORMAT, String(pid)])
+	const [user = '', state = ''] = printed.trim().split(FIELD_SEPARATOR)
+
+	return user.length === 0 ? 'unreadable' : reason_from(user, state)
+}
+
+const SYSTEM_PROBES: SettleProbes = {
+	residents: (lane) => lane_residents.residents(lane),
+	kill,
+	wait,
+	reason_of,
+}
+
+// A reading that failed is not an empty one.
+function is_empty(reading: ReadonlyArray<number> | undefined): boolean {
+	return reading?.length === 0
+}
+
+async function kill_all(
+	lingering: ReadonlyArray<number> | undefined,
+	probes: SettleProbes,
+): Promise<void> {
+	const targets = lingering ?? []
+
+	for (const pid of targets) probes.kill(pid)
+
+	await probes.wait(KILL_WAIT_MS)
+}
+
+function survivors(lane: ResidentLane, probes: SettleProbes): Array<Survivor> | undefined {
+	return probes.residents(lane)?.map((pid) => ({ pid, reason: probes.reason_of(pid) }))
+}
+
+/**
+ * Wait out the SIGTERM a reap sent, SIGKILL what is still in the lane's directory, and answer what
+ * outlived even that — the empty list is a lane with no process left, `undefined` a last reading that
+ * failed. A failed reading is never read as none: it is read again, and nothing is killed on it.
+ */
+async function settle(
+	lane: ResidentLane,
+	probes: SettleProbes = SYSTEM_PROBES,
+): Promise<Array<Survivor> | undefined> {
+	if (is_empty(probes.residents(lane))) return []
+
+	await probes.wait(GRACE_MS)
+
+	const lingering = probes.residents(lane)
+
+	if (is_empty(lingering)) return []
+
+	await kill_all(lingering, probes)
+
+	return survivors(lane, probes)
+}
+
+/** How a close's `left_behind` names what `settle` answered; a failed reading is named as such. */
+function survivor_texts(settled: ReadonlyArray<Survivor> | undefined): Array<string> {
+	if (settled === undefined) return [UNREADABLE_TEXT]
+
+	return settled.map((survivor) => `process ${String(survivor.pid)} (${survivor.reason})`)
+}
+
+const lane_reap_settle = { GRACE_MS, KILL_WAIT_MS, reason_from, settle, survivor_texts }
+
+export type { SettleProbes, Survivor }
+export { lane_reap_settle }

package/scripts/lane/lane-reap.ts

@@ -18,6 +18,9 @@ import { process_tools } from './process-tools'
 //
 // **The caller's own ancestry is never touched.** A `lane:close` issued from inside the lane it
 // closes would otherwise end the very session running it, before it could report.
+//
+// **What runs from the lane outside the tree is `lane-residents.ts`'s** (joshuafolkken/kit#4300): the
+// edit hook's `eslint_d`, a `script` wrapper re-parented to pid 1, found by working directory or mark.
 
 const PGREP_COMMAND = 'pgrep'
 const MATCH_FULL_COMMAND_LINE = '-f'
@@ -26,13 +29,24 @@ const CHILDREN_OF_FLAG = '-P'
 const PS_COMMAND = '/bin/ps'
 const PARENT_FORMAT = ['-o', 'ppid=', '-p']
 const TERMINATE_SIGNAL = 'SIGTERM'
+const CONTINUE_SIGNAL = 'SIGCONT'
 // `0` addresses the caller's own process group and `1` is init — neither is ever a lane child.
 const LOWEST_CHILD_PID = 2
 
-interface ReapProbes {
+// The lane a reap or a pause acts on: the child by its issue, the rest by its directory.
+interface LaneProcesses {
+	issue: string
+	directory: string
+}
+
+// What collecting a lane's process tree reads — shared with `lane:pause` (`lane-pause.ts`).
+interface TreeProbes {
 	matching: (pattern: string) => Array<number>
 	children_of: (pid: number) => Array<number>
 	parent_of: (pid: number) => number | undefined
+}
+
+interface ReapProbes extends TreeProbes {
 	terminate: (pid: number) => boolean
 }
 
@@ -64,9 +78,9 @@ function parent_of(pid: number): number | undefined {
 	return parse_pids(run_probe(PS_COMMAND, [...PARENT_FORMAT, String(pid)]))[0]
 }
 
-function terminate(pid: number): boolean {
+function send(pid: number, name: NodeJS.Signals): boolean {
 	try {
-		process.kill(pid, TERMINATE_SIGNAL)
+		process.kill(pid, name)
 
 		return true
 	} catch {
@@ -74,6 +88,16 @@ function terminate(pid: number): boolean {
 	}
 }
 
+// A stopped process (`lane:pause`) holds a SIGTERM it handles pending until it is continued, so the
+// terminate is followed by a SIGCONT; a running process ignores it.
+function terminate(pid: number): boolean {
+	if (!send(pid, TERMINATE_SIGNAL)) return false
+
+	send(pid, CONTINUE_SIGNAL)
+
+	return true
+}
+
 const SYSTEM_PROBES: ReapProbes = {
 	matching: (pattern) => parse_pids(run_probe(PGREP_COMMAND, [MATCH_FULL_COMMAND_LINE, pattern])),
 	children_of: (pid) => parse_pids(run_probe(PGREP_COMMAND, [CHILDREN_OF_FLAG, String(pid)])),
@@ -81,7 +105,7 @@ const SYSTEM_PROBES: ReapProbes = {
 	terminate,
 }
 
-function ancestry_of(pid: number, probes: ReapProbes): Set<number> {
+function ancestry_of(pid: number, probes: TreeProbes): Set<number> {
 	const ancestry = new Set<number>([pid])
 	let current = probes.parent_of(pid)
 
@@ -95,11 +119,11 @@ function ancestry_of(pid: number, probes: ReapProbes): Set<number> {
 
 // This process and every process above it. The Stop hook reads it to tell whether the session that
 // declared a carry record's `--owner "$PPID"` is the one it runs under.
-function own_ancestry(probes: ReapProbes = SYSTEM_PROBES): Set<number> {
+function own_ancestry(probes: TreeProbes = SYSTEM_PROBES): Set<number> {
 	return ancestry_of(process.pid, probes)
 }
 
-function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number> {
+function tree_of(roots: ReadonlyArray<number>, probes: TreeProbes): Array<number> {
 	const tree: Array<number> = []
 	const pending = [...roots]
 	let next = pending.shift()
@@ -116,35 +140,46 @@ function tree_of(roots: ReadonlyArray<number>, probes: ReapProbes): Array<number
 	return tree
 }
 
-function roots_of(issue: string, own: Set<number>, probes: ReapProbes): Array<number> {
+function roots_of(issue: string, own: Set<number>, probes: TreeProbes): Array<number> {
 	const pattern = lane_child_invocation.process_pattern(issue)
 
 	return probes.matching(pattern).filter((pid) => !own.has(pid))
 }
 
 /**
- * Terminate every process of the lane child for `issue` and everything under it, sparing the caller's
- * own ancestry. Returns the pids that were signalled — the empty list is the healthy case, a child
- * that had already ended by itself.
+ * Every process of the lane child for `issue` and everything under it, collected before anything is
+ * signalled, the caller's own ancestry left out.
  */
-function reap_child(issue: string, probes: ReapProbes = SYSTEM_PROBES): Array<number> {
+function lane_tree(issue: string, probes: TreeProbes = SYSTEM_PROBES): Array<number> {
 	const own = own_ancestry(probes)
-	const doomed = tree_of(roots_of(issue, own, probes), probes).filter((pid) => !own.has(pid))
 
-	return doomed.filter((pid) => probes.terminate(pid))
+	return tree_of(roots_of(issue, own, probes), probes).filter((pid) => !own.has(pid))
+}
+
+/**
+ * Terminate every process of the lane child for `lane.issue` and everything under it, sparing the
+ * caller's own ancestry. Returns the pids that were signalled — the empty list is the healthy case, a
+ * child that had already ended by itself.
+ */
+function reap_child(lane: LaneProcesses, probes: ReapProbes = SYSTEM_PROBES): Array<number> {
+	return lane_tree(lane.issue, probes).filter((pid) => probes.terminate(pid))
 }
 
 /** Whether a lane child for `issue` is running, by the same match `reap_child` would end. */
-function is_child_running(issue: string, probes: ReapProbes = SYSTEM_PROBES): boolean {
+function is_child_running(issue: string, probes: TreeProbes = SYSTEM_PROBES): boolean {
 	return roots_of(issue, own_ancestry(probes), probes).length > 0
 }
 
 const lane_reap = {
 	is_child_running,
+	lane_tree,
 	own_ancestry,
 	parse_pids,
+	PS_COMMAND,
 	reap_child,
+	run_probe,
+	SYSTEM_PROBES,
 }
 
-export type { ReapProbes }
+export type { LaneProcesses, ReapProbes, TreeProbes }
 export { lane_reap }