@joshuafolkken/kit 1.1471.0 → 1.1784.0

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

@@ -1,80 +1,168 @@
 import { run_board_labels } from './run-board-labels'
-import { run_board_machine } from './run-board-machine'
-import type { LaneUsage } from './run-board-usage'
-
-// A running row's CPU and memory column: `⚡ 20% 🧠1.6G`, each figure green, yellow or red in the
-// header gauges' `GAUGE_SHADES`. **A lane's thresholds are its share of what the running lanes may
-// use together**: the header's yellow threshold (`CPU_YELLOW` / `MEMORY_YELLOW`), never the whole
-// machine — the OS, the IDE and the browser always hold some of it — divided by the running rows the
-// frame draws. A lane turns yellow at three quarters of its share and red past the share itself — on
-// an 18 GB machine at 3.2 and 4.2 GB with three lanes running, 1.2 and 1.6 GB with eight. One lane's
-// share is the header's own threshold, so it takes no color the header gauge would not; a lane that
-// ends widens the others' shares, and their colors may turn back.
-
-const { GAUGE_SHADES, HEADER_ICONS, minute_of, painted } = run_board_labels
-const { CPU_YELLOW, MEMORY_YELLOW, percent_text, threshold_alert } = run_board_machine
-const YELLOW_OF_SHARE = 0.75
+import { run_board_machine, type Alert } from './run-board-machine'
+import type { UsageFigure, UsageScale } from './run-board-usage'
+
+// The CPU, memory and compressed-memory cells a lane row and a processes row draw: each a figure and a
+// gauge, `16.4 ■─────` / ` 0.7 ■────`, a processes row's gauge full at the whole machine — the header's
+// 💪 and 🧠 scale — a lane row's at its share (joshuafolkken/kit#4546), and its color the header gauges' own `GAUGE_SHADES`. CPU is a percentage of the whole
+// machine, the header's 💪 unit, and memory is in GB; the column labels name neither unit.
+//
+// **A lane row's gauge is full at its share of what the running lanes may use together**
+// (joshuafolkken/kit#3612): the header's yellow threshold (`CPU_YELLOW` / `MEMORY_YELLOW`), never the
+// whole machine — the OS, the IDE and the browser always hold some of it — divided by the running rows
+// the frame draws. A lane that ends widens the others' shares, and their gauges may shrink.
+//
+// **Both rows are shaded at the same two points of their full gauge** (joshuafolkken/kit#4570): yellow
+// past half, red past nine tenths, so the third cell reads yellow and the fifth red. The header's own
+// thresholds shade the header alone.
+
+const { GAUGE_SHADES, bar_of } = run_board_labels
+const { CPU_YELLOW, MEMORY_YELLOW } = run_board_machine
+const ROW_YELLOW_OF_FULL = 50
+const ROW_RED_OF_FULL = 90
 const BYTES_PER_KB = 1024
 const BYTES_PER_GB = BYTES_PER_KB * BYTES_PER_KB * BYTES_PER_KB
-const GB_DECIMALS = 1
-const PART_GAP = ' '
+const PERCENT = 100
+const DECIMALS = 1
+const FIGURE_WIDTH = '99.9'.length
+const GB_UNIT = 'G'
+const PERCENT_UNIT = '%'
+const CELL_GAP = ' '
+const PLAIN_GAP = '/'
+const NO_CORES = '-'
+
+// Where a row's gauges are full, in percent of the machine: the CPU's, then both memories'.
+interface CellLimits {
+	cpu: number
+	memory: number
+}
 
-type Shade = (typeof GAUGE_SHADES)[keyof typeof GAUGE_SHADES]
+const MACHINE_LIMITS: CellLimits = { cpu: PERCENT, memory: PERCENT }
 
