@joshuafolkken/kit 1.2116.0 → 1.3000.0

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

@@ -0,0 +1,77 @@
+import { lane_capacity, type LimitChoice } from './lane-capacity'
+import { lane_ledger_kind } from './lane-ledger-kind'
+import type { LedgerEntry, LimitEntry } from './lane-ledger-schema'
+import { lane_ledger_write } from './lane-ledger-write'
+import { lane_limit_override } from './lane-limit-override'
+import { lane_stats, type StatsWindow } from './lane-stats'
+
+// The lane limit's history in the lane ledger: one `limit` line each time a run starts and each time
+// `lane:limit` changes it, so `lane:stats` labels a period the limit moved in with every limit it
+// held — `3→4` — rather than the one it reads now (joshuafolkken/kit#6139).
+
+const { KIND } = lane_ledger_kind
+const CHANGE_SEPARATOR = '→'
+
+// Written best-effort; an unreadable limit writes nothing.
+async function record(choice: LimitChoice, path?: string): Promise<void> {
+	if (choice.kind !== 'limit') return
+
+	const at = new Date().toISOString()
+
+	await lane_ledger_write.record({ kind: KIND.LIMIT, at, limit: choice.limit }, path)
+}
+
+// The limit this process reads — the run's override, else the limit it started with, else
+// `JOSH_LANE_LIMIT`.
+async function record_current(path?: string): Promise<void> {
+	await record(await lane_capacity.lane_limit(), path)
+}
+
+// The limit a run starts under: kept on its carry record, so a later `lane:limit --reset` restores it
+// whatever a shell's `.env` reads by then (joshuafolkken/kit#6166), and written to the ledger.
+async function record_launch(path?: string): Promise<void> {
+	const choice = lane_capacity.environment_limit()
+
+	if (choice.kind === 'limit') await lane_limit_override.write_launch(choice.limit)
+
+	await record(choice, path)
+}
+
+function is_limit(entry: LedgerEntry): entry is LimitEntry {
+	return entry.kind === KIND.LIMIT
+}
+
+// The limit in force when the window opens — the last one written before it — then each one written
+// inside it, a repeat of the one before dropped.
+function limits_in(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): Array<number> {
+	const limits = entries.filter((entry) => is_limit(entry))
+	const opening = limits.findLast((entry) => Date.parse(entry.at) < window.since_ms)
+	const inside = lane_stats.in_window(limits, window)
+	const held = [...(opening === undefined ? [] : [opening]), ...inside].map((entry) => entry.limit)
+
+	return held.filter((limit, index) => index === 0 || limit !== held[index - 1])
+}
+
+async function current_label(): Promise<string> {
+	const choice = await lane_capacity.lane_limit()
+
+	return choice.kind === 'limit' ? String(choice.limit) : lane_stats.MISSING
+}
+
+// `lane:stats`'s `JOSH_LANE_LIMIT` cell: `--limit` outright, else the window's limits joined by `→`,
+// else — no `limit` line reaches the window — the limit this process reads.
+async function label(
+	given: string | undefined,
+	entries: ReadonlyArray<LedgerEntry>,
+	window: StatsWindow,
+): Promise<string> {
+	if (given !== undefined) return given
+
+	const limits = limits_in(entries, window)
+
+	return limits.length === 0 ? await current_label() : limits.map(String).join(CHANGE_SEPARATOR)
+}
+
+const lane_limit_history = { label, record_current, record_launch }
+
+export { lane_limit_history }

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

@@ -25,26 +25,60 @@ function live_carry(target: string): RunCarry | undefined {
 	return read.kind === 'carried' ? read.carry : undefined
 }
 
