@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-paused-spans.ts

@@ -0,0 +1,97 @@
+import {
+	lane_ledger,
+	type DispatchEntry,
+	type LaneStateChangeEntry,
+	type LedgerEntry,
+} from './lane-ledger'
+
+// The spans each lane stood paused, read off the `lane-state` lines `lane:pause` and `lane:resume`
+// append to the ledger (joshuafolkken/kit#5168). A SIGSTOP leaves the call in flight on the clock, so a
+// measurement of a lane's time takes its overlap with these out: `lane:pause --all` once put seven
+// hours into one plan call and one check call.
+//
+// **A pause opens a span, the lane's next resume or dispatch closes it** — `lane:restart` and a
+// re-dispatch start a fresh child without a resume; a pause with neither yet stays open, and a
+// resume with no pause before it closes nothing.
+
+const PAUSED = 'paused'
+const LANE_ISSUE_PATTERN = /-(?<issue>\d+)$/u
+
+interface PausedSpan {
+	from_ms: number
+	to_ms: number
+}
+
+// Each lane's paused spans, by issue number.
+type PausedSpans = ReadonlyMap<number, ReadonlyArray<PausedSpan>>
+
+interface Walk {
+	spans: Array<PausedSpan>
+	open_ms: number | undefined
+}
+
+// A ledger line that opens or closes a lane's paused span.
+type Change = LaneStateChangeEntry | DispatchEntry
+
+const NONE: ReadonlyArray<PausedSpan> = []
+
+function is_change(entry: LedgerEntry): entry is Change {
+	return entry.kind === lane_ledger.KIND.LANE_STATE || entry.kind === lane_ledger.KIND.DISPATCH
+}
+
+function is_pause(change: Change): boolean {
+	return change.kind === lane_ledger.KIND.LANE_STATE && change.state === PAUSED
+}
+
+function step(walk: Walk, change: Change): Walk {
+	const at_ms = Date.parse(change.at)
+
+	if (is_pause(change)) return { spans: walk.spans, open_ms: walk.open_ms ?? at_ms }
+	if (walk.open_ms === undefined) return walk
+
+	return { spans: [...walk.spans, { from_ms: walk.open_ms, to_ms: at_ms }], open_ms: undefined }
+}
+
+// One lane's changes, oldest first, folded into its spans.
+function spans_of(changes: ReadonlyArray<Change>): Array<PausedSpan> {
+	let walk: Walk = { spans: [], open_ms: undefined }
+
+	for (const change of changes) walk = step(walk, change)
+	if (walk.open_ms === undefined) return walk.spans
+
+	return [...walk.spans, { from_ms: walk.open_ms, to_ms: Infinity }]
+}
+
+function by_lane(entries: ReadonlyArray<LedgerEntry>): PausedSpans {
+	const changes = entries
+		.filter((entry) => is_change(entry))
+		.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+	const issues = [...new Set(changes.map((change) => change.issue))]
+
+	return new Map(
+		issues.map((issue) => [issue, spans_of(changes.filter((change) => change.issue === issue))]),
+	)
+}
+
+// The spans of the lane a transcript directory (`<lane-root-slug>-<issue>`) belongs to.
+function of_lane(spans: PausedSpans, lane: string): ReadonlyArray<PausedSpan> {
+	const issue = LANE_ISSUE_PATTERN.exec(lane)?.groups?.['issue']
+
+	return issue === undefined ? NONE : (spans.get(Number(issue)) ?? NONE)
+}
+
+// How much of `from_ms`…`to_ms` the spans cover.
+function overlap_ms(spans: ReadonlyArray<PausedSpan>, from_ms: number, to_ms: number): number {
+	let sum = 0
+
+	for (const span of spans) {
+		sum += Math.max(0, Math.min(to_ms, span.to_ms) - Math.max(from_ms, span.from_ms))
+	}
+
+	return sum
+}
+
+const lane_paused_spans = { by_lane, of_lane, overlap_ms }
+
+export type { PausedSpan, PausedSpans }
+export { lane_paused_spans }

