@nredd/pi-session-kit 0.0.0-stage → 0.4.0

package/src/index.ts

@@ -0,0 +1,52 @@
+/**
+ * pi-session-kit: session-scoped extensions. No daemon and no shared state: every feature keeps its
+ * state in session entries (or per-session files) so concurrent pi processes never see each other.
+ */
+
+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";
+
+/** 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: (pi, config, options) => registerStats(pi, config, options),
+};
+
+/** 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

@@ -0,0 +1,151 @@
+/**
+ * `/loop <interval> <prompt>`: re-send a prompt into this session on a timer.
+ *
+ * Per-process and in-memory only: loops die with the session (`session_shutdown`, `/new`) and are
+ * never persisted. A tick that finds the agent busy is skipped, never queued. Ticks do not fire
+ * while a `/goal` is active (they would fight over the same idle gaps) or Plan mode is on.
+ */
+
+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, clock: Clock = realClock): void {
+	const shared = coordination(pi);
+	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;
+		loop.timer.cancel();
+		loops.delete(id);
+	};
+	const stopAll = (): void => {
+		for (const id of [...loops.keys()]) stop(id);
+	};
+
+	const tick = (id: string): void => {
+		const loop = loops.get(id);
+		const ctx = lastCtx;
+		if (!loop || !ctx) return;
+		try {
+			const decision = decideTick({
+				isChild: isChildSession(pi),
+				busy: !ctx.isIdle() || ctx.hasPendingMessages() || shared.quotaParked.size > 0,
+				goalActive: shared.goalActive,
+				planMode: planModeActive(ctx),
+				loop: loop.entry,
+			});
+			if (!decision.fire) {
+				if (decision.reason !== "paused") loop.entry.skipped++;
+				return;
+			}
+			loop.entry.runs++;
+			pi.sendUserMessage(loop.entry.prompt, { expandPromptTemplates: true });
+			if (loop.entry.runs >= loop.entry.maxRuns) {
+				stop(id);
+				ctx.ui.notify(`loop ${id} finished: ${loop.entry.maxRuns} runs`, "info");
+			}
+		} catch {
+			// Stale context: the session this loop belonged to is gone.
+			stopAll();
+		}
+	};
+
+	pi.on("session_start", (_event, ctx) => {
+		stopAll();
+		lastCtx = ctx;
+	});
+	pi.on("session_shutdown", () => stopAll());
+	pi.on("before_agent_start", (_event, ctx) => {
+		lastCtx = ctx;
+	});
+
+	const pauseLoops = (reason: string, ctx: ExtensionContext): void => {
+		let paused = 0;
+		for (const { entry } of loops.values()) {
+			if (entry.paused) continue;
+			entry.paused = reason;
+			paused++;
+		}
+		if (paused > 0) ctx.ui.notify(`loop paused (${paused}): ${reason}. /loop resume after resolving it`, "warning");
+	};
+
+	watchQuota(pi, (reason, ctx) => {
+		if (!isChildSession(pi)) pauseLoops(reason, ctx);
+	});
+
+	watchStops(pi, (outcome, ctx) => {
+		if (outcome !== "error" || isChildSession(pi)) return;
+		pauseLoops("provider error", ctx);
+	});
+
+	const select = (target: string): string[] =>
+		target === "all" ? [...loops.keys()] : loops.has(target) ? [target] : [];
+
+	/** Registered from `session_start` so subagent (child) sessions never get `/loop`; see `/goal`. */
+	const registerLoopCommand = (): void => {
+		pi.registerCommand("loop", {
+			description:
+				"Re-send a prompt on a timer: /loop <30s|5m|1h> <prompt> [--max N] | list | stop [id|all] | resume [id|all]",
+			getArgumentCompletions: (prefix) => {
+				const items = ["list", "stop", "resume"]
+					.filter((name) => name.startsWith(prefix))
+					.map((name) => ({ value: name, label: name }));
+				return items.length > 0 ? items : null;
+			},
+			handler: async (args, ctx) => {
+				if (isChildSession(pi)) return;
+				lastCtx = ctx;
+				shared.reconcilePlanMode?.(ctx);
+				const command = parseLoopArgs(args);
+				if (command.kind === "error") return ctx.ui.notify(command.message, "error");
+				if (command.kind === "list") {
+					const lines = [...loops.values()].map(({ entry }) => describeLoop(entry));
+					return ctx.ui.notify(lines.length > 0 ? lines.join("\n") : "no loops", "info");
+				}
+				if (command.kind === "stop" || command.kind === "resume") {
+					if (command.kind === "resume" && shared.quotaParked.size > 0)
+						return ctx.ui.notify("refused: quota dispatch is still parked. Resolve it before resuming loops", "error");
+					const ids = select(command.target);
+					if (ids.length === 0)
+						return ctx.ui.notify(command.target === "all" ? "no loops" : `no loop ${command.target}`, "error");
+					for (const id of ids) {
+						if (command.kind === "stop") stop(id);
+						else delete loops.get(id)?.entry.paused;
+					}
+					return ctx.ui.notify(`${command.kind === "stop" ? "stopped" : "resumed"} ${ids.join(", ")}`, "info");
+				}
+				if (command.kind !== "start") return;
+				const id = String(nextId++);
+				const entry: LoopEntry = {
+					id,
+					intervalMs: command.intervalMs,
+					prompt: command.prompt,
+					maxRuns: command.maxRuns,
+					...(shared.quotaParked.size > 0 ? { paused: "quota parked" } : {}),
+					runs: 0,
+					skipped: 0,
+				};
+				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) {
+					ctx.ui.notify(
+						`loop ${id}: interval above 5m, every tick pays a cold prompt cache (use 5m or less to keep it warm)`,
+						"warning",
+					);
+				}
+			},
+		});
+	};
+
+	pi.on("session_start", () => {
+		if (!isChildSession(pi)) registerLoopCommand();
+	});
+}

