pi-daddy 0.15.0 → 0.16.0

package/src/pane-reaper.ts

@@ -1,9 +1,14 @@
 /**
  * Close herdr panes this process opened but never got to close.
  *
- * `runHerdrPane` closes its pane in a `finally`, which covers a thrown error and a timeout — **not the
- * process being killed**. A pi session interrupted mid-fan-out left one pane per in-flight child, and
- * `docs/probes/g16-herdr` records that an orphaned pane is not trivially closable afterwards.
+ * **As of ADR-0032 a pane belongs to the AGENT RUN, not to the tool call.** `runHerdrPane` closes a tab only for
+ * a child that did *not* settle — closing the tab is the only kill herdr offers, so a child still working must
+ * lose its pane. A child that answered keeps its pane so a human can read it, and this module reaps those: at
+ * `agent_settled` (async) and at process `exit` (sync backstop).
+ *
+ * The gap that remains is the one this module was created for. A pi session **killed outright** runs no `exit`
+ * handler, so it leaves one pane per tracked child, and `docs/probes/g16-herdr` records that an orphaned pane is
+ * not trivially closable afterwards. R-62 was re-rated L×L → M×L when ADR-0031 made panes the default path.
  *
  * **Registered on `exit` only, deliberately — not on SIGINT or SIGTERM.** That is the part worth reading,
  * because the obvious fix is the dangerous one. Adding a signal listener *suppresses Node's default
@@ -24,14 +29,52 @@
 
 import { execFileSync } from "node:child_process";
 import { rmSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { MAX_CHILDREN_PER_CALL } from "./fanout.ts";
+import { defaultExec, parseReply, type HerdrExec } from "./herdr-cli.ts";
+
+/**
+ * How many panes may be open at once — ADR-0032.
+ *
+ * **Derived from `MAX_CHILDREN_PER_CALL` rather than declared, so the two cannot drift.** The bound is not
+ * decoration: `delegate_all` is capped per call and the fan-out budget bounds a subtree, but a plain blocking
+ * `delegate` spends **nothing** from that budget by design — so thirty sequential `delegate` calls in one agent
+ * run would otherwise hold thirty panes open until it settled.
+ */
+export const MAX_OPEN_PANES = MAX_CHILDREN_PER_CALL;
 
 export interface OpenPane {
   /** herdr tab id — what `tab close` takes. */
   tab: string;
-  /** Agent name, so the agent is stopped before its tab goes away. */
+  /** herdr agent name, for diagnostics. There is no `agent stop`, so nothing acts on it — see `closePane`. */
   name: string;
   /** Staged system-prompt directory, removed with the pane it belonged to. */
   promptDir?: string;
+  /**
+   * True once the child has answered and stopped working.
+   *
+   * **The trim may only close a pane with this set**, and that is a correctness rule rather than politeness. pi
+   * executes tool calls in **parallel** by default, and a plain `delegate` spends nothing from the fan-out
+   * budget — so one assistant message can hold `delegate_all(8)` *and* a `delegate`, and the ninth pane's trim
+   * used to close the oldest **live sibling**. Measured: two `delegate_all(8)` in one message killed **8 of 16
+   * children mid-work**, each reported as "could not be started" with its partial output discarded, while the
+   * ledger recorded all sixteen as provisioned. ADR-0032 argued the cap from *sequential* delegates only.
+   */
+  settled?: boolean;
+  /**
+   * The operator asked to keep this tab (`PI_GRANTS_HERDR_KEEP_PANE=1`), so no sweep may close it.
+   *
+   * It is registered anyway, and only for its `promptDir`: that temp dir was otherwise unreachable by either
+   * sweep and leaked one directory per kept pane, forever. So `exit` removes the staged prompt and leaves the
+   * tab, which is exactly what the flag promises.
+   */
+  keepTab?: boolean;
+}
+
+/** A run has finished with its pane: the trim may now reclaim it. */
+export function markPaneSettled(tab: string): void {
+  const pane = open.get(tab);
+  if (pane) pane.settled = true;
 }
 
 /**
@@ -108,25 +151,120 @@ export function reapOpenPanes(syncExec: (args: string[]) => void = defaultSyncEx
     // Panes left behind stay in the map; there is no later sweep, and saying so is the honest position —
     // `openPaneCount()` is non-zero afterwards precisely so a caller could report it if it ever wanted to.
     if (now() >= deadline) break;
-    try {
-      syncExec(["agent", "stop", pane.name]);
-    } catch {
-      /* the agent may already be gone; the tab is what matters */
+    // No `agent stop`: it is not a herdr command (see `closePane`). Closing the tab is the kill.
+    //
+    // A `keepTab` pane is registered only for its staged prompt: remove that and leave the tab alone, which is
+    // the whole of what `PI_GRANTS_HERDR_KEEP_PANE=1` promises.
+    let closedThisPane = pane.keepTab === true;
+    if (pane.keepTab) {
+      if (pane.promptDir) {
+        try {
+          rmSync(pane.promptDir, { recursive: true, force: true });
+        } catch {
+          /* /tmp litter, not correctness */
+        }
+      }
+      open.delete(pane.tab);
+      continue;
     }
     try {
       syncExec(["tab", "close", pane.tab]);
       closed.push(pane.tab);
+      closedThisPane = true;
     } catch {
       /* an orphan we could not close: `herdr tab close` is the manual remedy, as documented above */
     }
