@nredd/pi-session-kit 0.7.0 → 0.9.0

package/src/mon/index.ts

@@ -0,0 +1,105 @@
+/** Command/lifecycle shell. Production wiring passes `createSamplerSource` (`source.ts`). */
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Clock } from "../clock.ts";
+import { MonView } from "./component.ts";
+import { MonPoll, type MonSource } from "./poll.ts";
+
+export interface MonOptions {
+	/** Required: no fake or fallback production collector. Invoked only while the TUI opens. */
+	createSource: () => MonSource;
+	clock?: Clock;
+}
+
+/** No persistence, model tools, notifications to model context, or collection at registration. */
+export function registerMon(pi: ExtensionAPI, options: MonOptions): void {
+	let closeActive: (() => Promise<void>) | undefined;
+	let generation = 0;
+	let ownership = Promise.resolve();
+	const serialize = (action: () => Promise<void>): Promise<void> => {
+		const next = ownership.then(action);
+		ownership = next.catch(() => {});
+		return next;
+	};
+	const reset = (): Promise<void> => {
+		generation++;
+		return serialize(async () => {
+			await closeActive?.();
+		});
+	};
+	pi.on("session_shutdown", reset);
+	pi.on("session_start", reset);
+	pi.registerCommand("mon", {
+		description: "Live local CPU, memory and busy processes (read only)",
+		async handler(_args: string, ctx: ExtensionCommandContext) {
+			if (ctx.mode !== "tui") {
+				ctx.ui.notify("/mon requires an interactive terminal", "warning");
+				return;
+			}
+			const requestedGeneration = generation;
+			let interaction: Promise<void> | undefined;
+			let poll: MonPoll | undefined;
+			let ownClose: (() => Promise<void>) | undefined;
+			try {
+				await serialize(async () => {
+					if (requestedGeneration !== generation) return;
+					await closeActive?.();
+					if (requestedGeneration !== generation) return;
+					let markReady!: () => void;
+					const ready = new Promise<void>((resolve) => {
+						markReady = resolve;
+					});
+					interaction = ctx.ui.custom<void>(
+						(tui, theme, _kb, done) => {
+							if (requestedGeneration !== generation) {
+								done();
+								return { render: () => [], invalidate: () => {} };
+							}
+							let closed = false;
+							const close = (): Promise<void> => {
+								const cleanup = poll?.dispose() ?? Promise.resolve();
+								if (!closed) {
+									closed = true;
+									done();
+								}
+								return cleanup;
+							};
+							ownClose = close;
+							closeActive = close;
+							const view = new MonView({
+								theme,
+								rows: () => tui.terminal.rows,
+								requestRender: () => tui.requestRender(),
+								onClose: () => {
+									void close();
+								},
+							});
+							poll = new MonPoll(options.createSource(), (sample) => view.update(sample), options.clock);
+							poll.start();
+							markReady();
+							return {
+								render: (width: number) => {
+									try {
+										return view.render(width);
+									} catch (error) {
+										void close();
+										throw error;
+									}
+								},
+								invalidate: () => view.invalidate(),
+								handleInput: (data: string) => view.handleInput(data),
+								dispose: () => poll?.dispose(),
+							};
+						},
+						{ overlay: true, overlayOptions: { anchor: "top-left", width: "100%", maxHeight: "100%", margin: 0 } },
+					);
+					// Hold ownership until even a deferred UI factory has installed its closer.
+					await Promise.race([ready, interaction]);
+				});
+				await interaction;
+			} finally {
+				await poll?.dispose();
+				if (closeActive === ownClose) closeActive = undefined;
+			}
+		},
+	});
+}

package/src/mon/model.ts

