@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/lane/lane-ledger.ts

@@ -1,12 +1,26 @@
 import { closeSync, constants, openSync, writeSync } from 'node:fs'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
+import { stamped_memo } from '#scripts/lib/stamped-memo'
 import { run_carry } from '#scripts/run/carry/run-carry'
-import { z } from 'zod'
+import {
+	lane_ledger_schema,
+	type CoreWaitRecord,
+	type GateRecord,
+	type HeldRecord,
+	type LedgerEntry,
+	type OverlapRecord,
+	type RoundTwoRecord,
+	type StageRecord,
+	type StopRecord,
+	type TestRelatedRecord,
+	type UnitFileRecord,
+} from './lane-ledger-schema'
 
 // The measurement ledger the lane limit is tuned against: one JSON line per
 // lane merge, per finished `josh gate`, per machine-load sample, per lane dispatch, per finished
-// `josh ship` stage and per stopped `josh ship`, read back by `josh lane:stats`.
+// `josh ship` stage, per stopped `josh ship`, per round-2 decision, per core-budget wait and per
+// `josh test:related` run, read back by `josh lane:stats`. Each line's shape is `lane-ledger-schema.ts`.
 //
 // **Its own file rather than the run's event stream.** The stream is capped at 500 events and is
 // rewritten whole on every append, which is right for "where is the run" and wrong for a measurement
@@ -23,101 +37,20 @@ const LEDGER_SUFFIX = '.jsonl'
 const LINE_SEPARATOR = '\n'
 // `followup`'s wait for CI — a stage of a lane's run that no `josh ship` stage is the whole of.
 const CI_WAIT_STAGE = 'ci-wait'
+// The part of `followup`'s waits CodeRabbit spent running or rate-limited, and the rate-limited part
+// alone (joshuafolkken/kit#4574).
+const CODERABBIT_WAIT_STAGE = 'coderabbit-wait'
+const CODERABBIT_RATE_LIMIT_STAGE = 'coderabbit-rate-limit'
+// A detached `josh ship`'s fast checks in the agent's own turn — not a resumable ship stage, since the
+// supervised gate runs them again (joshuafolkken/kit#4382).
+const PRE_DETACH_STAGE = 'pre-detach'
 const LEDGER_FILE_MODE = 0o600
 // The flags `detached-launch.ts` appends its log with, for the same deterministic shared-temp path.
 const { O_APPEND, O_CREAT, O_NOFOLLOW, O_WRONLY } = constants
 // eslint-disable-next-line no-bitwise -- POSIX open flags are a bit field; `||` here would be a bug
 const APPEND_FLAGS = O_WRONLY | O_APPEND | O_CREAT | O_NOFOLLOW
 