package/src/loop/state.ts

@@ -0,0 +1,107 @@
+/**
+ * Pure `/loop` logic: interval and command parsing, the tick decision and list formatting.
+ * No pi imports.
+ */
+
+export const MIN_INTERVAL_MS = 30_000;
+/** Longer than this and every tick finds a cold prompt cache (5 minute TTL). */
+export const CACHE_WARM_MS = 5 * 60_000;
+export const MAX_INTERVAL_MS = 24 * 60 * 60_000;
+/** Hard ceiling on `--max`: larger requests are clamped, never honoured. */
+export const MAX_RUNS_CEILING = 50;
+export const DEFAULT_MAX_RUNS = MAX_RUNS_CEILING;
+
+export type LoopCommand =
+	| { kind: "start"; intervalMs: number; prompt: string; maxRuns: number }
+	| { kind: "list" }
+	| { kind: "stop" | "resume"; target: string }
+	| { kind: "error"; message: string };
+
+const UNITS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000 };
+
+/** `30s`, `5m`, `1h` -> milliseconds, or an error string. */
+export function parseInterval(raw: string): { ok: true; ms: number } | { ok: false; error: string } {
+	const match = /^(\d+)([smh])$/i.exec(raw.trim());
+	if (!match) return { ok: false, error: `bad interval "${raw}" (use 30s, 5m or 1h)` };
+	const ms = Number(match[1]) * (UNITS[(match[2] as string).toLowerCase()] as number);
+	if (ms < MIN_INTERVAL_MS) return { ok: false, error: `interval ${raw} is below the 30s minimum` };
+	if (ms > MAX_INTERVAL_MS) return { ok: false, error: `interval ${raw} is above the 24h maximum` };
+	return { ok: true, ms };
+}
+
+export function formatInterval(ms: number): string {
+	if (ms % 3_600_000 === 0) return `${ms / 3_600_000}h`;
+	if (ms % 60_000 === 0) return `${ms / 60_000}m`;
+	return `${ms / 1_000}s`;
+}
+
+const USAGE = "usage: /loop <30s|5m|1h> <prompt> [--max N] | list | stop [id|all] | resume [id|all]";
+
+/** Parse `/loop` arguments. A bare `/loop` lists. */
+export function parseLoopArgs(raw: string): LoopCommand {
+	const text = raw.trim();
+	if (text === "" || text === "list") return { kind: "list" };
+	const [head = "", ...rest] = text.split(/\s+/);
+	if (head === "stop" || head === "resume") {
+		if (rest.length > 1) return { kind: "error", message: USAGE };
+		return { kind: head, target: rest[0] ?? "all" };
+	}
+	const interval = parseInterval(head);
+	if (!interval.ok) return { kind: "error", message: `${interval.error}. ${USAGE}` };
+	const words: string[] = [];
+	let maxRuns = DEFAULT_MAX_RUNS;
+	for (let i = 0; i < rest.length; i++) {
+		const token = rest[i] as string;
+		const flag = /^--max(?:=(.*))?$/.exec(token);
+		if (!flag) {
+			words.push(token);
+			continue;
+		}
+		const value = flag[1] ?? rest[++i] ?? "";
+		const count = /^\d+$/.test(value) ? Number(value) : Number.NaN;
+		if (!Number.isSafeInteger(count) || count < 1)
+			return { kind: "error", message: `--max needs a positive integer (got "${value}")` };
+		maxRuns = Math.min(count, MAX_RUNS_CEILING);
+	}
+	const prompt = words.join(" ");
+	if (prompt === "") return { kind: "error", message: USAGE };
+	return { kind: "start", intervalMs: interval.ms, prompt, maxRuns };
+}
+
+export interface LoopEntry {
+	id: string;
+	intervalMs: number;
+	prompt: string;
+	maxRuns: number;
+	runs: number;
+	skipped: number;
+	/** Why ticks are suspended (provider error); cleared by `/loop resume`. */
+	paused?: string;
+}
+
+export interface TickInput {
+	isChild: boolean;
+	busy: boolean;
+	goalActive: boolean;
+	planMode: boolean;
+	loop: LoopEntry;
+}
+
+export type TickDecision = { fire: true } | { fire: false; reason: string };
+
+/** Whether a timer tick may send the prompt. A skip never counts as a run and never queues. */
+export function decideTick(input: TickInput): TickDecision {
+	if (input.isChild) return { fire: false, reason: "child session" };
+	if (input.loop.paused) return { fire: false, reason: "paused" };
+	if (input.loop.runs >= input.loop.maxRuns) return { fire: false, reason: "run cap reached" };
+	if (input.goalActive) return { fire: false, reason: "goal active" };
+	if (input.planMode) return { fire: false, reason: "plan mode" };
+	if (input.busy) return { fire: false, reason: "agent busy" };
+	return { fire: true };
+}
+
+export function describeLoop(loop: LoopEntry): string {
+	const prompt = loop.prompt.length > 60 ? `${loop.prompt.slice(0, 57)}...` : loop.prompt;
+	const pause = loop.paused ? ` [paused: ${loop.paused}]` : "";
+	return `${loop.id}: every ${formatInterval(loop.intervalMs)}, ${loop.runs}/${loop.maxRuns} runs, ${loop.skipped} skipped: ${prompt}${pause}`;
+}

