@nredd/pi-session-kit 0.3.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-session-kit
 
-Publishable to npm as `@nredd/pi-session-kit` (`publishConfig.access: public`), version `0.3.0`; each publication is recorded in `releases/`.
+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.
@@ -16,7 +16,7 @@ session branch. Closing pi stops its work.
 ## Install and config
 
 ```sh
-pi install git:github.com/nredd/pi-session-kit@v0.3.0
+pi install npm:@nredd/pi-session-kit@0.4.0
 ```
 
 Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
@@ -33,7 +33,13 @@ Optional `~/.pi/agent/pi-session-kit.json` (respects `PI_CODING_AGENT_DIR`):
 }
 ```
 
-Every module defaults on. Malformed config reports a diagnostic and uses defaults. No daemon or
+Every module defaults on. Malformed config reports a diagnostic and uses defaults. SDK hosts can use
+`createSessionKit({ config, agentDir, monitorRoot })` from `src/index.ts`: explicit `config` avoids
+loading the config file, `agentDir` scopes config/rules/title aliases, and `monitorRoot` isolates
+monitor pidfiles and orphan sweeps. Optional `clock` (`now`, cancellable `setTimeout`/`setInterval`)
+and `spawnMonitor` seams control scheduling and child lifetime in SDK tests; the real manager,
+ring, coalescer, regex worker and host follow-up queue still run. Controlled stdout callbacks resolve
+after matching/ingestion; native pipe events need not await them. Omitted options keep the CLI defaults. No daemon or
 persistent cron is installed. Deferred-tool configurations need `goal_update` in `neverDefer`
 (without forcing it active), and `monitor_read` in `alwaysActive` and `neverDefer` for Plan mode.
 
@@ -68,6 +74,12 @@ persistent cron is installed. Deferred-tool configurations need `goal_update` in
   `$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.
+  A group whose leader already exited is reaped only when a member started at spawn anchors it: its
+  `ps lstart` must read under one second after, or under two before, the recorded spawn (`lstart` is
+  a whole-second floor). A member that reads a second or more after the spawn cannot authenticate a
+  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.
 - 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.
 
@@ -84,21 +96,37 @@ non-triggering display message. The overlay is TUI-only and works in Plan mode.
 `/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`. Overview: an activity heatmap (one column per week), headline numbers (favorite model, total tokens,
-sessions, longest session, active days, streaks, cache tokens, notional cost) and the token chart.
-Models: the chart, then every model grouped under its provider with in/out/cache/cost, two-up from
-80 columns. Tab switches tabs, `r` cycles All / 7d / 30d / 5h / 24h (default All), `m`/`M` cycle the filter
-(All, each provider, each `provider/model`), `j/k` or arrows scroll, `q` or Escape closes.
+snapshots retain last-good data and show `incomplete coverage`.
+
+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,
+total tokens, sessions, longest session, active days, streaks, cache tokens, notional cost) beside
+it from about 105 columns and under it below that, then the token chart. Models: the chart, then every
+model grouped under its provider. From about 100 columns that is a table (tokens, share, in, out, cache
+read, cache write, notional cost; a subtotal line per provider), else three-line cards. Tab switches
+tabs, `r` cycles All / 7d / 30d / 5h / 24h (default All), `m`/`M` cycle the filter (All, each provider,
+each `provider/model`), `j/k` or arrows scroll, `q` or Escape closes.
 
 - The chart is an asciichart-style line plot (`╭╮╰╯`), one line per provider under All, else the top
   three models. Where lines overlap they merge into junctions (`┴┬├┤┼`) so every line stays
   connected; the larger series keeps the colour. Line colours start at the theme's `accent` hue,
   saturated, with hues spread evenly over the lines drawn (two providers get opposite hues), so
