@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lane/lane-ledger.ts

@@ -1,228 +1,15 @@
-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 { run_carry } from '#scripts/run/carry/run-carry'
-import { z } from 'zod'
+import { stamped_memo } from '#scripts/lib/stamped-memo'
+import { lane_ledger_schema, type LedgerEntry } from './lane-ledger-schema'
+import { lane_ledger_write } from './lane-ledger-write'
 
-// 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`.
-//
-// **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
-// that spans days of one-a-minute load samples. This file is only ever appended to, so concurrent lanes
-// never lose each other's lines to a read-modify-write race.
-//
-// **Keyed on the common git directory, the event stream's key**, so a lane child's gate, the parent's
-// merge and the sampler all land in one ledger per repository. It sits in the temp root beside every
-// other josh record; a reboot clears it, which is why `docs/maintainers/lane-limit-measurement.md`
-// closes a period with `josh lane:stats` before one.
+// The measurement ledger read back: every line `lane-ledger-write.ts` appended, for `josh lane:stats`,
+// `lane:breakdown`, `run:board` and the other measurements. The writers import that leaf, never this
+// module, so a change to the reading reaches only the suites that read (joshuafolkken/kit#5202).
 
-const LEDGER_PREFIX = 'josh-lane-ledger-'
-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'
-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',
-	OVERLAP: 'overlap',
-} as const
-
-const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
-const check_schema = z.object({
-	label: z.string(),
-	elapsed_ms: z.number(),
-	is_passed: z.boolean(),
-	is_reused: z.boolean().optional(),
-})
-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(),
-	// Each check's own duration and verdict, so `josh lane:stats` can name the check a slow gate waited
-	// on. A reused check started no process: its row says so, and its zero is no timing.
-	checks: z.array(check_schema).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(),
-})
-// A `josh ship` on `issue` whose actual change overlapped the open pull requests of `lanes` on `paths`
-// before its sync: it waited `waited_ms` for their ships to end, and `is_cleared` is false where the
-// wait ran out first (joshuafolkken/kit#3901).
-const overlap_schema = z.object({
-	kind: z.literal(KIND.OVERLAP),
-	at: z.string(),
-	issue: z.number(),
-	lanes: z.array(z.number()),
-	paths: z.array(z.string()),
-	waited_ms: z.number(),
-	is_cleared: z.boolean(),
-})
-const entry_schema = z.discriminatedUnion('kind', [
-	merge_schema,
-	gate_schema,
-	load_schema,
-	dispatch_schema,
-	stage_schema,
-	stop_schema,
-	overlap_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>
-type OverlapEntry = z.infer<typeof overlap_schema>
-// What a finished gate reports; the ledger stamps the kind and the time.
-type GateRecord = Omit<GateEntry, 'kind' | 'at'>
-type GateCheckRecord = z.infer<typeof check_schema>
-type StageRecord = Omit<StageEntry, 'kind' | 'at'>
-type StopRecord = Omit<StopEntry, 'kind' | 'at'>
-type OverlapRecord = Omit<OverlapEntry, 'kind' | 'at'>
-
-function target_of(repository: string): string {
-	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
-}
-
-// The ledger of the repository this checkout belongs to, or `undefined` outside one. `git rev-parse`
-// rejects outside a repository, and `josh gate` resolves this before it runs a check, so the rejection
-// is read as "no ledger" rather than allowed to fail the gate it would only have measured.
-//
-// **A test run has no ledger either.** The writers sit on paths dozens of suites exercise — a ship
-// stage, a dispatch, a `followup` — and one suite that forgot to mock this module would append its
-// fixture durations to the real measurement; a test that writes passes its own path instead.
-async function target(): Promise<string | undefined> {
-	if (process.env['VITEST'] !== undefined) return undefined
-
-	try {
-		const repository = await run_carry.repository_directory()
-
-		return repository === undefined ? undefined : target_of(repository)
-	} catch {
-		return 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 {
-	const descriptor = openSync(path, APPEND_FLAGS, LEDGER_FILE_MODE)
-
-	try {
-		if (stamp_file.is_own_regular_file(path)) {
-			writeSync(descriptor, `${JSON.stringify(entry)}${LINE_SEPARATOR}`)
-		}
-	} finally {
-		closeSync(descriptor)
-	}
-}
-
-// Best-effort: a measurement must never fail the gate or the merge it measures, so every error — no
-// repository, an unwritable temp root — is dropped.
-async function record(entry: LedgerEntry, path?: string): Promise<void> {
-	try {
-		const destination = path ?? (await target())
-
-		if (destination !== undefined) append(destination, entry)
-	} catch {
-		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
-	}
-}
-
-function now_iso(): string {
-	return new Date().toISOString()
-}
-
-// One finished `josh gate`, whether it passed or not — a failing gate cost the lane its time as well.
-async function record_gate(path: string, gate: GateRecord): Promise<void> {
-	await record({ kind: KIND.GATE, at: now_iso(), ...gate }, path)
-}
-
-async function record_merge(issue: number): Promise<void> {
-	await record({ kind: KIND.MERGE, at: now_iso(), issue })
-}
-
-async function record_dispatch(issue: number, path?: string): Promise<void> {
-	await record({ kind: KIND.DISPATCH, at: now_iso(), issue }, path)
-}
-
-async function record_stage(stage: StageRecord, path?: string): Promise<void> {
-	await record({ kind: KIND.STAGE, at: now_iso(), ...stage }, path)
-}
-
-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)
-}
+const { entry_schema } = lane_ledger_schema
+const { LINE_SEPARATOR } = lane_ledger_write
 
 function parse_line(line: string): LedgerEntry | undefined {
 	return entry_schema.safeParse(json_value.parse_or_undefined(line)).data
@@ -232,9 +19,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 []
@@ -245,32 +30,70 @@ 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))
+}
+
+// The names a reader looks entries up by and the ledger it reads, the writer's own.
+const {
+	CI_WAIT_STAGE,
+	CODERABBIT_RATE_LIMIT_STAGE,
+	CODERABBIT_RETRIGGER_STAGE,
+	CODERABBIT_WAIT_STAGE,
+	KIND,
+	PRE_DETACH_STAGE,
+	ROUND_ONE_REUSED,
+	target,
+	target_of,
+} = lane_ledger_write
+
 const lane_ledger = {
 	CI_WAIT_STAGE,
+	CODERABBIT_RATE_LIMIT_STAGE,
+	CODERABBIT_RETRIGGER_STAGE,
+	CODERABBIT_WAIT_STAGE,
 	KIND,
-	append,
+	PRE_DETACH_STAGE,
+	ROUND_ONE_REUSED,
 	read_entries,
-	record,
-	record_dispatch,
-	record_gate,
-	record_merge,
-	record_overlap,
-	record_stage,
-	record_stop,
 	target,
 	target_of,
 }
 
 export type {
+	CoreWaitEntry,
+	CoreWaitRecord,
 	DispatchEntry,
 	GateCheckRecord,
 	GateEntry,
+	HeldEntry,
+	LaneStateChangeEntry,
 	LedgerEntry,
 	LoadEntry,
 	MergeEntry,
+	OfferableEntry,
 	OverlapEntry,
 	OverlapRecord,
+	PushMissEntry,
+	RoundOneEntry,
+	RoundTwoEntry,
+	ShipLapEntry,
+	SplitFiledEntry,
+	SplitNoticeEntry,
 	StageEntry,
 	StopEntry,
-}
+	StopRecord,
+	TestPinnedEntry,
+	TestPinnedRecord,
+	TestRelatedEntry,
+	TestRelatedRecord,
+	UnitFileRecord,
+	UnitFilesEntry,
+	UnplannedNoticeEntry,
+} 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, 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`
@@ -96,12 +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 { 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(occupied)} · 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> {

package/scripts/lane/lane-load.ts

@@ -1,7 +1,7 @@
 import { loadavg } from 'node:os'
 import { machine_capacity } from '#scripts/gate/machine-capacity'
 import { lane_await } from './lane-await'
-import type { LoadEntry } from './lane-ledger'
+import type { LoadEntry } from './lane-ledger-schema'
 import { lane_process_load } from './lane-process-load'
 import { lane_registry, type LaneInfo } from './lane-registry'
 

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

@@ -1,17 +1,22 @@
 #!/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 { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { lane_capacity } from './lane-capacity'
-import { lane_check_stats } from './lane-check-stats'
-import { lane_ledger } from './lane-ledger'
-import { lane_process_stats } from './lane-process-stats'
+import { lane_net_read } from './lane-net-read'
 import { lane_sampler, type MeasureContext } from './lane-sampler'
-import { lane_stage_stats } from './lane-stage-stats'
-import { lane_stats } from './lane-stats'
-import { lane_stop_stats } from './lane-stop-stats'
-
-// `josh lane:sample` / `josh lane:stats` — the lane-limit measurement.
+import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_stats_tables, type PeriodRecords } from './lane-stats-tables'
+import { lane_transcript_stats } from './lane-transcript-stats'
+import { lane_value } from './lane-value'
+import { lane_value_cell, type CellAddress } from './lane-value-cell'
+
+// `josh lane:sample` / `josh lane:stats` — the lane-limit measurement; `josh lane:value` and
+// `josh lane:net` print one measurement each.
 //
 // `lane:sample` appends one machine-load sample to the ledger, or one every `--every <seconds>` until it
 // is stopped; `lane:stats` reduces a period of the ledger to the one table row #3347 records per lane
@@ -23,16 +28,30 @@ 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 VALUE_VERB = 'value'
+const NET_VERB = 'net'
+// `lane:value cell` reads one `lane:stats` table cell rather than a named metric (joshuafolkken/kit#5144).
+const CELL_METRIC = 'cell'
+// A value keeps two decimals: seconds, minutes and per-lane counts read at that grain.
+const VALUE_DIGITS = 2
 const USAGE = [
 	'Usage: josh lane:sample [--every <seconds>]',
 	'       josh lane:stats --period <days> [--limit <lane-limit>]',
+	`       josh lane:value <${lane_value.NAMES.join('|')}> --since <instant>`,
+	`       josh lane:value ${CELL_METRIC} --table <title> --row <label> --column <header> --since <instant>`,
+	'       josh lane:net <issue>',
 ].join('\n')
 
 const SAMPLE_OPTIONS = { every: { type: 'string' } } as const
 const STATS_OPTIONS = { period: { type: 'string' }, limit: { type: 'string' } } as const
+const VALUE_OPTIONS = {
+	since: { type: 'string' },
+	table: { type: 'string' },
+	row: { type: 'string' },
+	column: { type: 'string' },
+} as const
 
 function refuse(): number {
 	console.error(USAGE)
@@ -94,12 +113,25 @@ async function limit_label(given: string | undefined): Promise<string> {
 	return choice.kind === 'limit' ? String(choice.limit) : lane_stats.MISSING
 }
 
-async function read_ledger(
-	context: MeasureContext,
-): Promise<ReturnType<typeof lane_ledger.read_entries>> {
-	const path = context.ledger_path ?? (await lane_ledger.target())
+// 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 path === undefined ? [] : lane_ledger.read_entries(path)
+	return cost_transcript.lane_transcript_directories(main_cwd, cost_transcript.home_directory())
+}
+
+// The whole ledger, every run event and the window's lane calls — what the `lane:stats` tables read.
+async function period_records(
+	context: MeasureContext,
+	window: StatsWindow,
+): Promise<PeriodRecords> {
+	return {
+		entries: await lane_net_read.read_ledger(context),
+		events: await lane_net_read.read_events(context),
+		calls: lane_transcript_stats.read_calls(transcript_directories(context), window),
+	}
 }
 
 async function stats_command(
@@ -113,28 +145,159 @@ async function stats_command(
 
 	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
 	const label = { limit: await limit_label(values.limit), period_days }
-	const entries = await read_ledger(context)
-	const row = lane_stats.row(entries, window, label)
-
-	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'),
-	)
+	const records = await period_records(context, window)
+	const row = lane_stats.row(records.entries, window, label)
+	const tables = lane_stats_tables.tables_of(records, window)
+
+	console.info([`${lane_stats.header()}\n${row}`, ...tables].join('\n\n'))
 
 	return 0
 }
 
-async function run(argv: ReadonlyArray<string>, context: MeasureContext = {}): Promise<number> {
-	const [verb, ...rest] = argv
+interface ValueRequest {
+	metric: string
+	since_ms: number
+	address?: CellAddress
+}
+
+interface AddressFlags {
+	table?: string | undefined
+	row?: string | undefined
+	column?: string | undefined
+}
+
+function since_of(text = ''): number | undefined {
+	const since_ms = Date.parse(text)
+
+	return Number.isNaN(since_ms) ? undefined : since_ms
+}
+
+function is_known(name: string): boolean {
+	return name === CELL_METRIC || lane_value.is_metric(name)
+}
+
+function metric_of(positionals: ReadonlyArray<string>): string | undefined {
+	const [name] = positionals
+
+	return name !== undefined && positionals.length === 1 && is_known(name) ? name : undefined
+}
+
+function address_of({ table, row, column }: AddressFlags): CellAddress | undefined {
+	return table === undefined || row === undefined || column === undefined
+		? undefined
+		: { table, row, column }
+}
+
+function request_of(
+	metric: string | undefined,
+	since_ms: number | undefined,
+): ValueRequest | undefined {
+	return metric === undefined || since_ms === undefined ? undefined : { metric, since_ms }
+}
+
+// One known metric and a readable `--since` instant — `cell` with its whole address — or `undefined`
+// for a refusal.
+function value_request(rest: ReadonlyArray<string>): ValueRequest | undefined {
+	const parsed = cli_flags.arguments_of(rest, VALUE_OPTIONS)
+
+	if (parsed === undefined) return undefined
+
+	const request = request_of(metric_of(parsed.positionals), since_of(parsed.values.since))
+
+	if (request?.metric !== CELL_METRIC) return request
+
+	const address = address_of(parsed.values)
+
+	return address === undefined ? undefined : { ...request, address }
+}
+
+// The value alone on its line, so a measurement declaration reads it as the output's last line; a
+// period with no sample prints nothing there and fails, which the drive reads as unreadable.
+function print_value(request: ValueRequest, measured: number | undefined): number {
+	if (measured === undefined) {
+		const since = new Date(request.since_ms).toISOString()
+
+		const missing = request.address === undefined ? 'no sample' : 'no single numeric cell'
+
+		console.error(`josh lane:value ${request.metric}: ${missing} since ${since}`)
 
-	if (verb === SAMPLE_VERB) return await sample_command(rest, context)
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(measured.toFixed(VALUE_DIGITS))
+
+	return 0
+}
+
+// The addressed cell of the tables `lane:stats` would print for `window`.
+async function cell_value(
+	address: CellAddress,
+	window: StatsWindow,
+	context: MeasureContext,
+): Promise<number | undefined> {
+	const tables = lane_stats_tables.tables_of(await period_records(context, window), window)
+
+	return lane_value_cell.value(tables, address)
+}
+
+async function value_command(
+	rest: ReadonlyArray<string>,
+	context: MeasureContext,
+): Promise<number> {
+	const request = value_request(rest)
+
+	if (request === undefined) return refuse()
+
+	const window = { since_ms: request.since_ms, until_ms: context.now_ms ?? Date.now() }
+
+	if (request.address !== undefined) {
+		return print_value(request, await cell_value(request.address, window, context))
+	}
+
+	const records = {
+		entries: await lane_net_read.read_ledger(context),
+		calls: lane_transcript_stats.read_calls(transcript_directories(context), window),
+	}
+
+	return print_value(request, lane_value.value(request.metric, records, window))
+}
+
+// The lane's net minutes, whole, alone on the line a causing-lane declaration copies
+// (`lane-net-time.ts`); a lane the ledger holds no dispatch and merge of fails.
+async function net_command(rest: ReadonlyArray<string>, context: MeasureContext): Promise<number> {
+	const [issue = ''] = rest
+
+	if (rest.length !== 1 || !issue_number_shape.is_issue_number(issue)) return refuse()
+
+	const net = await lane_net_read.net_minutes_of(Number(issue), context)
+
+	if (net === undefined) {
+		console.error(
+			`josh lane:net ${issue}: the ledger holds no dispatch and merge of ${session_cite.issue(issue)}`,
+		)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(String(net))
+
+	return 0
+}
+
+type VerbCommand = (rest: ReadonlyArray<string>, context: MeasureContext) => Promise<number>
+
+const VERBS: Readonly<Record<string, VerbCommand>> = {
+	[SAMPLE_VERB]: sample_command,
+	[STATS_VERB]: stats_command,
+	[VALUE_VERB]: value_command,
+	[NET_VERB]: net_command,
+}
+
+async function run(argv: ReadonlyArray<string>, context: MeasureContext = {}): Promise<number> {
+	const [verb = '', ...rest] = argv
+	const command = Object.hasOwn(VERBS, verb) ? VERBS[verb] : undefined
 
-	return verb === STATS_VERB ? await stats_command(rest, context) : refuse()
+	return command === undefined ? refuse() : await command(rest, context)
 }
 
 async function main(argv: ReadonlyArray<string>): Promise<void> {

package/scripts/lane/lane-net-read.ts

@@ -0,0 +1,44 @@
+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_ledger } from './lane-ledger'
+import { lane_net_time } from './lane-net-time'
+import type { MeasureContext } from './lane-sampler'
+
+// The ledger and the event stream the lane measurements read, and the one lane's net minutes read from
+// them — `josh lane:net` and the causing-lane line `josh issue:file --found-during` prints
+// (joshuafolkken/kit#5225) share it.
+
+type ReadContext = Pick<MeasureContext, 'ledger_path' | 'events_path'>
+
+async function read_ledger(
+	context: ReadContext,
+): Promise<ReturnType<typeof lane_ledger.read_entries>> {
+	const path = context.ledger_path ?? (await lane_ledger.target())
+
+	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: ReadContext): 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()
+}
+
+// The lane's net minutes, whole; `undefined` when the ledger holds no dispatch and merge of it.
+async function net_minutes_of(
+	issue: number,
+	context: ReadContext = {},
+): Promise<number | undefined> {
+	const events = await read_events(context)
+
+	return lane_net_time.net_minutes(await read_ledger(context), events, issue)
+}
+
+const lane_net_read = {
+	net_minutes_of,
+	read_events,
+	read_ledger,
+}
+
+export { lane_net_read }