@nredd/pi-session-kit 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 ## [Unreleased]
 
+- Make the portable stats CLI import-safe: importing `dist/pi-stats-export.mjs` no longer runs an operation; direct Node execution still runs it
+
+- Replace `/mon`'s ambiguous non-free label with `total-free` (`T-F` compact); accept additive native App+Wired+Compressed and swap metrics without silently substituting free-page subtraction
+- Accept native macOS interval CPU and footprint; add `f` to toggle the labelled byte column between `RSS` and `FOOT`, with failed measurements shown as `--`
+- Explain RSS versus footprint, compressed pages, executable names (`pi` as `node`), strong native identity and unavailable-CPU fallback in `?`; native metrics require the subsequent published sampler dependency bump
+
+- Raise the `monitor_start` `timeout_s` cap from 24h to 7 days (`604800`) so monitors can outlive long jobs
+
+## 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,27 @@
 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 native CPU/footprint require the upcoming sampler pin, executable names keep 16 bytes,
+RSS excludes compressed pages, `f` toggles a labelled footprint column,
+and memory labels state their measurement basis) 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 +36,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 }
 }
 ```
 
@@ -63,13 +71,17 @@ persistent cron is installed. Deferred-tool configurations need `goal_update` in
 ## Monitor
 
 - `monitor_start({argv, name, match?, wake?, timeout_s?})`: run an argv command with stdin closed,
-  no implicit shell. Five active monitors maximum, one-hour default timeout. Explicitly passing a
+  no implicit shell. Five active monitors maximum, one-hour default timeout, 7 day (`604800` s) maximum. Explicitly passing a
   shell remains arbitrary command execution; this is not a sandbox.
 - `monitor_read({id, since?})`: numbered output since a cursor. Ring buffers retain 2000 lines.
 - `monitor_stop({id})`, `/monitor list`, `/monitor stop <id|all>`: stop and inspect owned monitors.
 - Output batches every two seconds into the bounded ring buffer (with dropped-line reporting). Passive batches neither start turns nor create transcript/model-context entries; call `monitor_read` to fetch them. A regex match, natural exit, timeout or `wake: true` emits one compact visible wake with a cursor after the output the model last saw through a wake or read, not a replay of buffered output. A bounded batch preserves its first and latest dropped matching lines as wake evidence even if later output evicts them from the ring.
 - Children run in process groups: SIGTERM, then SIGKILL. Exit cleanup and pidfiles cover orderly quit
-  and later recovery after SIGKILL. Files live at
+  and later recovery after SIGKILL. Sweeps reauthenticate the leader after enumerating members;
+  uncertain identities or guards never authorize signaling. Reap checks are bounded to 20 polls
+  after escalation; a timeout keeps authenticated recovery on disk rather than claiming cleanup.
+  Spawn failures after child creation kill the child; matcher initialization failures also remove
+  its pidfile. A spawn completing after session disposal is killed without registration. Files live at
   `$TMPDIR/pi-monitors-<uid>/<sessionId>.<ownerPid>/<monitorId>.json`. Startup checks dead-owner
   records, including a resumed session, and validates process identity before signalling. It never
   sweeps a live owner's monitors. Two panes resuming the same session have separate directories.
@@ -213,8 +225,17 @@ the kit does not append a second reminder or request another continuation.
 `test/scenarios/` drives the real kit through core's in-process session harness under Vitest and Bun,
 covering goals, file-backed restore, child rename/reload, read-rule injection, titles,
 monitor output/wakes/cursors/caps/timeouts and loop scheduling with same-cwd session isolation.
+Command completion scenarios resolve public runner suggestions and execute the selected `/goal`,
+`/loop` and `/monitor` commands, checking persisted state, timer removal and the selected child.
+Loop resume starts from a provider-error pause: ticks stay quiet until the selected resume command
+restores dispatch. Git setup uses child-only scratch HOME/config and empty hooks/templates, with
+hostile config/template/hook controls; it never changes the parent process HOME.
+Pidfile age-boundary fixtures pin file/directory mtimes to the injected sweep clock and check the
+24-hour threshold under both past and future wall clocks.
 The interactive host/VirtualTerminal covers `/diff`, `/stats` and real `/name`, including width/resize
-matrices, chart glyph ports/colours and file-backed titles. Stats histories use a fixed clock;
+matrices, chart glyph ports/colours and file-backed titles. Mounted command callbacks also verify
+live-theme invalidation, empty Models ranges, help page boundaries, source-failure reopening,
+stale deferred factories and stats load-error cleanup without replacing the interactive host. Stats histories use a fixed clock;
 `createSessionKit({ agentDir, clock })` scopes both offline loading and displayed time ranges.
 Terminal fixtures route input chunks through pi-tui's real `StdinBuffer`, matching ProcessTerminal's
 keypress splitting (complete keys only; lone Escape is flushed immediately). Stats scroll-to-clamp
@@ -223,6 +244,18 @@ tabs and exact provider totals remain covered at every width. Each stats-view bo
 and disposes it in `finally`, so runner timeout teardown cannot race a still-running callback.
 Monitor scenarios use a shared fake clock and controlled children; native `test/monitor/` keeps real
 workers/processes, and process-group kill/orphan recovery stays in the assembled integration tier.
-`npm run check` runs Biome, TypeScript, the full Vitest suite and `bun test test/scenarios` (Bun 1.3.14).
+Native stop/dispose checks assert direct children are reaped when the operation resolves, then
+observe orphaned descendants disappearing with the existing bounded liveness check. Leader exit
+and pipe closure do not synchronize PID 1's reaping; on Linux, `kill(pid, 0)` can still succeed
+for a terminated zombie. No extra signal, fixed delay or larger timeout is needed.
+The native diff descendant timeout fixture gates its fake deadline on real stdout readiness, so
+slow process startup cannot race a fixed wall-clock deadline. Adapter fault tests cover monitor
+startup/sweep/widget failures, post-spawn errors, worker startup timeout, rejected sampler cleanup,
+first/latest dropped-match evidence, title-stream failure and real rule reinjection after tree
+navigation. Synthetic PIDs are never passed to real signal capabilities. Native Promise construction
+initializes the monitor exit resolver before child handlers register; synchronous close/error
+registration fixtures lock that ordering. The overwritten no-op resolver initializer is removed,
+not a reachable validation or lifecycle path.
+`npm run check` runs Biome, TypeScript, the full Vitest suite and `bun test test/scenarios` (Bun 1.4.4).
 Cross-extension Plan/subagent/todo interactions and OS terminal boundaries remain in the integration tier;
 `docs/verification-rebuild.md` at the monorepo root tracks their destinations.

package/dist/pi-stats-export.mjs

@@ -1,5 +1,7 @@
 // src/stats/cli.ts
+import { realpathSync } from "node:fs";
 import { resolve as resolve2 } from "node:path";
+import { pathToFileURL } from "node:url";
 
 // src/stats/load.ts
 import { createHash, randomUUID } from "node:crypto";
@@ -651,7 +653,23 @@ async function main() {
       "usage: export --agent-dir DIR --output OUT [--sessions-dir DIR] | import --agent-dir DIR --input REPO"
     );
 }
-main().catch((error) => {
-  console.error(error instanceof Error ? error.message : "Stats operation failed");
-  process.exitCode = 1;
-});
+async function run() {
+  try {
+    await main();
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : "Stats operation failed");
+    process.exitCode = 1;
+  }
+}
+function isEntrypoint() {
+  try {
+    return !!process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href;
+  } catch {
+    return false;
+  }
+}
+if (isEntrypoint()) void run();
+export {
+  main,
+  run
+};

package/docs/mon-dashboard.md

@@ -0,0 +1,140 @@
+# /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.
+- Upcoming sampler source supplies macOS native interval CPU and footprint via builtin FFI and
+  libproc, with process-start absolute ticks plus microsecond identity. Inaccessible PIDs and
+  unsupported runtimes have unknown metrics. The existing published `0.1.1` remains entirely
+  unavailable for process CPU; `ps` whole-second start times alone never authenticate CPU. The
+  view orders by RSS only when every process CPU is unavailable, 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. `f` toggles the byte column between
+  `RSS` and `FOOT` (native physical footprint, including compressed memory); unavailable/failed
+  PIDs show `--`, never zero. `MEM%` and `m` sorting remain RSS-based in either view. `--` 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 labels its actual basis. Older samplers report **total-free** (`T-F` in the compact
+  summary), which includes cached files and is NOT Activity Monitor's Memory Used. Additive v1
+  `memory.usage` metrics instead render **used (A+W+C)** (`A+W+C` compact), an estimate of resident
+  App + Wired + Compressed physical RAM. A failed native metric stays `--`, never total-free under
+  a used label. Cards also show free pages and swap used/allocated; missing swap stays `--/--`.
+  `?` explains each basis, RSS excluding compressed pages versus Activity Monitor's footprint,
+  executable names (`pi` runs as `node`), and decaying `ps %cpu` versus interval CPU.
+  Load averages are not percentages. Process CPU is interval CPU, where 100% is one logical CPU and
+  multithreaded processes can exceed 100%.
+- Release sequencing: the registry dependency remains `0.1.1`, which lacks native host-memory
+  metrics. This adapter accepts the new optional memory/footprint fields and tests them, but production
+  remains honestly labelled total-free with unavailable process CPU/footprint until a new sampler
+  is published, its common dependency pin
+  and nested registry lock entries are updated, and both consumer registry tests pass. Do NOT claim
+  the new native used/swap line is active with the old registry pin.
+- 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; `f` toggles RSS/FOOT; `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