package/src/monitor/README.md

@@ -0,0 +1,12 @@
+Process and matching limits:
+- `../diff/git.ts` awaits the scheduled group `SIGKILL` after timeout or output-cap termination, even if the leader exits and descendants close their pipes. The existing 2s TERM grace and 1s hard-resolve bound remain. Signals never fall back to a potentially reused bare PID.
+- `pidfiles.ts` serializes each record behind a PID/token sweep guard, then rereads it before validation. A live guard is never removed, regardless of age; confirmed dead guards are reclaimed by unlinking only their immutable owner filename and removing the empty directory. Empty/unknown guards require manual inspection and are reported as failures, never age-reclaimed. Interrupted cleaners retain persisted recovery identities. Cleanup failures/busy guards are returned in `failed` and reported as startup warnings.
+- For a leader that exited before the first sweep, a surviving member must belong to the recorded group and have started in the recorded spawn second, no later than the recorded spawn timestamp. Linux additionally validates the detached session ID against the original leader PID; macOS `ps` exposes an unusable zero session field, so group membership plus start time is the available identity boundary. Later-born-only survivors, changed persisted identities, reused live leaders and failed process queries retain the record and report failure rather than signal or silently discard it. An empty group permits removal. This conservative fallback cannot reclaim every orphan safely.
+- `pidfiles.ts` authenticates the leader, snapshots group member PID/start-time/command identities, revalidates the leader, and atomically persists the snapshot before TERM. Cleanup is awaited; the file remains on uncertainty. Escalation and recovery require an exact surviving member identity in the recorded group, so leader death does not skip KILL. Reused identities do not authorize signals. Groups that escape via `setsid`, or change every recorded identity, cannot be safely reclaimed. `ps` has one-second start-time precision and identity checking plus signaling is not atomic on macOS; identical-command same-second PID reuse and check-to-signal races remain platform limitations.
+- `matcher.ts` evaluates JavaScript regexes in one worker per matching monitor. Each line has a 100ms execution deadline, startup and final drain have 1s deadlines, and queued text plus per-item overhead is capped at 256KiB. Lines already have the splitter's 4096-character cap. Matching preserves order and final-output match markers. Timeout, queue overflow or worker failure disables matching for that monitor and marks pending/future lines matched, conservatively waking on output rather than silently dropping alerts. This can produce false-positive wakes. Worker termination is awaited on exit and disposal; disposal interrupts pending matching immediately. Timer deadlines are subject to normal event-loop scheduling, not realtime guarantees.
+
+Regression commands (from the repository root):
+```
+npx vitest run test/diff/git.test.ts test/monitor/pidfiles.test.ts test/monitor/manager.test.ts test/monitor/matcher.test.ts
+```
+These exercise real TERM-resistant descendant processes, leader exit with closed pipes, orphan escalation, leader exit before any sweep, two concurrent real cleaners with interruption and dead-guard recovery, persisted recovery, changed identities, catastrophic backtracking, final match draining and shutdown during matching. Process fixtures require macOS or Linux.