-    if (pane.promptDir) {
+    // **The staged prompt is deleted only when the tab is provably gone.** It used to be removed
+    // unconditionally, so a pane herdr refused to close lost its `--append-system-prompt` file — and pi treats a
+    // missing path there as **literal text, with no warning** (`resource-loader.js`: `existsSync` fails, the
+    // input is returned). Re-running that pane's echoed argv would hand the child a pathname as its
+    // instructions. Litter is cheaper than silently swapping a definition's body for its filename.
+    if (closedThisPane && pane.promptDir) {
       try {
         rmSync(pane.promptDir, { recursive: true, force: true });
       } catch {
         /* /tmp litter, not correctness */
       }
     }
+    // Untracked either way, and only here: at `exit` there is no later sweep, so keeping an unclosable pane
+    // registered buys nothing. `closePane`'s async path deliberately differs — another sweep may still run.
     open.delete(pane.tab);
   }
   return closed;
 }
+
+/**
+ * Close one tracked pane. Shared by the async sweep and the trim so they cannot disagree about what "closed"
+ * means — which is the whole of R-62's lesson, one layer up.
+ *
+ * Returns whether the tab is **provably** gone. A close herdr refused leaves the pane tracked, so the `exit`
+ * handler retries it; untracking on a failed close is what disabled the one control built for that failure.
+ */
+async function closePane(exec: HerdrExec, pane: OpenPane): Promise<boolean> {
+  // **No `agent stop`.** It is not a herdr command — measured against 0.7.5, where it prints the usage banner
+  // and exits 0, which `defaultExec` reports as success. Two call sites here and one in `run-herdr.ts` issued it
+  // for nothing, and `docs/probes/g16-herdr` asserted it worked from a block that was never run. Closing the tab
+  // is the only kill herdr offers, and it does kill the child.
+  const reply = await exec(["tab", "close", pane.tab]).catch(() => undefined);
+  const closed = reply !== undefined && !parseReply(reply).error;
+  if (!closed) return false;
+  if (pane.promptDir) await rm(pane.promptDir, { recursive: true, force: true }).catch(() => undefined);
+  open.delete(pane.tab);
+  return true;
+}
+
+/**
+ * Close every outstanding pane — the `agent_settled` path (ADR-0032).
+ *
+ * **A separate function from `reapOpenPanes` rather than a shared implementation**, and the reason is not
+ * style. The sync one is `execFileSync` with a six-second total budget *by necessity*: an `exit` handler cannot
+ * await. Running that at `agent_settled` would freeze pi for up to six seconds **every time the operator gets
+ * their prompt back** — turning a feature that exists to make work visible into a stall.
+ *
+ * Both drain the same `Map`, keyed by tab id, so a double close is impossible and a pane herdr refused stays
+ * registered for whichever sweep runs next.
+ *
+ * Sequential rather than concurrent: a fan-out's panes are at most `MAX_OPEN_PANES`, and eight `tab close`
+ * calls in parallel against one herdr server buys nothing worth the burst.
+ */
+export async function reapOpenPanesAsync(exec: HerdrExec = defaultExec): Promise<string[]> {
+  const closed: string[] = [];
+  for (const pane of [...open.values()]) {
+    // `keepTab` panes are registered only so their staged prompt can be reaped at `exit`; the tab itself is the
+    // operator's to close.
+    if (pane.keepTab) continue;
+    if (await closePane(exec, pane)) closed.push(pane.tab);
+  }
+  return closed;
+}
+
+/**
+ * Keep at most `MAX_OPEN_PANES` open, closing the oldest first.
+ *
+ * The `Map`'s insertion order **is** the age order, so no timestamp is needed — and that is why `trackPane`
+ * must never re-`set` an existing tab, which would move it to the back of the queue and make an old pane look
+ * new.
+ *
+ * Whatever it closes is returned so the caller can **say so** rather than silently dropping a pane the operator
+ * was reading (R-48's rule, applied to a display).
+ */
+export async function trimOpenPanes(exec: HerdrExec = defaultExec): Promise<string[]> {
+  if (open.size <= MAX_OPEN_PANES) return [];
+  const closed: string[] = [];
+
+  // **Only SETTLED panes are candidates, oldest first.** A live sibling's pane is its child's only terminal, and
+  // closing a tab kills the child — see `OpenPane.settled`. If every open pane is live the cap is exceeded and
+  // nothing is closed, which is the right failure: a pane too many costs an operator a keystroke, and a killed
+  // child costs them the work.
+  //
+  // **Walks past what it cannot close**, rather than attempting `excess` panes from the front and calling it
+  // done. A pane herdr refuses to close used to sit at the head forever, so the cap silently stopped holding
+  // (measured: 30 panes for 30 delegates when every close was refused) and the same corpse was re-attacked on
+  // every spawn — O(n²) round-trips.
+  for (const pane of [...open.values()]) {
+    if (open.size - closed.length <= MAX_OPEN_PANES) break;
+    if (!pane.settled || pane.keepTab) continue;
+    if (await closePane(exec, pane)) closed.push(pane.tab);
+  }
+  return closed;
+}

