@joshuafolkken/kit 1.2116.0 → 1.3041.0

package/scripts/lane/lane-ledger-write.ts

@@ -2,39 +2,44 @@ import { closeSync, constants, openSync, writeSync } from 'node:fs'
 import { durable_state } from '#scripts/josh/durable-state'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { run_carry } from '#scripts/run/carry/run-carry'
-import {
-	lane_ledger_schema,
-	type CoreWaitRecord,
-	type GateRecord,
-	type HeldRecord,
-	type LaneStateChangeRecord,
-	type LedgerEntry,
-	type OverlapRecord,
-	type PushMissRecord,
-	type RoundOneRecord,
-	type RoundTwoRecord,
-	type ShipLapRecord,
-	type SplitFiledRecord,
-	type SplitNoticeRecord,
-	type StageRecord,
-	type StopRecord,
-	type TestPinnedRecord,
-	type TestRelatedRecord,
-	type UnitFileRecord,
-	type UnplannedNoticeRecord,
+import { lane_ledger_kind } from './lane-ledger-kind'
+import type {
+	CoreWaitRecord,
+	GateRecord,
+	HeldRecord,
+	LaneStateChangeRecord,
+	LedgerEntry,
+	OverlapRecord,
+	PushMissRecord,
+	RoundOneRecord,
+	RoundTwoRecord,
+	ShipLapRecord,
+	SizeRecord,
+	SplitFiledRecord,
+	SplitNoticeRecord,
+	StageRecord,
+	StopRecord,
+	TestPinnedRecord,
+	TestRelatedRecord,
+	UnitFileRecord,
+	UnplannedNoticeRecord,
 } from './lane-ledger-schema'
+import type { OfferRecord } from './lane-ledger-schema-offer'
+import type { ChainRecord } from './lane-ledger-schema-ship'
 
 // 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, per stopped `josh ship`, per round-2 decision, per core-budget wait and per
-// `josh test:related` run, read back by `josh lane:stats` through `lane-ledger.ts`. Each line's shape
-// is `lane-ledger-schema.ts`.
+// `josh ship` stage, per stopped `josh ship`, per `josh run:chain`, per round-2 decision, per core-budget wait, per
+// `josh test:related` run and per lane-limit start or change (`limit`), read back by
+// `josh lane:stats` through `lane-ledger.ts`. Each line's shape is `lane-ledger-schema.ts`.
 //
 // **The writers' leaf, apart from the reader** (joshuafolkken/kit#5202). The gate, `followup`, `josh
 // ship`, the dispatch and the backlog driver write here, and dozens of suites import them; the reading
 // and the measurement modules built on it import `lane-ledger.ts`, so a change there no longer reaches
 // every suite a writer sits under.
 //
+// This writer still reaches the suites of its importing hubs — dispatch, gate and followup — until those hubs are cut (joshuafolkken/kit#5177).
+//
 // **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
@@ -67,7 +72,7 @@ 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 } = lane_ledger_schema
+const { KIND } = lane_ledger_kind
 
 function target_of(repository: string): string {
 	return durable_state.path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
@@ -99,9 +104,11 @@ function append(path: string, entry: object): 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}`)
+		if (!stamp_file.is_own_regular_file(path)) {
+			throw new Error('Ledger is not an owned regular file')
 		}
+
+		writeSync(descriptor, `${JSON.stringify(entry)}${LINE_SEPARATOR}`)
 	} finally {
 		closeSync(descriptor)
 	}
@@ -144,6 +151,10 @@ async function record_stop(stop: StopRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.STOP, at: now_iso(), ...stop }, path)
 }
 
+async function record_chain(chain: ChainRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.CHAIN, at: now_iso(), ...chain }, path)
+}
+
 async function record_overlap(overlap: OverlapRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.OVERLAP, at: now_iso(), ...overlap }, path)
 }
@@ -168,6 +179,10 @@ async function record_offerable(is_offerable: boolean, path?: string): Promise<v
 	await record({ kind: KIND.OFFERABLE, at: now_iso(), is_offerable }, path)
 }
 
+async function record_offer(offer: OfferRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.OFFER, at: now_iso(), ...offer }, path)
+}
+
 async function record_round_one(round_one: RoundOneRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.ROUND_ONE, at: now_iso(), ...round_one }, path)
 }
@@ -200,17 +215,31 @@ async function record_split_notice(notice: SplitNoticeRecord, path?: string): Pr
 }
 
 async function record_split_filed(filed: SplitFiledRecord, path?: string): Promise<void> {
-	await record({ kind: KIND.SPLIT_FILED, at: now_iso(), ...filed }, path)
+	const destination = path ?? (await target())
+
+	if (destination === undefined) throw new Error('Could not resolve the split-child ledger')
+	append(destination, { kind: KIND.SPLIT_FILED, at: now_iso(), ...filed })
 }
 
 async function record_push_miss(miss: PushMissRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.PUSH_MISS, at: now_iso(), ...miss }, path)
 }
 
+async function record_early_push(
+	push: Omit<Extract<LedgerEntry, { kind: 'early-push' }>, 'kind' | 'at'>,
+	path?: string,
+): Promise<void> {
+	await record({ kind: KIND.EARLY_PUSH, at: now_iso(), ...push }, path)
+}
+
 async function record_ship_lap(lap: ShipLapRecord, path?: string): Promise<void> {
 	await record({ kind: KIND.SHIP_LAP, at: now_iso(), ...lap }, path)
 }
 
+async function record_size(size: SizeRecord, path?: string): Promise<void> {
+	await record({ kind: KIND.SIZE, at: now_iso(), ...size }, path)
+}
+
 async function record_unplanned_notice(
 	notice: UnplannedNoticeRecord,
 	path?: string,
@@ -229,6 +258,7 @@ const lane_ledger_write = {
 	ROUND_ONE_REUSED,
 	append,
 	record,
+	record_chain,
 	record_core_wait,
 	record_dispatch,
 	record_gate,
@@ -237,11 +267,14 @@ const lane_ledger_write = {
 	record_released,
 	record_merge,
 	record_overlap,
+	record_offer,
 	record_offerable,
 	record_push_miss,
+	record_early_push,
 	record_round_one,
 	record_round_two,
 	record_ship_lap,
+	record_size,
 	record_split_filed,
 	record_split_notice,
 	record_stage,

package/scripts/lane/lane-ledger.ts

@@ -1,42 +1,17 @@
-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 { lane_ledger_schema, type LedgerEntry } from './lane-ledger-schema'
+import type { LedgerEntry } from './lane-ledger-schema'
+import { lane_ledger_tail } from './lane-ledger-tail'
 import { lane_ledger_write } from './lane-ledger-write'
 
 // 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 { 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
-}
-
-function is_present(entry: LedgerEntry | undefined): entry is LedgerEntry {
-	return entry !== undefined
-}
-
-function parse_entries(path: string): ReadonlyArray<LedgerEntry> {
-	const raw = stamp_file.read_stamp_text(path)
-
-	if (raw === undefined) return []
-
-	return raw
-		.split(LINE_SEPARATOR)
-		.map((line) => parse_line(line.trim()))
-		.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.
+// whole ledger unreadable, and an absent or unowned file is an empty ledger. An unchanged file is not
+// parsed again (joshuafolkken/kit#4263), and an appended one only past what was parsed
+// (joshuafolkken/kit#7012).
 function read_entries(path: string): ReadonlyArray<LedgerEntry> {
-	return parsed_ledgers.of(path, stamped_memo.file_stamp(path), () => parse_entries(path))
+	return lane_ledger_tail.read(path)
 }
 
 // The names a reader looks entries up by and the ledger it reads, the writer's own.

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

@@ -4,6 +4,7 @@ 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_history } from './lane-limit-history'
 import { lane_limit_override } from './lane-limit-override'
 import { lane_state } from './lane-state'
 
@@ -15,6 +16,9 @@ import { lane_state } from './lane-state'
 // **Only a raise wakes anyone.** Lowering stops no child — a finished lane is simply not refilled — so
 // there is nothing for the parent to do; a raise frees lanes, and its `lane-limit` event is what the
 // `--wait` watcher's arrival probe wakes the parent for.
+//
+// **Every change is measured.** A raise, a lower or a reset writes the limit it leaves to the lane
+// ledger, so `lane:stats` labels a period the limit moved in with its history (joshuafolkken/kit#6139).
 
 const ARGV_OFFSET = 2
 const SUCCESS_EXIT_CODE = 0
@@ -28,7 +32,7 @@ const NO_RUN_MESSAGE = `No run is in progress: lane:limit changes a live run's l
 
 const OPTIONS = { reset: { type: 'boolean' } } as const
 
-// `set` with no limit is `--reset`: the override is cleared and the environment's limit stands.
+// `set` with no limit is `--reset`: the override is cleared and the run's start limit stands.
 type LimitRequest =
 	| { kind: 'show' }
 	| { kind: 'set'; limit: number | undefined }
@@ -39,6 +43,7 @@ interface LimitPorts {
 	read_override: () => Promise<number | undefined>
 	write_override: (limit: number | undefined) => Promise<boolean>
 	emit_raise: (text: string) => Promise<void>
+	record_limit: () => Promise<void>
 	lane_use: () => Promise<LaneUse>
 }
 
@@ -57,6 +62,9 @@ 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,
+	record_limit: async () => {
+		await lane_limit_history.record_current()
+	},
 	lane_use: backlog_ready.lane_use,
 }
 
@@ -142,6 +150,8 @@ async function change(limit: number | undefined, ports: LimitPorts): Promise<num
 
 	const after = await seated_now(ports)
 
+	await ports.record_limit()
+
 	if (after > before) await ports.emit_raise(`lane limit ${String(before)} → ${String(after)}`)
 
 	return await show(ports)

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,
 }