@joshuafolkken/kit 1.1178.0 → 1.1240.0

package/scripts/lane/lane-dispatch.ts

@@ -1,12 +1,13 @@
 import { agent_argv, type AgentArgv, type AgentArgvResult } from '#scripts/agent/agent-argv'
 import { agent_role_profile, type AgentProfile } from '#scripts/agent/agent-role-profile'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { LabelWrite } from '#scripts/gh/git-gh-issue-write'
 import { IN_PROGRESS_LABEL } from '#scripts/issue/issue-labels'
 import { telegram_notify } from '#scripts/notify/telegram-notify'
 import { detached_launch } from '#scripts/run/detached-launch'
+import { run_event_stream } from '#scripts/run/event/run-event-stream'
+import { run_event_stream_emit } from '#scripts/run/event/run-event-stream-emit'
 import { run_ending } from '#scripts/run/run-ending'
-import { run_event_stream } from '#scripts/run/run-event-stream'
-import { run_event_stream_emit } from '#scripts/run/run-event-stream-emit'
 import { run_issue_number } from '#scripts/run/run-issue-number'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
@@ -79,7 +80,7 @@ type DispatchOutcome =
 	// that marks a child as holding its lane — the lane count, the offer filter, `run:progress` and the
 	// stale check all read it — so a child that ran without it would be counted as an empty lane and
 	// handed to a second session. Refusing the launch keeps "dispatched" and "counted as busy" one state.
-	| { kind: typeof LABEL_UNSET_KIND }
+	| { kind: typeof LABEL_UNSET_KIND; reason: string }
 
 type LogOutcome = { kind: 'ready'; path: string } | { kind: 'unrecordable'; reason: string }
 