-// A running lane's thresholds, in percent of the machine: its share of `pool_percent` among `running`.
-function lane_thresholds(pool_percent: number, running: number): { yellow: number; red: number } {
-	const share = pool_percent / Math.max(1, running)
+// The gauge is drawn full at `full`, and shaded at its fill.
+interface Cell {
+	text: string | undefined
+	value: number
+	full: number
+}
 
-	return { yellow: share * YELLOW_OF_SHARE, red: share }
+function gigabytes(bytes: number): string {
+	return (bytes / BYTES_PER_GB).toFixed(DECIMALS)
 }
 
-function shade_of(percent: number, pool_percent: number, running: number): Shade {
-	return GAUGE_SHADES[threshold_alert(percent, lane_thresholds(pool_percent, running))]
+function share_of(value: number, full: number): number {
+	return full === 0 ? 0 : (value / full) * PERCENT
 }
 
-// The first sample has no CPU figure, so a row draws its memory alone until the second.
-function cpu_part(cpu_percent: number | undefined, running: number): string | undefined {
-	if (cpu_percent === undefined) return undefined
+// The cores as a percentage of the machine's, `56.4`; a full machine is `100`, so the figure stays as
+// wide as `99.9`.
+function cpu_text(cores: number | undefined, scale: UsageScale): string | undefined {
+	if (cores === undefined) return undefined
 
-	const shade = shade_of(cpu_percent, CPU_YELLOW, running)
+	const text = share_of(cores, scale.cores).toFixed(DECIMALS)
 
-	return `${HEADER_ICONS.cpu}${painted(shade, percent_text(cpu_percent))}`
+	return Number(text) >= PERCENT ? String(PERCENT) : text
 }
 
-function memory_part(usage: LaneUsage, running: number): string {
-	const figure = `${(usage.memory_bytes / BYTES_PER_GB).toFixed(GB_DECIMALS)}G`
-	const shade = shade_of(usage.memory_percent, MEMORY_YELLOW, running)
+// The columns a gauge takes after its figure — none where no gauge is drawn.
+function gauge_width(gauge: number): number {
+	return gauge === 0 ? 0 : CELL_GAP.length + gauge
+}
 
-	return `${HEADER_ICONS.memory}${painted(shade, figure)}`
+// A row gauge's color at `percent` of its full: yellow past half, red past nine tenths, each line itself
+// still the color below it.
+function row_alert(percent: number): Alert {
+	if (percent > ROW_RED_OF_FULL) return 'red'
+
+	return percent > ROW_YELLOW_OF_FULL ? 'yellow' : 'normal'
 }
 
-// `undefined` for a lane no process was found under; `running` is the frame's running rows.
-function text_of(usage: LaneUsage | undefined, running: number): string | undefined {
-	if (usage === undefined) return undefined
+function cell_text(cell: Cell, width: number, gauge: number): string {
+	if (cell.text === undefined) return CELL_GAP.repeat(width + gauge_width(gauge))
+
+	const figure = cell.text.padStart(width)
 
-	return [cpu_part(usage.cpu_percent, running), memory_part(usage, running)]
-		.filter((part) => part !== undefined)
-		.join(PART_GAP)
+	if (gauge === 0) return figure
+
+	const shade = GAUGE_SHADES[row_alert(share_of(cell.value, cell.full))]
+
+	return `${figure}${CELL_GAP}${bar_of(cell.value, cell.full, gauge, shade)}`
 }
 
-// The day a settled row finished, `10/8 `, where that is not the board's own day.
-function day_of(ended_ms: number, now_ms: number): string {
-	const ended = new Date(ended_ms)
+// A running lane's share, in percent of the machine: `pool_percent` divided among `running`.
+function lane_share(pool_percent: number, running: number): number {
+	return pool_percent / Math.max(1, running)
+}
 
-	if (ended.toDateString() === new Date(now_ms).toDateString()) return ''
+// A lane row's limits with `running` lanes drawn: each gauge full at its share of the header's yellow
+// threshold (joshuafolkken/kit#4546).
+function lane_limits(running: number): CellLimits {
+	return { cpu: lane_share(CPU_YELLOW, running), memory: lane_share(MEMORY_YELLOW, running) }
+}
 
-	return `${String(ended.getMonth() + 1)}/${String(ended.getDate())} `
+function cell_of(text: string | undefined, value: number, full: number): Cell {
+	return { text, value, full }
 }
 
-// A settled row's finish time, drawn in the usage column: `🔚 14:05`, or
-// `🔚 10/8 14:05` on another day; `undefined` for a row settled with no recorded end. 🔚 is the
-// header's own end mark — 🏁 is already a done row's state icon.
-function finish_of(ended_ms: number | undefined, now_ms: number): string | undefined {
-	if (ended_ms === undefined) return undefined
+function cells_from(figure: UsageFigure, scale: UsageScale, limits: CellLimits): Array<Cell> {
+	const { cpu_cores, memory_bytes, compressed_bytes } = figure
+	const cores = (scale.cores * limits.cpu) / PERCENT
+	const bytes = (scale.total_bytes * limits.memory) / PERCENT
 
-	return `${HEADER_ICONS.ended} ${day_of(ended_ms, now_ms)}${minute_of(ended_ms)}`
+	return [
+		cell_of(cpu_text(cpu_cores, scale), cpu_cores ?? 0, cores),
+		cell_of(gigabytes(memory_bytes), memory_bytes, bytes),
+		cell_of(gigabytes(compressed_bytes), compressed_bytes, bytes),
+	]
 }
 
-const run_board_usage_text = { finish_of, lane_thresholds, text_of }
+// Each cell's width before its gauge: the CPU's text, then the two memories'.
+function text_widths(): Array<number> {
+	return [FIGURE_WIDTH, FIGURE_WIDTH, FIGURE_WIDTH]
+}
+
+// Each cell's width in columns, so a heading can put a column's label over it.
+function cell_widths(gauge: number): Array<number> {
+	return text_widths().map((width) => width + gauge_width(gauge))
+}
+
+// The CPU, MEM and CMPRS cells, each `gauge` columns of bar after its figure — the figure alone at a
+// `gauge` of 0, where a frame is not drawn on a terminal; a row with no figure, or
+// a figure from the first sample with no CPU yet, draws blanks of the same width in the cell it lacks.
+// Filled and shaded at `limits`, the whole machine's unless a lane row passes its share.
+function cells_of(
+	figure: UsageFigure | undefined,
+	scale: UsageScale,
+	gauge: number,
+	limits: CellLimits = MACHINE_LIMITS,
+): Array<string> {
+	if (figure === undefined) return cell_widths(gauge).map((width) => CELL_GAP.repeat(width))
+
+	const widths = text_widths()
+
+	return cells_from(figure, scale, limits).map((cell, index) =>
+		cell_text(cell, widths[index] ?? 0, gauge),
+	)
+}
+
+// A figure on one line where no gauge is drawn, and so no column label names the units:
+// `56.4%/0.7G/0.6G`, `-` for cores not read yet.
+function plain_of(figure: UsageFigure, scale: UsageScale): string {
+	const cpu = cpu_text(figure.cpu_cores, scale)
+	const memories = [figure.memory_bytes, figure.compressed_bytes].map(
+		(bytes) => `${gigabytes(bytes)}${GB_UNIT}`,
+	)
+
+	return [cpu === undefined ? NO_CORES : `${cpu}${PERCENT_UNIT}`, ...memories].join(PLAIN_GAP)
+}
+
+const run_board_usage_text = {
+	cell_widths,
+	cells_of,
+	lane_limits,
+	lane_share,
+	plain_of,
+}
 
 export { run_board_usage_text }
+export type { CellLimits }

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

@@ -0,0 +1,102 @@
+import { execa } from 'execa'
+
+// Each process's memory and compressed memory as `top`'s MEM and CMPRS count them — the columns
+// Activity Monitor's "Memory" and "Compressed Memory" show. Compressed pages are what a resident set
+// leaves out: `eslint_d` holds about 28 MB resident against 1 GB in `top`'s MEM (joshuafolkken/kit#4171).
+// **CMPRS has no cheaper reader**: `proc_pid_rusage` carries the footprint (MEM) but no compressed
+// count, and `top -l 1` costs about 1.1 s of system CPU against `ps`'s 30 ms. So `top` runs at most once
+// every 30 s, in the background, and the board draws the last reading; only the very first read waits.
+
+const TOP_ARGUMENTS = ['-l', '1', '-F', '-R', '-stats', 'pid,mem,cmprs']
+const TOP_INTERVAL_MS = 30_000
+// `top -l 1` samples for about a second and lists every process; `PROBE_TIMEOUT_MS` is sized for `ps`.
+const TOP_TIMEOUT_MS = 10_000
+const BYTES_PER_UNIT = 1024
+// `top`'s size units, each 1024 times the one before.
+const SIZE_UNITS = ['B', 'K', 'M', 'G', 'T']
+// A size such as `3904K`, `154M+` or `1.2G-` — the sign marks a change since the last sample.
+const SIZE_PATTERN = /^(\d+(?:\.\d+)?)([BKMGT])[+-]?$/u
+const TOP_LINE = /^\s*(\d+)\s+(\S+)\s+(\S+)\s*$/u
+
+interface TopReading {
+	memory_bytes: number
+	compressed_bytes: number
+}
+
+// Each process's `top` reading by its pid.
+type TopReadings = ReadonlyMap<number, TopReading>
+
+interface TopPorts {
+	// `top`'s one-sample listing.
+	list: () => Promise<string>
+	now: () => number
+}
+
+// `NaN` for a field that is not a size, such as the `MEM` column heading.
+function bytes_of(text = ''): number {
+	const [, amount, unit = ''] = SIZE_PATTERN.exec(text) ?? []
+
+	return Number(amount) * BYTES_PER_UNIT ** SIZE_UNITS.indexOf(unit)
+}
+
+function top_line(line: string): [number, TopReading] | undefined {
+	const [, pid, memory, compressed] = TOP_LINE.exec(line) ?? []
+	const reading = { memory_bytes: bytes_of(memory), compressed_bytes: bytes_of(compressed) }
+
+	if (Number.isNaN(reading.memory_bytes + reading.compressed_bytes)) return undefined
+
+	return [Number(pid), reading]
+}
+
+function parse_top(output: string): Map<number, TopReading> {
+	const lines = output.split('\n').map((line) => top_line(line))
+
+	return new Map(lines.filter((line) => line !== undefined))
+}
+
+interface TopHeld {
+	readings: TopReadings | undefined
+	read_ms: number
+	pending: Promise<TopReadings> | undefined
+}
+
+// A read that fails keeps the earlier readings, and an empty map where there were none.
+async function refreshed(held: TopHeld, ports: TopPorts): Promise<TopReadings> {
+	try {
+		held.readings = parse_top(await ports.list())
+	} catch {
+		held.readings ??= new Map()
+	} finally {
+		held.pending = undefined
+	}
+
+	return held.readings
+}
+
+// The last reading, with a fresh `top` started in the background once it is `TOP_INTERVAL_MS` old;
+// only the first read, which has none to draw, waits for it.
+function top_reader(ports: TopPorts): () => Promise<TopReadings> {
+	const held: TopHeld = { readings: undefined, read_ms: -Infinity, pending: undefined }
+
+	async function read(): Promise<TopReadings> {
+		if (held.pending === undefined && ports.now() - held.read_ms >= TOP_INTERVAL_MS) {
+			held.read_ms = ports.now()
+			held.pending = refreshed(held, ports)
+		}
+
+		return held.readings ?? (await (held.pending ?? Promise.resolve(new Map())))
+	}
+
+	return read
+}
+
+async function list_top(): Promise<string> {
+	const { stdout } = await execa('top', TOP_ARGUMENTS, { timeout: TOP_TIMEOUT_MS })
+
+	return stdout
+}
+
+const run_board_usage_top = { TOP_INTERVAL_MS, TOP_TIMEOUT_MS, list_top, parse_top, top_reader }
+
+export { run_board_usage_top }
+export type { TopPorts, TopReading, TopReadings }

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

@@ -1,66 +1,61 @@
-// Each lane's CPU and memory on its `run:board` row: which lane is loading the machine the header's ⚡
-// and 🧠 show. How the processes are read is `run-board-usage-read.ts`'s; this file turns two readings
-// into each lane's figures.
+// Each process's CPU, memory and compressed memory on `run:board`: which lane, which part of the
+// backlogrun, or which app outside it is loading the machine the header's 💪 and 🧠 show. How the
+// processes are read is `run-board-usage-read.ts`'s, how they are grouped `run-board-process-groups.ts`'s;
+// this file turns two readings into each process's figures and each lane's sum.
 //
-// A lane's CPU is its processes' CPU time between two samples as a share of the whole machine — the
-// header's ⚡ scale, so the two read side by side, never Activity Monitor's one-core-is-100% — and its
-// memory the sum of their resident sets. Shared pages are counted once per process, so the figure is
-// larger than what the kernel holds; it compares lanes, which is all the column is for.
-
-const PERCENT = 100
+// CPU is a process's CPU time between two samples in cores, drawn as a percentage of the machine's
+// cores — the header's 💪 unit, never Activity Monitor's one-core-is-100% — and memory what `top`'s
+// MEM and CMPRS count, so the figures read the same in the lane rows and the processes section.
 
 interface ProcessReading {
 	cpu_ms: number
-	rss_bytes: number
+	memory_bytes: number
+	compressed_bytes: number
 }
 
 interface UsageMark {
 	at_ms: number
 	processes: ReadonlyMap<number, ProcessReading>
-	// Every listed process's lane, `undefined` for one under none — kept so each is looked up once.
+	// Every listed process's lane — its working directory's, else its nearest ancestor's — `undefined`
+	// for one under none; kept so each directory is looked up once (`run-board-usage-lanes.ts`).
 	lanes: ReadonlyMap<number, string | undefined>
-	// Each process's parent, kept only where the counts fold in the children each reaped — empty on the
-	// `ps` path, so nothing is deducted there.
+	// The processes an `lsof` cut short was asked about, asked again on the next sample.
+	unread: ReadonlySet<number>
+	// Each process's command, which names the app it belongs to.
+	names: ReadonlyMap<number, string>
+	// Each process's parent: the ancestry the processes section groups by, and the way to the ancestor
+	// a gone process's reaped time landed in.
 	parents: ReadonlyMap<number, number>
 	// The processes whose count was read with its reaped children folded in — one whose own read failed
-	// keeps the larger of `ps`'s own time and its last reading, so nothing reaped is taken off it.
+	// keeps the larger of `ps`'s own time and its last reading, so nothing reaped is taken off it. Empty
+	// on the `ps` path, so nothing is deducted there.
 	folded: ReadonlySet<number>
 	cores: number
 	total_bytes: number
 }
 
-// The CPU share is `undefined` on the first sample, which has nothing to take a difference from.
-interface LaneUsage {
-	cpu_percent: number | undefined
+// What one process or group uses. The cores are `undefined` on the first sample, which has nothing to
+// take a difference from.
+interface UsageFigure {
+	cpu_cores: number | undefined
 	memory_bytes: number
-	memory_percent: number
+	compressed_bytes: number
 }
 
-// Each lane's usage by its issue number.
-type LaneUsages = ReadonlyMap<number, LaneUsage>
+// Each process's figure by its pid.
+type ProcessFigures = ReadonlyMap<number, UsageFigure>
 
-interface LaneProcess {
-	lane: string
-	pid: number
-	reading: ProcessReading
-}
+// Each lane's figure by its issue number.
+type LaneUsages = ReadonlyMap<number, UsageFigure>
 
-interface LaneTotal {
-	cpu_ms: number
-	rss_bytes: number
+// The machine's cores and its physical memory: a processes row's gauge is full at them, a lane row's
+// at its share of them.
+interface UsageScale {
+	cores: number
+	total_bytes: number
 }
 
-const NO_TOTAL: LaneTotal = { cpu_ms: 0, rss_bytes: 0 }
-
-function lane_processes(mark: UsageMark): Array<LaneProcess> {
-	const processes = [...mark.processes].map(([pid, reading]) => {
-		const lane = mark.lanes.get(pid)
-
-		return lane === undefined ? undefined : { lane, pid, reading }
-	})
-
-	return processes.filter((lane_process) => lane_process !== undefined)
-}
+const NO_FIGURE: UsageFigure = { cpu_cores: 0, memory_bytes: 0, compressed_bytes: 0 }
 
 // The nearest of a gone process's ancestors still running — the one whose reaped-children time it has
 // landed in. Walked through the last sample's parents, at most once round them. Where a parent between
@@ -101,65 +96,87 @@ function reaped_counted(before: UsageMark, after: UsageMark): Map<number, number
 function cpu_spent(
 	before: UsageMark,
 	counted: ReadonlyMap<number, number>,
-	{ pid, reading }: LaneProcess,
+	pid: number,
+	reading: ProcessReading,
 ): number {
 	const earlier = (before.processes.get(pid)?.cpu_ms ?? 0) + (counted.get(pid) ?? 0)
 
 	return Math.max(0, reading.cpu_ms - earlier)
 }
 
-function spent_of(
+// The cores a process used since the last sample, `undefined` with none to take a difference from.
+function cores_of(
 	before: UsageMark | undefined,
 	after: UsageMark,
-): (process: LaneProcess) => number {
-	if (before === undefined) return () => 0
+): ((pid: number, reading: ProcessReading) => number) | undefined {
+	const elapsed = before === undefined ? 0 : after.at_ms - before.at_ms
+
+	if (before === undefined || elapsed <= 0) return undefined
 
 	const counted = reaped_counted(before, after)
 
-	return (lane_process) => cpu_spent(before, counted, lane_process)
+	return (pid, reading) => cpu_spent(before, counted, pid, reading) / elapsed
+}
+
+function process_figures(
+	before: UsageMark | undefined,
+	after: UsageMark,
+): Map<number, UsageFigure> {
+	const cores = cores_of(before, after)
+	const figures = [...after.processes].map(([pid, reading]) => {
+		const { memory_bytes, compressed_bytes } = reading
+
+		return [pid, { cpu_cores: cores?.(pid, reading), memory_bytes, compressed_bytes }] as const
+	})
+
+	return new Map(figures)
 }
 
-function totals_of(before: UsageMark | undefined, after: UsageMark): Map<string, LaneTotal> {
-	const totals = new Map<string, LaneTotal>()
-	const spent = spent_of(before, after)
+function cores_sum(left: number | undefined, right: number | undefined): number | undefined {
+	return left === undefined || right === undefined ? undefined : left + right
+}
 
-	for (const lane_process of lane_processes(after)) {
-		const total = totals.get(lane_process.lane) ?? NO_TOTAL
+// The figures' sum, its cores `undefined` where any one's are.
+function sum_of(figures: Iterable<UsageFigure>): UsageFigure {
+	let sum = NO_FIGURE
 
-		totals.set(lane_process.lane, {
-			cpu_ms: total.cpu_ms + spent(lane_process),
-			rss_bytes: total.rss_bytes + lane_process.reading.rss_bytes,
-		})
+	for (const figure of figures) {
+		sum = {
+			cpu_cores: cores_sum(sum.cpu_cores, figure.cpu_cores),
+			memory_bytes: sum.memory_bytes + figure.memory_bytes,
+			compressed_bytes: sum.compressed_bytes + figure.compressed_bytes,
+		}
 	}
 
-	return totals
+	return sum
 }
 
-function cpu_percent(
-	before: UsageMark | undefined,
-	after: UsageMark,
-	cpu_ms: number,
-): number | undefined {
-	const elapsed = before === undefined ? 0 : after.at_ms - before.at_ms
+// Each group's sum, the group of each process given by `group_of`; one in none is left out.
+function grouped_sums<Key>(
+	figures: ProcessFigures,
+	group_of: (pid: number) => Key | undefined,
+): Map<Key, UsageFigure> {
+	const sums = new Map<Key, UsageFigure>()
 
-	return elapsed <= 0 ? undefined : (cpu_ms / (elapsed * after.cores)) * PERCENT
-}
+	for (const [pid, figure] of figures) {
+		const group = group_of(pid)
 
-function lane_usage(before: UsageMark | undefined, after: UsageMark, total: LaneTotal): LaneUsage {
-	return {
-		cpu_percent: cpu_percent(before, after, total.cpu_ms),
-		memory_bytes: total.rss_bytes,
-		memory_percent: (total.rss_bytes / after.total_bytes) * PERCENT,
+		if (group !== undefined) sums.set(group, sum_of([sums.get(group) ?? NO_FIGURE, figure]))
 	}
+
+	return sums
 }
 
-function usage_of(before: UsageMark | undefined, after: UsageMark): LaneUsages {
-	const totals = [...totals_of(before, after)]
+function lane_number(lane: string | undefined): number | undefined {
+	return lane === undefined ? undefined : Number(lane)
+}
 
-	return new Map(totals.map(([lane, total]) => [Number(lane), lane_usage(before, after, total)]))
+// Each lane's processes' sum, by each process's lane in `mark.lanes`.
+function usage_of(mark: UsageMark, figures: ProcessFigures): LaneUsages {
+	return grouped_sums(figures, (pid) => lane_number(mark.lanes.get(pid)))
 }
 
-const run_board_usage = { usage_of }
+const run_board_usage = { grouped_sums, process_figures, sum_of, usage_of }
 
 export { run_board_usage }
-export type { LaneUsage, LaneUsages, ProcessReading, UsageMark }
+export type { LaneUsages, ProcessFigures, ProcessReading, UsageFigure, UsageMark, UsageScale }

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

@@ -1,5 +1,6 @@
-import { lane_ledger, type LedgerEntry } from '#scripts/lane/lane-ledger'
+import type { LedgerEntry } from '#scripts/lane/lane-ledger'
 import { lane_stage_stats } from '#scripts/lane/lane-stage-stats'
+import { lane_stats } from '#scripts/lane/lane-stats'
 import { run_board_phase, type Phase } from './run-board-phase'
 
 // How long each phase usually takes: the lane ledger's median of the stage the phase is
@@ -7,10 +8,15 @@ import { run_board_phase, type Phase } from './run-board-phase'
 // (joshuafolkken/kit#3769). A phase is a `josh ship` stage under the names `run-board-phase.ts` gives
 // them, and `implement` is the ledger's derived one. A phase no stage records — `investigate`, `plan`,
 // `failed` — has no usual time, and is never drawn as long.
+//
+// **The median is the recent one** (joshuafolkken/kit#4319): only the last `PERIOD_DAYS` of the
+// ledger count, so a faster season long past never pulls the estimate down; a stage with nothing that
+// recent falls back to the whole ledger's median.
 
 type UsualTimes = ReadonlyMap<Phase, number>
 
 const IMPLEMENT_PHASE: Phase = 'implement'
+const PERIOD_DAYS = 3
 
 // Each phase's ledger stage, from the stage-to-phase names a row's phase is drawn with. The ledger's
 // `implement` runs from the dispatch, so it also holds the investigation and the plan the row draws
@@ -21,8 +27,18 @@ const PHASE_STAGES: ReadonlyArray<readonly [string, Phase | undefined]> = [
 	...Object.entries(run_board_phase.SHIP_PHASES),
 ]
 
-function usual_of(entries: ReadonlyArray<LedgerEntry>): UsualTimes {
-	const medians = lane_stage_stats.medians(entries)
+// Per stage, so a run's first lanes — dispatched, no stage recorded yet — still draw every phase.
+function medians_of(
+	entries: ReadonlyArray<LedgerEntry>,
+	now_ms: number,
+): ReadonlyMap<string, number> {
+	const recent = lane_stats.in_window(entries, lane_stats.window_of(PERIOD_DAYS, now_ms))
+
+	return new Map([...lane_stage_stats.medians(entries), ...lane_stage_stats.medians(recent)])
+}
+
+function usual_of(entries: ReadonlyArray<LedgerEntry>, now_ms: number): UsualTimes {
+	const medians = medians_of(entries, now_ms)
 
 	return new Map(
 		PHASE_STAGES.flatMap(([stage, phase]) => {
@@ -33,12 +49,7 @@ function usual_of(entries: ReadonlyArray<LedgerEntry>): UsualTimes {
 	)
 }
 
-// The repository's whole ledger, read where the board reads its stream; an absent one has no usual time.
-function read(repository: string): UsualTimes {
-	return usual_of(lane_ledger.read_entries(lane_ledger.target_of(repository)))
-}
-
-const run_board_usual = { read, usual_of }
+const run_board_usual = { usual_of }
 
 export { run_board_usual }
 export type { UsualTimes }

package/scripts/run/carry/run-carry-args.ts

@@ -13,7 +13,6 @@ const ONE_MERGE = 1
 // The four request groups below are mutually exclusive, so more than one of them named in a single
 // invocation is a usage error rather than an order to guess.
 const ONE_GROUP = 1
-const COUNT_PATTERN = /^\d+$/u
 const EMPTY_INVOCATION = ''
 // A pid below this addresses a process group rather than a process, which `process-identity.ts`
 // rejects on the read side. Refused here too, so a record never records an owner nothing can be.
@@ -87,7 +86,7 @@ function to_count(value: OptionValue): number | undefined {
 
 	if (text === undefined) return NO_INCREMENT
 
-	return COUNT_PATTERN.test(text) ? Number(text) : undefined
+	return cli_flags.to_count(text)
 }
 
 // **`--done` and `--merged` name an issue, so each is checked as one and not as a count.** The shape
@@ -105,7 +104,7 @@ function to_issue(value: OptionValue): { issue?: number } | undefined {
 	const issue = Number(text)
 
 	// The pattern is anchored on digits and bounds nothing, so the magnitude check is separate — the
-	// same shape `backlog_budget_cli.to_count` ends with. A number past the safe range would be
+	// same shape `cli_flags.to_count` ends with. A number past the safe range would be
 	// recorded as a different number and never match anything in `remaining`.
 	return Number.isSafeInteger(issue) ? { issue } : undefined
 }
@@ -196,11 +195,9 @@ function to_owner(value: OptionValue): CarryOwner | undefined {
 
 	if (text === undefined) return run_carry.NO_OWNER
 
-	if (!COUNT_PATTERN.test(text)) return undefined
+	const pid = cli_flags.to_count(text)
 
-	const pid = Number(text)
-
-	return pid < MIN_PID ? undefined : marked(run_carry.owner_of(pid))
+	return pid === undefined || pid < MIN_PID ? undefined : marked(run_carry.owner_of(pid))
 }
 
 // A non-empty `--summary`, or nothing. An empty string is nothing here, so it reads as absent and the