@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-overrun.ts

@@ -0,0 +1,274 @@
+import { agent_argv } from '#scripts/agent/agent-argv'
+import { agent_role_profile } from '#scripts/agent/agent-role-profile'
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { process_identity } from '#scripts/josh/process-identity'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { detached_launch } from '#scripts/run/detached-launch'
+import { run_event_overrun, type OverrunNote } from '#scripts/run/event/run-event-overrun'
+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_breakdown, type Breakdown } from './lane-breakdown'
+import { lane_breakdown_implement } from './lane-breakdown-implement'
+import { lane_breakdown_text, type Report } from './lane-breakdown-text'
+import { lane_child_marker } from './lane-child-marker'
+import { lane_investigation_switch } from './lane-investigation-switch'
+import { lane_ledger, type LedgerEntry } from './lane-ledger'
+import { lane_net_time } from './lane-net-time'
+import { lane_overrun_prompt } from './lane-overrun-prompt'
+import { lane_tail_stats } from './lane-tail-stats'
+
+// A merged lane over the overrun threshold of net time is investigated for its causes
+// (joshuafolkken/kit#4751). `run:merge` asks at each merge: a lane at or under the threshold — its long
+// total spent waiting on a person or an outage included — stops here, before any record of it is read.
+// An overrun launches a detached worker session that reads the lane's records and files each unfiled
+// cause through `issue:file` — the causes one fix place shares as one issue, or folded into an open
+// issue touching the same files (joshuafolkken/kit#4858) — so the next lane starts without waiting on
+// it. The session carries the lane's child mark, which makes `issue:file` count its filings against the
+// lane (`issue-file-cap.ts`), and `--found-during` names the same origin; its overrun mark records the
+// filings as the investigation's, not the child's (joshuafolkken/kit#4880). The launch and the session's result both go on the run's
+// event stream as notes. It runs only while `JOSH_LANE_INVESTIGATION` is on (`lane-investigation-switch.ts`);
+// off by default, an overrun leaves a skipped note in place of the launch (joshuafolkken/kit#5044).
+
+const { EVENT_KIND } = run_event_stream
+const { DISABLED_REASON } = run_event_overrun
+const LOG_PREFIX = 'josh-lane-overrun-'
+const LOG_SUFFIX = '.log'
+const NO_LEDGER = 'no ledger'
+
+// A lane's net minutes and their breakdown by stage, or why there are none (joshuafolkken/kit#4818).
+// `is_commented` says an earlier pass of the lane commented the breakdown on its Issue already;
+// `entries` are the ledger rows the breakdown's details are read off (joshuafolkken/kit#5078).
+type LaneNet =
+	| {
+			kind: 'minutes'
+			minutes: number
+			breakdown: Breakdown
+			entries: ReadonlyArray<LedgerEntry>
+			is_commented: boolean
+	  }
+	| { kind: 'missing'; reason: string }
+
+// A launch that failed is retried once, at the next `run:merge` (joshuafolkken/kit#4930).
+const MAX_LAUNCH_FAILURES = 2
+
+function overrun_notes(events: ReadonlyArray<RunEvent>): ReadonlyArray<OverrunNote> {
+	return events.flatMap((event) =>
+		event.kind === EVENT_KIND.NOTE ? (run_event_overrun.parse(event.text) ?? []) : [],
+	)
+}
+
+// A pass that threw before it noted anything leaves a failure with no minutes.
+function is_thrown(note: OverrunNote): boolean {
+	return note.kind === 'failed' && note.minutes === undefined
+}
+
+// A start note that launched no session.
+function is_launch_failure(note: OverrunNote): boolean {
+	return note.kind === 'failed' && note.minutes !== undefined
+}
+
+function is_final(note: OverrunNote): boolean {
+	return !is_thrown(note) && !is_launch_failure(note)
+}
+
+// A merge `run:merge` collects again — a driver retry, a parent's hand run — finds its lane's note on
+// the stream and launches no second session to file the same causes. A pass that threw before it
+// noted anything leaves only its failure, which the retry answers; a launch that failed is answered
+// once more.
+function is_noted(events: ReadonlyArray<RunEvent>, issue: number): boolean {
+	const notes = overrun_notes(events).filter((note) => note.issue === issue)
+	const failures = notes.filter((note) => is_launch_failure(note)).length
+
+	return failures >= MAX_LAUNCH_FAILURES || notes.some((note) => is_final(note))
+}
+
+// The earlier lanes whose latest note is a launch failure not yet retried; a retry that threw leaves
+// its own note last, so it is not swept up again at every merge after.
+function retried_lanes(events: ReadonlyArray<RunEvent>, issue: number): ReadonlyArray<number> {
+	const latest = new Map(overrun_notes(events).map((note) => [note.issue, note]))
+
+	latest.delete(issue)
+
+	return [...latest.values()]
+		.filter((note) => is_launch_failure(note) && !is_noted(events, note.issue))
+		.map((note) => note.issue)
+}
+
+// A pass that noted the lane before launched nothing it recorded, but it may have commented.
+function is_commented(events: ReadonlyArray<RunEvent>, issue: number): boolean {
+	return overrun_notes(events).some((note) => note.issue === issue)
+}
+
+function net_in(path: string, events: ReadonlyArray<RunEvent>, issue: number): LaneNet {
+	const entries = lane_ledger.read_entries(path)
+	const minutes = lane_net_time.net_minutes(entries, events, issue)
+	const breakdown = lane_breakdown.of(entries, events, issue)
+
+	if (minutes === undefined || breakdown === undefined) {
+		return { kind: 'missing', reason: lane_net_time.missing_reason(entries, issue) }
+	}
+
+	return { kind: 'minutes', minutes, breakdown, entries, is_commented: is_commented(events, issue) }
+}
+
+// The net time of a lane not yet noted, or `undefined` when its note is on the stream already.
+async function net_of(issue: number): Promise<LaneNet | undefined> {
+	const events = await run_event_stream_emit.all_events()
+
+	if (is_noted(events, issue)) return undefined
+
+	const path = await lane_ledger.target()
+
+	return path === undefined ? { kind: 'missing', reason: NO_LEDGER } : net_in(path, events, issue)
+}
+
+// What the session reads, and the four facts it traces each cause to.
+function reading(issue: number, cite: string, minutes: number): string {
+	const directories =
+		lane_breakdown_implement.transcript_directories(issue).join(', ') || 'none found'
+
+	return [
+		`Investigate why lane ${cite} took ${String(minutes)} minutes of net time (dispatch to merge, less`,
+		'its waits on a person and on outages). Leave this checkout as it is: write any file, an issue body',
+		'included, under the system temp directory, and never stage, commit or push.',
+		`Read the lane's transcripts (${directories}), its ship log (\`pnpm josh ship --log ${String(issue)}\`)`,
+		'and the run events (`pnpm josh run:event --from 0`), and find the causes that spent time other than',
+		'waiting. Trace each cause to what can fix it: the span it spent, the signal that led to the wrong call',
+		'or the wait (which command printed what), the `file:line` of the code or document that decided it, and',
+		'where to fix it.',
+	].join(' ')
+}
+
+// One line: `detached_launch` lets a prompt break lines, but a single line keeps the log header whole.
+// The breakdown leads, so the search starts from the longest stage (joshuafolkken/kit#4995).
+function prompt(issue: number, minutes: number, report: Report): string {
+	const reads = reading(issue, issue_cite.plain(issue), minutes)
+	const stages = lane_breakdown_text.line(report)
+
+	return `${stages} ${reads} ${lane_overrun_prompt.handling(issue, minutes)}`
+}
+
+function note_failure(issue: number): (note: string) => void {
+	return (note) => {
+		void run_event_stream_emit.emit(EVENT_KIND.NOTE, run_event_overrun.failed_text(issue, note))
+	}
+}
+
+// A detached investigation session: its prompt, its `env` — the lane marks an overrun's filings count
+// against that lane by, none for the baseline's — the prefix of its log's name, and the note a failed
+// launch leaves.
+interface Investigation {
+	env: Readonly<Record<string, string>>
+	prompt: string
+	log_prefix: string
+	on_failure: (note: string) => void
+}
+
+// What became of the launch, in the words the launch note carries — the overrun's and the baseline
+// investigation's (`lane-baseline.ts`) alike.
+function launch(investigation: Investigation): string {
+	const cwd = process.cwd()
+	const built = agent_argv.resolve_in(investigation.prompt, agent_role_profile.WORKER, cwd)
+
+	if (built.kind === 'rejected') return `not investigated: ${built.note}`
+
+	const request = {
+		argv: built.argv,
+		cwd,
+		env: investigation.env,
+		log_path: stamp_file.stamp_path(investigation.log_prefix, PROJECT_ROOT, LOG_SUFFIX),
+		profile: built.profile,
+	}
+	const result = detached_launch.launch(request, investigation.on_failure)
+
+	return result.kind === 'launched'
+		? run_event_overrun.investigating(result.pid, process_identity.read_start(result.pid))
+		: `not investigated: ${result.note}`
+}
+
+function launched(issue: number, minutes: number, report: Report): string {
+	return launch({
+		env: lane_child_marker.overrun_env_for(String(issue)),
+		prompt: prompt(issue, minutes, report),
+		log_prefix: `${LOG_PREFIX}${String(issue)}-`,
+		on_failure: note_failure(issue),
+	})
+}
+
+type OverranNet = Extract<LaneNet, { kind: 'minutes' }>
+
+// The breakdown goes on the lane's Issue before the session starts, once across the lane's passes; a
+// refused comment costs the comment, not the investigation.
+async function overran_text(issue: number, net: OverranNet): Promise<string> {
+	const report = lane_breakdown_text.report_of(issue, net.breakdown, net.entries)
+	const comment = lane_breakdown_text.comment(issue, net.minutes, report)
+
+	if (!net.is_commented) await git_gh_issue_write.issue_try_comment(String(issue), comment)
+
+	const outcome = launched(issue, net.minutes, report)
+	const longest = lane_breakdown.longest_of(net.breakdown)
+
+	return run_event_overrun.started_text(issue, net.minutes, outcome, longest)
+}
+
+// The note every merged lane leaves: its net minutes at or under the threshold, why it has none, or the
+// launch of its overrun's investigation.
+async function note_text(issue: number, net: LaneNet): Promise<string> {
+	if (net.kind === 'missing') return run_event_overrun.skipped_text(issue, net.reason)
+	// The threshold sets no priority: each filing is ranked by its causes' reducible minutes
+	// (joshuafolkken/kit#4928). `lane:stats` counts the lanes over it on dispatch-to-merge time, not
+	// on this net time.
+	const is_over = lane_tail_stats.is_overrun(net.minutes)
+
+	if (!is_over) return run_event_overrun.within_text(issue, net.minutes)
+
+	// The switch off, an overrun leaves its skip: no breakdown comment and no launch.
+	if (!lane_investigation_switch.is_on()) {
+		return run_event_overrun.skipped_text(issue, DISABLED_REASON)
+	}
+
+	return await overran_text(issue, net)
+}
+
+async function investigate_lane(issue: number): Promise<void> {
+	const net = await net_of(issue)
+
+	if (net === undefined) return
+
+	await run_event_stream_emit.emit(EVENT_KIND.NOTE, await note_text(issue, net))
+}
+
+// Never fails the merge it follows: an error is a note on the stream, not a refused merge.
+async function guarded(issue: number, pass: (issue: number) => Promise<void>): Promise<void> {
+	try {
+		await pass(issue)
+	} catch (error) {
+		note_failure(issue)(detached_launch.note_of(error))
+	}
+}
+
+// The merged lane, then each earlier lane whose launch failed once.
+async function investigate_with_retries(issue: number): Promise<void> {
+	await investigate_lane(issue)
+	const retried = retried_lanes(await run_event_stream_emit.all_events(), issue)
+
+	for (const lane of retried) {
+		// eslint-disable-next-line no-await-in-loop -- one pass at a time appends to the stream, as the merged lane's did
+		await guarded(lane, investigate_lane)
+	}
+}
+
+// With the switch off a lane still notes its net minutes, which `run:board` draws; no earlier lane is
+// retried.
+async function investigate(issue: number): Promise<void> {
+	const pass = lane_investigation_switch.is_on() ? investigate_with_retries : investigate_lane
+
+	await guarded(issue, pass)
+}
+
+const lane_overrun = { investigate, launch }
+
+export type { Investigation }
+export { lane_overrun }

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-paths.ts