@@ -3,7 +3,14 @@
 Build the committed `dist/pi-stats-export.mjs` with `npm ci && npm run build:stats-export`.
 The exact esbuild version and dependencies are locked; tests assert byte-identical rebuilds.
 Copy only that file. Runtime is Node 22+ with builtins only, no Pi install, extension, private
-repository, package install, auth or network access.
+repository, package install, auth or network access. Importing the artifact is silent, even when
+an importing process supplies a nonexistent entrypoint argument; direct and symlinked Node execution
+still run the CLI. Packed-CLI tests explicitly launch `node`, including when their Vitest
+host is Bun; this tests the artifact's declared runtime, not Bun's entry-module resolver.
+
+Chart tick steps parse decimal powers directly rather than using implementation-approximated
+exponentiation, keeping large finite ticks consistent between Node and Bun. Steps above the
+numeric range retain infinite headroom.
 
 ```
 node ARTIFACT export --agent-dir DIR --output OUT [--sessions-dir ROOT]
@@ -36,10 +43,16 @@ Installation state, never synced:
 - `DIR/pi-session-kit/stats-cache.json`: local parser cache v2, including file paths and compact
   usage tuples. Version 1 entries for deleted files stay intact; existing files reparse even if
   their mtime/size match. Strong identities are not invented for inaccessible legacy files.
+  Failed stat/parse operations count as incomplete history; a failed reparse retains the last-good
+  cached record. Invalid cached identities and raw provider/model pairs are discarded. Persisted
+  child markers apply only to the matching session ID, surviving user-visible renames.
 - `DIR/pi-session-kit/stats-global.json`: one atomically replaced document containing validated
   last-good machine snapshots, last successful import time and coverage problems. Imports do not
   mutate local usage or installation identity. A wholly failed import does not advance the sync
-  time; a partial import records valid updates and marks coverage incomplete.
+  time; a partial import records valid updates and marks coverage incomplete. The assembled cache
+  accepts up to 128 MiB; exceeding that limit fails before replacement and retains its last-good
+  bytes. Tests inject final-document byte accounting at the exact limit and one byte over, while
+  retaining real import validation and atomic publication.
 
 Snapshot version 1:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.7.0",
+  "version": "0.9.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.2.0"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
@@ -35,15 +39,16 @@
     "format": "biome check --write src/ test/",
     "typecheck": "tsc --noEmit",
     "build:stats-export": "esbuild src/stats/cli.ts --bundle --platform=node --format=esm --target=node22 --outfile=dist/pi-stats-export.mjs",
-    "test": "npm run build:stats-export && vitest run",
-    "test:bun": "bun test test/scenarios",
+    "test": "npm run build:stats-export && vitest run --coverage",
+    "test:bun": "bun test test/scenarios --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage/bun",
     "check": "npm run lint && npm run typecheck && npm run test && npm run test:bun"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.15",
-    "@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",
+    "@earendil-works/pi-coding-agent": "https://github.com/nredd/pi/releases/download/v1.3.0-nredd.8/earendil-works-pi-coding-agent-1.3.0.tgz",
+    "@earendil-works/pi-tui": "https://github.com/nredd/pi/releases/download/v1.3.0-nredd.8/earendil-works-pi-tui-1.3.0.tgz",
     "@types/node": "26.6.5",
+    "@vitest/coverage-v8": "5.0.3",
     "@xterm/headless": "5.5.0",
     "esbuild": "0.28.2",
     "typebox": "1.3.36",

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