@joshuafolkken/kit 1.1240.0 → 1.1370.0

package/scripts/lane/lane-install.ts

@@ -3,7 +3,7 @@ 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).
+// Filling the lane, which is the other half of opening one.
 //
 // **A work tree with no `node_modules` is not a lane yet.** A linked work tree starts as a checkout
 // and nothing else, and the lane root is a hidden *sibling* of the repository, so nothing above it
@@ -19,7 +19,7 @@ import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 // The child is spawned through `buffered_process` rather than through `execa` here. What this needs
 // is exactly that module's contract — output buffered rather than inherited, a non-zero exit
 // reported rather than thrown, and a bound on how long the child may hang — and a second copy of it
-// is how a fix to one missed the other before (joshuafolkken/kit#914).
+// is how a fix to one missed the other before.
 
 // `--frozen-lockfile` because a lane is cut from `refs/remotes/origin/<default>` and has to build
 // exactly the lock committed there. A lock the install would rather rewrite is a finding, not
@@ -27,8 +27,8 @@ import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 const INSTALL_ARGUMENTS = ['install', '--frozen-lockfile']
 // The manifest whose absence is the whole skip condition. A lane cut from a repository that has no
 // `package.json` has nothing to install, so running `pnpm install` there could only fail on a
-// manifest that was never there — which is exactly the fixture a cross-process lane test needs
-// (joshuafolkken/kit#2148). The condition is strictly "the file does not exist": a manifest that is
+// manifest that was never there — which is exactly the fixture a cross-process lane test needs.
+// The condition is strictly "the file does not exist": a manifest that is
 // present but unreadable or broken still runs the install and still fails as before, so a genuinely
 // broken repository is never passed silently.
 const MANIFEST_FILE_NAME = 'package.json'
@@ -46,10 +46,9 @@ interface InstallResult {
 
 // A lane with no manifest has nothing to install, so the install is skipped rather than run — the
 // seam a cross-process lane test needs, and a root-cause fix rather than a switch, because running
-// an install with no install target was the defect (joshuafolkken/kit#2148). The condition is
-// strictly the file's absence: `existsSync` answers only whether the path is there, never whether
-// its contents parse, so a present-but-broken manifest falls through to the real install and fails
-// exactly as before.
+// an install with no install target is the defect. The condition is strictly the file's absence:
+// `existsSync` answers only whether the path is there, never whether its contents parse, so a
+// present-but-broken manifest falls through to the real install and fails there.
 function has_manifest(directory: string): boolean {
 	return existsSync(path.join(directory, MANIFEST_FILE_NAME))
 }
@@ -58,12 +57,12 @@ function has_manifest(directory: string): boolean {
  * Install the lane's dependencies, and report whether it worked rather than throwing.
  *
  * **A lane with no `package.json` skips the install** — there is nothing to install, so the reported
- * state is installed rather than failed, and no child is spawned (joshuafolkken/kit#2148). This is
+ * state is installed rather than failed, and no child is spawned. This is
  * the only seam: the production call path, its arguments and its environment are all unchanged.
  *
  * **The verdict is the exit code and only the exit code.** `pnpm install` runs `prepare`, which runs
  * the lefthook installer, and in a linked work tree the hooks are shared with the primary repository
- * — so a warning from it is expected and correct (joshuafolkken/kit#1503, #1507). Reading the child's
+ * — so a warning from it is expected and correct. Reading the child's
  * text for a word like "failed" would turn that correct warning into a refusal to open a lane.
  */
 async function install_dependencies(directory: string): Promise<InstallResult> {

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

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { josh_command } from '#scripts/josh/josh-run'
 import { lane_registry, type LaneInfo } from '#scripts/lane/lane-registry'
 import { lane_vacant } from '#scripts/lane/lane-vacant'
@@ -8,7 +9,7 @@ import { INSTALL_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 
 // `josh lane:launch <issue> [--stash <message>]` — one composite command for a `backlogrun` lane-start
-// event (joshuafolkken/kit#2162). Opening one lane was four to six turns of the parent: `lane:open`,
+// event. Opening one lane was four to six turns of the parent: `lane:open`,
 // then — only the first lane, and only when `josh latest` had stashed — `stash:pop` and a re-install,
 // then `lane:dispatch`. This collapses them into one call that returns the child's pid, or a refusal,
 // the same shape `lane:dispatch` alone has.
@@ -24,7 +25,6 @@ const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const should_forward_stderr = true
 const PNPM = 'pnpm'
-const ISSUE_PATTERN = /^[1-9]\d*$/u
 
 const USAGE = 'Usage: josh lane:launch <issue-number> [--stash <message>]'
 
@@ -44,7 +44,13 @@ function read_context(argv: ReadonlyArray<string>): LaunchContext | undefined {
 
 	const [issue, ...rest] = parsed.positionals
 
-	if (issue === undefined || rest.length > 0 || !ISSUE_PATTERN.test(issue)) return undefined
+	if (
+		issue === undefined ||
+		rest.length > 0 ||
+		!issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue)
+	) {
+		return undefined
+	}
 
 	return { issue, stash: parsed.values.stash }
 }
@@ -82,8 +88,7 @@ async function prepare(stash: string | undefined, directory: string): Promise<bo
 }
 
 // Where the chain ended. `unopened` is a `lane:open` refusal — no lane was taken; `failed` is a step
-// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike
-// (joshuafolkken/kit#3027).
+// after it, which leaves the opened lane holding a seat, so a caller cannot read the two alike.
 type LaunchOutcome = { kind: 'launched'; pid: string } | { kind: 'unopened' } | { kind: 'failed' }
 
 const UNOPENED: LaunchOutcome = { kind: 'unopened' }
@@ -95,7 +100,7 @@ async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
 	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
+// **A lane a park kept open is resumed, not reopened**. 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
@@ -103,7 +108,7 @@ async function close_if_vacant(lane: LaneInfo | undefined): Promise<void> {
 // `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
+// — 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> {
@@ -119,7 +124,7 @@ async function lane_directory(issue: string): Promise<string | undefined> {
 }
 
 // The launch chain in-process. The CLI prints the pid; `backlog:drive` launches through this same
-// chain (joshuafolkken/kit#2508).
+// chain.
 async function launch_lane(context: LaunchContext): Promise<LaunchOutcome> {
 	const directory = await lane_directory(context.issue)
 

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

@@ -5,7 +5,7 @@ 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 —
@@ -15,7 +15,7 @@ import { IGNORED_CACHE_FILES } from '#scripts/josh/josh-command-types'
 // **The test for removing it is that removing it loses nothing**, not a list of names. Every file in
 // 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
+// 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

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