pi-daddy 0.15.0 → 0.17.0

package/dist/herdr-poll.js

@@ -0,0 +1,150 @@
+/**
+ * Waiting for a herdr agent to settle, and reading what it printed on the way.
+ *
+ * Split out of `src/run-herdr.ts` when that file hit **404 of the 400-line ceiling** adding ADR-0032's output
+ * polling. The seam was named in the plan before it was needed, and it is a real one: this module is about
+ * *observing* an agent, `run-herdr.ts` is about *starting and cleaning up after* one. Nothing here creates or
+ * destroys anything.
+ *
+ * The two facts it is built on were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`) and both are
+ * counter-intuitive enough to be worth the module comment: `agent wait --until idle` matches the state the
+ * agent was **already** in, and `agent read` is the one command that does **not** return a JSON envelope.
+ */
+import { parseReply } from "./herdr-cli.js";
+/** Statuses herdr reports for a settled agent. `blocked` counts: it is waiting for a human, not working. */
+const TERMINAL = new Set(["idle", "done", "blocked"]);
+/** How often to poll `agent get` while waiting for the child to settle. */
+export const POLL_INTERVAL_MS = 750;
+/** Lines of pane tail reported per poll. Matches the status block's own tail, so nothing is fetched unused. */
+export const DEFAULT_SNAPSHOT_LINES = 3;
+/**
+ * Wait for the child to settle, without accepting the state it was already in.
+ *
+ * **R-33, measured.** `herdr agent wait --until idle` called right after `agent prompt` returned
+ * *immediately*, matching the agent's **pre-existing** idle state with `state_change_seq` unchanged — a
+ * reply indistinguishable from a completed run. For fan-out that is not an inconvenience but a
+ * correctness bug: an orchestrator would "collect" N children that never ran and merge N empty results
+ * into a confident summary (R-03 with a new cause).
+ *
+ * So this polls `agent get` and requires **both** that the status is terminal **and** that
+ * `state_change_seq` has advanced past the value observed before prompting. `agent wait` is deliberately
+ * not used at all: its contract cannot express "settled *after* this point".
+ */
+export async function waitForSettled(exec, request, before, deadline, maxOutputBytes) {
+    const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
+    // ADR-0032. The pane is read on every poll so the parent can show what the child is doing, rather than the
+    // one word `delegate` for up to ten minutes.
+    //
+    // No cross-poll state is kept, deliberately: the previous design remembered what it had reported so it could
+    // send a diff, and that is what broke — see `tailLines`. A snapshot needs no memory.
+    const keep = request.snapshotLines ?? DEFAULT_SNAPSHOT_LINES;
+    for (;;) {
+        if (request.signal?.aborted)
+            return { aborted: true };
+        if (Date.now() >= deadline)
+            return { timedOut: true };
+        const reply = parseReply(await exec(["agent", "get", request.name]));
+        if (reply.error)
+            return { spawnError: `herdr agent get failed: ${reply.error}` };
+        const agent = (reply.result?.agent ?? reply.result ?? {});
+        const status = agent.agent_status;
+        const seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+        if (request.onSnapshot) {
+            // Read BEFORE the terminal check returns, so a child that settles on this iteration still has its last
+            // output shown. `readFailed` is passed so a failed read renders as such instead of silently freezing the
+            // block on the previous frame — and, crucially, is never mistaken for the child's output.
+            const read = await readPane(exec, request.name, maxOutputBytes);
+            try {
+                request.onSnapshot(read.readFailed ? ["[pane could not be read]"] : tailLines(read.text, keep));
+            }
+            catch {
+                /* display only — a renderer must not break a governed run */
+            }
+        }
+        if (status && TERMINAL.has(status) && seq > before)
+            return { status };
+        await new Promise((r) => setTimeout(r, Math.min(interval, Math.max(0, deadline - Date.now()))));
+    }
+}
+/**
+ * The last `keep` non-blank lines of a pane snapshot — what the display actually needs.
+ *
+ * **This replaces a `newSuffix` diff, and the replacement is a correction rather than a tune-up.** The old
+ * design treated `agent read` as a *stream* and tried to report only what was new, by testing whether the new
+ * text extended the old. That is wrong about the substrate: `agent read` returns a **snapshot of a bounded
+ * terminal**, and a snapshot is not an append-only log. Two ordinary things break the prefix test forever —
+ * the pane **scrolling** (its top lines are gone, so the new text is not an extension of the old) and
+ * `readPane` **truncating to the tail** past `maxOutputBytes` (each read is a different window of a growing
+ * buffer). Once either happens, every poll reported the whole buffer.
+ *
+ * Measured before the fix: **51 MiB streamed for ~600 bytes of real output — 89,000× amplification** in 37
+ * seconds, per child, with a scrolling pane also delivering the same real lines three times each. The old
+ * docstring named that exact failure as the thing it prevented.
+ *
+ * So the herdr path now reports a **bounded snapshot** and the consumer *replaces* rather than appends. There
+ * is no diff to get wrong, the per-poll cost is `keep` lines regardless of buffer size, and a scrolling pane
+ * simply shows its current tail — which is what a human looking at that pane would see.
+ */
+export function tailLines(snapshot, keep) {
+    if (keep <= 0)
+        return [];
+    const lines = [];
+    // Walked from the END, so a 1 MiB buffer costs the last few lines rather than a full split.
+    let end = snapshot.length;
+    while (end > 0 && lines.length < keep) {
+        const start = snapshot.lastIndexOf("\n", end - 1);
+        const line = snapshot.slice(start + 1, end).replace(/\r/g, "").trimEnd();
+        if (line.length > 0)
+            lines.unshift(line);
+        if (start === -1)
+            break;
+        end = start;
+    }
+    return lines;
+}
+/**
+ * Read the pane's contents.
+ *
+ * `agent read` is the ONE command that does not return herdr's JSON envelope — it writes the terminal's
+ * text straight to stdout. Running it through `parseReply` turned every successful read into
+ * "unparseable herdr reply", i.e. reported the child's actual answer as a failure to read it. Found by the
+ * end-to-end run; the unit fake had been written to the envelope shape and so agreed with the bug.
+ *
+ * A JSON envelope is still accepted first, because an `error` reply here IS JSON and must not be mistaken
+ * for terminal output.
+ *
+ * **`readFailed` is separate from `text`, and that separation is the fix for an R-03 defect.** A failed read
+ * used to return its own diagnostic *as* `text` — so `runHerdrPane` returned
+ * `[grants] could not read the agent pane: pane is gone` **as the child's answer, with `code: 0`**, and the
+ * orchestrator read a failure message as a completed sub-agent's report. Measured. It mattered little when this
+ * ran once per child; ADR-0032 made it run on every poll, up to 800 times for a ten-minute child, so a
+ * transient failure went from unlikely to expected. The caller must now decide, and it cannot do so by
+ * inspecting a string.
+ */
+export async function readPane(exec, name, maxOutputBytes) {
+    const reply = await exec(["agent", "read", name]);
+    let text;
+    try {
+        const parsed = JSON.parse(reply.stdout);
+        if (parsed.error) {
+            return { text: "", truncated: false, readFailed: parsed.error.message ?? "unknown error" };
+        }
+        const raw = parsed.result?.output ?? parsed.result?.text ?? parsed.result?.content ?? "";
+        text = typeof raw === "string" ? raw : JSON.stringify(raw);
+    }
+    catch {
+        text = reply.stdout;
+    }
+    if (Buffer.byteLength(text) <= maxOutputBytes)
+        return { text, truncated: false };
+    // Keep the TAIL, not the head: a terminal's useful content is its most recent output, and the head is
+    // the startup banner. `runChild` keeps the head because it streams and must stop a runaway producer;
+    // here the output is already complete, so the choice is free and the tail is the answer.
+    //
+    // Sliced by BYTES via a Buffer round trip rather than by code units, for `takeBytes`'s reason in
+    // `run-child.ts`: `slice(-maxOutputBytes)` on a CJK pane overran the cap by three times. `toString` repairs
+    // a character split at the cut by replacing it, which is the right trade for a tail — one replacement
+    // character at the boundary, versus a cap that does not hold.
+    return { text: Buffer.from(text, "utf8").subarray(-maxOutputBytes).toString("utf8"), truncated: true };
+}
+//# sourceMappingURL=herdr-poll.js.map

