pi-daddy 0.14.0 → 0.16.0

package/src/herdr-stage.ts

@@ -0,0 +1,55 @@
+/**
+ * Staging a definition's instructions to a file, because herdr cannot carry them in argv.
+ *
+ * Split out of `src/run-herdr.ts` at the 400-line ceiling. A real seam rather than an arbitrary cut: this is
+ * the one place that works around a **herdr encoding limit**, and it is the only part of the herdr path that
+ * touches the filesystem. `run-herdr.ts` starts and reaps agents; this prepares one argument.
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Move a multi-line `--append-system-prompt` out of argv, because herdr cannot encode it.
+ *
+ * **Measured.** `herdr agent start` types the argv into the pane's shell, so a value containing newlines
+ * is rejected outright: `invalid_agent_argument — agent arguments cannot be encoded safely for the target
+ * shell`. A definition's `SKILL.md` body is always multi-line, so every `delegate({agent})` spawn would
+ * fail on this path.
+ *
+ * pi accepts a **file path** there as readily as literal text (`resolvePromptInput` + `existsSync` in
+ * `dist/core/resource-loader.js`), so the fix is to write the body to a temp file and pass its path — one
+ * short, shell-safe argument.
+ *
+ * The split lives here rather than in `planSpawn` because the constraint is **herdr's**, not pi's: the
+ * direct executor passes the same text inline with no trouble, and a plan builder that pre-emptively wrote
+ * temp files for everybody would be paying one executor's tax on both paths.
+ */
+export function splitSystemPrompt(args: string[]): { args: string[]; systemPrompt?: string } {
+  const at = args.indexOf("--append-system-prompt");
+  if (at === -1 || at + 1 >= args.length) return { args };
+  return { args: [...args.slice(0, at), ...args.slice(at + 2)], systemPrompt: args[at + 1] };
+}
+
+/**
+ * Move a multi-line system prompt into a temp file and return argv pointing at it.
+ *
+ * Returns the directory so the caller can remove it — and **every** early return on the herdr path must, because
+ * nothing else can: a reviewer measured a permanent `/tmp/grants-herdr-*` per failed `tab create`, unreachable by
+ * either pane sweep because the pane it belonged to never existed.
+ */
+export async function stageSystemPrompt(
+  args: string[],
+): Promise<{ args: string[]; promptDir?: string; error?: string }> {
+  const split = splitSystemPrompt(args);
+  if (split.systemPrompt === undefined) return { args: split.args };
+  try {
+    const promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
+    const file = join(promptDir, "system-prompt.md");
+    await writeFile(file, split.systemPrompt, "utf8");
+    return { args: [...split.args, "--append-system-prompt", file], promptDir };
+  } catch (error) {
+    return { args: split.args, error: `could not stage the system prompt for herdr: ${String(error)}` };
+  }
+}

package/src/ledger-report.ts

@@ -27,6 +27,20 @@ export interface LedgerReport {
   corrupt: Array<{ line: number; text: string }>;
   /** Records where an agent asked for more than it held — ADR-0008's designated signal. */
   escalationAttempts: number;
+  /**
+   * How many records ran under each executor, plus how many name none — ADR-0031.
+   *
+   * **Added because the field was written and never read, which is R-51's shape exactly.** R-51 was
+   * `definitionDigest`: recorded from the start, absent from every report, so the questions ADR-0018 advertised
+   * needed hand-written `jq`. `executor` arrived the same way — `src/ledger.ts` justifies making it *required*
+   * with "reading it back is the only reason it exists", and nothing read it back. `docs/SPEC.md` claims the
+   * executor is "announced three times… per child in the ledger"; without this the third announcement was to
+   * `jq` only.
+   *
+   * `unknown` counts pre-0.16 lines, which have no such field. Reported rather than folded into `process`,
+   * because "written before the executor was recorded" and "ran as a subprocess" are different facts.
+   */
+  executors: { herdr: number; process: number; unknown: number };
   /**
    * Every distinct set of instructions this ledger saw run, with how many spawns used it (R-51).
    *
@@ -113,6 +127,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         records: 0,
         corrupt: [],
         escalationAttempts: 0,
+        executors: { herdr: 0, process: 0, unknown: 0 },
         definitions: [],
         approvals: {
           bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
@@ -132,6 +147,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
   const digests = new Map<string, { name: string; source: string; sha256: string; spawns: number }>();
   let records = 0;
   let escalationAttempts = 0;
+  const executors = { herdr: 0, process: 0, unknown: 0 };
   const bySource: Record<ApprovalSource, number> = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
   // `capability@subject` seen per source, so the report can state a bound as well as a raw count.
   const distinct: Record<ApprovalSource, Set<string>> = {
@@ -153,6 +169,10 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
       if (!Array.isArray(parsed.denied)) throw new Error("not a grant record");
       records += 1;
       if (isEscalationAttempt(parsed)) escalationAttempts += 1;
+      const executor = (parsed as { executor?: unknown }).executor;
+      if (executor === "herdr") executors.herdr += 1;
+      else if (executor === "process") executors.process += 1;
+      else executors.unknown += 1;
       if (parsed.humanDenied) {
         humanDenied += 1;
         const subject = parsed.agentType === undefined || parsed.agentType === "delegate" ? DELEGATE_SUBJECT : parsed.agentType;
@@ -209,6 +229,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
     records,
     corrupt,
     escalationAttempts,
+    executors,
     definitions: [...digests.values()].sort((a, b) => a.name.localeCompare(b.name) || a.sha256.localeCompare(b.sha256)),
     approvals: {
       bySource,

package/src/ledger.ts

@@ -23,6 +23,7 @@ import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { withFileLock } from "./file-lock.ts";
 import { dirname } from "node:path";
 import type { Capability, ResolveResult } from "./resolve.ts";
+import type { ExecutorKind } from "./executor.ts";
 import type { DefinitionDigest } from "./definitions.ts";
 import { DELEGATE_SUBJECT } from "./approval.ts";
 import type { ApprovalScope, ApprovalSource } from "./approval.ts";
@@ -107,6 +108,20 @@ export interface GrantRecord {
    * it. Absent for a `tools:`-style delegation, which has no definition.
    */
   definitionDigest?: DefinitionDigest;
+  /**
+   * WHERE this child ran — ADR-0031.
+   *
+   * **Required rather than optional**, which is unusual in this record and deliberate. Before ADR-0031 the
+   * executor was a variable an operator set, so "which one ran?" was answerable from configuration after the
+   * fact. It is now decided by a **runtime probe** at session start, so nothing outside the record preserves
+   * the answer — and the two paths do not produce the same argv, because the herdr plan withholds `--print`
+   * (`delegationContext.interactive`). A trail that cannot say where a child ran cannot be read back
+   * reliably, and reading it back is the only reason it exists.
+   *
+   * Written on refusals too, including the tripwire's: the honest value there is the executor the session
+   * *would* have used, because a refused spawn has no executor of its own.
+   */
+  executor: ExecutorKind;
 }
 
 export interface LedgerOptions {
@@ -137,6 +152,8 @@ export function buildRecord(args: {
   humanDenied?: boolean;
   gateOutcome?: PromptOutcomeKind;
   definitionDigest?: DefinitionDigest;
+  /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
+  executor: ExecutorKind;
   now: Date;
 }): GrantRecord {
   // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
@@ -151,6 +168,7 @@ export function buildRecord(args: {
     childId: args.childId,
     depth: args.depth,
     agentType: args.agentType,
+    executor: args.executor,
     requested: args.requested,
     parentGrant: args.parentGrant,
     effective: args.result.effective,

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();
+    },
+  };
+}