@@ -0,0 +1,197 @@
+/** Presentation-only resource values. The sampler adapter owns measurement and validity. */
+export interface MonProcess {
+	/** Stable sampler identity, not PID alone (PIDs can be reused). */
+	identity: string;
+	pid: number;
+	/** Untrusted executable basename; "" when the OS gave none. */
+	name: string;
+	/** `unknown`: no name was readable. `truncated`: the OS limit may have cut it (macOS 16 bytes). */
+	nameState?: "unknown" | "truncated";
+	cpuPercent: number | null;
+	rssBytes: number | null;
+	/** Native macOS physical footprint, including compression; undefined/null is not zero. */
+	footprintBytes?: number | null;
+}
+
+/** No process arguments, environment, working directories or host identifiers enter the view. */
+export interface MonSnapshot {
+	cpuPercent: number | null;
+	logicalCpus: number;
+	memoryUsedBytes: number | null;
+	memoryTotalBytes: number | null;
+	/** Explicit measurement basis; older fixtures/producers default to total-free. */
+	memoryBasis?: "total-free" | "app+wired+compressed";
+	memoryFreeBytes?: number | null;
+	swapUsedBytes?: number | null;
+	swapTotalBytes?: number | null;
+	load: readonly number[];
+	processes: readonly MonProcess[];
+	/** Wall-clock capture time, for display only (it can jump). Never persisted. */
+	capturedAt: number;
+	/** Monotonic capture time; history spacing uses this, never wall time. */
+	sampledAtMs: number;
+	/** Collection time of this capture, when the adapter measured it. */
+	scanMs?: number | null;
+	/** Collector outcome: `live` is a successful collection even when host CPU has no value yet. */
+	status: "live" | "stale";
+	/** Host interval CPU state, independent of collector success. */
+	cpuState: "available" | "warming" | "unavailable";
+	/** Process interval CPU cannot exist for this platform; the view then defaults to RSS order. */
+	processCpu?: "unavailable";
+	/** Safe, bounded warning supplied by the adapter: something limits what the view can show. */
+	notice?: string;
+	/** Safe, bounded platform note (expected limits, e.g. macOS process CPU); rendered muted. */
+	hint?: string;
+}
+
+export type MonSort = "cpu" | "rss" | "pid";
+export const SORTS: readonly MonSort[] = ["cpu", "rss", "pid"];
+
+/**
+ * Sort unknown/nonfinite measurements last, with deterministic ties.
+ * @param processes Readonly input rows.
+ * @param sort Requested CPU/RSS/PID ordering.
+ * @returns Sorted copy, leaving input untouched.
+ */
+export function sortProcesses(processes: readonly MonProcess[], sort: MonSort): MonProcess[] {
+	return [...processes].sort((a, b) => {
+		const av = sort === "cpu" ? a.cpuPercent : sort === "rss" ? a.rssBytes : a.pid;
+		const bv = sort === "cpu" ? b.cpuPercent : sort === "rss" ? b.rssBytes : b.pid;
+		const au = av === null || !Number.isFinite(av);
+		const bu = bv === null || !Number.isFinite(bv);
+		if (au !== bu) return au ? 1 : -1;
+		if (!au && !bu && av !== bv) return sort === "pid" ? av - bv : bv - av;
+		return a.pid - b.pid || a.identity.localeCompare(b.identity);
+	});
+}
+
+/**
+ * Format a percentage without inventing zero for unknown input.
+ * @param value Percentage or null.
+ * @returns One decimal plus percent sign, or --.
+ */
+export function percent(value: number | null): string {
+	return value === null || !Number.isFinite(value) ? "--" : `${value.toFixed(1)}%`;
+}
+
+/**
+ * Format process RSS share of the same sample's total RAM.
+ * @param part Resident bytes or null.
+ * @param total Physical RAM bytes or null.
+ * @returns One decimal percentage without its sign, or --.
+ */
+export function share(part: number | null, total: number | null): string {
+	if (part === null || total === null || !Number.isFinite(part) || !Number.isFinite(total) || total <= 0) return "--";
+	return `${((part / total) * 100).toFixed(1)}`;
+}
+
+/**
+ * Format binary byte quantities for bounded dashboard cells.
+ * @param value Bytes or null.
+ * @returns GiB/MiB quantity with compact G/M suffix, or --.
+ */
+export function bytes(value: number | null): string {
+	if (value === null || !Number.isFinite(value)) return "--";
+	return value >= 1024 ** 3 ? `${(value / 1024 ** 3).toFixed(1)}G` : `${(value / 1024 ** 2).toFixed(0)}M`;
+}
+
+export interface MonHistoryPoint {
+	/** Monotonic milliseconds, so wall-clock steps cannot invent or hide gaps. */
+	sampledAtMs: number;
+	value: number | null;
+}
+
+/**
+ * Time-proportional buckets, newest on the right. A column is the typical sampling interval (lower
+ * median of consecutive captures), widened only when the history spans more than the width. Columns
+ * after the first capture without a CPU value are real gaps (`null`), never interpolated CPU; the
+ * leading `blank` columns precede the first capture because no history exists yet. The latest sample
+ * in a bucket wins.
+ * @param history Monotonic ordered CPU observations.
+ * @param width Available chart columns.
+ * @returns Leading blank count and measured/gap buckets.
+ */
+function historyBuckets(
+	history: readonly MonHistoryPoint[],
+	width: number,
+): { blank: number; buckets: (number | null)[] } {
+	const first = history[0];
+	const last = history.at(-1);
+	if (!first || !last || width < 1) return { blank: Math.max(0, width), buckets: [] };
+	const span = last.sampledAtMs - first.sampledAtMs;
+	if (span <= 0) return { blank: width - 1, buckets: [last.value] };
+	const deltas = history
+		.slice(1)
+		.map((point, i) => point.sampledAtMs - (history[i]?.sampledAtMs ?? point.sampledAtMs))
+		.filter((delta) => delta > 0)
+		.sort((a, b) => a - b);
+	const typical = deltas[Math.floor((deltas.length - 1) / 2)] ?? span;
+	const step = Math.max(typical, span / Math.max(1, width - 1));
+	const buckets: (number | null)[] = Array.from({ length: width }, () => null);
+	let oldest = width - 1;
+	for (const point of history) {
+		const index = width - 1 - Math.round((last.sampledAtMs - point.sampledAtMs) / step);
+		if (index < 0 || index >= width) continue;
+		buckets[index] = point.value;
+		oldest = Math.min(oldest, index);
+	}
+	return { blank: oldest, buckets: buckets.slice(oldest) };
+}
+
+/**
+ * Render one-row history: blank before data, dots for gaps.
+ * @param history Monotonic ordered CPU observations.
+ * @param width Available chart columns.
+ * @returns Time-proportional CPU sparkline.
+ */
+export function timeHistory(history: readonly MonHistoryPoint[], width: number): string {
+	if (!history.length || width < 1) return "";
+	const { blank, buckets } = historyBuckets(history, width);
+	return " ".repeat(blank) + sparkline(buckets, buckets.length);
+}
+
+/**
+ * Multi-row history (top row first), `rows * 8` levels on the same fixed 0..100 scale. A gap is `·`
+ * on the bottom row only; zero keeps a `▁` baseline so a quiet host never looks like missing data.
+ * @param history Monotonic ordered CPU observations.
+ * @param width Available chart columns.
+ * @param rows Chart height.
+ * @returns Top-first rendered chart rows.
+ */
+export function timeHistoryRows(history: readonly MonHistoryPoint[], width: number, rows: number): string[] {
+	if (rows <= 1) return [timeHistory(history, width)];
+	const lines = Array.from({ length: rows }, () => "");
+	if (!history.length || width < 1) return lines;
+	const { blank, buckets } = historyBuckets(history, width);
+	const ticks = "▁▂▃▄▅▆▇█";
+	for (let row = 0; row < rows; row++) lines[row] = " ".repeat(blank);
+	for (const value of buckets) {
+		const level =
+			value === null || !Number.isFinite(value)
+				? -1
+				: Math.max(0, Math.min(rows * 8, Math.round((value * rows * 8) / 100)));
+		for (let row = 0; row < rows; row++) {
+			// Row 0 is the top; `fill` is how many eighths this row holds.
+			const floor = (rows - 1 - row) * 8;
+			const fill = level - floor;
+			const bottom = row === rows - 1;
+			lines[row] +=
+				level < 0 ? (bottom ? "·" : " ") : fill >= 8 ? "█" : fill > 0 ? (ticks[fill - 1] ?? " ") : bottom ? "▁" : " ";
+		}
+	}
+	return lines;
+}
+
+/**
+ * Render a fixed 0..100 CPU scale so quiet history does not look saturated.
+ * @param history CPU percentages or unknown samples.
+ * @param width Maximum newest samples to show.
+ * @returns Sparkline with dots for unknown/nonfinite samples.
+ */
+export function sparkline(history: readonly (number | null)[], width: number): string {
+	const ticks = "▁▂▃▄▅▆▇█";
+	const values = history.slice(-Math.max(0, width));
+	return values
+		.map((n) => (n === null || !Number.isFinite(n) ? "·" : ticks[Math.min(7, Math.max(0, Math.round((n * 7) / 100)))]))
+		.join("");
+}