package/dist/herdr-poll.js.map

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

package/dist/herdr-stage.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+/**
+ * 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 declare function splitSystemPrompt(args: string[]): {
+    args: string[];
+    systemPrompt?: string;
+};
+/**
+ * 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 declare function stageSystemPrompt(args: string[]): Promise<{
+    args: string[];
+    promptDir?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=herdr-stage.d.ts.map

package/dist/herdr-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-stage.d.ts","sourceRoot":"","sources":["../src/herdr-stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAI3F;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAWjE"}

package/dist/herdr-stage.js

@@ -0,0 +1,54 @@
+/**
+ * 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) {
+    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) {
+    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)}` };
+    }
+}
+//# sourceMappingURL=herdr-stage.js.map

package/dist/herdr-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-stage.js","sourceRoot":"","sources":["../src/herdr-stage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAc;IAC9C,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC;IAClD,IAAI,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACxD,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;AAC7F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,IAAc;IAEd,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;IAClE,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,CAAC;QACjD,MAAM,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,wBAAwB,EAAE,IAAI,CAAC,EAAE,SAAS,EAAE,CAAC;IAC9E,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,gDAAgD,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;IACtG,CAAC;AACH,CAAC"}

package/dist/ledger-report.d.ts

@@ -23,6 +23,24 @@ export interface LedgerReport {
     }>;
     /** 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).
      *

package/dist/ledger-report.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ledger-report.d.ts","sourceRoot":"","sources":["../src/ledger-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,yFAAyF;IACzF,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,EAAE;QACT,2FAA2F;QAC3F,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACzC,2EAA2E;QAC3E,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACjD,0GAA0G;QAC1G,YAAY,EAAE,MAAM,CAAC;QACrB,uFAAuF;QACvF,WAAW,EAAE,MAAM,CAAC;QACpB;;;;;;;;WAQG;QACH,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA0HtE"}
+{"version":3,"file":"ledger-report.d.ts","sourceRoot":"","sources":["../src/ledger-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,yFAAyF;IACzF,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,EAAE;QACT,2FAA2F;QAC3F,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACzC,2EAA2E;QAC3E,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACjD,0GAA0G;QAC1G,YAAY,EAAE,MAAM,CAAC;QACrB,uFAAuF;QACvF,WAAW,EAAE,MAAM,CAAC;QACpB;;;;;;;;WAQG;QACH,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAiItE"}

package/dist/ledger-report.js

@@ -36,6 +36,7 @@ export async function verifyLedger(path) {
                 records: 0,
                 corrupt: [],
                 escalationAttempts: 0,
+                executors: { herdr: 0, process: 0, unknown: 0 },
                 definitions: [],
                 approvals: {
                     bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
@@ -54,6 +55,7 @@ export async function verifyLedger(path) {
     const digests = new Map();
     let records = 0;
     let escalationAttempts = 0;
+    const executors = { herdr: 0, process: 0, unknown: 0 };
     const bySource = { 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 = {
@@ -77,6 +79,13 @@ export async function verifyLedger(path) {
             records += 1;
             if (isEscalationAttempt(parsed))
                 escalationAttempts += 1;
+            const executor = parsed.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;
@@ -138,6 +147,7 @@ export async function verifyLedger(path) {
         records,
         corrupt,
         escalationAttempts,
+        executors,
         definitions: [...digests.values()].sort((a, b) => a.name.localeCompare(b.name) || a.sha256.localeCompare(b.sha256)),
         approvals: {
             bySource,

package/dist/ledger-report.js.map

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

package/dist/ledger.d.ts

@@ -19,6 +19,7 @@
  * "what was this child told to do?" is out of the ledger by decision, not by omission.
  */
 import type { Capability, ResolveResult } from "./resolve.ts";