-// The override, or `undefined` where no live run set one — the environment's limit then stands.
-async function read_override(): Promise<number | undefined> {
+async function current_carry(): Promise<RunCarry | undefined> {
 	const target = await carry_target()
 
-	return target === undefined ? undefined : live_carry(target)?.lane_limit
+	return target === undefined ? undefined : live_carry(target)
 }
 
-// `undefined` clears the override. Answers whether a live run took it: with no run there is no record
-// to write to, and the next run reads `JOSH_LANE_LIMIT` as it starts.
-async function write_override(limit: number | undefined): Promise<boolean> {
+// The override, or `undefined` where no live run set one — the run's start limit, else the
+// environment's, then stands.
+async function read_override(): Promise<number | undefined> {
+	const carry = await current_carry()
+
+	return carry?.lane_limit
+}
+
+// A record a crashed run left must not pin its start limit over an edited `.env`: the start limit
+// counts while its owner lives, or while a cut hands the record to a successor.
+function is_run_live(carry: RunCarry): boolean {
+	return carry.is_handed_off === true || run_carry.is_owner_live(carry)
+}
+
+// The limit a live run holds: its override, else the limit it started with — so a `--reset` returns
+// to the run's own `JOSH_LANE_LIMIT`, not the one a shell's `.env` reads now (joshuafolkken/kit#6166).
+async function read_carried(): Promise<number | undefined> {
+	const carry = await current_carry()
+
+	if (carry?.lane_limit !== undefined) return carry.lane_limit
+
+	return carry !== undefined && is_run_live(carry) ? carry.launch_limit : undefined
+}
+
+// Answers whether a live run took the fields: with no run there is no record to write to, and the
+// next run reads `JOSH_LANE_LIMIT` as it starts.
+async function update_carry(
+	fields: Pick<RunCarry, 'lane_limit'> | Pick<RunCarry, 'launch_limit'>,
+): Promise<boolean> {
 	const target = await carry_target()
 	const carry = target === undefined ? undefined : live_carry(target)
 
 	if (target === undefined || carry === undefined) return false
 
-	stamp_file.write_stamp(target, { ...carry, lane_limit: limit })
+	stamp_file.write_stamp(target, { ...carry, ...fields })
 
 	return true
 }
 
+// `undefined` clears the override.
+async function write_override(limit: number | undefined): Promise<boolean> {
+	return await update_carry({ lane_limit: limit })
+}
+
+async function write_launch(limit: number): Promise<boolean> {
+	return await update_carry({ launch_limit: limit })
+}
+
 async function emit_raise(text: string): Promise<void> {
 	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.LANE_LIMIT, text)
 }
@@ -69,6 +103,13 @@ async function watch_raise(): Promise<() => boolean> {
 	}
 }
 
-const lane_limit_override = { emit_raise, read_override, watch_raise, write_override }
+const lane_limit_override = {
+	emit_raise,
+	read_carried,
+	read_override,
+	watch_raise,
+	write_launch,
+	write_override,
+}
 
 export { lane_limit_override }

package/scripts/lane/lane-listening-ports.ts

@@ -0,0 +1,77 @@
+import { readFile } from 'node:fs/promises'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
+
+type ReadText = (file: string) => Promise<string>
+const PORT_FIELD = /^n.*:(?<port>\d+)$/gmu
+const NO_MATCH = 1
+const HEX_RADIX = 16
+const LISTEN_STATE = '0A'
+const TCP_TABLE = '/proc/net/tcp'
+const TCP6_TABLE = '/proc/net/tcp6'
+const TABLE_FIELDS = 4
+const ADDRESS_FIELDS = 2
+
+async function read_text(file: string): Promise<string> {
+	return await readFile(file, 'utf8')
+}
+
+function linux_port(line: string): Array<number> {
+	const [, local, , state] = line.trim().split(/\s+/u, TABLE_FIELDS)
+	if (state !== LISTEN_STATE || local === undefined) return []
+	const port = Number.parseInt(local.split(':', ADDRESS_FIELDS)[1] ?? '', HEX_RADIX)
+
+	return Number.isSafeInteger(port) ? [port] : []
+}
+
+async function ipv6_text(read: ReadText): Promise<string> {
+	try {
+		return await read(TCP6_TABLE)
+	} catch (error) {
+		if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return ''
+		throw error
+	}
+}
+
+async function linux_ports(read: ReadText): Promise<ReadonlySet<number>> {
+	const tables = await Promise.all([read(TCP_TABLE), ipv6_text(read)])
+
+	return new Set(tables.flatMap((table) => table.split('\n').flatMap((line) => linux_port(line))))
+}
+
+async function darwin_ports(): Promise<ReadonlySet<number> | undefined> {
+	const result = await execa('lsof', ['-nP', '-iTCP', '-sTCP:LISTEN', '-Fn'], {
+		reject: false,
+		timeout: PROBE_TIMEOUT_MS,
+	})
+	if (result.exitCode !== 0 && result.exitCode !== NO_MATCH) return undefined
+	if (result.stderr.trim() !== '') return undefined
+
+	return new Set(
+		[...result.stdout.matchAll(PORT_FIELD)].map((match) => Number(match.groups?.['port'])),
+	)
+}
+
+async function read_for(
+	platform: NodeJS.Platform,
+	read: ReadText,
+): Promise<ReadonlySet<number> | undefined> {
+	if (platform === 'linux') return await linux_ports(read)
+
+	return platform === 'darwin' ? await darwin_ports() : undefined
+}
+
+async function read_ports(
+	platform: NodeJS.Platform = process.platform,
+	read: ReadText = read_text,
+): Promise<ReadonlySet<number> | undefined> {
+	try {
+		return await read_for(platform, read)
+	} catch {
+		return undefined
+	}
+}
+
+const lane_listening_ports = { read_ports }
+
+export { lane_listening_ports }