package/src/monitor/coalescer.ts

@@ -0,0 +1,76 @@
+/** 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[];
+	dropped: number;
+	droppedMatched: boolean;
+}
+
+export class Coalescer<T> {
+	private items: T[] = [];
+	private bytes = 0;
+	private dropped = 0;
+	private droppedMatched = false;
+	private timer: TimerHandle | undefined;
+
+	constructor(
+		private readonly windowMs: number,
+		private readonly onFlush: (batch: CoalescedBatch<T>) => void,
+		private readonly options: {
+			maxItems?: number;
+			maxBytes?: number;
+			sizeOf?: (item: T) => number;
+			matched?: (item: T) => boolean;
+		} = {},
+		private readonly clock: Clock = realClock,
+	) {}
+
+	add(item: T): void {
+		const size = this.options.sizeOf?.(item) ?? 1;
+		const maxItems = this.options.maxItems ?? 200;
+		const maxBytes = this.options.maxBytes ?? 64 * 1024;
+		if (this.items.length >= maxItems || this.bytes + size > maxBytes) {
+			this.dropped++;
+			this.droppedMatched ||= this.options.matched?.(item) ?? false;
+		} else {
+			this.items.push(item);
+			this.bytes += size;
+		}
+		if (this.timer) return;
+		this.timer = this.clock.setTimeout(() => this.flush(), this.windowMs);
+	}
+
+	flush(): void {
+		this.timer?.cancel();
+		this.timer = undefined;
+		const batch = this.takeBatch();
+		if (batch.items.length === 0 && batch.dropped === 0) return;
+		this.onFlush(batch);
+	}
+
+	/** Take what is pending without calling `onFlush`. */
+	take(): CoalescedBatch<T> {
+		this.timer?.cancel();
+		this.timer = undefined;
+		return this.takeBatch();
+	}
+
+	cancel(): void {
+		this.timer?.cancel();
+		this.timer = undefined;
+		this.items = [];
+		this.bytes = 0;
+		this.dropped = 0;
+		this.droppedMatched = false;
+	}
+
+	private takeBatch(): CoalescedBatch<T> {
+		const batch = { items: this.items, dropped: this.dropped, droppedMatched: this.droppedMatched };
+		this.items = [];
+		this.bytes = 0;
+		this.dropped = 0;
+		this.droppedMatched = false;
+		return batch;
+	}
+}

package/src/monitor/index.ts