+import type { ExecutorKind } from "./executor.ts";
 import type { DefinitionDigest } from "./definitions.ts";
 import type { ApprovalScope, ApprovalSource } from "./approval.ts";
 import type { PromptOutcomeKind } from "./approval-prompt.ts";
@@ -101,6 +102,32 @@ 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;
+    /**
+     * The child whose OUTPUT composed this child's task — ADR-0033.
+     *
+     * **Optional, unlike `executor`, and the asymmetry is deliberate.** A non-chained spawn has no prior author, and
+     * an empty string would assert one. Present only on chain steps after the first.
+     *
+     * Why it is recorded at all: a chain makes step N's task the output of a governed child, and ADR-0033's chosen
+     * handoff is *framing* rather than enforcement. So "who wrote this instruction?" is exactly the question that
+     * decision makes worth asking, and it is unanswerable from any other field — `agentType` names the definition,
+     * `definitionDigest` names its instructions, and neither says where the TASK came from.
+     */
+    taskFrom?: string;
 }
 export interface LedgerOptions {
     /** Path to the JSONL file. Parent directories are created on demand. */
@@ -129,6 +156,10 @@ export declare 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;
+    /** The child whose output composed this task (ADR-0033). Absent for anything but a chain step. */
+    taskFrom?: string;
     now: Date;
 }): GrantRecord;
 export { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from "./file-lock.ts";

package/dist/ledger.d.ts.map

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

package/dist/ledger.js

@@ -35,6 +35,8 @@ export function buildRecord(args) {
         childId: args.childId,
         depth: args.depth,
         agentType: args.agentType,
+        executor: args.executor,
+        ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
         requested: args.requested,
         parentGrant: args.parentGrant,
         effective: args.result.effective,

package/dist/ledger.js.map

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

package/dist/pane-reaper.d.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
@@ -21,14 +26,45 @@
  *
  * Everything here is **synchronous**, because an `exit` handler is: a promise scheduled there never runs.
  */
+import { 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 declare const MAX_OPEN_PANES = 8;
 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 declare function markPaneSettled(tab: string): void;
 /** A run has opened a pane. Idempotent per tab, and installs the exit hook on first use only. */
 export declare function trackPane(pane: OpenPane): void;
 /** A run closed its own pane the normal way. */
@@ -46,4 +82,30 @@ export declare function openPaneCount(): number;
  * other seven, and nothing at exit has anywhere to report to anyway.
  */
 export declare function reapOpenPanes(syncExec?: (args: string[]) => void, now?: () => number): string[];
+/**
+ * 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 declare function reapOpenPanesAsync(exec?: HerdrExec): Promise<string[]>;
+/**
+ * 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 declare function trimOpenPanes(exec?: HerdrExec): Promise<string[]>;
 //# sourceMappingURL=pane-reaper.d.ts.map

package/dist/pane-reaper.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pane-reaper.d.ts","sourceRoot":"","sources":["../src/pane-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAeD,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAO9C;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAsB,EAAE,GAAG,eAAW,GAAG,MAAM,EAAE,CA6B5G"}
+{"version":3,"file":"pane-reaper.d.ts","sourceRoot":"","sources":["../src/pane-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEzE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,IAAwB,CAAC;AAEpD,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,4GAA4G;IAC5G,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;OASG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAGjD;AAeD,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAO9C;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAsB,EAAE,GAAG,eAAW,GAAG,MAAM,EAAE,CAgD5G;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,GAAE,SAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CASzF;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,IAAI,GAAE,SAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAmBpF"}