pi-famulus 0.1.7 → 0.1.8

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/Leechael/pi-famulus/main/assets/logo.png" alt="pi-famulus" width="120" />
   <h1>pi-famulus</h1>
-  <p><b>Let your agent delegate, and keep working.</b></p>
+  <p><b>Keep your main agent focused. Hand off the rest.</b></p>
   <p>English · <a href="https://github.com/Leechael/pi-famulus/blob/main/README_CN.md">中文</a></p>
-  <p>Subagents and long-running bash for <a href="https://pi.dev">pi</a> and agents built on it. Results wake the agent when work finishes, so it never has to poll. One daemon owns every shell it starts.</p>
+  <p>Subagents and long-running bash for <a href="https://pi.dev">pi</a> and agents built on it. Results wake the agent when work finishes, so the conversation keeps going. One Rust daemon runs the shells and monitors it starts.</p>
   <p>
     <a href="https://github.com/Leechael/pi-famulus/blob/main/docs/tools.md">Tools</a> ·
     <a href="https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md">CLI</a> ·
@@ -22,6 +22,8 @@
 
 ## Why
 
+pi-famulus is less about subagents than about the main agent: keep its context clean, keep it on the goal, and keep talking to it while work runs. Plan with the main agent, hand the coding to a subagent on a cheaper model, and let tests and logs run in the background until they need attention.
+
 A famulus is the assistant who runs a scholar's errands, as Wagner does for Faust. pi's core leaves subagents, background bash and monitoring to extensions on purpose ([design, section 1](https://github.com/Leechael/pi-famulus/blob/main/docs/design.md#1-background-and-goals)). pi-famulus adds them. It is for people who run pi, or an agent built on pi, on real projects and want to hand off slow or parallel work, such as a test suite, a build, a dev server or a code review, without stalling the conversation.
 
 Three things go wrong when an agent has to wait:
@@ -34,6 +36,10 @@ One machine-wide daemon (`pi-famulus`, written in Rust) starts every shell comma
 
 pi-famulus is a pi extension, so it works wherever pi loads extensions: the pi TUI, RPC mode, and agents you build with the pi SDK. Outside the TUI there is no `/tasks` list and no fleet line, but results still wake the agent. Print mode (`pi -p`) exits when the first run ends, so results that arrive later are not seen.
 
+### Not a pane manager
+
+If you use Herdr or tmux panes, keep them. Panes are for watching and taking over an agent. pi-famulus is for the main agent: it is woken when a subagent overruns its budget, asks for a decision or finishes, so it never has to watch a pane to know work is done. A subagent that stalls is retried on its own, and the parent hears the outcome.
+
 ## Quick Start
 
 > **Before you install**: pi-famulus registers the tools `bash` (replacing the built-in), `subagent`, `monitor`, `agent_message`, `task_list`, `task_output` and `task_stop`, and the commands `/tasks`, `/famulus` and `/reply`. In pi 1.0.0, when two extensions register the same tool name, the extension loaded first keeps it, and the other one's tool is hidden.
@@ -63,10 +69,11 @@ Run the full test suite and tell me what fails.
 - **Wake on completion**: A finished command, a monitor event or a subagent result is injected into the conversation. The agent continues from it without polling.
 - **Subagents**: A call takes up to 10 subagents, which run 4 at a time by default, or a `chain` that runs in order. If the wait passes 45 seconds, the call returns and the run continues in the background. Each subagent reports back when it finishes.
 - **Clean finish**: A subagent's `bash` runs in the foreground until the command exits or times out, and subagents cannot start subagents or monitors. So a finished subagent leaves nothing it started through pi-famulus running, unless a command detached itself with `setsid` or left a process running with `&`.
-- **One daemon for every process**: The daemon is the parent of every shell and monitor task across your pi sessions. If it crashes or is killed with `kill -9`, each task's process group is stopped. Commands that move into a new session with `setsid` escape this.
+- **Hears about trouble early**: With the default settings, a subagent with no activity for 5 minutes is resumed once on the same session, and marked failed if it stalls again. The watchdog pauses while a tool runs or a `contact_supervisor` question waits for an answer. Past its 30-minute soft budget (`timeout_ms`) the child keeps running, and the parent gets an overrun wake every 10 minutes to extend, steer or interrupt it; the wake is held while the child waits for an answer. These values are set in the `subagent` section of the [configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md).
+- **One daemon for every shell and monitor**: The daemon is the parent of every shell and monitor task across your pi sessions. If it crashes or is killed with `kill -9`, each task's process group is stopped. Commands that move into a new session with `setsid` escape this.
 - **Shared capacity**: By default, at most 8 subagents run at once across all pi sessions on the machine (`pi-famulus config set max-agents <n>` changes it). The rest wait in a queue. Subagents labelled `work_kind: "test-suite"` or `"test"` are capped at 2 at a time; without a label, a subagent counts as `other`.
 - **Parent and subagent talk**: A subagent asks its parent a question with `contact_supervisor` and waits for the answer. You can answer it yourself with `/reply`. `agent_message` sends messages between parent and subagents.
-- **Inspectable**: `pi-famulus top`, `ls`, `show`, `agent` and `events` show what ran, why it ended, and why a notification did or did not arrive.
+- **Inspectable**: In a terminal, `pi-famulus top` is a live dashboard of sessions, subagents, shells and monitors. Open a subagent to read its conversation or a task to read its output, and stop a running shell or monitor from there. `ls`, `show`, `agent` and `events` show what ran, why it ended, and why a notification did or did not arrive.
 - **Tested against real models**: Tool descriptions are graded on real-model runs. The latest matrix (2026-10-08; 12 xAI and OpenAI configurations, 10 scenarios, k=10) recorded 1198 passes and 2 failures, with 6 invalid or errored episodes excluded ([eval/RESULTS.md](https://github.com/Leechael/pi-famulus/blob/main/eval/RESULTS.md)). It predates a later wording change to the `subagent` and wake prompts ([PR #62](https://github.com/Leechael/pi-famulus/pull/62)), which has not been through the full matrix yet.
 
 ## Usage Guide
@@ -74,7 +81,7 @@ Run the full test suite and tell me what fails.
 | Ask the agent | What happens |
 | :--- | :--- |
 | `Run the full test suite and tell me what fails.` | `bash` moves the run to the background after 20 seconds; the result arrives when it exits |
-| `Start the dev server and tell me if an error shows up in its output.` | `monitor` turns each output line into an event and wakes the agent when one arrives |
+| `Start the dev server and tell me if an error shows up in its output.` | `monitor` batches new output into bounded events; repeated lines are deduplicated within a configurable window |
 | `Review these three modules in parallel with subagents.` | `subagent` runs the tasks in parallel; each subagent reports back when it finishes |
 | `Which models can subagents use?` | The agent calls `subagent({action: "models"})` and lists the choices |
 
@@ -121,7 +128,7 @@ pi-famulus starts and stops processes for you. This section states what it guara
 - Running work does not survive the last pi session closing. Five seconds after the last session disconnects, the daemon stops what is left and exits. Records, output and transcripts stay on disk for 24 hours.
 - A subagent still running when its 30-minute turn budget ends is not killed, unless you set `hardTimeoutMs`. The parent is told and chooses to extend, steer or interrupt it.
 - A subagent with no activity for 5 minutes is resumed once on the same session, with its transcript kept. The timer pauses while a tool runs or a `contact_supervisor` question waits for an answer. If the subagent stalls again, it is marked failed.
-- `monitor` batches output every 200 ms. It allows a burst of 10 events, then one event every 2 seconds. Batches over that limit are dropped. If at least half the batches are dropped over a 30-second window that holds at least 10 batches, the monitor stops and you are told.
+- `monitor` batches output every 200 ms. Rust-framed repeated complete lines from the same monitor are deduplicated for 60 seconds by default after a representative is delivered; legacy/raw fallback previews are not content-deduplicated, and missing metadata, capacity eviction, and omitted representatives fail open. Exact matching is the default, with timestamp normalization opt-in. Previews are bounded; original output remains readable with `task_output`. Deduplication does not count as overload loss. Admitted batches allow a burst of 10 events, then one event every 2 seconds. Batches over that limit are dropped. If at least half the batches are dropped over a 30-second window that holds at least 10 batches, the monitor stops and you are told.
 - On Linux and macOS, the daemon checks its own executable every 2 seconds. When the file is replaced, the running daemon re-executes itself with the same pid. `pi-famulus upgrade` does the same on demand. Running commands keep going and clients reconnect. The measured gap was 30 to 46 ms.
 
 ## FAQ
@@ -135,7 +142,7 @@ pi-famulus starts and stops processes for you. This section states what it guara
 - **Which binary and versions am I running?** Type `/famulus`. It shows the `pi-famulus` binary path and its version, the running manager's version and pid, and the extension version.
 - **Why does my pi bash command hang on long builds?** With pi-famulus, `bash` stops waiting after 20 seconds and moves the command to the background, so the turn continues. To change the limit, set `foregroundBudgetMs` in `~/.pi/agent/pi-famulus/config.json` ([configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md)).
 - **How do I see or stop running work?** Type `/tasks` in the pi TUI and press `ctrl+x` on an item. From a terminal, `pi-famulus ls` lists what is running.
-- **Does it work on Windows?** Yes, on x64 and arm64. The in-place upgrade, where the daemon re-executes itself, works only on Linux and macOS. On Windows, replace the binary and restart the daemon manually.
+- **Does it work on Windows?** Yes, on x64 and arm64. The in-place upgrade, where the daemon re-executes itself, works only on Linux and macOS. On Windows, replace the binary and restart the daemon manually. Unless `PI_FAMULUS_SHELL` names another shell, `bash` commands run in Git Bash when Git for Windows is installed, else in a `bash.exe` on `PATH` other than WSL's, else in `cmd.exe` ([configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md)). Git Bash's runtime can crash or hang when several copies start at the same moment ([git-for-windows/git#6368](https://github.com/git-for-windows/git/issues/6368)). With a posix shell (anything but `cmd.exe`), pi-famulus staggers shell start-ups to avoid it. A likely start-up crash ends as `shell-start-failed`. A task with no output and no process besides the shell after 20 seconds is stopped as `shell-start-hung`, so a silent command that runs only shell builtins for that long is stopped too. In both cases the agent is told to check for side effects before it retries.
 - **What if a notification does not arrive?** Run `pi-famulus events --id <id>` to see whether the wake was emitted, delivered and injected. Run `pi-famulus doctor` to check daemon health.
 
 ## Docs

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.7",
-  "description": "Done means done: subagents and long-running background bash for Pi. One daemon owns every shell it starts and wakes the agent when work finishes. No polling.",
+  "version": "0.1.8",
+  "description": "Keep your main agent's context clean: subagents on cheaper models, long bash in the background, and monitors that wake the agent. One Rust daemon runs the shells.",
   "keywords": [
     "pi-package",
     "pi",
@@ -54,12 +54,12 @@
     "pi-famulus": "./bin/pi-famulus.js"
   },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.7",
-    "pi-famulus-linux-arm64": "0.1.7",
-    "pi-famulus-darwin-x64": "0.1.7",
-    "pi-famulus-darwin-arm64": "0.1.7",
-    "pi-famulus-win-x64": "0.1.7",
-    "pi-famulus-win-arm64": "0.1.7"
+    "pi-famulus-linux-x64": "0.1.8",
+    "pi-famulus-linux-arm64": "0.1.8",
+    "pi-famulus-darwin-x64": "0.1.8",
+    "pi-famulus-darwin-arm64": "0.1.8",
+    "pi-famulus-win-x64": "0.1.8",
+    "pi-famulus-win-arm64": "0.1.8"
   },
   "pi": {
     "extensions": [

package/src/bash-override.ts

@@ -13,10 +13,7 @@
  * ({ truncation?, fullOutputPath? }); extension fields are added alongside.
  */
 import { spawn } from "node:child_process";
-import { randomUUID } from "node:crypto";
-import { writeFileSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { BoundedOutput } from "./bounded-output";
 import { Type, type Static } from "typebox";
 import {
   getShellConfig,
@@ -29,6 +26,7 @@ import { taskOutputPath, type FamulusConfig } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 import { backgroundRowText, formatBackgroundNotice, truncateTail } from "./format";
 import { toolComponent } from "./tui/tool-component";
+import { scrubTty } from "./tui/conversation-view";
 import type { WorkIndex } from "./work-index";
 import type { ManagerClient } from "./manager-client";
 import { fill, PROMPTS } from "./prompts.generated";
@@ -38,6 +36,7 @@ import {
   collectOutput,
   formatFinishedOutput,
   killedBy,
+  exitedStatus,
   killedStatus,
   timedOutStatus,
   SHELL_MAX_BYTES,
@@ -177,7 +176,13 @@ async function executeLocal(
   }
   const viaStdin = shell.commandTransport === "stdin";
 
-  const output = await new Promise<{ text: string; exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
+  const collector = new BoundedOutput({
+    maxBytes: MAX_BYTES,
+    maxLines: MAX_LINES,
+    // structuredOutput() keeps up to this much tail.
+    tailBytes: STRUCTURED_OUTPUT_MAX_BYTES,
+  });
+  const output = await new Promise<{ exitCode: number | null; signal: string | null; timedOut: boolean; aborted: boolean }>(
     (resolve, reject) => {
       const child = spawn(shell.shell, viaStdin ? shell.args : [...shell.args, params.command], {
         cwd: ctx.cwd,
@@ -190,7 +195,6 @@ async function executeLocal(
         child.stdin?.on("error", () => {});
         child.stdin?.end(params.command);
       }
-      const chunks: Buffer[] = [];
       let settled = false;
       let timedOut = false;
       let aborted = false;
@@ -200,7 +204,7 @@ async function executeLocal(
         settled = true;
         if (timer !== null) clock.clearTimeout(timer);
         signal?.removeEventListener("abort", onAbort);
-        resolve({ text: Buffer.concat(chunks).toString("utf8"), exitCode, signal: killSignal, timedOut, aborted });
+        resolve({ exitCode, signal: killSignal, timedOut, aborted });
       };
       const kill = () => {
         try {
@@ -222,8 +226,7 @@ async function executeLocal(
           : null;
       if (timer !== null) clock.unref?.(timer);
       signal?.addEventListener("abort", onAbort, { once: true });
-      child.stdout?.on("data", (d: Buffer) => chunks.push(d));
-      child.stderr?.on("data", (d: Buffer) => chunks.push(d));
+      collector.attach(child.stdout, child.stderr);
       child.on("error", (err) => {
         if (timer !== null) clock.clearTimeout(timer);
         signal?.removeEventListener("abort", onAbort);
@@ -236,21 +239,22 @@ async function executeLocal(
     },
   );
 
-  const t = truncateTail(output.text, MAX_LINES, MAX_BYTES);
+  const collected = await collector.finish();
+  const t = truncateTail(collected.text, MAX_LINES, MAX_BYTES);
+  const totalLines = collected.totalLines;
   let text = t.text || "(no output)";
   let details: FamulusBashDetails | undefined;
-  if (t.truncated) {
-    const fullOutputPath = join(tmpdir(), `pi-famulus-bash-${randomUUID()}.log`);
-    writeFileSync(fullOutputPath, output.text, "utf8");
+  if (t.truncated || collected.headDropped) {
+    const fullOutputPath = collected.fullOutputPath;
     const outputLines = t.text.length === 0 ? 0 : t.text.split("\n").length;
-    const startLine = t.totalLines - outputLines + 1;
+    const startLine = totalLines - outputLines + 1;
     details = {
       truncation: {
         content: t.text,
         truncated: true,
-        truncatedBy: t.totalLines > MAX_LINES ? "lines" : "bytes",
-        totalLines: t.totalLines,
-        totalBytes: t.totalBytes,
+        truncatedBy: totalLines > MAX_LINES ? "lines" : "bytes",
+        totalLines,
+        totalBytes: collected.totalBytes,
         outputLines,
         outputBytes: Buffer.byteLength(t.text, "utf8"),
         lastLinePartial: false,
@@ -260,7 +264,9 @@ async function executeLocal(
       },
       fullOutputPath,
     };
-    text += `\n\n[Showing lines ${startLine}-${t.totalLines} of ${t.totalLines}. Full output: ${fullOutputPath}]`;
+    text += fullOutputPath
+      ? `\n\n[Showing lines ${startLine}-${totalLines} of ${totalLines}. Full output: ${fullOutputPath}]`
+      : `\n\n[Showing lines ${startLine}-${totalLines} of ${totalLines}. Full output unavailable]`;
   }
 
   if (output.aborted) throw new Error(appendStatus(text, "Command aborted"));
@@ -268,10 +274,10 @@ async function executeLocal(
     throw new Error(appendStatus(text, timedOutStatus(params.timeout)));
   }
   if (output.exitCode === null) throw new Error(appendStatus(text, killedBy(output.signal)));
-  const { output: structuredText, truncated: structuredTruncated } = structuredOutput(output.text);
+  const { output: structuredText, truncated: structuredTruncated } = structuredOutput(collected.text);
   const structuredContent: BashToolOutput = {
     output: structuredText,
-    truncated: structuredTruncated,
+    truncated: structuredTruncated || collected.headDropped,
     ...(details?.fullOutputPath ? { full_output_path: details.fullOutputPath } : {}),
     exit_code: output.exitCode,
     wall_time_seconds: wallSeconds(startedAtMs, clock.now()),
@@ -311,24 +317,26 @@ export function createBashOverride(
         const index = deps.getIndex?.() ?? null;
         const state = context.state as { unsubscribe?: () => void };
         const item = index?.get(taskId);
-        if (index && !state.unsubscribe && isActiveStatus(item?.status)) {
-          // Redraw this row when the task finishes, then stop listening.
+        if (index && !state.unsubscribe && (!item || isActiveStatus(item.status))) {
+          // Redraw this row as the task appears or finishes; stop once it has.
           state.unsubscribe = index.onChange(() => {
-            if (!isActiveStatus(index.get(taskId)?.status)) {
+            const now = index.get(taskId);
+            if (now && !isActiveStatus(now.status)) {
               state.unsubscribe?.();
               state.unsubscribe = () => {};
             }
             context.invalidate();
           });
         }
-        const row = backgroundRowText(taskId, item, (deps.clock ?? realClock).now());
+        const row = backgroundRowText(taskId, item, (deps.clock ?? realClock).now(), index !== null);
         return toolComponent([`${theme.fg(row.color as never, row.glyph)} ${theme.fg("muted", row.text)}`]) as never;
       }
       const text = result.content
         .filter((c): c is { type: "text"; text: string } => c.type === "text")
         .map((c) => c.text)
         .join("\n");
-      const lines = text.split("\n");
+      // Progress \r, tabs, and cursor sequences would scramble the row.
+      const lines = scrubTty(text).split("\n");
       const shown = expanded ? lines : lines.slice(0, PREVIEW_LINES);
       const out = shown.map((l) => theme.fg("toolOutput", l));
       if (shown.length < lines.length) {
@@ -442,7 +450,7 @@ export function createBashOverride(
         // Mirror the built-in bash tool: non-zero exits resolve to an isError
         // result carrying structuredContent instead of rejecting.
         return {
-          content: [{ type: "text", text: appendStatus(text, `Command exited with code ${exitCode}`) }],
+          content: [{ type: "text", text: appendStatus(text, await exitedStatus(client, start.task_id, exitCode)) }],
           details,
           structuredContent,
           isError: true,

package/src/bounded-output.ts

@@ -0,0 +1,167 @@
+/**
+ * Bounded collector for a streaming command's output.
+ *
+ * Keeps only a raw byte tail in memory and, once the output outgrows the
+ * display limits, streams the full output to a temp file asynchronously.
+ * Memory stays bounded and no step materializes the whole output as one
+ * buffer or string on the event loop.
+ */
+import { randomUUID } from "node:crypto";
+import { createWriteStream, type WriteStream } from "node:fs";
+import type { Readable } from "node:stream";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface BoundedOutputOptions {
+  /** Spill to a temp file once total bytes exceed this. */
+  maxBytes: number;
+  /** Spill to a temp file once total lines exceed this. */
+  maxLines: number;
+  /** Raw bytes of tail to keep in memory. */
+  tailBytes: number;
+  /** Temp file name prefix. */
+  tempFilePrefix?: string;
+}
+
+export interface BoundedOutputResult {
+  /** Decoded tail (the whole output when nothing was dropped). */
+  text: string;
+  /** True when `text` is missing a head that was dropped from memory. */
+  headDropped: boolean;
+  totalBytes: number;
+  /** Line count as `text.split("\n").length` would give for the full output. */
+  totalLines: number;
+  /** Full output, present once the output exceeded the limits. */
+  fullOutputPath?: string;
+}
+
+export class BoundedOutput {
+  private chunks: Buffer[] = [];
+  private bufferedBytes = 0;
+  private headDropped = false;
+  private totalBytes = 0;
+  private newlines = 0;
+  private stream: WriteStream | null = null;
+  private streamFailed = false;
+  private path: string | undefined;
+  private sources: Readable[] = [];
+  private waitingForDrain = false;
+
+  constructor(private readonly opts: BoundedOutputOptions) {}
+
+  /**
+   * Collect from these streams, pausing them while the spill file drains so
+   * output faster than the disk cannot pile up in the write stream's buffer.
+   */
+  attach(...streams: Array<Readable | null | undefined>): void {
+    for (const stream of streams) {
+      if (!stream) continue;
+      this.sources.push(stream);
+      stream.on("data", (d: Buffer) => this.append(d));
+    }
+  }
+
+  append(data: Buffer): void {
+    if (data.length === 0) return;
+    this.totalBytes += data.length;
+    for (let i = data.indexOf(10); i !== -1; i = data.indexOf(10, i + 1)) this.newlines++;
+    if (this.stream === null && !this.streamFailed && this.exceedsLimits()) this.openSpill();
+    if (this.stream !== null && !this.stream.write(data)) this.applyBackpressure(this.stream);
+    this.chunks.push(data);
+    this.bufferedBytes += data.length;
+    // Trim lazily (at 2x) so trimming cost is amortized over many chunks.
+    if (this.bufferedBytes > this.opts.tailBytes * 2) this.trim();
+  }
+
+  async finish(): Promise<BoundedOutputResult> {
+    // Sources have ended; drop any pause left from the last write.
+    if (this.waitingForDrain) {
+      this.waitingForDrain = false;
+      for (const source of this.sources) source.resume();
+    }
+    this.trim();
+    let raw = this.chunks.length === 1 ? this.chunks[0] : Buffer.concat(this.chunks);
+    if (this.headDropped) raw = skipPartialUtf8(raw);
+    const text = raw.toString("utf8");
+    let fullOutputPath: string | undefined;
+    if (this.stream !== null) {
+      const stream = this.stream;
+      this.stream = null;
+      const ok = await new Promise<boolean>((resolve) => {
+        stream.once("error", () => resolve(false));
+        stream.end(() => resolve(true));
+      });
+      if (ok && !this.streamFailed) fullOutputPath = this.path;
+    }
+    return {
+      text,
+      headDropped: this.headDropped,
+      totalBytes: this.totalBytes,
+      totalLines: this.newlines + 1,
+      fullOutputPath,
+    };
+  }
+
+  private applyBackpressure(stream: WriteStream): void {
+    if (this.waitingForDrain || this.sources.length === 0) return;
+    this.waitingForDrain = true;
+    for (const source of this.sources) source.pause();
+    const release = () => {
+      stream.off("drain", release);
+      stream.off("close", release);
+      this.waitingForDrain = false;
+      for (const source of this.sources) source.resume();
+    };
+    stream.on("drain", release);
+    stream.on("close", release);
+  }
+
+  private exceedsLimits(): boolean {
+    return this.totalBytes > this.opts.maxBytes || this.newlines + 1 > this.opts.maxLines;
+  }
+
+  private openSpill(): void {
+    this.path = join(tmpdir(), `${this.opts.tempFilePrefix ?? "pi-famulus-bash"}-${randomUUID()}.log`);
+    const stream = createWriteStream(this.path);
+    stream.on("error", () => {
+      this.streamFailed = true;
+      // Stop writing to a failed spill; keep collecting the in-memory tail.
+      // autoDestroy then emits "close", which releases paused sources.
+      if (this.stream === stream) this.stream = null;
+    });
+    // Everything seen so far is still in memory: the head is only dropped
+    // after the spill file exists.
+    this.stream = stream;
+    let drained = true;
+    for (const chunk of this.chunks) drained = stream.write(chunk);
+    if (!drained) this.applyBackpressure(stream);
+  }
+
+  private trim(): void {
+    const cap = this.opts.tailBytes;
+    if (this.bufferedBytes <= cap) return;
+    // Spill before dropping anything so the full output survives.
+    if (this.stream === null && !this.streamFailed) this.openSpill();
+    let excess = this.bufferedBytes - cap;
+    while (excess > 0 && this.chunks.length > 0) {
+      const first = this.chunks[0];
+      if (first.length <= excess) {
+        this.chunks.shift();
+        excess -= first.length;
+        this.bufferedBytes -= first.length;
+      } else {
+        this.chunks[0] = first.subarray(excess);
+        this.bufferedBytes -= excess;
+        excess = 0;
+      }
+    }
+    this.headDropped = true;
+  }
+}
+
+/** Drop leading UTF-8 continuation bytes left by a byte-offset cut. */
+function skipPartialUtf8(buf: Buffer): Buffer {
+  let i = 0;
+  while (i < buf.length && i < 4 && (buf[i] & 0xc0) === 0x80) i++;
+  return i === 0 ? buf : buf.subarray(i);
+}

package/src/comms/reply-command.ts

@@ -38,7 +38,7 @@ export function registerReplyCommand(pi: ExtensionAPI, comms: Comms): void {
     handler: async (args, ctx: ExtensionContext) => {
       const resolved = resolveReplyCommand(args, comms.pendingRequests());
       if ("error" in resolved) {
-        ctx.ui.notify(resolved.error, "info");
+        ctx.ui.notify(resolved.error, "warning");
         return;
       }
       try {

package/src/format.ts

@@ -8,6 +8,7 @@ import {
   formatFamulusWake,
   shellWakeTitle,
   type FamulusWake,
+  type MonitorOutputInfo,
   wakeDuration,
   type FormattedWake,
   type OverrunShell,
@@ -15,6 +16,21 @@ import {
   type WakeItem,
 } from "./wake";
 import { fill } from "./prompts.generated";
+import { shellStartStatus } from "./shell-start";
+import { statusGlyph } from "./tui/tool-component";
+
+/** `850ms`, `12s`, `4m05s`, `2h03m`, `3d04h`: the same style as `pi-famulus top`. */
+export function formatDuration(ms: number): string {
+  const total = Math.max(0, Math.floor(ms));
+  if (total < 1000) return `${total}ms`;
+  const secs = Math.floor(total / 1000);
+  if (secs < 60) return `${secs}s`;
+  const m = Math.floor(secs / 60);
+  if (m < 60) return `${m}m${String(secs % 60).padStart(2, "0")}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h${String(m % 60).padStart(2, "0")}m`;
+  return `${Math.floor(h / 24)}d${String(h % 24).padStart(2, "0")}h`;
+}
 
 export { FAMULUS_WAKE_LEAD_IN } from "./wake";
 export type { FormattedWake, WakeItem } from "./wake";
@@ -84,6 +100,8 @@ export interface TaskExitInfo {
   preview: string;
   /** Signal name from the manager, when the exit was a signal. */
   signal?: string;
+  /** The manager's end_reason, when it sent one. */
+  endReason?: string;
 }
 
 /** Shorten a command for one-line display inside notifications. */
@@ -92,6 +110,8 @@ function displayCommand(command: string): string {
 }
 
 function statusPhrase(info: TaskExitInfo): string {
+  const startFailure = shellStartStatus(info.endReason);
+  if (startFailure) return startFailure;
   const code = info.exitCode === null ? null : `exit code ${info.exitCode}`;
   switch (info.status) {
     case "completed":
@@ -160,17 +180,22 @@ export function backgroundRowText(
   taskId: string,
   item: { status: string; exitCode?: number | null; startedAt: number; endedAt?: number } | undefined,
   now: number,
+  indexed = false,
 ): { glyph: string; color: string; text: string } {
+  // Missing from the index: pruned after it finished, or not yet re-listed
+  // after a reload. Either way the state is unknown, so claim neither.
+  if (!item && indexed) return { glyph: "·", color: "dim", text: `${taskId} · status in /tasks` };
   if (!item || item.status === "running" || item.status === "pending") {
-    return { glyph: "⏵", color: "accent", text: `${taskId} running in background · /tasks` };
+    const { glyph, color } = statusGlyph(item?.status ?? "running");
+    return { glyph, color, text: `${taskId} running in background · /tasks` };
   }
-  const secs = ((item.endedAt ?? now) - item.startedAt) / 1000;
-  const dur = secs < 60 ? `${secs.toFixed(1)}s` : `${Math.floor(secs / 60)}m${Math.round(secs % 60)}s`;
+  const dur = formatDuration((item.endedAt ?? now) - item.startedAt);
   const exit = item.exitCode === null || item.exitCode === undefined ? "" : ` · exit ${item.exitCode}`;
   const ok = item.status === "completed" && (item.exitCode === 0 || item.exitCode === null || item.exitCode === undefined);
-  return ok
-    ? { glyph: "✓", color: "success", text: `${taskId} finished${exit} · ${dur}` }
-    : { glyph: "✗", color: "error", text: `${taskId} ${item.status}${exit} · ${dur} · /tasks` };
+  if (ok) return { ...statusGlyph("completed"), text: `${taskId} finished${exit} · ${dur}` };
+  // A non-zero exit fails the row even when the task "completed".
+  const { glyph, color } = statusGlyph(item.status === "completed" ? "failed" : item.status);
+  return { glyph, color, text: `${taskId} ${item.status}${exit} · ${dur} · /tasks` };
 }
 
 /** Injected payload for a batch of monitor output lines (§4.4 / §4.5). */
@@ -179,7 +204,7 @@ export function formatMonitorEvent(
   taskId: string,
   batchText: string,
   status?: string,
-  extras: { eventCount?: number; droppedLines?: number } = {},
+  extras: { eventCount?: number; droppedLines?: number; output?: MonitorOutputInfo } = {},
 ): FormattedWake {
   return formatFamulusWake({
     kind: "monitor",
@@ -189,6 +214,7 @@ export function formatMonitorEvent(
     event: batchText,
     ...(extras.eventCount !== undefined ? { eventCount: extras.eventCount } : {}),
     ...(extras.droppedLines !== undefined ? { droppedLines: extras.droppedLines } : {}),
+    ...(extras.output ? { output: extras.output } : {}),
   });
 }
 

package/src/index.ts

@@ -302,6 +302,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       status: toExitStatus(event),
       exitCode: event.exit_code ?? null,
       ...(typeof event.signal === "string" && event.signal ? { signal: event.signal } : {}),
+      ...(event.end_reason ? { endReason: event.end_reason } : {}),
       durationMs: event.duration_ms ?? 0,
       outputPath: event.output_path ?? "",
       preview: readPreview(event.output_path, 4000),
@@ -381,7 +382,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
       noteStopRequested: (id) => monitorRegistry?.noteStopRequested(id),
     }),
   );
-  pi.registerTool(createMonitorTool(monitorRegistry));
+  pi.registerTool(createMonitorTool(monitorRegistry, () => workIndex));
   registerTasksCommand(pi, {
     getRegistry: () => subagentRegistry,
     getIndex: () => workIndex,
@@ -556,7 +557,7 @@ function createFamulusRuntime(retiring?: Promise<unknown>): FamulusRuntime {
         return;
       }
       if (event.event === "output" && event.task_id && typeof event.chunk === "string") {
-        monitorRegistry?.handleOutput(event.task_id, event.chunk, event.next_cursor);
+        monitorRegistry?.handleOutput(event.task_id, event.chunk, event.next_cursor, event.monitor_records);
         return;
       }
       if (event.event === "task_exited" && event.task_id) {

package/src/manager-client.ts

@@ -18,7 +18,7 @@ import { famulusPaths } from "./config";
 import { realClock, type Clock, type ClockTimer } from "./clock";
 
 const MAX_FRAME_BYTES = 4 * 1024 * 1024; // 4 MiB (§3.3)
-const EXTENSION_VERSION = "0.1.7";
+const EXTENSION_VERSION = "0.1.8";
 export { EXTENSION_VERSION };
 // 5: speaks per-kind agent admission and queued acquire.
 const PROTOCOL = 5;
@@ -52,6 +52,8 @@ export interface StartRequest {
   run_in_background?: boolean;
   timeout_ms?: number | null;
   origin?: TaskOrigin;
+  /** Human-readable name (monitor description). */
+  label?: string;
 }
 
 export interface StartResponse {
@@ -91,6 +93,19 @@ export interface TaskRecord {
   end_reason?: string;
 }
 
+/** Rust-framed logical output. Fingerprints cover full content, not the preview. */
+export interface MonitorOutputRecord {
+  version: 1;
+  kind: "line" | "progress";
+  observed_at: number;
+  cursor_start: number;
+  cursor_end: number;
+  preview: string;
+  truncated: boolean;
+  fingerprint?: string;
+  timestamp_fingerprint?: string;
+}
+
 /** Server-pushed event (§3.3). Fields beyond `event` depend on the event kind. */
 export interface ManagerEvent {
   event: "task_started" | "output" | "task_exited" | "session_rebound" | string;
@@ -100,6 +115,8 @@ export interface ManagerEvent {
   pid?: number;
   chunk?: string;
   next_cursor?: number;
+  /** Absent on legacy managers/replay fallback; [] means Rust framing is active. */
+  monitor_records?: MonitorOutputRecord[];
   exit_code?: number | null;
   signal?: string | null;
   duration_ms?: number;