@@ -305,9 +306,10 @@ function prepared(lane: LaneInfo): Prepared {
 // to its (idempotent) apply. `issue_add_label` creates the label if the repository lacks it — a
 // `POST /issues/{N}/labels` provisions a missing label with a generated color (measured on
 // joshuafolkken/kit#1026, `git-gh-issue-write.ts`) — so no separate `label_ensure` is needed here, and
-// its `false` is a real refusal to launch rather than a note.
-async function mark_in_progress(issue: string): Promise<boolean> {
-	return await git_gh_command.issue_add_label(issue, IN_PROGRESS_LABEL)
+// its unapplied answer is a real refusal to launch rather than a note — confirmed by a read-back, so
+// a write that landed but answered with an error still launches (joshuafolkken/kit#3312).
+async function mark_in_progress(issue: string): Promise<LabelWrite> {
+	return await git_gh_command.issue_apply_label(issue, IN_PROGRESS_LABEL)
 }
 
 // The dispatch owns both halves of the marker: it applied it, so a launch that never started takes it
@@ -324,8 +326,12 @@ async function unmark_in_progress(issue: string): Promise<void> {
 
 // A started child is recorded on the run's stream, which is where the stall detector ages the last
 // dispatch from (joshuafolkken/kit#2464) — unrecorded, every stall read "hours since the last dispatch"
-// minutes after a launch. A failed start records nothing: no child is running.
+// minutes after a launch. A failed start records nothing: no child is running. The marker is claimed
+// first, so a refused one starts nothing.
 async function finish_dispatch(issue: string, request: StartRequest): Promise<DispatchOutcome> {
+	const mark = await mark_in_progress(issue)
+
+	if (!mark.is_applied) return { kind: LABEL_UNSET_KIND, reason: mark.reason }
 	const outcome = await started(request)
 
 	const is_failed = outcome.kind === 'failed'
@@ -353,8 +359,6 @@ async function dispatch_child(issue: string): Promise<DispatchOutcome> {
 
 	if (log.kind !== 'ready') return log
 
-	if (!(await mark_in_progress(issue))) return { kind: LABEL_UNSET_KIND }
-
 	return await finish_dispatch(issue, { lane, log_path: log.path, ...built })
 }
 
@@ -410,7 +414,7 @@ function describe(outcome: DispatchOutcome, issue: string): string {
 	if (outcome.kind === 'unrecordable') return outcome.reason
 
 	if (outcome.kind === LABEL_UNSET_KIND) {
-		return `The child for #${issue} was not started: the \`${IN_PROGRESS_LABEL}\` label could not be applied, so the lane would be counted as empty. Nothing was launched.`
+		return `The child for #${issue} was not started: the \`${IN_PROGRESS_LABEL}\` label could not be applied (${outcome.reason}), so the lane would be counted as empty. Nothing was launched.`
 	}
 
 	if (outcome.kind === 'failed') {

package/scripts/lane/lane-environment.ts

@@ -185,9 +185,13 @@ function replace_assignment(
 	key: string,
 ): Array<string> {
 	return lines.flatMap((entry, index) => {
+		// One return type across the branches (sonarjs/function-return-type) keeps the array wrappers.
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
 		if (index === keep) return [assignment]
+		if (is_key_line(entry, key)) return []
 
-		return is_key_line(entry, key) ? [] : [entry]
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
+		return [entry]
 	})
 }
 

package/scripts/lane/lane-handoff.ts

@@ -1,5 +1,5 @@
 import { git_common_directory } from '#scripts/git/git-common-directory'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { lane_child_marker, type MarkerSource } from './lane-child-marker'
 
 // Whether a lane has handed its post-implementation region to the detached ship (joshuafolkken/kit#2962).

package/scripts/lane/lane-install.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { buffered_process } from '#scripts/lib/buffered-process'
+import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 
 // Filling the lane, which is the other half of opening one (joshuafolkken/kit#1554).
 //
@@ -34,12 +35,6 @@ const MANIFEST_FILE_NAME = 'package.json'
 // The lane opens with no dependencies installed, and that is the reported state rather than a
 // failure — there was nothing to install, so nothing failed.
 const NO_MANIFEST_OUTPUT = `No ${MANIFEST_FILE_NAME} in the lane, so the dependency install was skipped.`
-// The 3.5 s above is a warm store; a first run, or one after a dependency change, goes to the
-// network, so that figure is not the bound to write here. Ten minutes covers that fetch and still
-// ends `lane:open` when a registry never answers, rather than holding a parallel run open with
-// nothing printed. It is well under the fan-out's own half hour because this one blocks a command a
-// person is waiting on, not a check suite.
-const INSTALL_TIMEOUT_MS = 600_000
 
 interface InstallResult {
 	is_installed: boolean
@@ -85,10 +80,4 @@ async function install_dependencies(directory: string): Promise<InstallResult> {
 const lane_install = { install_dependencies }
 
 export type { InstallResult }
-export {
-	lane_install,
-	INSTALL_ARGUMENTS,
-	INSTALL_TIMEOUT_MS,
-	MANIFEST_FILE_NAME,
-	NO_MANIFEST_OUTPUT,
-}
+export { lane_install, INSTALL_ARGUMENTS, MANIFEST_FILE_NAME, NO_MANIFEST_OUTPUT }

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { josh_command } from '#scripts/josh/josh-run'
-import { lane_registry } from '#scripts/lane/lane-registry'
+import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
+import { lane_vacant } from '#scripts/lane/lane-vacant'
 import { cli_flags } from '#scripts/lib/cli-flags'
 import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
@@ -88,17 +89,30 @@ type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } |
 const UNOPENED: LaunchOutcome = { kind: 'unopened' }
 const FAILED: LaunchOutcome = { kind: 'failed' }
 
+async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
+	if (lane === undefined || !(await lane_vacant.is_vacant(lane))) return
+
+	await josh_command.josh_run(['lane:close', lane.issue], should_forward_stderr)
+}
+
 // **A lane a park kept open is resumed, not reopened** (joshuafolkken/kit#3228). A child parked before
 // its commit leaves its uncommitted work in its lane, and `lane:open` refuses that lane as
 // `already-open` — so the released child is dispatched into the kept tree instead. **Only a lane a
 // child was already dispatched into counts as kept**: `lane:dispatch` records the child's output in the
 // lane's `.env`, and a lane whose install failed never got that far, so it still goes through
 // `lane:open` and its refusal. So does a stranded lane, whose `.env` is gone with its tree.
+//
+// **A lane no child was dispatched into and that holds nothing is closed and opened afresh**
+// (joshuafolkken/kit#3289) — a run cut between the open and the dispatch leaves one. It is reopened
+// rather than reused because nothing recorded whether its install finished. A lane with work or a live
+// process in it still meets `lane:open`'s refusal.
 async function lane_directory(issue: string): Promise<string | undefined> {
 	const kept = await lane_registry.find_open_lane(issue)
 
 	if (kept?.output !== undefined) return kept.directory
 
+	await close_if_vacant(kept)
+
 	const opened = await josh_command.josh_run(['lane:open', issue], should_forward_stderr)
 
 	return opened.code === SUCCESS_EXIT_CODE ? opened.out : undefined

package/scripts/lane/lane-ledger.ts

@@ -0,0 +1,145 @@
+import { closeSync, constants, openSync, writeSync } from 'node:fs'
+import { stamp_file } from '#scripts/josh/stamp-file'
+import { json_value } from '#scripts/lib/json-value'
+import { run_carry } from '#scripts/run/carry/run-carry'
+import { z } from 'zod'
+
+// 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`.
+//
+// **Its own file rather than the run's event stream.** The stream is capped at 500 events and is
+// rewritten whole on every append, which is right for "where is the run" and wrong for a measurement
+// that spans days of one-a-minute load samples. This file is only ever appended to, so concurrent lanes
+// never lose each other's lines to a read-modify-write race.
+//
+// **Keyed on the common git directory, the event stream's key**, so a lane child's gate, the parent's
+// merge and the sampler all land in one ledger per repository. It sits in the temp root beside every
+// other josh record; a reboot clears it, which is why `docs/maintainers/lane-limit-measurement.md`
+// closes a period with `josh lane:stats` before one.
+
+const LEDGER_PREFIX = 'josh-lane-ledger-'
+const LEDGER_SUFFIX = '.jsonl'
+const LINE_SEPARATOR = '\n'
+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 merge_schema = z.object({ kind: z.literal(KIND.MERGE), at: z.string(), issue: z.number() })
+const gate_schema = z.object({
+	kind: z.literal(KIND.GATE),
+	at: z.string(),
+	elapsed_ms: z.number(),
+	is_passed: z.boolean(),
+})
+// `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.
+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(),
+	lanes: z.number().optional(),
+})
+const entry_schema = z.discriminatedUnion('kind', [merge_schema, gate_schema, load_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>
+
+function target_of(repository: string): string {
+	return stamp_file.stamp_path(LEDGER_PREFIX, repository, LEDGER_SUFFIX)
+}
+
+// The ledger of the repository this checkout belongs to, or `undefined` outside one. `git rev-parse`
+// rejects outside a repository, and `josh gate` resolves this before it runs a check, so the rejection
+// is read as "no ledger" rather than allowed to fail the gate it would only have measured.
+async function target(): Promise<string | undefined> {
+	try {
+		const repository = await run_carry.repository_directory()
+
+		return repository === undefined ? undefined : target_of(repository)
+	} catch {
+		return undefined
+	}
+}
+
+// **Append, never rewrite** — `O_APPEND` keeps each short line whole across concurrent writers, and
+// `O_NOFOLLOW` plus `stamp_file`'s ownership test keep a planted link or another account's file from
+// receiving it.
+function append(path: string, entry: LedgerEntry): void {
+	const descriptor = openSync(path, APPEND_FLAGS, LEDGER_FILE_MODE)
+
+	try {
+		if (stamp_file.is_own_regular_file(path)) {
+			writeSync(descriptor, `${JSON.stringify(entry)}${LINE_SEPARATOR}`)
+		}
+	} finally {
+		closeSync(descriptor)
+	}
+}
+
+// Best-effort: a measurement must never fail the gate or the merge it measures, so every error — no
+// repository, an unwritable temp root — is dropped.
+async function record(entry: LedgerEntry, path?: string): Promise<void> {
+	try {
+		const destination = path ?? (await target())
+
+		if (destination !== undefined) append(destination, entry)
+	} catch {
+		// Reporting is best-effort: a failed append is dropped rather than raised into the caller's work.
+	}
+}
+
+function now_iso(): string {
+	return new Date().toISOString()
+}
+
+// One finished `josh gate`, whether it passed or not — a failing gate cost the lane its time as well.
+async function record_gate(path: string, elapsed_ms: number, is_passed: boolean): Promise<void> {
+	await record({ kind: KIND.GATE, at: now_iso(), elapsed_ms, is_passed }, path)
+}
+
+async function record_merge(issue: number): Promise<void> {
+	await record({ kind: KIND.MERGE, at: now_iso(), issue })
+}
+
+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
+}
+
+// Every entry, oldest first. A malformed line — a write cut short — is skipped rather than making the
+// whole ledger unreadable, and an absent or unowned file is an empty ledger.
+function read_entries(path: string): ReadonlyArray<LedgerEntry> {
+	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)
+}
+
+const lane_ledger = {
+	KIND,
+	append,
+	read_entries,
+	record,
+	record_gate,
+	record_merge,
+	target,
+	target_of,
+}
+
+export type { GateEntry, LedgerEntry, LoadEntry, MergeEntry }
+export { lane_ledger }

package/scripts/lane/lane-leftover.ts

@@ -1,7 +1,9 @@
 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).
 //
@@ -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** (joshuafolkken/kit#3370): 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.
@@ -59,13 +68,18 @@ function walk_files(directory: string, relative: string): Array<string> {
 	return readdirSync(path.join(directory, relative), { withFileTypes: true }).flatMap((entry) => {
 		const child = relative === '' ? entry.name : `${relative}/${entry.name}`
 
-		return entry.isDirectory() ? walk_files(directory, child) : [child]
+		return entry.isDirectory() ? walk_files(directory, child) : child
 	})
 }
 
-// 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-load.ts

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises'
+import { freemem, loadavg } from 'node:os'
+import { execa } from 'execa'
+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.
+//
+// **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 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.
+function count_working(
+	lanes: ReadonlyArray<LaneInfo>,
+	is_running: (issue: string) => boolean = lane_await.is_process_running_default,
+): number {
+	return lanes.filter((lane) => !lane.is_stranded && is_running(lane.issue)).length
+}
+
+async function read_lanes(): Promise<number | undefined> {
+	try {
+		return count_working(await lane_registry.list_lanes())
+	} catch {
+		return undefined
+	}
+}
+
+async function sample(at: string): Promise<LoadEntry> {
+	const [swap_mb, lanes] = await Promise.all([read_swap_mb(), read_lanes()])
+	const [load = 0] = loadavg()
+
+	return {
+		kind: 'load',
+		at,
+		load,
+		free_mb: Math.round(freemem() / BYTES_PER_MB),
+		swap_mb,
+		lanes,
+	}
+}
+
+const lane_load = {
+	count_working,
+	parse_darwin_swap,
+	parse_linux_swap,
+	read_swap_mb,
+	sample,
+}
+
+export { lane_load }