@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/run/board/run-board-tick.ts

@@ -0,0 +1,210 @@
+import { run_progress } from '#scripts/run/progress/run-progress'
+import type { ClosedIssue } from './run-board-closed'
+import { run_board_github } from './run-board-github'
+import { run_board_header, type BoardHeader } from './run-board-header'
+import { run_board_labels } from './run-board-labels'
+import { run_board_layout, type BoardLayout, type BoardPlan } from './run-board-layout'
+import { run_board_link } from './run-board-link'
+import { run_board_machine } from './run-board-machine'
+import { run_board_notes, type Titles } from './run-board-notes'
+import type { LocalRead } from './run-board-read'
+import { run_board_render, type FrameBounds } from './run-board-render'
+import { run_board_spin, type Spun } from './run-board-spin'
+import { run_board_state, type BoardPorts, type BoardState, type Pace } from './run-board-state'
+import { run_board_status } from './run-board-status'
+import { run_board_usage } from './run-board-usage'
+
+// One `run:board` redraw. **Three speeds**: the frame is redrawn once a second, on the second, so
+// every elapsed time moves by one, its spinners turned between redraws by `run-board-spin.ts`; the
+// run's own stream and lanes are re-read no more often than `LOCAL_READ_MS`, because each read parses
+// the whole stream and asks git twice, and a board left open all night would otherwise grow heavier
+// as the run grew longer; the GitHub reads they are laid over are `run-board-github.ts`'s, which a
+// live board never waits on. Between reads the last one is kept and drawn against the current time.
+// A run that ended stays on screen until the next one starts. With no run in this checkout it reads
+// nothing from GitHub. The machine is sampled once a second: one `sysctl` takes a few milliseconds,
+// and its gauges are the differences between consecutive samples.
+
+const { REDRAW_MS, SPOT } = run_board_spin
+const MACHINE_SAMPLE_MS = run_progress.MS_PER_SECOND
+const LOCAL_READ_SECONDS = 5
+const LOCAL_READ_MS = LOCAL_READ_SECONDS * run_progress.MS_PER_SECOND
+const { FRESH_STATE, is_due } = run_board_state
+const { PLAN_RETRY_MS, gather_github, statuses_for } = run_board_github
+
+async function reread(state: BoardState, ports: BoardPorts, now_ms: number): Promise<BoardState> {
+	if (!is_due(state.read_ms, LOCAL_READ_MS, now_ms)) return state
+
+	return { ...state, local: await ports.read_local(), read_ms: now_ms }
+}
+
+// Each lane's usage, read on the machine's second; a reading that failed draws no column.
+async function read_usages(
+	state: BoardState,
+	ports: BoardPorts,
+): Promise<Pick<BoardState, 'usage' | 'usages'>> {
+	const usage = await ports.read_usage(state.usage)
+	const usages = usage === undefined ? undefined : run_board_usage.usage_of(state.usage, usage)
+
+	return { usage, usages }
+}
+
+// The sample is timed when it is taken, not when the tick began: a plan read between the two would put
+// its seconds on the wrong side of the rate's interval. It is due by the tick's clock, so a sample
+// taken a few milliseconds into its tick does not slip to the redraw after the second.
+async function resample(state: BoardState, ports: BoardPorts, now_ms: number): Promise<BoardState> {
+	if (!is_due(state.sampled_ms, MACHINE_SAMPLE_MS, now_ms)) return state
+
+	const at_ms = ports.now()
+	const machine = { sample: await ports.read_machine(), at_ms }
+	const gauges = run_board_machine.gauges_of(state.machine, machine)
+
+	return { ...state, ...(await read_usages(state, ports)), machine, gauges, sampled_ms: now_ms }
+}
+
+// The state of the run on screen; a different run starts its plan state from nothing, so no row, count
+// or baseline of the previous run is drawn over the new one.
+function state_for(state: BoardState, local: LocalRead): BoardState {
+	if (state.run_started_ms === local.started_ms) return state
+
+	const { local: kept, read_ms } = state
+
+	return { ...FRESH_STATE, local: kept, read_ms, run_started_ms: local.started_ms }
+}
+
+// The plan with a closed child's title and labels under the listing's own.
+function with_closed(plan: BoardPlan, closed: ReadonlyMap<number, ClosedIssue>): BoardPlan {
+	const closed_titles = [...closed].map(([issue, { title }]) => [issue, title] as const)
+	const closed_labels = [...closed].map(([issue, { labels }]) => [issue, labels] as const)
+	const titles = new Map([...closed_titles, ...plan.context.titles])
+	const labels = new Map([...closed_labels, ...plan.labels])
+
+	return { ...plan, context: { ...plan.context, titles }, labels }
+}
+
+// The titles the findings name a parked issue by — the rows' own; none before the plan is read.
+function titles_of(state: BoardState): Titles {
+	if (state.plan === undefined) return new Map()
+
+	return with_closed(state.plan, state.closed).context.titles
+}
+
+// The statuses scoped to the run's plan, a running child the plan's listing no longer holds settled.
+// Before the plan is read, the run's own children alone.
+function layout_for(state: BoardState, local: LocalRead): BoardLayout {
+	const { plan, closed } = state
+
+	if (plan === undefined) {
+		return run_board_layout.local_layout_of(
+			run_board_status.statuses_of(local.events, local.lanes, new Set()),
+		)
+	}
+
+	const read = {
+		open_numbers: plan.context.open_numbers,
+		read_ms: state.fetched_ms,
+		closed,
+		labels: plan.labels,
+	}
+	const statuses = run_board_status.settle_closed(statuses_for(plan, local), read)
+
+	return run_board_layout.layout_of(with_closed(plan, closed), statuses)
+}
+
+// What one redraw draws with.
+interface Redraw {
+	ports: BoardPorts
+	now_ms: number
+}
+
+function header_of(
+	state: BoardState,
+	local: LocalRead,
+	layout: BoardLayout,
+	redraw: Redraw,
+): BoardHeader {
+	return {
+		now_ms: redraw.now_ms,
+		started_ms: local.started_ms,
+		ended_ms: local.ended_ms,
+		activity: run_board_status.activity_of(local.events, local.ended_ms !== undefined),
+		layout,
+		baseline_total: state.baseline_total,
+		plan_fetched_ms: state.fetched_ms,
+		plan_failed_ms: state.failed_ms,
+		is_plan_loading: state.plan_fetch !== undefined,
+		machine: state.gauges,
+		usages: state.usages,
+		form: redraw.ports.form,
+		spinner: redraw.ports.is_tty ? SPOT : undefined,
+		link: run_board_link.linker(state.plan?.context.repo, redraw.ports.link),
+	}
+}
+
+// The pane a live frame is kept within and the footer it ends on, read at every redraw.
+function bounds_of(ports: BoardPorts): FrameBounds {
+	return { size: ports.size?.(), footer: ports.footer }
+}
+
+// The frame with its spinners drawn at this moment's frame, and where they are on screen.
+function frame_of(state: BoardState, local: LocalRead, layout: BoardLayout, redraw: Redraw): Spun {
+	const bounds = bounds_of(redraw.ports)
+	const lines = run_board_render.render({
+		header: header_of(state, local, layout, redraw),
+		notes: run_board_notes.notes_of(local.events, titles_of(state)),
+		resume: local.resume,
+		...bounds,
+	})
+
+	return run_board_spin.spun(lines, run_board_labels.spinner_of(redraw.now_ms), bounds.size)
+}
+
+function draw(ports: BoardPorts, lines: ReadonlyArray<string>): void {
+	ports.write(`${lines.join('\n')}\n`)
+}
+
+// The first total the plan gives is the baseline every later arrival is counted against; the run's own
+// children before it are no total.
+function draw_run(state: BoardState, local: LocalRead, redraw: Redraw): BoardState {
+	const layout = layout_for(state, local)
+	const first_total =
+		state.plan === undefined ? undefined : run_board_header.counts_of(layout).total
+	const settled = { ...state, baseline_total: state.baseline_total ?? first_total }
+	const { lines, spots } = frame_of(settled, local, layout, redraw)
+
+	draw(redraw.ports, lines)
+
+	return { ...settled, spots }
+}
+
+// One redraw. No run reads nothing from GitHub and keeps the plan it had for when one starts. A live
+// board redraws at the `background` pace; one plain frame waits for the GitHub reads.
+async function tick(
+	state: BoardState,
+	ports: BoardPorts,
+	pace: Pace = 'settled',
+): Promise<BoardState> {
+	const now_ms = ports.now()
+	const read = await reread(state, ports, now_ms)
+	const { local } = read
+
+	if (local === undefined) {
+		draw(ports, run_board_render.render_no_run(now_ms, bounds_of(ports)))
+
+		return { ...read, spots: [] }
+	}
+
+	const gathered = await gather_github(state_for(read, local), { ports, local, now_ms, pace })
+
+	return draw_run(await resample(gathered, ports, now_ms), local, { ports, now_ms })
+}
+
+const run_board_tick = {
+	FRESH_STATE,
+	LOCAL_READ_MS,
+	MACHINE_SAMPLE_MS,
+	PLAN_RETRY_MS,
+	REDRAW_MS,
+	tick,
+}
+
+export { run_board_tick }

