pi-famulus 0.1.6 → 0.1.8

package/README.md

@@ -1,41 +1,170 @@
-# pi-famulus
+<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>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 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> ·
+    <a href="https://github.com/Leechael/pi-famulus/blob/main/docs/design.md">Architecture</a> ·
+    <a href="https://github.com/Leechael/pi-famulus/blob/main/eval/RESULTS.md">Eval results</a>
+  </p>
+  <a href="https://www.npmjs.com/package/pi-famulus"><img src="https://img.shields.io/npm/v/pi-famulus?style=flat-square" alt="npm"></a>
+  <a href="https://github.com/Leechael/pi-famulus/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/Leechael/pi-famulus/ci.yml?branch=main&style=flat-square&label=ci" alt="CI"></a>
+  <a href="https://github.com/Leechael/pi-famulus/stargazers"><img src="https://img.shields.io/github/stars/Leechael/pi-famulus?style=flat-square" alt="Stars"></a>
+  <a href="https://github.com/Leechael/pi-famulus/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square" alt="License"></a>
+  <a href="https://github.com/Leechael/pi-famulus/commits"><img src="https://img.shields.io/github/commit-activity/m/Leechael/pi-famulus?style=flat-square" alt="Commits"></a>
+  <a href="https://x.com/leechael"><img src="https://img.shields.io/badge/follow-leechael-red?style=flat-square&logo=x" alt="X"></a>
+</div>
 
-Subagent orchestration, auto-backgrounding bash, monitoring, and agent-to-agent communication for pi 1.0.0 or newer.
+<!-- TODO(visual): a full-width screenshot or GIF goes here. None exists yet. Candidate: a recording of `/tasks` and the fleet line while a test suite runs in the background and a subagent reports back. -->
 
-Workers inherit user/global and trusted-project pi configuration and resources, including codemode and MCP, then receive famulus communication tools. An explicit agent `tools` list remains an allowlist; omitting it inherits the user’s default tools. Parent-only CLI resource overrides are not copied.
+## Why
 
-After the first public release:
+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.
 
-```sh
+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:
+
+- **A foreground watch blocks the chat.** With pi-famulus, `bash` moves a command to the background after 20 seconds, and the turn goes on.
+- **A backgrounded command finishes silently.** With pi-famulus, the result is injected into the conversation when the command exits, so the model reacts instead of polling.
+- **A subagent reports "done" while its work still runs.** With pi-famulus, a subagent's `bash` cannot move to the background, and a subagent cannot start subagents or monitors. When it reports done, nothing it started through pi-famulus is still running, unless a command detached itself with `setsid` or left a process running with `&`.
+
+One machine-wide daemon (`pi-famulus`, written in Rust) starts every shell command and monitor, including the ones subagents run, and is their parent. If the daemon crashes or is killed, the process groups it started are stopped, except commands that moved into a new session with `setsid`. Subagents themselves run inside pi.
+
+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.
+>
+> - `pi-subagents` also registers `subagent`. Do not install it alongside pi-famulus.
+> - `pi-background-tasks` also registers `/tasks`, so pi lists both as `/tasks:1` and `/tasks:2`. It overlaps with pi-famulus in purpose. Choose one of the two.
+>
+> Details: [conflicts](https://github.com/Leechael/pi-famulus/blob/main/docs/development.md#conflicts-with-other-packages).
+
+```bash
 pi install npm:pi-famulus
 ```
 
-npm installs the matching native manager automatically through an exact-version optional dependency. No Rust compiler, postinstall download, or separate manager installation is needed. Keep optional dependencies enabled.
+Requires pi 1.0.0 or newer. Native daemon builds ship for Linux x64 and arm64, macOS x64 and arm64 (macOS 13+), and Windows x64 and arm64. The daemon ships as an exact-version optional dependency of the npm package, so keep optional dependencies enabled. No Rust compiler or extra download is needed.
+
+You do not write tool calls. After installing, ask the agent in plain language:
+
+```text
+Run the full test suite and tell me what fails.
+```
+
+`bash` waits 20 seconds. If the command is still running, it moves to the background and the turn continues. The result arrives in the conversation when the command exits.
+
+## Features
+
+- **Auto-backgrounding bash**: A command that runs longer than `foregroundBudgetMs` (20 seconds by default) moves to the background. Set `run_in_background` to start it there at once. Bare `sleep` is rejected.
+- **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 `&`.
+- **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**: 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
+
+| 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` 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 |
+
+| In the pi TUI | Does |
+| :--- | :--- |
+| `/tasks` | Live list of shells, monitors and subagents; `ctrl+x` stops the selected item |
+| `/reply <child> <text>` | Answers a subagent's question without going through the model |
+| `/famulus` | Shows the `pi-famulus` binary path and the manager and extension versions |
+| Fleet line (the status line below the editor) | Shows the shells, monitors and subagents that are running |
+
+**Plan with your strongest model, implement with a cheap one.** Select your strongest model in pi, then save this as `~/.pi/agent/agents/worker.md`:
+
+```markdown
+---
+name: worker
+description: Implements one concrete task end to end
+model: haiku
+---
+Do the task you were given. Make the edits and run the tests that prove it works.
+Stay within the task's scope. Report what you changed and how you verified it.
+```
+
+Now ask:
+
+```text
+Plan the move from callbacks to async/await in src/api/. When the plan is settled,
+have subagents implement it one module at a time, then review what they return.
+```
+
+The session model writes the plan. `subagent` runs `worker` by default, and `worker` uses the model that `haiku` matches.
+
+- `model` is matched against the model ids and names that pi lets you use: your `enabledModels` or `--models` scope, or every available model when no scope is set. It must match exactly one. In an agent file, no match or several matches fall back to the parent model with a warning. On a single `subagent` call, they are an error, and the model is told the candidates.
+- Add a thinking level with a suffix, for example `model: haiku:high`.
+- A `worker.md` in `<project>/.pi/agents/` overrides the one in your home directory. Without any `worker.md`, subagents use the parent's model.
+- Built-in agents are `explorer` (read, grep, find, ls, bash) and `worker` (inherits your tools). Add your own as markdown files in the same folders.
+- `subagent({action: "steer" | "resume" | "extend" | "interrupt"})` redirects a running subagent, continues a finished one, gives it more time, or stops it.
+
+## Reliability
+
+pi-famulus starts and stops processes for you. This section states what it guarantees and where the guarantee ends.
+
+- On Unix, the daemon starts every shell and monitor task in a process group, and is its parent. When the daemon ends (`shutdown`, `kill -9`, panic), each group gets SIGTERM, then SIGKILL 2 seconds later. Windows tasks run in Job Objects and are terminated as a unit when stopped or when the daemon exits.
+- A command that moves a child into a new session (`setsid`) leaves the group and escapes this. A process left running with `&` keeps running until it exits or the daemon stops it.
+- 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. 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
 