-const KIND = {
-	MERGE: 'merge',
-	GATE: 'gate',
-	LOAD: 'load',
-	DISPATCH: 'dispatch',
-	STAGE: 'stage',
-	STOP: 'stop',
-} as const
-
-const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
-const gate_schema = z.object({
-	kind: z.literal(KIND.GATE),
-	at: z.string(),
-	elapsed_ms: z.number(),
-	is_passed: z.boolean(),
-	// The unit suite's own duration, present when this gate ran it — the one
-	// record of a full vitest run `josh metrics` reads, so the suite is never timed twice.
-	unit_ms: z.number().optional(),
-	// The whole cores busy outside this gate, beyond the machine's baseline, at its start or its end —
-	// whichever was higher. Absent when the machine could not be read.
-	external_cores: z.number().optional(),
-})
-// `available_mb`, `swapped_mb` and `lanes` are optional because each read can fail on its own — a
-// platform with no memory reading, a `git worktree` call that did not answer — and a sample is still
-// worth its load. `swapped_mb` is `machine_capacity`'s counter, every page swapped since boot.
-// Both memory fields were renamed with their meaning (joshuafolkken/kit#3593): an older row's
-// `free_mb` / `swap_mb` are stripped on read, so the two measurements never share a column.
-const process_kind_schema = z.object({
-	kind: z.string(),
-	cpu_percent: z.number(),
-	rss_mb: z.number(),
-	count: z.number(),
-})
-const load_schema = z.object({
-	kind: z.literal(KIND.LOAD),
-	at: z.string(),
-	load: z.number(),
-	available_mb: z.number().optional(),
-	swapped_mb: z.number().optional(),
-	lanes: z.number().optional(),
-	// The heaviest process kinds at the instant of the sample (`lane-process-load.ts`), so the load the
-	// core budget's ledger does not explain can be read back by what made it (joshuafolkken/kit#3874).
-	processes: z.array(process_kind_schema).optional(),
-})
-// A lane child started on `issue` — the instant its implementation is timed from.
-const dispatch_schema = z.object({
-	kind: z.literal(KIND.DISPATCH),
-	at: z.string(),
-	issue: z.number(),
-})
-// One finished stage of a lane's run, passed or failed: `at` is its end and `elapsed_ms` its length, so
-// its start is read from the two. `issue` is absent where the writer does not hold one — `followup`'s
-// CI wait, which is timed on a path that fails before the issue is known.
-const stage_schema = z.object({
-	kind: z.literal(KIND.STAGE),
-	at: z.string(),
-	stage: z.string(),
-	elapsed_ms: z.number(),
-	issue: z.number().optional(),
-})
-// A `josh ship` that stopped on `issue`: `reason` is the stage it stopped at, or `conflict` — the
-// retrospective's stop reason. How long it stayed stopped is derived from the next ship stage, not
-// recorded, so a resumed ship never has to know the stop it ends.
-const stop_schema = z.object({
-	kind: z.literal(KIND.STOP),
-	at: z.string(),
-	issue: z.number(),
-	reason: z.string(),
-})
-const entry_schema = z.discriminatedUnion('kind', [
-	merge_schema,
-	gate_schema,
-	load_schema,
-	dispatch_schema,
-	stage_schema,
-	stop_schema,
-])
-
-type LedgerEntry = z.infer<typeof entry_schema>
-type MergeEntry = z.infer<typeof merge_schema>
-type GateEntry = z.infer<typeof gate_schema>
-type LoadEntry = z.infer<typeof load_schema>
-type DispatchEntry = z.infer<typeof dispatch_schema>
-type StageEntry = z.infer<typeof stage_schema>
-type StopEntry = z.infer<typeof stop_schema>
-// What a finished gate reports; the ledger stamps the kind and the time.
-type GateRecord = Omit<GateEntry, 'kind' | 'at'>
-type StageRecord = Omit<StageEntry, 'kind' | 'at'>
-type StopRecord = Omit<StopEntry, 'kind' | 'at'>
+const { KIND, entry_schema } = lane_ledger_schema
 
 function target_of(repository: string): string {
 	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
@@ -144,8 +77,8 @@ async function target(): Promise<string | undefined> {
 
 // **Append, never rewrite** — `O_APPEND` keeps each short line whole across concurrent writers, and
 // `O_NOFOLLOW` plus `stamp_file`'s ownership test keep a planted link or another account's file from
-// receiving it.
-function append(path: string, entry: LedgerEntry): void {
+// receiving it. Any JSON-lines log takes it — the durable review stop log too (joshuafolkken/kit#4519).
+function append(path: string, entry: object): void {
 	const descriptor = openSync(path, APPEND_FLAGS, LEDGER_FILE_MODE)
 
 	try {
@@ -194,6 +127,45 @@ async function record_stop(stop: StopRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.STOP, at: now_iso(), ...stop }, path)
 }
 
+async function record_overlap(overlap: OverlapRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.OVERLAP, at: now_iso(), ...overlap }, path)
+}
+
+// `waiting` is written only when the offer named issues, so a hold that waited on none stays one short line.
+async function record_held(held: HeldRecord, path?: string): Promise<void> {
+	const waiting = held.waiting ?? []
+	const named = waiting.length > 0 ? { waiting: [...waiting] } : {}
+
+	await record({ kind: KIND.HELD, at: now_iso(), reason: held.reason, ...named }, path)
+}
+
+async function record_released(path?: string): Promise<void> {
+	await record({ kind: KIND.RELEASED, at: now_iso() }, path)
+}
+
+async function record_offerable(is_offerable: boolean, path?: string): Promise<void> {
+	await record({ kind: KIND.OFFERABLE, at: now_iso(), is_offerable }, path)
+}
+
+async function record_round_two(round_two: RoundTwoRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.ROUND_TWO, at: now_iso(), ...round_two }, path)
+}
+
+async function record_core_wait(wait: CoreWaitRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.CORE_WAIT, at: now_iso(), ...wait }, path)
+}
+
+async function record_unit_files(
+	files: ReadonlyArray<UnitFileRecord>,
+	path?: string,
+): Promise<void> {
+	await record({ kind: KIND.UNIT_FILES, at: now_iso(), files: [...files] }, path)
+}
+
+async function record_test_related(run: TestRelatedRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.TEST_RELATED, at: now_iso(), ...run }, path)
+}
+
 function parse_line(line: string): LedgerEntry | undefined {
 	return entry_schema.safeParse(json_value.parse_or_undefined(line)).data
 }
@@ -202,9 +174,7 @@ function is_present(entry: LedgerEntry | undefined): entry is LedgerEntry {
 	return entry !== undefined
 }
 
