@nredd/pi-session-kit 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [Unreleased]
+
+## 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,7 +3,7 @@
 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.
 
 ## Standalone use
 
@@ -16,7 +16,7 @@ session branch. Closing pi stops its work.
 ## Install and config
 
 ```sh
-pi install npm:@nredd/pi-session-kit@0.6.0
+pi install npm:@nredd/pi-session-kit@0.7.0
 ```
 
 Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
@@ -27,7 +27,7 @@ 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 }
 }
@@ -79,6 +79,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 +110,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/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.7.0",
   "publishConfig": {
     "access": "public"
   },
@@ -12,6 +12,7 @@
     "src",
     "dist/pi-stats-export.mjs",
     "docs/stats-snapshots.md",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md"
   ],
@@ -40,8 +41,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

@@ -16,6 +16,66 @@ 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/monitor/index.ts

@@ -1,6 +1,7 @@
 /**
  * `/monitor`: background process watchers the model can start, read and stop.
  *
+ * - a collapsible above-editor widget (`monitor.collapseKey`, default `ctrl+shift+m`) lists them
  * - `monitor_start` / `monitor_read` / `monitor_stop` tools and a `/monitor` command (list, stop)
  * - output is coalesced for 2s in each monitor's ring buffer; only `match`, exit/timeout or
  *   `wake: true` emits a compact custom wake, while passive output stays out of the session
@@ -12,9 +13,10 @@
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { KeyId } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { isChildSession, registerChildIdentity, registerParentTool } from "../child.ts";
-import type { KitConfig } from "../config.ts";
+import { COLLAPSE_KEY_OFF, defaultConfig, type KitConfig } from "../config.ts";
 import { type ManagerOptions, MonitorError, MonitorManager } from "./manager.ts";
 import { formatDuration } from "./messages.ts";
 import { boundTail } from "./output.ts";
@@ -46,7 +48,7 @@ function text(out: string, details?: unknown, isError = false) {
 
 export function register(
 	pi: ExtensionAPI,
-	_config: KitConfig,
+	config: KitConfig,
 	monitorRoot?: string,
 	runtime: Pick<ManagerOptions, "clock" | "spawnMonitor"> = {},
 ): void {
@@ -55,6 +57,17 @@ export function register(
 	let manager: MonitorManager | undefined;
 	let widget: MonitorWidget | undefined;
 
+	// Registered once per runtime, like Todos: a key change needs /reload. `off` skips the binding.
+	const { collapseKey, maxWidgetLines } = config.monitor ?? defaultConfig().monitor; // hosts passing a pre-0.7 config shape get defaults
+	if (collapseKey !== COLLAPSE_KEY_OFF) {
+		pi.registerShortcut(collapseKey as KeyId, {
+			description: "Collapse or expand the monitors widget",
+			handler: (ctx) => {
+				if (ctx.hasUI && widget?.isVisible()) widget.toggle();
+			},
+		});
+	}
+
 	const teardown = async (): Promise<void> => {
 		const old = manager;
 		const oldWidget = widget;
@@ -75,7 +88,7 @@ export function register(
 			ctx.ui.notify(`/monitor: cannot create ${root}: ${(error as Error).message}`, "warning");
 			return;
 		}
-		const w = new MonitorWidget(() => manager?.running() ?? []);
+		const w = new MonitorWidget(() => manager?.list() ?? [], { maxLines: maxWidgetLines, collapseKey });
 		w.attach(ctx);
 		widget = w;
 		manager = new MonitorManager({

package/src/monitor/manager.ts

@@ -62,6 +62,8 @@ interface Monitor {
 	stopReason: "stop" | "timeout" | undefined;
 	/** Cursor after the output the model most recently received through a wake or read. */
 	notifiedSince: number;
+	/** Lines that matched, counted as they are ingested. */
+	matches: number;
 	/** Resolves after the exit was fully processed (status set, pidfile removed). */
 	done: Promise<void>;
 }
