pi-famulus 0.1.6 → 0.1.8

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."},

package/src/reload-handoff.ts

@@ -0,0 +1,137 @@
+/**
+ * /reload keeps background work alive.
+ *
+ * pi's /reload emits session_shutdown(reason "reload") on the old extension
+ * instance, re-imports every extension (fresh module scope), then emits
+ * session_start(reason "reload") on the new instances. Shells, monitors and
+ * subagents belong to the pi session, not to one module instance, so the old
+ * instance parks its runtime here instead of tearing it down, and the new
+ * instance adopts it.
+ *
+ * The runtime registers its tools, commands and handlers on a PiBinding: a
+ * stand-in ExtensionAPI that records registrations and replays them on every
+ * pi it is attached to. Other calls go to the attached pi; sendMessage is
+ * queued while no live pi can take it (between the old instance going stale
+ * and the new one's session_start).
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { realClock, type Clock } from "./clock";
+
+const HANDOFF_KEY = Symbol.for("pi-famulus.reload-handoff");
+
+/** A parked runtime nobody adopts (pi-famulus removed from the config) is torn down after this. */
+export const HANDOFF_EXPIRY_MS = 60_000;
+
+const REGISTRATIONS = new Set<PropertyKey>([
+  "on",
+  "registerTool",
+  "registerCommand",
+  "registerShortcut",
+  "registerFlag",
+  "registerMessageRenderer",
+  "registerProvider",
+]);
+
+export interface PiBinding {
+  /** Pass this to the runtime in place of the real pi. */
+  readonly api: ExtensionAPI;
+  /** Replay every registration on `pi` and route calls to it. */
+  attach(pi: ExtensionAPI): void;
+  /** Deliver queued messages; call once the attached pi's session has started. */
+  ready(): void;
+  /** Stop calling the attached pi (it is about to go stale). */
+  detach(): void;
+  /** Drop queued messages; they belong to a session that is not coming back. */
+  discardQueued(): void;
+}
+
+export function createPiBinding(): PiBinding {
+  const registrations: Array<{ method: PropertyKey; args: unknown[] }> = [];
+  const queued: unknown[][] = [];
+  let current: ExtensionAPI | null = null;
+  let live = false;
+
+  const call = (pi: ExtensionAPI, method: PropertyKey, args: unknown[]): unknown =>
+    (Reflect.get(pi, method) as (...a: unknown[]) => unknown).apply(pi, args);
+
+  const api = new Proxy({} as ExtensionAPI, {
+    get(_target, key) {
+      if (REGISTRATIONS.has(key)) {
+        return (...args: unknown[]) => {
+          registrations.push({ method: key, args });
+          return current ? call(current, key, args) : undefined;
+        };
+      }
+      if (key === "sendMessage") {
+        return (...args: unknown[]) => {
+          if (current && live) return call(current, key, args);
+          queued.push(args);
+        };
+      }
+      if (!current) throw new Error(`pi-famulus: pi.${String(key)} used while detached (between reloads)`);
+      const value = Reflect.get(current, key) as unknown;
+      return typeof value === "function" ? (value as (...a: unknown[]) => unknown).bind(current) : value;
+    },
+  });
+
+  return {
+    api,
+    attach(pi) {
+      current = pi;
+      live = false;
+      for (const { method, args } of registrations) call(pi, method, args);
+    },
+    ready() {
+      if (!current) return;
+      live = true;
+      for (const args of queued.splice(0)) call(current, "sendMessage", args);
+    },
+    detach() {
+      current = null;
+      live = false;
+    },
+    discardQueued() {
+      queued.length = 0;
+    },
+  };
+}
+
+export interface ParkedRuntime<R> {
+  /** Extension version that parked it; another version's runtime is not adopted. */
+  version: string;
+  runtime: R;
+  /** Full teardown (what a non-reload session_shutdown does). */
+  dispose(): Promise<void>;
+}
+
+interface Slot {
+  parked: ParkedRuntime<unknown>;
+  expiry: unknown;
+}
+
+/** Park a runtime for the next instance; tear it down if nobody takes it in time. */
+export function parkRuntime<R>(parked: ParkedRuntime<R>, clock: Clock = realClock): void {
+  const store = globalThis as Record<symbol, Slot | undefined>;
+  const previous = store[HANDOFF_KEY];
+  if (previous) {
+    clock.clearTimeout(previous.expiry);
+    void previous.parked.dispose().catch(() => {});
+  }
+  const expiry = clock.setTimeout(() => {
+    if (store[HANDOFF_KEY]?.parked !== parked) return;
+    store[HANDOFF_KEY] = undefined;
+    void parked.dispose().catch(() => {});
+  }, HANDOFF_EXPIRY_MS);
+  clock.unref?.(expiry);
+  store[HANDOFF_KEY] = { parked: parked as ParkedRuntime<unknown>, expiry };
+}
+
+/** Take the parked runtime, if any. The caller adopts or disposes it. */
+export function takeParkedRuntime<R>(clock: Clock = realClock): ParkedRuntime<R> | null {
+  const store = globalThis as Record<symbol, Slot | undefined>;
+  const slot = store[HANDOFF_KEY];
+  if (!slot) return null;
+  store[HANDOFF_KEY] = undefined;
+  clock.clearTimeout(slot.expiry);
+  return slot.parked as ParkedRuntime<R>;
+}

