@nredd/pi-session-kit 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## 0.8.0
+
+- Add `/mon`: a read-only TUI dashboard of host CPU history, non-free memory, load and sampled processes, on by default (`mon.enabled`)
+- Depend on the exact published `@nredd/pi-resource-sampler@0.1.1` (executable names, never argv or process titles; Bun host CPU measured), locked as a nested registry install so tests never borrow the workspace copy; one sampler per open view, disposed (children reaped, no timers) on close, session shutdown or replacement
+- Map warming/unavailable metrics to `--`, never zero; split warnings (budget-limited lists, unavailable host CPU) from muted platform hints (Linux kernel-thread skips, unknown names, macOS process CPU)
+- Render unreadable names as `(unknown)` and mark macOS names that may be cut at 16 bytes with `…`
+- Header shows collector state with the last successful collection's local time; every resolved sample counts as live, separate from host CPU `warming`/`unavailable`
+- Side-by-side cards from 72 columns with a two-row CPU history at the observed monotonic interval; process table `PID CPU% RSS MEM% NAME` with a selection marker and overflow scrollbar
+- Pack `docs/mon-dashboard.md`, which the README links
+
 ## 0.7.0
 
 - Add a `/stats` **Machines** tab (Tab/Shift-Tab): each known machine's label and opaque UUID, local scan status, and remote producer `exportedAt` UTC instant plus age at opening

package/README.md

