@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -1,15 +1,26 @@
 #!/usr/bin/env tsx
 import { setInterval as every } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
+import { cost_transcript } from '#scripts/cost-runtime/cost-transcript'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
+import { run_event_stream, type RunEvent } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { lane_capacity } from './lane-capacity'
 import { lane_check_stats } from './lane-check-stats'
+import { lane_core_wait_stats } from './lane-core-wait-stats'
+import { lane_gap_stats } from './lane-gap-stats'
+import { lane_held_stats } from './lane-held-stats'
 import { lane_ledger } from './lane-ledger'
 import { lane_process_stats } from './lane-process-stats'
+import { lane_round_two_stats } from './lane-round-two-stats'
 import { lane_sampler, type MeasureContext } from './lane-sampler'
 import { lane_stage_stats } from './lane-stage-stats'
-import { lane_stats } from './lane-stats'
+import { lane_stats, type StatsWindow } from './lane-stats'
 import { lane_stop_stats } from './lane-stop-stats'
+import { lane_test_related_stats } from './lane-test-related-stats'
+import type { ToolCall } from './lane-transcript-calls'
+import { lane_transcript_stats } from './lane-transcript-stats'
 
 // `josh lane:sample` / `josh lane:stats` — the lane-limit measurement.
 //
@@ -23,7 +34,6 @@ import { lane_stop_stats } from './lane-stop-stats'
 
 const ARGV_OFFSET = 2
 const FAILURE_EXIT_CODE = 1
