@nredd/pi-session-kit 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [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
+- Label the header clock `viewer last import` (or `viewer never imported`); it is not producer freshness, so an old export stays old after a fresh import
+- Flag future export clocks as `future; clock skew`, absent/invalid timestamps as `unknown`, and missing/rejected sources with `Incomplete import; retained last-good snapshot`; print/JSON output carries the same provenance
+- Keep snapshot schema v1 and the exporter CLI contract unchanged; existing snapshots need no migration or re-export
+- Redesign the monitors widget like the Todos and subagents panels: disclosure heading with running/failed/done counts, one bulleted row per monitor (running, matched, failed, exited) with flush-right `elapsed · N lines`, and a constant-height window with `↑/↓ N more`
+- Collapse with a heading click or `monitor.collapseKey` (default `ctrl+shift+m`, `"off"` disables, validated with the rpiv-todo key grammar); cap rows with `monitor.maxWidgetLines` (default 12, minimum 4)
+- Keep finished monitors visible beside running ones while any monitor runs; the widget still never writes to the transcript or model context
+- Add `MonitorInfo.matches` and `KitConfig.monitor`; hosts passing a config without `monitor` get the defaults
+
+## 0.6.0
+
+- Keep passive monitor output only in the monitor ring buffer; `monitor_read` is the explicit output surface and match/exit/timeout wakes are compact summaries with a cursor

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.
+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.6.0
+pi install npm:@nredd/pi-session-kit@0.8.0
 ```
 
 Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
@@ -27,9 +32,10 @@ Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
   "rules": { "enabled": true },
   "goal": { "enabled": true },
   "loop": { "enabled": true },
-  "monitor": { "enabled": true },
+  "monitor": { "enabled": true, "collapseKey": "ctrl+shift+m", "maxWidgetLines": 12 },
   "diff": { "enabled": true },
-  "stats": { "enabled": true }
+  "stats": { "enabled": true },
+  "mon": { "enabled": true }
 }
 ```
 
@@ -79,6 +85,23 @@ persistent cron is installed. Deferred-tool configurations need `goal_update` in
   possibly reused group, so its record is kept, not signalled. Within that window a later-born member
   in a reused group is indistinguishable; the dead leader, matching group and session, and no prior
   members bound that case, they do not exclude it.
+- Widget: while any monitor runs, a Todos/subagents-style panel sits above the editor. Heading
+  `▾ ● Monitors (2 running · 1 failed · 1 done)`; one row per retained monitor (running monitors
+  plus up to ten finished ones) with a bullet by state (green running, yellow matched, red
+  failed = non-zero exit, signal or timeout, dim exited/stopped), the name and last line truncated,
+  and `elapsed · N lines` flush right. It is display only: the quiet rules above are unchanged, and
+  a repaint never adds anything to the transcript or model context. Clicking the heading or
+  pressing `monitor.collapseKey` collapses it to the heading plus a `ctrl+shift+m to expand` hint
+  (`▸`). `monitor.maxWidgetLines` caps content rows (heading included, default 12, integer >= 4,
+  else the default), excluding the one trailing spacer row. It is a constant-height window:
+  `↑ N more` / `↓ N more` take a row each, so it never resizes while you scroll with the mouse
+  wheel. Pi's tool-output expansion shows every row.
+  `collapseKey` takes the same grammar as rpiv-todo's `collapseKey` (trimmed, lowercased; distinct
+  `ctrl`/`shift`/`alt`/`super` modifiers plus one printable key or a named key; `"off"` removes the
+  binding; anything else falls back to the default). It is bound once per runtime, so a change needs
+  `/reload`. The default `ctrl+shift+m` is unused by pi core, Todos (`ctrl+shift+t`), subagents and
+  Plan mode (no default key). Like Todos' key it needs a terminal with the kitty keyboard protocol.
+  There is no `collapseOnResume`: monitors never survive a resume, so there is nothing to collapse.
 - Plan mode admits only `monitor_read`; start and stop are mutating tools. Ordinary tool hooks apply
   to the tool call, but a custom argv tool does not automatically inherit Bash-specific policies.
 
@@ -93,9 +116,13 @@ non-triggering display message. The overlay is TUI-only and works in Plan mode.
 ## Stats
 
 `/stats` is Claude Code's `/stats` pane over fresh local sessions plus imported machine snapshots,
