pi-famulus 0.1.7 → 0.1.9

package/src/native-manager.js

@@ -1,5 +1,9 @@
-import { accessSync, constants, readFileSync, statSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { accessSync, closeSync, constants, mkdirSync, openSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 import { getSystemErrorMap } from "node:util";
 
 // Filesystem failures mean this optional package is unusable, regardless of the syscall code.
@@ -11,8 +15,10 @@ const resolutionErrorCodes = new Set([
   "ERR_INVALID_MODULE_SPECIFIER", "ERR_UNSUPPORTED_RESOLVE_REQUEST",
 ]);
 
+const modulePath = fileURLToPath(import.meta.url);
 const packageVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 const resolveInstalled = createRequire(import.meta.url).resolve;
+const RESTORE_HINT = "not installed; run `npm install --include=optional pi-famulus`";
 
 /** The native optional packages are selected by npm's os/cpu constraints. */
 export function nativePackageName(platform, arch) {
@@ -23,20 +29,263 @@ export function nativePackageName(platform, arch) {
   return `pi-famulus-${packageOs}-${arch}`;
 }
 
+/**
+ * Cache for the exact platform package. `pi update --extensions` reinstalls
+ * with npm, and `omit=optional` (user or project npmrc) deletes optional
+ * dependencies during that install. The cache is outside the famulus runtime
+ * home and outside pi's package tree, so the next update does not remove it.
+ */
+export function nativeCacheDir({
+  version = packageVersion,
+  platform = process.platform,
+  arch = process.arch,
+  env = process.env,
+  home = homedir(),
+} = {}) {
+  const base = platform === "win32"
+    ? join(env.LOCALAPPDATA || join(home, "AppData", "Local"), "pi-famulus", "native")
+    : join(env.XDG_CACHE_HOME || join(home, ".cache"), "pi-famulus", "native");
+  return join(base, version, `${platform}-${arch}`);
+}
+
+function isIgnoredResolveError(error) {
+  return error instanceof SyntaxError || systemErrorCodes.has(error?.code) || resolutionErrorCodes.has(error?.code);
+}
+
+function executableFile(path) {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile() || stat.size <= 0) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch (error) {
+    if (isIgnoredResolveError(error)) return false;
+    throw error;
+  }
+}
+
+/** Usable exact-version binary inside one package directory, or null. */
+function binaryInPackage(dir, name) {
+  let metadata;
+  try {
+    metadata = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  } catch (error) {
+    if (isIgnoredResolveError(error)) return null;
+    throw error;
+  }
+  if (!metadata || metadata.name !== name || metadata.version !== packageVersion) return null;
+  const exported = metadata.exports?.["./bin/pi-famulus"];
+  const rel = typeof exported === "string" ? exported : metadata.main;
+  if (typeof rel !== "string" || !rel.startsWith("./") || rel.split("/").includes("..")) return null;
+  const binary = join(dir, rel);
+  const root = dir.endsWith(sep) ? dir : dir + sep;
+  if (!binary.startsWith(root)) return null;
+  return executableFile(binary) ? binary : null;
+}
+
+function walkNodeModules(startFile, stopAt) {
+  const dirs = [];
+  let dir = dirname(startFile);
+  const seen = new Set();
+  const boundary = stopAt ? resolve(stopAt) : null;
+  while (!seen.has(dir)) {
+    seen.add(dir);
+    dirs.push(join(dir, "node_modules"));
+    if (boundary && (dir === boundary || !dir.startsWith(boundary.endsWith(sep) ? boundary : boundary + sep))) break;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return dirs;
+}
+
+function legacyResolve(name, resolve) {
+  const metadata = JSON.parse(readFileSync(resolve(`${name}/package.json`), "utf8"));
+  if (!metadata || metadata.name !== name || metadata.version !== packageVersion) return null;
+  const binary = resolve(`${name}/bin/pi-famulus`);
+  const stat = statSync(binary);
+  if (!stat.isFile() || stat.size <= 0) return null;
+  accessSync(binary, constants.X_OK);
+  return binary;
+}
+
+function searchNative({ platform = process.platform, arch = process.arch, from, stopAt, cacheDir } = {}) {
+  const name = nativePackageName(platform, arch);
+  if (!name) return { name: null, path: null, detail: `unsupported ${platform}/${arch}` };
+  let start = from ?? modulePath;
+  if (!from) {
+    try { start = realpathSync(modulePath); } catch { /* keep the URL path */ }
+  }
+  const seen = new Set();
+  for (const nodeModules of walkNodeModules(start, stopAt)) {
+    const dir = join(nodeModules, name);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    const binary = binaryInPackage(dir, name);
+    if (binary) return { name, path: binary, detail: "" };
+  }
+  // NODE_PATH and other resolver roots. An explicit `from` is a hermetic walk.
+  if (!from) {
+    try {
+      const resolved = dirname(resolveInstalled(`${name}/package.json`));
+      if (!seen.has(resolved)) {
+        const binary = binaryInPackage(resolved, name);
+        if (binary) return { name, path: binary, detail: "" };
+      }
+    } catch (error) {
+      if (!isIgnoredResolveError(error)) throw error;
+    }
+  }
+  if (cacheDir !== false) {
+    const dir = join(cacheDir ?? nativeCacheDir({ platform, arch }), "node_modules", name);
+    const binary = binaryInPackage(dir, name);
+    if (binary) return { name, path: binary, detail: "" };
+  }
+  return { name, path: null, detail: RESTORE_HINT };
+}
+
 /** Resolve the exact-version optional package without loading native executable bytes. */
-export function resolveNativeManagerPath({ platform = process.platform, arch = process.arch, resolve = resolveInstalled } = {}) {
+export function resolveNativeManagerPath({ platform = process.platform, arch = process.arch, resolve, from, stopAt, cacheDir } = {}) {
   const name = nativePackageName(platform, arch);
   if (!name) return null;
+  // Injected resolvers stay hermetic: tests use them to simulate one install tree.
+  if (resolve) {
+    try {
+      return legacyResolve(name, resolve);
+    } catch (error) {
+      if (isIgnoredResolveError(error)) return null;
+      throw error;
+    }
+  }
+  return searchNative({ platform, arch, from, stopAt, cacheDir }).path;
+}
+
+/** `npm <package> <path>` or why that exact platform package was not usable. */
+export function describeNativeLookup(options) {
+  const name = nativePackageName(options?.platform ?? process.platform, options?.arch ?? process.arch);
+  if (!name) return `npm native manager (unsupported ${options?.platform ?? process.platform}/${options?.arch ?? process.arch})`;
+  if (options?.resolve) {
+    const path = resolveNativeManagerPath(options);
+    return path ? `npm ${name} ${path}` : `npm ${name} (missing or unusable, ignored)`;
+  }
+  const found = searchNative(options);
+  return found.path ? `npm ${name} ${found.path}` : `npm ${name} (${found.detail})`;
+}
+
+function pidAlive(pid) {
   try {
-    const metadata = JSON.parse(readFileSync(resolve(`${name}/package.json`), "utf8"));
-    if (!metadata || metadata.name !== name || metadata.version !== packageVersion) return null;
-    const binary = resolve(`${name}/bin/pi-famulus`);
-    const stat = statSync(binary);
-    if (!stat.isFile() || stat.size <= 0) return null;
-    accessSync(binary, constants.X_OK);
-    return binary;
+    process.kill(pid, 0);
+    return true;
   } catch (error) {
-    if (error instanceof SyntaxError || systemErrorCodes.has(error?.code) || resolutionErrorCodes.has(error?.code)) return null;
-    throw error;
+    return error?.code === "EPERM";
+  }
+}
+
+function sleepMs(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+/** A lock left by a dead process, or held far longer than one npm install, can be replaced. */
+function installLockIsStale(lockPath) {
+  try {
+    const age = Date.now() - statSync(lockPath).mtimeMs;
+    const pid = Number(readFileSync(lockPath, "utf8").trim());
+    if (Number.isInteger(pid) && pid > 0) return !pidAlive(pid) || age > 150_000;
+    return age > 5_000;
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * One npm install per cache directory. Another startup either waits until that
+ * install publishes a binary or takes over a stale lock. Returns the open lock,
+ * or null when waiting itself produced a usable binary.
+ */
+function acquireInstallLock(dir, lookup) {
+  mkdirSync(dir, { recursive: true });
+  const lockPath = `${dir}.install.lock`;
+  const deadline = Date.now() + 130_000;
+  while (Date.now() <= deadline) {
+    try {
+      const fd = openSync(lockPath, "wx");
+      try { writeSync(fd, String(process.pid)); } catch { /* the fd is still the lock */ }
+      return { fd, lockPath };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+      const ready = resolveNativeManagerPath(lookup);
+      if (ready) return null;
+      if (installLockIsStale(lockPath)) {
+        rmSync(lockPath, { force: true });
+        continue;
+      }
+      sleepMs(200);
+    }
+  }
+  return null;
+}
+
+function releaseInstallLock(lock) {
+  if (!lock) return;
+  try { closeSync(lock.fd); } catch { /* already closed */ }
+  rmSync(lock.lockPath, { force: true });
+}
+
+/**
+ * Install the exact platform package into the versioned cache when the
+ * optional dependency is missing. No-ops when a usable binary is already
+ * resolvable. `PI_FAMULUS_NO_NATIVE_FETCH=1`, `PI_OFFLINE=1`, and Vitest skip
+ * the install. Directory, manifest, and npm failures return null so startup
+ * degrades instead of throwing.
+ */
+export function ensureNativeManagerInstalled({
+  platform = process.platform,
+  arch = process.arch,
+  cacheDir,
+  env = process.env,
+  npmCommand,
+  spawn = spawnSync,
+  from,
+  stopAt,
+} = {}) {
+  const lookup = { platform, arch, cacheDir, from, stopAt };
+  try {
+    const existing = resolveNativeManagerPath(lookup);
+    if (existing) return existing;
+    if (!nativePackageName(platform, arch)) return null;
+    if (env.PI_FAMULUS_NO_NATIVE_FETCH === "1" || env.PI_OFFLINE === "1" || env.VITEST) return null;
+    if (cacheDir === false) return null;
+    const dir = cacheDir ?? nativeCacheDir({ platform, arch, env });
+    const lockedLookup = { ...lookup, cacheDir: dir };
+    const lock = acquireInstallLock(dir, lockedLookup);
+    if (!lock) return resolveNativeManagerPath(lockedLookup);
+    try {
+      const manifest = join(dir, "package.json");
+      try {
+        readFileSync(manifest);
+      } catch {
+        writeFileSync(manifest, `${JSON.stringify({ private: true, name: "pi-famulus-native-cache", version: "0.0.0" })}\n`);
+      }
+      const command = npmCommand ?? (platform === "win32" ? "npm.cmd" : "npm");
+      const name = nativePackageName(platform, arch);
+      let result;
+      try {
+        result = spawn(command, [
+          "install", `${name}@${packageVersion}`,
+          "--prefix", dir,
+          "--ignore-scripts", "--no-fund", "--no-audit", "--loglevel=error",
+        ], { timeout: 120_000, windowsHide: true, encoding: "utf8" });
+      } catch {
+        return resolveNativeManagerPath(lockedLookup);
+      }
+      const found = resolveNativeManagerPath(lockedLookup);
+      if (found) return found;
+      if (!result || result.error || result.status !== 0) return null;
+      return null;
+    } finally {
+      releaseInstallLock(lock);
+    }
+  } catch {
+    return null;
   }
 }

package/src/notify.ts

@@ -14,10 +14,12 @@
  *   ever delivered once.
  */
 import { formatMonitorEvent, formatTaskNotification, type TaskExitInfo } from "./format";
-import { FAMULUS_WAKE_CUSTOM_TYPE, stampWakeAsOf, wakeIds, type WakeItem } from "./wake";
+import { FAMULUS_WAKE_CUSTOM_TYPE, stampWakeAsOf, wakeIds, type MonitorOutputInfo, type WakeItem } from "./wake";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 
+type MonitorDeliveryAck = (visiblePreview?: string) => void;
+
 export interface NotifyMessage {
   customType: string;
   content: string;
@@ -42,6 +44,64 @@ export interface NotifyCenterDeps {
 }
 
 
+// Reserve 100 of the 3000 preview characters for the event-count prefix and
+// omission marker. No raw pending text grows with the number/size of events.
+const MONITOR_PREVIEW_CHARS = 2900;
+const MONITOR_PREVIEW_HALF = MONITOR_PREVIEW_CHARS / 2;
+interface MonitorPreview {
+  head: string;
+  tail: string;
+  omittedChars: number;
+}
+
+function clipUtf16Start(text: string, max: number): string {
+  if (text.length <= max) return text;
+  const out = text.slice(0, max);
+  const last = out.charCodeAt(out.length - 1);
+  return last >= 0xd800 && last <= 0xdbff ? out.slice(0, -1) : out;
+}
+
+function clipUtf16End(text: string, max: number): string {
+  if (text.length <= max) return text;
+  const out = text.slice(-max);
+  const first = out.charCodeAt(0);
+  return first >= 0xdc00 && first <= 0xdfff ? out.slice(1) : out;
+}
+
+function appendMonitorPreview(previous: MonitorPreview | undefined, event: string): MonitorPreview {
+  const total = previous
+    ? previous.head.length + previous.tail.length + previous.omittedChars + 1 + event.length
+    : event.length;
+  if (total <= MONITOR_PREVIEW_CHARS) {
+    return { head: previous ? `${previous.head}\n${event}` : event, tail: "", omittedChars: 0 };
+  }
+  const head = previous
+    ? clipUtf16Start(`${previous.head}\n${clipUtf16Start(event, MONITOR_PREVIEW_HALF)}`, MONITOR_PREVIEW_HALF)
+    : clipUtf16Start(event, MONITOR_PREVIEW_HALF);
+  const tail = event.length >= MONITOR_PREVIEW_HALF
+    ? clipUtf16End(event, MONITOR_PREVIEW_HALF)
+    : clipUtf16End(`${previous?.tail || previous?.head || ""}\n${event}`, MONITOR_PREVIEW_HALF);
+  return { head, tail, omittedChars: total - head.length - tail.length };
+}
+
+function mergeMonitorOutput(previous: MonitorOutputInfo | undefined, next: MonitorOutputInfo | undefined): MonitorOutputInfo | undefined {
+  if (!previous && !next) return undefined;
+  const output = { ...previous };
+  for (const key of ["firstObservedAt", "cursorStart"] as const) {
+    const value = next?.[key];
+    if (value !== undefined) output[key] = Math.min(previous?.[key] ?? value, value);
+  }
+  for (const key of ["lastObservedAt", "cursorEnd"] as const) {
+    const value = next?.[key];
+    if (value !== undefined) output[key] = Math.max(previous?.[key] ?? value, value);
+  }
+  for (const key of ["suppressedCount", "omittedChars"] as const) {
+    if (previous?.[key] !== undefined || next?.[key] !== undefined) output[key] = (previous?.[key] ?? 0) + (next?.[key] ?? 0);
+  }
+  if (previous?.truncated !== undefined || next?.truncated !== undefined) output.truncated = !!previous?.truncated || !!next?.truncated;
+  return output;
+}
+
 export class NotifyCenter {
   private readonly deps: NotifyCenterDeps;
   private readonly batchMs: number;
@@ -49,14 +109,14 @@ export class NotifyCenter {
   private pendingExits: TaskExitInfo[] = [];
   private readonly pendingMonitors = new Map<
     string,
-    { description: string; eventCount: number; lastEvent: string; droppedLines: number; quiet: boolean }
+    { description: string; eventCount: number; preview: MonitorPreview; droppedLines: number; quiet: boolean; output?: MonitorOutputInfo; onDelivered?: MonitorDeliveryAck }
   >();
   private readonly seen = new Set<string>();
   private timer: ClockTimer | null = null;
   private disposed = false;
   /** A wake started or steered a run that has not settled yet. */
   private runPending = false;
-  private held: NotifyMessage[] = [];
+  private held: { message: NotifyMessage; onDelivered?: MonitorDeliveryAck; sourcePreview?: string }[] = [];
 
   constructor(deps: NotifyCenterDeps) {
     this.deps = deps;
@@ -94,13 +154,17 @@ export class NotifyCenter {
     if (wake?.kind === "monitor" && typeof wake.id === "string") this.flushMonitor(wake.id, opts.quietEvents);
     if (!opts.passive) {
       this.deliver(message);
-    } else if (this.runPending || !this.deps.isIdle()) {
-      this.held.push(message);
     } else {
-      this.deliver(message, true);
+      this.deliverPassive(message);
     }
   }
 
+  private deliverPassive(message: NotifyMessage, onDelivered?: MonitorDeliveryAck, sourcePreview?: string): void {
+    message = stampWakeAsOf(message, this.clock.now());
+    if (this.runPending || !this.deps.isIdle()) this.held.push({ message, onDelivered, sourcePreview });
+    else this.deliver(message, true, onDelivered, sourcePreview);
+  }
+
   /**
    * The agent settled: the run any earlier wake started is over. Flush
    * coalesced monitor output, then, unless that started another run, the
@@ -111,7 +175,7 @@ export class NotifyCenter {
     this.runPending = false;
     this.flushMonitorEvents();
     if (this.runPending) return;
-    for (const message of this.held.splice(0)) this.deliver(message, true);
+    for (const { message, onDelivered, sourcePreview } of this.held.splice(0)) this.deliver(message, true, onDelivered, sourcePreview);
   }
 
   /**
@@ -119,21 +183,30 @@ export class NotifyCenter {
    * monitor. `quiet`: output of a monitor the model stopped; it is only
    * coalesced, and its summary is delivered without a turn (with the exit
    * notice, or at settle), pending events of that monitor included.
+   * `onDelivered` receives surviving source lines after sendMessage returns, not
+   * enqueue; generated headings/omission markers are never acknowledgement
+   * evidence. Callers must reuse one stable callback per monitor: retaining one
+   * callback bounds pending acknowledgements without silently dropping any.
    */
-  notifyMonitorEvent(description: string, taskId: string, event: string, droppedLines = 0, opts: { quiet?: boolean } = {}): void {
+  notifyMonitorEvent(description: string, taskId: string, event: string, droppedLines = 0, opts: { quiet?: boolean; onDelivered?: MonitorDeliveryAck; output?: MonitorOutputInfo } = {}): void {
     if (this.disposed) return;
     const pending = this.pendingMonitors.get(taskId);
+    if (pending?.onDelivered && opts.onDelivered && pending.onDelivered !== opts.onDelivered) {
+      throw new Error(`Monitor ${taskId} requires a stable onDelivered callback while pending`);
+    }
     if (this.deps.isIdle() && !pending && !opts.quiet) {
-      const wake = formatMonitorEvent(description, taskId, event, undefined, { droppedLines });
-      this.deliver({ customType: wake.customType, content: wake.content, details: wake.details });
+      const wake = formatMonitorEvent(description, taskId, event, undefined, { droppedLines, output: opts.output });
+      this.deliver({ customType: wake.customType, content: wake.content, details: wake.details }, false, opts.onDelivered);
       return;
     }
     this.pendingMonitors.set(taskId, {
       description,
       eventCount: (pending?.eventCount ?? 0) + 1,
-      lastEvent: event,
+      preview: appendMonitorPreview(pending?.preview, event),
       droppedLines: (pending?.droppedLines ?? 0) + droppedLines,
       quiet: (pending?.quiet ?? false) || opts.quiet === true,
+      output: mergeMonitorOutput(pending?.output, opts.output),
+      onDelivered: pending?.onDelivered ?? opts.onDelivered,
     });
     if (this.deps.isIdle() && !opts.quiet) this.flushMonitorEvents();
   }
@@ -149,16 +222,25 @@ export class NotifyCenter {
     const item = this.pendingMonitors.get(taskId);
     if (!item) return;
     this.pendingMonitors.delete(taskId);
-    const summary = item.eventCount > 1
-      ? `${item.eventCount} events · last: ${item.lastEvent}`
-      : item.lastEvent;
+    const { head, tail, omittedChars } = item.preview;
+    const preview = omittedChars > 0 ? `${head}\n[... ${omittedChars} characters omitted ...]\n${tail}` : head;
+    const summary = item.eventCount > 1 ? `${item.eventCount} events\n${preview}` : preview;
     const wake = formatMonitorEvent(item.description, taskId, summary, undefined, {
       eventCount: item.eventCount,
       droppedLines: item.droppedLines,
+      output: mergeMonitorOutput(item.output, omittedChars > 0 ? { truncated: true, omittedChars } : undefined),
     });
     const message = { customType: wake.customType, content: wake.content, details: wake.details };
-    if (quiet || item.quiet) this.notify(message, { passive: true });
-    else this.deliver(message);
+    // Exclude generated text and boundary fragments: a clipped middle source
+    // line named e.g. "30 events" was not seen just because our heading says it.
+    const sourcePreview = omittedChars > 0
+      ? [
+        head.slice(0, Math.max(0, head.lastIndexOf("\n"))),
+        tail.includes("\n") ? tail.slice(tail.indexOf("\n") + 1) : "",
+      ].filter(Boolean).join("\n")
+      : head;
+    if (quiet || item.quiet) this.deliverPassive(message, item.onDelivered, sourcePreview);
+    else this.deliver(message, false, item.onDelivered, sourcePreview);
   }
 
   /** Flush any pending task exit notifications now. */
@@ -204,7 +286,7 @@ export class NotifyCenter {
     });
   }
 
-  private deliver(message: NotifyMessage, passive = false): void {
+  private deliver(message: NotifyMessage, passive = false, onDelivered?: MonitorDeliveryAck, sourcePreview?: string): void {
     // Wakes built here (task batches, monitor events) are stamped now.
     message = stampWakeAsOf(message, this.clock.now());
     const msg = { ...message, display: true };
@@ -227,5 +309,6 @@ export class NotifyCenter {
     } else {
       this.deps.sendMessage(msg, { deliverAs: "steer" });
     }
+    onDelivered?.(sourcePreview ?? (details?.kind === "monitor" ? (message.details as { event?: string }).event : undefined));
   }
 }

package/src/prompts.generated.ts

@@ -5,8 +5,8 @@ export const PROMPTS = {
   "agents.explorer.system-prompt": "You are an explorer agent. Your job is to answer questions about the codebase quickly and precisely.\n\nRules:\n- Return findings, never change code. You are strictly read-only: do not edit, write, or create files.\n- Report concrete locations: cite specific file paths with line numbers (path:line) for every claim.\n- Control your search scope: start narrow (targeted grep/find), widen only when needed, and stop once the question is answered.\n- Prefer a short, factual summary over exhaustive dumps. List what you found and where.",
   "agents.worker.description": "General-purpose executor — completes concrete coding tasks end to end",
   "agents.worker.system-prompt": "You are a worker agent. Your job is to complete the concrete task you were given, end to end.\n\nRules:\n- Do the task, don't just describe it. Make the actual edits and run the actual commands.\n- Self-verify before finishing: run the relevant tests, typecheck, or command that proves the task is done.\n- Stay within the task's scope; do not refactor unrelated code.\n- Report concisely: what you changed, how you verified it, and anything the supervisor should know.",
-  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.\n- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. Do not wait for further user input when the next step is clear; do not merely acknowledge and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them.",
-  "guidelines.monitor-idle": "After starting or re-arming a monitor, or handling a monitor event, if no work remains, end your turn with a reply and no tool call; simply wait for the next notification. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield.",
+  "guidelines.parent": "## Background tasks and notifications (pi-famulus)\n\n- Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands.\n- When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop.\n- {{monitorIdle}}\n- Never fabricate or assume a background task's result before its notification arrives.\n- Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue.\n- A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again.\n- Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them.",
+  "guidelines.monitor-idle": "After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield.",
   "guidelines.child": "## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result.",
   "tools.agent_message.description": "Message your subagents. \"send\" steers or queues a running child. Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). \"reply\" answers a child's pending decision request; \"broadcast\" steers every running child of a run (to = run_id); \"list\" shows children, pending decision requests, and recent traffic.",
   "tools.agent_message.snippet": "Send/reply/broadcast messages to subagents",
@@ -34,14 +34,16 @@ export const PROMPTS = {
   "tools.child.contact_supervisor.snippet": "Ask the parent agent for a decision or report progress",
   "tools.child.contact_supervisor.param.reason": "\"need_decision\" blocks until the supervisor (parent agent) replies; \"progress_update\" is fire-and-forget.",
   "tools.child.contact_supervisor.param.message": "Message for the supervisor.",
-  "tools.monitor.description": "Start a background monitor process whose stdout lines are injected back to you as <pi-famulus-wake kind=\"monitor\"> messages (batched over 200ms, rate-limited). The command must be line-buffered: each event must be a single line. It must keep running and follow its source, e.g. `tail -n +1 -F file | grep --line-buffered PATTERN`; a command that reads once and exits (a plain grep or cat) only reports what is there now. Add `-m1` to grep to stop after the first match. Silence is not success: write the command so failures also produce lines (e.g. grep for both success and error patterns). Events arrive as system wakes (not new user messages). Handle each <pi-famulus-wake kind=\"monitor\"> before other work. Do not poll. {{monitorIdle}}",
+  "tools.monitor.description": "Start a background monitor process whose stdout lines are injected back to you as <pi-famulus-wake kind=\"monitor\"> messages (batched over 200ms, rate-limited). The command must be line-buffered: each event must be a single line. It must keep running and follow its source, e.g. `tail -n +1 -F file | grep --line-buffered PATTERN`; a command that reads once and exits (a plain grep or cat) only reports what is there now. Add `-m1` to grep to stop after the first match. Silence is not success: print explicit success and terminal failures. Routine unchanged retries may stay silent; do not print a heartbeat on every check. Events arrive as system wakes (not new user messages). Handle each <pi-famulus-wake kind=\"monitor\"> before other work. Do not poll. Repeated Rust-framed lines are suppressed within dedup_window_ms (default 60000); exact matching is the default. Enable ignore-timestamps only when edge ISO timestamps are incidental. Wakes contain bounded head/tail previews and original-byte references; use task_output for missing details, not polling. {{monitorIdle}}",
   "tools.monitor.snippet": "Watch a command's line stream and get injected events",
   "tools.monitor.rules": ["Use the monitor tool to watch for conditions instead of running sleep/poll loops in bash.","{{monitorIdle}}","When woken by a <pi-famulus-wake kind=\"monitor\">, handle the <event> before doing anything else — it is not a new user request and not user confirmation."],
   "tools.monitor.param.command": "Command producing one event per line on stdout. Must be line-buffered (e.g. use `stdbuf -oL` / `grep --line-buffered` where needed).",
   "tools.monitor.param.description": "Short human-readable description of what is being watched",
   "tools.monitor.param.timeout_ms": "Stop the monitor after this many milliseconds (default {{defaultMs}}, min {{minMs}}, max {{maxMs}})",
   "tools.monitor.param.persistent": "Keep the monitor alive until the session ends (no timeout). Default false.",
-  "tools.monitor.result.started": "You will get a <pi-famulus-wake kind=\"monitor\"> for each event, and a notice when it exits or times out. Do not poll it (task_list, task_output, or reading what it watches) or sleep. {{monitorIdle}}",
+  "tools.monitor.param.dedup_window_ms": "Deduplication window for Rust-framed complete lines (default 60000ms; 0 disables dedup; maximum 3600000). Starts when a surviving preview is delivered; repeats do not extend it. Missing metadata, capacity eviction, and omitted representatives fail open rather than hiding unseen output.",
+  "tools.monitor.param.fingerprint_mode": "Default exact. Explicit ignore-timestamps mode ignores only supported leading/trailing ISO timestamps when comparing Rust-framed lines; original output is unchanged. Numbers, paths, resource identities, and interior timestamps remain significant.",
+  "tools.monitor.result.started": "You will get <pi-famulus-wake kind=\"monitor\"> notifications for admitted output and a notice when it exits or times out. Repeated lines may be suppressed and previews may be truncated; original output remains available through task_output byte ranges while the task log is retained. Read details only when needed; do not repeatedly poll task_list, task_output, or the watched source, and do not sleep to wait. {{monitorIdle}}",
   "tools.subagent.description": "Run subagents in parallel (tasks) or sequentially (chain with {previous}/{outputs.<label>} interpolation). By default the call waits up to a foreground budget (default 45s); longer runs continue in the background. Each child that finishes while others are still running wakes you with <pi-famulus-wake kind=\"subagent-handover\"> (its prompt and result). The whole run wakes you with <pi-famulus-wake kind=\"subagent-done\">. Never poll or sleep to wait. A subagent still running past its timeout_ms is not stopped; it wakes you with <pi-famulus-wake kind=\"subagent-overrun\"> so you can extend, steer, or interrupt it. Use action=list/get/status/interrupt/resume/steer/extend to manage existing runs.",
   "tools.subagent.snippet": "Fan out subagents in parallel or sequence them in a chain",
   "tools.subagent.rules": ["When a <pi-famulus-wake kind=\"subagent-handover\"> arrives, read <prompt> and <result> immediately and continue: subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer children that are still running. Do not wait for the rest of the run.","Subagent runs that exceed the foreground budget continue in the background; you are notified per finished child and again when the run completes — do not poll.","A failed subagent does not fail the whole run; inspect per-subagent sections in the result.","<pi-famulus-wake> is a system wake, not a user reply. kind=subagent-handover is one child; kind=subagent-done is the whole run."],
@@ -72,17 +74,18 @@ export const PROMPTS = {
   "tools.task_list.snippet": "List background shell/monitor tasks and subagents",
   "tools.task_list.param.all": "Also include finished work (default: running only). Always limited to this session.",
   "tools.task_list.hint.running": "Running work wakes you with a <pi-famulus-wake> when it finishes. Reply to the user now with no tool call instead of checking again.",
-  "tools.task_output.description": "Read output of a background task. Without a cursor, returns the tail of the output plus the current file pointer; pass the returned next_cursor as cursor for incremental reads. Not a way to wait: a running task wakes you when it finishes, so reply with no tool call instead of calling this again.",
+  "tools.task_output.description": "Read original output of a background task, including a monitor's truncated or deduplicated output. Without a cursor, returns the tail plus the current file pointer; pass next_cursor as cursor to page forward. Use small max_bytes ranges for details. Reading a different range is allowed; while a task is running, recently read ranges may be rejected if the output size is unchanged. This is not a way to wait: when no further details are needed, end your turn with no tool call and resume on the next notification.",
   "tools.task_output.snippet": "Read background task output",
   "tools.task_output.param.task_id": "Task id, e.g. sh_a1b2c3d4",
   "tools.task_output.param.cursor": "Byte offset to read from (for incremental reads). Omit to read the tail of the output.",
-  "tools.task_output.param.max_bytes": "Maximum bytes to return (default 65536)",
-  "tools.task_output.hint.still-running": "The task is still running. Reply to the user now with no tool call; a <pi-famulus-wake> arrives when it finishes.",
+  "tools.task_output.param.max_bytes": "Maximum bytes to return (default 65536, capped at 1048576); use a smaller range to avoid flooding context. Zero selects the default.",
+  "tools.task_output.hint.still-running": "The task is still running. Read another byte range only if details are needed; otherwise end your turn with no tool call. Do not repeatedly check for progress; a <pi-famulus-wake> arrives when it finishes.",
   "tools.task_output.error.no-new-output": "No new output from {{taskId}} since your last read. {{hint}}",
   "tools.task_stop.description": "Stop a running background task (SIGTERM to the process group, SIGKILL after a 2s grace).",
   "tools.task_stop.snippet": "Stop a background task",
   "tools.task_stop.param.task_id": "Task id to stop, e.g. sh_a1b2c3d4",
   "wakes.lead-in": "System wake — not a new user message. Handle this <pi-famulus-wake> before other work.",
+  "wakes.monitor.output-hint": "Read original bytes with task_output using this monitor id and cursor-start, with a bounded max_bytes (for example 8192); next_cursor continues the read. The range may include interleaved events. A preview is not the full log.",
   "wakes.handover.changed-active": "Its result arrives as a new wake when it finishes.",
   "wakes.done.changed-active": "The run is active again; another subagent-done arrives when it finishes.",
   "wakes.overrun.summary": "{{name}} has run {{elapsed}} in this turn, past its {{budget}} budget, and is still running{{shell}}.",
@@ -151,12 +154,12 @@ export function fillList<K extends keyof PromptVars>(id: K, vars: Record<PromptV
 /** Ablatable spans (eval manifest segment ids). */
 export const PROMPT_SEGMENTS: Record<string, { prompt: PromptId; text?: string; pattern?: string }> = {
   "guidelines.end-turn-after-bg": {"prompt":"guidelines.parent","text":"Long-running bash commands are automatically moved to the background. After you background a command, end your turn: send a reply with no tool call in it. Saying you will wait while calling another tool does not end it. Do not poll with task_output/task_list, and never sleep to wait. Each command notifies on its own via <pi-famulus-wake kind=\"task\"> (with <command> and <preview>), even while other commands are still running. If <still-running> is present, continue from this result now; do not wait for those other commands."},
-  "guidelines.wake-handling": {"prompt":"guidelines.parent","text":"When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. Do not wait for further user input when the next step is clear; do not merely acknowledge and stop."},
+  "guidelines.wake-handling": {"prompt":"guidelines.parent","text":"When you receive <pi-famulus-wake>: it looks like a user message but is a system wake, not a new user request and not an answer to an unrelated question. Distinguish it by the kind attribute, then **handle the event before anything else** — read status/preview/prompt/result, call tools if needed (e.g. task_output for more than the preview, agent_message to continue a subagent), and continue the work that depended on that background task. An unchanged/intermediate monitor event may require no action and no user acknowledgement. Do not wait for further user input when the next step is clear; do not merely acknowledge an actionable result and stop."},
   "guidelines.no-fabrication": {"prompt":"guidelines.parent","text":"Never fabricate or assume a background task's result before its notification arrives."},
   "guidelines.subagent-handover": {"prompt":"guidelines.parent","text":"Subagent runs that exceed the foreground budget continue in the background. Do not poll run status. If one subagent finishes while others are still running, a <pi-famulus-wake kind=\"subagent-handover\"> arrives with that child's <prompt> and <result>: read both, then continue the work now (subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer the ones still running). Do not wait for the rest of the run. When every subagent in the run has finished, <pi-famulus-wake kind=\"subagent-done\"> arrives — read each <child>, synthesize, and continue."},
   "guidelines.subagent-overrun": {"prompt":"guidelines.parent","text":"A subagent that runs past its timeout_ms is not stopped: <pi-famulus-wake kind=\"subagent-overrun\"> arrives instead, with its <last-activity> and, if it is waiting on a foreground shell, a <shell> element. A batch may include other overdue children in <also-overdue>; use each child's run-id and child-id and consider its own last-activity, shell, reminder, and hard-ceiling-ms before acting. Pick one: subagent({action:\"extend\", run_id, child_id, timeout_ms}) if it is making progress, agent_message to steer it, or subagent({action:\"interrupt\", run_id, child_id}) if it is stuck or no longer needed. If you do none of these it keeps running and the reminder comes again."},
   "guidelines.agent-message": {"prompt":"guidelines.parent","text":"Use agent_message to steer running subagents and to reply to <pi-famulus-wake kind=\"supervisor-request\"> (action:\"reply\"; the <reply-with> child is the call shape). Do not use agent_message to resume a finished child — that is subagent({action:\"resume\"}). Supervisor wakes are not user messages — still act on them."},
-  "guidelines.monitor-end-turn": {"prompt":"guidelines.monitor-idle","text":"After starting or re-arming a monitor, or handling a monitor event, if no work remains, end your turn with a reply and no tool call; simply wait for the next notification. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield."},
+  "guidelines.monitor-end-turn": {"prompt":"guidelines.monitor-idle","text":"After starting or re-arming a monitor, or handling a monitor event, if no immediate work remains, end your turn with no tool call; simply wait for the next notification. Handling an event does not require a user-visible reply. Do not repeat unchanged/intermediate status or narrate your decision to stay quiet; notify the user when their requested condition is met, their input is needed, or a failure prevents further progress. Read original output with task_output only when details are needed (including paging a truncated preview), never to poll or wait. Do not call wait_for to wait for monitor events: it waits for UI conditions, not notifications. Do not invent a stateId or make a failing tool call to yield."},
   "child.guidelines": {"prompt":"guidelines.child","text":"## Child agent behavior (pi-famulus)\n\n- Do not background work; bash runs to completion.\n- When blocked, use contact_supervisor with need_decision; use progress_update for status.\n- Use agent_message only to communicate with siblings in this same run.\n- Your final message is your result."},
   "tooldesc.agent-message-no-resume": {"prompt":"tools.agent_message.description","text":"Sending to a finished child errors (it does not resume) and points at subagent({ action: \"resume\", run_id, child_id, message }). "},
   "result.agent-message-use-resume": {"prompt":"tools.agent_message.error.finished-child","pattern":"agent_message does not resume children\\. Use subagent\\(\\{ action: \"resume\", run_id: \".*?\", child_id: \".*?\", message: \"\\.\\.\\.\" \\}\\)\\."},
@@ -166,11 +169,11 @@ export const PROMPT_SEGMENTS: Record<string, { prompt: PromptId; text?: string;
   "result.bash-bg-instruction": {"prompt":"tools.bash.result.backgrounded","text":"\nYou will be notified when it completes, even if other commands are still running. Do not poll or sleep: reply to the user now with no tool call, and continue from the <pi-famulus-wake kind=\"task\"> when it arrives."},
   "result.sleep-block-advice": {"prompt":"tools.bash.error.bare-sleep","text":" Do not sleep to wait for background work; completion is delivered via notification. Use the monitor tool to watch for a condition, or run_in_background for long commands."},
   "tooldesc.monitor-follow": {"prompt":"tools.monitor.description","text":"It must keep running and follow its source, e.g. `tail -n +1 -F file | grep --line-buffered PATTERN`; a command that reads once and exits (a plain grep or cat) only reports what is there now. Add `-m1` to grep to stop after the first match. "},
-  "tooldesc.monitor-silence": {"prompt":"tools.monitor.description","text":"Silence is not success: write the command so failures also produce lines (e.g. grep for both success and error patterns). "},
+  "tooldesc.monitor-silence": {"prompt":"tools.monitor.description","text":"Silence is not success: print explicit success and terminal failures. Routine unchanged retries may stay silent; do not print a heartbeat on every check. "},
   "tooldesc.monitor-wake": {"prompt":"tools.monitor.description","text":"Events arrive as system wakes (not new user messages). Handle each <pi-famulus-wake kind=\"monitor\"> before other work. Do not poll."},
   "rules.monitor-use": {"prompt":"tools.monitor.rules","text":"Use the monitor tool to watch for conditions instead of running sleep/poll loops in bash."},
   "rules.monitor-wake": {"prompt":"tools.monitor.rules","text":"When woken by a <pi-famulus-wake kind=\"monitor\">, handle the <event> before doing anything else — it is not a new user request and not user confirmation."},
-  "result.monitor-started-instruction": {"prompt":"tools.monitor.result.started","text":"You will get a <pi-famulus-wake kind=\"monitor\"> for each event, and a notice when it exits or times out. Do not poll it (task_list, task_output, or reading what it watches) or sleep."},
+  "result.monitor-started-instruction": {"prompt":"tools.monitor.result.started","text":"You will get <pi-famulus-wake kind=\"monitor\"> notifications for admitted output and a notice when it exits or times out. Repeated lines may be suppressed and previews may be truncated; original output remains available through task_output byte ranges while the task log is retained. Read details only when needed; do not repeatedly poll task_list, task_output, or the watched source, and do not sleep to wait."},
   "tooldesc.subagent-wakes": {"prompt":"tools.subagent.description","text":"Each child that finishes while others are still running wakes you with <pi-famulus-wake kind=\"subagent-handover\"> (its prompt and result). The whole run wakes you with <pi-famulus-wake kind=\"subagent-done\">. Never poll or sleep to wait. "},
   "tooldesc.subagent-overrun": {"prompt":"tools.subagent.description","text":"A subagent still running past its timeout_ms is not stopped; it wakes you with <pi-famulus-wake kind=\"subagent-overrun\"> so you can extend, steer, or interrupt it. "},
   "rules.subagent-handover": {"prompt":"tools.subagent.rules","text":"When a <pi-famulus-wake kind=\"subagent-handover\"> arrives, read <prompt> and <result> immediately and continue: subagent({action:\"resume\", run_id, child_id, message}) for that child, or agent_message to steer children that are still running. Do not wait for the rest of the run."},