package/scripts/lane/lane-load.ts

@@ -1,5 +1,7 @@
 import { loadavg } from 'node:os'
 import { machine_capacity } from '#scripts/gate/machine-capacity'
+import { MS_PER_SECOND, PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
 import { lane_await } from './lane-await'
 import type { LoadEntry } from './lane-ledger-schema'
 import { lane_process_load } from './lane-process-load'
@@ -39,11 +41,65 @@ function rounded(megabytes: number | undefined): number | undefined {
 	return megabytes === undefined ? undefined : Math.round(megabytes)
 }
 
+// The host's sleep since boot (joshuafolkken/kit#7026): at each wake macOS stamps both its continuous
+// clock, which runs through a sleep, and its absolute one, which stops, in timebase ticks. Their
+// difference grows only by sleeping, so two samples' readings give the sleep between them even when
+// different processes took them. Another platform, or a probe that did not answer, records none.
+// The boot and last-wake instants ride along: a reboot resets the counter, and the last wake is where a
+// sleep ended, which a sampler started long after it cannot tell from its own first sample.
+const CLOCK_SYSCTL_NAMES = ['hw.tbfrequency', 'machdep.wake_abstime', 'machdep.wake_conttime']
+const SLEEP_SYSCTL_NAMES = [...CLOCK_SYSCTL_NAMES, 'kern.boottime', 'kern.waketime']
+const SYSCTL_LINE = /^(?<name>[\w.]+): (?<value>\d+)$/gmu
+const SYSCTL_TIME = /^kern\.(?<name>boottime|waketime): \{ sec = (?<seconds>\d+)/gmu
+
+interface HostSleep {
+	slept_ms?: number | undefined
+	booted_ms?: number | undefined
+	woke_ms?: number | undefined
+}
+
+function parse_times(stdout: string): Pick<HostSleep, 'booted_ms' | 'woke_ms'> {
+	const times = new Map(
+		Array.from(stdout.matchAll(SYSCTL_TIME), (match) => [
+			match.groups?.['name'],
+			Number(match.groups?.['seconds']) * MS_PER_SECOND,
+		]),
+	)
+
+	return { booted_ms: times.get('boottime'), woke_ms: times.get('waketime') }
+}
+
+function parse_slept_ms(stdout: string): number | undefined {
+	const values = new Map(
+		Array.from(stdout.matchAll(SYSCTL_LINE), (match) => [
+			match.groups?.['name'],
+			Number(match.groups?.['value']),
+		]),
+	)
+	const [frequency = 0, awake = 0, total = 0] = CLOCK_SYSCTL_NAMES.map((name) => values.get(name))
+
+	if ([frequency, awake, total].includes(0)) return undefined
+
+	return Math.round(((total - awake) / frequency) * MS_PER_SECOND)
+}
+
+async function read_host_sleep(): Promise<HostSleep> {
+	if (process.platform !== 'darwin') return {}
+
+	const { stdout } = await execa('sysctl', SLEEP_SYSCTL_NAMES, {
+		reject: false,
+		timeout: PROBE_TIMEOUT_MS,
+	})
+
+	return { slept_ms: parse_slept_ms(stdout), ...parse_times(stdout) }
+}
+
 async function sample(at: string): Promise<LoadEntry> {
-	const [memory, lanes, processes] = await Promise.all([
+	const [memory, lanes, reading, host_sleep] = await Promise.all([
 		machine_capacity.read_memory(),
 		read_lanes(),
 		lane_process_load.read(),
+		read_host_sleep(),
 	])
 	const [load = 0] = loadavg()
 
@@ -54,12 +110,16 @@ async function sample(at: string): Promise<LoadEntry> {
 		available_mb: rounded(memory.available_mb),
 		swapped_mb: rounded(memory.swapped_mb),
 		lanes,
-		processes,
+		processes: reading?.processes,
+		resident_mb: reading?.resident_mb,
+		...host_sleep,
 	}
 }
 
 const lane_load = {
 	count_working,
+	parse_slept_ms,
+	parse_times,
 	sample,
 }
 

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

@@ -6,14 +6,22 @@ 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_ledger_archive } from './lane-ledger-archive'
+import { lane_limit_history } from './lane-limit-history'
 import { lane_net_read } from './lane-net-read'
+import { lane_over_causes } from './lane-over-causes'
+import { lane_pairs } from './lane-pairs'
 import { lane_sampler, type MeasureContext } from './lane-sampler'
+import { lane_sinks } from './lane-sinks'
+import { lane_sinks_issues } from './lane-sinks-issues'
 import { lane_stats, type StatsWindow } from './lane-stats'
+import { lane_stats_request, type StatsRequest, type StatsStart } from './lane-stats-request'
 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'
+import { lane_value_cell, type CellAddress, type CellFilter } from './lane-value-cell'
+import { lane_value_missing } from './lane-value-missing'
+import { lane_why_period } from './lane-why-period'
 
 // `josh lane:sample` / `josh lane:stats` — the lane-limit measurement; `josh lane:value` and
 // `josh lane:net` print one measurement each.
@@ -39,19 +47,28 @@ const VALUE_DIGITS = 2
 const USAGE = [
 	'Usage: josh lane:sample [--every <seconds>]',
 	'       josh lane:stats --period <days> [--limit <lane-limit>]',
+	'       josh lane:stats --period <days> --sinks [<minutes>]',
+	'       josh lane:stats --period <days> --over <minutes>',
+	'       josh lane:stats --period <days> --why <minutes>',
+	'       josh lane:stats --period <days> --pairs',
+	'       josh lane:stats --since <instant> … — any form above, the window opened at the instant',
 	`       josh lane:value <${lane_value.NAMES.join('|')}> --since <instant>`,
-	`       josh lane:value ${CELL_METRIC} --table <title> --row <label> --column <header> --since <instant>`,
+	`       josh lane:value ${CELL_METRIC} --table <title> [--row <label>] [--where <header>=<text>] --column <header> [--item <label>] [--zero] --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' },
+	where: { type: 'string' },
+	item: { type: 'string' },
+	zero: { type: 'boolean' },
 } as const
+// `--where <header>=<text>`: the header ends at the first `=`, so the text may hold one.
+const WHERE_SEPARATOR = '='
 
 function refuse(): number {
 	console.error(USAGE)
@@ -59,13 +76,6 @@ function refuse(): number {
 	return FAILURE_EXIT_CODE
 }
 
-// A positive finite number, or `undefined` for anything else — a typo must not become a zero period.
-function positive(text: string | undefined): number | undefined {
-	const value = Number(text)
-
-	return text !== undefined && Number.isFinite(value) && value > 0 ? value : undefined
-}
-
 // The `--every` interval: `{ seconds: undefined }` for a single sample, `undefined` for a refusal.
 function sample_interval(rest: ReadonlyArray<string>): { seconds: number | undefined } | undefined {
 	const values = cli_flags.values_of(rest, SAMPLE_OPTIONS)
@@ -74,7 +84,7 @@ function sample_interval(rest: ReadonlyArray<string>): { seconds: number | undef
 
 	if (values.every === undefined) return { seconds: undefined }
 
-	const seconds = positive(values.every)
+	const seconds = lane_stats_request.positive(values.every)
 
 	return seconds === undefined ? undefined : { seconds }
 }
@@ -103,16 +113,6 @@ async function sample_command(
 	return 0
 }
 
-// The label defaults to the limit this process reads, which is the period's limit only when nobody
-// changed it since — `--limit` names it outright.
-async function limit_label(given: string | undefined): Promise<string> {
-	if (given !== undefined) return given
-
-	const choice = await lane_capacity.lane_limit()
-
-	return choice.kind === 'limit' ? String(choice.limit) : lane_stats.MISSING
-}
-
 // 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
@@ -122,34 +122,85 @@ function transcript_directories(context: MeasureContext): ReadonlyArray<string>
 	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.
+// The whole ledger with its archive, 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),
+		entries: await lane_ledger_archive.read_history(context),
 		events: await lane_net_read.read_events(context),
 		calls: lane_transcript_stats.read_calls(transcript_directories(context), window),
 	}
 }
 
+type LedgerTable = typeof lane_sinks.table
+
+// The `--over` or `--sinks` table with its threshold, `undefined` for the period's row and tables.
+function table_choice(request: StatsRequest): { table: LedgerTable; minutes: number } | undefined {
+	if (request.why !== undefined) return { table: lane_why_period.table, minutes: request.why }
+	if (request.over !== undefined) return { table: lane_over_causes.view, minutes: request.over }
+
+	return request.sinks === undefined
+		? undefined
+		: { table: lane_sinks.table, minutes: request.sinks }
+}
+
+// The ledger and the event stream alone — no lane's transcript (`lane-sinks.ts`, `lane-over.ts`).
+async function threshold_text(
+	choice: { table: LedgerTable; minutes: number },
+	context: MeasureContext,
+	window: StatsWindow,
+): Promise<string> {
+	const sources = {
+		entries: await lane_ledger_archive.read_history(context),
+		events: await lane_net_read.read_events(context),
+	}
+	const issues = await lane_sinks_issues.read()
+
+	return session_cite.text(choice.table(sources, window, choice.minutes, issues))
+}
+
+async function stats_text(
+	request: StatsRequest,
+	context: MeasureContext,
+	window: StatsWindow,
+): Promise<string> {
+	const choice = table_choice(request)
+
+	if (choice !== undefined) return await threshold_text(choice, context, window)
+
+	if (request.is_pairs) {
+		return lane_pairs.table(await lane_ledger_archive.read_history(context), window)
+	}
+
+	const records = await period_records(context, window)
+	const limit = await lane_limit_history.label(request.limit, records.entries, window)
+	const row = lane_stats.row(records.entries, window, { limit })
+	const tables = lane_stats_tables.tables_of(records, window)
+
+	return [`${lane_stats.header()}\n${row}`, ...tables].join('\n\n')
+}
+
+// `--since` opens the window at its instant; `--period` opens it that many days before now.
+function window_of(start: StatsStart, now_ms: number): StatsWindow {
+	if ('since_ms' in start) return { since_ms: start.since_ms, until_ms: now_ms }
+
+	return lane_stats.window_of(start.period_days, now_ms)
+}
+
 async function stats_command(
 	rest: ReadonlyArray<string>,
 	context: MeasureContext,
 ): Promise<number> {
-	const values = cli_flags.values_of(rest, STATS_OPTIONS)
-	const period_days = positive(values?.period)
+	const request = lane_stats_request.stats_request(rest)
 
-	if (values === undefined || period_days === undefined) return refuse()
+	if (request === undefined) return refuse()
 
-	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
-	const label = { limit: await limit_label(values.limit), period_days }
-	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)
+	const window = window_of(request.start, context.now_ms ?? Date.now())
 
-	console.info([`${lane_stats.header()}\n${row}`, ...tables].join('\n\n'))
+	console.info(await stats_text(request, context, window))
 
 	return 0
 }
@@ -164,12 +215,9 @@ 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
+	where?: string | undefined
+	item?: string | undefined
+	zero?: boolean | undefined
 }
 
 function is_known(name: string): boolean {
@@ -182,10 +230,24 @@ function metric_of(positionals: ReadonlyArray<string>): string | undefined {
 	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 }
+// `{ filter: undefined }` with no `--where`, `undefined` for one without a header or an `=`.
+function where_of(text: string | undefined): { filter: CellFilter | undefined } | undefined {
+	if (text === undefined) return { filter: undefined }
+
+	const at = text.indexOf(WHERE_SEPARATOR)
+
+	if (at < 1) return undefined
+
+	return { filter: { column: text.slice(0, at), text: text.slice(at + WHERE_SEPARATOR.length) } }
+}
+
+function address_of(flags: AddressFlags): CellAddress | undefined {
+	const { table, column } = flags
+	const where = where_of(flags.where)
+
+	if (table === undefined || column === undefined || where === undefined) return undefined
+
+	return { table, column, row: flags.row, where: where.filter, item: flags.item, zero: flags.zero }
 }
 
 function request_of(
@@ -202,7 +264,10 @@ function value_request(rest: ReadonlyArray<string>): ValueRequest | undefined {
 
 	if (parsed === undefined) return undefined
 
-	const request = request_of(metric_of(parsed.positionals), since_of(parsed.values.since))
+	const request = request_of(
+		metric_of(parsed.positionals),
+		lane_stats_request.since_of(parsed.values.since),
+	)
 
 	if (request?.metric !== CELL_METRIC) return request
 
@@ -211,33 +276,45 @@ function value_request(rest: ReadonlyArray<string>): ValueRequest | undefined {
 	return address === undefined ? undefined : { ...request, address }
 }
 
+// A value read, or the words `lane:value` fails with when there is none.
+interface Measured {
+	value: number | undefined
+	missing: string
+}
+
 // 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()
+// period with no sample prints nothing there and fails, which the drive reads as a wait
+// (`lane-value-missing.ts`).
+function print_value(request: ValueRequest, measured: Measured): number {
+	const { value, missing } = measured
 
-		const missing = request.address === undefined ? 'no sample' : 'no single numeric cell'
+	if (value === undefined) {
+		const since = new Date(request.since_ms).toISOString()
 
 		console.error(`josh lane:value ${request.metric}: ${missing} since ${since}`)
 
 		return FAILURE_EXIT_CODE
 	}
 
-	console.info(measured.toFixed(VALUE_DIGITS))
+	console.info(value.toFixed(VALUE_DIGITS))
 
 	return 0
 }
 
-// The addressed cell of the tables `lane:stats` would print for `window`.
+// The addressed cell of the tables `lane:stats` would print for `window`, and why there is none.
 async function cell_value(
 	address: CellAddress,
 	window: StatsWindow,
 	context: MeasureContext,
-): Promise<number | undefined> {
+): Promise<Measured> {
 	const tables = lane_stats_tables.tables_of(await period_records(context, window), window)
+	const { MISSING } = lane_value_missing
+	const is_several = lane_value_cell.is_several(tables, address)
 
-	return lane_value_cell.value(tables, address)
+	return {
+		value: lane_value_cell.value(tables, address),
+		missing: is_several ? MISSING.SEVERAL : MISSING.CELL,
+	}
 }
 
 async function value_command(
@@ -255,11 +332,13 @@ async function value_command(
 	}
 
 	const records = {
-		entries: await lane_net_read.read_ledger(context),
+		entries: await lane_ledger_archive.read_history(context),
 		calls: lane_transcript_stats.read_calls(transcript_directories(context), window),
 	}
 
-	return print_value(request, lane_value.value(request.metric, records, window))
+	const value = lane_value.value(request.metric, records, window)
+
+	return print_value(request, { value, missing: lane_value_missing.MISSING.SAMPLE })
 }
 
 // The lane's net minutes, whole, alone on the line a causing-lane declaration copies