package/src/shell-exec.ts

@@ -3,6 +3,7 @@
  * Previously copied in both files.
  */
 import type { BashToolDetails } from "@earendil-works/pi-coding-agent";
+import { shellStartStatus } from "./shell-start";
 import { truncateTail } from "./format";
 import type { ManagerClient } from "./manager-client";
 import { fill } from "./prompts.generated";
@@ -134,9 +135,34 @@ export function appendStatus(text: string, status: string): string {
  * kill for a command still running (eval batch 4).
  */
 export async function killedStatus(client: ManagerClient, taskId: string, timeoutSeconds: number | undefined): Promise<string> {
-  const record = (await client.list(true).catch(() => [])).find((t) => t.task_id === taskId);
+  const record = await taskRecord(client, taskId);
   if (record?.end_reason === "timeout" && timeoutSeconds !== undefined) return timedOutStatus(timeoutSeconds);
-  return killedBy(record?.signal);
+  return shellStartStatus(record?.end_reason) ?? killedBy(record?.signal);
+}
+
+/**
+ * Status line for a non-zero exit. On Windows the manager marks a Git Bash
+ * that crashed while starting (shell-start-failed); elsewhere that cannot
+ * happen, so skip the record lookup.
+ */
+export async function exitedStatus(
+  client: ManagerClient,
+  taskId: string,
+  exitCode: number,
+  platform: NodeJS.Platform = process.platform,
+): Promise<string> {
+  const plain = `Command exited with code ${exitCode}`;
+  if (platform !== "win32") return plain;
+  const hint = shellStartStatus((await taskRecord(client, taskId))?.end_reason);
+  return hint ? `${hint} (exit code ${exitCode})` : plain;
+}
+
+async function taskRecord(client: ManagerClient, taskId: string) {
+  try {
+    return (await client.list(true)).find((t) => t.task_id === taskId);
+  } catch {
+    return undefined;
+  }
 }
 
 /** The one wording of a timeout kill, on every bash path. */

package/src/shell-start.ts

@@ -0,0 +1,25 @@
+/**
+ * Windows Git Bash start-up failures (manager end_reasons, see
+ * manager/src/shellstart.rs). Concurrent MSYS cold starts race while building
+ * the shared mount table (git-for-windows/git#6368). These reasons are
+ * inferred: a nested shell can print the same fatal text after the command
+ * has already had side effects, and a silent builtin-only command looks like
+ * a hung start. Say that, and do not tell the model the command did not run.
+ */
+export const SHELL_START_FAILED = "shell-start-failed";
+export const SHELL_START_HUNG = "shell-start-hung";
+
+/** The status line for a shell start-up failure, or undefined. */
+export function shellStartStatus(endReason: string | undefined): string | undefined {
+  if (endReason === SHELL_START_FAILED) {
+    return "Git Bash reported a Windows runtime startup failure; the command may have partially run. Check for side effects before retrying.";
+  }
+  if (endReason === SHELL_START_HUNG) {
+    return (
+      "Git Bash showed no output and only the shell process for 20s, so it was killed. " +
+      "This is usually a hung start, but a silent builtin-only command looks the same and may have been running. " +
+      "Check for side effects before retrying."
+    );
+  }
+  return undefined;
+}

package/src/subagent/child-bash.ts

@@ -32,6 +32,7 @@ import {
   bareSleepError,
   collectOutput,
   formatFinishedOutput,
+  exitedStatus,
   killedStatus,
   timedOutStatus,
   SHELL_MAX_BYTES,
@@ -172,7 +173,7 @@ export function createChildBashTool(
         const { text, details } = formatFinishedOutput(collected, outputPath);
         const exitCode = waitResult.exit_code ?? null;
         if (exitCode !== 0 && exitCode !== null) {
-          throw new Error(appendStatus(text, `Command exited with code ${exitCode}`));
+          throw new Error(appendStatus(text, await exitedStatus(client, start.task_id, exitCode)));
         }
         // No exit code: killed (timeout, stop, crash), unless the manager
         // finished it as completed with its runner status unobservable.