@asterxsk/kiln 0.3.0 → 0.4.2

package/agent/extensions/background-terminals/docs/implementation-guide.md

@@ -1,942 +1,942 @@
-# background-terminals — Implementation Guide
-
-> Research phase output. Updated 2026-07-24 against:
-> - `effect@4.0.0-beta.101` (verified installed in this package's `node_modules/effect`; the
->   `unstable/process` module exists there but we deliberately do NOT use it — see §6)
-> - `@earendil-works/pi-coding-agent@^0.82.0` docs at
->   `/Users/davis/.vite-plus/js_runtime/node/24.18.0/lib/node_modules/@earendil-works/pi-coding-agent/docs/`
-> - Reference implementations: `extensions/subagents` (Effect v4 service/manager/read-model/tools)
->   and `extensions/workflows` (dashboard UI, status line, background completion follow-ups).
->
-> Read alongside `extensions/subagents/docs/effect-v4-notes.md` (API cheat sheet) and
-> `extensions/subagents/docs/effect-v4-extension-guide.md` (toolchain + ManagedRuntime boundary).
-> Those two documents are authoritative for Effect v4 API names — do not use v3 APIs
-> (`Effect.fork`, `Effect.async`, `Either`, `Context.Tag`, `Mailbox`, `ServiceMap` are all
-> wrong; use `forkChild`/`forkDetach`, `Effect.callback`, `Result`, `Context.Service`, `Queue`).
-
-## 1. What this extension is
-
-The model can start long-running shell processes ("background terminals"), keep working while
-they run, check on them, and stop them. It can **never** write to a running process's stdin —
-processes are launched with `stdin: "ignore"`; there is no send/steer surface at all (this is
-the key simplification vs. subagents' `send()`).
-
-- Full stdout and stderr are captured **separately and completely** in private spill files;
-  bounded in-memory tails keep `/ps` responsive (§7.4).
-- Tool responses to the model are **always truncated** with the pi truncation utilities.
-- When a process exits, the model is woken **exactly once** via `pi.sendMessage(...,
-  { deliverAs: "followUp", triggerTurn: true })` — no polling — using the same
-  deferred-delivery/consumed dance as subagents (§9).
-- While ≥1 process is running, a one-line widget renders **directly above the editor**:
-  `N background terminal(s) running • /ps to view` (§10).
-- `/ps` opens a two-stage full-screen overlay (list → detail with scrollable stdout/stderr),
-  modeled on `extensions/subagents/src/ui/takeover.ts` and
-  `extensions/workflows/dashboard.ts` (§11).
-
-## 2. Directory / file architecture
-
-Mirror the subagents layout exactly (it is the known-green reference; `npm run check` passes
-there against the pinned toolchain):
-
-```
-extensions/background-terminals/
-├── package.json              # exact pins, see §3
-├── tsconfig.json             # extends ../../tsconfig.json + effect LS plugin
-├── index.ts                  # extension edge: tools, command, widget, events (plain TS + runTool)
-├── docs/
-│   └── implementation-guide.md   (this file)
-├── src/
-│   ├── domain.ts             # types, status union, errors, formatting helpers
-│   ├── manager.ts            # TerminalManager Context.Service + Layer (the Effect core)
-│   ├── output.ts             # OutputBuffer: bounded decoded text + byte counters (plain TS class)
-│   ├── runtime.ts            # ManagedRuntime factory + runTool helper (copy of subagents')
-│   ├── prompt.ts             # all model-facing strings (tool descriptions, result builders)
-│   ├── result-delivery.ts    # deferred one-shot delivery map (copy of subagents')
-│   └── ui/
-│       ├── ps.ts             # /ps picker + detail view components
-│       └── output-view.ts    # stdout/stderr → wrapped display lines
-├── manager.test.ts           # node:test end-to-end through a real ManagedRuntime
-├── output.test.ts            # OutputBuffer truncation/decoding unit tests
-├── result-delivery.test.ts   # (copied semantics, tiny)
-└── ps.test.ts                # selection-reconciliation tests (like takeover.test.ts)
-```
-
-Tests live at the package root, plain `node --test --experimental-strip-types`, exactly like
-`extensions/subagents/package.json`'s `test` script. Note the repo-root `package.json` test
-script (`node --test --experimental-strip-types extensions/*/*.test.ts`) will automatically
-pick these up.
-
-## 3. Toolchain (copy exactly, per effect-v4-extension-guide.md §1)
-
-`package.json`:
-
-```jsonc
-{
-  "name": "background-terminals",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "check": "tsc --noEmit -p .",
-    "prepare": "effect-tsgo patch",
-    "test": "node --test --experimental-strip-types manager.test.ts output.test.ts result-delivery.test.ts ps.test.ts"
-  },
-  "dependencies": {
-    "effect": "^4.0.0-beta.99"
-  },
-  "devDependencies": {
-    "@effect/tsgo": "^0.24.2",
-    "typescript": "^7.0.2"
-  }
-}
-```
-
-`tsconfig.json` — identical to `extensions/subagents/tsconfig.json`:
-
-```jsonc
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": { "plugins": [{ "name": "@effect/language-service" }] },
-  "include": ["index.ts", "src/**/*.ts", "*.test.ts"]
-}
-```
-
-Per AGENTS.md: add deps with an install command (`npm install effect@^4.0.0-beta.99`),
-run `npm run check` when done, avoid explicit return types unless needed, no `as any`.
-Verification runs from inside `extensions/background-terminals/` only — never root scripts
-(house rule, effect-v4-extension-guide.md §7/§8).
-
-Note: we do **not** need `@effect/platform-node`. Subagents' codex backend uses raw
-`node:child_process` `spawn` inside Effect and that is the right model here too (§6).
-
-## 4. Domain model (`src/domain.ts`)
-
-Follow `extensions/subagents/src/domain.ts` (readonly interfaces, `Data.TaggedError`, status
-string union, mutable-snapshot-behind-readonly-view trick lives in the manager).
-
-```ts
-import { Data } from "effect";
-
-export type TerminalStatus = "running" | "done" | "failed" | "killed";
-// "done"   = exited with code 0
-// "failed" = exited non-zero, or spawn-level runtime error after start
-// "killed" = terminated by bg_kill, UI kill, or session teardown
-
-export interface TerminalSnapshot {
-  readonly id: string;                 // "bt-1", "bt-2", ... (manager counter, like "sa-N")
-  readonly command: string;            // exactly what the model asked to run (display string)
-  readonly title: string;              // short model-provided name, shown in UI (<=80 chars)
-  readonly cwd: string;                // resolved absolute cwd the process runs in
-  readonly pid?: number;               // undefined only if spawn itself failed
-  readonly status: TerminalStatus;
-  readonly createdAt: number;          // Date.now() at spawn
-  readonly settledAt?: number;         // Date.now() at exit/kill
-  readonly exitCode?: number;          // null-safe: only set when exited via exit code
-  readonly signal?: string;            // e.g. "SIGTERM" when terminated by signal
-  readonly errorText?: string;         // spawn error / kill-escalation notes, bounded
-  // Live output views (see src/output.ts):
-  readonly stdout: OutputView;
-  readonly stderr: OutputView;
-}
-
-export interface OutputView {
-  readonly text: string;               // decoded, possibly head-trimmed text (bounded)
-  readonly totalBytes: number;         // true total bytes ever received
-  readonly truncatedBytes: number;     // bytes dropped from the head (0 = complete)
-  readonly spillPath?: string;         // on-disk full capture, when spilling engaged (§7.6)
-}
-
-export class SpawnError extends Data.TaggedError("SpawnError")<{
-  readonly message: string;
-}> {}
-export class ConcurrencyLimitError extends Data.TaggedError("ConcurrencyLimitError")<{
-  readonly message: string;
-}> {}
-export class UnknownTerminalError extends Data.TaggedError("UnknownTerminalError")<{
-  readonly message: string;
-}> {}
-
-export function formatElapsed(snap: TerminalSnapshot) { /* copy from subagents domain.ts */ }
-```
-
-### State transitions
-
-```
-        spawn ok                     exit code 0
- (none) ────────► running ───────────────────────► done
-                    │                exit code ≠0 / 'error' event
-                    ├─────────────────────────────► failed
-                    │      bg_kill / UI x / session_shutdown
-                    └─────────────────────────────► killed
- spawn throws (ENOENT etc.) → tool call fails; NO entry is tracked (SpawnError to the model)
-```
-
-Terminal states are final; there is no restart (unlike subagents' `send()` restart). A killed
-process that raced an exit event keeps whichever settle landed first — settle must be
-idempotent (`if (s.status !== "running") return;`, exactly like `settle()` in
-`extensions/subagents/src/manager.ts`).
-
-Timestamps: `createdAt`/`settledAt` are `Date.now()` millis (matches subagents; `formatElapsed`
-consumes them). Exit status: record **both** `exitCode` (number | undefined) and `signal`
-(string | undefined) from Node's `exit (code, signal)` callback — exactly one is non-null per
-Node semantics; render "exit 0", "exit 137", or "SIGKILL" accordingly.
-
-## 5. Effect architecture (`src/runtime.ts`, `src/manager.ts`)
-
-### 5.1 Runtime boundary
-
-Copy `extensions/subagents/src/runtime.ts` nearly verbatim (it is only 53 lines):
-
-```ts
-import { Cause, Exit, ManagedRuntime, type Effect } from "effect";
-import { TerminalManagerLive } from "./manager.ts";
-
-export function createTerminalRuntime() {
-  return ManagedRuntime.make(TerminalManagerLive);
-}
-export type TerminalRuntime = ReturnType<typeof createTerminalRuntime>;
-
-export async function runTool<A, E>(
-  runtime: TerminalRuntime,
-  effect: Effect.Effect<A, E>,
-  options: { signal?: AbortSignal; interruptMessage?: string } = {},
-) {
-  const exit = await runtime.runPromiseExit(
-    effect,
-    options.signal ? { signal: options.signal } : undefined,
-  );
-  if (Exit.isSuccess(exit)) return exit.value;
-  if (Cause.hasInterruptsOnly(exit.cause)) {
-    throw new Error(options.interruptMessage ?? "Operation was aborted.");
-  }
-  const [first] = Cause.prettyErrors(exit.cause);
-  throw new Error(first?.message ?? Cause.pretty(exit.cause));
-}
-```
-
-No `BackendRegistry` layer is needed — there is exactly one "backend" (node spawn), so
-`AppLayer` is just `TerminalManagerLive`.
-
-`index.ts` builds the runtime lazily and disposes it on `session_shutdown`, exactly like
-`extensions/subagents/index.ts` lines 128–222:
-
-```ts
-let runtime: TerminalRuntime | undefined;
-let managerPromise: Promise<TerminalManagerShape> | undefined;
-const getRuntime = () => (runtime ??= createTerminalRuntime());
-const getManager = () => {
-  managerPromise ??= getRuntime().runPromise(TerminalManager).then((manager) => {
-    manager.view.setOnSettled(onSettled);
-    unsubStatus?.();
-    unsubStatus = manager.view.subscribe(() => updateWidget(manager));
-    updateWidget(manager);
-    return manager;
-  });
-  return managerPromise;
-};
-```
-
-### 5.2 TerminalManager service (`src/manager.ts`)
-
-One `Context.Service` holding a plain `Map<string, Entry>` plus the synchronous read model
-(the exact structure of `SubagentManager` — see `extensions/subagents/src/manager.ts`, which
-is the single most important file to imitate):
-
-```ts
-export interface TerminalManagerShape {
-  start(options: StartOptions): Effect.Effect<TerminalSnapshot, SpawnError | ConcurrencyLimitError>;
-  status(id: string): Effect.Effect<TerminalSnapshot, UnknownTerminalError>;
-  readonly list: Effect.Effect<ReadonlyArray<TerminalSnapshot>>;
-  kill(ids: ReadonlyArray<string>): Effect.Effect<ReadonlyArray<KillResult>>; // resolves when settled
-  readonly disposeAll: Effect.Effect<void>;
-  readonly view: TerminalReadModel;   // synchronous bridge for the TUI + widget
-}
-
-export class TerminalManager extends Context.Service<TerminalManager, TerminalManagerShape>()(
-  "background-terminals/TerminalManager",
-) {}
-
-export const TerminalManagerLive: Layer.Layer<TerminalManager> =
-  Layer.effect(TerminalManager, makeManager);
-```
-
-`makeManager = Effect.gen(function* () { ... })` closes over:
-
-- `const entries = new Map<string, Entry>()` — mutable snapshot per entry (readonly view out).
-- `const listeners = new Set<() => void>()` + `notify()` — any-change subscription for the
-  widget and `/ps` list, with try/catch around each UI listener.
-- One `Deferred<void>` per entry, completed synchronously and exactly once by `settle()`.
-  Every `kill()` caller awaits the Deferreds for entries that were running when it began.
-- A scoped `FiberSet.runtime` bridge for fire-and-forget UI kills, process-event settlement,
-  and pruning. Completed fibers remove themselves; disposal waits for the set within a bound,
-  and scope close interrupts cleanup still live after that bound.
-- `let counter = 0` for ids; `let disposed = false`; `waitInterest` is NOT needed (there is no
-  `bg_wait` tool in v1 — see §8 note), but the "consumed" concept still applies to `bg_kill`
-  and `bg_status` so a settle isn't double-announced (§9.3).
-- `yield* Effect.addFinalizer(() => disposeAll)` — the safety net so `runtime.dispose()` in
-  `session_shutdown` kills every process even if the extension forgot (subagents manager.ts
-  line 657).
-
-Concurrency cap: subagents caps at `MAX_RUNNING = 4` with a synchronous reservation
-(`Effect.suspend` before the first yield so parallel tool calls cannot race the check —
-manager.ts lines 364–383). For terminals use `MAX_RUNNING = 8` (processes are cheaper than
-agents) and the same reservation pattern; and `MAX_TRACKED = 32` completed entries retained,
-pruned oldest-settled-first exactly like `pruneSettled()` (never prune running entries).
-
-### 5.3 Where Effect fibers/queues/etc. do and don't earn their keep
-
-Per effect-v4-extension-guide.md §0 the async core is Effect; per the codex backend precedent
-the Node stream plumbing stays plain callbacks. Concretely:
-
-- **Yes Effect:** the manager service/layer, `start` reservation, per-entry `Deferred`,
-  `kill` (timeout + escalation + Deferred wait), scoped `FiberSet` cleanup, `disposeAll`
-  (parallel bounded teardown), `runTool` boundary, and `Effect.addFinalizer`.
-- **Plain TS callbacks:** `child.stdout.on("data")`, `child.on("exit")` handlers mutate the
-  entry snapshot and call `notify()` directly. This is exactly what the codex backend does with
-  its JSON-RPC stdout pump (`codex.ts` lines ~820–860). Do NOT build a
-  `Queue<SubagentEvent>`/pump-fiber pipeline here — subagents needs that because three
-  heterogeneous backends normalize into one event stream; a single spawn does not.
-
-## 6. Node child_process design (the core of `start`)
-
-Model on `makeCodexSession` in `extensions/subagents/src/backends/codex.ts` (spawn options,
-kill-tree, terminate-with-escalation), minus the JSON-RPC machinery:
-
-```ts
-import { spawn } from "node:child_process";
-
-const child = yield* Effect.try({
-  try: () =>
-    spawn(shellPath, ["-c", options.command], {
-      cwd: options.cwd,
-      env: process.env,
-      stdio: ["ignore", "pipe", "pipe"],       // ← stdin IGNORED: no input surface, ever
-      detached: process.platform !== "win32",  // own process group on POSIX → group kill
-    }),
-  catch: (error) => new SpawnError({ message: boundedError(error) }),
-});
-```
-
-Decisions and rationale:
-
-- **Shell execution.** The model supplies one `command` string; run it through the platform
-  shell (`/bin/sh -c` on POSIX, `cmd.exe /d /s /c` on Windows) so pipes/redirection work. Honor the
-  user's configured shell if convenient (`~/.pi/agent/settings.json` has
-  `"shellPath": ".../zsh-with-rc"`), but `/bin/sh` is an acceptable v1 — document which you
-  pick in the tool description. Never `shell: true` with an args array (double-parse trap).
-- **`stdin: "ignore"`** enforces the "no subsequent input" requirement at the OS level. A
-  process that tries to read stdin gets EOF immediately, which is the honest contract (and the
-  tool description must say so — interactive commands will exit or hang, and `bg_kill` is the
-  remedy).
-- **`detached: true` on POSIX** gives the child its own process group, so kill can signal
-  `-pid` and take down the whole tree (grandchildren from `npm run dev` etc.). `killTree`
-  keeps the direct-signal fallback when the group is gone; Windows uses `taskkill /T` and
-  adds `/F` for the force-kill phase. `terminateChild` uses Effect
-  callbacks/timeouts: SIGTERM now, SIGKILL after 2s if needed, then a final 500ms bound.
-  Do NOT call `child.unref()` — we want the exit event, and pi owns the lifetime anyway.
-- **Spawn failure semantics.** `spawn()` itself rarely throws; ENOENT arrives via
-  `child.once("error", ...)`. Wire the error handler *before* returning from `start`, and treat
-  an error event pre-exit as settling the entry to `failed` with `errorText` (mirror
-  `failForProcessExit` in codex.ts). To catch instant failures, you may optionally wait one
-  tick for `spawn` event vs `error` event, but simplest correct behavior: register the entry
-  immediately as `running` and let the near-instant `error`/`exit` settle it; the model gets
-  the settle notification milliseconds later.
-- **Exit handling** (single source of truth for settling):
-
-```ts
-child.once("exit", (code, signal) => {
-  finishOutput(entry);       // flush any pending partial decode
-  settle(entry, {
-    status: entry.killSignaled ? "killed" : code === 0 ? "done" : "failed",
-    exitCode: code ?? undefined,
-    signal: signal ?? undefined,
-  });
-});
-```
-
-  `killSignaled` is set in the same synchronous effect that sends SIGTERM, so a process that
-  exits before signaling keeps its natural status while a signaled process reports `killed`.
-  Settle is idempotent (§4).
-- **cwd semantics.** The tool takes optional `working_dir`; resolve with
-  `path.resolve(ctx.cwd, params.working_dir ?? ".")` and validate
-  `fs.existsSync(cwd) && fs.statSync(cwd).isDirectory()` in the tool handler *before* touching
-  the runtime — throw a plain Error otherwise. This is copied from `subagent_spawn`'s handler
-  (`extensions/subagents/index.ts` lines 262–265). No trust-store logic is needed (we are not
-  spawning an agent in another project; a shell command in another directory is equivalent to
-  what the bash tool already allows).
-
-### 6.1 Why not `effect/unstable/process` yet?
-
-`ChildProcess.make` + `ChildProcessHandle` is the eventual target, but the current Effect beta
-cannot preserve the current process contract yet:
-
-1. `forceKillAfter` does not correctly wait before SIGKILL on POSIX in this pin.
-2. `ChildProcessHandle.exitCode` does not expose the actual terminating signal, while the
-   public snapshot and model-facing output distinguish `SIGTERM` from `SIGKILL`.
-
-This first pass therefore keeps raw spawn and stream callbacks, while moving termination
-waits, escalation deadlines, settlement coordination, and cleanup ownership into Effect.
-Do not add `@effect/platform-node` until both blockers can be resolved.
-
-## 7. Output capture (`src/output.ts`)
-
-### 7.1 Requirements recap
-
-Capture stdout and stderr **separately** and **completely** (the user's "full stdout/stderr"),
-viewable in `/ps`; tool responses truncated; memory must be bounded.
-
-### 7.2 Decoding — do it right
-
-Do NOT use `child.stdout.setEncoding("utf8")` naïvely-per-chunk... actually `setEncoding`
-internally uses a StringDecoder and *is* multibyte-safe across chunk boundaries, which is why
-codex.ts can use it. Two acceptable options; pick (a):
-
-- (a) `child.stdout.setEncoding("utf8")` and receive `string` chunks (Node handles split
-  UTF-8 sequences). Simplest, matches codex.ts line ~824.
-- (b) accumulate `Buffer`s and decode with `new (await import("node:string_decoder")).StringDecoder("utf8")`.
-
-Either way, strip nothing at capture time — raw text goes into the buffer; ANSI/control
-sanitization happens at *render* time using `sanitizeText` (copy from
-`extensions/subagents/src/ui/transcript.ts` lines 15–29; it exists precisely because raw ANSI
-desyncs the TUI renderer).
-
-### 7.3 OutputBuffer (bounded ring with head-drop + optional spill)
-
-```ts
-export class OutputBuffer {
-  private chunks: string[] = [];
-  private bytes = 0;            // bytes currently retained (Buffer.byteLength of chunks)
-  totalBytes = 0;               // true total ever received
-  truncatedBytes = 0;           // dropped from the head
-  spillPath?: string;
-
-  constructor(private maxRetainedBytes: number, private spill?: (chunk: string) => void) {}
-
-  push(chunk: string) {
-    /* Count and spill the complete chunk first. If the chunk alone exceeds
-       maxRetainedBytes, discard older retained chunks and UTF-8-safely trim
-       this chunk to its newest cap-sized tail. Otherwise append it and evict
-       older whole chunks until retained bytes fit. Every discarded byte
-       increments truncatedBytes; totalBytes counts the original input. */
-  }
-  view(): OutputView { /* { text: this.chunks.join(""), totalBytes, truncatedBytes, spillPath } */ }
-}
-```
-
-Cache the `join("")` and invalidate on push so the 1Hz UI tick doesn't re-join megabytes.
-
-### 7.4 Memory bounds vs "full inspection" — the honest tradeoff
-
-Unbounded retention of a `yes`-style firehose is a hard memory leak (codex.ts caps its stderr
-retain at 4 KiB and treats an unbounded protocol buffer as session-fatal for exactly this
-reason). Resolution:
-
-- **In-memory retained cap: 2 MiB per stream per process** (so ≤ 8 procs × 2 streams × 2 MiB =
-  32 MiB worst case). The newest output is always retained; the head is dropped.
-- **Spill-to-disk for the full capture** (this is what makes "full stdout/stderr" true even
-  past the cap): create the shared/session directories with owner-only `0700` permissions,
-  then open two `0600` append-mode `WriteStream`s under
-  ``path.join(os.tmpdir(), "pi-background-terminals", sessionId, `${id}.stdout.log`)`` (and
-  `.stderr.log`). A `WriteStream` serializes writes per stream; settlement ends and awaits
-  both streams behind a bounded flush barrier before publishing the result. A stream error or
-  flush timeout clears the affected full-log pointer and surfaces a bounded `errorText` note.
-  The `/ps` detail view shows the in-memory tail and, when `truncatedBytes > 0`, a header line
-  "first N KiB dropped from view — full log: <spillPath>"; model-facing results reference the
-  same path. `disposeAll` removes the private session spill directory after all entry scopes
-  and spill flushes complete, so secret-bearing logs do not outlive the owning pi session.
-- Precedent for "truncate + point at the full file": docs/extensions.md "Output Truncation"
-  section recommends exactly this shape for tool results.
-
-### 7.5 Entry wiring inside `start`
-
-Per entry, like subagents' `spawn` (manager.ts lines 385–466):
-
-```ts
-const scope = yield* Scope.make();
-const settled = yield* Deferred.make<void>();
-// finalizer kills the tree; registered in the scope so BOTH kill() and disposeAll()
-// and runtime.dispose() converge on one teardown path:
-yield* Scope.provide(
-  Effect.addFinalizer(() =>
-    Effect.gen(function* () {
-      yield* terminateChild(child, () => entry.stdioClosed, markKillSignaled);
-      yield* Deferred.await(settled).pipe(
-        Effect.timeout(SETTLE_GRACE_MS),
-        Effect.ignore,
-      );
-      // If still running, flush output within its bound and settle here.
-    }),
-  ),
-  scope,
-);
-entries.set(id, { snapshot, child, scope, stdoutBuf, stderrBuf, settled });
-```
-
-`kill(ids)` then is: `Scope.close(entry.scope, Exit.void)` (bounded with
-`Effect.timeout(STOP_TIMEOUT_MS)` + `Effect.ignore`) in the scoped cleanup `FiberSet`, then
-await every captured entry's `Deferred`. Return per-id `{ id, status, killed: boolean }`
-results and treat already-settled ids as no-ops rather than errors.
-
-`disposeAll`: set `disposed = true`, snapshot `[...entries.values()]`, close every scope with
-`{ concurrency: "unbounded" }` and a 5s timeout each — verbatim subagents `disposeAll`
-(manager.ts lines 596–618).
-
-### 7.6 Race conditions checklist (each has a subagents precedent)
-
-- **Spawn vs concurrent spawn past the cap** → synchronous reservation before first yield
-  (`reserved++` inside `Effect.suspend`; decrement in `Effect.ensuring`).
-- **Kill vs natural exit** → idempotent `settle` with one authoritative precedence rule. If
-  kill reaches a live shell, set `killSignaled` in the same effect that signals it and report
-  `killed`. If the shell's `exit` event was already observed, preserve its natural
-  `done`/`failed` status even when cleanup must still signal descendants holding stdio open.
-  A missing `close` after `exit` starts a bounded grace, then closes the entry scope so the
-  surviving process group is terminated and the entry cannot occupy a running slot forever.
-- **Exit event vs scope close ("stream ended unexpectedly")** → we have no pump, so this class
-  disappears; the only settle source is the `exit`/`error` listener.
-- **Settle during teardown** → `if (!disposed) onSettled?.(...)` so a result is never queued
-  into a shutting-down session (subagents `settle`, manager.ts line 280).
-- **Tool AbortSignal during `bg_kill`'s wait** → interruption stops only that caller's
-  `Deferred.await`; the detached scope-close stays owned by the manager `FiberSet`, and
-  `Effect.ensuring` still releases bookkeeping.
-- **Late output after exit** → Node may still flush 'data' after 'exit' is observed in rare
-  orderings; buffers accept pushes until `close` — harmless because settle doesn't freeze the
-  buffer, and the UI just shows more text. (Optionally listen on `close` instead of `exit` to
-  be strictly after stdio flush; `close` fires when stdio streams end — prefer `close` for
-  settling to guarantee complete output at notification time, and keep `exit` only to record
-  code/signal. This is the one place we improve on codex.ts, which doesn't need output
-  completeness.)
-
-**Recommended:** record `{code, signal}` on `exit`, settle + notify on `close`. This
-guarantees the completion follow-up message contains the final output tail.
-
-## 8. Tools (`index.ts` + `src/prompt.ts`)
-
-All model-facing strings live in `src/prompt.ts` (subagents convention). Register with
-`pi.registerTool`; parameters via `typebox` `Type.Object`; use `StringEnum` from
-`@earendil-works/pi-ai` if any enum appears (Google-compat rule, docs/extensions.md
-"Tool Definition"). Throw plain `Error` for failures (that is what sets `isError`).
-
-### 8.1 `bg_start`
-
-```ts
-parameters: Type.Object({
-  command: Type.String({ description: "Shell command line to run in the background (sh -c on POSIX, cmd.exe /d /s /c on Windows). It receives no stdin (EOF immediately); interactive commands will not work." }),
-  title: Type.String({ description: "Short human-readable name shown in listings and the UI" }),
-  working_dir: Type.Optional(Type.String({ description: "Working directory (default: current working directory)" })),
-})
-```
-
-Handler: validate cwd (§6), `title.trim().slice(0, 80) || "terminal"`, then
-`runTool(getRuntime(), manager.start({ command, title, cwd }))`. Result text (build in
-prompt.ts, like `buildSubagentSpawnResult`):
-
-```
-Started background terminal bt-3 "dev server" (pid 12345, /Users/davis/project).
-It runs in the background with no stdin. You'll get a message when it exits, or use
-bg_status(id: "bt-3") to peek, bg_kill to stop it, bg_list to see all.
-```
-
-`promptSnippet`: "Run a long-lived shell command in the background (dev servers, builds,
-watchers); output is captured and you're notified on exit".
-`promptGuidelines` (name the tool explicitly — docs warn "this tool" is ambiguous):
-- "Use bg_start for commands expected to run long or indefinitely (servers, watch modes); use the regular bash tool for quick commands."
-- "bg_start processes receive no stdin — never start a command that requires interactive input."
-- "After bg_start, keep working; the exit result arrives automatically. Use bg_status only when you need current output before continuing."
-
-Description documents the truncation limits (docs requirement) and the no-stdin contract.
-
-### 8.2 `bg_status`
-
-```ts
-parameters: Type.Object({ id: Type.String({ description: 'Terminal id, e.g. "bt-1"' }) })
-```
-
-Unknown id → throw with the known-ids list (copy the exact error style from `subagent_check`:
-`Unknown terminal id "x". Known: bt-1, bt-2.`). Result: one metadata line
-(`bt-1 [running] "dev server" (pid 12345, 3m12s, exit -, /path)`) then **tail-truncated**
-stdout and stderr sections:
-
-```ts
-const stdout = truncateTail(snap.stdout.text, { maxBytes: 16 * 1024, maxLines: 400 });
-const stderr = truncateTail(snap.stderr.text, { maxBytes: 8 * 1024, maxLines: 200 });
-```
-
-`truncateTail` (not head) because for process logs the end matters — this is the documented
-guidance in docs/extensions.md Output Truncation. When truncated, append
-`[stdout truncated: showing last X of Y. Full log: <spillPath or "in /ps viewer">]` using
-`formatSize` + the truncation result fields (see `truncatedOutput()` in subagents index.ts for
-the message shape). If `bg_status` observes a settled entry whose completion message is still
-pending delivery, mark it consumed (§9.3).
-
-### 8.3 `bg_list`
-
-No parameters. One line per entry via a `describeTerminal(snap)` helper (mirror
-`describeSubagent`): id, status, title, pid, elapsed, exit code/signal, cwd, and total output
-sizes (`formatSize(stdout.totalBytes)`). "No background terminals." when empty. Include both
-running and completed (completed entries are retained up to `MAX_TRACKED`).
-
-### 8.4 `bg_kill`
-
-```ts
-parameters: Type.Object({ ids: Type.Array(Type.String(), { description: 'Terminal ids to stop, e.g. ["bt-1"]' }) })
-```
-
-Validate all ids known first (throw listing unknowns, copy `subagent_cancel`). Then
-`runTool(getRuntime(), manager.kill(ids), { signal, interruptMessage: "Kill wait aborted; termination continues in the background." })`.
-Report per id: `Killed bt-1 "dev server" (SIGTERM).` or `bt-2 "build" was already done (exit 0).`
-Killing marks the settle consumed so the model doesn't also get the async completion message
-(§9.3) — same reason subagents' `cancel` calls `addInterest` before interrupting.
-
-**No `bg_wait` and no `bg_send`.** No stdin is a hard requirement. Blocking wait is
-deliberately omitted in v1: completion notification makes it redundant, and it would drag in
-subagents' full `waitInterest` machinery. If it's ever wanted, each entry already has a
-settlement `Deferred` and the subagents `waitFor` result shaping is the template.
-
-## 9. Completion notification — exactly once, no polling, no turn races
-
-This is the subtlest requirement. Copy the subagents solution wholesale; it exists precisely
-to solve this problem (see comments in `extensions/subagents/index.ts` lines 168–222 and
-`result-delivery.ts`).
-
-### 9.1 Mechanism
-
-On settle, the manager invokes a hook `onSettled(snap, consumed)` registered by `index.ts`
-(same `view.setOnSettled` bridge). The hook:
-
-```ts
-const resultDelivery = createDeferredResultDelivery<TerminalSnapshot>();  // copy the 20-line module
-
-const onSettled = (snap: TerminalSnapshot, consumed: boolean) => {
-  if (consumed) { resultDelivery.consume([snap.id]); return; }
-  // Defer a deep-enough copy: the live snapshot keeps mutating (late output flushes).
-  resultDelivery.defer({ ...snap, stdout: { ...snap.stdout }, stderr: { ...snap.stderr } });
-  if (sessionContext?.isIdle()) flushResults();
-};
-
-pi.on("agent_settled", flushResults);
-
-const flushResults = () => {
-  for (const snap of resultDelivery.drain()) {
-    pi.sendMessage({
-      customType: "background-terminal-result",
-      content: buildTerminalResultMessage(snap),   // prompt.ts; truncateTail'd output inside
-      display: true,
-      details: { id: snap.id, title: snap.title, status: snap.status, exitCode: snap.exitCode, signal: snap.signal },
-    }, { deliverAs: "followUp", triggerTurn: true });
-  }
-};
-```
-
-### 9.2 Why this is race-free (the reasoning to preserve in code comments)
-
-- `deliverAs: "followUp"` queues the message until the agent has no more tool calls; it never
-  interrupts a mid-turn stream (docs/extensions.md § pi.sendMessage).
-- `triggerTurn: true` wakes the model immediately **iff idle**; if busy, the queued follow-up
-  is delivered when the current run settles — either way exactly one delivery.
-- The `Map`-keyed `resultDelivery` (keyed by id, `drain()` clears) makes double-delivery
-  structurally impossible even if both the `isIdle()` fast-path and the `agent_settled` event
-  fire: whoever drains first wins, the second drain sees an empty map.
-- The `consumed` flag closes the remaining hole: if the model is *currently inside*
-  `bg_kill` (which returns the final state itself), the settle must not ALSO queue a message.
-  Manager computes `consumed` = "a kill/status collection is in flight for this id" at settle
-  time (subagents: `waitInterest`; here: the `kill()`-marked id set).
-- `if (!disposed)` in `settle` prevents queueing into a shutting-down session.
-
-### 9.3 Consumed-set details
-
-Keep a `Map<string, number> killInterest` in the manager; `kill()` adds interest before
-signaling and releases in `Effect.ensuring` (identical to `addInterest`/`releaseInterest`).
-`settle` computes `consumed = (killInterest.get(id) ?? 0) > 0`. Additionally, `bg_kill`'s tool
-handler calls `resultDelivery.consume(ids)` after `runTool` returns, mirroring
-`subagent_wait`'s "settlement may have happened before this wait began" comment (index.ts
-line 352) — belt and suspenders for the settled-before-kill-started ordering.
-
-### 9.4 Result message content
-
-`buildTerminalResultMessage` (prompt.ts): first line
-`Background terminal bt-3 "dev server" exited (exit 1) after 4m12s.` (or `(SIGTERM)` /
-`was killed`), then tail-truncated stdout (≤ 16 KiB) and, if non-empty, stderr (≤ 8 KiB) in
-labeled sections, with truncation notes pointing at the spill file. Register a
-`pi.registerMessageRenderer("background-terminal-result", ...)` for a collapsed preview —
-copy the subagent-result renderer (index.ts lines 514–561: icon by status, header line,
-8-line preview, "ctrl+o to expand").
-
-## 10. Widget above the editor
-
-Requirement: visible **only while ≥1 process is running**, directly above editor, text
-`N background terminal(s) running • /ps to view`.
-
-API: `ctx.ui.setWidget(key, linesOrFactory)` — default placement is already **above the
-editor** (docs/extensions.md "Widgets, Status, and Footer" + tui.md Pattern 5); do NOT pass
-`placement: "belowEditor"`. Clear with `setWidget(key, undefined)`.
-
-```ts
-const updateWidget = (manager: TerminalManagerShape) => {
-  if (!ui) return;                               // captured from session_start ctx.hasUI
-  const running = manager.view.list().filter((s) => s.status === "running").length;
-  if (running === 0) { ui.setWidget("background-terminals", undefined); return; }
-  ui.setWidget("background-terminals", (_tui, theme) => {
-    const line =
-      theme.fg("warning", "■ ") +
-      theme.fg("text", `${running} background terminal${running === 1 ? "" : "s"} running`) +
-      theme.fg("dim", " • ") + theme.fg("accent", "/ps") + theme.fg("dim", " to view");
-    return { render: () => [line], invalidate: () => {} };
-  });
-};
-```
-
-Drive it from `manager.view.subscribe(...)` exactly like subagents drives `setStatus`
-(index.ts lines 139–166) — the subscription fires on every state change, including settles, so
-the widget disappears the moment the last process exits. Guard `ctx.hasUI`; wrap in try/catch
-like workflows' `updateIndicator` ("UI may be unavailable"). Clear the widget in
-`session_shutdown` before disposing the runtime.
-
-(Singular/plural: render `1 background terminal running`, `2 background terminals running` —
-implement the requested "terminal(s)" sense as proper pluralization.)
-
-## 11. `/ps` command + two-stage UI (`src/ui/ps.ts`, `src/ui/output-view.ts`)
-
-Register `pi.registerCommand("ps", { description: "List and inspect background terminals", handler })`.
-Handler: TUI-mode guard + empty-state notify + open picker — copy the `/subagents` command
-skeleton (index.ts lines 565–587). Non-TUI (`ctx.mode !== "tui"`): print a plain-text listing
-via `ctx.ui.notify` like workflows' non-TUI fallback, or just the notify error like subagents —
-prefer the listing (cheap and useful in RPC mode).
-
-### 11.1 Stage 1 — list (dashboard)
-
-Copy `SubagentDashboard` (`src/ui/takeover.ts` lines 109–344) with terminal rows:
-
-- Entry point loop `openTerminalPicker(ctx, view)` — the `while (true)` pick→detail→back loop
-  of `openSubagentPicker` (lines 52–86), full-screen overlay
-  (`{ overlay: true, overlayOptions: { anchor: "center", width: "100%", maxHeight: "100%" } }`).
-- Row left: selection marker, status glyph (`■` warning/success/error — reuse `statusGlyph`
-  pattern; map `killed` to muted/error), title, dim id.
-- Row right: `pid 12345 · 3m12s · exit 0` (or `running` / `SIGTERM`), dim separators — the
-  `split(left, right, width)` helper from workflows' dashboard is the cleanest to copy.
-- Keys: up/down/j/k select, enter open, `x` kill selected (only when running →
-  `view.requestKill(id)` fire-and-forget, precedent: dashboard `x` → `requestAbort`), esc
-  close. Hint line built from `keybindings.getKeys(...)` via the `configuredKeys` helper.
-- 1Hz `setInterval` ticker for elapsed times + `view.subscribe` re-render, both cleaned up in
-  `dispose()`/`cleanup()` (idempotent closed-flag pattern — copy it exactly; overlay components
-  are disposed on close and must not be reused, tui.md "Overlay Lifecycle").
-- Keep list selection stable across refreshes with `reconcileDashboardSelection` (takeover.ts
-  lines 95–107) — copy it and its test (`takeover.test.ts`).
-
-### 11.2 Stage 2 — detail (read-only inspector)
-
-Copy `TakeoverView` (takeover.ts lines 350–563) **minus the Input line** (read-only: no
-`Focusable`, no `Input`, no `requestSend`). Layout:
-
-```
-────────────────────────────────────────────────────────────
-■ bt-3 · dev server · running · 4m12s · pid 12345 · ~/project
-$ npm run dev
-────────────────────────────────────────────────────────────
-[ tab: stdout (1.2MB) | stderr (4KB) ]        ← `t` toggles streams
-  ...scrollable output lines (sanitized, wrapped, tail-pinned)...
-  ... 120 lines below · ↓/pgdn
-────────────────────────────────────────────────────────────
-esc back · t stdout/stderr · x kill · ↑/↓ scroll · pgup/pgdn page · g/G top/bottom
-────────────────────────────────────────────────────────────
-```
-
-- Metadata header: status glyph, id, title, status word, elapsed (`formatElapsed`), pid, cwd,
-  exit code/signal when settled, total sizes (`formatSize`), truncation note when
-  `truncatedBytes > 0` (with spill path).
-- **stdout/stderr shown separately** (requirement): a `t` key toggles the active stream;
-  header tab shows both sizes. (Alternative side-by-side split like workflows' phases/agents
-  panels is more code for less readability of wide log lines — use the toggle.)
-- Output rendering (`src/ui/output-view.ts`): split buffer text on `\n`, `sanitizeText` each
-  line (copy from transcript.ts — ANSI strip is mandatory or the overlay smears), wrap with
-  `wrapTextWithAnsi`, `truncateToWidth`. Scroll state = offset-from-bottom, 0 = pinned to
-  bottom so a running process live-tails; clamp `scrollOffset` to `maxOffset` each render
-  (TakeoverView lines 510–543 is exactly this fixed-height-viewport math — copy it, including
-  the "scroll status consumes a viewport row" trick so height never jumps).
-- Live updates: `view.subscribeTo(id, ...)` per-entry subscription + the 50ms
-  `scheduleRender` debounce (TakeoverView lines 406–414 — a chatty process emits a chunk per
-  write; do not repaint per chunk).
-- Keys: esc/left back to list (loop re-opens dashboard), `x` kill (running only), scroll keys
-  via `keybindings.matches(data, "tui.editor.cursorUp"/"cursorDown"/"pageUp"/"pageDown")` plus
-  j/k and g/G (workflows transcript view precedent).
-- Big-buffer perf: with the 2 MiB cap, worst case ~30k lines; recompute wrapped lines only when
-  the buffer version or width changed (cache `(version, width) → lines`), not per render tick.
-
-### 11.3 Read model
-
-```ts
-export interface TerminalReadModel {
-  list(): ReadonlyArray<TerminalSnapshot>;
-  get(id: string): TerminalSnapshot | undefined;
-  size(): number;
-  subscribe(listener: () => void): () => void;
-  subscribeTo(id: string, listener: () => void): () => void;
-  requestKill(id: string): void;   // fire-and-forget via the scoped FiberSet runtime
-  setOnSettled(hook?: (snap: TerminalSnapshot, consumed: boolean) => void): void;
-}
-```
-
-Verbatim shape of `SubagentReadModel` minus `requestSend`. Snapshots are live objects; the UI
-must not mutate them (same doc comment as manager.ts line 89).
-
-## 12. Lifecycle: reload / new / resume / fork / shutdown
-
-pi's session replacement flow (docs/extensions.md "Lifecycle Overview" + session_shutdown):
-`/new`, `/resume`, `/fork`, `/reload`, and quit all emit `session_shutdown` (with `event.reason`)
-for the old extension instance, then re-instantiate extensions and emit `session_start`.
-Consequences:
-
-- **Processes do not survive any session transition.** In `session_shutdown`: clear
-  `resultDelivery`, unsubscribe, clear widget, null the ui/context refs, then
-  `await closing?.dispose()` — the ManagedRuntime close runs the manager finalizer →
-  `disposeAll` → every entry scope → `terminateChild` (SIGTERM→SIGKILL tree kill). This is
-  the identical teardown in subagents index.ts lines 210–222; each scope close is bounded
-  (5s timeout) so a wedged process cannot hang shutdown, and SIGKILL covers it anyway.
-- **Spill files do not survive the session either.** `disposeAll` first closes every entry
-  scope and awaits bounded spill flushes, then recursively removes its owner-only session
-  directory. Paths shown in the old transcript are intentionally session-lifetime pointers.
-- **No persistence / no resurrection.** Unlike workflows (which persists `workflow.json` and
-  marks stale "running" runs as aborted on reload — dashboard.ts lines 286–297), v1 keeps no
-  cross-session record: killed-on-shutdown processes simply disappear. Optionally append a
-  `pi.appendEntry("background-terminals-note", {...})` breadcrumb ("bt-2 'dev server' was
-  killed by session shutdown") so a resumed session's transcript explains the vanished
-  terminal — cheap and worth doing; entries don't enter LLM context (docs: appendEntry).
-  The model-facing story stays consistent because tool results always describe terminals as
-  session-scoped ("killed when the session ends" in `bg_start`'s description).
-- **Do not spawn from stale contexts.** All spawning goes through tool handlers with a live
-  `ctx`; the manager rejects `start` when `disposed` (SpawnError "shutting down", subagents
-  manager.ts lines 370–374 precedent).
-- **Fork/clone:** nothing special — same shutdown+start pair; the new instance starts empty.
-
-## 13. Truncation constants (single place, `index.ts` top)
-
-```ts
-const STATUS_STDOUT_MAX = 16 * 1024;   // bg_status stdout tail
-const STATUS_STDERR_MAX = 8 * 1024;    // bg_status stderr tail
-const RESULT_STDOUT_MAX = 16 * 1024;   // completion follow-up stdout tail
-const RESULT_STDERR_MAX = 8 * 1024;
-const RETAINED_PER_STREAM = 2 * 1024 * 1024;  // in-memory cap per stream (spill keeps the rest)
-```
-
-All clamped by `Math.min(..., DEFAULT_MAX_BYTES)` and `DEFAULT_MAX_LINES` (imports from
-`@earendil-works/pi-coding-agent`, verified exported in `dist/index.d.ts`) — same defensive
-clamp as `truncatedOutput` in subagents index.ts. Always `truncateTail` for process output.
-
-## 14. Test plan
-
-Follow the house style: `node:test` + `assert/strict`, end-to-end through a real
-`ManagedRuntime`, minimal count, deterministic (subagents `manager.test.ts` is the template,
-including the `withManager` fixture that guarantees `runtime.dispose()` in `finally`).
-
-**`output.test.ts`** (pure, no processes)
-1. push/view roundtrip; totalBytes/truncatedBytes accounting when the cap evicts head chunks.
-2. multibyte boundary: feeding split UTF-8 via setEncoding path is Node's job, but verify the
-   buffer never splits what it was given and byte counts use `Buffer.byteLength`.
-3. spill callback receives every chunk in order even after eviction.
-
-**`manager.test.ts`** (real processes — use `node -e` one-liners for portability, no shell
-tricks; they exist on any machine running pi)
-1. happy path: `start` node printing to stdout+stderr then exiting 0 → status transitions
-   running→done, exitCode 0, both buffers correct and separate, settle hook fired once with
-   `consumed: false`.
-2. non-zero exit → `failed`, exitCode captured.
-3. `kill` on a `setInterval` never-exiting script → `killed`, signal recorded, `kill()` only
-   resolves after settle; second `kill` of same id reports already-settled, no error.
-4. process-tree termination: spawn a grandchild that updates a unique heartbeat sentinel,
-   kill, then use bounded polling with an explicit timeout to confirm both that the process is
-   gone and that its unique sentinel stopped changing. The sentinel ties the assertion to the
-   spawned child so PID reuse cannot create a false pass.
-5. concurrency cap: cap+1 concurrent starts → last fails with ConcurrencyLimitError;
-   reservation released on spawn failure (start a bogus binary → SpawnError → slot free).
-6. consumed semantics: settle during an in-flight `kill` reports `consumed: true`.
-7. `disposeAll` (via `runtime.dispose()`) kills a running process and settles it as killed;
-   no settle hook fires after dispose (`disposed` guard).
-8. pruning: exceed MAX_TRACKED with settled entries → oldest pruned, running never pruned.
-9. SIGTERM-resistant process → SIGKILL after the 2s grace, within the 5s close bound.
-10. aborted `bg_kill` wait → detached escalation still reaches SIGKILL and settles.
-11. overlapping multi-id kills → every caller observes every captured settlement; each
-    settle hook fires once and consumed state remains true.
-12. shell `exit` without stdio `close` → bounded cleanup reaps the descendant holding the
-    pipes, preserves the shell's natural exit status, and releases the running slot.
-
-**`result-delivery.test.ts`** — consume-before-drain, drain-once (copy subagents' file).
-
-**`ps.test.ts`** — `reconcileTerminalSelection` behavior (copy `takeover.test.ts` cases).
-
-**Manual validation (must actually run pi):**
-- `pi` → ask the model to `bg_start` a dev-server-like command → widget appears above editor
-  with correct count/pluralization → `/ps` list → enter detail → live tail scrolls, `t`
-  toggles stderr, ANSI-heavy output (e.g. `npm run dev`) renders without smearing → back →
-  `x` kills → widget disappears when last settles → completion message arrives exactly once,
-  rendered collapsed, expands with ctrl+o.
-- Race check: start a 2s `sleep`-then-echo while the model is mid-long-turn → result arrives
-  as follow-up after the turn, not mid-stream, and only once.
-- `/new` and `/reload` with a running process → process is dead afterwards (`ps aux | grep`),
-  no orphan, widget cleared.
-- `npm run check` green; `npm test` green; repo-root `npm run format:check` clean for the new
-  files (prettier covers `extensions/**/*.ts`).
-
-## 15. Pitfalls (each burned someone in the reference code)
-
-1. **Effect v3 API names don't exist** — `Effect.fork`, `Effect.async`, `Either`,
-   `Layer.scoped`, `Context.Tag`. Check every API against effect-v4-notes.md before writing it.
-2. **`Queue.end` needs `Cause.Done` in the error type** — only relevant if you add a queue;
-   this design avoids queues entirely.
-3. **Don't render raw process output** — ANSI/tabs/control chars desync the TUI
-   (transcript.ts's `sanitizeText` comment). Sanitize at render, never at capture.
-4. **Don't repaint per data chunk** — 50ms debounce (TakeoverView) or the UI starves input.
-5. **Overlay components are disposed on close** — never cache and re-show; re-invoke
-   `ctx.ui.custom` (tui.md Overlay Lifecycle). Make `cleanup()` idempotent with a `closed`
-   flag and clear every timer in it.
-6. **`detached` + group kill or you orphan grandchildren** — `sh -c "npm run dev"` without
-   process-group SIGTERM leaves node servers running after pi exits (codex.ts `killTree`
-   comment).
-7. **Settle must be idempotent and single-sourced** — kill vs exit vs error events race;
-   `if (status !== "running") return` in settle. Set `killSignaled` atomically with SIGTERM
-   only while the shell is live; an already-observed natural exit keeps `done`/`failed` even
-   if its surviving process group still needs cleanup.
-8. **Never queue messages into a dying session** — `disposed` guard around `onSettled`, and
-   try/catch around `pi.sendMessage` (workflows wraps its follow-up send in try/catch:
-   "Session may be shutting down").
-9. **Defer a copy, not the live snapshot** — the buffer keeps mutating after settle (late
-   flushes); subagents defers `{ ...snap, meta: { ...snap.meta } }` for the same reason.
-10. **Synchronous reservation for the cap** — an `await` between check and increment lets
-    parallel tool calls race past it (manager.ts spawn comment).
-11. **Bound every teardown wait** — 5s timeout on scope closes, or a wedged child hangs
-    `session_shutdown` (subagents `disposeAll` + `abortEntry` comments).
-12. **Snapshot kill interest before Deferred completion** — Effect can resume kill waiters
-    immediately; compute `consumed` before `Deferred.doneUnsafe` so their `ensuring`
-    blocks cannot release interest first.
-13. **Tool output limits are a hard requirement** — unbounded stdout in a tool result causes
-    context overflow/compaction failures (docs Output Truncation). Truncate *everything* the
-    model sees, including the completion message.
-14. **`prepareArguments` is not needed v1** — but never rename/retype `bg_*` parameters later
-    without adding it (resumed sessions replay old tool calls; docs Tool Definition).
-15. **`hasUI`/`mode` guards** — widget + `/ps` must no-op gracefully in print/RPC modes.
-
-## 16. Acceptance checklist
-
-- [ ] `npm install && npm run check` green in `extensions/background-terminals` (TS7 + Effect LS).
-- [ ] `npm test` green (manager, output, result-delivery, ps selection).
-- [ ] Tools registered: `bg_start`, `bg_status`, `bg_list`, `bg_kill`; descriptions document
-      no-stdin, session-scoped lifetime, and truncation limits; no stdin/steer surface exists.
-- [ ] stdout and stderr captured separately and completely (in-memory tail + spill file);
-      `/ps` detail can inspect both, read-only, scrollable, ANSI-sanitized, live-tailing.
-- [ ] Every model-visible output path truncated (`truncateTail` + clamps) with pointers to the
-      full log.
-- [ ] Exactly-once async completion notification via `sendMessage followUp + triggerTurn`,
-      deferred-delivery map, consumed-set for kill, `agent_settled` flush, `isIdle()` fast
-      path, `disposed` guard. No polling anywhere.
-- [ ] Widget above editor only while ≥1 running, text `N background terminals running • /ps to
-      view`, cleared on last settle and on shutdown.
-- [ ] `/ps` two-stage overlay: list (select/kill/open) → detail (metadata, stdout/stderr
-      toggle, scroll, back), matching subagents/workflows interaction conventions and hint
-      lines from `keybindings.getKeys`.
-- [ ] Kill terminates the whole process tree (SIGTERM → 2s → SIGKILL), records exit
-      code/signal, resolves only after settle.
-- [ ] `session_shutdown` (quit/reload/new/resume/fork) kills all processes within bounded
-      time via `runtime.dispose()`; no orphans; no messages sent during teardown.
-- [ ] Completed entries retained (≤ MAX_TRACKED, pruned oldest-settled) and visible in
-      `bg_list` + `/ps`; running entries never pruned.
-- [ ] Concurrency cap enforced race-free; ids are `bt-N`; cwd resolved against `ctx.cwd` and
-      validated; timestamps and elapsed rendering consistent with subagents.
-- [ ] Code style: model strings in `prompt.ts`, Effect only in the async core, plain TS
-      callbacks for stream plumbing, no `as any`, prettier-clean.
+# background-terminals — Implementation Guide
+
+> Research phase output. Updated 2026-07-24 against:
+> - `effect@4.0.0-beta.101` (verified installed in this package's `node_modules/effect`; the
+>   `unstable/process` module exists there but we deliberately do NOT use it — see §6)
+> - `@earendil-works/pi-coding-agent@^0.82.0` docs at
+>   `/Users/davis/.vite-plus/js_runtime/node/24.18.0/lib/node_modules/@earendil-works/pi-coding-agent/docs/`
+> - Reference implementations: `extensions/subagents` (Effect v4 service/manager/read-model/tools)
+>   and `extensions/workflows` (dashboard UI, status line, background completion follow-ups).
+>
+> Read alongside `extensions/subagents/docs/effect-v4-notes.md` (API cheat sheet) and
+> `extensions/subagents/docs/effect-v4-extension-guide.md` (toolchain + ManagedRuntime boundary).
+> Those two documents are authoritative for Effect v4 API names — do not use v3 APIs
+> (`Effect.fork`, `Effect.async`, `Either`, `Context.Tag`, `Mailbox`, `ServiceMap` are all
+> wrong; use `forkChild`/`forkDetach`, `Effect.callback`, `Result`, `Context.Service`, `Queue`).
+
+## 1. What this extension is
+
+The model can start long-running shell processes ("background terminals"), keep working while
+they run, check on them, and stop them. It can **never** write to a running process's stdin —
+processes are launched with `stdin: "ignore"`; there is no send/steer surface at all (this is
+the key simplification vs. subagents' `send()`).
+
+- Full stdout and stderr are captured **separately and completely** in private spill files;
+  bounded in-memory tails keep `/ps` responsive (§7.4).
+- Tool responses to the model are **always truncated** with the pi truncation utilities.
+- When a process exits, the model is woken **exactly once** via `pi.sendMessage(...,
+  { deliverAs: "followUp", triggerTurn: true })` — no polling — using the same
+  deferred-delivery/consumed dance as subagents (§9).
+- While ≥1 process is running, a one-line widget renders **directly above the editor**:
+  `N background terminal(s) running • /ps to view` (§10).
+- `/ps` opens a two-stage full-screen overlay (list → detail with scrollable stdout/stderr),
+  modeled on `extensions/subagents/src/ui/takeover.ts` and
+  `extensions/workflows/dashboard.ts` (§11).
+
+## 2. Directory / file architecture
+
+Mirror the subagents layout exactly (it is the known-green reference; `npm run check` passes
+there against the pinned toolchain):
+
+```
+extensions/background-terminals/
+├── package.json              # exact pins, see §3
+├── tsconfig.json             # extends ../../tsconfig.json + effect LS plugin
+├── index.ts                  # extension edge: tools, command, widget, events (plain TS + runTool)
+├── docs/
+│   └── implementation-guide.md   (this file)
+├── src/
+│   ├── domain.ts             # types, status union, errors, formatting helpers
+│   ├── manager.ts            # TerminalManager Context.Service + Layer (the Effect core)
+│   ├── output.ts             # OutputBuffer: bounded decoded text + byte counters (plain TS class)
+│   ├── runtime.ts            # ManagedRuntime factory + runTool helper (copy of subagents')
+│   ├── prompt.ts             # all model-facing strings (tool descriptions, result builders)
+│   ├── result-delivery.ts    # deferred one-shot delivery map (copy of subagents')
+│   └── ui/
+│       ├── ps.ts             # /ps picker + detail view components
+│       └── output-view.ts    # stdout/stderr → wrapped display lines
+├── manager.test.ts           # node:test end-to-end through a real ManagedRuntime
+├── output.test.ts            # OutputBuffer truncation/decoding unit tests
+├── result-delivery.test.ts   # (copied semantics, tiny)
+└── ps.test.ts                # selection-reconciliation tests (like takeover.test.ts)
+```
+
+Tests live at the package root, plain `node --test --experimental-strip-types`, exactly like
+`extensions/subagents/package.json`'s `test` script. Note the repo-root `package.json` test
+script (`node --test --experimental-strip-types extensions/*/*.test.ts`) will automatically
+pick these up.
+
+## 3. Toolchain (copy exactly, per effect-v4-extension-guide.md §1)
+
+`package.json`:
+
+```jsonc
+{
+  "name": "background-terminals",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "check": "tsc --noEmit -p .",
+    "prepare": "effect-tsgo patch",
+    "test": "node --test --experimental-strip-types manager.test.ts output.test.ts result-delivery.test.ts ps.test.ts"
+  },
+  "dependencies": {
+    "effect": "^4.0.0-beta.99"
+  },
+  "devDependencies": {
+    "@effect/tsgo": "^0.24.2",
+    "typescript": "^7.0.2"
+  }
+}
+```
+
+`tsconfig.json` — identical to `extensions/subagents/tsconfig.json`:
+
+```jsonc
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": { "plugins": [{ "name": "@effect/language-service" }] },
+  "include": ["index.ts", "src/**/*.ts", "*.test.ts"]
+}
+```
+
+Per AGENTS.md: add deps with an install command (`npm install effect@^4.0.0-beta.99`),
+run `npm run check` when done, avoid explicit return types unless needed, no `as any`.
+Verification runs from inside `extensions/background-terminals/` only — never root scripts
+(house rule, effect-v4-extension-guide.md §7/§8).
+
+Note: we do **not** need `@effect/platform-node`. Subagents' codex backend uses raw
+`node:child_process` `spawn` inside Effect and that is the right model here too (§6).
+
+## 4. Domain model (`src/domain.ts`)
+
+Follow `extensions/subagents/src/domain.ts` (readonly interfaces, `Data.TaggedError`, status
+string union, mutable-snapshot-behind-readonly-view trick lives in the manager).
+
+```ts
+import { Data } from "effect";
+
+export type TerminalStatus = "running" | "done" | "failed" | "killed";
+// "done"   = exited with code 0
+// "failed" = exited non-zero, or spawn-level runtime error after start
+// "killed" = terminated by bg_kill, UI kill, or session teardown
+
+export interface TerminalSnapshot {
+  readonly id: string;                 // "bt-1", "bt-2", ... (manager counter, like "sa-N")
+  readonly command: string;            // exactly what the model asked to run (display string)
+  readonly title: string;              // short model-provided name, shown in UI (<=80 chars)
+  readonly cwd: string;                // resolved absolute cwd the process runs in
+  readonly pid?: number;               // undefined only if spawn itself failed
+  readonly status: TerminalStatus;
+  readonly createdAt: number;          // Date.now() at spawn
+  readonly settledAt?: number;         // Date.now() at exit/kill
+  readonly exitCode?: number;          // null-safe: only set when exited via exit code
+  readonly signal?: string;            // e.g. "SIGTERM" when terminated by signal
+  readonly errorText?: string;         // spawn error / kill-escalation notes, bounded
+  // Live output views (see src/output.ts):
+  readonly stdout: OutputView;
+  readonly stderr: OutputView;
+}
+
+export interface OutputView {
+  readonly text: string;               // decoded, possibly head-trimmed text (bounded)
+  readonly totalBytes: number;         // true total bytes ever received
+  readonly truncatedBytes: number;     // bytes dropped from the head (0 = complete)
+  readonly spillPath?: string;         // on-disk full capture, when spilling engaged (§7.6)
+}
+
+export class SpawnError extends Data.TaggedError("SpawnError")<{
+  readonly message: string;
+}> {}
+export class ConcurrencyLimitError extends Data.TaggedError("ConcurrencyLimitError")<{
+  readonly message: string;
+}> {}
+export class UnknownTerminalError extends Data.TaggedError("UnknownTerminalError")<{
+  readonly message: string;
+}> {}
+
+export function formatElapsed(snap: TerminalSnapshot) { /* copy from subagents domain.ts */ }
+```
+
+### State transitions
+
+```
+        spawn ok                     exit code 0
+ (none) ────────► running ───────────────────────► done
+                    │                exit code ≠0 / 'error' event
+                    ├─────────────────────────────► failed
+                    │      bg_kill / UI x / session_shutdown
+                    └─────────────────────────────► killed
+ spawn throws (ENOENT etc.) → tool call fails; NO entry is tracked (SpawnError to the model)
+```
+
+Terminal states are final; there is no restart (unlike subagents' `send()` restart). A killed
+process that raced an exit event keeps whichever settle landed first — settle must be
+idempotent (`if (s.status !== "running") return;`, exactly like `settle()` in
+`extensions/subagents/src/manager.ts`).
+
+Timestamps: `createdAt`/`settledAt` are `Date.now()` millis (matches subagents; `formatElapsed`
+consumes them). Exit status: record **both** `exitCode` (number | undefined) and `signal`
+(string | undefined) from Node's `exit (code, signal)` callback — exactly one is non-null per
+Node semantics; render "exit 0", "exit 137", or "SIGKILL" accordingly.
+
+## 5. Effect architecture (`src/runtime.ts`, `src/manager.ts`)
+
+### 5.1 Runtime boundary
+
+Copy `extensions/subagents/src/runtime.ts` nearly verbatim (it is only 53 lines):
+
+```ts
+import { Cause, Exit, ManagedRuntime, type Effect } from "effect";
+import { TerminalManagerLive } from "./manager.ts";
+
+export function createTerminalRuntime() {
+  return ManagedRuntime.make(TerminalManagerLive);
+}
+export type TerminalRuntime = ReturnType<typeof createTerminalRuntime>;
+
+export async function runTool<A, E>(
+  runtime: TerminalRuntime,
+  effect: Effect.Effect<A, E>,
+  options: { signal?: AbortSignal; interruptMessage?: string } = {},
+) {
+  const exit = await runtime.runPromiseExit(
+    effect,
+    options.signal ? { signal: options.signal } : undefined,
+  );
+  if (Exit.isSuccess(exit)) return exit.value;
+  if (Cause.hasInterruptsOnly(exit.cause)) {
+    throw new Error(options.interruptMessage ?? "Operation was aborted.");
+  }
+  const [first] = Cause.prettyErrors(exit.cause);
+  throw new Error(first?.message ?? Cause.pretty(exit.cause));
+}
+```
+
+No `BackendRegistry` layer is needed — there is exactly one "backend" (node spawn), so
+`AppLayer` is just `TerminalManagerLive`.
+
+`index.ts` builds the runtime lazily and disposes it on `session_shutdown`, exactly like
+`extensions/subagents/index.ts` lines 128–222:
+
+```ts
+let runtime: TerminalRuntime | undefined;
+let managerPromise: Promise<TerminalManagerShape> | undefined;
+const getRuntime = () => (runtime ??= createTerminalRuntime());
+const getManager = () => {
+  managerPromise ??= getRuntime().runPromise(TerminalManager).then((manager) => {
+    manager.view.setOnSettled(onSettled);
+    unsubStatus?.();
+    unsubStatus = manager.view.subscribe(() => updateWidget(manager));
+    updateWidget(manager);
+    return manager;
+  });
+  return managerPromise;
+};
+```
+
+### 5.2 TerminalManager service (`src/manager.ts`)
+
+One `Context.Service` holding a plain `Map<string, Entry>` plus the synchronous read model
+(the exact structure of `SubagentManager` — see `extensions/subagents/src/manager.ts`, which
+is the single most important file to imitate):
+
+```ts
+export interface TerminalManagerShape {
+  start(options: StartOptions): Effect.Effect<TerminalSnapshot, SpawnError | ConcurrencyLimitError>;
+  status(id: string): Effect.Effect<TerminalSnapshot, UnknownTerminalError>;
+  readonly list: Effect.Effect<ReadonlyArray<TerminalSnapshot>>;
+  kill(ids: ReadonlyArray<string>): Effect.Effect<ReadonlyArray<KillResult>>; // resolves when settled
+  readonly disposeAll: Effect.Effect<void>;
+  readonly view: TerminalReadModel;   // synchronous bridge for the TUI + widget
+}
+
+export class TerminalManager extends Context.Service<TerminalManager, TerminalManagerShape>()(
+  "background-terminals/TerminalManager",
+) {}
+
+export const TerminalManagerLive: Layer.Layer<TerminalManager> =
+  Layer.effect(TerminalManager, makeManager);
+```
+
+`makeManager = Effect.gen(function* () { ... })` closes over:
+
+- `const entries = new Map<string, Entry>()` — mutable snapshot per entry (readonly view out).
+- `const listeners = new Set<() => void>()` + `notify()` — any-change subscription for the
+  widget and `/ps` list, with try/catch around each UI listener.
+- One `Deferred<void>` per entry, completed synchronously and exactly once by `settle()`.
+  Every `kill()` caller awaits the Deferreds for entries that were running when it began.
+- A scoped `FiberSet.runtime` bridge for fire-and-forget UI kills, process-event settlement,
+  and pruning. Completed fibers remove themselves; disposal waits for the set within a bound,
+  and scope close interrupts cleanup still live after that bound.
+- `let counter = 0` for ids; `let disposed = false`; `waitInterest` is NOT needed (there is no
+  `bg_wait` tool in v1 — see §8 note), but the "consumed" concept still applies to `bg_kill`
+  and `bg_status` so a settle isn't double-announced (§9.3).
+- `yield* Effect.addFinalizer(() => disposeAll)` — the safety net so `runtime.dispose()` in
+  `session_shutdown` kills every process even if the extension forgot (subagents manager.ts
+  line 657).
+
+Concurrency cap: subagents caps at `MAX_RUNNING = 4` with a synchronous reservation
+(`Effect.suspend` before the first yield so parallel tool calls cannot race the check —
+manager.ts lines 364–383). For terminals use `MAX_RUNNING = 8` (processes are cheaper than
+agents) and the same reservation pattern; and `MAX_TRACKED = 32` completed entries retained,
+pruned oldest-settled-first exactly like `pruneSettled()` (never prune running entries).
+
+### 5.3 Where Effect fibers/queues/etc. do and don't earn their keep
+
+Per effect-v4-extension-guide.md §0 the async core is Effect; per the codex backend precedent
+the Node stream plumbing stays plain callbacks. Concretely:
+
+- **Yes Effect:** the manager service/layer, `start` reservation, per-entry `Deferred`,
+  `kill` (timeout + escalation + Deferred wait), scoped `FiberSet` cleanup, `disposeAll`
+  (parallel bounded teardown), `runTool` boundary, and `Effect.addFinalizer`.
+- **Plain TS callbacks:** `child.stdout.on("data")`, `child.on("exit")` handlers mutate the
+  entry snapshot and call `notify()` directly. This is exactly what the codex backend does with
+  its JSON-RPC stdout pump (`codex.ts` lines ~820–860). Do NOT build a
+  `Queue<SubagentEvent>`/pump-fiber pipeline here — subagents needs that because three
+  heterogeneous backends normalize into one event stream; a single spawn does not.
+
+## 6. Node child_process design (the core of `start`)
+
+Model on `makeCodexSession` in `extensions/subagents/src/backends/codex.ts` (spawn options,
+kill-tree, terminate-with-escalation), minus the JSON-RPC machinery:
+
+```ts
+import { spawn } from "node:child_process";
+
+const child = yield* Effect.try({
+  try: () =>
+    spawn(shellPath, ["-c", options.command], {
+      cwd: options.cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],       // ← stdin IGNORED: no input surface, ever
+      detached: process.platform !== "win32",  // own process group on POSIX → group kill
+    }),
+  catch: (error) => new SpawnError({ message: boundedError(error) }),
+});
+```
+
+Decisions and rationale:
+
+- **Shell execution.** The model supplies one `command` string; run it through the platform
+  shell (`/bin/sh -c` on POSIX, `cmd.exe /d /s /c` on Windows) so pipes/redirection work. Honor the
+  user's configured shell if convenient (`~/.pi/agent/settings.json` has
+  `"shellPath": ".../zsh-with-rc"`), but `/bin/sh` is an acceptable v1 — document which you
+  pick in the tool description. Never `shell: true` with an args array (double-parse trap).
+- **`stdin: "ignore"`** enforces the "no subsequent input" requirement at the OS level. A
+  process that tries to read stdin gets EOF immediately, which is the honest contract (and the
+  tool description must say so — interactive commands will exit or hang, and `bg_kill` is the
+  remedy).
+- **`detached: true` on POSIX** gives the child its own process group, so kill can signal
+  `-pid` and take down the whole tree (grandchildren from `npm run dev` etc.). `killTree`
+  keeps the direct-signal fallback when the group is gone; Windows uses `taskkill /T` and
+  adds `/F` for the force-kill phase. `terminateChild` uses Effect
+  callbacks/timeouts: SIGTERM now, SIGKILL after 2s if needed, then a final 500ms bound.
+  Do NOT call `child.unref()` — we want the exit event, and pi owns the lifetime anyway.
+- **Spawn failure semantics.** `spawn()` itself rarely throws; ENOENT arrives via
+  `child.once("error", ...)`. Wire the error handler *before* returning from `start`, and treat
+  an error event pre-exit as settling the entry to `failed` with `errorText` (mirror
+  `failForProcessExit` in codex.ts). To catch instant failures, you may optionally wait one
+  tick for `spawn` event vs `error` event, but simplest correct behavior: register the entry
+  immediately as `running` and let the near-instant `error`/`exit` settle it; the model gets
+  the settle notification milliseconds later.
+- **Exit handling** (single source of truth for settling):
+
+```ts
+child.once("exit", (code, signal) => {
+  finishOutput(entry);       // flush any pending partial decode
+  settle(entry, {
+    status: entry.killSignaled ? "killed" : code === 0 ? "done" : "failed",
+    exitCode: code ?? undefined,
+    signal: signal ?? undefined,
+  });
+});
+```
+
+  `killSignaled` is set in the same synchronous effect that sends SIGTERM, so a process that
+  exits before signaling keeps its natural status while a signaled process reports `killed`.
+  Settle is idempotent (§4).
+- **cwd semantics.** The tool takes optional `working_dir`; resolve with
+  `path.resolve(ctx.cwd, params.working_dir ?? ".")` and validate
+  `fs.existsSync(cwd) && fs.statSync(cwd).isDirectory()` in the tool handler *before* touching
+  the runtime — throw a plain Error otherwise. This is copied from `subagent_spawn`'s handler
+  (`extensions/subagents/index.ts` lines 262–265). No trust-store logic is needed (we are not
+  spawning an agent in another project; a shell command in another directory is equivalent to
+  what the bash tool already allows).
+
+### 6.1 Why not `effect/unstable/process` yet?
+
+`ChildProcess.make` + `ChildProcessHandle` is the eventual target, but the current Effect beta
+cannot preserve the current process contract yet:
+
+1. `forceKillAfter` does not correctly wait before SIGKILL on POSIX in this pin.
+2. `ChildProcessHandle.exitCode` does not expose the actual terminating signal, while the
+   public snapshot and model-facing output distinguish `SIGTERM` from `SIGKILL`.
+
+This first pass therefore keeps raw spawn and stream callbacks, while moving termination
+waits, escalation deadlines, settlement coordination, and cleanup ownership into Effect.
+Do not add `@effect/platform-node` until both blockers can be resolved.
+
+## 7. Output capture (`src/output.ts`)
+
+### 7.1 Requirements recap
+
+Capture stdout and stderr **separately** and **completely** (the user's "full stdout/stderr"),
+viewable in `/ps`; tool responses truncated; memory must be bounded.
+
+### 7.2 Decoding — do it right
+
+Do NOT use `child.stdout.setEncoding("utf8")` naïvely-per-chunk... actually `setEncoding`
+internally uses a StringDecoder and *is* multibyte-safe across chunk boundaries, which is why
+codex.ts can use it. Two acceptable options; pick (a):
+
+- (a) `child.stdout.setEncoding("utf8")` and receive `string` chunks (Node handles split
+  UTF-8 sequences). Simplest, matches codex.ts line ~824.
+- (b) accumulate `Buffer`s and decode with `new (await import("node:string_decoder")).StringDecoder("utf8")`.
+
+Either way, strip nothing at capture time — raw text goes into the buffer; ANSI/control
+sanitization happens at *render* time using `sanitizeText` (copy from
+`extensions/subagents/src/ui/transcript.ts` lines 15–29; it exists precisely because raw ANSI
+desyncs the TUI renderer).
+
+### 7.3 OutputBuffer (bounded ring with head-drop + optional spill)
+
+```ts
+export class OutputBuffer {
+  private chunks: string[] = [];
+  private bytes = 0;            // bytes currently retained (Buffer.byteLength of chunks)
+  totalBytes = 0;               // true total ever received
+  truncatedBytes = 0;           // dropped from the head
+  spillPath?: string;
+
+  constructor(private maxRetainedBytes: number, private spill?: (chunk: string) => void) {}
+
+  push(chunk: string) {
+    /* Count and spill the complete chunk first. If the chunk alone exceeds
+       maxRetainedBytes, discard older retained chunks and UTF-8-safely trim
+       this chunk to its newest cap-sized tail. Otherwise append it and evict
+       older whole chunks until retained bytes fit. Every discarded byte
+       increments truncatedBytes; totalBytes counts the original input. */
+  }
+  view(): OutputView { /* { text: this.chunks.join(""), totalBytes, truncatedBytes, spillPath } */ }
+}
+```
+
+Cache the `join("")` and invalidate on push so the 1Hz UI tick doesn't re-join megabytes.
+
+### 7.4 Memory bounds vs "full inspection" — the honest tradeoff
+
+Unbounded retention of a `yes`-style firehose is a hard memory leak (codex.ts caps its stderr
+retain at 4 KiB and treats an unbounded protocol buffer as session-fatal for exactly this
+reason). Resolution:
+
+- **In-memory retained cap: 2 MiB per stream per process** (so ≤ 8 procs × 2 streams × 2 MiB =
+  32 MiB worst case). The newest output is always retained; the head is dropped.
+- **Spill-to-disk for the full capture** (this is what makes "full stdout/stderr" true even
+  past the cap): create the shared/session directories with owner-only `0700` permissions,
+  then open two `0600` append-mode `WriteStream`s under
+  ``path.join(os.tmpdir(), "pi-background-terminals", sessionId, `${id}.stdout.log`)`` (and
+  `.stderr.log`). A `WriteStream` serializes writes per stream; settlement ends and awaits
+  both streams behind a bounded flush barrier before publishing the result. A stream error or
+  flush timeout clears the affected full-log pointer and surfaces a bounded `errorText` note.
+  The `/ps` detail view shows the in-memory tail and, when `truncatedBytes > 0`, a header line
+  "first N KiB dropped from view — full log: <spillPath>"; model-facing results reference the
+  same path. `disposeAll` removes the private session spill directory after all entry scopes
+  and spill flushes complete, so secret-bearing logs do not outlive the owning pi session.
+- Precedent for "truncate + point at the full file": docs/extensions.md "Output Truncation"
+  section recommends exactly this shape for tool results.
+
+### 7.5 Entry wiring inside `start`
+
+Per entry, like subagents' `spawn` (manager.ts lines 385–466):
+
+```ts
+const scope = yield* Scope.make();
+const settled = yield* Deferred.make<void>();
+// finalizer kills the tree; registered in the scope so BOTH kill() and disposeAll()
+// and runtime.dispose() converge on one teardown path:
+yield* Scope.provide(
+  Effect.addFinalizer(() =>
+    Effect.gen(function* () {
+      yield* terminateChild(child, () => entry.stdioClosed, markKillSignaled);
+      yield* Deferred.await(settled).pipe(
+        Effect.timeout(SETTLE_GRACE_MS),
+        Effect.ignore,
+      );
+      // If still running, flush output within its bound and settle here.
+    }),
+  ),
+  scope,
+);
+entries.set(id, { snapshot, child, scope, stdoutBuf, stderrBuf, settled });
+```
+
+`kill(ids)` then is: `Scope.close(entry.scope, Exit.void)` (bounded with
+`Effect.timeout(STOP_TIMEOUT_MS)` + `Effect.ignore`) in the scoped cleanup `FiberSet`, then
+await every captured entry's `Deferred`. Return per-id `{ id, status, killed: boolean }`
+results and treat already-settled ids as no-ops rather than errors.
+
+`disposeAll`: set `disposed = true`, snapshot `[...entries.values()]`, close every scope with
+`{ concurrency: "unbounded" }` and a 5s timeout each — verbatim subagents `disposeAll`
+(manager.ts lines 596–618).
+
+### 7.6 Race conditions checklist (each has a subagents precedent)
+
+- **Spawn vs concurrent spawn past the cap** → synchronous reservation before first yield
+  (`reserved++` inside `Effect.suspend`; decrement in `Effect.ensuring`).
+- **Kill vs natural exit** → idempotent `settle` with one authoritative precedence rule. If
+  kill reaches a live shell, set `killSignaled` in the same effect that signals it and report
+  `killed`. If the shell's `exit` event was already observed, preserve its natural
+  `done`/`failed` status even when cleanup must still signal descendants holding stdio open.
+  A missing `close` after `exit` starts a bounded grace, then closes the entry scope so the
+  surviving process group is terminated and the entry cannot occupy a running slot forever.
+- **Exit event vs scope close ("stream ended unexpectedly")** → we have no pump, so this class
+  disappears; the only settle source is the `exit`/`error` listener.
+- **Settle during teardown** → `if (!disposed) onSettled?.(...)` so a result is never queued
+  into a shutting-down session (subagents `settle`, manager.ts line 280).
+- **Tool AbortSignal during `bg_kill`'s wait** → interruption stops only that caller's
+  `Deferred.await`; the detached scope-close stays owned by the manager `FiberSet`, and
+  `Effect.ensuring` still releases bookkeeping.
+- **Late output after exit** → Node may still flush 'data' after 'exit' is observed in rare
+  orderings; buffers accept pushes until `close` — harmless because settle doesn't freeze the
+  buffer, and the UI just shows more text. (Optionally listen on `close` instead of `exit` to
+  be strictly after stdio flush; `close` fires when stdio streams end — prefer `close` for
+  settling to guarantee complete output at notification time, and keep `exit` only to record
+  code/signal. This is the one place we improve on codex.ts, which doesn't need output
+  completeness.)
+
+**Recommended:** record `{code, signal}` on `exit`, settle + notify on `close`. This
+guarantees the completion follow-up message contains the final output tail.
+
+## 8. Tools (`index.ts` + `src/prompt.ts`)
+
+All model-facing strings live in `src/prompt.ts` (subagents convention). Register with
+`pi.registerTool`; parameters via `typebox` `Type.Object`; use `StringEnum` from
+`@earendil-works/pi-ai` if any enum appears (Google-compat rule, docs/extensions.md
+"Tool Definition"). Throw plain `Error` for failures (that is what sets `isError`).
+
+### 8.1 `bg_start`
+
+```ts
+parameters: Type.Object({
+  command: Type.String({ description: "Shell command line to run in the background (sh -c on POSIX, cmd.exe /d /s /c on Windows). It receives no stdin (EOF immediately); interactive commands will not work." }),
+  title: Type.String({ description: "Short human-readable name shown in listings and the UI" }),
+  working_dir: Type.Optional(Type.String({ description: "Working directory (default: current working directory)" })),
+})
+```
+
+Handler: validate cwd (§6), `title.trim().slice(0, 80) || "terminal"`, then
+`runTool(getRuntime(), manager.start({ command, title, cwd }))`. Result text (build in
+prompt.ts, like `buildSubagentSpawnResult`):
+
+```
+Started background terminal bt-3 "dev server" (pid 12345, /Users/davis/project).
+It runs in the background with no stdin. You'll get a message when it exits, or use
+bg_status(id: "bt-3") to peek, bg_kill to stop it, bg_list to see all.
+```
+
+`promptSnippet`: "Run a long-lived shell command in the background (dev servers, builds,
+watchers); output is captured and you're notified on exit".
+`promptGuidelines` (name the tool explicitly — docs warn "this tool" is ambiguous):
+- "Use bg_start for commands expected to run long or indefinitely (servers, watch modes); use the regular bash tool for quick commands."
+- "bg_start processes receive no stdin — never start a command that requires interactive input."
+- "After bg_start, keep working; the exit result arrives automatically. Use bg_status only when you need current output before continuing."
+
+Description documents the truncation limits (docs requirement) and the no-stdin contract.
+
+### 8.2 `bg_status`
+
+```ts
+parameters: Type.Object({ id: Type.String({ description: 'Terminal id, e.g. "bt-1"' }) })
+```
+
+Unknown id → throw with the known-ids list (copy the exact error style from `subagent_check`:
+`Unknown terminal id "x". Known: bt-1, bt-2.`). Result: one metadata line
+(`bt-1 [running] "dev server" (pid 12345, 3m12s, exit -, /path)`) then **tail-truncated**
+stdout and stderr sections:
+
+```ts
+const stdout = truncateTail(snap.stdout.text, { maxBytes: 16 * 1024, maxLines: 400 });
+const stderr = truncateTail(snap.stderr.text, { maxBytes: 8 * 1024, maxLines: 200 });
+```
+
+`truncateTail` (not head) because for process logs the end matters — this is the documented
+guidance in docs/extensions.md Output Truncation. When truncated, append
+`[stdout truncated: showing last X of Y. Full log: <spillPath or "in /ps viewer">]` using
+`formatSize` + the truncation result fields (see `truncatedOutput()` in subagents index.ts for
+the message shape). If `bg_status` observes a settled entry whose completion message is still
+pending delivery, mark it consumed (§9.3).
+
+### 8.3 `bg_list`
+
+No parameters. One line per entry via a `describeTerminal(snap)` helper (mirror
+`describeSubagent`): id, status, title, pid, elapsed, exit code/signal, cwd, and total output
+sizes (`formatSize(stdout.totalBytes)`). "No background terminals." when empty. Include both
+running and completed (completed entries are retained up to `MAX_TRACKED`).
+
+### 8.4 `bg_kill`
+
+```ts
+parameters: Type.Object({ ids: Type.Array(Type.String(), { description: 'Terminal ids to stop, e.g. ["bt-1"]' }) })
+```
+
+Validate all ids known first (throw listing unknowns, copy `subagent_cancel`). Then
+`runTool(getRuntime(), manager.kill(ids), { signal, interruptMessage: "Kill wait aborted; termination continues in the background." })`.
+Report per id: `Killed bt-1 "dev server" (SIGTERM).` or `bt-2 "build" was already done (exit 0).`
+Killing marks the settle consumed so the model doesn't also get the async completion message
+(§9.3) — same reason subagents' `cancel` calls `addInterest` before interrupting.
+
+**No `bg_wait` and no `bg_send`.** No stdin is a hard requirement. Blocking wait is
+deliberately omitted in v1: completion notification makes it redundant, and it would drag in
+subagents' full `waitInterest` machinery. If it's ever wanted, each entry already has a
+settlement `Deferred` and the subagents `waitFor` result shaping is the template.
+
+## 9. Completion notification — exactly once, no polling, no turn races
+
+This is the subtlest requirement. Copy the subagents solution wholesale; it exists precisely
+to solve this problem (see comments in `extensions/subagents/index.ts` lines 168–222 and
+`result-delivery.ts`).
+
+### 9.1 Mechanism
+
+On settle, the manager invokes a hook `onSettled(snap, consumed)` registered by `index.ts`
+(same `view.setOnSettled` bridge). The hook:
+
+```ts
+const resultDelivery = createDeferredResultDelivery<TerminalSnapshot>();  // copy the 20-line module
+
+const onSettled = (snap: TerminalSnapshot, consumed: boolean) => {
+  if (consumed) { resultDelivery.consume([snap.id]); return; }
+  // Defer a deep-enough copy: the live snapshot keeps mutating (late output flushes).
+  resultDelivery.defer({ ...snap, stdout: { ...snap.stdout }, stderr: { ...snap.stderr } });
+  if (sessionContext?.isIdle()) flushResults();
+};
+
+pi.on("agent_settled", flushResults);
+
+const flushResults = () => {
+  for (const snap of resultDelivery.drain()) {
+    pi.sendMessage({
+      customType: "background-terminal-result",
+      content: buildTerminalResultMessage(snap),   // prompt.ts; truncateTail'd output inside
+      display: true,
+      details: { id: snap.id, title: snap.title, status: snap.status, exitCode: snap.exitCode, signal: snap.signal },
+    }, { deliverAs: "followUp", triggerTurn: true });
+  }
+};
+```
+
+### 9.2 Why this is race-free (the reasoning to preserve in code comments)
+
+- `deliverAs: "followUp"` queues the message until the agent has no more tool calls; it never
+  interrupts a mid-turn stream (docs/extensions.md § pi.sendMessage).
+- `triggerTurn: true` wakes the model immediately **iff idle**; if busy, the queued follow-up
+  is delivered when the current run settles — either way exactly one delivery.
+- The `Map`-keyed `resultDelivery` (keyed by id, `drain()` clears) makes double-delivery
+  structurally impossible even if both the `isIdle()` fast-path and the `agent_settled` event
+  fire: whoever drains first wins, the second drain sees an empty map.
+- The `consumed` flag closes the remaining hole: if the model is *currently inside*
+  `bg_kill` (which returns the final state itself), the settle must not ALSO queue a message.
+  Manager computes `consumed` = "a kill/status collection is in flight for this id" at settle
+  time (subagents: `waitInterest`; here: the `kill()`-marked id set).
+- `if (!disposed)` in `settle` prevents queueing into a shutting-down session.
+
+### 9.3 Consumed-set details
+
+Keep a `Map<string, number> killInterest` in the manager; `kill()` adds interest before
+signaling and releases in `Effect.ensuring` (identical to `addInterest`/`releaseInterest`).
+`settle` computes `consumed = (killInterest.get(id) ?? 0) > 0`. Additionally, `bg_kill`'s tool
+handler calls `resultDelivery.consume(ids)` after `runTool` returns, mirroring
+`subagent_wait`'s "settlement may have happened before this wait began" comment (index.ts
+line 352) — belt and suspenders for the settled-before-kill-started ordering.
+
+### 9.4 Result message content
+
+`buildTerminalResultMessage` (prompt.ts): first line
+`Background terminal bt-3 "dev server" exited (exit 1) after 4m12s.` (or `(SIGTERM)` /
+`was killed`), then tail-truncated stdout (≤ 16 KiB) and, if non-empty, stderr (≤ 8 KiB) in
+labeled sections, with truncation notes pointing at the spill file. Register a
+`pi.registerMessageRenderer("background-terminal-result", ...)` for a collapsed preview —
+copy the subagent-result renderer (index.ts lines 514–561: icon by status, header line,
+8-line preview, "ctrl+o to expand").
+
+## 10. Widget above the editor
+
+Requirement: visible **only while ≥1 process is running**, directly above editor, text
+`N background terminal(s) running • /ps to view`.
+
+API: `ctx.ui.setWidget(key, linesOrFactory)` — default placement is already **above the
+editor** (docs/extensions.md "Widgets, Status, and Footer" + tui.md Pattern 5); do NOT pass
+`placement: "belowEditor"`. Clear with `setWidget(key, undefined)`.
+
+```ts
+const updateWidget = (manager: TerminalManagerShape) => {
+  if (!ui) return;                               // captured from session_start ctx.hasUI
+  const running = manager.view.list().filter((s) => s.status === "running").length;
+  if (running === 0) { ui.setWidget("background-terminals", undefined); return; }
+  ui.setWidget("background-terminals", (_tui, theme) => {
+    const line =
+      theme.fg("warning", "■ ") +
+      theme.fg("text", `${running} background terminal${running === 1 ? "" : "s"} running`) +
+      theme.fg("dim", " • ") + theme.fg("accent", "/ps") + theme.fg("dim", " to view");
+    return { render: () => [line], invalidate: () => {} };
+  });
+};
+```
+
+Drive it from `manager.view.subscribe(...)` exactly like subagents drives `setStatus`
+(index.ts lines 139–166) — the subscription fires on every state change, including settles, so
+the widget disappears the moment the last process exits. Guard `ctx.hasUI`; wrap in try/catch
+like workflows' `updateIndicator` ("UI may be unavailable"). Clear the widget in
+`session_shutdown` before disposing the runtime.
+
+(Singular/plural: render `1 background terminal running`, `2 background terminals running` —
+implement the requested "terminal(s)" sense as proper pluralization.)
+
+## 11. `/ps` command + two-stage UI (`src/ui/ps.ts`, `src/ui/output-view.ts`)
+
+Register `pi.registerCommand("ps", { description: "List and inspect background terminals", handler })`.
+Handler: TUI-mode guard + empty-state notify + open picker — copy the `/subagents` command
+skeleton (index.ts lines 565–587). Non-TUI (`ctx.mode !== "tui"`): print a plain-text listing
+via `ctx.ui.notify` like workflows' non-TUI fallback, or just the notify error like subagents —
+prefer the listing (cheap and useful in RPC mode).
+
+### 11.1 Stage 1 — list (dashboard)
+
+Copy `SubagentDashboard` (`src/ui/takeover.ts` lines 109–344) with terminal rows:
+
+- Entry point loop `openTerminalPicker(ctx, view)` — the `while (true)` pick→detail→back loop
+  of `openSubagentPicker` (lines 52–86), full-screen overlay
+  (`{ overlay: true, overlayOptions: { anchor: "center", width: "100%", maxHeight: "100%" } }`).
+- Row left: selection marker, status glyph (`■` warning/success/error — reuse `statusGlyph`
+  pattern; map `killed` to muted/error), title, dim id.
+- Row right: `pid 12345 · 3m12s · exit 0` (or `running` / `SIGTERM`), dim separators — the
+  `split(left, right, width)` helper from workflows' dashboard is the cleanest to copy.
+- Keys: up/down/j/k select, enter open, `x` kill selected (only when running →
+  `view.requestKill(id)` fire-and-forget, precedent: dashboard `x` → `requestAbort`), esc
+  close. Hint line built from `keybindings.getKeys(...)` via the `configuredKeys` helper.
+- 1Hz `setInterval` ticker for elapsed times + `view.subscribe` re-render, both cleaned up in
+  `dispose()`/`cleanup()` (idempotent closed-flag pattern — copy it exactly; overlay components
+  are disposed on close and must not be reused, tui.md "Overlay Lifecycle").
+- Keep list selection stable across refreshes with `reconcileDashboardSelection` (takeover.ts
+  lines 95–107) — copy it and its test (`takeover.test.ts`).
+
+### 11.2 Stage 2 — detail (read-only inspector)
+
+Copy `TakeoverView` (takeover.ts lines 350–563) **minus the Input line** (read-only: no
+`Focusable`, no `Input`, no `requestSend`). Layout:
+
+```
+────────────────────────────────────────────────────────────
+■ bt-3 · dev server · running · 4m12s · pid 12345 · ~/project
+$ npm run dev
+────────────────────────────────────────────────────────────
+[ tab: stdout (1.2MB) | stderr (4KB) ]        ← `t` toggles streams
+  ...scrollable output lines (sanitized, wrapped, tail-pinned)...
+  ... 120 lines below · ↓/pgdn
+────────────────────────────────────────────────────────────
+esc back · t stdout/stderr · x kill · ↑/↓ scroll · pgup/pgdn page · g/G top/bottom
+────────────────────────────────────────────────────────────
+```
+
+- Metadata header: status glyph, id, title, status word, elapsed (`formatElapsed`), pid, cwd,
+  exit code/signal when settled, total sizes (`formatSize`), truncation note when
+  `truncatedBytes > 0` (with spill path).
+- **stdout/stderr shown separately** (requirement): a `t` key toggles the active stream;
+  header tab shows both sizes. (Alternative side-by-side split like workflows' phases/agents
+  panels is more code for less readability of wide log lines — use the toggle.)
+- Output rendering (`src/ui/output-view.ts`): split buffer text on `\n`, `sanitizeText` each
+  line (copy from transcript.ts — ANSI strip is mandatory or the overlay smears), wrap with
+  `wrapTextWithAnsi`, `truncateToWidth`. Scroll state = offset-from-bottom, 0 = pinned to
+  bottom so a running process live-tails; clamp `scrollOffset` to `maxOffset` each render
+  (TakeoverView lines 510–543 is exactly this fixed-height-viewport math — copy it, including
+  the "scroll status consumes a viewport row" trick so height never jumps).
+- Live updates: `view.subscribeTo(id, ...)` per-entry subscription + the 50ms
+  `scheduleRender` debounce (TakeoverView lines 406–414 — a chatty process emits a chunk per
+  write; do not repaint per chunk).
+- Keys: esc/left back to list (loop re-opens dashboard), `x` kill (running only), scroll keys
+  via `keybindings.matches(data, "tui.editor.cursorUp"/"cursorDown"/"pageUp"/"pageDown")` plus
+  j/k and g/G (workflows transcript view precedent).
+- Big-buffer perf: with the 2 MiB cap, worst case ~30k lines; recompute wrapped lines only when
+  the buffer version or width changed (cache `(version, width) → lines`), not per render tick.
+
+### 11.3 Read model
+
+```ts
+export interface TerminalReadModel {
+  list(): ReadonlyArray<TerminalSnapshot>;
+  get(id: string): TerminalSnapshot | undefined;
+  size(): number;
+  subscribe(listener: () => void): () => void;
+  subscribeTo(id: string, listener: () => void): () => void;
+  requestKill(id: string): void;   // fire-and-forget via the scoped FiberSet runtime
+  setOnSettled(hook?: (snap: TerminalSnapshot, consumed: boolean) => void): void;
+}
+```
+
+Verbatim shape of `SubagentReadModel` minus `requestSend`. Snapshots are live objects; the UI
+must not mutate them (same doc comment as manager.ts line 89).
+
+## 12. Lifecycle: reload / new / resume / fork / shutdown
+
+pi's session replacement flow (docs/extensions.md "Lifecycle Overview" + session_shutdown):
+`/new`, `/resume`, `/fork`, `/reload`, and quit all emit `session_shutdown` (with `event.reason`)
+for the old extension instance, then re-instantiate extensions and emit `session_start`.
+Consequences:
+
+- **Processes do not survive any session transition.** In `session_shutdown`: clear
+  `resultDelivery`, unsubscribe, clear widget, null the ui/context refs, then
+  `await closing?.dispose()` — the ManagedRuntime close runs the manager finalizer →
+  `disposeAll` → every entry scope → `terminateChild` (SIGTERM→SIGKILL tree kill). This is
+  the identical teardown in subagents index.ts lines 210–222; each scope close is bounded
+  (5s timeout) so a wedged process cannot hang shutdown, and SIGKILL covers it anyway.
+- **Spill files do not survive the session either.** `disposeAll` first closes every entry
+  scope and awaits bounded spill flushes, then recursively removes its owner-only session
+  directory. Paths shown in the old transcript are intentionally session-lifetime pointers.
+- **No persistence / no resurrection.** Unlike workflows (which persists `workflow.json` and
+  marks stale "running" runs as aborted on reload — dashboard.ts lines 286–297), v1 keeps no
+  cross-session record: killed-on-shutdown processes simply disappear. Optionally append a
+  `pi.appendEntry("background-terminals-note", {...})` breadcrumb ("bt-2 'dev server' was
+  killed by session shutdown") so a resumed session's transcript explains the vanished
+  terminal — cheap and worth doing; entries don't enter LLM context (docs: appendEntry).
+  The model-facing story stays consistent because tool results always describe terminals as
+  session-scoped ("killed when the session ends" in `bg_start`'s description).
+- **Do not spawn from stale contexts.** All spawning goes through tool handlers with a live
+  `ctx`; the manager rejects `start` when `disposed` (SpawnError "shutting down", subagents
+  manager.ts lines 370–374 precedent).
+- **Fork/clone:** nothing special — same shutdown+start pair; the new instance starts empty.
+
+## 13. Truncation constants (single place, `index.ts` top)
+
+```ts
+const STATUS_STDOUT_MAX = 16 * 1024;   // bg_status stdout tail
+const STATUS_STDERR_MAX = 8 * 1024;    // bg_status stderr tail
+const RESULT_STDOUT_MAX = 16 * 1024;   // completion follow-up stdout tail
+const RESULT_STDERR_MAX = 8 * 1024;
+const RETAINED_PER_STREAM = 2 * 1024 * 1024;  // in-memory cap per stream (spill keeps the rest)
+```
+
+All clamped by `Math.min(..., DEFAULT_MAX_BYTES)` and `DEFAULT_MAX_LINES` (imports from
+`@earendil-works/pi-coding-agent`, verified exported in `dist/index.d.ts`) — same defensive
+clamp as `truncatedOutput` in subagents index.ts. Always `truncateTail` for process output.
+
+## 14. Test plan
+
+Follow the house style: `node:test` + `assert/strict`, end-to-end through a real
+`ManagedRuntime`, minimal count, deterministic (subagents `manager.test.ts` is the template,
+including the `withManager` fixture that guarantees `runtime.dispose()` in `finally`).
+
+**`output.test.ts`** (pure, no processes)
+1. push/view roundtrip; totalBytes/truncatedBytes accounting when the cap evicts head chunks.
+2. multibyte boundary: feeding split UTF-8 via setEncoding path is Node's job, but verify the
+   buffer never splits what it was given and byte counts use `Buffer.byteLength`.
+3. spill callback receives every chunk in order even after eviction.
+
+**`manager.test.ts`** (real processes — use `node -e` one-liners for portability, no shell
+tricks; they exist on any machine running pi)
+1. happy path: `start` node printing to stdout+stderr then exiting 0 → status transitions
+   running→done, exitCode 0, both buffers correct and separate, settle hook fired once with
+   `consumed: false`.
+2. non-zero exit → `failed`, exitCode captured.
+3. `kill` on a `setInterval` never-exiting script → `killed`, signal recorded, `kill()` only
+   resolves after settle; second `kill` of same id reports already-settled, no error.
+4. process-tree termination: spawn a grandchild that updates a unique heartbeat sentinel,
+   kill, then use bounded polling with an explicit timeout to confirm both that the process is
+   gone and that its unique sentinel stopped changing. The sentinel ties the assertion to the
+   spawned child so PID reuse cannot create a false pass.
+5. concurrency cap: cap+1 concurrent starts → last fails with ConcurrencyLimitError;
+   reservation released on spawn failure (start a bogus binary → SpawnError → slot free).
+6. consumed semantics: settle during an in-flight `kill` reports `consumed: true`.
+7. `disposeAll` (via `runtime.dispose()`) kills a running process and settles it as killed;
+   no settle hook fires after dispose (`disposed` guard).
+8. pruning: exceed MAX_TRACKED with settled entries → oldest pruned, running never pruned.
+9. SIGTERM-resistant process → SIGKILL after the 2s grace, within the 5s close bound.
+10. aborted `bg_kill` wait → detached escalation still reaches SIGKILL and settles.
+11. overlapping multi-id kills → every caller observes every captured settlement; each
+    settle hook fires once and consumed state remains true.
+12. shell `exit` without stdio `close` → bounded cleanup reaps the descendant holding the
+    pipes, preserves the shell's natural exit status, and releases the running slot.
+
+**`result-delivery.test.ts`** — consume-before-drain, drain-once (copy subagents' file).
+
+**`ps.test.ts`** — `reconcileTerminalSelection` behavior (copy `takeover.test.ts` cases).
+
+**Manual validation (must actually run pi):**
+- `pi` → ask the model to `bg_start` a dev-server-like command → widget appears above editor
+  with correct count/pluralization → `/ps` list → enter detail → live tail scrolls, `t`
+  toggles stderr, ANSI-heavy output (e.g. `npm run dev`) renders without smearing → back →
+  `x` kills → widget disappears when last settles → completion message arrives exactly once,
+  rendered collapsed, expands with ctrl+o.
+- Race check: start a 2s `sleep`-then-echo while the model is mid-long-turn → result arrives
+  as follow-up after the turn, not mid-stream, and only once.
+- `/new` and `/reload` with a running process → process is dead afterwards (`ps aux | grep`),
+  no orphan, widget cleared.
+- `npm run check` green; `npm test` green; repo-root `npm run format:check` clean for the new
+  files (prettier covers `extensions/**/*.ts`).
+
+## 15. Pitfalls (each burned someone in the reference code)
+
+1. **Effect v3 API names don't exist** — `Effect.fork`, `Effect.async`, `Either`,
+   `Layer.scoped`, `Context.Tag`. Check every API against effect-v4-notes.md before writing it.
+2. **`Queue.end` needs `Cause.Done` in the error type** — only relevant if you add a queue;
+   this design avoids queues entirely.
+3. **Don't render raw process output** — ANSI/tabs/control chars desync the TUI
+   (transcript.ts's `sanitizeText` comment). Sanitize at render, never at capture.
+4. **Don't repaint per data chunk** — 50ms debounce (TakeoverView) or the UI starves input.
+5. **Overlay components are disposed on close** — never cache and re-show; re-invoke
+   `ctx.ui.custom` (tui.md Overlay Lifecycle). Make `cleanup()` idempotent with a `closed`
+   flag and clear every timer in it.
+6. **`detached` + group kill or you orphan grandchildren** — `sh -c "npm run dev"` without
+   process-group SIGTERM leaves node servers running after pi exits (codex.ts `killTree`
+   comment).
+7. **Settle must be idempotent and single-sourced** — kill vs exit vs error events race;
+   `if (status !== "running") return` in settle. Set `killSignaled` atomically with SIGTERM
+   only while the shell is live; an already-observed natural exit keeps `done`/`failed` even
+   if its surviving process group still needs cleanup.
+8. **Never queue messages into a dying session** — `disposed` guard around `onSettled`, and
+   try/catch around `pi.sendMessage` (workflows wraps its follow-up send in try/catch:
+   "Session may be shutting down").
+9. **Defer a copy, not the live snapshot** — the buffer keeps mutating after settle (late
+   flushes); subagents defers `{ ...snap, meta: { ...snap.meta } }` for the same reason.
+10. **Synchronous reservation for the cap** — an `await` between check and increment lets
+    parallel tool calls race past it (manager.ts spawn comment).
+11. **Bound every teardown wait** — 5s timeout on scope closes, or a wedged child hangs
+    `session_shutdown` (subagents `disposeAll` + `abortEntry` comments).
+12. **Snapshot kill interest before Deferred completion** — Effect can resume kill waiters
+    immediately; compute `consumed` before `Deferred.doneUnsafe` so their `ensuring`
+    blocks cannot release interest first.
+13. **Tool output limits are a hard requirement** — unbounded stdout in a tool result causes
+    context overflow/compaction failures (docs Output Truncation). Truncate *everything* the
+    model sees, including the completion message.
+14. **`prepareArguments` is not needed v1** — but never rename/retype `bg_*` parameters later
+    without adding it (resumed sessions replay old tool calls; docs Tool Definition).
+15. **`hasUI`/`mode` guards** — widget + `/ps` must no-op gracefully in print/RPC modes.
+
+## 16. Acceptance checklist
+
+- [ ] `npm install && npm run check` green in `extensions/background-terminals` (TS7 + Effect LS).
+- [ ] `npm test` green (manager, output, result-delivery, ps selection).
+- [ ] Tools registered: `bg_start`, `bg_status`, `bg_list`, `bg_kill`; descriptions document
+      no-stdin, session-scoped lifetime, and truncation limits; no stdin/steer surface exists.
+- [ ] stdout and stderr captured separately and completely (in-memory tail + spill file);
+      `/ps` detail can inspect both, read-only, scrollable, ANSI-sanitized, live-tailing.
+- [ ] Every model-visible output path truncated (`truncateTail` + clamps) with pointers to the
+      full log.
+- [ ] Exactly-once async completion notification via `sendMessage followUp + triggerTurn`,
+      deferred-delivery map, consumed-set for kill, `agent_settled` flush, `isIdle()` fast
+      path, `disposed` guard. No polling anywhere.
+- [ ] Widget above editor only while ≥1 running, text `N background terminals running • /ps to
+      view`, cleared on last settle and on shutdown.
+- [ ] `/ps` two-stage overlay: list (select/kill/open) → detail (metadata, stdout/stderr
+      toggle, scroll, back), matching subagents/workflows interaction conventions and hint
+      lines from `keybindings.getKeys`.
+- [ ] Kill terminates the whole process tree (SIGTERM → 2s → SIGKILL), records exit
+      code/signal, resolves only after settle.
+- [ ] `session_shutdown` (quit/reload/new/resume/fork) kills all processes within bounded
+      time via `runtime.dispose()`; no orphans; no messages sent during teardown.
+- [ ] Completed entries retained (≤ MAX_TRACKED, pruned oldest-settled) and visible in
+      `bg_list` + `/ps`; running entries never pruned.
+- [ ] Concurrency cap enforced race-free; ids are `bt-N`; cwd resolved against `ctx.cwd` and
+      validated; timestamps and elapsed rendering consistent with subagents.
+- [ ] Code style: model strings in `prompt.ts`, Effect only in the async core, plain TS
+      callbacks for stream plumbing, no `as any`, prettier-clean.