@@ -0,0 +1,220 @@
+/**
+ * `/monitor`: background process watchers the model can start, read and stop.
+ *
+ * - `monitor_start` / `monitor_read` / `monitor_stop` tools and a `/monitor` command (list, stop)
+ * - output is coalesced for 2s into ONE custom message per monitor; the agent is only woken on a
+ *   `match` hit, on exit/timeout, or when `wake: true`, otherwise the message is passive context
+ * - every child dies on `session_shutdown`, which pi fires for quit AND for /new, /resume, /fork
+ *   and /reload (a reload replaces the extension runtime, so a monitor could not be reattached
+ *   anyway). A SIGKILLed pi leaves pidfiles; the next session sweeps only dead owners' files
+ * - plan mode: only `monitor_read` carries `readOnlyHint`, so the `pi-plan-mode` fork admits just
+ *   that. `monitor_start` runs arbitrary argv and goes through the normal `tool_call` guards
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { isChildSession, registerChildIdentity, registerParentTool } from "../child.ts";
+import type { KitConfig } from "../config.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";
+import type { MonitorInfo } from "./types.ts";
+import { MAX_MONITORS, MAX_TIMEOUT_S } from "./validate.ts";
+import { MonitorWidget } from "./widget.ts";
+
+export const MESSAGE_TYPE = "session-kit:monitor";
+export const TOOL_NAMES = ["monitor_start", "monitor_read", "monitor_stop"] as const;
+
+const NOT_AVAILABLE = "monitors are not available in this session";
+
+function describeAt(info: MonitorInfo, now: number): string {
+	const age = formatDuration((info.endedAt ?? now) - info.startedAt);
+	const state =
+		info.status === "running"
+			? `running ${age}`
+			: info.signal
+				? `${info.status} (${info.signal}) after ${age}`
+				: `${info.status} (code ${info.exitCode ?? "?"}) after ${age}`;
+	const extra = [info.match ? `match /${info.match}/` : "", info.wake ? "wake" : ""].filter(Boolean).join(" ");
+	return `${info.id} "${info.name}" ${state}, ${info.lines} lines, pid ${info.pid}${extra ? `, ${extra}` : ""}: ${info.argv.join(" ")}`;
+}
+
+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,
+	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;
+
+	const teardown = async (): Promise<void> => {
+		const old = manager;
+		const oldWidget = widget;
+		manager = undefined;
+		widget = undefined;
+		oldWidget?.dispose();
+		await old?.dispose();
+	};
+
+	pi.on("session_start", async (_event, ctx: ExtensionContext) => {
+		await teardown();
+		if (isChildSession(pi)) return;
+		const sessionId = ctx.sessionManager.getSessionId();
+		const root = monitorRoot ?? rootDir();
+		try {
+			ensureRoot(root);
+		} catch (error) {
+			ctx.ui.notify(`/monitor: cannot create ${root}: ${(error as Error).message}`, "warning");
+			return;
+		}
+		const w = new MonitorWidget(() => manager?.running() ?? []);
+		w.attach(ctx);
+		widget = w;
+		manager = new MonitorManager({
+			...runtime,
+			sessionId,
+			root,
+			send: (message) => {
+				pi.sendMessage(
+					{ customType: MESSAGE_TYPE, content: message.text, display: true, details: message.details },
+					message.wake ? { triggerTurn: true, deliverAs: "followUp" } : { triggerTurn: false },
+				);
+			},
+			onChange: () => w.refresh(),
+		});
+		// Fire and forget: never delay startup on the sweep, and never let it throw into pi.
+		sweepOrphans(root, sessionDirName(sessionId, process.pid))
+			.then((result) => {
+				if (result.failed.length)
+					ctx.ui.notify(`/monitor: retained uncertain or busy orphan records: ${result.failed.join(", ")}`, "warning");
+			})
+			.catch((error: unknown) => ctx.ui.notify(`/monitor: orphan cleanup failed: ${String(error)}`, "warning"));
+	});
+
+	pi.on("session_shutdown", teardown);
+
+	registerParentTool(pi, {
+		name: "monitor_start",
+		label: "Monitor start",
+		description:
+			"Start a long-running background process (log tail, watcher, poller) and get its output as it appears. " +
+			'argv is spawned directly with no shell; use ["sh","-c","..."] explicitly for pipes. ' +
+			"Output lines are coalesced for 2s into one message. You are woken only when a line matches `match` " +
+			"(JS regex), when the process exits or times out, or on every batch when `wake` is true; otherwise output " +
+			"is passive context and monitor_read fetches it. Do not use this for commands that finish quickly.",
+		promptSnippet: "Start a background process and be woken on matching output or exit",
+		parameters: Type.Object({
+			argv: Type.Array(Type.String(), { minItems: 1, description: "Command and arguments, no shell" }),
+			name: Type.String({ description: "Unique short name, [A-Za-z0-9._-]" }),
+			match: Type.Optional(Type.String({ description: "JS regex; a matching line wakes you" })),
+			wake: Type.Optional(Type.Boolean({ description: "Wake on every output batch" })),
+			timeout_s: Type.Optional(
+				Type.Number({ minimum: 1, maximum: MAX_TIMEOUT_S, description: "Kill after this many seconds (default 3600)" }),
+			),
+		}),
+		annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+		async execute(_id, params, _signal, _update, ctx) {
+			if (!manager) return text(NOT_AVAILABLE, undefined, true);
+			try {
+				const info = await manager.start(params, ctx.cwd);
+				const how = info.match
+					? `wakes on /${info.match}/`
+					: info.wake
+						? "wakes on every batch"
+						: "passive (wakes on exit)";
+				return text(
+					`started ${info.id} "${info.name}" (pid ${info.pid}); ${how}; killed after ${formatDuration(info.timeoutMs)}. ` +
+						`${MAX_MONITORS} monitors max per session.`,
+					info,
+				);
+			} catch (error) {
+				if (error instanceof MonitorError) return text(error.message, undefined, true);
+				throw error;
+			}
+		},
+	});
+
+	registerParentTool(pi, {
+		name: "monitor_read",
+		label: "Monitor read",
+		description:
+			"Read buffered output (last 2000 lines kept) of a monitor by id or name. `since` is a line number: only " +
+			"later lines are returned. The result ends with `next since` to pass on the following call.",
+		promptSnippet: "Read output of a running or finished background monitor",
+		parameters: Type.Object({
+			id: Type.String({ description: "Monitor id (m1) or name" }),
+			since: Type.Optional(Type.Number({ minimum: 0, description: "Only lines numbered after this" })),
+		}),
+		annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+		async execute(_id, params) {
+			if (!manager) return text(NOT_AVAILABLE, undefined, true);
+			const read = manager.read(params.id, params.since);
+			if (!read) return text(`no monitor "${params.id}"; /monitor lists them`, undefined, true);
+			const { info } = read;
+			const head = [describe(info)];
+			if (read.missed > 0) head.push(`${read.missed} older lines were evicted from the 2000-line buffer`);
+			const body = read.lines.map((l) => `${l.n}: ${l.text}`).join("\n");
+			const bounded = await boundTail(body, `${info.id}-read`);
+			const tail = `next since: ${read.lastLine}`;
+			return text([...head, bounded.text || "(no new output)", tail].join("\n"), {
+				...info,
+				lastLine: read.lastLine,
+				fullOutputPath: bounded.fullOutputPath,
+			});
+		},
+	});
+
+	registerParentTool(pi, {
+		name: "monitor_stop",
+		label: "Monitor stop",
+		description: "Stop a monitor by id or name: SIGTERM to its process group, SIGKILL after 2s.",
+		promptSnippet: "Stop a background monitor",
+		parameters: Type.Object({ id: Type.String({ description: "Monitor id (m1) or name" }) }),
+		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+		async execute(_id, params) {
+			if (!manager) return text(NOT_AVAILABLE, undefined, true);
+			const info = await manager.stop(params.id);
+			if (!info) return text(`no monitor "${params.id}"; /monitor lists them`, undefined, true);
+			return text(describe(info), info);
+		},
+	});
+
+	pi.registerCommand("monitor", {
+		description: "List background monitors, or `stop <id|name|all>`",
+		getArgumentCompletions: (prefix) =>
+			["list", "stop all", ...(manager?.running().map((m) => `stop ${m.id}`) ?? [])]
+				.filter((c) => c.startsWith(prefix))
+				.map((value) => ({ value, label: value })),
+		async handler(args, ctx) {
+			if (!manager) {
+				ctx.ui.notify(`/monitor: ${NOT_AVAILABLE}`, "warning");
+				return;
+			}
+			const [sub = "list", ...rest] = args.trim().split(/\s+/).filter(Boolean);
+			const target = rest.join(" ");
+			if (sub === "list" && rest.length === 0) {
+				const all = manager.list();
+				ctx.ui.notify(all.length === 0 ? "no monitors" : all.map(describe).join("\n"), "info");
+			} else if (sub === "stop" && target === "all") {
+				const stopped = await manager.stopAll();
+				ctx.ui.notify(
+					stopped.length === 0 ? "no running monitors" : `stopped ${stopped.map((m) => m.id).join(", ")}`,
+					"info",
+				);
+			} else if (sub === "stop" && target) {
+				const info = await manager.stop(target);
+				ctx.ui.notify(info ? `stopped ${describe(info)}` : `no monitor "${target}"`, info ? "info" : "error");
+			} else {
+				ctx.ui.notify("usage: /monitor [list] | /monitor stop <id|name|all>", "warning");
+			}
+		},
+	});
+}