@@ -57,6 +57,16 @@ function is_lane_root(directory: string, environment: LaneEnvironment): boolean
 	return DEFAULT_LANE_ROOT_PATTERN.test(path.basename(directory))
 }
 
+// Claude Code's own worktrees (`EnterWorktree`, an `isolation: "worktree"` subagent) sit at
+// `<checkout>/.claude/worktrees/<name>`, and a hook launched in one runs there
+// (joshuafolkken/kit#4617). The session is still the one its checkout started, so a directory under
+// one reads as the checkout that holds it.
+const CLAUDE_WORKTREES_PATTERN = /[/\\]\.claude[/\\]worktrees[/\\][^/\\]+(?:[/\\].*)?$/u
+
+function checkout_of(directory: string): string {
+	return directory.replace(CLAUDE_WORKTREES_PATTERN, '')
+}
+
 // **The inverse of `lane_directory`, and the one lane test that needs no git.** `lane_registry`
 // answers the same question authoritatively by parsing `git worktree list`, but that read is
 // asynchronous and a `PreToolUse` guard is synchronous by contract — so a guard that has to know
@@ -71,7 +81,7 @@ function lane_issue_of(
 	directory: string,
 	environment: LaneEnvironment = process.env,
 ): string | undefined {
-	const resolved = path.resolve(directory)
+	const resolved = checkout_of(path.resolve(directory))
 	const issue = path.basename(resolved)
 
 	if (!issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)) return undefined