-Supported native packages:
+- **How is pi-famulus different from `pi-subagents` or `pi-background-tasks`?** They are alternatives, so choose one. Choose [`pi-subagents`](https://github.com/nicobailon/pi-subagents) for ready-made roles, saved workflows, `/council`, or background subagents in a detached process. Choose [`pi-background-tasks`](https://github.com/ismailsaleekh/pi-background-tasks) for named background shell jobs with output files, a read-only delegated agent, or its Fusion workflows. Choose pi-famulus for one daemon that owns every shell and monitor process across your pi sessions, a shared cap on concurrent subagents, and a CLI for inspecting past runs.
+- **Can I attach to a subagent like a tmux pane?** No. Subagents run inside the agent's process, so you cannot attach to one or take over its session. Steer, resume or interrupt it through the parent, answer its questions with `/reply`, and read what it did with `pi-famulus agent <id> -f`, `show <id>` and `top`.
+- **Does it work outside the pi TUI?** Yes. It loads wherever pi loads extensions, including RPC mode (`pi --mode rpc`) and agents built with the pi SDK. Print mode (`pi -p`) loads it too, but exits when the first run ends, so later results are not seen. In an SDK agent, load it through `DefaultResourceLoader` (for example with `additionalExtensionPaths`) and call `session.bindExtensions()`. The real-model eval drives pi in RPC mode.
+- **Can a subagent start its own subagents?** No. Nesting is limited to one level.
+- **What happens to background tasks when pi exits?** Five seconds after the last pi session closes, the daemon stops whatever is still running and exits. Read the records afterwards with `pi-famulus show <id>`.
+- **Does `/reload` stop running work?** No. Shells, monitors and subagents keep running, and their results still arrive. If the reload loads a different pi-famulus version, the old version's work is stopped first.
+- **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. 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.
 
-| System | CPU | Package |
-|---|---|---|
-| Linux | x64 | `pi-famulus-linux-x64` |
-| Linux | arm64 | `pi-famulus-linux-arm64` |
-| macOS | Intel x64 | `pi-famulus-darwin-x64` |
-| macOS | Apple Silicon arm64 | `pi-famulus-darwin-arm64` |
-| Windows | x64 | `pi-famulus-win-x64` |
+## Docs
 
-Linux binaries are statically linked with musl. macOS binaries target macOS 13 or newer; Windows x64 binaries use MSVC with the CRT linked statically. Windows ARM64 is not published until CI produces that tarball. Your Node/pi runtime's requirements also apply. In-place manager upgrade remains Unix-only.
+- [Tool reference](https://github.com/Leechael/pi-famulus/blob/main/docs/tools.md): parameters, agent files, terminal UI
+- [Configuration](https://github.com/Leechael/pi-famulus/blob/main/docs/configuration.md): `config.json`, timeouts, binary lookup, degraded mode
+- [CLI manual](https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md): `doctor`, `ls`, `show`, `top`, `agent`, `stats`, `events`
+- [Architecture](https://github.com/Leechael/pi-famulus/blob/main/docs/design.md): daemon, lifeline, wakes, subagent runner
+- [Machine-wide capacity](https://github.com/Leechael/pi-famulus/blob/main/docs/global-capacity.md): `max-agents` and work-kind limits
+- [Eval results](https://github.com/Leechael/pi-famulus/blob/main/eval/RESULTS.md): real-model scenario matrix
+- [Development](https://github.com/Leechael/pi-famulus/blob/main/docs/development.md): building from source, tests, package conflicts
+- [Releasing](https://github.com/Leechael/pi-famulus/blob/main/docs/releasing.md)
 
-The npm package also exposes the `pi-famulus` CLI (`npx pi-famulus --help`). The extension's binary search order is:
+## Background
 
-1. Executable `managerPath` from configuration.
-2. Executable `PI_FAMULUS_MANAGER_PATH` override.
-3. The matching-version installed native npm package.
-4. Executable `~/.pi/agent/pi-famulus/bin/pi-famulus` (or the equivalent beneath `PI_FAMULUS_HOME`).
-5. Executable `pi-famulus` on `PATH`.
+pi-famulus borrows several behaviors from other agents. From Claude Code it takes background-on-timeout instead of kill, completion injected into the conversation, a batched `monitor`, and bare-`sleep` interception. From grok-build it takes a 45-second wait budget for subagents and an admission queue that waits instead of rejecting. From lain it takes foreground-only bash for child agents. It also takes lessons from `pi-subagents` and `pi-intercom` about what to leave out. The research notes are in [design, section 1](https://github.com/Leechael/pi-famulus/blob/main/docs/design.md#1-background-and-goals).
 
-On Windows the file name in steps 4 and 5 (and inside the native package) is `pi-famulus.exe`.
+## Support
 
-Configuration and runtime state remain in `~/.pi/agent/pi-famulus`. Installing/updating the npm package does not move that state or copy a binary into the shared home. The npm CLI uses the package's native executable; use the extension configuration above when intentionally running a separately built manager.
+- If pi-famulus helped you, give it a star, or open an [issue](https://github.com/Leechael/pi-famulus/issues) or a pull request.
+- When you report a problem, include the output of `pi-famulus doctor` and `pi-famulus events --id <id>`.
 
-If optional dependencies were omitted, reinstall with them enabled. The CLI reports an actionable error; the extension can still discover an explicitly installed manager and otherwise enters degraded mode. An arbitrary different-version native npm package is never substituted.
+## License
 
-See the [project README](https://github.com/Leechael/pi-famulus#readme) for tools, settings, one-time migration, and source-build instructions; see the [CLI manual](https://github.com/Leechael/pi-famulus/blob/main/docs/cli.md) for operations.
+Released under the [MIT License](https://github.com/Leechael/pi-famulus/blob/main/LICENSE).

package/package.json

@@ -1,9 +1,32 @@
 {
   "name": "pi-famulus",
-  "version": "0.1.6",
-  "description": "Subagents, monitoring, and auto-backgrounding bash for pi",
+  "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",
+    "pi-extension",
+    "pi-coding-agent",
+    "subagent",
+    "subagents",
+    "background",
+    "background-tasks",
+    "bash",
+    "daemon",
+    "multi-agent",
+    "monitor",
+    "agent-orchestration"
+  ],
+  "author": "Leechael Yim",
+  "homepage": "https://github.com/Leechael/pi-famulus",
+  "bugs": {
+    "url": "https://github.com/Leechael/pi-famulus/issues"
+  },
   "type": "module",
   "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/Leechael/pi-famulus",
@@ -31,11 +54,12 @@
     "pi-famulus": "./bin/pi-famulus.js"
   },
   "optionalDependencies": {
-    "pi-famulus-linux-x64": "0.1.6",
-    "pi-famulus-linux-arm64": "0.1.6",
-    "pi-famulus-darwin-x64": "0.1.6",
-    "pi-famulus-darwin-arm64": "0.1.6",
-    "pi-famulus-win-x64": "0.1.6"
+    "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": [
@@ -46,6 +70,7 @@
     "deps": "nub install --frozen-lockfile --node-linker hoisted",
     "prompts": "node scripts/build-prompts.ts",
     "test": "vitest run",
+    "test:compat": "vitest run tests/unit/impl-child-resource-isolation.test.ts tests/unit/impl-child-tools.test.ts tests/unit/impl-child-guidelines.test.ts tests/unit/impl-subagent-lifecycle.test.ts tests/unit/impl-steering-drain.test.ts tests/unit/impl-model-spec.test.ts tests/unit/impl-eval-fixes.test.ts tests/integration/behavior-guidelines.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {

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 {