package/src/mon/poll.ts

@@ -0,0 +1,80 @@
+/** Single-flight, completion-paced sampling. No polling exists outside an open interaction. */
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
+import type { MonSnapshot } from "./model.ts";
+
+/** Presentation boundary; the production adapter must delegate to the shared sampler. */
+export interface MonSource {
+	sample(signal: AbortSignal): Promise<MonSnapshot>;
+	dispose(): void | Promise<void>;
+}
+
+/** Errors retain the last data as explicitly stale and stop probes until the view is reopened. */
+export class MonPoll {
+	private timer: TimerHandle | undefined;
+	private readonly abort = new AbortController();
+	private disposed = false;
+	private started = false;
+	private last: MonSnapshot | undefined;
+	private cleanup: Promise<void> | undefined;
+
+	constructor(
+		private readonly source: MonSource,
+		private readonly update: (snapshot: MonSnapshot) => void,
+		private readonly clock: Clock = realClock,
+		private readonly intervalMs = 2000,
+	) {}
+
+	start(): void {
+		if (this.started || this.disposed) return;
+		this.started = true;
+		void this.poll().catch(() => {});
+	}
+
+	private async poll(): Promise<void> {
+		try {
+			const snapshot = await this.source.sample(this.abort.signal);
+			if (this.disposed) return;
+			this.last = snapshot;
+			this.update(snapshot);
+			if (!this.disposed)
+				this.timer = this.clock.setTimeout(() => {
+					void this.poll().catch(() => {});
+				}, this.intervalMs);
+		} catch {
+			if (this.disposed) return;
+			try {
+				this.update({
+					cpuPercent: null,
+					logicalCpus: 0,
+					memoryUsedBytes: null,
+					memoryTotalBytes: null,
+					load: [],
+					processes: [],
+					capturedAt: this.clock.now(),
+					sampledAtMs: performance.now(),
+					cpuState: "unavailable",
+					...this.last,
+					status: "stale",
+					notice: "Sampling stopped. Close and reopen to retry.",
+				});
+			} catch {
+				// A failed renderer must not leave collection running or reject an unobserved task.
+			} finally {
+				await this.dispose();
+			}
+		}
+	}
+
+	/** Await this at the command boundary so asynchronous probes are reaped before returning. */
+	dispose(): Promise<void> {
+		if (this.cleanup) return this.cleanup;
+		this.disposed = true;
+		this.timer?.cancel();
+		this.timer = undefined;
+		this.abort.abort();
+		this.cleanup = Promise.resolve().then(() => this.source.dispose());
+		// Timer callbacks cannot surface cleanup failures; the command's finally awaits the same promise.
+		void this.cleanup.catch(() => {});
+		return this.cleanup;
+	}
+}