package/src/progress.ts

@@ -0,0 +1,206 @@
+/**
+ * The status block a running delegation renders — ADR-0032, in the shape the operator chose on 2026-08-17.
+ *
+ * Three properties are load-bearing rather than cosmetic, and each has a test:
+ *
+ *  - **Bounded height AND bounded width.** Five lines per child — header, up to `TAIL_LINES` of tail, and a
+ *    blank separator — so eight children is at most 42 lines, plus `MAX_LINE_CHARS` per line. The width half was
+ *    missing and the omission mattered: a line cap is what actually bounds the block, because eight children
+ *    each printing one megabyte-long line rendered 25 lines and 8 MiB. "Four lines per child" was also simply
+ *    wrong arithmetic — the separator was never counted.
+ *  - **No braiding.** Each child's text stays under its own header, which is what a chronological stream of two
+ *    concurrent children cannot offer.
+ *  - **The pane id is on screen while the child is alive.** That is the entire difference between a pane you can
+ *    switch to and one you learn about after it closed.
+ *
+ * What it gives up is stated rather than implied (R-48): output older than the last `TAIL_LINES` lines is not
+ * here. It is in the pane while the pane lives, and in the returned result afterwards. **The block is a display
+ * and never the result** — conflating the two is R-03 with a new cause.
+ *
+ * Pure: no pi, no herdr, and no clock. `now` is a parameter so elapsed time is testable.
+ */
+
+/** Lines of context kept per child. Three, because four children of four lines each is already a screenful. */
+export const TAIL_LINES = 3;
+
+/**
+ * Longest a single displayed line may be.
+ *
+ * **The line COUNT cap was never a height cap, and this is what makes the module header's claim true.** A child
+ * printing a minified bundle, a base64 blob or single-line JSON produces one line of megabytes, so
+ * `TAIL_LINES` bounded nothing that matters: eight such children rendered **25 lines and 8 MiB — about 84,000
+ * wrapped rows** — and were repainted every `PAINT_INTERVAL_MS`. Measured. The test asserting "fixed height"
+ * passed throughout, because 25 ≤ 34.
+ *
+ * 200 is a little over two rows on a wide terminal: enough to read a long path or a stack frame, short enough
+ * that eight children cannot flood the screen.
+ */
+export const MAX_LINE_CHARS = 200;
+
+/** Trim one display line to `MAX_LINE_CHARS`, saying so rather than cutting silently (R-48). */
+function clampLine(line: string): string {
+  if (line.length <= MAX_LINE_CHARS) return line;
+  return `${line.slice(0, MAX_LINE_CHARS)}… (+${line.length - MAX_LINE_CHARS} chars)`;
+}
+
+export type ChildState = "starting" | "running" | "completed" | "failed";
+
+/**
+ * The last few lines a child printed, plus whether the final one is still being written.
+ *
+ * **`open` is why this is not a bare `string[]`.** A pipe delivers bytes, not lines, so `Read` and
+ * `ing file.ts` arrive as two chunks and must render as one line — and knowing whether to join or to start a new
+ * line is state that `(lines, chunk)` alone cannot carry. The first draft encoded it as a trailing-space
+ * sentinel inside the array, which worked and was unreadable; a named boolean is the same information without
+ * the puzzle.
+ */
+export interface Tail {
+  lines: string[];
+  /** True when the last element is a partial line awaiting more bytes. */
+  open: boolean;
+}
+
+export const emptyTail: Tail = { lines: [], open: false };
+
+export interface ChildProgress {
+  /** Definition name, or `delegate` for a `tools:` spawn. */
+  label: string;
+  /** herdr agent name, when this child runs in a pane. */
+  agentName?: string;
+  paneId?: string;
+  state: ChildState;
+  startedAt: number;
+  /** Set once terminal, so elapsed time freezes instead of counting forever. */
+  settledAt?: number;
+  tail: Tail;
+}
+
+/**
+ * Collapse a terminal's carriage returns the way a terminal would: what follows the last `\r` wins.
+ *
+ * A spinner writes `working \r working \r done`. Splitting on `\r` as if it were a newline would fill the whole
+ * three-line tail with one frame per tick and push the child's real output out of the block.
+ */
+function lastAfterCarriageReturn(line: string): string {
+  const at = line.lastIndexOf("\r");
+  return at === -1 ? line : line.slice(at + 1);
+}
+
+/**
+ * Fold a raw chunk into a tail.
+ *
+ * Blank lines are dropped so a child printing newlines cannot blank the block — at three lines of context, four
+ * newlines would erase everything the operator was reading.
+ */
+export function appendTail(tail: Tail, chunk: string): Tail {
+  if (chunk.length === 0) return tail;
+
+  const parts = chunk.split("\n");
+  const lines = [...tail.lines];
+
+  // The first part continues the previous line when that line was left open.
+  //
+  // **Clamped on every write, not only at render.** A child that never emits a newline keeps extending one
+  // line, and an unclamped join grew it without bound — measured at 12,692 characters from a pane that never
+  // held more than 16. Clamping here also bounds what is retained, not merely what is shown.
+  if (tail.open && lines.length > 0) {
+    lines[lines.length - 1] = clampLine(lastAfterCarriageReturn(lines[lines.length - 1] + parts[0]));
+  } else if (parts[0].trim().length > 0) {
+    lines.push(clampLine(lastAfterCarriageReturn(parts[0])));
+  }
+
+  for (const part of parts.slice(1)) {
+    if (part.trim().length > 0) lines.push(clampLine(lastAfterCarriageReturn(part)));
+  }
+
+  return { lines: lines.slice(-TAIL_LINES), open: !chunk.endsWith("\n") };
+}
+
+/**
+ * Replace a tail wholesale from a pane SNAPSHOT — the herdr path's counterpart to `appendTail`.
+ *
+ * `agent read` returns a snapshot of a bounded terminal, so the right operation is *replace*, not *append*.
+ * Appending snapshots is what fabricated text the child never printed: a pane whose bottom line was
+ * `working on step 29` followed by a re-report beginning `line30` rendered `working on step 29line30`.
+ * Measured. `open` is always false here, because a snapshot is never mid-line as far as the display is
+ * concerned — there is nothing further to join onto.
+ */
+export function replaceTail(lines: string[]): Tail {
+  return { lines: lines.slice(-TAIL_LINES).map(clampLine), open: false };
+}
+
+/**
+ * A child label is a DIRECTORY name, so it is third-party text on a line this package composes.
+ *
+ * R-77 and R-78 were both "a name from somewhere else reached a generated artefact"; here a newline forges an
+ * entire extra child row in the operator's status block, complete with a plausible agent and pane. Same class,
+ * same treatment as `spawn-summary.ts`'s `safeName`: rendered inert rather than trusted.
+ */
+function safeLabel(label: string): string {
+  return /[\n\r\t]/.test(label) ? JSON.stringify(label) : label;
+}
+
+/** `m:ss`. A delegation is minutes-scale, and an hour-long one has problems this line will not explain. */
+function elapsed(child: ChildProgress, now: number): string {
+  const total = Math.floor(Math.max(0, (child.settledAt ?? now) - child.startedAt) / 1000);
+  return `${Math.floor(total / 60)}:${String(total % 60).padStart(2, "0")}`;
+}
+
+export function renderProgress(children: ChildProgress[], executorKind: "herdr" | "process", now: number): string {
+  const where = executorKind === "herdr" ? "herdr panes" : "captured subprocesses";
+  const lines = [`${children.length} ${children.length === 1 ? "child" : "children"} · ${where}`, ""];
+
+  for (const child of children) {
+    const header = [safeLabel(child.label).padEnd(10)];
+    if (child.agentName) header.push(`agent ${child.agentName}`);
+    if (child.paneId) header.push(`pane ${child.paneId}`);
+    header.push(child.state, elapsed(child, now));
+    lines.push(header.join("   "));
+    // Sliced again here as well as in `appendTail`, so a caller that assembled a `Tail` by hand cannot make the
+    // block unbounded. The height guarantee belongs to the renderer, not to its inputs.
+    // Clamped again here as well as on write, so a caller that assembled a `Tail` by hand cannot make the block
+    // unbounded either. The height guarantee belongs to the renderer, not to its inputs.
+    for (const line of child.tail.lines.slice(-TAIL_LINES)) lines.push(`  ${clampLine(line)}`);
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}
+
+/** How often the block is repainted. A child printing fast must not re-render it hundreds of times a second. */
+export const PAINT_INTERVAL_MS = 250;
+
+/**
+ * Call `fn` at most once per `intervalMs`, and always once more after the last call.
+ *
+ * The trailing call is the point: without it the final frame — the one showing every child settled — is the one
+ * most likely to be dropped, so the block would freeze mid-run and never show completion. `flush` exists so a
+ * caller that knows it is finished can paint immediately rather than waiting out the interval.
+ */
+export function throttle(fn: () => void, intervalMs: number): { call: () => void; flush: () => void } {
+  let last = 0;
+  let timer: NodeJS.Timeout | undefined;
+
+  const run = (at: number) => {
+    last = at;
+    timer = undefined;
+    fn();
+  };
+
+  return {
+    call: () => {
+      const now = Date.now();
+      if (now - last >= intervalMs) return run(now);
+      // Already scheduled: the pending call will render whatever state exists when it fires, which is newer
+      // than this one. Queueing another would only repaint the same thing twice.
+      if (timer) return;
+      timer = setTimeout(() => run(Date.now()), intervalMs - (now - last)).unref?.() as never;
+    },
+    flush: () => {
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+      last = Date.now();
+      fn();
+    },
+  };
+}

package/src/run-child.ts

@@ -10,8 +10,35 @@
  */
 
 import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { parseBound } from "./propagation.ts";
 
+/**
+ * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
+ *
+ * Both halves matter. Truncating by `String.prototype.slice` counts UTF-16 code units against a byte budget,
+ * which overruns by the encoding width of whatever the child printed. Truncating the *buffer* instead would
+ * respect the budget and split a multi-byte character or a surrogate pair, putting a lone `\ud83d` in the
+ * result. So the walk is by code POINT (`for…of` iterates code points, keeping surrogate pairs whole) and the
+ * budget is checked in bytes before each one is admitted.
+ *
+ * Exported for the test that feeds it CJK and emoji: an ASCII-only test cannot fail on any of this, which is
+ * exactly why the original defect survived a test named for it.
+ */
+export function takeBytes(text: string, budget: number): string {
+  if (budget <= 0) return "";
+  if (Buffer.byteLength(text) <= budget) return text;
+  let out = "";
+  let used = 0;
+  for (const character of text) {
+    const size = Buffer.byteLength(character);
+    if (used + size > budget) break;
+    out += character;
+    used += size;
+  }
+  return out;
+}
+
 /**
  * Operator override for the child wall-clock limit, in seconds.
  *
@@ -40,6 +67,20 @@ export interface ChildRunRequest {
   /** Wall-clock cap. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. */
   timeoutMs?: number;
   killGraceMs?: number;
+  /**
+   * Called with each chunk as it arrives, for the parent's progress display (ADR-0032).
+   *
+   * **Display only, and the distinction is load-bearing.** The child's answer is still `text`, assembled here
+   * and returned; a caller must never treat what it saw streamed as the result. A partial stream that could be
+   * mistaken for a complete answer is R-03's defect — a missing result indistinguishable from an empty one —
+   * with a new cause.
+   *
+   * Bounded by the same `maxOutputBytes` as `text`, so the cap governs the transcript and not merely memory.
+   *
+   * Exceptions are swallowed: a renderer is not a governance control, and one that throws must not kill a
+   * governed child mid-task.
+   */
+  onOutput?: (chunk: string) => void;
 }
 
 export interface ChildRunResult {
@@ -85,6 +126,9 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       return;
     }
 