-// Every entry, oldest first. A malformed line — a write cut short — is skipped rather than making the
-// whole ledger unreadable, and an absent or unowned file is an empty ledger.
-function read_entries(path: string): ReadonlyArray<LedgerEntry> {
+function parse_entries(path: string): ReadonlyArray<LedgerEntry> {
 	const raw = stamp_file.read_stamp_text(path)
 
 	if (raw === undefined) return []
@@ -215,20 +185,61 @@ function read_entries(path: string): ReadonlyArray<LedgerEntry> {
 		.filter(is_present)
 }
 
+// Each ledger's entries, parsed again only once the file itself has changed (joshuafolkken/kit#4263).
+const parsed_ledgers = stamped_memo.create<ReadonlyArray<LedgerEntry>>()
+
+// Every entry, oldest first. A malformed line — a write cut short — is skipped rather than making the
+// whole ledger unreadable, and an absent or unowned file is an empty ledger.
+function read_entries(path: string): ReadonlyArray<LedgerEntry> {
+	return parsed_ledgers.of(path, stamped_memo.file_stamp(path), () => parse_entries(path))
+}
+
 const lane_ledger = {
 	CI_WAIT_STAGE,
+	CODERABBIT_RATE_LIMIT_STAGE,
+	CODERABBIT_WAIT_STAGE,
 	KIND,
+	PRE_DETACH_STAGE,
 	append,
 	read_entries,
 	record,
+	record_core_wait,
 	record_dispatch,
 	record_gate,
+	record_held,
+	record_released,
 	record_merge,
+	record_overlap,
+	record_offerable,
+	record_round_two,
 	record_stage,
 	record_stop,
+	record_test_related,
+	record_unit_files,
 	target,
 	target_of,
 }
 
-export type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry, StageEntry, StopEntry }
+export type {
+	CoreWaitEntry,
+	CoreWaitRecord,
+	DispatchEntry,
+	GateCheckRecord,
+	GateEntry,
+	HeldEntry,
+	LedgerEntry,
+	LoadEntry,
+	MergeEntry,
+	OfferableEntry,
+	OverlapEntry,
+	OverlapRecord,
+	RoundTwoEntry,
+	StageEntry,
+	StopEntry,
+	StopRecord,
+	TestRelatedEntry,
+	TestRelatedRecord,
+	UnitFileRecord,
+	UnitFilesEntry,
+} from './lane-ledger-schema'
 export { lane_ledger }

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

@@ -1,9 +1,11 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
-import { backlog_ready } from '#scripts/backlog/backlog-ready'
+import { backlog_ready, type LaneUse } from '#scripts/backlog/backlog-ready'
+import { session_cite } from '#scripts/issue/session-cite'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { lane_capacity, type LimitChoice } from './lane-capacity'
 import { lane_limit_override } from './lane-limit-override'
+import { lane_state } from './lane-state'
 
 // `josh lane:limit [<limit>] [--reset]` — change a live `backlogrun`'s lane limit without stopping it.
 // A running parent keeps the environment it started with, so `JOSH_LANE_LIMIT`
@@ -37,13 +39,13 @@ interface LimitPorts {
 	read_override: () => Promise<number | undefined>
 	write_override: (limit: number | undefined) => Promise<boolean>
 	emit_raise: (text: string) => Promise<void>
-	live_lane_count: () => Promise<number>
+	lane_use: () => Promise<LaneUse>
 }
 
 interface LimitStatus {
 	limit: number
 	override: number | undefined
-	in_use: number
+	use: LaneUse
 }
 
 const SHOW: LimitRequest = { kind: 'show' }
@@ -55,7 +57,7 @@ const DEFAULT_PORTS: LimitPorts = {
 	read_override: lane_limit_override.read_override,
 	write_override: lane_limit_override.write_override,
 	emit_raise: lane_limit_override.emit_raise,
-	live_lane_count: backlog_ready.live_lane_count,
+	lane_use: backlog_ready.lane_use,
 }
 
 function refuse(message: string): number {
@@ -96,11 +98,21 @@ function limit_text(limit: number): string {
 		: `${String(seated)} (${String(limit)} capped at the seats)`
 }
 
+// The lanes with no state record, counted in use since their state is unknown.
+function unknown_text(unknown: ReadonlyArray<string>): string {
+	if (unknown.length === 0) return ''
+
+	const issues = unknown.map((issue) => session_cite.issue(issue)).join(' ')
+
+	return ` · ${issues}: ${lane_state.NO_STATE_HINT}`
+}
+
 function status_line(status: LimitStatus): string {
 	const source = status.override === undefined ? lane_capacity.LANE_LIMIT_KEY : OVERRIDE_SOURCE
-	const free = lane_capacity.free_lanes(status.limit, status.in_use)
+	const { occupied, seated } = status.use
+	const free = lane_capacity.free_lanes(status.limit, occupied, seated)
 
-	return `lane limit ${limit_text(status.limit)} (${source}) · in use ${String(status.in_use)} · free ${String(free)}`
+	return `lane limit ${limit_text(status.limit)} (${source}) · in use ${String(occupied)} · free ${String(free)}${unknown_text(status.use.unknown)}`
 }
 
 async function show(ports: LimitPorts): Promise<number> {
@@ -110,9 +122,7 @@ async function show(ports: LimitPorts): Promise<number> {
 
 	const override = await ports.read_override()
 
-	console.info(
-		status_line({ limit: choice.limit, override, in_use: await ports.live_lane_count() }),
-	)
+	console.info(status_line({ limit: choice.limit, override, use: await ports.lane_use() }))
 
 	return SUCCESS_EXIT_CODE
 }

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

@@ -1,14 +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.
 //
@@ -22,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 = [
@@ -101,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,
@@ -114,15 +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),
-		].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 }