@joshuafolkken/kit 1.1229.0 → 1.1370.0

package/scripts/lane/lane-ledger.ts

@@ -4,8 +4,9 @@ import { json_value } from '#scripts/lib/json-value'
 import { run_carry } from '#scripts/run/carry/run-carry'
 import { z } from 'zod'
 
-// The measurement ledger the lane limit is tuned against (joshuafolkken/kit#3355): one JSON line per
-// lane merge, per finished `josh gate`, and per machine-load sample, read back by `josh lane:stats`.
+// 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 and per finished
+// `josh ship` stage, 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
@@ -20,13 +21,21 @@ import { z } from 'zod'
 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' } as const
+const KIND = {
+	MERGE: 'merge',
+	GATE: 'gate',
+	LOAD: 'load',
+	DISPATCH: 'dispatch',
+	STAGE: 'stage',
+} as const
 
 const merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
 const gate_schema = z.object({
@@ -34,23 +43,59 @@ const gate_schema = z.object({
 	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(),
 })
-// `swap_mb` and `lanes` are optional because either read can fail on its own — a platform with no
-// swap reading, a `git worktree` call that did not answer — and a sample is still worth its load.
+// `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 load_schema = z.object({
 	kind: z.literal(KIND.LOAD),
 	at: z.string(),
 	load: z.number(),
-	free_mb: z.number(),
-	swap_mb: z.number().optional(),
+	available_mb: z.number().optional(),
+	swapped_mb: z.number().optional(),
 	lanes: z.number().optional(),
 })