+    // One decoder for BOTH streams is deliberate: they are already interleaved into one `text`, and two
+    // decoders would each hold their own partial character, so a split byte could surface out of order.
+    const decoder = new StringDecoder("utf8");
     let text = "";
     let bytes = 0;
     let truncated = false;
@@ -101,20 +145,65 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       timers.push(setTimeout(() => child.kill("SIGKILL"), killGraceMs));
     };
 
+    /** How much of `text` the progress display has already been shown. */
+    let emittedUpTo = 0;
+
+    /**
+     * Stream whatever `text` has gained since the last call.
+     *
+     * **Derived from `text` rather than from the incoming chunk**, and that is the whole correctness argument:
+     * what gets streamed is then *by construction* a prefix of what gets returned, so the output cap bounds the
+     * parent's transcript exactly as it bounds the result. The first version emitted the raw chunk and pushed
+     * 1924 bytes through a 1024-byte cap on the truncating write — the cap bounded memory and not the screen
+     * it had just been extended to protect. Found by the test, not by reading it.
+     *
+     * Swallowing is deliberate: `onOutput` renders, and a renderer that throws must not become a way to kill a
+     * governed child. Nothing downstream depends on it having run.
+     */
+    const flush = () => {
+      if (!request.onOutput || text.length <= emittedUpTo) return;
+      const chunk = text.slice(emittedUpTo);
+      emittedUpTo = text.length;
+      try {
+        request.onOutput(chunk);
+      } catch {
+        /* display only */
+      }
+    };
+
     const capture = (chunk: unknown) => {
       if (truncated) return;
-      const s = String(chunk);
-      bytes += Buffer.byteLength(s);
-      if (bytes > maxOutputBytes) {
-        // Keep what fits, mark it, and stop the child: an unbounded producer must not be able to
-        // exhaust the orchestrator's memory just because it was granted a tool that prints.
-        text += s;
-        text = text.slice(0, maxOutputBytes);
+      // **Decoded through a StringDecoder, not `String(chunk)`.** A pipe splits on byte boundaries, not
+      // character ones, so a multi-byte character straddling two `data` events was decoded as two invalid
+      // halves and became U+FFFD — in the child's ANSWER, not merely the display. Measured: 300,000 bytes of
+      // CJK produced **twelve** replacement characters, because 65536 % 3 == 1. Emoji happened to survive
+      // (65536 % 4 == 0), which is why width-dependent corruption went unnoticed. The decoder holds the
+      // partial bytes until the rest arrives.
+      const s = decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+      if (s.length === 0) return;
+
+      const size = Buffer.byteLength(s);
+      if (bytes + size > maxOutputBytes) {
+        // Keep what fits, mark it, and stop the child: an unbounded producer must not be able to exhaust the
+        // orchestrator's memory just because it was granted a tool that prints.
+        //
+        // **Trimmed by BYTES, and that is a fix rather than a refinement.** This was
+        // `text.slice(0, maxOutputBytes)` — a count of UTF-16 code units against a budget measured in bytes,
+        // so any non-ASCII output overran the cap by its own encoding width: 300 bytes of CJK through a
+        // 100-byte cap, and a measured **2048 bytes through the real 1024 default**. It is the same defect as
+        // the 1924-byte one already fixed here, one layer down: that fix bounded the *unit* count, and the
+        // budget was never in units. An odd cap also split a surrogate pair, putting a lone `\ud83d` into
+        // both the transcript and the returned answer.
+        text += takeBytes(s, maxOutputBytes - bytes);
+        bytes = maxOutputBytes;
         truncated = true;
+        flush();
         stop();
         return;
       }
+      bytes += size;
       text += s;
+      flush();
     };
 
     child.stdout?.on("data", capture);