@@ -3,20 +3,25 @@
 Published to npm as `@nredd/pi-session-kit` (public). From `0.4.0`, each version is cut by the monorepo `Publish` workflow from a signed `@nredd/pi-session-kit@<version>` tag, with npm provenance and a GitHub release carrying the tarball, checksums and manifest (`docs/releases.md`); earlier versions were published manually without provenance. `0.4.0` adds `createSessionKit(options)` (explicit `config`, `agentDir`, `monitorRoot`, injectable `clock` and `spawnMonitor`; the default export is unchanged) and fixes leaderless orphan-group sweeps at `ps` start-time resolution. `0.5.0` redesigns `/stats` around the full pane (pinned header, aligned stat cells, a Models table on wide panes) and gives every chart a clock- or calendar-aligned time axis, including the 5h and 24h hourly views.
 Use the [monorepo development commands](https://github.com/nredd/pi-harness/blob/main/README.md). The Git install and standalone harness
 references below describe the legacy deployment, not installation or candidate verification of
-this package. `0.6.0` keeps passive monitor output only in the monitor ring buffer rather than adding it to the transcript or model context; `monitor_read` is the explicit output surface, and match/exit/timeout wakes are compact summaries with a cursor. `0.7.0` adds the `/stats` Machines tab with per-machine producer export age, separate from the viewer's last import, and the collapsible monitors widget.
+this package. `0.6.0` keeps passive monitor output only in the monitor ring buffer rather than adding it to the transcript or model context; `monitor_read` is the explicit output surface, and match/exit/timeout wakes are compact summaries with a cursor. `0.7.0` adds the `/stats` Machines tab with per-machine producer export age, separate from the viewer's last import, and the collapsible monitors widget. `0.8.0` adds `/mon`.
 
 ## Standalone use
 
-The packed tarball is self-contained: Pi host modules (`@earendil-works/pi-*`, `typebox`) are `*` peers supplied by Pi, there are no runtime dependencies and no sibling plugin is required. Verified by installing the tarball alone and running it in exact stock Pi 1.3.0 (see the repository's `docs/package-contracts.md`). Optional fork integrations (subagents, Plan mode) are absent in that setup; the exercised behavior does not need them.
+The packed tarball is self-contained: Pi host modules (`@earendil-works/pi-*`, `typebox`) are `*` peers supplied by Pi, and no sibling plugin is required. Its only runtime dependency is the exact published `@nredd/pi-resource-sampler@0.1.1` library (no Pi imports), which npm installs from the registry for `/mon`. Verified by installing the tarball alone and running it in exact stock Pi 1.3.0 (see the repository's `docs/package-contracts.md`). Optional fork integrations (subagents, Plan mode) are absent in that setup; the exercised behavior does not need them.
 
 Session-scoped pi extensions for tmux users. No daemon, supervisor, core patch or cross-pane
 registry. Each runtime owns its goal, loops and monitors; persisted goal state follows the active
 session branch. Closing pi stops its work.
 
+`/mon` opens a read-only, full-pane view of local CPU, memory, load and processes, sampled
+every ~2s by the shared `@nredd/pi-resource-sampler` library only while it is open. Details and
+limits (macOS process CPU is unavailable, macOS names keep 16 bytes, memory is non-free, partial coverage) are in
+[docs/mon-dashboard.md](docs/mon-dashboard.md). It is not a second `/monitor` process runner.
+
 ## Install and config
 
 ```sh
-pi install npm:@nredd/pi-session-kit@0.7.0
+pi install npm:@nredd/pi-session-kit@0.8.0
 ```
 
 Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
@@ -29,7 +34,8 @@ Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
   "loop": { "enabled": true },
   "monitor": { "enabled": true, "collapseKey": "ctrl+shift+m", "maxWidgetLines": 12 },
   "diff": { "enabled": true },
-  "stats": { "enabled": true }
+  "stats": { "enabled": true },
+  "mon": { "enabled": true }
 }
 ```
 

package/docs/mon-dashboard.md

@@ -0,0 +1,123 @@
+# /mon resource dashboard
+
+`/mon` is a read-only, interactive-TUI view of local host resources. It is on by default and
+disabled with `{ "mon": { "enabled": false } }` in `pi-session-kit.json`. In RPC/print/JSON modes
+it only warns; it never samples there.
+
+## Source
+
+`src/mon/source.ts` is a thin mapping over the published `@nredd/pi-resource-sampler`, declared
+as the exact runtime dependency `0.1.1` (`0.1.0` leaked argv-style process titles as macOS names
+and could fake Bun host CPU). No collector lives in session-kit. Each open view creates
+one sampler (its own CPU baseline) and disposes it on close; disposal aborts and awaits any active
+sample, including its `ps` child on macOS. Mapping rules:
+
+- Collector success and host CPU state are separate. Every resolved sample is `LIVE` and refreshes
+  the last-success time, even while host CPU is `warming` or `unavailable`, because its memory,
+  load and process data are fresh. The CPU readout then says `-- warming` or `-- unavailable`.
+  The header pairs the state (`● LIVE`, `○ WAITING`, `▲ STALE`) with the local wall time of the
+  last successful collection (`updated HH:MM:SS`, `last ok` when stale), so freshness is never
+  inferred from the CPU state.
+- `warming` and `unavailable` metrics become `--`, never zero. The first observation is a warming
+  baseline; persistent warming shows the sampler's reason (e.g. `Host CPU warming: CPU counters
+  have not advanced`).
+- Two diagnostic tones. A warning (`▲`, warning color) means a limit hides data the user would
+  expect: `Partial list: S of E seen (reasons)` for budget caps or collector failures (at most three
+  reasons, in words: `time budget`, `process cap`, `read budget`, `ps failed`, ...), unavailable host
+  CPU, persistent warming. A muted hint states an expected platform limit: Linux always skips kernel
+  threads (no RSS) and processes that exit mid-scan, so a scan whose only reason is
+  `process-unreadable-or-changed` is `N skipped: kernel threads, exited or unreadable`, not a
+  warning; `N names unknown (no access, e.g. other users)`; macOS process CPU. The process header
+  counts *sampled* rows, not host processes.
+- Names are the sampler's executable basenames, never argv or process titles. `""` renders as a dim
+  `(unknown)` (Linux hides other users' `/proc/PID/exe` without ptrace access). macOS `p_comm` keeps
+  16 bytes, so a macOS name of 16+ UTF-8 bytes ends in a dim `…` (`Google Chrome He…`): possibly cut,
+  never claimed complete. Names stay untrusted text: sanitized, never interpreted.
+- macOS process interval CPU is always unavailable (the sampler's `ps` start time has one-second
+  precision, so PID reuse cannot be excluded). The view says so, explains it in help, and orders by
+  RSS until the user picks a sort. Linux first samples are warming, so CPU order stays stable.
+- History spacing uses the sampler's monotonic `monotonicTimeMs`, so wall-clock steps (NTP, manual
+  changes) cannot invent or hide gaps; the wall `wallTimeMs` is only displayed (header clock and
+  last-success UTC).
+  Node's monotonic clock pauses during system sleep on macOS and Linux, so a suspend shows no gap.
+  `scan Nms` (80+ columns) is the sampler's collection duration. Missing/zero memory totals and non-finite values become unknown.
+
+## Presentation
+
+- From 72 columns and 17 rows (one more per diagnostic line), CPU and memory/load cards sit side
+  by side; CPU history is two rows (16 levels) there. Narrower or shorter terminals get a
+  three-line summary (`CPU`, `RAM`, 1-minute load, one-row history); at six rows summary/chrome
+  yields to the selected process, but a compact partial-list or stopped/retry warning remains visible.
+  At eight rows, core CPU/RAM/load metrics take priority over optional history and platform hints.
+  Compact metrics tighten spacing when needed to keep CPU, RAM and the 1-minute load visible.
+  The last row reserves close/help. Below 60 columns the header
+  keeps the update clock over the tagline.
+- Columns: `PID`, `CPU%` (100 = one core), `RSS`, `MEM%` (RSS over total RAM, 60+ columns),
+  `NAME` last so long names never push numbers off screen. `--` is dimmed. A `▸` marks the
+  selection; a theme scrollbar appears only when the list overflows. The memory card adds 1-minute
+  load per logical CPU.
+- Host CPU severity colors the value (success under 50%, warning under 85%, error above) next to
+  the number itself. Stale CPU retains the last measured value, muted rather than live severity-colored.
+  Cards add a `last value` label; compact summaries rely on the `STALE` header instead, reserving
+  the metric row for CPU, RAM and load.
+- Host CPU history keeps each capture timestamp, uses a fixed 0..100% scale and at most 120
+  samples, newest on the right. A column is the lower-median interval between captures, widened
+  only when the history is longer than the width, so completion-paced drift never invents gaps.
+  Columns with no CPU value after the first one are gaps (`·`), never zero or interpolation;
+  columns before it are blank, including the warming baseline. Stale snapshots add no point. The caption states the actual span. The latest sample in a bucket wins.
+  Stale views show the last successful capture's UTC timestamp (or `none`). Waiting/live/stale and
+  CPU warming/unavailable use semantic theme colors and text, so meaning does not depend on color.
+- Memory is total minus free, explicitly **non-free**, not available memory or a pressure score
+  (on macOS free pages are small by design). Load averages are not percentages. Process CPU is
+  interval CPU, where 100% is one logical CPU and multithreaded processes can exceed 100%.
+- The process viewport preserves selection by sampler identity, not PID or sorted row.
+  Exited identities choose a bounded neighboring row; PID reuse cannot inherit selection.
+  Unknown/non-finite measurements sort last with deterministic PID/identity tie breaks.
+- `j/k` and arrows select; PageUp/PageDown page; `g/G` jump first/last; `c/m/p` sort
+  CPU/RSS/PID; `s` cycles sort; `?` toggles help; `q`/Escape close. CPU/RSS descend,
+  PID ascends. Help has a bounded, wrapped viewport with a visible range and scroll hint;
+  `j/k`, arrows, PageUp/PageDown and `g/G` scroll help without moving the process selection.
+  No kill, locks, workload control, process arguments or environment display. Process names
+  are the sampler's sanitized display names and are never interpreted.
+
+## Ownership
+
+`MonView` accepts presentation snapshots and never collects data. It caches rendered lines
+by dimensions until update/input/theme invalidation. `MonPoll` owns one completion-paced probe
+(~2s after the previous one completed), with no catch-up queue. Closing aborts collection,
+cancels the timeout and awaits the sampler's disposal. Errors stop collection and retain
+explicitly stale values; reopening is the retry mechanism. Late results are discarded.
+
+`registerMon` opens a source only inside a TUI interaction and serializes replacement through
+completed asynchronous disposal, including concurrent opens. Session shutdown/start invalidates
+pending openers before they can create a source, even when Pi defers the UI factory. It registers
+no model tool, persists no history, sends no model messages and does no network work.
+
+## Verification
+
+- `npm run check` in `packages/session-kit`. The root lock pins a nested registry install
+  (`packages/session-kit/node_modules/@nredd/pi-resource-sampler`, exact `0.1.1` tarball and
+  integrity), so tests run the published bytes, not the same-version workspace that npm would
+  otherwise link. `source.test.ts` fails if resolution ever reaches the workspace.
+  - `test/mon/source.test.ts`: two actual host observations (warming, then measured), a real poll's
+    two updates, and mapping edge cases. In-flight close wraps the real sampler to hold its pending
+    sample, then requires that sample to reject with `AbortError`, no update, no child and no timer.
+    On macOS it first requires the sampler's live `ps` child; Linux reads `/proc` in process, so
+    there the `AbortError` is the only provider evidence and no child is claimed.
+  - `test/mon/theme.test.ts`: actual built-in dark and light themes over an actual observation at
+    40x12, 60x20, 80x24 and 120x40.
+  - `test/scenarios/mon.test.ts` (Vitest and Bun): the real interactive Pi host, `createSessionKit`
+    and the real sampler; two observations, resize matrix, close/Escape/reopen, close before the
+    first sample and session shutdown all leave no kit timer or child process.
+  - `test/mon/{component,poll,index}.test.ts`: layout, identity, history, lifecycle interleavings
+    with fakes; `resource-fixture.ts` is type-checked against the package's `ResourceSnapshot`.
+- `make check-package-contracts` packs session-kit, installs it alone (sampler from npm, exact
+  lockfile closure) and drives it through stock Pi.
+- Real macOS terminal recordings exercise the packed, registry-backed view, resize, navigation,
+  close and reopen. Empty direct-child lists before and after close show only that no child was
+  observed at those instants; they do NOT prove an in-flight helper was cancelled or reaped.
+  In-flight cancellation/reaping evidence comes from the deterministic real-sampler tests above,
+  not those terminal snapshots. No Linux terminal recording is claimed.
+- Manual fixture preview (no sampling): `bun test/mon/terminal.ts dark|light`. It is labelled
+  `FIXTURE DATA` and uses `fixture-*` names, so a capture can never pass for host data; it is not
+  evidence of real measurements.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -12,6 +12,7 @@
     "src",
     "dist/pi-stats-export.mjs",
     "docs/stats-snapshots.md",
+    "docs/mon-dashboard.md",
     "CHANGELOG.md",
     "LICENSE",
     "README.md"
@@ -25,6 +26,9 @@
     "pi-package",
     "pi-extension"
   ],
+  "dependencies": {
+    "@nredd/pi-resource-sampler": "0.1.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",

package/src/config.ts

@@ -9,7 +9,7 @@ import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 
-export const FEATURES = ["titles", "rules", "goal", "loop", "monitor", "diff", "stats"] as const;
+export const FEATURES = ["titles", "rules", "goal", "loop", "monitor", "diff", "stats", "mon"] as const;
 export type Feature = (typeof FEATURES)[number];
 
 export interface KitConfig {

package/src/index.ts

@@ -9,6 +9,8 @@ import { configPath, type Feature, type KitConfig, loadConfig } from "./config.t
 import { register as registerDiff } from "./diff/index.ts";
 import { register as registerGoal } from "./goal/index.ts";
 import { register as registerLoop } from "./loop/index.ts";
+import { registerMon } from "./mon/index.ts";
+import { createSamplerSource } from "./mon/source.ts";
 import { register as registerMonitor } from "./monitor/index.ts";
 import type { MonitorProcess, SpawnOptions } from "./monitor/process.ts";
 import { register as registerRules } from "./rules/index.ts";
@@ -20,7 +22,7 @@ export interface SessionKitOptions {
 	config?: KitConfig;
 	agentDir?: string;
 	monitorRoot?: string;
-	/** Time for stats ranges, loops, goal wakes and monitor batching/timeouts. Defaults to real time. */
+	/** Time for stats ranges, loops, goal wakes, monitor batching/timeouts and /mon cadence. Defaults to real time. */
 	clock?: Clock;
 	/** Child boundary only; validation, matching, ring buffering and message delivery stay in the manager. */
 	spawnMonitor?: (argv: readonly string[], options: SpawnOptions) => Promise<MonitorProcess>;
@@ -37,6 +39,7 @@ const MODULES: Record<Feature, Register> = {
 		registerMonitor(pi, config, options.monitorRoot, { clock: options.clock, spawnMonitor: options.spawnMonitor }),
 	diff: registerDiff,
 	stats: (pi, config, options) => registerStats(pi, config, options),
+	mon: (pi, _config, options) => registerMon(pi, { createSource: () => createSamplerSource(), clock: options.clock }),
 };
 
 /** Create the real kit without requiring a machine-local agent configuration. */

package/src/mon/component.ts

@@ -0,0 +1,486 @@
+/** Responsive, cached /mon dashboard. Rendering and navigation never collect resources. */
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import {
+	type Component,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+import { fitCols, sanitize } from "../diff/view.ts";
+import {
+	bytes,
+	type MonHistoryPoint,
+	type MonProcess,
+	type MonSnapshot,
+	type MonSort,
+	percent,
+	SORTS,
+	share,
+	sortProcesses,
+	timeHistory,
+	timeHistoryRows,
+} from "./model.ts";
+
+export interface MonViewOptions {
+	theme: Pick<Theme, "fg" | "bold" | "bg">;
+	rows: () => number;
+	requestRender: () => void;
+	onClose: () => void;
+}
+
+type Color = Parameters<Theme["fg"]>[0];
+
+/** Cards need this much room; below it a three-line summary keeps the process list usable. */
+const CARD_MIN_WIDTH = 72;
+const CARD_MIN_HEIGHT = 17;
+const HISTORY_LIMIT = 120;
+
+const HELP = [
+	"*Keys",
+	" j/k or arrows   select process",
+	" PgUp/PgDn       move one page",
+	" g/G             first/last",
+	" c CPU  m RSS    descending",
+	" p PID           ascending",
+	" s               cycle sort",
+	" ?               back to dashboard",
+	" q/Esc           close",
+	"",
+	"*Reading it",
+	" LIVE: the last collection succeeded;",
+	" updated HH:MM:SS is when (local).",
+	" CPU warming: first interval baseline,",
+	" not a stale or failed sample.",
+	" CPU is interval usage, not lifetime.",
+	" Process CPU can exceed 100% (one core).",
+	" -- is unavailable, never zero.",
+	" RAM is total minus free, not pressure.",
+	" MEM% is RSS over total RAM.",
+	" Load 1/5/15 min: not percent.",
+	" History: elapsed time, newest right;",
+	" dots are gaps, blank is no data yet.",
+	"",
+	"*Processes",
+	" Names are executable files, never",
+	" arguments; still untrusted text.",
+	" (unknown): no access, e.g. another",
+	" user's process on Linux.",
+	" macOS keeps 16 bytes of a name;",
+	" a trailing … marks a possible cut.",
+	" macOS: ps start time is whole seconds,",
+	" so process CPU stays -- (sort: RSS).",
+	" Lists can be partial; notices say why.",
+	" Selection follows identity, not row.",
+	" No kill, locks or scheduling.",
+];
+
+/** Local wall clock `HH:MM:SS`, display only. */
+function clock(ms: number): string {
+	const d = new Date(ms);
+	return [d.getHours(), d.getMinutes(), d.getSeconds()].map((n) => String(n).padStart(2, "0")).join(":");
+}
+
+/** Single-interaction view; update is the sole ingress for sampler data. */
+export class MonView implements Component {
+	private snapshot: MonSnapshot | undefined;
+	private history: MonHistoryPoint[] = [];
+	private lastSuccess: number | undefined;
+	private helpScroll = 0;
+	private helpPageSize = 1;
+	private helpLength = 0;
+	private processes: MonProcess[] = [];
+	private selected: string | undefined;
+	private sort: MonSort = "cpu";
+	private sortChosen = false;
+	private help = false;
+	private scroll = 0;
+	private pageSize = 1;
+	private cache: { width: number; height: number; lines: string[] } | undefined;
+
+	constructor(private readonly options: MonViewOptions) {}
+
+	get state(): { selected: string | undefined; sort: MonSort; historyLength: number; scroll: number } {
+		return { selected: this.selected, sort: this.sort, historyLength: this.history.length, scroll: this.scroll };
+	}
+
+	update(snapshot: MonSnapshot): void {
+		this.snapshot = snapshot;
+		// Collector success is independent of CPU: a warming sample still carries fresh memory/processes.
+		// A stale snapshot is not a new measurement, so it adds no history point.
+		if (snapshot.status === "live") {
+			this.lastSuccess = snapshot.capturedAt;
+			// Leading samples without a CPU value are "no data yet" (blank), not gaps.
+			if (snapshot.cpuPercent !== null || this.history.length > 0) {
+				this.history.push({ sampledAtMs: snapshot.sampledAtMs, value: snapshot.cpuPercent });
+				if (this.history.length > HISTORY_LIMIT) this.history.shift();
+			}
+		}
+		// Never rank by a column that is unavailable for every row, unless the user asked for it.
+		if (!this.sortChosen) this.sort = snapshot.processCpu === "unavailable" ? "rss" : "cpu";
+		this.reorder();
+		this.refresh();
+	}
+
+	invalidate(): void {
+		this.cache = undefined;
+	}
+
+	private refresh(): void {
+		this.invalidate();
+		this.options.requestRender();
+	}
+
+	private reorder(): void {
+		const oldIndex = Math.max(
+			0,
+			this.processes.findIndex((p) => p.identity === this.selected),
+		);
+		this.processes = sortProcesses(this.snapshot?.processes ?? [], this.sort);
+		if (!this.processes.some((p) => p.identity === this.selected)) {
+			this.selected = this.processes[Math.min(oldIndex, this.processes.length - 1)]?.identity;
+		}
+	}
+
+	handleInput(data: string): void {
+		if (data === "q" || matchesKey(data, Key.escape) || matchesKey(data, Key.ctrl("c"))) {
+			this.options.onClose();
+			return;
+		}
+		let index = Math.max(
+			0,
+			this.processes.findIndex((p) => p.identity === this.selected),
+		);
+		if (data === "?") this.help = !this.help;
+		else if (this.help) {
+			if (data === "j" || matchesKey(data, Key.down)) this.helpScroll++;
+			else if (data === "k" || matchesKey(data, Key.up)) this.helpScroll--;
+			else if (matchesKey(data, Key.pageDown)) this.helpScroll += this.helpPageSize;
+			else if (matchesKey(data, Key.pageUp)) this.helpScroll -= this.helpPageSize;
+			else if (data === "g" || matchesKey(data, Key.home)) this.helpScroll = 0;
+			else if (data === "G" || matchesKey(data, Key.end)) this.helpScroll = this.helpLength;
+			else return;
+			this.helpScroll = Math.max(0, Math.min(this.helpScroll, this.helpLength - this.helpPageSize));
+		} else if (data === "c" || data === "m" || data === "p" || data === "s") {
+			this.sortChosen = true;
+			this.sort =
+				data === "c"
+					? "cpu"
+					: data === "m"
+						? "rss"
+						: data === "p"
+							? "pid"
+							: (SORTS[(SORTS.indexOf(this.sort) + 1) % SORTS.length] ?? "cpu");
+			this.reorder();
+		} else {
+			if (data === "j" || matchesKey(data, Key.down)) index++;
+			else if (data === "k" || matchesKey(data, Key.up)) index--;
+			else if (matchesKey(data, Key.pageDown)) index += this.pageSize;
+			else if (matchesKey(data, Key.pageUp)) index -= this.pageSize;
+			else if (data === "g" || matchesKey(data, Key.home)) index = 0;
+			else if (data === "G" || matchesKey(data, Key.end)) index = this.processes.length - 1;
+			else return;
+			this.selected = this.processes[Math.max(0, Math.min(this.processes.length - 1, index))]?.identity;
+		}
+		this.refresh();
+	}
+
+	/** `--` reads as absent, not as a value: dim it everywhere. */
+	private value(text: string, width: number): string {
+		const padded = text.padStart(width);
+		return text === "--" ? this.options.theme.fg("dim", padded) : padded;
+	}
+
+	/** Host CPU severity, always paired with the number so meaning never depends on color. */
+	private cpuColor(value: number | null): Color {
+		return value === null ? "dim" : value >= 85 ? "error" : value >= 50 ? "warning" : "success";
+	}
+
+	private panel(title: string, lines: string[], width: number): string[] {
+		const { theme } = this.options;
+		const inner = Math.max(0, width - 2);
+		const label = truncateToWidth(`─ ${title} `, inner, "…");
+		return [
+			theme.fg("border", "╭") +
+				theme.fg("accent", label) +
+				theme.fg("border", `${"─".repeat(Math.max(0, inner - visibleWidth(label)))}╮`),
+			...lines.map((line) => theme.fg("border", "│") + fitCols(line, inner) + theme.fg("border", "│")),
+			theme.fg("border", `╰${"─".repeat(inner)}╯`),
+		];
+	}
+
+	/** Compact mode omits capacity and the stale suffix; the header already labels every metric STALE. */
+	private cpuSummary(capacity = true): string {
+		const t = this.options.theme;
+		const s = this.snapshot;
+		const value = s?.cpuPercent ?? null;
+		const state = !capacity && s?.status === "stale" ? "" : this.cpuState();
+		const head =
+			value === null
+				? t.fg("dim", "--")
+				: s?.status === "stale"
+					? t.fg("muted", percent(value))
+					: t.bold(t.fg(this.cpuColor(value), percent(value)));
+		if (!capacity) return `${head}${state}`;
+		return `${head}${state} ${t.fg("muted", `${state ? "·" : "of"} ${s?.logicalCpus || "--"} logical CPUs`)}`;
+	}
+
+	private loads(): string {
+		const load = this.snapshot?.load ?? [];
+		return load.length ? load.map((n) => (Number.isFinite(n) ? n.toFixed(2) : "--")).join(" ") : "--";
+	}
+
+	private cards(width: number): string[] {
+		const s = this.snapshot;
+		const t = this.options.theme;
+		const leftWidth = Math.floor((width - 2) * 0.58);
+		const rightWidth = width - leftWidth - 2;
+		const chartWidth = leftWidth - 4;
+		const total = s?.memoryTotalBytes ?? null;
+		const used = s?.memoryUsedBytes ?? null;
+		const ratio = total && used !== null ? Math.max(0, Math.min(1, used / total)) : null;
+		const meterWidth = Math.max(1, Math.min(28, rightWidth - 9));
+		const full = ratio === null ? 0 : Math.round(ratio * meterWidth);
+		const load1 = s?.load[0];
+		const perCpu =
+			typeof load1 === "number" && Number.isFinite(load1) && s?.logicalCpus ? (load1 / s.logicalCpus).toFixed(2) : "--";
+		const cpu = this.panel(
+			"CPU / interval",
+			[
+				` ${this.cpuSummary()}`,
+				...timeHistoryRows(this.history, chartWidth, 2).map((row) => ` ${t.fg("accent", row)}`),
+				` ${t.fg("dim", this.historyLabel())}`,
+			],
+			leftWidth,
+		);
+		const memory = this.panel(
+			"MEMORY / load",
+			[
+				` ${t.bold(bytes(used))} ${t.fg("muted", `/ ${bytes(total)} non-free`)}`,
+				` ${t.fg("accent", "━".repeat(full))}${t.fg("borderMuted", "─".repeat(meterWidth - full))} ${ratio === null ? t.fg("dim", "--") : `${Math.round(ratio * 100)}%`}`,
+				` ${t.fg("muted", "load")} ${this.loads()}`,
+				` ${t.fg("muted", "1/5/15 min ·")} ${perCpu === "--" ? t.fg("dim", perCpu) : perCpu} ${t.fg("muted", "per CPU")}`,
+			],
+			rightWidth,
+		);
+		return cpu.map((line, i) => `${line}  ${memory[i] ?? ""}`);
+	}
+
+	/** Compact three-line summary when cards do not fit. */
+	private summary(width: number): string[] {
+		const s = this.snapshot;
+		const t = this.options.theme;
+		const total = s?.memoryTotalBytes ?? null;
+		const used = s?.memoryUsedBytes ?? null;
+		const ram = `${bytes(used)}/${bytes(total)}`;
+		const metrics = [
+			`${t.fg("muted", "CPU")} ${this.cpuSummary(false)}`,
+			`${t.fg("muted", "RAM")} ${ram}`,
+			`${t.fg("muted", "load")} ${this.loads().split(" ")[0]}`,
+		];
+		const spaced = ` ${metrics.join("  ")}`;
+		return [
+			visibleWidth(spaced) <= width ? spaced : metrics.join(" "),
+			` ${t.fg("accent", timeHistory(this.history, width - 2))}`,
+			` ${t.fg("dim", this.historyLabel())}`,
+		];
+	}
+
+	/** Why host CPU reads `--`; textual, so meaning never depends on color. */
+	private cpuState(): string {
+		if (this.snapshot?.status === "stale") return ` ${this.options.theme.fg("muted", "last value")}`;
+		const state = this.snapshot?.cpuState;
+		return state === "warming" || state === "unavailable" ? ` ${this.options.theme.fg("warning", state)}` : "";
+	}
+
+	private historyLabel(): string {
+		const span = Math.max(0, (this.history.at(-1)?.sampledAtMs ?? 0) - (this.history[0]?.sampledAtMs ?? 0));
+		return `0..100% · ${(span / 1000).toFixed(1)}s span · time →`;
+	}
+
+	/** Title, collector state, and when the shown data was collected. */
+	private header(width: number): string {
+		const t = this.options.theme;
+		const status = this.snapshot?.status ?? "waiting";
+		const [mark, color]: [string, Color] =
+			status === "live" ? ["●", "success"] : status === "stale" ? ["▲", "warning"] : ["○", "warning"];
+		const left =
+			t.bold(t.fg("accent", " MON")) +
+			`  ${t.fg(color, `${mark} ${status.toUpperCase()}`)}` +
+			// Narrow terminals keep freshness over the tagline.
+			(width >= 60 ? t.fg("dim", "  local resources · read only") : "");
+		const scan = this.snapshot?.scanMs;
+		const parts: string[] = [];
+		if (this.lastSuccess !== undefined)
+			parts.push(
+				width >= 60
+					? `${status === "stale" ? "last ok" : "updated"} ${clock(this.lastSuccess)}`
+					: clock(this.lastSuccess),
+			);
+		if (width >= 80 && typeof scan === "number" && Number.isFinite(scan) && status === "live")
+			parts.push(`scan ${Math.round(scan)}ms`);
+		const right = parts.length ? t.fg("muted", `${parts.join(" · ")} `) : "";
+		const gap = width - visibleWidth(left) - visibleWidth(right);
+		return gap >= 2 ? `${left}${" ".repeat(gap)}${right}` : left;
+	}
+
+	private footer(width: number): string {
+		const t = this.options.theme;
+		const keys: [string, string][] = this.help
+			? [
+					["q/Esc", "close"],
+					["?", "help"],
+					["j/k PgDn", "scroll"],
+				]
+			: width < 60
+				? [
+						["q/Esc", "close"],
+						["?", "help"],
+						["s", "sort"],
+					]
+				: [
+						["q/Esc", "close"],
+						["?", "help"],
+						["j/k", "move"],
+						["PgUp/PgDn", "page"],
+						["c/m/p", "sort"],
+					];
+		return ` ${keys.map(([key, label]) => `${t.fg("accent", key)} ${t.fg("muted", label)}`).join("  ")}`;
+	}
+
+	/** Process name cell: dim `(unknown)` for no name, dim `…` where the OS may have cut it. */
+	private nameCell(p: MonProcess): string {
+		const t = this.options.theme;
+		if (p.nameState === "unknown" || p.name === "") return t.fg("dim", "(unknown)");
+		const name = sanitize(p.name);
+		return p.nameState === "truncated" ? `${name}${t.fg("dim", "…")}` : name;
+	}
+
+	render(width: number): string[] {
+		const height = Math.max(1, this.options.rows());
+		width = Math.max(1, width);
+		if (this.cache?.width === width && this.cache.height === height) return this.cache.lines;
+		const t = this.options.theme;
+		const status = this.snapshot?.status ?? "waiting";
+		const footer = this.footer(width);
+		if (height === 1) return [fitCols(footer, width)];
+		const lines = [this.header(width)];
+		if (this.help) {
+			const help = HELP.map((line) =>
+				line.startsWith("*") ? t.bold(t.fg("accent", ` ${line.slice(1)}`)) : line,
+			).flatMap((line) => wrapTextWithAnsi(line, width));
+			this.helpPageSize = Math.max(1, height - 3);
+			this.helpLength = help.length;
+			this.helpScroll = Math.max(0, Math.min(this.helpScroll, help.length - this.helpPageSize));
+			lines.push(
+				t.fg(
+					"accent",
+					` HELP ${this.helpScroll + 1}-${Math.min(help.length, this.helpScroll + this.helpPageSize)}/${help.length}`,
+				),
+			);
+			lines.push(...help.slice(this.helpScroll, this.helpScroll + this.helpPageSize));
+		} else {
+			const notice = this.snapshot?.notice;
+			const hint = this.snapshot?.hint;
+			const compactNotice = notice?.startsWith("Partial list:")
+				? `Partial: ${notice.match(/\(([^)]+)\)/)?.[1] ?? "list incomplete"}`
+				: notice?.startsWith("Sampling stopped")
+					? "Stopped: reopen to retry"
+					: notice;
+			const diagnosticRows = Number(status === "stale") + Number(Boolean(notice)) + Number(Boolean(hint));
+			if (height >= CARD_MIN_HEIGHT + diagnosticRows && width >= CARD_MIN_WIDTH) lines.push(...this.cards(width));
+			else if (height >= 8) {
+				// Reserve a process row and actionable warnings before optional history/platform hints.
+				const warnings = Number(status === "stale") + Number(Boolean(notice));
+				lines.push(...this.summary(width).slice(0, Math.max(1, height - 5 - warnings)));
+			}
+			if (height >= 8) {
+				if (status === "stale")
+					lines.push(
+						t.fg(
+							"warning",
+							` Last success: ${this.lastSuccess === undefined ? "none" : new Date(this.lastSuccess).toISOString()}`,
+						),
+					);
+				if (notice) lines.push(t.fg("warning", ` ▲ ${sanitize(width < 60 ? (compactNotice ?? notice) : notice)}`));
+				if (hint && lines.length < height - 5) lines.push(t.fg("muted", ` ${sanitize(hint)}`));
+			} else if (notice && height >= 6) {
+				// One short warning must survive even when there is no room for the metric summary.
+				lines.push(t.fg("warning", ` ▲ ${sanitize(compactNotice ?? notice)}`));
+			}
+			lines.push(
+				`${t.bold(t.fg("accent", " PROCESSES"))}  ${t.fg("muted", `${this.processes.length} sampled`)}  ${t.fg("accent", `${this.sort.toUpperCase()} ${this.sort === "pid" ? "↑" : "↓"}`)}`,
+			);
+			this.table(lines, width, height);
+		}
+		const clipped = lines.slice(0, height - 1);
+		while (clipped.length < height - 1) clipped.push("");
+		clipped.push(footer);
+		const result = clipped.map((line) => fitCols(line, width));
+		this.cache = { width, height, lines: result };
+		return result;
+	}
+
+	/** Column header, the visible page of rows with a scrollbar when it overflows, and a position line. */
+	private table(lines: string[], width: number, height: number): void {
+		const t = this.options.theme;
+		const compact = width < 60;
+		const pidWidth = compact ? 6 : 7;
+		const cpuWidth = compact ? 7 : 8;
+		const rssWidth = compact ? 6 : 8;
+		const memWidth = compact ? 0 : 6;
+		// Rows after the header: position line and footer stay reserved.
+		this.pageSize = Math.max(1, height - lines.length - 3);
+		const overflow = this.processes.length > this.pageSize;
+		const rowWidth = width - (overflow ? 1 : 0);
+		const nameWidth = Math.max(1, rowWidth - 1 - pidWidth - cpuWidth - rssWidth - memWidth - 2);
+		const row = (mark: string, pid: string, cpu: string, rss: string, mem: string, name: string) =>
+			fitCols(
+				`${mark}${fitCols(pid, pidWidth)}${cpu}${rss}${memWidth ? mem : ""}  ${fitCols(name, nameWidth)}`,
+				rowWidth,
+			);
+		lines.push(
+			t.fg(
+				"muted",
+				row(" ", "PID", "CPU%".padStart(cpuWidth), "RSS".padStart(rssWidth), "MEM%".padStart(memWidth), "NAME"),
+			),
+		);
+		const index = Math.max(
+			0,
+			this.processes.findIndex((p) => p.identity === this.selected),
+		);
+		this.scroll = Math.min(this.scroll, Math.max(0, this.processes.length - this.pageSize));
+		if (index < this.scroll) this.scroll = index;
+		if (index >= this.scroll + this.pageSize) this.scroll = index - this.pageSize + 1;
+		const total = this.snapshot?.memoryTotalBytes ?? null;
+		const visible = this.processes.slice(this.scroll, this.scroll + this.pageSize);
+		const thumbSize = Math.max(1, Math.round((this.pageSize * this.pageSize) / Math.max(1, this.processes.length)));
+		const thumbAt = Math.round(
+			(this.scroll / Math.max(1, this.processes.length - this.pageSize)) * (this.pageSize - thumbSize),
+		);
+		visible.forEach((p, i) => {
+			const selected = p.identity === this.selected;
+			let text = row(
+				selected ? t.fg("accent", "▸") : " ",
+				String(p.pid),
+				this.value(percent(p.cpuPercent).replace("%", ""), cpuWidth),
+				this.value(bytes(p.rssBytes), rssWidth),
+				this.value(share(p.rssBytes, total), memWidth),
+				this.nameCell(p),
+			);
+			if (selected) text = t.bg("selectedBg", text);
+			if (overflow)
+				text += i >= thumbAt && i < thumbAt + thumbSize ? t.fg("scrollbarThumb", "┃") : t.fg("scrollbarTrack", "│");
+			lines.push(text);
+		});
+		if (this.processes.length === 0) lines.push(t.fg("dim", " Waiting for process sample..."));
+		if (lines.length < height - 1)
+			lines.push(
+				t.fg(
+					"dim",
+					` ${this.processes.length ? index + 1 : 0}/${this.processes.length} selected · CPU% 100 = one core${memWidth && total ? ` · MEM% of ${bytes(total)}` : ""}`,
+				),
+			);
+	}
+}

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,153 @@
+/** 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;
+}
+
+/** 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;
+	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"];
+
+/** Unknown/non-finite measurements sort last; ties are deterministic across refreshes. */
+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);
+	});
+}
+
+export function percent(value: number | null): string {
+	return value === null || !Number.isFinite(value) ? "--" : `${value.toFixed(1)}%`;
+}
+
+/** Process share of total RAM, from the same sample's RSS and total. */
+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)}`;
+}
+
+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.
+ */
+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) };
+}
+
+/** One-row history: blank before data, `·` for gaps. */
+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.
+ */
+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;
+}
+
+/** Fixed 0..100 host CPU scale: a quiet history must not look saturated. */
+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,121 @@
+/** Production /mon source: a thin mapping over the published shared sampler. No collector lives here. */
+import {
+	createResourceSampler,
+	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": "ps unavailable",
+	"command-failed": "ps failed",
+	"malformed-process-row": "unparsed rows",
+	"process-collection-unavailable": "process list unavailable",
+};
+const utf8 = new TextEncoder();
+
+function finite(value: number): number | null {
+	return Number.isFinite(value) ? value : null;
+}
+
+/** Every observed process lacks interval CPU by platform design, not because it is warming. */
+function processCpuUnavailable(snapshot: ResourceSnapshot): boolean {
+	return snapshot.processes.length > 0 && snapshot.processes.every((p) => p.cpu.state === "unavailable");
+}
+
+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;
+}
+
+/** Limits that hide data the user would expect: budget caps, collector failures, unavailable host CPU. */
+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;
+}
+
+/** Expected platform limits, stated once so `--` and `(unknown)` are never mistaken for zero or a bug. */
+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.
+ */
+export function toMonSnapshot(snapshot: ResourceSnapshot, baseline = true): MonSnapshot {
+	const total = finite(snapshot.memory.totalBytes);
+	const free = finite(snapshot.memory.freeBytes);
+	const text = notice(snapshot, baseline);
+	const note = hint(snapshot);
+	return {
+		cpuPercent: snapshot.cpu.state === "available" ? finite(snapshot.cpu.value) : null,
+		logicalCpus: snapshot.logicalCpus,
+		memoryUsedBytes: total !== null && total > 0 && free !== null ? Math.max(0, total - free) : null,
+		memoryTotalBytes: total !== null && total > 0 ? total : 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),
+			};
+		}),
+		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 } : {}),
+	};
+}
+
+/** One sampler per open interaction; its baseline and child cleanup end with the view. */
+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(),
+	};
+}