@@ -79,6 +89,17 @@ function lane_issue_of(
 	return is_lane_root(path.dirname(resolved), environment) ? issue : undefined
 }
 
+// The lane `directory` (this process's own by default) sits in, as a number; `undefined` outside a
+// lane — the `issue` a ledger row written from inside a lane carries.
+function issue_here(
+	directory: string = process.cwd(),
+	environment: LaneEnvironment = process.env,
+): number | undefined {
+	const lane = lane_issue_of(directory, environment)
+
+	return lane === undefined ? undefined : Number(lane)
+}
+
 function lane_branch(issue: string): string {
 	return `${issue}${LANE_BRANCH_SUFFIX}`
 }
@@ -98,8 +119,10 @@ const lane_paths = {
 	LANE_BRANCH_SUFFIX,
 	LANE_ROOT_KEY,
 	SEAT_LOCK_DIR,
+	checkout_of,
 	default_lane_root,
 	is_lane_entry,
+	issue_here,
 	lane_branch,
 	lane_directory,
 	lane_issue_of,

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

@@ -0,0 +1,133 @@
+#!/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_ledger_write } from './lane-ledger-write'
+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, and to the lane ledger, so `lane:stats` leaves the
+// stopped time out of the lane's implement sub-stages (joshuafolkken/kit#5168).
+
+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 lane_ledger_write.record_lane_state({ issue: Number(issue), state: VERBS[verb].state })
+	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 }