@joshuafolkken/kit 1.2114.0 → 1.3000.0

package/scripts/lane/lane-plan.ts

@@ -1,9 +1,11 @@
+import fs from 'node:fs'
 import { backlog_overlap, type Clash, type Declared } from '#scripts/backlog/backlog-overlap'
 import { git_common_directory } from '#scripts/git/git-common-directory'
 import { durable_state } from '#scripts/josh/durable-state'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { json_value } from '#scripts/lib/json-value'
 import { z } from 'zod'
+import { lane_plan_approval } from './lane-plan-approval'
 
 // The files a lane child plans to edit, recorded by `josh lane:plan` once its work summary settles.
 //
@@ -22,9 +24,20 @@ const lane_plan_schema = z.object({
 	issue: z.number(),
 	paths: z.array(z.string()),
 	planned_at: z.string(),
+	size_approval: lane_plan_approval.approval_schema.optional(),
+	// `--single`: the plan is one deliverable with no separately-mergeable part, so a files-axis overrun
+	// is noted for the pre-gate `run:cut` to verify rather than refused (joshuafolkken/kit#6647).
+	single: z.boolean().optional(),
 	cleared: z.boolean().optional(),
+	// The plan met the size bar (`lane-plan-size.ts`), whatever the overlap check answered after it.
+	sized: z.boolean().optional(),
 	// The lane gave its lane back on this plan (`lane-yield.ts`), so the plan outlives the lane.
 	yielded: z.boolean().optional(),
+	// When the lane's bounded wait on a later-dispatched holder ends (`lane-plan-wait.ts`), ISO time.
+	waits_until: z.string().optional(),
+	// Every path an earlier cleared plan of this lane held (joshuafolkken/kit#5672), so a re-plan that
+	// narrows `paths` keeps the files the lane already cleared and edited planned for the hunks axis.
+	cleared_paths: z.array(z.string()).optional(),
 })
 
 type LanePlan = z.infer<typeof lane_plan_schema>
@@ -33,12 +46,34 @@ function plan_path(repository: string, issue: number): string {
 	return durable_state.path(durable_state.PREFIX.LANE_PLAN, repository, `-${String(issue)}.json`)
 }
 
+function read(issue: number, directory: string): LanePlan | undefined {
+	const repository = git_common_directory.repository(directory)
+	const text =
+		repository === undefined ? undefined : stamp_file.read_stamp_text(plan_path(repository, issue))
+
+	return text === undefined ? undefined : json_value.parse_with(text, lane_plan_schema)
+}
+
+// The paths `prior`'s clears held — its history, and its `paths` when it was cleared itself.
+function cleared_history(prior: LanePlan | undefined): Array<string> {
+	const latest = prior?.cleared === true ? prior.paths : []
+
+	return [...new Set([...(prior?.cleared_paths ?? []), ...latest])]
+}
+
+function with_history(plan: LanePlan, prior: LanePlan | undefined): LanePlan {
+	const cleared_paths = cleared_history(prior)
+
+	return cleared_paths.length === 0 ? plan : { ...plan, cleared_paths }
+}
+
 function record(plan: LanePlan, directory: string): boolean {
 	const repository = git_common_directory.repository(directory)
 
 	if (repository === undefined) return false
+	const recorded = with_history(plan, read(plan.issue, directory))
 
-	stamp_file.replace_stamp(plan_path(repository, plan.issue), plan)
+	stamp_file.replace_stamp(plan_path(repository, plan.issue), recorded)
 
 	return true
 }
@@ -49,14 +84,6 @@ function remove(issue: number, directory: string): void {
 	if (repository !== undefined) stamp_file.remove_stamp(plan_path(repository, issue))
 }
 
-function read(issue: number, directory: string): LanePlan | undefined {
-	const repository = git_common_directory.repository(directory)
-	const text =
-		repository === undefined ? undefined : stamp_file.read_stamp_text(plan_path(repository, issue))
-
-	return text === undefined ? undefined : json_value.parse_with(text, lane_plan_schema)
-}
-
 // Whether `issue` has no plan that `lane:plan` cleared, in a repository that can hold one — a checkout
 // with no common git directory cannot record a plan, so it is never asked for one. A plan recorded but
 // not cleared — a yield, an unread listing — lifts no hold: the record is written before the check.
@@ -67,6 +94,12 @@ function is_uncleared(issue: number, directory: string): boolean {
 	)
 }
 