package/scripts/run/board/run-board-track.ts

@@ -0,0 +1,22 @@
+import { run_board_labels } from './run-board-labels'
+import type { Phase } from './run-board-phase'
+import type { ItemState } from './run-board-status'
+
+// A row's phases as a track: the icon of every phase it has passed, left to right, so how far a child
+// has got and what it is doing now are one mark. **The track is a history**: it grows as the child
+// goes and draws nothing ahead, since a ship that stops sends the child back and no fixed frame says
+// how many rounds are left.
+
+const { PHASE_ICONS, STATE_ICONS } = run_board_labels
+
+// A settled row's track ends on the row's own state icon rather than a fixed ✅, so a child that
+// stopped or parked never reads as having succeeded.
+function track_of(track: ReadonlyArray<Phase>, state: ItemState = 'running'): string {
+	const end = state === 'running' ? '' : STATE_ICONS[state]
+
+	return `${track.map((phase) => PHASE_ICONS[phase]).join('')}${end}`
+}
+
+const run_board_track = { track_of }
+
+export { run_board_track }

package/scripts/run/board/run-board-usage-read.ts

@@ -0,0 +1,255 @@
+import { cpus, totalmem } from 'node:os'
+import path from 'node:path'
+import { lane_paths } from '#scripts/lane/lane-paths'
+import { lane_registry } from '#scripts/lane/lane-registry'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
+import type { ProcessReading, UsageMark } from './run-board-usage'
+import { run_board_usage_rusage, type RusageReader } from './run-board-usage-rusage'
+
+// How `run:board` reads which lane each process belongs to and what it uses.
+// **One `ps` a second, and `lsof` only for a process not seen before.** `ps` lists every process's
+// cumulative CPU time and resident memory in about 15 ms; a process is put in the lane its working
+// directory sits under (`.kit-lanes/<N>`), looked up once and remembered, so a full `lsof` (about
+// 220 ms) is paid on the first sample alone. The working directory rather than the parent chain: a
+// process detached with `josh ship --detach` is re-parented and no longer traceable to its lane.
+// **Only this repository's lanes root counts** — another repository's lane of the same number is a
+// different lane. **macOS alone:** Linux's `ps` prints `time` in whole seconds, too coarse for a
+// one-second difference, so there the board draws no column rather than a figure flickering to 0.
+// **A process born and gone between two samples** — a vitest worker, a gate's eslint / tsc / cspell —
+// is never seen by `ps`, and macOS's `ps -S` does not fold a reaped child's time into its parent's.
+// Where `node:ffi` reaches the kernel's reaped-children times (`run-board-usage-rusage.ts`), each
+// process's CPU time is read with them folded in and its parent is kept, so such a child lands in its
+// parent's lane; elsewhere the figure stays `ps`'s own time, a lower bound.
+
+const PS_ARGUMENTS = ['-A', '-o', 'pid=,ppid=,time=,rss=']
+const LSOF_ARGUMENTS = ['-a', '-d', 'cwd', '-Fn', '-p']
+const PID_SEPARATOR = ','
+const PS_FIELDS = 4
+const DAY_SEPARATOR = '-'
+const CLOCK_SEPARATOR = ':'
+const SECONDS_PER_DAY = 86_400
+const SECONDS_PER_CLOCK_PART = 60
+const MS_PER_SECOND = 1000
+const BYTES_PER_KB = 1024
+// `lsof -F`'s field lines: `p<pid>` opens a process, `n<path>` names its directory.
+const LSOF_PROCESS = /^(?=p)/mu
+const LSOF_NAME = 'n'
+const { load_builtin, rusage_reader } = run_board_usage_rusage
+
+// One process's line of `ps`'s listing.
+interface ProcessListing {
+	parent: number
+	reading: ProcessReading
+}
+
+interface UsagePorts {
+	// `ps`'s listing.
+	list: () => Promise<string>
+	// Each process's CPU time with its reaped children's, where `node:ffi` reaches it.
+	rusage: RusageReader | undefined
+	// The working directory of each process that answered.
+	directories: (pids: ReadonlyArray<number>) => Promise<ReadonlyMap<number, string>>
+	now: () => number
+	// The board's own lanes root.
+	root: string
+}
+
+// `ps`'s `time`, `[DD-][HH:]MM:SS[.ss]`, in milliseconds.
+function cpu_ms_of(text: string): number {
+	const [days, clock = ''] = text.includes(DAY_SEPARATOR) ? text.split(DAY_SEPARATOR) : ['0', text]
+	const seconds = clock
+		.split(CLOCK_SEPARATOR)
+		.reduce((sum, part) => sum * SECONDS_PER_CLOCK_PART + Number(part), 0)
+
+	return (Number(days) * SECONDS_PER_DAY + seconds) * MS_PER_SECOND
+}
+
+function listing_of(line: string): [number, ProcessListing] | undefined {
+	const fields = line.trim().split(/\s+/u)
+	const [pid, parent, time = '', rss] = fields
+	const reading = { cpu_ms: cpu_ms_of(time), rss_bytes: Number(rss) * BYTES_PER_KB }
+	const is_number = !Number.isNaN(reading.cpu_ms + reading.rss_bytes + Number(parent))
+
+	if (!is_number || fields.length !== PS_FIELDS) return undefined
+
+	return [Number(pid), { parent: Number(parent), reading }]
+}
+
+function parse_ps(output: string): Map<number, ProcessListing> {
+	const listings = output.split('\n').map((line) => listing_of(line))
+
+	return new Map(listings.filter((listing) => listing !== undefined))
+}
+
+// A process whose read failed keeps the larger of `ps`'s own time and its last reading: once reaped,
+// its whole folded count lands in its parent's, so what comes off there has to be that count — its own
+// time alone would count its reaped children a second time.
+function folded_reading(
+	reading: ProcessReading,
+	cpu_ms: number | undefined,
+	earlier: ProcessReading | undefined,
+): ProcessReading {
+	if (cpu_ms !== undefined) return { ...reading, cpu_ms }
+
+	return { ...reading, cpu_ms: Math.max(reading.cpu_ms, earlier?.cpu_ms ?? 0) }
+}
+
+type Readings = Pick<UsageMark, 'folded' | 'parents' | 'processes'>
+
+function own_readings(listings: ReadonlyMap<number, ProcessListing>): Readings {
+	const processes = new Map([...listings].map(([pid, { reading }]) => [pid, reading] as const))
+
+	return { processes, parents: new Map(), folded: new Set() }
+}
+
+// `ps`'s own-time readings, each replaced by its reaped-children-folded time where `rusage` reads one.
+// Every process keeps its parent once there is a reader: one whose own read failed — gone by then, or
+// another user's — still lands in its parent's count when reaped, so what was counted for it comes off.
+function readings_of(
+	listings: ReadonlyMap<number, ProcessListing>,
+	rusage: RusageReader | undefined,
+	earlier: ReadonlyMap<number, ProcessReading> = new Map(),
+): Readings {
+	if (rusage === undefined) return own_readings(listings)
+
+	const processes = new Map<number, ProcessReading>()
+	const folded = new Set<number>()
+	const parents = new Map([...listings].map(([pid, { parent }]) => [pid, parent] as const))
+
+	for (const [pid, { reading }] of listings) {
+		const cpu_ms = rusage(pid)
+
+		processes.set(pid, folded_reading(reading, cpu_ms, earlier.get(pid)))
+		if (cpu_ms !== undefined) folded.add(pid)
+	}
+
+	return { processes, parents, folded }
+}
+
+function lsof_block(block: string): [number, string] | undefined {
+	const [process_line = '', ...rest] = block.trim().split('\n')
+	const name = rest.find((line) => line.startsWith(LSOF_NAME))
+
+	return name === undefined ? undefined : [Number(process_line.slice(1)), name.slice(1)]
+}
+
+function parse_lsof(output: string): Map<number, string> {
+	const blocks = output.split(LSOF_PROCESS).map((block) => lsof_block(block))
+
+	return new Map(blocks.filter((block) => block !== undefined))
+}
+
+// The lane of `root` a directory sits under — itself or a directory above it, the outermost first.
+function lane_of(directory: string, root: string): string | undefined {
+	const parts = directory.split(path.sep)
+	const ancestors = parts.map((_, index) => parts.slice(0, index + 1).join(path.sep)).slice(1)
+	const environment = { [lane_paths.LANE_ROOT_KEY]: root }
+
+	return ancestors.map((ancestor) => lane_paths.lane_issue_of(ancestor, environment)).find(Boolean)
+}
+
+function directory_lane(directory: string | undefined, root: string): string | undefined {
+	return directory === undefined ? undefined : lane_of(directory, root)
+}
+
+// The lanes of the processes still listed: a gone one dropped, and one not seen before looked up.
+async function lanes_for(
+	known: ReadonlyMap<number, string | undefined>,
+	processes: ReadonlyMap<number, ProcessReading>,
+	ports: UsagePorts,
+): Promise<Map<number, string | undefined>> {
+	const kept = new Map([...known].filter(([pid]) => processes.has(pid)))
+	const fresh = [...processes.keys()].filter((pid) => !kept.has(pid))
+
+	if (fresh.length === 0) return kept
+
+	const directories = await ports.directories(fresh)
+	const found = fresh.map((pid) => [pid, directory_lane(directories.get(pid), ports.root)] as const)
+
+	return new Map([...kept, ...found])
+}
+
+async function sample(before: UsageMark | undefined, ports: UsagePorts): Promise<UsageMark> {
+	const at_ms = ports.now()
+	const readings = readings_of(parse_ps(await ports.list()), ports.rusage, before?.processes)
+	const lanes = await lanes_for(before?.lanes ?? new Map(), readings.processes, ports)
+
+	return { at_ms, ...readings, lanes, cores: cpus().length, total_bytes: totalmem() }
+}
+
+async function darwin_directories(
+	pids: ReadonlyArray<number>,
+): Promise<ReadonlyMap<number, string>> {
+	// `lsof` exits non-zero when any one process is gone, and still lists the rest. A budget kill is
+	// not that: it lists nothing, and `lanes_for` never asks again about a process it read as being in
+	// no lane, so the sample fails instead of pinning every live process to none.
+	const lsof_arguments = [...LSOF_ARGUMENTS, pids.join(PID_SEPARATOR)]
+	const result = await execa('lsof', lsof_arguments, { reject: false, timeout: PROBE_TIMEOUT_MS })
+
+	if (result.timedOut) throw new Error('lsof timed out')
+
+	return parse_lsof(result.stdout)
+}
+
+const PLATFORM_DIRECTORIES: Readonly<Partial<Record<NodeJS.Platform, UsagePorts['directories']>>> =
+	{ darwin: darwin_directories }
+
+async function list_live(): Promise<string> {
+	const { stdout } = await execa('ps', PS_ARGUMENTS, { timeout: PROBE_TIMEOUT_MS })
+
+	return stdout
+}
+
+async function board_lane_root(): Promise<string> {
+	return lane_paths.lane_root(await lane_registry.main_repository_root())
+}
+
+// What one board's reader resolves once and keeps, since neither moves while the board is open.
+interface ReaderSetup {
+	root: Promise<string>
+	rusage: RusageReader | undefined
+}
+
+// `undefined` where the processes cannot be read — no `ps`, no way to a working directory, no
+// repository — so the board draws no column rather than failing.
+async function read_usage(
+	before: UsageMark | undefined,
+	setup: ReaderSetup,
+	platform: NodeJS.Platform,
+): Promise<UsageMark | undefined> {
+	const directories = PLATFORM_DIRECTORIES[platform]
+
+	if (directories === undefined) return undefined
+
+	try {
+		const { rusage } = setup
+		const ports = { list: list_live, rusage, directories, now: Date.now, root: await setup.root }
+
+		return await sample(before, ports)
+	} catch {
+		return undefined
+	}
+}
+
+// One board's reader: the `node:ffi` reader is opened with it, and the lanes root resolved on the first
+// sample.
+function usage_reader(
+	platform: NodeJS.Platform = process.platform,
+): (before: UsageMark | undefined) => Promise<UsageMark | undefined> {
+	const rusage = rusage_reader(platform, load_builtin)
+	const resolved: { root?: Promise<string> } = {}
+
+	async function read(before: UsageMark | undefined): Promise<UsageMark | undefined> {
+		resolved.root ??= board_lane_root()
+
+		return await read_usage(before, { root: resolved.root, rusage }, platform)
+	}
+
+	return read
+}
+
+const run_board_usage_read = { lane_of, parse_lsof, parse_ps, sample, usage_reader }
+
+export { run_board_usage_read }
+export type { UsagePorts }

