pi-daddy 0.15.0 → 0.17.0

package/dist/pane-reaper.js

@@ -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
@@ -23,6 +28,24 @@
  */
 import { execFileSync } from "node:child_process";
 import { rmSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { MAX_CHILDREN_PER_CALL } from "./fanout.js";
+import { defaultExec, parseReply } from "./herdr-cli.js";
+/**
+ * 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;
+/** A run has finished with its pane: the trim may now reclaim it. */
+export function markPaneSettled(tab) {
+    const pane = open.get(tab);
+    if (pane)
+        pane.settled = true;
+}
 /**
  * Panes opened by THIS process and not yet closed. Keyed by tab id, so a double close is impossible.
  *
@@ -92,20 +115,37 @@ export function reapOpenPanes(syncExec = defaultSyncExec, now = Date.now) {
         // `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 });
             }
@@ -113,8 +153,90 @@ export function reapOpenPanes(syncExec = defaultSyncExec, now = Date.now) {
                 /* /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, pane) {
+    // **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 = defaultExec) {
+    const closed = [];
+    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 = defaultExec) {
+    if (open.size <= MAX_OPEN_PANES)
+        return [];
+    const closed = [];
+    // **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;
+}
 //# sourceMappingURL=pane-reaper.js.map

package/dist/pane-reaper.js.map

@@ -1 +1 @@
-{"version":3,"file":"pane-reaper.js","sourceRoot":"","sources":["../src/pane-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAWjC;;;;;;;;;GASG;AACH,MAAM,IAAI,GAAG,IAAI,GAAG,EAAoB,CAAC;AACzC,IAAI,aAAa,GAAG,KAAK,CAAC;AAE1B,iGAAiG;AACjG,MAAM,UAAU,SAAS,CAAC,IAAc;IACtC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACzB,IAAI,aAAa;QAAE,OAAO;IAC1B,aAAa,GAAG,IAAI,CAAC;IACrB,qGAAqG;IACrG,oGAAoG;IACpG,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,KAAK,aAAa,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AACnB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC;AACnB,CAAC;AAED,wGAAwG;AACxG,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB;;;;;;;;;;;;GAYG;AACH,MAAM,eAAe,GAAG,IAAI,CAAC;AAE7B,sGAAsG;AACtG,MAAM,eAAe,GAAG,CAAC,IAAc,EAAQ,EAAE;IAC/C,YAAY,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;AAChG,CAAC,CAAC;AAEF;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAAC,WAAqC,eAAe,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG;IAChG,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,QAAQ,GAAG,GAAG,EAAE,GAAG,eAAe,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;QACtC,sGAAsG;QACtG,qGAAqG;QACrG,uGAAuG;QACvG,IAAI,GAAG,EAAE,IAAI,QAAQ;YAAE,MAAM;QAC7B,IAAI,CAAC;YACH,QAAQ,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;QACD,IAAI,CAAC;YACH,QAAQ,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACrC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxB,CAAC;QAAC,MAAM,CAAC;YACP,+FAA+F;QACjG,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3D,CAAC;YAAC,MAAM,CAAC;gBACP,kCAAkC;YACpC,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"pane-reaper.js","sourceRoot":"","sources":["../src/pane-reaper.ts"],"names":[],"mappings":"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"}

package/dist/progress.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 declare 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 declare const MAX_LINE_CHARS = 200;
+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 declare const emptyTail: Tail;
+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;
+}
+/**
+ * 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 declare function appendTail(tail: Tail, chunk: string): Tail;
+/**
+ * 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 declare function replaceTail(lines: string[]): Tail;
+export declare function renderProgress(children: ChildProgress[], executorKind: "herdr" | "process", now: number): string;
+/** How often the block is repainted. A child printing fast must not re-render it hundreds of times a second. */
+export declare 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 declare function throttle(fn: () => void, intervalMs: number): {
+    call: () => void;
+    flush: () => void;
+};
+//# sourceMappingURL=progress.d.ts.map

package/dist/progress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,+GAA+G;AAC/G,eAAO,MAAM,UAAU,IAAI,CAAC;AAE5B;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,cAAc,MAAM,CAAC;AAQlC,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,WAAW,IAAI;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wEAAwE;IACxE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,SAAS,EAAE,IAAiC,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC5B,2DAA2D;IAC3D,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,IAAI,CAAC;CACZ;AAaD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAsB1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAEjD;AAmBD,wBAAgB,cAAc,CAAC,QAAQ,EAAE,aAAa,EAAE,EAAE,YAAY,EAAE,OAAO,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAmBhH;AAED,gHAAgH;AAChH,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,UAAU,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CA0BpG"}

package/dist/progress.js

@@ -0,0 +1,167 @@
+/**
+ * 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) {
+    if (line.length <= MAX_LINE_CHARS)
+        return line;
+    return `${line.slice(0, MAX_LINE_CHARS)}… (+${line.length - MAX_LINE_CHARS} chars)`;
+}
+export const emptyTail = { lines: [], open: false };
+/**
+ * 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) {
+    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, chunk) {
+    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) {
+    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) {
+    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, now) {
+    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, executorKind, now) {
+    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, intervalMs) {
+    let last = 0;
+    let timer;
+    const run = (at) => {
+        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?.();
+        },
+        flush: () => {
+            if (timer)
+                clearTimeout(timer);
+            timer = undefined;
+            last = Date.now();
+            fn();
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/progress.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"progress.js","sourceRoot":"","sources":["../src/progress.ts"],"names":[],"mappings":"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"}

package/dist/run-child.d.ts

@@ -8,6 +8,19 @@
  *
  * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
  */
+/**
+ * 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 declare function takeBytes(text: string, budget: number): string;
 /**
  * Operator override for the child wall-clock limit, in seconds.
  *
@@ -29,6 +42,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 {
     /** Exit code, or `null` when nothing was spawned or the child was killed by a signal. */

package/dist/run-child.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-child.d.ts","sourceRoot":"","sources":["../src/run-child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,QAAc,CAAC;AACpD,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AACjD,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAsF1E"}
+{"version":3,"file":"run-child.d.ts","sourceRoot":"","sources":["../src/run-child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAY9D;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9D;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,QAAc,CAAC;AACpD,kGAAkG;AAClG,eAAO,MAAM,kBAAkB,QAAiB,CAAC;AACjD,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAsI1E"}

package/dist/run-child.js

@@ -9,7 +9,36 @@
  * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
  */
 import { spawn } from "node:child_process";
+import { StringDecoder } from "node:string_decoder";
 import { parseBound } from "./propagation.js";
+/**
+ * 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, budget) {
+    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.
  *
@@ -54,6 +83,9 @@ export function runChild(request) {
             settle({ code: null, text: "", truncated: false, timedOut: false, aborted: false, spawnError: String(error) });
             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;
@@ -67,21 +99,66 @@ export function runChild(request) {
             child.kill("SIGTERM");
             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) => {
             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);
         child.stderr?.on("data", capture);