-  muted themes still separate them. The heatmap and the chart span 75% of the pane, with the same right edge; the heatmap shows as
-  many weeks as fit, never less than a year when the pane allows. Days sum into 1/2/3/7/14/30-day buckets (longer
-  when needed) so the range fits the width; short ranges are interpolated, not stepped. Y ticks land
-  on round values with little headroom. Height follows the pane in whole tick steps (5 to 40 rows):
-  Overview grows the chart into the rows it has left, Models gives it about half.
+  muted themes still separate them. The title row carries the legend on its right (it wraps under the
+  title on narrow panes). Every block spans the whole pane, except the heatmap, which shows as many
+  weeks as fit up to two years. Days sum into 1/2/3/7/14/30-day buckets (longer when needed) so the
+  range fits the width; short ranges are interpolated, not stepped. Y ticks land on round values with
+  little headroom. Height follows the pane in whole tick steps (5 to 40 rows): Overview grows the chart
+  into the rows it has left, Models gives it what a short list leaves, at least half.
+- X axis: a baseline with a mark under every tick, labels centred on their bucket's column (the first and
+  last clamp to the plot edges). Ticks are evenly spaced, at most 13, never overlap and are never cut; the
+  finest set whose labels fit wins, so a wider pane gets more of them. 5h and 24h label hours starting on
+  the clock (`09:00`, or `9a` / `12p` when narrow; every hour, 2, 3, 4, 6, 12 or 24 hours apart; across a
+  DST change they stay evenly spaced, so later labels shift by the hour) with a row of dates where they
+  fit: each new local day first, then the first bucket. Day buckets: a week of single days gets `Wed 7`
+  (or `Wed`), longer ranges get dates on every day, 2 or 3 days, every Monday or every other Monday
+  (counted back from today for multi-day buckets), then month names, quarters, half years and years, with
+  `'26` only where the ticks span more than one year. A pane too narrow for any label draws the baseline
+  alone.
 - Rolling 5h/24h use the original call timestamps in zero-filled one-hour UTC buckets, with
   partial edges labeled. Labels use viewer-local time and UTC offsets, including repeated DST
   hours. The same rolling filter feeds chart/model/overview totals; future calls are ignored in
@@ -162,7 +190,19 @@ No private subagent marker is imported. Existing tool permissions are not widene
 A prior settle handler's continuation (including a todo reminder) suppresses the goal nudge;
 the kit does not append a second reminder or request another continuation.
 
-`npm run check`: Biome, TypeScript and Vitest. `pi-harness-e2e` adds faux-provider integration tests,
-real tmux width matrices (60 through 320 columns), Plan-mode tests, background-agent/todo interaction
-and two-pane lifecycle/isolation scenarios. Run its full `make verify` before tags or pins. Real
-monitor/display testing remains manual; see that repo's `docs/footer-cache-ultrawide.md`.
+`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.
+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;
+`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
+checks batch input and settle once; intermediate-frame checks still settle per step. Both hourly
+tabs and exact provider totals remain covered at every width. Each stats-view body owns its fixture
+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).
+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/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@nredd/pi-session-kit",
-  "version": "0.3.0",
-  "publishConfig": {"access": "public"},
+  "version": "0.5.0",
+  "publishConfig": {
+    "access": "public"
+  },
   "description": "Session-scoped pi tools and commands, offline cross-machine usage stats and a portable privacy-only stats CLI. No daemon.",
   "author": "nredd",
   "license": "MIT",
   "type": "module",