-const MS_PER_SECOND = 1000
 const SAMPLE_VERB = 'sample'
 const STATS_VERB = 'stats'
 const USAGE = [
@@ -102,6 +112,45 @@ async function read_ledger(
 	return path === undefined ? [] : lane_ledger.read_entries(path)
 }
 
+// The run's event stream, read for the parks that end a stop's wait.
+async function read_events(context: MeasureContext): Promise<ReadonlyArray<RunEvent>> {
+	if (context.events_path !== undefined) return run_event_stream.read_events(context.events_path)
+
+	return await run_event_stream_emit.all_events()
+}
+
+// Every lane's transcript directory under this checkout's lane root, read from a lane or the main checkout.
+function transcript_directories(context: MeasureContext): ReadonlyArray<string> {
+	if (context.transcript_directories !== undefined) return context.transcript_directories
+
+	const main_cwd = cost_transcript.session_cwd(process.cwd())
+
+	return cost_transcript.lane_transcript_directories(main_cwd, cost_transcript.home_directory())
+}
+
+interface PeriodRecords {
+	entries: ReturnType<typeof lane_ledger.read_entries>
+	events: ReadonlyArray<RunEvent>
+	calls: ReadonlyArray<ToolCall>
+}
+
+// The tables under the period's row, in the order `lane:stats` prints them.
+function tables_of({ entries, events, calls }: PeriodRecords, window: StatsWindow): Array<string> {
+	return [
+		lane_stage_stats.table(entries, window),
+		lane_stop_stats.table(entries, window, events),
+		lane_gap_stats.table(entries, window, events),
+		lane_round_two_stats.table(entries, window),
+		lane_held_stats.table(entries, window),
+		lane_core_wait_stats.table(entries, window),
+		lane_process_stats.table(entries, window),
+		lane_check_stats.table(entries, window),
+		lane_test_related_stats.table(entries, window),
+		lane_test_related_stats.trigger_table(entries, window),
+		lane_transcript_stats.table(calls, window),
+	]
+}
+
 async function stats_command(
 	rest: ReadonlyArray<string>,
 	context: MeasureContext,
@@ -115,16 +164,13 @@ async function stats_command(
 	const label = { limit: await limit_label(values.limit), period_days }
 	const entries = await read_ledger(context)
 	const row = lane_stats.row(entries, window, label)
+	const records = {
+		entries,
+		events: await read_events(context),
+		calls: lane_transcript_stats.read_calls(transcript_directories(context), window),
+	}
 
-	console.info(
-		[
-			`${lane_stats.header()}\n${row}`,
-			lane_stage_stats.table(entries, window),
-			lane_stop_stats.table(entries, window),
-			lane_process_stats.table(entries, window),
-			lane_check_stats.table(entries, window),
-		].join('\n\n'),
-	)
+	console.info([`${lane_stats.header()}\n${row}`, ...tables_of(records, window)].join('\n\n'))
 
 	return 0
 }

package/scripts/lane/lane-open.ts

@@ -13,6 +13,7 @@ import { lane_paths } from './lane-paths'
 import { lane_registry, type LaneInfo } from './lane-registry'
 import { lane_seed_policy } from './lane-seed'
 import { lane_start_point } from './lane-start-point'
+import { lane_state } from './lane-state'
 
 // Opening a lane: one linked work tree, one branch, one port seed, and the dependencies to run in it.
 //
@@ -256,6 +257,13 @@ async function clear_the_way(
 	await lane_leftover.reclaim(lane_paths.lane_directory(root, issue))
 }
 
+// The lane's state record starts here, so no lane opened from now on is without one.
+async function opened(lane: LaneInfo): Promise<OpenOutcome> {
+	await lane_state.record_change({ issue: lane.issue, state: 'open', command: 'lane:open' })
+
+	return { kind: 'opened', lane }
+}
+
 /**
  * Open the lane for `issue`, or say why it was not opened.
  *
@@ -283,7 +291,7 @@ async function open_lane(issue: string): Promise<OpenOutcome> {
 
 	await materialize(plan, repository_root)
 
-	return { kind: 'opened', lane: plan.lane }
+	return await opened(plan.lane)
 }
 
 const lane_open = {

package/scripts/lane/lane-parked.ts

@@ -1,7 +1,7 @@
-import { has_label_name, NEEDS_DECISION_LABEL } from '#scripts/issue/issue-labels'
+import { has_parked_label } from '#scripts/issue/issue-labels'
 import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 
-// Whether an issue is parked for a person — the `needs-decision` label — read live, so a session a
+// Whether an issue is parked for a person — any park label (`PARKED_LABELS`) — read live, so a session a
 // lane's broker would start for it is refused once the run has parked it (joshuafolkken/kit#3878).
 //
 // **An issue whose state cannot be read is not parked**: the read gates every brokered review, so
@@ -10,7 +10,7 @@ import { issue_state_cli } from '#scripts/issue/issue-state-cli'
 async function is_parked(issue: string): Promise<boolean> {
 	const read = await issue_state_cli.read_issue(issue)
 
-	return read.kind === 'state' && has_label_name(read.state.labels, NEEDS_DECISION_LABEL)
+	return read.kind === 'state' && has_parked_label(read.state.labels)
 }
 
 const lane_parked = { is_parked }

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

@@ -0,0 +1,130 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+import { lane_pause, type LaneSignalled } from './lane-pause'
+import type { LaneProcesses } from './lane-reap'
+import { lane_registry } from './lane-registry'
+import { lane_state } from './lane-state'
+
+// `josh lane:pause <issue> | --all` and `josh lane:resume <issue> | --all` — one script told apart by
+// the verb the registry passes first. A named lane with no child process to signal exits non-zero, so a
+// caller never takes a pause that stopped nothing as done — a detached resident signalled alone counts
+// as nothing. A lane whose detached processes could not be read exits non-zero too, since a resume
+// may have left one of them stopped. A lane whose child was signalled has the change written to its state record and to the
+// run's event stream, so who halted it is on record.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ALL_FLAG = '--all'
+const USAGE = [
+	'Usage: josh lane:pause <issue-number> | josh lane:pause --all',
+	'       josh lane:resume <issue-number> | josh lane:resume --all',
+].join('\n')
+
+const VERBS = {
+	pause: { act: 'pause_lane', done: 'paused', state: 'paused' },
+	resume: { act: 'resume_lane', done: 'resumed', state: 'running' },
+} as const
+
+type Verb = keyof typeof VERBS
+
+function is_verb(value: string | undefined): value is Verb {
+	return value === 'pause' || value === 'resume'
+}
+
+async function lanes_of(target: ReadonlyArray<string>): Promise<Array<LaneProcesses> | undefined> {
+	const [issue, ...rest] = target
+
+	if (issue === undefined || rest.length > 0) return undefined
+	if (issue === ALL_FLAG) return await lane_pause.open_lanes()
+	if (!issue_number_shape.is_issue_number(issue)) return undefined
+
+	return [await lane_registry.lane_location(issue)]
+}
+
+function outcome_of(verb: Verb, result: LaneSignalled): string {
+	const { done } = VERBS[verb]
+	const count = String(result.signalled.length)
+
+	if (result.signalled.length === 0) return `no child process running — nothing ${done}`
+
+	if (result.child.length === 0) {
+		return `no child process running — ${done} ${count} detached process(es), state unchanged`
+	}
+
+	return `${done} ${count} process(es)`
+}
+
+const UNREAD_NOTE =
+	' — could not read the detached processes (lsof or ps failed); any of them was missed'
+
+// One line per lane: how many of its processes were signalled, and whether its residents went unread.
+function report(verb: Verb, issue: string, result: LaneSignalled): void {
+	const note = result.is_unread ? UNREAD_NOTE : ''
+
+	console.info(`lane:${verb} ${issue_cite.plain(issue)}: ${outcome_of(verb, result)}${note}`)
+}
+
+async function record(verb: Verb, issue: string): Promise<void> {
+	const command = `lane:${verb}`
+
+	await lane_state.record_change({ issue, state: VERBS[verb].state, command })
+	await run_event_stream_emit.emit(
+		run_event_stream.EVENT_KIND.LANE_STATE,
+		`${issue_cite.plain(issue)} ${VERBS[verb].done} by ${command}`,
+	)
+}
+
+async function settle(verb: Verb, lane: LaneProcesses): Promise<LaneSignalled> {
+	const result = lane_pause[VERBS[verb].act](lane)
+
+	report(verb, lane.issue, result)
+	if (result.child.length > 0) await record(verb, lane.issue)
+
+	return result
+}
+
+// A named lane with no child signalled fails; any lane whose residents went unread fails.
+function is_failed(result: LaneSignalled, is_named: boolean): boolean {
+	return result.is_unread || (is_named && result.child.length === 0)
+}
+
+async function apply(
+	verb: Verb,
+	lanes: ReadonlyArray<LaneProcesses>,
+	is_named: boolean,
+): Promise<number> {
+	const results = await Promise.all(lanes.map(async (lane) => await settle(verb, lane)))
+
+	return results.some((result) => is_failed(result, is_named))
+		? FAILURE_EXIT_CODE
+		: SUCCESS_EXIT_CODE
+}
+
+function report_usage(): number {
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [verb, ...target] = argv
+	if (!is_verb(verb)) return report_usage()
+	const lanes = await lanes_of(target)
+
+	return lanes === undefined ? report_usage() : await apply(verb, lanes, target[0] !== ALL_FLAG)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_pause_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_pause_cli }

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-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 }