-const entry_schema = z.discriminatedUnion('kind', [merge_schema, gate_schema, load_schema])
+// 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(),
+})
+const entry_schema = z.discriminatedUnion('kind', [
+	merge_schema,
+	gate_schema,
+	load_schema,
+	dispatch_schema,
+	stage_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>
+// What a finished gate reports; the ledger stamps the kind and the time.
+type GateRecord = Omit<GateEntry, 'kind' | 'at'>
+type StageRecord = Omit<StageEntry, 'kind' | 'at'>
 
 function target_of(repository: string): string {
 	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
@@ -59,7 +104,13 @@ function target_of(repository: string): string {
 // 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()
 
@@ -101,14 +152,22 @@ function now_iso(): string {
 }
 
 // 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, elapsed_ms: number, is_passed: boolean): Promise<void> {
-	await record({ kind: KIND.GATE, at: now_iso(), elapsed_ms, is_passed }, path)
+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)
+}
+
 function parse_line(line: string): LedgerEntry | undefined {
 	return entry_schema.safeParse(json_value.parse_or_undefined(line)).data
 }
@@ -131,15 +190,18 @@ function read_entries(path: string): ReadonlyArray<LedgerEntry> {
 }
 
 const lane_ledger = {
+	CI_WAIT_STAGE,
 	KIND,
 	append,
 	read_entries,
 	record,
+	record_dispatch,
 	record_gate,
 	record_merge,
+	record_stage,
 	target,
 	target_of,
 }
 
-export type { GateEntry, LedgerEntry, LoadEntry, MergeEntry }
+export type { DispatchEntry, GateEntry, LedgerEntry, LoadEntry, MergeEntry, StageEntry }
 export { lane_ledger }

package/scripts/lane/lane-leftover.ts

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto'
 import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync, rmSync } from 'node:fs'
 import path from 'node:path'
+import { ENV_FILE_NAME } from '#ports'
 import { git_spawn } from '#scripts/git/git-spawn'
+import { IGNORED_CACHE_FILES } from '#scripts/josh/josh-command-types'
 
-// A lane directory git no longer registers as a work tree (joshuafolkken/kit#2857).
+// A lane directory git no longer registers as a work tree.
 //
 // **Nothing else can see it.** `lane:list` and `lane:prune` read `git worktree list`, so a directory
 // whose registration is gone is invisible to both, and `git worktree add` refuses its path for good —
@@ -11,31 +13,38 @@ import { git_spawn } from '#scripts/git/git-spawn'
 // here before it adds the tree.
 //
 // **The test for removing it is that removing it loses nothing**, not a list of names. Every file in
-// it has to be one the repository already holds with the same content, so it is a checkout git would
-// write again; the one exception is the `.git` file, a pointer to the registration that is gone. A
-// list of generated names would break the next time a file is generated, and would delete whatever
-// shares one of those names.
-
-// `git ls-tree -r -z`: `<mode> <type> <object>\t<path>`, entries separated by NUL — the `-z` form
-// leaves a path with an unusual character unquoted, so it can be compared to the path on disk.
-const TREE_ENTRY_PATTERN = /^\d+ blob (?<object>[\da-f]+)\t(?<path>.+)$/su
+// it has to hold content the repository's history already stores — a blob some ref reaches — so git
+// can write it again; the one exception is the `.git` file, a pointer to the registration that is
+// gone. **Any commit's content, not only `HEAD`'s at the same path**: a
+// leftover is a checkout of whatever commit its lane was on, and measured against `HEAD` the
+// leftovers that issue found differed in 167 to 1,431 files each while every one of them was in the
+// history. A list of generated names would break the next time a file is generated, and would delete
+// whatever shares one of those names.
+//
+// **The one list of names is what `lane:open` and the gate regenerate**, and only at the top level:
+// the install's `node_modules`, the build's `dist`, the `.env` `lane:open` writes from the root's, and
+// the gate's caches. A lane carries them on top of its checkout, none is in the history, and walking
+// `node_modules` alone would hash tens of thousands of files.
+const REGENERATED_PATHS: ReadonlySet<string> = new Set([
+	'node_modules',
+	'dist',
+	ENV_FILE_NAME,
+	...IGNORED_CACHE_FILES,
+])
 const GIT_POINTER = '.git'
 const GITDIR_PREFIX = 'gitdir: '
 // The foreign paths a refusal names before it summarizes the rest as a count.
 const NAMED_PATH_LIMIT = 10
 
-// One blob entry as `[path, object id]`; a tree, a commit (a submodule) or the trailing empty entry is
-// none.
-function tree_entry(entry: string): Array<[string, string]> {
-	const { path: entry_path, object } = TREE_ENTRY_PATTERN.exec(entry)?.groups ?? {}
-
-	if (entry_path === undefined || object === undefined) return []
-
-	return [[entry_path, object]]
+// `git rev-list --objects --all`: one `<object>[ <path>]` line per object any ref reaches — commits,
+// trees and blobs alike, which costs nothing here, because only a blob id can equal a file's.
+function parse_objects(listing: string): Set<string> {
+	return new Set(listing.split('\n').map((line) => line.split(' ', 1)[0] ?? ''))
 }
 
-function parse_tree(listing: string): Map<string, string> {
-	return new Map(listing.split('\0').flatMap((entry) => tree_entry(entry)))
+/** Every object id the repository's refs reach — the content a leftover can be restored from. */
+async function recoverable_objects(): Promise<Set<string>> {
+	return parse_objects(await git_spawn.read(['rev-list', '--objects', '--all']))
 }
 
 // The object id git gives this file — a symbolic link's is that of its target string, as git stores it.
@@ -63,9 +72,14 @@ function walk_files(directory: string, relative: string): Array<string> {
 	})
 }
 
-// Every file under `directory` as a repository path, symbolic links included and never followed.
+// Every file under `directory` as a repository path, symbolic links included and never followed —
+// less the regenerated top-level entries, which are neither walked nor listed.
 function list_files(directory: string): Array<string> {
-	return walk_files(directory, '')
+	return readdirSync(directory)
+		.filter((name) => !REGENERATED_PATHS.has(name))
+		.flatMap((name) =>
+			lstatSync(path.join(directory, name)).isDirectory() ? walk_files(directory, name) : name,
+		)
 }
 
 // The `.git` file is disposable only while the registration it points to is gone: one that still
@@ -85,25 +99,25 @@ function is_dangling_pointer(directory: string): boolean {
 function is_reclaimable_file(
 	directory: string,
 	relative: string,
-	tracked: ReadonlyMap<string, string>,
+	recoverable: ReadonlySet<string>,
 ): boolean {
 	if (relative === GIT_POINTER) return is_dangling_pointer(directory)
 
-	return tracked.get(relative) === blob_id(path.join(directory, relative))
+	return recoverable.has(blob_id(path.join(directory, relative)))
 }
 
 /**
  * The paths under `directory` whose removal would lose something — empty when it holds nothing but
- * the repository's own files and the `.git` pointer. A `.git` directory is a repository of its own,
- * so it is foreign as a whole rather than walked.
+ * content the history stores, the regenerated entries and the `.git` pointer. A `.git` directory is a
+ * repository of its own, so it is foreign as a whole rather than walked.
  */
-function foreign_paths(directory: string, tracked: ReadonlyMap<string, string>): Array<string> {
+function foreign_paths(directory: string, recoverable: ReadonlySet<string>): Array<string> {
 	const pointer = lstatSync(path.join(directory, GIT_POINTER), { throwIfNoEntry: false })
 
 	if (pointer?.isDirectory() === true) return [GIT_POINTER]
 
 	return list_files(directory).filter(
-		(relative) => !is_reclaimable_file(directory, relative, tracked),
+		(relative) => !is_reclaimable_file(directory, relative, recoverable),
 	)
 }
 
@@ -125,8 +139,7 @@ function refusal(directory: string, foreign: ReadonlyArray<string>): Error {
 async function reclaim(directory: string): Promise<void> {
 	if (!existsSync(directory)) return
 
-	const tracked = parse_tree(await git_spawn.read(['ls-tree', '-r', '-z', '--full-tree', 'HEAD']))
-	const foreign = foreign_paths(directory, tracked)
+	const foreign = foreign_paths(directory, await recoverable_objects())
 
 	if (foreign.length > 0) throw refusal(directory, foreign)
 
@@ -136,8 +149,9 @@ async function reclaim(directory: string): Promise<void> {
 const lane_leftover = {
 	blob_id,
 	foreign_paths,
-	parse_tree,
+	parse_objects,
 	reclaim,
+	recoverable_objects,
 }
 
 export { lane_leftover }

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

@@ -0,0 +1,160 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { backlog_ready } from '#scripts/backlog/backlog-ready'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { lane_capacity, type LimitChoice } from './lane-capacity'
+import { lane_limit_override } from './lane-limit-override'
+
+// `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`
+// cannot move under it; this writes an override onto the run's carry record, which
+// `lane_capacity.lane_limit` reads first. Bare, it prints the limit, the lanes in use and the free ones.
+//
+// **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.
+
+const ARGV_OFFSET = 2
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const MAX_POSITIONALS = 1
+const NO_LIMIT = 0
+const LIMIT_NAME = '<limit>'
+const OVERRIDE_SOURCE = 'lane:limit override'
+const USAGE = 'Usage: josh lane:limit [<limit>] [--reset]'
+const NO_RUN_MESSAGE = `No run is in progress: lane:limit changes a live run's limit. Set ${lane_capacity.LANE_LIMIT_KEY} for the next run.`
+
+const OPTIONS = { reset: { type: 'boolean' } } as const
+
+// `set` with no limit is `--reset`: the override is cleared and the environment's limit stands.
+type LimitRequest =
+	| { kind: 'show' }
+	| { kind: 'set'; limit: number | undefined }
+	| { kind: 'refuse'; message: string }
+
+interface LimitPorts {
+	read_limit: () => Promise<LimitChoice>
+	read_override: () => Promise<number | undefined>
+	write_override: (limit: number | undefined) => Promise<boolean>
+	emit_raise: (text: string) => Promise<void>
+	live_lane_count: () => Promise<number>
+}
+
+interface LimitStatus {
+	limit: number
+	override: number | undefined
+	in_use: number
+}
+
+const SHOW: LimitRequest = { kind: 'show' }
+const RESET: LimitRequest = { kind: 'set', limit: undefined }
+const USAGE_REFUSAL: LimitRequest = { kind: 'refuse', message: USAGE }
+
+const DEFAULT_PORTS: LimitPorts = {
+	read_limit: async () => await lane_capacity.lane_limit(),
+	read_override: lane_limit_override.read_override,
+	write_override: lane_limit_override.write_override,
+	emit_raise: lane_limit_override.emit_raise,
+	live_lane_count: backlog_ready.live_lane_count,
+}
+
+function refuse(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+// The rule `JOSH_LANE_LIMIT` is read by, so the two refuse alike.
+function limit_request(raw: string): LimitRequest {
+	const choice = lane_capacity.read_limit(raw, LIMIT_NAME)
+
+	return choice.kind === 'limit'
+		? { kind: 'set', limit: choice.limit }
+		: { kind: 'refuse', message: choice.problem }
+}
+
+function request_of(raw: string | undefined, is_reset: boolean): LimitRequest {
+	if (is_reset) return raw === undefined ? RESET : USAGE_REFUSAL
+
+	return raw === undefined ? SHOW : limit_request(raw)
+}
+
+function parse_request(argv: ReadonlyArray<string>): LimitRequest {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined || parsed.positionals.length > MAX_POSITIONALS) return USAGE_REFUSAL
+
+	return request_of(parsed.positionals[0], parsed.values.reset === true)
+}
+
+// A limit past the port seats is shown at the seats it can actually fill, as `free_lanes` counts it.
+function limit_text(limit: number): string {
+	const seated = lane_capacity.seated_limit(limit)
+
+	return seated === limit
+		? String(limit)
+		: `${String(seated)} (${String(limit)} capped at the seats)`
+}
+
+function status_line(status: LimitStatus): string {
+	const source = status.override === undefined ? lane_capacity.LANE_LIMIT_KEY : OVERRIDE_SOURCE
+	const free = lane_capacity.free_lanes(status.limit, status.in_use)
+
+	return `lane limit ${limit_text(status.limit)} (${source}) · in use ${String(status.in_use)} · free ${String(free)}`
+}
+
+async function show(ports: LimitPorts): Promise<number> {
+	const choice = await ports.read_limit()
+
+	if (choice.kind === 'problem') return refuse(choice.problem)
+
+	const override = await ports.read_override()
+
+	console.info(
+		status_line({ limit: choice.limit, override, in_use: await ports.live_lane_count() }),
+	)
+
+	return SUCCESS_EXIT_CODE
+}
+
+// An unreadable limit counts as none, so a valid one set over it is a raise.
+async function seated_now(ports: LimitPorts): Promise<number> {
+	const choice = await ports.read_limit()
+
+	return choice.kind === 'limit' ? lane_capacity.seated_limit(choice.limit) : NO_LIMIT
+}
+
+// Measured in seats, so a raise past the seats — which frees no lane — wakes nobody.
+async function change(limit: number | undefined, ports: LimitPorts): Promise<number> {
+	const before = await seated_now(ports)
+
+	if (!(await ports.write_override(limit))) return refuse(NO_RUN_MESSAGE)
+
+	const after = await seated_now(ports)
+
+	if (after > before) await ports.emit_raise(`lane limit ${String(before)} → ${String(after)}`)
+
+	return await show(ports)
+}
+
+async function run(
+	argv: ReadonlyArray<string>,
+	ports: LimitPorts = DEFAULT_PORTS,
+): Promise<number> {
+	const request = parse_request(argv)
+
+	if (request.kind === 'refuse') return refuse(request.message)
+
+	return request.kind === 'show' ? await show(ports) : await change(request.limit, ports)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_limit_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { LimitPorts }
+export { lane_limit_cli }

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

@@ -0,0 +1,74 @@
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { run_carry, type RunCarry } from '#scripts/run/carry/run-carry'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
+
+// The live run's lane-limit override: where `josh lane:limit` writes it, where
+// `lane_capacity.lane_limit` reads it, and how the `--wait` watcher sees a raise.
+//
+// **It lives on the run's carry record**, not in a file of its own. A running parent keeps the
+// environment it started with, so `JOSH_LANE_LIMIT` cannot change under it; the record is keyed on the
+// common git directory, so the parent, its lanes and a person's shell all resolve the same one — and it
+// is removed with the run at `run:carry --end`, so an override never outlives the run it was set on.
+
+const STREAM_START = 0
+
+async function carry_target(): Promise<string | undefined> {
+	const repository = await run_carry.repository_directory()
+
+	return repository === undefined ? undefined : run_carry.carry_path(repository)
+}
+
+function live_carry(target: string): RunCarry | undefined {
+	const read = run_carry.read_carry(target)
+
+	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> {
+	const target = await carry_target()
+
+	return target === undefined ? undefined : live_carry(target)?.lane_limit
+}
+
+// `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> {
+	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 })
+
+	return true
+}
+
+async function emit_raise(text: string): Promise<void> {
+	await run_event_stream_emit.emit(run_event_stream.EVENT_KIND.LANE_LIMIT, text)
+}
+
+function never_raised(): boolean {
+	return false
+}
+
+// A check for a raise written after this call — the watcher takes it at its start, so a raise it was
+// started after is not one it wakes for.
+async function watch_raise(): Promise<() => boolean> {
+	const target = await run_event_stream_emit.stream_target()
+
+	if (target === undefined) return never_raised
+
+	const start = run_event_stream.read_from(target, STREAM_START).next_position
+
+	return function is_raised(): boolean {
+		const { events } = run_event_stream.read_from(target, start)
+
+		return events.some((event) => event.kind === run_event_stream.EVENT_KIND.LANE_LIMIT)
+	}
+}
+
+const lane_limit_override = { emit_raise, read_override, watch_raise, write_override }
+
+export { lane_limit_override }

package/scripts/lane/lane-load.ts

@@ -1,70 +1,20 @@
-import { readFile } from 'node:fs/promises'
-import { freemem, loadavg } from 'node:os'
-import { execa } from 'execa'
+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 { lane_registry, type LaneInfo } from './lane-registry'
 
-// One machine-load sample for the lane-limit measurement (joshuafolkken/kit#3355): the one-minute load
-// average, free memory, swap in use and how many lanes have a child working, read at one instant so
-// `josh lane:stats` can set the load beside the lane count that produced it.
+// One machine-load sample for the lane-limit measurement: the one-minute load
+// average, available memory, the swap counter and how many lanes have a child working, read at one
+// instant so `josh lane:stats` can set the load beside the lane count that produced it.
 //
-// **Swap is read per platform and is optional.** Node exposes no swap figure, so macOS asks `sysctl` and
-// Linux reads `/proc/meminfo`; any other platform, or an output neither parser recognizes, records the
-// sample without it rather than as a zero nobody measured.
-
-const BYTES_PER_MB = 1_048_576
-const MB_PER_GB = 1024
-const KB_PER_MB = 1024
-const DARWIN_SWAP = /used = (?<amount>[\d.]+)(?<unit>[MG])/u
-const LINUX_SWAP_TOTAL = /^SwapTotal:\s+(?<kb>\d+) kB/mu
-const LINUX_SWAP_FREE = /^SwapFree:\s+(?<kb>\d+) kB/mu
-const MEMINFO_PATH = '/proc/meminfo'
-const SYSCTL_ARGUMENTS = ['-n', 'vm.swapusage']
-const GB_UNIT = 'G'
-
-// `sysctl -n vm.swapusage` → `total = 5120.00M  used = 3993.25M  free = 1126.75M  (encrypted)`.
-function parse_darwin_swap(output: string): number | undefined {
-	const groups = DARWIN_SWAP.exec(output)?.groups
-
-	if (groups?.['amount'] === undefined) return undefined
-
-	const scale = groups['unit'] === GB_UNIT ? MB_PER_GB : 1
-
-	return Number(groups['amount']) * scale
-}
-
-function kilobytes_of(meminfo: string, pattern: RegExp): number | undefined {
-	const kb = pattern.exec(meminfo)?.groups?.['kb']
-
-	return kb === undefined ? undefined : Number(kb)
-}
-
-// `/proc/meminfo` carries the total and the free swap; what is in use is their difference.
-function parse_linux_swap(meminfo: string): number | undefined {
-	const total = kilobytes_of(meminfo, LINUX_SWAP_TOTAL)
-	const free = kilobytes_of(meminfo, LINUX_SWAP_FREE)
-
-	if (total === undefined || free === undefined) return undefined
-
-	return (total - free) / KB_PER_MB
-}
-
-async function read_swap_mb(
-	platform: NodeJS.Platform = process.platform,
-): Promise<number | undefined> {
-	try {
-		if (platform === 'darwin') {
-			const { stdout } = await execa('sysctl', SYSCTL_ARGUMENTS)
-
-			return parse_darwin_swap(stdout)
-		}
-
-		return platform === 'linux' ? parse_linux_swap(await readFile(MEMINFO_PATH, 'utf8')) : undefined
-	} catch {
-		return undefined
-	}
-}
+// **The memory is `machine_capacity`'s reading, the one the gate admits against.** `os.freemem()` reads
+// near zero on macOS with gigabytes to spare, and a second swap parser here measured swap in use while
+// the gate measured pages swapped — two figures for one machine. `swapped_mb` is that counter, every
+// page swapped since boot, so `lane:stats` reads a rate from the difference between two samples.
+//
+// **Either figure is optional.** A platform the reading does not cover, or a probe that did not answer,
+// records the sample without it rather than as a zero nobody measured.
 
 // The lanes with a child at work. An open lane is not enough: a stranded lane, or one a park kept, holds
 // a tree but no running child, so it adds no load — the child's process is what `lane:await` polls.
@@ -83,25 +33,26 @@ async function read_lanes(): Promise<number | undefined> {
 	}
 }
 
+function rounded(megabytes: number | undefined): number | undefined {
+	return megabytes === undefined ? undefined : Math.round(megabytes)
+}
+
 async function sample(at: string): Promise<LoadEntry> {
-	const [swap_mb, lanes] = await Promise.all([read_swap_mb(), read_lanes()])
+	const [memory, lanes] = await Promise.all([machine_capacity.read_memory(), read_lanes()])
 	const [load = 0] = loadavg()
 
 	return {
 		kind: 'load',
 		at,
 		load,
-		free_mb: Math.round(freemem() / BYTES_PER_MB),
-		swap_mb,
+		available_mb: rounded(memory.available_mb),
+		swapped_mb: rounded(memory.swapped_mb),
 		lanes,
 	}
 }
 
 const lane_load = {
 	count_working,
-	parse_darwin_swap,
-	parse_linux_swap,
-	read_swap_mb,
 	sample,
 }