package/scripts/run/board/run-board-usage-rusage.ts

@@ -0,0 +1,124 @@
+import type { dlopen } from 'node:ffi'
+
+// A process's CPU time with the children it has reaped folded in, so a vitest worker or a gate's
+// eslint born and gone between two `run:board` samples still reaches its lane through its parent.
+// macOS's `ps -S` does not fold them; the kernel keeps them in `proc_pid_rusage`'s
+// `ri_child_user_time` / `ri_child_system_time`, reached here through `node:ffi`.
+//
+// **`node:ffi` is experimental** — added in Node 26 (kit's `engines` is `^22.19.0 || ^24.0.0 ||
+// >=26.0.0`) and liable to change. Where it is missing, or the platform is not macOS, or a call
+// fails, there is no reader and the board keeps `ps`'s own-time figure. Loading it emits an
+// `ExperimentalWarning`, which would land on the board's alternate screen, so the load alone drops it.
+
+// The one part of `node:ffi` the board calls.
+interface Ffi {
+	dlopen: typeof dlopen
+}
+
+type ModuleLoad = (id: string) => unknown
+
+// `ri_*` times are mach absolute time units, which `mach_timebase_info`'s numer / denom turn into ns.
+interface Timebase {
+	numer: number
+	denom: number
+}
+
+// The CPU milliseconds of one process, `undefined` where it cannot be read (gone, or another user's).
+type RusageReader = (pid: number) => number | undefined
+
+const PROC_LIBRARY = '/usr/lib/libproc.dylib'
+const SYSTEM_LIBRARY = '/usr/lib/libSystem.B.dylib'
+const RUSAGE_INFO_V2 = 2
+const RUSAGE_INFO_V2_BYTES = 160
+// `rusage_info_v2`'s `ri_user_time`, `ri_system_time`, `ri_child_user_time`, `ri_child_system_time`.
+const USER_TIME_OFFSET = 16
+const SYSTEM_TIME_OFFSET = 24
+const CHILD_USER_TIME_OFFSET = 96
+const CHILD_SYSTEM_TIME_OFFSET = 104
+const TIME_OFFSETS = [
+	USER_TIME_OFFSET,
+	SYSTEM_TIME_OFFSET,
+	CHILD_USER_TIME_OFFSET,
+	CHILD_SYSTEM_TIME_OFFSET,
+]
+const TIMEBASE_BYTES = 8
+const DENOM_OFFSET = 4
+const NS_PER_MS = 1_000_000
+const EXPERIMENTAL_WARNING = 'ExperimentalWarning'
+const DARWIN: NodeJS.Platform = 'darwin'
+
+const PROC_PID_RUSAGE = {
+	proc_pid_rusage: { arguments: ['int32', 'int32', 'buffer'], return: 'int32' },
+} as const
+const MACH_TIMEBASE_INFO = {
+	mach_timebase_info: { arguments: ['buffer'], return: 'int32' },
+} as const
+
+// The four times of an `rusage_info_v2`, in milliseconds.
+function cpu_ms_of(buffer: Buffer, timebase: Timebase): number {
+	const ticks = TIME_OFFSETS.reduce(
+		(sum, offset) => sum + Number(buffer.readBigUInt64LE(offset)),
+		0,
+	)
+
+	return (ticks * timebase.numer) / timebase.denom / NS_PER_MS
+}
+
+// `node:ffi`, its load's `ExperimentalWarning` dropped — the load is synchronous, so no other warning
+// can fall inside the window.
+function quiet_ffi(load: ModuleLoad): Ffi | undefined {
+	const emit_warning = process.emitWarning
+
+	process.emitWarning = function quiet(warning: string | Error, ...rest: Array<unknown>): void {
+		if (rest[0] !== EXPERIMENTAL_WARNING) Reflect.apply(emit_warning, process, [warning, ...rest])
+	}
+
+	try {
+		return load('node:ffi') as Ffi | undefined
+	} finally {
+		process.emitWarning = emit_warning
+	}
+}
+
+function timebase_of(ffi: Ffi): Timebase {
+	const buffer = Buffer.alloc(TIMEBASE_BYTES)
+
+	ffi.dlopen(SYSTEM_LIBRARY, MACH_TIMEBASE_INFO).functions.mach_timebase_info(buffer)
+
+	return { numer: buffer.readUInt32LE(0), denom: buffer.readUInt32LE(DENOM_OFFSET) }
+}
+
+function reader_of(ffi: Ffi): RusageReader {
+	const timebase = timebase_of(ffi)
+	const { proc_pid_rusage } = ffi.dlopen(PROC_LIBRARY, PROC_PID_RUSAGE).functions
+	const buffer = Buffer.alloc(RUSAGE_INFO_V2_BYTES)
+
+	return function read(pid: number): number | undefined {
+		const status = proc_pid_rusage(pid, RUSAGE_INFO_V2, buffer)
+
+		return status === 0 ? cpu_ms_of(buffer, timebase) : undefined
+	}
+}
+
+function load_builtin(id: string): unknown {
+	return process.getBuiltinModule(id)
+}
+
+// `load` answers `undefined` for a module this Node lacks, as `process.getBuiltinModule` does; there,
+// and off macOS, there is no reader and every process keeps `ps`'s figure.
+function rusage_reader(platform: NodeJS.Platform, load: ModuleLoad): RusageReader | undefined {
+	if (platform !== DARWIN) return undefined
+
+	try {
+		const ffi = quiet_ffi(load)
+
+		return ffi === undefined ? undefined : reader_of(ffi)
+	} catch {
+		return undefined
+	}
+}
+
+const run_board_usage_rusage = { cpu_ms_of, load_builtin, quiet_ffi, rusage_reader }
+
+export { run_board_usage_rusage }
+export type { RusageReader, Timebase }