package/scripts/lane/lane-plan-check.ts

@@ -0,0 +1,207 @@
+import { auto_ok_cli } from '#scripts/auto-ok/auto-ok-cli'
+import { backlog_overlap, type Clash } from '#scripts/backlog/backlog-overlap'
+import { backlog_plan_comment } from '#scripts/backlog/backlog-plan-comment'
+import type { OpenIssueData } from '#scripts/git/git-schemas'
+import { has_any_label, IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { run_hold_cli } from '#scripts/run/hold/run-hold-cli'
+import { lane_plan, type LanePlan } from './lane-plan'
+import { lane_yield, type YieldAt } from './lane-yield'
+
+// The check `josh lane:plan <issue> <path>...` runs (`lane-plan-cli.ts`) — record the files a lane child
+// plans to edit, and answer once whether a running lane that planned earlier declares or plans one of
+// them (joshuafolkken/kit#4864).
+//
+// **The check happens before the first edit**, so a conflict the bodies did not show is met while the
+// later lane has nothing to throw away, not at its ship. **A lane that finds a holder gives its lane
+// back** rather than waiting for the holder to end (joshuafolkken/kit#4926): polling kept the seat taken
+// while nothing moved, which made two lanes one. It notes its yield (`lane-yield.ts`), keeps its plan as
+// yielded, releases its hold, prints `yield` and the child ends; the issue is offered again once the
+// holder's lane ends. A document under `docs/` is never a clash (`backlog-overlap.ts` →
+// `is_shared_document`).
+//
+// **`--probe` answers the same question and records nothing** (joshuafolkken/kit#5211) — no plan, no
+// yield, no release. **`run:entry` gives the lane back at the entry** in a lane child, before any
+// reading, on the paths dispatch gated on (`yield_at_entry`), so a holder that planned them since
+// dispatch takes the lane back before the investigation the later `lane:plan` would have thrown away.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const YIELD_EXIT_CODE = 2
+const RELEASE_FLAG = '--release'
+const RUNNING = new Set([IN_PROGRESS_LABEL])
+const UNREAD = 'unread'
+
+// What the overlap check found: the clash, none, or a listing it could not read.
+type Probe = Clash | typeof UNREAD | undefined
+
+function plan_of(argv: ReadonlyArray<string>, now: Date): LanePlan | undefined {
+	const [issue = '', ...paths] = argv
+
+	const claims = [...backlog_overlap.path_claims(paths)]
+
+	if (!issue_number_shape.is_issue_number(issue) || claims.length === 0) return undefined
+
+	return { issue: Number(issue), paths: claims, planned_at: now.toISOString() }
+}
+
+// The opted-in listing — the running lanes carry the pickup label, so it holds their bodies.
+async function opted_in(): Promise<ReadonlyArray<OpenIssueData> | undefined> {
+	const read = await auto_ok_cli.fetch_opted_in()
+
+	return read.kind === 'read' ? read.issues : undefined
+}
+
+function running_of(issues: ReadonlyArray<OpenIssueData>): ReadonlyArray<OpenIssueData> {
+	return issues.filter((issue) => has_any_label(issue.labels, RUNNING))
+}
+
+function clash_among(
+	plan: LanePlan,
+	issues: ReadonlyArray<OpenIssueData>,
+	directory: string,
+): Clash | undefined {
+	const declared = lane_plan.with_plans(backlog_overlap.declared_of(issues), directory)
+
+	return lane_plan.clash_of(plan, declared, directory)
+}
+
+function overlap_text(issue: number, clash: Clash): string {
+	const holder = session_cite.issue(clash.holder)
+
+	return `${session_cite.issue(issue)}'s planned \`${clash.path}\` overlaps \`${clash.claimed}\`, which ${holder} declares or plans`
+}
+
+// The yield goes on the stream before the child is told to end, so `run:merge` books it `yielded`. The
+// plan is kept as yielded (`lane_plan.release`) and the child's hold released, so it can end with no
+// edit; `yield` is printed last, after the release's own verdict.
+async function give_back(
+	plan: LanePlan,
+	clash: Clash,
+	directory: string,
+	at: YieldAt,
+): Promise<number> {
+	const overlap = overlap_text(plan.issue, clash)
+
+	lane_plan.record({ ...plan, yielded: true }, directory)
+	await lane_yield.record_yield(plan.issue, overlap, at)
+	await run_hold_cli.run([RELEASE_FLAG, String(plan.issue)])
+	console.error(
+		`${overlap}, so it gives its lane back: end the session now, with no edit — \`run:merge\` closes the lane, and the issue is offered again once that lane ends.`,
+	)
+	console.info('yield')
+
+	return YIELD_EXIT_CODE
+}
+
+function clear_answer(): number {
+	console.info('clear')
+
+	return SUCCESS_EXIT_CODE
+}
+
+function clear(plan: LanePlan, directory: string): number {
+	lane_plan.record({ ...plan, cleared: true, yielded: undefined }, directory)
+
+	return clear_answer()
+}
+
+// An unread listing proves no holder absent, so it holds the edit back for one more ask.
+function unread(): number {
+	console.error(auto_ok_cli.UNREADABLE_MESSAGE)
+	console.info('wait')
+
+	return FAILURE_EXIT_CODE
+}
+
+// The overlap check alone, writing nothing — what `--probe` answers and `check_plan` acts on.
+async function probe(plan: LanePlan, directory: string): Promise<Probe> {
+	const issues = await opted_in()
+
+	return issues === undefined ? UNREAD : clash_among(plan, running_of(issues), directory)
+}
+
+async function check_plan(plan: LanePlan, directory: string): Promise<number> {
+	lane_plan.record(plan, directory)
+	const found = await probe(plan, directory)
+
+	if (found === UNREAD) return unread()
+
+	return found === undefined
+		? clear(plan, directory)
+		: await give_back(plan, found, directory, 'summary')
+}
+
+// `--probe`'s answer: the same tokens and exit codes as the plan's, with nothing written.
+async function probe_answer(plan: LanePlan, directory: string): Promise<number> {
+	const found = await probe(plan, directory)
+
+	if (found === UNREAD) return unread()
+	if (found === undefined) return clear_answer()
+
+	console.error(`${overlap_text(plan.issue, found)}.`)
+	console.info('yield')
+
+	return YIELD_EXIT_CODE
+}
+
+// A lane that plans again — after a yield, or to add a file — keeps the place in line its first plan
+// took: a fresh time would hand the files it already holds to a lane that planned after it. A yield
+// stays marked until the plan clears, so a check the listing could not answer keeps the plan its lane
+// yielded on.
+function placed(plan: LanePlan, directory: string): LanePlan {
+	const recorded = lane_plan.read(plan.issue, directory)
+	if (recorded === undefined) return plan
+
+	return { ...plan, planned_at: recorded.planned_at, yielded: recorded.yielded }
+}
+
+// The paths `issue` declares in the scope dispatch gated on — its recorded plan, else its plan comment,
+// else its body (`backlog-plan-comment.ts`) — read off the same listing the probe reads the holders from.
+async function entry_plan(
+	issue: number,
+	issues: ReadonlyArray<OpenIssueData>,
+	directory: string,
+): Promise<LanePlan | undefined> {
+	const own = issues.filter((candidate) => candidate.number === issue)
+	const declared = await backlog_plan_comment.declared_of(own, directory)
+	const plan = plan_of([String(issue), ...(declared.get(issue) ?? [])], new Date())
+
+	return plan === undefined ? undefined : placed(plan, directory)
+}
+
+async function entry_yield(
+	issue: number,
+	issues: ReadonlyArray<OpenIssueData>,
+	directory: string,
+): Promise<boolean> {
+	const plan = await entry_plan(issue, issues, directory)
+	const found = plan === undefined ? undefined : clash_among(plan, running_of(issues), directory)
+
+	if (plan === undefined || found === undefined) return false
+
+	await give_back(plan, found, directory, 'entry')
+
+	return true
+}
+
+// **The entry probe** `run:entry` runs in a lane child before the investigation: a clash gives the lane back
+// there, noted `at: entry`, the way `lane:plan` would after the summary. A clear answer, an unread
+// listing or no declared path writes nothing — the later `lane:plan` still checks at the first edit.
+async function yield_at_entry(issue: number, directory: string = process.cwd()): Promise<boolean> {
+	const issues = await opted_in()
+
+	return issues === undefined ? false : await entry_yield(issue, issues, directory)
+}
+
+const lane_plan_check = {
+	YIELD_EXIT_CODE,
+	check_plan,
+	placed,
+	plan_of,
+	probe_answer,
+	yield_at_entry,
+}
+
+export { lane_plan_check }

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

@@ -0,0 +1,41 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { lane_plan_check } from './lane-plan-check'
+
+// `josh lane:plan <issue> <path>... [--probe]` — the command line over `lane-plan-check.ts`, which holds
+// the check and the yield so `run:entry` can import them without this entry's main guard.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const PROBE_FLAG = '--probe'
+const USAGE = 'Usage: josh lane:plan <issue-number> <path> [<path> ...] [--probe]'
+const { YIELD_EXIT_CODE } = lane_plan_check
+
+async function run(
+	argv: ReadonlyArray<string>,
+	directory: string = process.cwd(),
+): Promise<number> {
+	const plan = lane_plan_check.plan_of(
+		argv.filter((token) => token !== PROBE_FLAG),
+		new Date(),
+	)
+	const action = argv.includes(PROBE_FLAG)
+		? lane_plan_check.probe_answer
+		: lane_plan_check.check_plan
+
+	if (plan !== undefined) return await action(lane_plan_check.placed(plan, directory), directory)
+
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_plan_cli = { USAGE, YIELD_EXIT_CODE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { lane_plan_cli }

package/scripts/lane/lane-plan.ts

@@ -0,0 +1,144 @@
+import { backlog_overlap, type Clash, type Declared } from '#scripts/backlog/backlog-overlap'
+import { git_common_directory } from '#scripts/git/git-common-directory'
+import { durable_state } from '#scripts/josh/durable-state'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+
+// The files a lane child plans to edit, recorded by `josh lane:plan` once its work summary settles.
+//
+// **An issue body names the paths its reporter saw, not the ones the change touches.**
+// joshuafolkken/kit#4858 and joshuafolkken/kit#4859 declared disjoint paths, ran side by side, and both
+// edited `scripts/lane/lane-overrun.ts`; the second ship stopped on the conflict (joshuafolkken/kit#4864).
+// The plan is the first moment the touched files are known, so it is recorded here and read as the
+// declaration in place of the body — by `lane:plan` to hold the later lane back, and by `backlog:next`.
+//
+// **Keyed to the repository and the issue, not the work tree**, and kept in the common git directory
+// (`durable-state.ts`): the lane records it from its own work tree and the parent reads it from the main
+// checkout, both resolve the same directory, and a reboot does not drop a running lane's plan.
+// `lane:close` releases it with the lane (`release`).
+
+const lane_plan_schema = z.object({
+	issue: z.number(),
+	paths: z.array(z.string()),
+	planned_at: z.string(),
+	cleared: z.boolean().optional(),
+	// The lane gave its lane back on this plan (`lane-yield.ts`), so the plan outlives the lane.
+	yielded: z.boolean().optional(),
+})
+
+type LanePlan = z.infer<typeof lane_plan_schema>
+
+function plan_path(repository: string, issue: number): string {
+	return durable_state.path(durable_state.PREFIX.LANE_PLAN, repository, `-${String(issue)}.json`)
+}
+
+function record(plan: LanePlan, directory: string): boolean {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository === undefined) return false
+
+	stamp_file.replace_stamp(plan_path(repository, plan.issue), plan)
+
+	return true
+}
+
+function remove(issue: number, directory: string): void {
+	const repository = git_common_directory.repository(directory)
+
+	if (repository !== undefined) stamp_file.remove_stamp(plan_path(repository, issue))
+}
+
+function read(issue: number, directory: string): LanePlan | undefined {
+	const repository = git_common_directory.repository(directory)
+	const text =
+		repository === undefined ? undefined : stamp_file.read_stamp_text(plan_path(repository, issue))
+
+	return text === undefined ? undefined : json_value.parse_with(text, lane_plan_schema)
+}
+
+// Whether `issue` has no plan that `lane:plan` cleared, in a repository that can hold one — a checkout
+// with no common git directory cannot record a plan, so it is never asked for one. A plan recorded but
+// not cleared — a yield, an unread listing — lifts no hold: the record is written before the check.
+function is_uncleared(issue: number, directory: string): boolean {
+	return (
+		git_common_directory.repository(directory) !== undefined &&
+		read(issue, directory)?.cleared !== true
+	)
+}
+
+// What an ended lane does with its plan. A plan the lane yielded on (`lane-yield.ts`,
+// joshuafolkken/kit#4926) stays: `backlog:next` holds the issue back on it while the holder runs, and
+// its next lane keeps the place in line it took. Any other plan goes — cleared, or left by a lane that
+// ended before its check answered — so the issue's next lane plans afresh rather than inheriting the
+// files and the place in line of a run that is over.
+function release(issue: number, directory: string): void {
+	if (read(issue, directory)?.yielded !== true) remove(issue, directory)
+}
+
+// `declared` with each issue's recorded plan, if any, in place of what it declares (joshuafolkken/kit#4937).
+function with_plans(declared: Declared, directory: string): Declared {
+	const replaced = [...declared].map(([issue, paths]): [number, ReadonlySet<string>] => [
+		issue,
+		new Set(read(issue, directory)?.paths ?? paths),
+	])
+
+	return new Map(replaced)
+}
+
+// Whether `other` holds its files ahead of `plan`: it was cleared, or it planned first. A cleared lane
+// may already be editing, so a kept place in line never takes its files from it.
+function goes_before(other: LanePlan, plan: LanePlan): boolean {
+	return other.cleared === true || other.planned_at < plan.planned_at
+}
+
+// The `holders` whose plan goes before `plan` — the only ones it yields to. Of two uncleared plans the
+// earlier goes first, so two lanes that plan the same file never yield to each other.
+function earlier_holders(
+	plan: LanePlan,
+	holders: ReadonlyArray<number>,
+	directory: string,
+): Array<number> {
+	return holders.filter((holder) => {
+		const other = holder === plan.issue ? undefined : read(holder, directory)
+
+		return other !== undefined && goes_before(other, plan)
+	})
+}
+
+// The first file of `plan` that a lane in `declared` — its recorded plan, else its body — holds ahead of
+// it. `lane:plan` yields on it, and a named run holds the yielded issue back on the same answer.
+function clash_of(plan: LanePlan, declared: Declared, directory: string): Clash | undefined {
+	const holders = earlier_holders(plan, [...declared.keys()], directory)
+
+	return backlog_overlap.path_clash(new Set(plan.paths), declared, holders)
+}
+
+function is_yielded(issue: number, directory: string): boolean {
+	return read(issue, directory)?.yielded === true
+}
+
+// Whether `issue` yielded on a plan that a lane in `declared` still holds one of its files ahead of —
+// what a named run holds the issue back on, as `backlog:next` does on the same kept plan
+// (joshuafolkken/kit#4926). Without it the run relaunches the issue at once, and the lane yields again.
+function is_yield_held(issue: number, declared: Declared, directory: string): boolean {
+	const plan = read(issue, directory)
+
+	return plan?.yielded === true && clash_of(plan, declared, directory) !== undefined
+}
+
+const lane_plan = {
+	clash_of,
+	earlier_holders,
+	is_uncleared,
+	is_yield_held,
+	is_yielded,
+	read,
+	record,
+	release,
+	remove,
+	with_plans,
+}
+
+export { lane_plan }
+export type { LanePlan }

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 }