-split by provider and model. It NEVER performs network I/O. Machine coverage and the last successful
-remote import are shown; unsynced machines show `local-only` / `never synced`. Invalid or missing
-snapshots retain last-good data and show `incomplete coverage`.
+split by provider and model. It NEVER performs network I/O. The header shows `viewer last import`,
+not producer freshness; without imports it says `viewer never imported`. Tab/Shift-Tab reaches
+**Machines**, with each known label/opaque UUID, local scan status, and remote exported-at UTC
+instant plus age at opening. Old exports stay old after a fresh import; future clocks are flagged.
+Unknown/rejected sources and retained last-good snapshots are explicit. This lists known sources,
+not undiscovered machines. Invalid or missing snapshots show `incomplete coverage`.
+Print/JSON output includes the same provenance. Details: [here](docs/stats-snapshots.md).
 
 Pinned header: tabs and the coverage note, then the date ranges and the model filter, then a rule.
 Overview: an activity heatmap (one column per week) with the headline numbers (favorite model,

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/docs/stats-snapshots.md

@@ -101,8 +101,25 @@ Producer updates are invisible until the producer exports AND the viewer imports
 known machines, not undiscovered installations; it is not proof that every machine has synced.
 
 `/stats` freshly scans local sessions and combines them with this cache without network access.
-Its UI labels cached coverage, successful import time, local-only/never-synced state and incomplete
-coverage. Future calls are ignored in display totals, not removed from durable history. Statistics
+Its header labels cached coverage, **viewer last import**, local-only/never-imported state and
+incomplete coverage. Tab/Shift-Tab cycles Overview, Models and **Machines**. Machines lists each
+known installation's label plus full opaque UUID (default labels may repeat), fresh local scan
+status, and each remote producer's **exported-at** UTC instant and age at opening. Use j/k or
+arrows to scroll; narrow panes wrap details. Print/JSON output includes the same provenance;
+empty histories include it in the notification. Range/model filters do not filter provenance.
+
+The viewer import clock is NOT producer freshness: importing a ten-day-old export today still
+shows a ten-day producer age. Future export clocks say `future; clock skew`, never fresh.
+Absent/invalid display timestamps say `unknown`. Invalid v1 manifests still fail validation and
+retain last-good data; rejected known UUIDs without last-good data show unknown export time.
+Missing/rejected sources with retained data say `Incomplete import; retained last-good snapshot`.
+Existing v1 snapshots require no migration or re-export. Unreadable caches report incomplete
+coverage, not invented machine identities. Only known sources are listed; this cannot discover
+machines that have never supplied a snapshot. No freshness threshold implies fleet completeness.
+
+Labels come only from the existing local `machine.json`, never automatic hostname/environment
+collection. Keep custom labels non-sensitive: they are exported. No schema or sync cadence changes.
+Future calls are ignored in display totals, not removed from durable history. Statistics
 are not subscription quota measurements or router inputs.
 
 Harness API:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "publishConfig": {
     "access": "public"
   },
@@ -12,6 +12,8 @@
     "src",
     "dist/pi-stats-export.mjs",
     "docs/stats-snapshots.md",
+    "docs/mon-dashboard.md",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
@@ -24,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": "*",
@@ -40,8 +45,8 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
-    "@earendil-works/pi-coding-agent": "https://github.com/nredd/pi/releases/download/v1.3.0-nredd.6/earendil-works-pi-coding-agent-1.3.0.tgz",
-    "@earendil-works/pi-tui": "https://github.com/nredd/pi/releases/download/v1.3.0-nredd.6/earendil-works-pi-tui-1.3.0.tgz",
+    "@earendil-works/pi-coding-agent": "https://github.com/nredd/pi/releases/download/v1.3.0-nredd.7/earendil-works-pi-coding-agent-1.3.0.tgz",
+    "@earendil-works/pi-tui": "https://github.com/nredd/pi/releases/download/v1.3.0-nredd.7/earendil-works-pi-tui-1.3.0.tgz",
     "@types/node": "26.6.5",
     "@xterm/headless": "5.5.0",
     "esbuild": "0.28.2",

package/src/config.ts

@@ -9,13 +9,73 @@ 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 {
 	features: Record<Feature, boolean>;
 	/** Overrides the auto-title model, as `provider/id`. */
 	titleModel?: string;
+	monitor: MonitorWidgetConfig;
+}
+
+/** `monitor.*` widget settings, mirroring rpiv-todo's `collapseKey` / `maxWidgetLines`. */
+export interface MonitorWidgetConfig {
+	/** Key spec that collapses/expands the widget, or `"off"` for no binding. */
+	collapseKey: string;
+	/** Content-row budget including the heading, excluding the trailing spacer; floor `MIN_WIDGET_LINES`. */
+	maxWidgetLines: number;
+}
+
+export const DEFAULT_COLLAPSE_KEY = "ctrl+shift+m";
+export const COLLAPSE_KEY_OFF = "off";
+export const DEFAULT_MAX_WIDGET_LINES = 12;
+/** Heading + two edge hints + one row: below this a scrolled window shows nothing. */
+export const MIN_WIDGET_LINES = 4;
+
+// Named keys accepted by pi-tui's `matchesKey`; lowercase spellings are canonical.
+const SPECIAL_KEYS = new Set([
+	"escape",
+	"esc",
+	"enter",
+	"return",
+	"tab",
+	"space",
+	"backspace",
+	"delete",
+	"insert",
+	"clear",
+	"home",
+	"end",
+	"pageup",
+	"pagedown",
+	"up",
+	"down",
+	"left",
+	"right",
+	...Array.from({ length: 12 }, (_, i) => `f${i + 1}`),
+]);
+const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
+
+/**
+ * Strict pi-tui KeyId grammar: distinct modifiers, then one printable char or a named key.
+ * Loose checks are not enough: pi-tui takes the LAST `+` part as the key and ignores unknown
+ * parts, so a typo like `ctr+]` would silently bind every bare `]`.
+ */
+export function isValidKeySpec(spec: string): boolean {
+	if (!spec || spec.startsWith("+") || spec.endsWith("+") || spec.includes("++")) return false;
+	const parts = spec.split("+");
+	const base = parts[parts.length - 1] ?? "";
+	const modifiers = parts.slice(0, -1);
+	if (modifiers.length !== new Set(modifiers).size || !modifiers.every((m) => MODIFIERS.has(m))) return false;
+	return base.length === 1 ? /[a-z0-9_\-!@#$%^&*()|~`'":;,./<>?[\]{}=\\]/.test(base) : SPECIAL_KEYS.has(base);
+}
+
+/** Trim and lowercase; `"off"` disables, anything missing or invalid falls back to the default. */
+export function resolveCollapseKey(raw: unknown): string {
+	const key = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+	if (key === COLLAPSE_KEY_OFF) return COLLAPSE_KEY_OFF;
+	return isValidKeySpec(key) ? key : DEFAULT_COLLAPSE_KEY;
 }
 
 export function configPath(agentDir = process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent")): string {
@@ -23,7 +83,10 @@ export function configPath(agentDir = process.env.PI_CODING_AGENT_DIR ?? join(ho
 }
 
 export function defaultConfig(): KitConfig {
-	return { features: Object.fromEntries(FEATURES.map((f) => [f, true])) as Record<Feature, boolean> };
+	return {
+		features: Object.fromEntries(FEATURES.map((f) => [f, true])) as Record<Feature, boolean>,
+		monitor: { collapseKey: DEFAULT_COLLAPSE_KEY, maxWidgetLines: DEFAULT_MAX_WIDGET_LINES },
+	};
 }
 
 /** Parse a config document, ignoring unknown keys and wrong-typed values. */
@@ -38,6 +101,14 @@ export function parseConfig(raw: unknown): KitConfig {
 			if (typeof enabled === "boolean") config.features[feature] = enabled;
 		}
 	}
+	const monitor = doc.monitor;
+	if (typeof monitor === "object" && monitor !== null) {
+		const section = monitor as Record<string, unknown>;
+		config.monitor.collapseKey = resolveCollapseKey(section.collapseKey);
+		const lines = section.maxWidgetLines;
+		if (typeof lines === "number" && Number.isInteger(lines) && lines >= MIN_WIDGET_LINES)
+			config.monitor.maxWidgetLines = lines;
+	}
 	const titles = doc.titles;
 	if (typeof titles === "object" && titles !== null) {
 		const model = (titles as Record<string, unknown>).model;

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. */