@joshuafolkken/kit 1.1178.0 → 1.1229.0

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 }

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

@@ -0,0 +1,149 @@
+#!/usr/bin/env tsx
+import { setInterval as every } from 'node:timers/promises'
+import { fileURLToPath } from 'node:url'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { lane_capacity } from './lane-capacity'
+import { lane_ledger } from './lane-ledger'
+import { lane_load } from './lane-load'
+import { lane_stats } from './lane-stats'
+
+// `josh lane:sample` / `josh lane:stats` — the lane-limit measurement (joshuafolkken/kit#3355).
+//
+// `lane:sample` appends one machine-load sample to the ledger, or one every `--every <seconds>` until it
+// is stopped; `lane:stats` reduces a period of the ledger to the one table row #3347 records per lane
+// limit. The merges and the gates write themselves (`run:merge`, `josh gate`), so a person runs only
+// the sampler beside a `backlogrun` and closes the period with `lane:stats`. The procedure is
+// `docs/maintainers/lane-limit-measurement.md`.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const MS_PER_SECOND = 1000
+const SAMPLE_VERB = 'sample'
+const STATS_VERB = 'stats'
+const USAGE = [
+	'Usage: josh lane:sample [--every <seconds>]',
+	'       josh lane:stats --period <days> [--limit <lane-limit>]',
+].join('\n')
+
+const SAMPLE_OPTIONS = { every: { type: 'string' } } as const
+const STATS_OPTIONS = { period: { type: 'string' }, limit: { type: 'string' } } as const
+
+// Where the ledger is and what "now" is, overridable so a test reads a fixed ledger at a fixed instant.
+interface MeasureContext {
+	ledger_path?: string
+	now_ms?: number
+}
+
+function refuse(): number {
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+// A positive finite number, or `undefined` for anything else — a typo must not become a zero period.
+function positive(text: string | undefined): number | undefined {
+	const value = Number(text)
+
+	return text !== undefined && Number.isFinite(value) && value > 0 ? value : undefined
+}
+
+async function take_sample(context: MeasureContext): Promise<void> {
+	const at = new Date(context.now_ms ?? Date.now()).toISOString()
+
+	await lane_ledger.record(await lane_load.sample(at), context.ledger_path)
+}
+
+// The `--every` interval: `{ seconds: undefined }` for a single sample, `undefined` for a refusal.
+function sample_interval(rest: ReadonlyArray<string>): { seconds: number | undefined } | undefined {
+	const values = cli_flags.values_of(rest, SAMPLE_OPTIONS)
+
+	if (values === undefined) return undefined
+
+	if (values.every === undefined) return { seconds: undefined }
+
+	const seconds = positive(values.every)
+
+	return seconds === undefined ? undefined : { seconds }
+}
+
+// A sample every `seconds` until a person stops the process, which is how a measurement period is held
+// open; it never returns.
+async function keep_sampling(context: MeasureContext, seconds: number): Promise<void> {
+	const ticks = every(seconds * MS_PER_SECOND, context)
+
+	for await (const tick_context of ticks) await take_sample(tick_context)
+}
+
+// One sample now, then — with `--every` — one per interval.
+async function sample_command(
+	rest: ReadonlyArray<string>,
+	context: MeasureContext,
+): Promise<number> {
+	const interval = sample_interval(rest)
+
+	if (interval === undefined) return refuse()
+
+	await take_sample(context)
+
+	if (interval.seconds !== undefined) await keep_sampling(context, interval.seconds)
+
+	return 0
+}
+
+// The label defaults to the limit this process reads, which is the period's limit only when nobody
+// changed it since — `--limit` names it outright.
+function limit_label(given: string | undefined): string {
+	if (given !== undefined) return given
+
+	const choice = lane_capacity.lane_limit()
+
+	return choice.kind === 'limit' ? String(choice.limit) : lane_stats.MISSING
+}
+
+async function read_ledger(
+	context: MeasureContext,
+): Promise<ReturnType<typeof lane_ledger.read_entries>> {
+	const path = context.ledger_path ?? (await lane_ledger.target())
+
+	return path === undefined ? [] : lane_ledger.read_entries(path)
+}
+
+async function stats_command(
+	rest: ReadonlyArray<string>,
+	context: MeasureContext,
+): Promise<number> {
+	const values = cli_flags.values_of(rest, STATS_OPTIONS)
+	const period_days = positive(values?.period)
+
+	if (values === undefined || period_days === undefined) return refuse()
+
+	const window = lane_stats.window_of(period_days, context.now_ms ?? Date.now())
+	const label = { limit: limit_label(values.limit), period_days }
+	const row = lane_stats.row(await read_ledger(context), window, label)
+
+	console.info(`${lane_stats.header()}\n${row}`)
+
+	return 0
+}
+
+async function run(argv: ReadonlyArray<string>, context: MeasureContext = {}): Promise<number> {
+	const [verb, ...rest] = argv
+
+	if (verb === SAMPLE_VERB) return await sample_command(rest, context)
+
+	return verb === STATS_VERB ? await stats_command(rest, context) : refuse()
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const lane_measure_cli = {
+	USAGE,
+	run,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { MeasureContext }
+export { lane_measure_cli }

package/scripts/lane/lane-occupancy.ts

@@ -82,7 +82,10 @@ function without_label_line(issue: number): string {
 
 function labelled_lines(labelled: ReadonlyArray<LabelledIssue>): Array<string> {
 	return labelled.flatMap((entry) => {
+		// 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 (entry.liveness === 'stopped') return [stopped_line(entry.issue)]
+		// eslint-disable-next-line unicorn/no-unnecessary-array-flat-map -- see above
 		if (entry.liveness === 'unknown') return [unknown_line(entry.issue)]
 
 		return []

package/scripts/lane/lane-reap.ts

@@ -1,4 +1,5 @@
 import { execFileSync } from 'node:child_process'
+import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { lane_child_invocation } from './lane-child-invocation'
 
 // Ending a lane child that did not end itself (joshuafolkken/kit#2421).
@@ -24,9 +25,6 @@ const CHILDREN_OF_FLAG = '-P'
 const PS_COMMAND = '/bin/ps'
 const PARENT_FORMAT = ['-o', 'ppid=', '-p']
 const TERMINATE_SIGNAL = 'SIGTERM'
-// A probe that hung would hang the close it runs inside; failing answers "no process", which leaves
-// the lane exactly as it was before this module existed.
-const PROBE_TIMEOUT_MS = 2000
 // `0` addresses the caller's own process group and `1` is init — neither is ever a lane child.
 const LOWEST_CHILD_PID = 2
 

package/scripts/lane/lane-relaunch.ts

@@ -1,6 +1,6 @@
 import { agent_argv } from '#scripts/agent/agent-argv'
 import { detached_launch, type LaunchResult } from '#scripts/run/detached-launch'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
 import { lane_child_invocation } from './lane-child-invocation'
 import { lane_child_marker } from './lane-child-marker'
 import { lane_dispatch_log } from './lane-dispatch-log'

package/scripts/lane/lane-stats.ts

@@ -0,0 +1,224 @@
+import type { GateEntry, LedgerEntry, LoadEntry } from './lane-ledger'
+
+// The lane-limit measurement's one table row (joshuafolkken/kit#3355): the ledger entries of one period
+// reduced to throughput, gate duration and machine load, in the column order
+// `docs/maintainers/lane-limit-measurement.md` documents, so the row pastes into #3347's table as is.
+//
+// **A column with no samples prints `—`, never `0`.** A period nobody ran the sampler through has no
+// load, which is not a load of zero; a zero would be read as an idle machine.
+//
+// **Throughput is per active hour** — the time load samples saw a lane child working — rather than per
+// calendar hour, so the nights between runs in a several-day period do not dilute the rate. The gaps
+// between work entries cannot stand in for it: at a low limit the gap from one merge to the next child's
+// first gate is a whole implementation, which a gap cap drops, inflating exactly the low limits' rate.
+// Only a period no sample saw working falls back to the gaps of up to an hour between merges and gates.
+//
+// **The means take working samples only** for the same reason: the sampler runs through the nights,
+// and their idle samples would read four busy lanes as about one. Peaks and minima take every sample.
+
+const MS_PER_MINUTE = 60_000
+const MS_PER_HOUR = 3_600_000
+// A busy lane pool finishes a gate well within this; a longer silence is time nobody was running work.
+const ACTIVE_GAP_MS = MS_PER_HOUR
+const MS_PER_DAY = 86_400_000
+const MB_PER_GB = 1024
+const HALF = 2
+const DECIMALS = 1
+const MISSING = '—'
+const CELL_SEPARATOR = ' | '
+
+const COLUMNS = [
+	'JOSH_LANE_LIMIT',
+	'period (days)',
+	'merges',
+	'merges / hour',
+	'effective lanes',
+	'gate median (min)',
+	'gate max (min)',
+	'load peak',
+	'load mean',
+	'swap peak (GB)',
+	'swap mean (GB)',
+	'free memory min (GB)',
+	'free memory mean (GB)',
+	'load samples',
+] as const
+
+interface StatsWindow {
+	since_ms: number
+	until_ms: number
+}
+
+interface RowLabel {
+	limit: string
+	period_days: number
+}
+
+function window_of(period_days: number, now_ms: number): StatsWindow {
+	return { since_ms: now_ms - period_days * MS_PER_DAY, until_ms: now_ms }
+}
+
+function in_window(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): Array<LedgerEntry> {
+	return entries.filter((entry) => {
+		const at = Date.parse(entry.at)
+
+		return at >= window.since_ms && at <= window.until_ms
+	})
+}
+
+function is_gate(entry: LedgerEntry): entry is GateEntry {
+	return entry.kind === 'gate'
+}
+
+function is_load(entry: LedgerEntry): entry is LoadEntry {
+	return entry.kind === 'load'
+}
+
+function is_number(value: number | undefined): value is number {
+	return value !== undefined
+}
+
+function mean(values: ReadonlyArray<number>): number | undefined {
+	if (values.length === 0) return undefined
+
+	return values.reduce((sum, value) => sum + value, 0) / values.length
+}
+
+function median(values: ReadonlyArray<number>): number | undefined {
+	if (values.length === 0) return undefined
+
+	const sorted = values.toSorted((left, right) => left - right)
+	const middle = Math.floor(sorted.length / HALF)
+
+	return sorted.length % HALF === 0 ? mean(sorted.slice(middle - 1, middle + 1)) : sorted[middle]
+}
+
+function peak(values: ReadonlyArray<number>): number | undefined {
+	return values.length === 0 ? undefined : Math.max(...values)
+}
+
+function lowest(values: ReadonlyArray<number>): number | undefined {
+	return values.length === 0 ? undefined : Math.min(...values)
+}
+
+type WorkingEntry = LoadEntry & { lanes: number }
+
+function is_working(sample: LoadEntry): sample is WorkingEntry {
+	return (sample.lanes ?? 0) > 0
+}
+
+function sum_hours(gaps: ReadonlyArray<number>): number | undefined {
+	const active = gaps.filter((gap) => gap <= ACTIVE_GAP_MS).reduce((sum, gap) => sum + gap, 0)
+
+	return active > 0 ? active / MS_PER_HOUR : undefined
+}
+
+// The fallback for a period no sampler saw working: the gaps between consecutive work entries (merges
+// and gates) no longer than `ACTIVE_GAP_MS`.
+function gap_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
+	const instants = entries
+		.filter((entry) => !is_load(entry))
+		.map((entry) => Date.parse(entry.at))
+		.toSorted((left, right) => left - right)
+
+	return sum_hours(
+		instants.slice(1).map((instant, index) => instant - (instants[index] ?? instant)),
+	)
+}
+
+// The time from each working sample to the next sample. The cap still applies, so a sampler stopped
+// mid-run does not count its silence as work.
+function sampled_hours(samples: ReadonlyArray<LoadEntry>): number | undefined {
+	const sorted = samples.toSorted((left, right) => Date.parse(left.at) - Date.parse(right.at))
+	const gaps = sorted
+		.slice(1)
+		.map((next, index) => ({ sample: sorted[index] ?? next, next }))
+		.filter(({ sample }) => is_working(sample))
+		.map(({ sample, next }) => Date.parse(next.at) - Date.parse(sample.at))
+
+	return sum_hours(gaps)
+}
+
+// The hours work was under way; `undefined` when nothing leaves any active time.
+function active_hours(entries: ReadonlyArray<LedgerEntry>): number | undefined {
+	const samples = entries.filter(is_load)
+
+	return samples.some((sample) => is_working(sample)) ? sampled_hours(samples) : gap_hours(entries)
+}
+
+function gigabytes(megabytes: number | undefined): number | undefined {
+	return megabytes === undefined ? undefined : megabytes / MB_PER_GB
+}
+
+function cell(value: number | undefined): string {
+	return value === undefined ? MISSING : value.toFixed(DECIMALS)
+}
+
+function throughput_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
+	const merges = entries.filter((entry) => entry.kind === 'merge').length
+	const hours = active_hours(entries)
+	const lanes = entries
+		.filter(is_load)
+		.filter(is_working)
+		.map((entry) => entry.lanes)
+	const per_hour = hours === undefined ? undefined : merges / hours
+
+	return [String(merges), cell(per_hour), cell(mean(lanes))]
+}
+
+function gate_cells(entries: ReadonlyArray<LedgerEntry>): Array<string> {
+	const minutes = entries.filter(is_gate).map((entry) => entry.elapsed_ms / MS_PER_MINUTE)
+
+	return [cell(median(minutes)), cell(peak(minutes))]
+}
+
+function load_cells(samples: ReadonlyArray<LoadEntry>): Array<string> {
+	const working = samples.filter(is_working)
+	const swap = samples.map((sample) => sample.swap_mb).filter(is_number)
+	const working_swap = working.map((sample) => sample.swap_mb).filter(is_number)
+	const free = samples.map((sample) => sample.free_mb)
+	const working_free = working.map((sample) => sample.free_mb)
+
+	return [
+		cell(peak(samples.map((sample) => sample.load))),
+		cell(mean(working.map((sample) => sample.load))),
+		cell(gigabytes(peak(swap))),
+		cell(gigabytes(mean(working_swap))),
+		cell(gigabytes(lowest(free))),
+		cell(gigabytes(mean(working_free))),
+		String(samples.length),
+	]
+}
+
+function to_row(cells: ReadonlyArray<string>): string {
+	return `| ${cells.join(CELL_SEPARATOR)} |`
+}
+
+function header(): string {
+	return [to_row(COLUMNS), to_row(COLUMNS.map(() => '---'))].join('\n')
+}
+
+// The period's row: `entries` is the whole ledger, filtered here to `window`.
+function row(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow, label: RowLabel): string {
+	const period = in_window(entries, window)
+
+	return to_row([
+		label.limit,
+		String(label.period_days),
+		...throughput_cells(period),
+		...gate_cells(period),
+		...load_cells(period.filter(is_load)),
+	])
+}
+
+const lane_stats = {
+	COLUMNS,
+	MISSING,
+	header,
+	median,
+	row,
+	window_of,
+}
+
+export type { RowLabel, StatsWindow }
+export { lane_stats }

package/scripts/lane/lane-vacant.ts

@@ -0,0 +1,36 @@
+import { git_command } from '#scripts/git/git-command'
+import { run_hold } from '#scripts/run/hold/run-hold'
+import { lane_await } from './lane-await'
+import type { LaneInfo } from './lane-registry'
+
+// Whether an open lane holds nothing worth keeping (joshuafolkken/kit#3289): no commit on its branch
+// beyond the default branch, a clean work tree, and no child or ship supervisor alive for its issue. A
+// `backlogrun` cut between `lane:open` and `lane:dispatch` leaves exactly such a lane, and `lane:open`
+// refuses it as `already-open` — so the next launch of that issue failed on a lane with nothing in it.
+//
+// **Every unreadable answer is "not vacant"**: `is_tree_dirty` already reads an unreadable status as
+// dirty, and a branch whose commits cannot be counted is kept rather than closed, because closing it
+// deletes the branch and anything on it.
+async function has_no_commits(lane: LaneInfo): Promise<boolean> {
+	try {
+		const base = await git_command.default_branch_reference()
+
+		return (await git_command.commit_count_beyond(base, lane.branch)) === 0
+	} catch {
+		return false
+	}
+}
+
+function is_occupied(lane: LaneInfo): boolean {
+	return lane.is_stranded || lane_await.is_process_running_default(lane.issue)
+}
+
+async function is_vacant(lane: LaneInfo): Promise<boolean> {
+	if (is_occupied(lane) || (await run_hold.is_tree_dirty(lane.directory))) return false
+
+	return await has_no_commits(lane)
+}
+
+const lane_vacant = { is_vacant }
+
+export { lane_vacant }

package/scripts/lane/openai-lane-ship.ts

@@ -1,6 +1,6 @@
 import { setTimeout as sleep } from 'node:timers/promises'
-import { run_ship_detach } from '#scripts/run/run-ship-detach'
-import { run_ship_probe } from '#scripts/run/run-ship-probe'
+import { run_ship_detach } from '#scripts/run/ship/run-ship-detach'
+import { run_ship_probe } from '#scripts/run/ship/run-ship-probe'
 
 const POLL_MS = 250
 type ShipEnding = 'none' | 'success' | 'failed' | 'abnormal'