package/src/mon/source.ts

@@ -0,0 +1,181 @@
+/** Production /mon source: a thin mapping over the published shared sampler. No collector lives here. */
+import {
+	createResourceSampler,
+	type Metric,
+	type ResourceSampler,
+	type ResourceSnapshot,
+	type SamplerOptions,
+} from "@nredd/pi-resource-sampler";
+import type { MonSnapshot } from "./model.ts";
+import type { MonSource } from "./poll.ts";
+
+/** Bounded so a notice line stays readable even with many coverage reasons. */
+const MAX_REASONS = 3;
+/** macOS keeps at most this many bytes of the executable name (`p_comm`). */
+const DARWIN_NAME_BYTES = 16;
+/** Skips every Linux scan expects: kernel threads have no RSS, and processes exit mid-scan. */
+const ROUTINE_SKIP = "process-unreadable-or-changed";
+const REASONS: Readonly<Record<string, string>> = {
+	deadline: "time budget",
+	"pid-limit": "process cap",
+	"byte-limit": "read budget",
+	"file-byte-limit": "read budget",
+	[ROUTINE_SKIP]: "unreadable or exited",
+	"command-unavailable": "OS reader unavailable",
+	"command-failed": "OS reader failed",
+	"malformed-process-row": "unparsed rows",
+	"process-collection-unavailable": "process list unavailable",
+};
+const utf8 = new TextEncoder();
+
+/** Additive v1 fields for registry 0.1.1 compatibility; remove this shim at the owner-gated 0.2.0 pin. */
+type MemorySnapshot = Omit<ResourceSnapshot, "memory" | "processes"> & {
+	processes: (ResourceSnapshot["processes"][number] & { footprint?: Metric<number> })[];
+	memory: ResourceSnapshot["memory"] & {
+		usage?: Metric<{ usedBytes: number; availableBytes: number; basis: "app+wired+compressed" }>;
+		swap?: Metric<{ usedBytes: number; totalBytes: number }>;
+	};
+};
+
+/**
+ * Convert nonfinite producer values to the view's unknown sentinel.
+ * @param value Producer number.
+ * @returns Finite value or null.
+ */
+function finite(value: number): number | null {
+	return Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Distinguish unavailable process CPU from initial warming.
+ * @param snapshot Producer snapshot.
+ * @returns Whether a nonempty process list has no supported interval CPU metrics.
+ */
+function processCpuUnavailable(snapshot: ResourceSnapshot): boolean {
+	return snapshot.processes.length > 0 && snapshot.processes.every((p) => p.cpu.state === "unavailable");
+}
+
+/**
+ * Annotate unknown or potentially truncated executable names.
+ * @param snapshot Snapshot supplying platform semantics.
+ * @param name Producer's sanitized executable basename.
+ * @returns Unknown/truncated marker, or undefined for a complete known name.
+ */
+function nameState(snapshot: ResourceSnapshot, name: string): "unknown" | "truncated" | undefined {
+	if (name === "") return "unknown";
+	return snapshot.platform === "darwin" && utf8.encode(name).length >= DARWIN_NAME_BYTES ? "truncated" : undefined;
+}
+
+/**
+ * Explain budget caps, collector failures and unavailable host CPU.
+ * @param snapshot Producer snapshot and coverage.
+ * @param baseline Whether this is the first observation.
+ * @returns User-facing limit notice, or undefined when unnecessary.
+ */
+function notice(snapshot: ResourceSnapshot, baseline: boolean): string | undefined {
+	const parts: string[] = [];
+	const { coverage } = snapshot;
+	const limits = coverage.reasons.filter((reason) => reason !== ROUTINE_SKIP);
+	if (!coverage.complete && (limits.length || !coverage.reasons.length)) {
+		const reasons = [...new Set(coverage.reasons.map((reason) => REASONS[reason] ?? reason))];
+		const text = reasons.slice(0, MAX_REASONS).join(", ") || "unknown";
+		parts.push(`Partial list: ${coverage.sampled} of ${coverage.enumerated} seen (${text})`);
+	}
+	if (snapshot.cpu.state === "unavailable") parts.push("Host CPU unavailable");
+	// The first observation is always a baseline; persistent warming (e.g. frozen counters) is explained.
+	else if (snapshot.cpu.state === "warming" && !baseline) parts.push(`Host CPU warming: ${snapshot.cpu.reason}`);
+	return parts.length ? parts.join(" · ") : undefined;
+}
+
+/**
+ * Explain expected platform limits so unknown metrics are not mistaken for zero.
+ * @param snapshot Producer snapshot and availability states.
+ * @returns User-facing platform hint, or undefined when unnecessary.
+ */
+function hint(snapshot: ResourceSnapshot): string | undefined {
+	const parts: string[] = [];
+	const { coverage } = snapshot;
+	if (!coverage.complete && coverage.reasons.length && coverage.reasons.every((reason) => reason === ROUTINE_SKIP))
+		parts.push(`${coverage.enumerated - coverage.sampled} skipped: kernel threads, exited or unreadable`);
+	const unknown = snapshot.processes.filter((p) => p.name === "").length;
+	if (unknown) parts.push(`${unknown} ${unknown === 1 ? "name" : "names"} unknown (no access, e.g. other users)`);
+	if (processCpuUnavailable(snapshot))
+		parts.push(snapshot.platform === "darwin" ? "macOS: process CPU unavailable (see ?)" : "Process CPU unavailable");
+	return parts.length ? parts.join(" · ") : undefined;
+}
+
+/**
+ * Map one typed sampler snapshot without inventing zeros for warming/unavailable values.
+ * `baseline` marks a source's first observation, whose warming CPU needs no explanation.
+ * @param snapshot Typed producer snapshot including optional native metrics.
+ * @param baseline Whether this is the source's first observation.
+ * @returns View snapshot preserving unknown/failed metrics and measurement basis.
+ */
+export function toMonSnapshot(snapshot: MemorySnapshot, baseline = true): MonSnapshot {
+	const total = finite(snapshot.memory.totalBytes);
+	const free = finite(snapshot.memory.freeBytes);
+	const usage = snapshot.memory.usage;
+	const swap = snapshot.memory.swap;
+	const measuredUsed = usage?.state === "available" ? finite(usage.value.usedBytes) : null;
+	const nativeUsed =
+		measuredUsed !== null && measuredUsed >= 0 && total !== null && total > 0 && measuredUsed <= total
+			? measuredUsed
+			: null;
+	const swapUsed = swap?.state === "available" ? finite(swap.value.usedBytes) : null;
+	const swapTotal = swap?.state === "available" ? finite(swap.value.totalBytes) : null;
+	const validSwap = swapUsed !== null && swapTotal !== null && swapUsed >= 0 && swapTotal >= swapUsed;
+	const text = notice(snapshot, baseline);
+	const note = hint(snapshot);
+	return {
+		cpuPercent: snapshot.cpu.state === "available" ? finite(snapshot.cpu.value) : null,
+		logicalCpus: snapshot.logicalCpus,
+		memoryUsedBytes: usage
+			? nativeUsed
+			: total !== null && total > 0 && free !== null && free >= 0 && free <= total
+				? total - free
+				: null,
+		memoryTotalBytes: total !== null && total > 0 ? total : null,
+		memoryBasis: usage ? "app+wired+compressed" : "total-free",
+		memoryFreeBytes: free !== null && free >= 0 ? free : null,
+		swapUsedBytes: validSwap ? swapUsed : null,
+		swapTotalBytes: validSwap ? swapTotal : null,
+		load: snapshot.loadAverage,
+		processes: snapshot.processes.map((p) => {
+			const state = nameState(snapshot, p.name);
+			return {
+				identity: p.identity,
+				pid: p.pid,
+				name: p.name,
+				...(state ? { nameState: state } : {}),
+				cpuPercent: p.cpu.state === "available" ? finite(p.cpu.value) : null,
+				rssBytes: finite(p.rssBytes),
+				footprintBytes: p.footprint?.state === "available" && p.footprint.value >= 0 ? finite(p.footprint.value) : null,
+			};
+		}),
+		capturedAt: snapshot.wallTimeMs,
+		sampledAtMs: snapshot.monotonicTimeMs,
+		scanMs: finite(snapshot.durationMs),
+		// A resolved sample is a successful collection, whatever its CPU state.
+		status: "live",
+		cpuState: snapshot.cpu.state,
+		...(processCpuUnavailable(snapshot) ? { processCpu: "unavailable" as const } : {}),
+		...(text ? { notice: text } : {}),
+		...(note ? { hint: note } : {}),
+	};
+}
+
+/**
+ * Own one sampler per open interaction; its baseline/cleanup end with the view.
+ * @param create Sampler factory, injectable for lifecycle tests.
+ * @returns Disposable view source with first-observation baseline tracking.
+ */
+export function createSamplerSource(
+	create: (options?: SamplerOptions) => ResourceSampler = createResourceSampler,
+): MonSource {
+	const sampler = create();
+	let observed = 0;
+	return {
+		sample: async (signal) => toMonSnapshot(await sampler.sample(signal), observed++ === 0),
+		dispose: () => sampler.dispose(),
+	};
+}

package/src/monitor/process.ts

@@ -78,7 +78,8 @@ function wrap(child: ChildProcess, opts: SpawnOptions): MonitorProcess {
 	let hardTimer: NodeJS.Timeout | undefined;
 	let drainTimer: NodeJS.Timeout | undefined;
 	let exit: ExitInfo | undefined;
-	let finish: (info: ExitInfo) => void = () => {};
+	// The native Promise executor assigns this synchronously, before any child handlers register.
+	let finish!: (info: ExitInfo) => void;
 	const exited = new Promise<ExitInfo>((resolve) => {
 		finish = resolve;
 	});

package/src/monitor/validate.ts

@@ -2,7 +2,7 @@
 
 export const MAX_MONITORS = 5;
 export const DEFAULT_TIMEOUT_S = 3600;
-export const MAX_TIMEOUT_S = 86_400;
+export const MAX_TIMEOUT_S = 604_800;
 export const MAX_NAME_LENGTH = 40;
 export const MAX_MATCH_LENGTH = 500;
 const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;

package/src/stats/chart.ts

@@ -96,7 +96,9 @@ export function bucketize(
  */
 export function niceStep(x: number): number {
 	if (!(x > 1)) return 1;
-	const exp = 10 ** Math.floor(Math.log10(x));
+	if (!Number.isFinite(x)) return Number.POSITIVE_INFINITY;
+	// Parse decimal powers directly: exponentiation accuracy differs across JS engines.
+	const exp = Number(`1e${Math.floor(Math.log10(x))}`);
 	for (const m of NICE) {
 		const step = m * exp;
 		if (Number.isInteger(step) && step >= x - 1e-9 * exp) return step;

package/src/stats/cli.ts

@@ -1,9 +1,12 @@
 /** Standalone data-only CLI. Bundles the parser; never imports Pi or the private extension entrypoint. */
+import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
 import { agentDir } from "./load.ts";
 import { exportStats, importStats } from "./snapshot.ts";
 
-async function main(): Promise<void> {
+/** Parse the portable CLI argv, run its selected operation, and report JSON to stdout. */
+export async function main(): Promise<void> {
 	const [command, ...args] = process.argv.slice(2);
 	const options = new Map<string, string>();
 	for (let i = 0; i < args.length; i += 2) {
@@ -44,7 +47,23 @@ async function main(): Promise<void> {
 			"usage: export --agent-dir DIR --output OUT [--sessions-dir DIR] | import --agent-dir DIR --input REPO",
 		);
 }
-main().catch((error: unknown) => {
-	console.error(error instanceof Error ? error.message : "Stats operation failed");
-	process.exitCode = 1;
-});
+/** Run `main`, converting failures to one diagnostic and a nonzero process exit code. */
+export async function run(): Promise<void> {
+	try {
+		await main();
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : "Stats operation failed");
+		process.exitCode = 1;
+	}
+}
+
+/** Importers may supply an absent or unresolvable entrypoint, which must not prevent import. */
+function isEntrypoint(): boolean {
+	try {
+		return !!process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+	} catch {
+		return false;
+	}
+}
+
+if (isEntrypoint()) void run();