+// Whether `plan` met the size bar — recorded `sized`, or cleared before `sized` was recorded
+// (joshuafolkken/kit#5605).
+function is_sized(plan: LanePlan | undefined): boolean {
+	return plan?.sized === true || plan?.cleared === true
+}
+
 // What an ended lane does with its plan. A plan the lane yielded on (`lane-yield.ts`,
 // joshuafolkken/kit#4926) stays: `backlog:next` holds the issue back on it while the holder runs, and
 // its next lane keeps the place in line it took. Any other plan goes — cleared, or left by a lane that
@@ -76,16 +109,70 @@ function release(issue: number, directory: string): void {
 	if (read(issue, directory)?.yielded !== true) remove(issue, directory)
 }
 
-// `declared` with each issue's recorded plan, if any, in place of what it declares (joshuafolkken/kit#4937).
-function with_plans(declared: Declared, directory: string): Declared {
+// When `issue`'s plan was last written, in epoch milliseconds — `NaN` with none. A re-plan keeps
+// `planned_at`, its place in line, so the file's time is the record's age.
+function recorded_ms(issue: number, directory: string): number {
+	const repository = git_common_directory.repository(directory)
+	const stats =
+		repository === undefined
+			? undefined
+			: fs.statSync(plan_path(repository, issue), { throwIfNoEntry: false })
+
+	return stats?.mtimeMs ?? NaN
+}
+
+function is_after(commented_at: string | undefined, recorded: number): boolean {
+	return commented_at !== undefined && Date.parse(commented_at) > recorded
+}
+
+// `issue`'s recorded paths, or `paths` when it has no record or its plan comment came after it.
+function plan_or(
+	issue: number,
+	paths: ReadonlySet<string>,
+	commented_at: string | undefined,
+	directory: string,
+): ReadonlySet<string> {
+	const recorded = read(issue, directory)
+
+	if (recorded === undefined || is_after(commented_at, recorded_ms(issue, directory))) return paths
+
+	return new Set(recorded.paths)
+}
+
+// `declared` with each issue's recorded plan, if any, in place of what it declares (joshuafolkken/kit#4937)
+// — unless the issue's plan comment, posted at its time in `commented`, came after the record: a yielded
+// plan outlives its lane, and a plan comment fixed since is the newer scope (joshuafolkken/kit#6798).
+function with_plans(
+	declared: Declared,
+	directory: string,
+	commented: ReadonlyMap<number, string> = new Map(),
+): Declared {
 	const replaced = [...declared].map(([issue, paths]): [number, ReadonlySet<string>] => [
 		issue,
-		new Set(read(issue, directory)?.paths ?? paths),
+		plan_or(issue, paths, commented.get(issue), directory),
 	])
 
 	return new Map(replaced)
 }
 
+// `declared` with the recorded plan of each of `holders` it has no entry for — a running lane outside
+// the opted-in listing, whose plan dispatch otherwise never reads (joshuafolkken/kit#7185).
+function with_holder_plans(
+	declared: Declared,
+	holders: ReadonlyArray<number>,
+	directory: string,
+): Declared {
+	const added = holders
+		.filter((issue) => !declared.has(issue))
+		.flatMap((issue): Array<[number, ReadonlySet<string>]> => {
+			const recorded = read(issue, directory)
+
+			return recorded === undefined ? [] : [[issue, new Set(recorded.paths)]]
+		})
+
+	return new Map([...declared, ...added])
+}
+
 // Whether `other` holds its files ahead of `plan`: it was cleared, or it planned first. A cleared lane
 // may already be editing, so a kept place in line never takes its files from it.
 function goes_before(other: LanePlan, plan: LanePlan): boolean {
@@ -121,15 +208,26 @@ function is_yielded(issue: number, directory: string): boolean {
 // Whether `issue` yielded on a plan that a lane in `declared` still holds one of its files ahead of —
 // what a named run holds the issue back on, as `backlog:next` does on the same kept plan
 // (joshuafolkken/kit#4926). Without it the run relaunches the issue at once, and the lane yields again.
-function is_yield_held(issue: number, declared: Declared, directory: string): boolean {
+// `scope`, the issue's own declaration read through `with_plans`, stands in for the kept paths, so a
+// plan comment fixed since the yield is what is held (joshuafolkken/kit#6798).
+function is_yield_held(
+	issue: number,
+	declared: Declared,
+	directory: string,
+	scope?: ReadonlySet<string>,
+): boolean {
 	const plan = read(issue, directory)
 
-	return plan?.yielded === true && clash_of(plan, declared, directory) !== undefined
+	if (plan?.yielded !== true) return false
+	const held = scope === undefined ? plan : { ...plan, paths: [...scope] }
+
+	return clash_of(held, declared, directory) !== undefined
 }
 
 const lane_plan = {
 	clash_of,
 	earlier_holders,
+	is_sized,
 	is_uncleared,
 	is_yield_held,
 	is_yielded,
@@ -137,6 +235,7 @@ const lane_plan = {
 	record,
 	release,
 	remove,
+	with_holder_plans,
 	with_plans,
 }
 

package/scripts/lane/lane-preserve.ts

@@ -1,6 +1,11 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
 import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+import { repository_lock } from '#scripts/git/repository-lock'
 import { git_stash } from '#scripts/git/stash/git-stash'
+import { session_cite } from '#scripts/issue/session-cite'
 import { error_text } from '#scripts/lib/error-message'
+import { lane_close } from './lane-close'
 
 // Keeping a lane's uncommitted work before something discards or restarts it — `run:merge` closing a
 // lane, `lane:restart` handing it to a fresh session. The stash stack outlives the tree, so the push is
@@ -38,40 +43,80 @@ type KeptWork =
 	| { kind: 'saved'; stash: string | undefined }
 	| { kind: 'unsaved'; directory: string; reason: string }
 
+// One keep per issue at a time: two withdraws of one lane each reading the tree and pushing pushed one
+// entry twice under one message, which `stash:pop` then refused as ambiguous (joshuafolkken/kit#6979).
+// Held for a status read and one push, so the wait only bounds a holder that hung.
+const KEEP_LOCK_PREFIX = 'josh-lane-keep-lock-'
+const KEEP_LOCK_WAIT_MS = 60_000
+const KEEP_LOCK_TIMEOUT = 'another keep of this lane held the lock for the whole wait'
+
+function keep_lock_path(issue: string, directory: string): string {
+	return repository_lock.lock_path(`${KEEP_LOCK_PREFIX}${issue}-`, directory)
+}
+
+// A tree holding only deleted tracked files is one caught mid-removal, not work (`holds_work`).
 async function stash_of(
 	issue: string,
 	directory: string,
 	occasion: string,
 ): Promise<string | undefined> {
-	if (!(await git_stash.has_changes(directory))) return undefined
+	if (!(await git_stash.has_work(directory))) return undefined
 
 	return await push_work(issue, directory, occasion)
 }
 
+async function locked_stash_of(
+	issue: string,
+	directory: string,
+	occasion: string,
+): Promise<KeptWork> {
+	const kept = await repository_lock.with_lock(
+		async () => ({ stash: await stash_of(issue, directory, occasion) }),
+		keep_lock_path(issue, directory),
+		KEEP_LOCK_WAIT_MS,
+	)
+
+	if (kept === undefined) return { kind: 'unsaved', directory, reason: KEEP_LOCK_TIMEOUT }
+
+	return { kind: 'saved', stash: kept.stash }
+}
+
 /** Stash the tree's uncommitted work, if any, answering `unsaved` rather than throwing. */
 async function keep_work(issue: string, directory: string, occasion: string): Promise<KeptWork> {
 	try {
-		return { kind: 'saved', stash: await stash_of(issue, directory, occasion) }
+		return await locked_stash_of(issue, directory, occasion)
 	} catch (error) {
 		return { kind: 'unsaved', directory, reason: error_text.message_of(error) }
 	}
 }
 
-/** `push_work`, then `announce` — for a caller with no reason to separate the two. */
-async function stash_work(
-	issue: string,
-	directory: string,
-	occasion: string,
-	cause: string,
-): Promise<string> {
-	const message = await push_work(issue, directory, occasion)
+// Keep whatever the issue's lane still holds uncommitted, and say on the Issue where it went — before
+// `run:merge` closes a merged child's lane, or (`--stash`) classifies a stopped unit. Returns whether
+// the tree is safe to remove: `false` when it could not be read or pushed, so it is left rather than
+// lost. A directory with no `.git` is no work tree — the remnant of an interrupted close — and holds
+// nothing git could keep.
+async function preserve_lane(issue: string, occasion: string, cause: string): Promise<boolean> {
+	const lane = await lane_close.resolve_lane(issue)
+	const { directory } = lane.targets
 
-	await announce(issue, message, cause)
+	if (!existsSync(path.join(directory, '.git'))) return true
 
-	return message
+	const kept = await keep_work(issue, directory, occasion)
+
+	if (kept.kind === 'unsaved') {
+		console.error(
+			`${session_cite.issue(issue)}: uncommitted work could not be stashed — lane left at ${directory}`,
+		)
+
+		return false
+	}
+
+	if (kept.stash !== undefined) await announce(issue, kept.stash, cause)
+
+	return true
 }
 
-const lane_preserve = { announce, keep_work, stash_work }
+const lane_preserve = { announce, keep_work, preserve_lane }
 
 export type { KeptWork }
 export { lane_preserve }

package/scripts/lane/lane-process-load.ts

@@ -1,6 +1,12 @@
 import { PROBE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import {
+	run_board_usage_rusage,
+	type RusageReader,
+} from '#scripts/run/board/run-board-usage-rusage'
 import { execa } from 'execa'
 
+const { load_builtin, rusage_reader } = run_board_usage_rusage
+
 // What the machine's load is made of at one instant: every process grouped by the kind of tool it
 // runs, the heaviest kinds kept with their CPU and resident size, for a `load` sample to carry.
 //
@@ -20,15 +26,26 @@ import { execa } from 'execa'
 //
 // **`%cpu` is the share of one core**, so 300 is three cores busy; it is `ps`'s decaying average,
 // which is what a one-minute sample beside the one-minute load average wants.
+//
+// **The footprint counts compressed pages; the resident set does not.** An idle `eslint_d`'s footprint in
+// `top`'s MEM was thirty times its `ps` resident size (joshuafolkken/kit#7244), so each process's
+// `ri_phys_footprint` is read by pid beside `ps` — one `proc_pid_rusage` call each, never a slow `top`.
 
-const PS_ARGUMENTS = ['-A', '-o', 'rss=,%cpu=,args=']
+const PS_ARGUMENTS = ['-A', '-o', 'pid=,rss=,%cpu=,args=']
 // `ps` prints `%cpu` with the locale's decimal separator, and a `0,7` would parse as NaN.
 const PS_ENVIRONMENT = { LC_ALL: 'C' }
 const FIELD_SEPARATOR = /\s+/u
 const KB_PER_MB = 1024
+const BYTES_PER_MB = KB_PER_MB * KB_PER_MB
 // Enough to name what dominates and the runner-up behind it, short enough for one ledger line a minute.
 const TOP_KINDS = 5
 const OTHER_KIND = 'other'
+// The apps a person keeps open beside a run, matched as command-line substrings: every Chrome and VS Code
+// helper runs out of its `.app` bundle, so the bundle name catches them all — and only them: Playwright's
+// `Google Chrome for Testing.app` is not the person's browser.
+const RESIDENT_APPS: ReadonlyArray<string> = ['Google Chrome.app', 'Visual Studio Code.app']
+const RESIDENT_APPS_VARIABLE = 'JOSH_LANE_RESIDENT_APPS'
+const NAME_SEPARATOR = ','
 
 const KIND_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
 	['vscode', /Visual Studio Code|Code Helper|\.vscode\/extensions\//u],
@@ -41,47 +58,135 @@ const KIND_PATTERNS: ReadonlyArray<readonly [string, RegExp]> = [
 	['chrome', /Google Chrome/u],
 	['chromium', /chromium|headless_shell/iu],
 	['claude', /(?:^|\/)claude(?:\s|$)|@anthropic-ai\/claude-code\//u],
-	['josh', /josh\.ts|\btsx\b|(?<!\.)\bpnpm\b/u],
+	['josh', /josh(?:-ready)?\.[jt]s|\btsx\b|(?<!\.)\bpnpm\b/u],
 	['node', /\bnode\b/u],
 ]
 
+// `footprint_mb` sums the processes whose footprint could be read — none off macOS or before Node's
+// `node:ffi`, so the field is left out, and not another user's process, whose call is refused.
 interface ProcessKind {
 	kind: string
 	cpu_percent: number
 	rss_mb: number
+	footprint_mb?: number | undefined
 	count: number
 }
 
+interface ProcessSnapshot {
+	processes: Array<ProcessKind>
+	resident_mb?: number | undefined
+}
+
+interface LineReading {
+	pid: number
+	command_line: string
+	cpu_percent: number
+	rss_mb: number
+}
+
+type ProcessReading = Omit<ProcessKind, 'count'>
+
 function kind_of(command_line: string): string {
 	return KIND_PATTERNS.find(([, pattern]) => pattern.test(command_line))?.[0] ?? OTHER_KIND
 }
 
-// One line of `ps`'s listing as its kind and readings; a header or a cut-short line reads as nothing.
-function process_of(line: string): Omit<ProcessKind, 'count'> | undefined {
-	const [rss, cpu, ...command] = line.trim().split(FIELD_SEPARATOR)
-	const reading = { cpu_percent: Number(cpu), rss_mb: Number(rss) / KB_PER_MB }
+// One line of `ps`'s listing as its command line and readings; a header or a cut-short line reads as nothing.
+function line_of(line: string): LineReading | undefined {
+	const [pid, rss, cpu, ...command] = line.trim().split(FIELD_SEPARATOR)
+	const reading = { pid: Number(pid), cpu_percent: Number(cpu), rss_mb: Number(rss) / KB_PER_MB }
+
+	if (command.length === 0 || Number.isNaN(reading.pid + reading.cpu_percent + reading.rss_mb)) {
+		return undefined
+	}
 
-	if (command.length === 0 || Number.isNaN(reading.cpu_percent + reading.rss_mb)) return undefined
+	return { command_line: command.join(' '), ...reading }
+}
 
-	return { kind: kind_of(command.join(' ')), ...reading }
+function footprint_mb_of(footprint: RusageReader | undefined, pid: number): number | undefined {
+	const footprint_bytes = footprint?.(pid)?.footprint_bytes
+
+	return footprint_bytes === undefined ? undefined : footprint_bytes / BYTES_PER_MB
 }
 
-function add_line(totals: Map<string, ProcessKind>, line: string): void {
-	const reading = process_of(line)
+function process_of(line: string, footprint: RusageReader | undefined): ProcessReading | undefined {
+	const reading = line_of(line)
 
-	if (reading === undefined) return
+	if (reading === undefined) return undefined
 
-	const { kind } = reading
-	const total = totals.get(kind) ?? { kind, cpu_percent: 0, rss_mb: 0, count: 0 }
+	return {
+		kind: kind_of(reading.command_line),
+		cpu_percent: reading.cpu_percent,
+		rss_mb: reading.rss_mb,
+		footprint_mb: footprint_mb_of(footprint, reading.pid),
+	}
+}
 
+// The resident apps' names: `JOSH_LANE_RESIDENT_APPS`, comma-separated, overrides the default; an empty
+// value names none, so no sample records a size (joshuafolkken/kit#5690).
+function resident_apps(
+	value: string | undefined = process.env[RESIDENT_APPS_VARIABLE],
+): ReadonlyArray<string> {
+	if (value === undefined) return RESIDENT_APPS
+
+	return value
+		.split(NAME_SEPARATOR)
+		.map((name) => name.trim())
+		.filter((name) => name.length > 0)
+}
+
+function is_resident(
+	reading: LineReading | undefined,
+	names: ReadonlyArray<string>,
+): reading is LineReading {
+	return reading !== undefined && names.some((name) => reading.command_line.includes(name))
+}
+
+// The resident size of every process a resident app runs, summed, so `lane:stats` can set a day the apps
+// were closed beside a day they were not (joshuafolkken/kit#5658); `undefined` with no names to match.
+function resident_mb(listing: string, names: ReadonlyArray<string>): number | undefined {
+	if (names.length === 0) return undefined
+
+	const readings = listing.split('\n').map((line) => line_of(line))
+	const resident = readings.filter((reading) => is_resident(reading, names))
+
+	return Math.round(resident.reduce((total, reading) => total + reading.rss_mb, 0))
+}
+
+function add_reading(total: ProcessKind, reading: ProcessReading): void {
 	total.cpu_percent += reading.cpu_percent
 	total.rss_mb += reading.rss_mb
 	total.count += 1
+
+	if (reading.footprint_mb !== undefined) {
+		total.footprint_mb = (total.footprint_mb ?? 0) + reading.footprint_mb
+	}
+}
+
+function add_line(
+	totals: Map<string, ProcessKind>,
+	line: string,
+	footprint: RusageReader | undefined,
+): void {
+	const reading = process_of(line, footprint)
+
+	if (reading === undefined) return
+
+	const { kind } = reading
+	const total = totals.get(kind) ?? { kind, cpu_percent: 0, rss_mb: 0, count: 0 }
+
+	add_reading(total, reading)
 	totals.set(kind, total)
 }
 
 function rounded(total: ProcessKind): ProcessKind {
-	return { ...total, cpu_percent: Math.round(total.cpu_percent), rss_mb: Math.round(total.rss_mb) }
+	const { footprint_mb, ...rest } = total
+	const kind = {
+		...rest,
+		cpu_percent: Math.round(rest.cpu_percent),
+		rss_mb: Math.round(rest.rss_mb),
+	}
+
+	return footprint_mb === undefined ? kind : { ...kind, footprint_mb: Math.round(footprint_mb) }
 }
 
 // The heaviest kinds first: by CPU, the load average's own measure, then by memory for idle kinds.
@@ -89,10 +194,10 @@ function by_weight(left: ProcessKind, right: ProcessKind): number {
 	return right.cpu_percent - left.cpu_percent || right.rss_mb - left.rss_mb
 }
 
-function summarize(listing: string): Array<ProcessKind> {
+function summarize(listing: string, footprint?: RusageReader): Array<ProcessKind> {
 	const totals = new Map<string, ProcessKind>()
 
-	for (const line of listing.split('\n')) add_line(totals, line)
+	for (const line of listing.split('\n')) add_line(totals, line, footprint)
 
 	return [...totals.values()]
 		.map((total) => rounded(total))
@@ -101,25 +206,31 @@ function summarize(listing: string): Array<ProcessKind> {
 }
 
 // `undefined` where `ps` did not answer, so the sample records no breakdown rather than an empty one.
-async function read(): Promise<Array<ProcessKind> | undefined> {
+async function read(
+	names: ReadonlyArray<string> = resident_apps(),
+	footprint: RusageReader | undefined = rusage_reader(process.platform, load_builtin),
+): Promise<ProcessSnapshot | undefined> {
 	try {
 		const { stdout } = await execa('ps', PS_ARGUMENTS, {
 			env: PS_ENVIRONMENT,
 			timeout: PROBE_TIMEOUT_MS,
 		})
 
-		return summarize(stdout)
+		return { processes: summarize(stdout, footprint), resident_mb: resident_mb(stdout, names) }
 	} catch {
 		return undefined
 	}
 }
 
 const lane_process_load = {
+	RESIDENT_APPS,
 	TOP_KINDS,
 	kind_of,
 	read,
+	resident_apps,
+	resident_mb,
 	summarize,
 }
 
-export type { ProcessKind }
+export type { ProcessKind, ProcessSnapshot }
 export { lane_process_load }

package/scripts/lane/lane-process-stats.ts

@@ -12,14 +12,24 @@ import { lane_stats, type StatsWindow } from './lane-stats'
 //
 // **CPU is in cores** — `ps`'s share of one core over a hundred — so the column reads against the load
 // average and the machine's core count without a conversion.
+//
+// **The footprint peak counts compressed pages**, which the resident peak leaves out
+// (joshuafolkken/kit#7244); a kind whose samples recorded no footprint prints it as missing.
 
+const RSS_PEAK = 'rss peak (GB)'
+const SAMPLES = 'samples'
 const COLUMNS = [
 	'process',
 	'cpu mean (cores)',
 	'cpu peak (cores)',
-	'rss peak (GB)',
-	'samples',
+	RSS_PEAK,
+	'footprint peak (GB)',
+	SAMPLES,
 ] as const
+const RESIDENT_COLUMNS = ['resident apps', 'rss median (GB)', RSS_PEAK, SAMPLES] as const
+// Not the names: a sample sums the apps `JOSH_LANE_RESIDENT_APPS` named when it ran, which the ledger does
+// not keep, so names read at print time could label sizes another set of apps made (joshuafolkken/kit#5690).
+const RESIDENT_LABEL = 'summed'
 const PERCENT_PER_CORE = 100
 const MB_PER_GB = 1024
 const DECIMALS = 1
@@ -60,14 +70,20 @@ function cell(value: number | undefined): string {
 	return value === undefined ? lane_stats.MISSING : value.toFixed(DECIMALS)
 }
 
-function kind_cells(row: KindRow): Array<string> {
-	const rss_peak = lane_stats.peak(row.readings.map((reading) => reading.rss_mb))
+// The largest of `sizes` in gigabytes, `undefined` where none was recorded.
+function peak_gb(sizes: ReadonlyArray<number>): number | undefined {
+	const peak = lane_stats.peak(sizes)
+
+	return peak === undefined ? undefined : peak / MB_PER_GB
+}
 
+function kind_cells(row: KindRow): Array<string> {
 	return [
 		row.kind,
 		cell(mean_cores(row)),
 		cell(lane_stats.peak(cores(row.readings))),
-		cell(rss_peak === undefined ? undefined : rss_peak / MB_PER_GB),
+		cell(peak_gb(row.readings.map((reading) => reading.rss_mb))),
+		cell(peak_gb(row.readings.flatMap((reading) => reading.footprint_mb ?? []))),
 		String(row.readings.length),
 	]
 }
@@ -76,16 +92,41 @@ function by_mean_cpu(left: KindRow, right: KindRow): number {
 	return mean_cores(right) - mean_cores(left)
 }
 
+function to_table(columns: ReadonlyArray<string>, rows: ReadonlyArray<Array<string>>): string {
+	return [
+		lane_stats.to_row(columns),
+		lane_stats.to_row(columns.map(() => '---')),
+		...rows.map((row) => lane_stats.to_row(row)),
+	].join('\n')
+}
+
+// The resident apps' summed size over the samples that recorded it (joshuafolkken/kit#5658), so a period
+// run with the IDE and browser closed reads against one run with them open. Older samples carry none,
+// and a period with none prints no table, leaving the output as it was.
+function resident_tables(samples: ReadonlyArray<LoadEntry>): Array<string> {
+	const sizes = samples.flatMap((sample) => sample.resident_mb ?? [])
+
+	if (sizes.length === 0) return []
+
+	const gigabytes = sizes.map((size) => size / MB_PER_GB)
+	const row = [RESIDENT_LABEL, cell(lane_stats.median(gigabytes)), cell(lane_stats.peak(gigabytes))]
+
+	return [to_table(RESIDENT_COLUMNS, [[...row, String(sizes.length)]])]
+}
+
 // The period's table: `entries` is the whole ledger, filtered here to `window`. A period whose samples
 // carried no breakdown prints the header alone.
 function table(entries: ReadonlyArray<LedgerEntry>, window: StatsWindow): string {
-	const rows = group(lane_stats.in_window(entries, window).filter(is_load)).toSorted(by_mean_cpu)
+	const samples = lane_stats.in_window(entries, window).filter(is_load)
+	const rows = group(samples).toSorted(by_mean_cpu)
 
 	return [
-		lane_stats.to_row(COLUMNS),
-		lane_stats.to_row(COLUMNS.map(() => '---')),
-		...rows.map((row) => lane_stats.to_row(kind_cells(row))),
-	].join('\n')
+		to_table(
+			COLUMNS,
+			rows.map((row) => kind_cells(row)),
+		),
+		...resident_tables(samples),
+	].join('\n\n')
 }
 
 const lane_process_stats = { table }

package/scripts/lane/lane-reap.ts

@@ -6,7 +6,7 @@ import { process_tools } from './process-tools'
 // Ending a lane child that did not end itself.
 //
 // **A detached child is kept alive on purpose and was never ended by anything.** `detached_launch`
-// lets a child outlive its parent's session, and every reader of it — `run:liveness`, the 30-minute
+// lets a child outlive its parent's session, and every reader of it — `run:liveness`, the
 // silence window — only *reads* whether it stopped. So a child that merged and then hung on a wait
 // loop of its own lived on for a day, and the documented `pgrep -laf "fullrun #<N>$"` answered
 // `alive` for that issue number forever, which is a verification answering wrongly. The close and the
@@ -105,7 +105,8 @@ const SYSTEM_PROBES: ReapProbes = {
 	terminate,
 }
 
-function ancestry_of(pid: number, probes: TreeProbes): Set<number> {
+// `pid` and every process above it.
+function ancestry_of(pid: number, probes: TreeProbes = SYSTEM_PROBES): Set<number> {
 	const ancestry = new Set<number>([pid])
 	let current = probes.parent_of(pid)
 
@@ -171,6 +172,7 @@ function is_child_running(issue: string, probes: TreeProbes = SYSTEM_PROBES): bo
 }
 
 const lane_reap = {
+	ancestry_of,
 	is_child_running,
 	lane_tree,
 	own_ancestry,