-  "files": ["src", "dist/pi-stats-export.mjs", "docs/stats-snapshots.md", "LICENSE", "README.md"],
+  "files": [
+    "src",
+    "dist/pi-stats-export.mjs",
+    "docs/stats-snapshots.md",
+    "LICENSE",
+    "README.md"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/nredd/pi-harness.git",
@@ -27,13 +35,15 @@
     "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",
-    "check": "npm run lint && npm run typecheck && npm run test"
+    "test:bun": "bun test test/scenarios",
+    "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": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@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",
     "@types/node": "26.6.5",
+    "@xterm/headless": "5.5.0",
     "esbuild": "0.28.2",
     "typebox": "1.3.36",
     "typescript": "7.0.2",

package/src/clock.ts

@@ -0,0 +1,25 @@
+/** Timers used by session scheduling. Handles own cancellation, not Node-specific timer methods. */
+export interface TimerHandle {
+	cancel(): void;
+}
+
+/** Injectable scheduling boundary; production timers are unreferenced so they cannot keep Pi alive. */
+export interface Clock {
+	now(): number;
+	setTimeout(callback: () => void, ms: number): TimerHandle;
+	setInterval(callback: () => void, ms: number): TimerHandle;
+}
+
+export const realClock: Clock = {
+	now: () => Date.now(),
+	setTimeout(callback, ms) {
+		const timer = setTimeout(callback, ms);
+		timer.unref();
+		return { cancel: () => clearTimeout(timer) };
+	},
+	setInterval(callback, ms) {
+		const timer = setInterval(callback, ms);
+		timer.unref();
+		return { cancel: () => clearInterval(timer) };
+	},
+};

package/src/goal/index.ts

@@ -11,6 +11,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { isChildSession, registerChildIdentity, registerParentTool } from "../child.ts";
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
 import type { KitConfig } from "../config.ts";
 import { coordination, planModeActive, planModeEnteredSince, watchQuota, watchStops } from "../shared.ts";
 import {
@@ -52,22 +53,22 @@ export function turnTokens(message: unknown): number {
 	return (m.usage.input ?? 0) + (m.usage.output ?? 0) + (m.usage.cacheWrite ?? 0);
 }
 
-export function register(pi: ExtensionAPI, _config: KitConfig): void {
+export function register(pi: ExtensionAPI, _config: KitConfig, clock: Clock = realClock): void {
 	registerChildIdentity(pi);
 	const shared = coordination(pi);
 	let goal: Goal | undefined;
 	let lastCtx: ExtensionContext | undefined;
-	let wakeTimer: ReturnType<typeof setTimeout> | undefined;
+	let wakeTimer: TimerHandle | undefined;
 	let skippedForAgents = false;
 
 	const clearWake = (): void => {
-		if (wakeTimer !== undefined) clearTimeout(wakeTimer);
+		wakeTimer?.cancel();
 		wakeTimer = undefined;
 	};
 
 	const armWake = (): void => {
 		if (wakeTimer !== undefined || goal?.status !== "active" || shared.quotaParked.size > 0) return;
-		wakeTimer = setTimeout(() => {
+		wakeTimer = clock.setTimeout(() => {
 			wakeTimer = undefined;
 			const ctx = lastCtx;
 			if (!ctx || !goal || goal.status !== "active" || isChildSession(pi) || shared.quotaParked.size > 0) return;
@@ -80,7 +81,6 @@ export function register(pi: ExtensionAPI, _config: KitConfig): void {
 				// Stale context: the session is gone.
 			}
 		}, WAKE_MS);
-		wakeTimer.unref();
 	};
 
 	const tracker = new SubagentTracker(() => {

package/src/index.ts

@@ -3,29 +3,50 @@
  * state in session entries (or per-session files) so concurrent pi processes never see each other.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { type Feature, loadConfig } from "./config.ts";
+import type { ExtensionAPI, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type { Clock } from "./clock.ts";
+import { configPath, type Feature, type KitConfig, loadConfig } from "./config.ts";
 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 { register as registerMonitor } from "./monitor/index.ts";
+import type { MonitorProcess, SpawnOptions } from "./monitor/process.ts";
 import { register as registerRules } from "./rules/index.ts";
 import { register as registerStats } from "./stats/index.ts";
 import { register as registerTitles } from "./titles/index.ts";
 
-const MODULES: Record<Feature, (pi: ExtensionAPI, config: ReturnType<typeof loadConfig>) => void> = {
-	titles: registerTitles,
-	rules: registerRules,
-	goal: registerGoal,
-	loop: registerLoop,
-	monitor: registerMonitor,
+/** Explicit configuration and filesystem roots for SDK hosts; omitted values keep CLI defaults. */
+export interface SessionKitOptions {
+	config?: KitConfig;
+	agentDir?: string;
+	monitorRoot?: string;
+	/** Time for stats ranges, loops, goal wakes and monitor batching/timeouts. 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>;
+}
+
+type Register = (pi: ExtensionAPI, config: KitConfig, options: SessionKitOptions) => void;
+
+const MODULES: Record<Feature, Register> = {
+	titles: (pi, config, options) => registerTitles(pi, config, options.agentDir),
+	rules: (pi, config, options) => registerRules(pi, config, options.agentDir),
+	goal: (pi, config, options) => registerGoal(pi, config, options.clock),
+	loop: (pi, config, options) => registerLoop(pi, config, options.clock),
+	monitor: (pi, config, options) =>
+		registerMonitor(pi, config, options.monitorRoot, { clock: options.clock, spawnMonitor: options.spawnMonitor }),
 	diff: registerDiff,
-	stats: registerStats,
+	stats: (pi, config, options) => registerStats(pi, config, options),
 };
 
-export default function (pi: ExtensionAPI): void {
-	const config = loadConfig();
-	for (const [feature, register] of Object.entries(MODULES) as [Feature, (typeof MODULES)[Feature]][]) {
-		if (config.features[feature]) register(pi, config);
-	}
+/** Create the real kit without requiring a machine-local agent configuration. */
+export function createSessionKit(options: SessionKitOptions = {}): ExtensionFactory {
+	return (pi: ExtensionAPI): void => {
+		const config = options.config ?? loadConfig(configPath(options.agentDir));
+		for (const [feature, register] of Object.entries(MODULES) as [Feature, Register][]) {
+			if (config.features[feature]) register(pi, config, options);
+		}
+	};
 }
+
+export default createSessionKit();

package/src/loop/index.ts

@@ -8,20 +8,21 @@
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { isChildSession } from "../child.ts";
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
 import type { KitConfig } from "../config.ts";
 import { coordination, planModeActive, watchQuota, watchStops } from "../shared.ts";
 import { CACHE_WARM_MS, decideTick, describeLoop, formatInterval, type LoopEntry, parseLoopArgs } from "./state.ts";
 
-export function register(pi: ExtensionAPI, _config: KitConfig): void {
+export function register(pi: ExtensionAPI, _config: KitConfig, clock: Clock = realClock): void {
 	const shared = coordination(pi);
-	const loops = new Map<string, { entry: LoopEntry; timer: ReturnType<typeof setInterval> }>();
+	const loops = new Map<string, { entry: LoopEntry; timer: TimerHandle }>();
 	let lastCtx: ExtensionContext | undefined;
 	let nextId = 1;
 
 	const stop = (id: string): void => {
 		const loop = loops.get(id);
 		if (!loop) return;
-		clearInterval(loop.timer);
+		loop.timer.cancel();
 		loops.delete(id);
 	};
 	const stopAll = (): void => {
@@ -131,8 +132,7 @@ export function register(pi: ExtensionAPI, _config: KitConfig): void {
 					runs: 0,
 					skipped: 0,
 				};
-				const timer = setInterval(() => tick(id), command.intervalMs);
-				timer.unref();
+				const timer = clock.setInterval(() => tick(id), command.intervalMs);
 				loops.set(id, { entry, timer });
 				ctx.ui.notify(`loop ${id}: every ${formatInterval(command.intervalMs)}, max ${command.maxRuns} runs`, "info");
 				if (command.intervalMs > CACHE_WARM_MS) {

package/src/monitor/coalescer.ts

@@ -1,4 +1,5 @@
 /** Collects a bounded batch for a fixed window after the first item. */
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
 
 export interface CoalescedBatch<T> {
 	items: T[];
@@ -11,7 +12,7 @@ export class Coalescer<T> {
 	private bytes = 0;
 	private dropped = 0;
 	private droppedMatched = false;
-	private timer: NodeJS.Timeout | undefined;
+	private timer: TimerHandle | undefined;
 
 	constructor(
 		private readonly windowMs: number,
@@ -22,6 +23,7 @@ export class Coalescer<T> {
 			sizeOf?: (item: T) => number;
 			matched?: (item: T) => boolean;
 		} = {},
+		private readonly clock: Clock = realClock,
 	) {}
 
 	add(item: T): void {
@@ -36,12 +38,11 @@ export class Coalescer<T> {
 			this.bytes += size;
 		}
 		if (this.timer) return;
-		this.timer = setTimeout(() => this.flush(), this.windowMs);
-		this.timer.unref();
+		this.timer = this.clock.setTimeout(() => this.flush(), this.windowMs);
 	}
 
 	flush(): void {
-		if (this.timer) clearTimeout(this.timer);
+		this.timer?.cancel();
 		this.timer = undefined;
 		const batch = this.takeBatch();
 		if (batch.items.length === 0 && batch.dropped === 0) return;
@@ -50,13 +51,13 @@ export class Coalescer<T> {
 
 	/** Take what is pending without calling `onFlush`. */
 	take(): CoalescedBatch<T> {
-		if (this.timer) clearTimeout(this.timer);
+		this.timer?.cancel();
 		this.timer = undefined;
 		return this.takeBatch();
 	}
 
 	cancel(): void {
-		if (this.timer) clearTimeout(this.timer);
+		this.timer?.cancel();
 		this.timer = undefined;
 		this.items = [];
 		this.bytes = 0;

package/src/monitor/index.ts

@@ -15,7 +15,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { isChildSession, registerChildIdentity, registerParentTool } from "../child.ts";
 import type { KitConfig } from "../config.ts";
-import { MonitorError, MonitorManager } from "./manager.ts";
+import { type ManagerOptions, MonitorError, MonitorManager } from "./manager.ts";
 import { formatDuration } from "./messages.ts";
 import { boundTail } from "./output.ts";
 import { ensureRoot, rootDir, sessionDirName, sweepOrphans } from "./pidfiles.ts";
@@ -28,8 +28,8 @@ export const TOOL_NAMES = ["monitor_start", "monitor_read", "monitor_stop"] as c
 
 const NOT_AVAILABLE = "monitors are not available in this session";
 
-function describe(info: MonitorInfo): string {
-	const age = formatDuration((info.endedAt ?? Date.now()) - info.startedAt);
+function describeAt(info: MonitorInfo, now: number): string {
+	const age = formatDuration((info.endedAt ?? now) - info.startedAt);
 	const state =
 		info.status === "running"
 			? `running ${age}`
@@ -44,8 +44,14 @@ function text(out: string, details?: unknown, isError = false) {
 	return { content: [{ type: "text" as const, text: out }], details, isError };
 }
 
-export function register(pi: ExtensionAPI, _config: KitConfig): void {
+export function register(
+	pi: ExtensionAPI,
+	_config: KitConfig,
+	monitorRoot?: string,
+	runtime: Pick<ManagerOptions, "clock" | "spawnMonitor"> = {},
+): void {
 	registerChildIdentity(pi);
+	const describe = (info: MonitorInfo): string => describeAt(info, runtime.clock?.now() ?? Date.now());
 	let manager: MonitorManager | undefined;
 	let widget: MonitorWidget | undefined;
 
@@ -62,7 +68,7 @@ export function register(pi: ExtensionAPI, _config: KitConfig): void {
 		await teardown();
 		if (isChildSession(pi)) return;
 		const sessionId = ctx.sessionManager.getSessionId();
-		const root = rootDir();
+		const root = monitorRoot ?? rootDir();
 		try {
 			ensureRoot(root);
 		} catch (error) {
@@ -73,6 +79,7 @@ export function register(pi: ExtensionAPI, _config: KitConfig): void {
 		w.attach(ctx);
 		widget = w;
 		manager = new MonitorManager({
+			...runtime,
 			sessionId,
 			root,
 			send: (message) => {

package/src/monitor/manager.ts

@@ -5,6 +5,7 @@
  */
 
 import { join } from "node:path";
+import { type Clock, realClock, type TimerHandle } from "../clock.ts";
 import { type CoalescedBatch, Coalescer } from "./coalescer.ts";
 import { BoundedMatcher } from "./matcher.ts";
 import { formatMessage, type TaggedLine } from "./messages.ts";
@@ -35,6 +36,8 @@ export interface ManagerOptions {
 	ownerPid?: number;
 	coalesceMs?: number;
 	killGraceMs?: number;
+	clock?: Clock;
+	spawnMonitor?: typeof spawnMonitor;
 }
 
 export class MonitorError extends Error {}
@@ -55,7 +58,7 @@ interface Monitor {
 	proc: MonitorProcess;
 	ring: RingBuffer;
 	coalescer: Coalescer<TaggedLine>;
-	timeoutTimer: NodeJS.Timeout;
+	timeoutTimer: TimerHandle;
 	stopReason: "stop" | "timeout" | undefined;
 	/** Resolves after the exit was fully processed (status set, pidfile removed). */
 	done: Promise<void>;
@@ -67,6 +70,7 @@ export class MonitorManager {
 	private readonly opts: Required<Pick<ManagerOptions, "coalesceMs" | "killGraceMs" | "ownerPid">> & ManagerOptions;
 	/** Names of monitors being spawned right now; reserved so parallel starts cannot exceed the caps. */
 	private readonly starting = new Set<string>();
+	private readonly clock: Clock;
 	private counter = 0;
 	private disposed = false;
 	private readonly exitBackstop = () => {
@@ -74,6 +78,7 @@ export class MonitorManager {
 	};
 
 	constructor(opts: ManagerOptions) {
+		this.clock = opts.clock ?? realClock;
 		this.opts = { coalesceMs: COALESCE_MS, killGraceMs: KILL_GRACE_MS, ownerPid: process.pid, ...opts };
 		this.sessionDir = join(opts.root ?? defaultRootDir(), sessionDirName(opts.sessionId, this.opts.ownerPid));
 		// SIGKILL cannot be caught (the pidfile sweep covers that), but any other exit path must not leak children.
@@ -128,18 +133,22 @@ export class MonitorManager {
 		const ring = new RingBuffer();
 		let monitor: Monitor | undefined;
 		const early: string[] = [];
-		const onLine = (text: string) => {
-			if (monitor) this.ingest(monitor, text);
-			else early.push(text);
+		const onLine = (text: string): Promise<void> => {
+			if (monitor) return this.ingest(monitor, text);
+			early.push(text);
+			return Promise.resolve();
+		};
+		const consume = async (splitter: LineSplitter, chunk: Buffer): Promise<void> => {
+			await Promise.all(splitter.push(chunk).map(onLine));
 		};
 		const out = new LineSplitter();
 		const err = new LineSplitter();
 		let proc: MonitorProcess;
 		try {
-			proc = await spawnMonitor(argv, {
+			proc = await (this.opts.spawnMonitor ?? spawnMonitor)(argv, {
 				cwd,
-				onStdout: (chunk) => out.push(chunk).forEach(onLine),
-				onStderr: (chunk) => err.push(chunk).forEach(onLine),
+				onStdout: (chunk) => consume(out, chunk),
+				onStderr: (chunk) => consume(err, chunk),
 			});
 		} catch (error) {
 			throw new MonitorError(`cannot start ${JSON.stringify(argv[0])}: ${(error as Error).message}`);
@@ -176,9 +185,9 @@ export class MonitorManager {
 			this.opts.coalesceMs,
 			(batch) => this.emitBatch(monitor as Monitor, batch),
 			{ sizeOf: (line) => Buffer.byteLength(line.text), matched: (line) => line.matched },
+			this.clock,
 		);
-		const timeoutTimer = setTimeout(() => this.finishRequested(monitor as Monitor, "timeout"), timeoutMs);
-		timeoutTimer.unref();
+		const timeoutTimer = this.clock.setTimeout(() => this.finishRequested(monitor as Monitor, "timeout"), timeoutMs);
 		monitor = {
 			id,
 			name,
@@ -235,7 +244,7 @@ export class MonitorManager {
 		this.disposed = true;
 		const running = [...this.monitors.values()].filter((m) => m.status === "running");
 		for (const m of running) {
-			clearTimeout(m.timeoutTimer);
+			m.timeoutTimer.cancel();
 			m.coalescer.cancel();
 			m.proc.terminate(this.opts.killGraceMs);
 			// Interrupt a busy regex immediately, rather than making shutdown wait for its deadline.
@@ -248,11 +257,16 @@ export class MonitorManager {
 		process.off("exit", this.exitBackstop);
 	}
 
-	private ingest(m: Monitor, text: string): void {
+	private ingest(m: Monitor, text: string): Promise<void> {
 		const line = m.ring.push(text);
-		const add = (matched: boolean) => m.coalescer.add({ ...line, matched });
-		if (m.matcher) m.matcher.test(text, add);
-		else add(false);
+		return new Promise((resolve) => {
+			const add = (matched: boolean) => {
+				m.coalescer.add({ ...line, matched });
+				resolve();
+			};
+			if (m.matcher) m.matcher.test(text, add);
+			else add(false);
+		});
 	}
 
 	private finishRequested(m: Monitor, reason: "stop" | "timeout"): void {
@@ -262,9 +276,9 @@ export class MonitorManager {
 	}
 
 	private onExited(m: Monitor, exit: ExitInfo): void {
-		clearTimeout(m.timeoutTimer);
+		m.timeoutTimer.cancel();
 		m.exit = exit;
-		m.endedAt = Date.now();
+		m.endedAt = this.clock.now();
 		m.status = m.stopReason === "timeout" ? "timeout" : m.stopReason === "stop" ? "stopped" : "exited";
 		removePidfile(this.sessionDir, m.id);
 		const pending = m.coalescer.take();

package/src/monitor/pidfiles.ts

@@ -32,6 +32,11 @@ const execFileAsync = promisify(execFile);
 
 /** Allowed drift between the recorded spawn time and `ps -o lstart=` (1s resolution plus slack). */
 export const START_TOLERANCE_MS = 5_000;
+/**
+ * `ps lstart` is a whole-second floor of a start time derived from an integer boot time, so a process
+ * started milliseconds after `Date.now()` can read up to one second later, or nearly two earlier.
+ */
+const PS_START_RESOLUTION_MS = 1_000;
 /** Malformed files and empty dirs older than this are cleaned up; younger ones may be mid-write. */
 const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
 
@@ -293,8 +298,8 @@ export async function sweepOrphans(
 						(m) =>
 							m.pgid === record.childPid &&
 							(m.sessionId === undefined || m.sessionId === record.childPid) &&
-							m.startedAt <= record.startedAt &&
-							record.startedAt - m.startedAt < 1_000,
+							m.startedAt < record.startedAt + PS_START_RESOLUTION_MS &&
+							record.startedAt - m.startedAt < 2 * PS_START_RESOLUTION_MS,
 					);
 					if (
 						record.members?.length ||

package/src/monitor/process.ts

@@ -31,8 +31,9 @@ export interface MonitorProcess {
 
 export interface SpawnOptions {
 	cwd: string;
-	onStdout: (chunk: Buffer) => void;
-	onStderr: (chunk: Buffer) => void;
+	/** Resolves when complete lines have been ingested, including matching. Real pipes need not await it. */
+	onStdout: (chunk: Buffer) => void | Promise<void>;
+	onStderr: (chunk: Buffer) => void | Promise<void>;
 }
 
 /**

package/src/rules/index.ts

@@ -49,7 +49,7 @@ export function loadRuleDir(dir: string, source: "project" | "user"): Rule[] {
 	return rules;
 }
 
-export function register(pi: ExtensionAPI, _config: KitConfig): void {
+export function register(pi: ExtensionAPI, _config: KitConfig, userAgentDir = agentDir()): void {
 	let injected = new Set<string>();
 	let turnCount = 0;
 
@@ -75,7 +75,7 @@ export function register(pi: ExtensionAPI, _config: KitConfig): void {
 
 		const rules = [
 			...loadRuleDir(path.join(ctx.cwd, ".pi", "rules"), "project"),
-			...loadRuleDir(path.join(agentDir(), "rules"), "user"),
+			...loadRuleDir(path.join(userAgentDir, "rules"), "user"),
 		];
 		const fresh: Rule[] = [];
 		for (const rule of rules) {

package/src/stats/aggregate.ts

@@ -34,6 +34,8 @@ export interface ModelTotals {
 
 export interface DayPoint {
 	day: string;
+	/** Bucket start instant; hourly series only. */
+	ms?: number;
 	/** Tokens per series key (provider, or `provider/model`). */
 	byKey: Map<string, number>;
 	total: number;
@@ -210,6 +212,7 @@ export function hourlySeries(
 	const points: DayPoint[] = [];
 	for (let ms = from; ms <= to; ms += HOUR_MS)
 		points.push({
+			ms,
 			day: `${hourLabel(ms)}${ms < start || ms + HOUR_MS > now ? " (partial)" : ""}`,
 			byKey: new Map(),
 			total: 0,