@@ -210,6 +212,7 @@ export class MonitorManager {
 			timeoutTimer,
 			stopReason: undefined,
 			notifiedSince: 0,
+			matches: 0,
 			done: Promise.resolve(),
 		};
 		const m = monitor;
@@ -266,6 +269,7 @@ export class MonitorManager {
 		const line = m.ring.push(text);
 		return new Promise((resolve) => {
 			const add = (matched: boolean) => {
+				if (matched) m.matches++;
 				m.coalescer.add({ ...line, matched });
 				resolve();
 			};
@@ -328,6 +332,7 @@ function toInfo(m: Monitor): MonitorInfo {
 		exitCode: m.exit.exitCode,
 		signal: m.exit.signal,
 		lines: m.ring.lastLine,
+		matches: m.matches,
 		lastLine: m.ring.lastText,
 		wake: m.wake,
 		match: m.matchSource,

package/src/monitor/types.ts

@@ -29,6 +29,8 @@ export interface MonitorInfo {
 	exitCode: number | null;
 	signal: NodeJS.Signals | null;
 	lines: number;
+	/** Lines that matched `match`, for the widget's matched state. */
+	matches: number;
 	/** Newest buffered output, for the compact TUI summary only. */
 	lastLine?: string;
 	wake: boolean;

package/src/monitor/widget.ts

@@ -1,7 +1,13 @@
-/** Quiet above-editor summary of running monitors. */
+/**
+ * Above-editor monitors panel, laid out like the Todos and subagents widgets: a disclosure heading
+ * (clickable, plus a configurable shortcut), one bulleted row per monitor with flush-right stats,
+ * and a fixed-height scroll window. It is display only: passive monitor output still stays in the
+ * ring buffer and never enters the transcript or model context.
+ */
 
 import type { ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { type TUI, type TuiMouseEvent, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { COLLAPSE_KEY_OFF } from "../config.ts";
 import { formatDuration } from "./messages.ts";
 import type { MonitorInfo } from "./types.ts";
 
@@ -9,54 +15,202 @@ export const WIDGET_KEY = "session-kit:monitors";
 const TICK_MS = 1_000;
 
 type WidgetTheme = Pick<Theme, "fg">;
+type Color = Parameters<Theme["fg"]>[0];
 
-function monitorSummary(info: MonitorInfo, now: number): string {
-	return `${info.name} ${formatDuration(now - info.startedAt)} ${info.lines} lines last: ${info.lastLine ?? "(no output)"}`;
+export type MonitorState = "running" | "matched" | "failed" | "exited";
+
+const STATE_COLOR: Record<MonitorState, Color> = {
+	running: "success",
+	matched: "warning",
+	failed: "error",
+	exited: "dim",
+};
+
+/** Bullet state: a running monitor that has matched, a non-clean end, or a clean/requested end. */
+export function monitorState(info: MonitorInfo): MonitorState {
+	if (info.status === "running") return info.matches > 0 ? "matched" : "running";
+	if (info.status === "timeout") return "failed";
+	if (info.status === "stopped") return "exited";
+	return info.exitCode === 0 && info.signal === null ? "exited" : "failed";
+}
+
+/** A slice `[start, end)` of the rows plus which edge hints take a row. */
+export interface MonitorWindow {
+	start: number;
+	end: number;
+	above: boolean;
+	below: boolean;
+	maxOffset: number;
+}
+
+/**
+ * Window of exactly `budget` rows over `total` monitors from `offset`: each visible edge hint costs
+ * a row, so the panel height never changes while scrolling (budget >= 3 keeps every position
+ * showing at least one monitor).
+ */
+export function windowFor(total: number, budget: number, offset: number): MonitorWindow {
+	if (total <= budget) return { start: 0, end: total, above: false, below: false, maxOffset: 0 };
+	const maxOffset = total - (budget - 1);
+	const start = Math.max(0, Math.min(maxOffset, offset));
+	if (start === 0) return { start, end: budget - 1, above: false, below: true, maxOffset };
+	if (start === maxOffset) return { start, end: total, above: true, below: false, maxOffset };
+	return { start, end: start + budget - 2, above: true, below: true, maxOffset };
+}
+
+/** `left` truncated first so `right` survives; never wider than `width` (a wrap desyncs pi's diff). */
+function rightAlign(left: string, right: string, width: number): string {
+	const rightWidth = visibleWidth(right);
+	const clamped = truncateToWidth(left, Math.max(0, width - rightWidth - 1), "…");
+	const gap = Math.max(1, width - visibleWidth(clamped) - rightWidth);
+	return truncateToWidth(clamped + " ".repeat(gap) + right, width, "…");
+}
+
+/** Keep the full heading ahead of an optional hint; a narrow panel omits the hint. */
+function headingLine(heading: string, hint: string | undefined, width: number): string {
+	if (hint && visibleWidth(heading) + visibleWidth(hint) + 1 <= width) return rightAlign(heading, hint, width);
+	return truncateToWidth(heading, width, "…");
+}
+
+export interface WidgetView {
+	collapsed: boolean;
+	offset: number;
+	/** Row budget including the heading. */
+	maxLines: number;
+	/** Shortcut shown in the collapsed hint, or `"off"`. */
+	collapseKey: string;
+	/** Show every row (pi's tool-output expansion) instead of the budget. */
+	showAll?: boolean;
+}
+
+export interface RenderedWidget {
+	lines: string[];
+	/** The offset actually used after clamping to the window. */
+	offset: number;
+	/** Largest scroll offset (0 when everything fits). */
+	maxOffset: number;
 }
 
-/** Render one compact summary, favouring the newest monitor when all do not fit. */
-export function formatSummary(infos: MonitorInfo[], now: number, width: number, theme: WidgetTheme): string[] {
-	if (infos.length === 0) return [];
-	const count = `${infos.length} monitor${infos.length === 1 ? "" : "s"}`;
-	const all = `● ${count}  ${infos.map((info) => monitorSummary(info, now)).join("  ")}`;
-	if (visibleWidth(all) <= width) return [theme.fg("success", "●") + theme.fg("muted", all.slice(1))];
-	const newest = infos.reduce((latest, info) => (info.startedAt > latest.startedAt ? info : latest));
-	const compact = `● ${count}  ${monitorSummary(newest, now)}`;
-	return [truncateToWidth(theme.fg("success", "●") + theme.fg("muted", compact.slice(1)), width, "…")];
+function headingText(infos: MonitorInfo[]): string {
+	const running = infos.filter((i) => i.status === "running").length;
+	const failed = infos.filter((i) => monitorState(i) === "failed").length;
+	const done = infos.length - running - failed;
+	const parts = [
+		running ? `${running} running` : "",
+		failed ? `${failed} failed` : "",
+		done ? `${done} done` : "",
+	].filter(Boolean);
+	return `Monitors (${parts.join(" · ")})`;
+}
+
+function rowLine(info: MonitorInfo, now: number, width: number, theme: WidgetTheme): string {
+	const bullet = theme.fg(STATE_COLOR[monitorState(info)], "●");
+	const last = info.lastLine === undefined || info.lastLine === "" ? "(no output)" : info.lastLine;
+	const left = `${bullet} ${info.name}  ${theme.fg("dim", last)}`;
+	const elapsed = formatDuration((info.endedAt ?? now) - info.startedAt);
+	const stats = theme.fg("dim", `${elapsed} · ${info.lines} ${info.lines === 1 ? "line" : "lines"}`);
+	return rightAlign(left, stats, width);
+}
+
+/** Pure render: collapsed is heading plus spacer, expanded is a constant-height window. */
+export function renderWidget(
+	infos: MonitorInfo[],
+	now: number,
+	width: number,
+	theme: WidgetTheme,
+	view: WidgetView,
+): RenderedWidget {
+	if (infos.length === 0) return { lines: [], offset: 0, maxOffset: 0 };
+	const anyRunning = infos.some((i) => i.status === "running");
+	const color: Color = anyRunning ? "accent" : "dim";
+	const disclosure = theme.fg("dim", view.collapsed ? "▸" : "▾");
+	const head = `${disclosure} ${theme.fg(color, anyRunning ? "●" : "○")} ${theme.fg(color, headingText(infos))}`;
+
+	if (view.collapsed) {
+		const hint = view.collapseKey === COLLAPSE_KEY_OFF ? "collapsed" : `${view.collapseKey} to expand`;
+		return { lines: [headingLine(head, theme.fg("dim", hint), width), ""], offset: 0, maxOffset: 0 };
+	}
+
+	const budget = view.showAll ? infos.length : view.maxLines - 1;
+	const win = windowFor(infos.length, budget, view.offset);
+	const rows: string[] = [];
+	if (win.above) rows.push(theme.fg("dim", `↑ ${win.start} more`));
+	for (const info of infos.slice(win.start, win.end)) rows.push(rowLine(info, now, Math.max(0, width - 3), theme));
+	if (win.below) rows.push(theme.fg("dim", `↓ ${infos.length - win.end} more`));
+
+	const lines = [headingLine(head, undefined, width)];
+	rows.forEach((row, i) => {
+		const connector = theme.fg("dim", i === rows.length - 1 ? "└─" : "├─");
+		lines.push(truncateToWidth(`${connector} ${row}`, width, "…"));
+	});
+	lines.push("");
+	return { lines, offset: win.start, maxOffset: win.maxOffset };
+}
+
+export interface WidgetOptions {
+	maxLines: number;
+	collapseKey: string;
+	now?: () => number;
 }
 
 export class MonitorWidget {
 	private ctx: ExtensionContext | undefined;
 	private visible = false;
-	private requestRender: (() => void) | undefined;
+	private tui: TUI | undefined;
 	private timer: NodeJS.Timeout | undefined;
+	private collapsed = false;
+	private offset = 0;
+	private maxOffset = 0;
 
-	constructor(private readonly running: () => MonitorInfo[]) {}
+	/** `list` is every retained monitor; the panel shows while at least one is running. */
+	constructor(
+		private readonly list: () => MonitorInfo[],
+		private readonly options: WidgetOptions,
+	) {}
 
 	/** Bind to the session's UI; a no-op outside the TUI. */
 	attach(ctx: ExtensionContext): void {
 		if (ctx.mode === "tui") this.ctx = ctx;
 	}
 
+	isVisible(): boolean {
+		return this.visible;
+	}
+
+	isCollapsed(): boolean {
+		return this.collapsed;
+	}
+
+	/** Collapse or expand, resetting the scroll position; a full redraw covers the height step. */
+	toggle(): void {
+		this.collapsed = !this.collapsed;
+		this.offset = 0;
+		this.tui?.requestRender(true);
+	}
+
 	/** Show or hide the widget to match the manager, and repaint. */
 	refresh(): void {
 		const ctx = this.ctx;
 		if (!ctx) return;
-		const any = this.running().length > 0;
+		const any = this.list().some((i) => i.status === "running");
 		if (any && !this.visible) {
-			ctx.ui.setWidget(WIDGET_KEY, (tui, theme) => {
-				this.requestRender = () => tui.requestRender();
-				return {
-					render: (width: number) => formatSummary(this.running(), Date.now(), width, theme),
-					invalidate() {},
-				};
-			});
+			ctx.ui.setWidget(
+				WIDGET_KEY,
+				(tui, theme) => {
+					this.tui = tui;
+					return {
+						render: (width: number) => this.render(width, theme),
+						handleMouse: (event: TuiMouseEvent) => this.handleMouse(event),
+						invalidate() {},
+					};
+				},
+				{ placement: "aboveEditor" },
+			);
 			this.visible = true;
 			this.startTicking();
 		} else if (!any && this.visible) {
 			this.hide();
 		}
-		this.requestRender?.();
+		this.tui?.requestRender();
 	}
 
 	/** Remove the widget and stop the timer. */
@@ -65,16 +219,45 @@ export class MonitorWidget {
 		this.ctx = undefined;
 	}
 
+	private render(width: number, theme: WidgetTheme): string[] {
+		const out = renderWidget(this.list(), (this.options.now ?? Date.now)(), width, theme, {
+			collapsed: this.collapsed,
+			offset: this.offset,
+			maxLines: this.options.maxLines,
+			collapseKey: this.options.collapseKey,
+			showAll: this.ctx?.ui.getToolsExpanded?.() === true,
+		});
+		this.offset = out.offset;
+		this.maxOffset = out.maxOffset;
+		return out.lines;
+	}
+
+	private handleMouse(event: TuiMouseEvent): { handled: true } | undefined {
+		if (event.type === "click" && event.button === "left" && event.y === 0) {
+			this.toggle();
+			return { handled: true };
+		}
+		if (event.type !== "wheel" || this.collapsed) return undefined;
+		const next = Math.max(0, Math.min(this.maxOffset, this.offset + Math.trunc(event.wheelDelta ?? 0)));
+		if (next === this.offset) return undefined;
+		this.offset = next;
+		this.tui?.requestRender();
+		return { handled: true };
+	}
+
 	private hide(): void {
 		if (this.timer) clearInterval(this.timer);
 		this.timer = undefined;
 		if (this.visible) this.ctx?.ui.setWidget(WIDGET_KEY, undefined);
 		this.visible = false;
-		this.requestRender = undefined;
+		this.tui = undefined;
 	}
 
 	private startTicking(): void {
-		this.timer = setInterval(() => this.requestRender?.(), TICK_MS);
+		// Collapsed rows show no elapsed time; counts repaint through `refresh` on state changes.
+		this.timer = setInterval(() => {
+			if (!this.collapsed) this.tui?.requestRender();
+		}, TICK_MS);
 		this.timer.unref();
 	}
 }

package/src/stats/component.ts

@@ -5,7 +5,15 @@
  */
 
 import type { Theme, ThemeColor } from "@earendil-works/pi-coding-agent";
-import { type Color, type Component, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import {
+	type Color,
+	type Component,
+	Key,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
 import { sanitize } from "../diff/view.ts";
 import {
 	chartSeries,
@@ -39,8 +47,8 @@ import { seriesPalette } from "./palette.ts";
 import { timeAxis } from "./ticks.ts";
 
 type ThemeLike = Pick<Theme, "fg" | "bg" | "bold" | "style" | "colors">;
-export type Tab = "Overview" | "Models";
-const TABS: readonly Tab[] = ["Overview", "Models"];
+export type Tab = "Overview" | "Models" | "Machines";
+const TABS: readonly Tab[] = ["Overview", "Models", "Machines"];
 /** Chart lines, at most; their colours are shared by the chart, its legend and the model list. */
 const SERIES = 3;
 /** Narrowest plot `plot` can draw; only panes too narrow for a 6-week heatmap hit it. */
@@ -76,6 +84,8 @@ export interface StatsViewOptions {
 	today?: string;
 	now?: number;
 	coverage?: string;
+	/** Offline per-source provenance, rendered as a scrollable Machines tab. */
+	freshness?: readonly string[];
 	tab?: Tab;
 }
 
@@ -126,7 +136,8 @@ export class StatsView implements Component {
 			return;
 		}
 		if (matchesKey(data, Key.tab) || matchesKey(data, Key.shift("tab"))) {
-			this.tab = this.tab === "Overview" ? "Models" : "Overview";
+			const step = matchesKey(data, Key.shift("tab")) ? -1 : 1;
+			this.tab = TABS[(TABS.indexOf(this.tab) + step + TABS.length) % TABS.length] ?? "Overview";
 			this.scroll = 0;
 		} else if (data === "r") {
 			this.range = RANGES[(RANGES.indexOf(this.range) + 1) % RANGES.length] ?? "all";
@@ -155,6 +166,13 @@ export class StatsView implements Component {
 		let body: string[];
 		let hint = "";
 		if (this.tab === "Overview") body = this.scrolled(this.overviewBody(w, room), room);
+		else if (this.tab === "Machines")
+			body = this.scrolled(
+				(this.o.freshness ?? ["Per-machine freshness unknown (no source metadata)."]).flatMap((line) =>
+					wrapTextWithAnsi(this.paint("muted", line), contentWidth(w)),
+				),
+				room,
+			);
 		else {
 			const models = this.modelsBody(w, room);
 			body = this.scrolled(models.lines, room);
@@ -175,7 +193,7 @@ export class StatsView implements Component {
 		const joined = spread(tabs, coverage, inner);
 		const lines = [
 			joined ?? tabs,
-			...this.selectors(inner),
+			...(this.tab === "Machines" ? [] : this.selectors(inner)),
 			...(joined ? [] : [coverage]),
 			this.paint("dim", "─".repeat(inner)),
 		];

package/src/stats/freshness.ts

@@ -0,0 +1,46 @@
+/** Offline provenance display. Export time is not last activity or proof of fleet completeness. */
+import { sanitize } from "../diff/view.ts";
+import type { Coverage } from "./snapshot.ts";
+
+/** Invalid/absent clocks never become fresh; future clocks are explicitly untrustworthy. */
+export function timestampLabel(ms: number | undefined, now: number): string {
+	if (ms === undefined || !Number.isFinite(ms) || ms <= 0 || ms > 8640000000000000) return "unknown";
+	const timestamp = new Date(ms).toISOString();
+	if (ms > now) return `${timestamp} (future; clock skew)`;
+	const minutes = Math.floor((now - ms) / 60000);
+	const age =
+		minutes < 1
+			? "<1m"
+			: minutes < 60
+				? `${minutes}m`
+				: minutes < 1440
+					? `${Math.floor(minutes / 60)}h`
+					: `${Math.floor(minutes / 1440)}d`;
+	return `${timestamp} (${age} ago)`;
+}
+
+/** Shared print/TUI lines. UUIDs disambiguate default or duplicate labels without exposing hostnames. */
+export function freshnessLines(coverage: Coverage, now = Date.now()): string[] {
+	const lines = [
+		`Viewer last import: ${timestampLabel(coverage.importedAt, now)}`,
+		"Known sources only; other machines cannot be discovered here.",
+		"Export age is not last activity. Local history is scanned on opening.",
+	];
+	if (!coverage.sources?.length) return [...lines, "Per-machine freshness unknown (no source metadata)."];
+	for (const source of [...coverage.sources].sort(
+		(a, b) => Number(b.local) - Number(a.local) || a.machineId.localeCompare(b.machineId),
+	)) {
+		lines.push("", `${sanitize(source.label)} [${source.machineId}]${source.local ? " (local)" : ""}`);
+		if (source.local) lines.push(source.incomplete ? "Local scan incomplete" : "Local scan complete at opening");
+		else {
+			lines.push(`Producer exported: ${timestampLabel(source.exportedAt, now)}`);
+			if (source.incomplete)
+				lines.push(
+					source.exportedAt === undefined
+						? "Incomplete import; no last-good snapshot"
+						: "Incomplete import; retained last-good snapshot",
+				);
+		}
+	}
+	return lines;
+}

package/src/stats/index.ts

@@ -8,6 +8,7 @@ import { type Clock, realClock } from "../clock.ts";
 import type { KitConfig } from "../config.ts";
 import { say } from "../output.ts";
 import { StatsView, summary } from "./component.ts";
+import { freshnessLines } from "./freshness.ts";
 import type { Loaded } from "./load.ts";
 import { type Combined, coverageLabel, loadCombined } from "./snapshot.ts";
 
@@ -52,19 +53,20 @@ export function register(
 
 			const damage = [...problems(loaded), ...loaded.coverage.problems.map((p) => `/stats: ${p}`)];
 			const coverage = coverageLabel(loaded.coverage);
+			const freshness = freshnessLines(loaded.coverage, clock.now());
 			if (!tui) {
 				say(
 					pi,
 					ctx,
 					MESSAGE_TYPE,
-					[summary(loaded.calls.filter((c) => c.ms <= clock.now())), coverage, ...damage].join("\n"),
+					[summary(loaded.calls.filter((c) => c.ms <= clock.now())), coverage, ...freshness, ...damage].join("\n"),
 					"info",
 				);
 				return;
 			}
 			for (const line of damage) ctx.ui.notify(line, "warning");
 			if (loaded.calls.length === 0) {
-				ctx.ui.notify(`/stats: no usage recorded yet\n${coverage}`, "info");
+				ctx.ui.notify(`/stats: no usage recorded yet\n${coverage}\n${freshness.join("\n")}`, "info");
 				return;
 			}
 			const { calls, sessions, badLines } = loaded;
@@ -75,6 +77,7 @@ export function register(
 						sessions,
 						badLines,
 						coverage,
+						freshness,
 						now: clock.now(),
 						theme,
 						rows: () => tuiHost.terminal.rows,

package/src/stats/snapshot.ts

@@ -63,7 +63,14 @@ export interface GlobalCache {
 	machines: Record<string, MachineSnapshot>;
 	problems: string[];
 }
+/** Known sources only, including failed imports with no last-good snapshot. */
+export interface MachineCoverage extends Identity {
+	local: boolean;
+	exportedAt?: number;
+	incomplete: boolean;
+}
 export interface Coverage {
+	sources?: MachineCoverage[];
 	machines: number;
 	remoteMachines: number;
 	importedAt?: number;
@@ -484,6 +491,22 @@ export async function loadCombined(
 		sessionMetadata: [...sessions.values()],
 		sessions: [...sessions.values()].filter((s) => !s.child && owners.has(s.path)),
 		coverage: {
+			sources: [
+				{ ...identity, local: true, incomplete: local.errors > 0 || local.badLines > 0 },
+				...remotes.map(({ manifest }) => ({
+					machineId: manifest.machineId,
+					label: manifest.label,
+					local: false,
+					exportedAt: manifest.exportedAt,
+					incomplete: global.problems.some((p) => p.endsWith(` ${manifest.machineId}`)),
+				})),
+				...global.problems.flatMap((p) => {
+					const id = /^(?:Incomplete|Missing) snapshot (.+)$/.exec(p)?.[1];
+					return id && UUID.test(id) && id !== identity.machineId && !global.machines[id]
+						? [{ machineId: id, label: "Pi machine", local: false, incomplete: true }]
+						: [];
+				}),
+			],
 			machines: remotes.length + 1,
 			remoteMachines: remotes.length,
 			importedAt: global.importedAt || undefined,
@@ -493,5 +516,5 @@ export async function loadCombined(
 	};
 }
 export function coverageLabel(c: Coverage): string {
-	return `${c.incomplete ? "incomplete coverage · " : ""}${c.machines} machine${c.machines === 1 ? "" : "s"} · ${c.remoteMachines ? "cached" : "local-only"} · ${c.importedAt ? `last remote sync ${new Date(c.importedAt).toISOString()}` : "never synced"}`;
+	return `${c.incomplete ? "incomplete coverage · " : ""}${c.machines} machine${c.machines === 1 ? "" : "s"} · ${c.remoteMachines ? "cached" : "local-only"} · ${c.importedAt && positive(c.importedAt) ? `viewer last import ${new Date(c.importedAt).toISOString()}` : "viewer never imported"}`;
 }