pi-daddy 0.27.4 → 0.32.0

package/dist/executors/herdr-poll.js

@@ -0,0 +1,252 @@
+/**
+ * Waiting for a herdr agent to settle, and reading what it printed on the way.
+ *
+ * Split out of `src/executors/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";
+import { herdrSessionReference } from "../governance/native-session.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"]);
+/** The pre-prompt sequence from the native start reply; absent is unknown, never zero. */
+export function observeHerdrSession(agent, pane, sink) {
+    if (!pane || !sink)
+        return;
+    try {
+        const reference = herdrSessionReference(agent, pane);
+        if (reference)
+            sink(reference);
+    }
+    catch {
+        /* optional observation */
+    }
+}
+export function seqOf(result) {
+    const agent = (result?.agent ?? {});
+    return typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+}
+/** How often to poll `agent get` while waiting for the child to settle. */
+export const POLL_INTERVAL_MS = 750;
+/**
+ * A prompt accepted from a terminal state must produce an observable lifecycle change promptly.
+ *
+ * Herdr 0.8's `agent prompt --wait` documents this same five-second bound. We retain polling because it
+ * supplies the bounded live pane snapshots, but refuse rather than holding a parent for the whole child timeout when
+ * the only reported state remains the pre-prompt terminal state. That is a detector/integration failure, not
+ * evidence that a child settled.
+ */
+export const FRESH_LIFECYCLE_TIMEOUT_MS = 5_000;
+/** 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".
+ */
+/**
+ * Establish the bundled Pi lifecycle reporter's idle baseline before prompt dispatch.
+ *
+ * `screen_detection_skipped` is Herdr's reported fact that a full lifecycle authority owns this pane.
+ * Waiting for it prevents the reporter's asynchronously queued initial idle report from becoming a
+ * post-prompt sequence advance. This is not completion: no prompt has been sent at this point.
+ */
+export async function waitForLifecycleBaseline(exec, request, deadline) {
+    const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
+    for (;;) {
+        if (request.signal?.aborted)
+            return { aborted: true };
+        if (Date.now() >= deadline)
+            return { spawnError: "Herdr did not activate the bundled Pi lifecycle reporter before prompt dispatch" };
+        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 seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+        if (agent.screen_detection_skipped === true && agent.agent_status && TERMINAL.has(agent.agent_status) && seq >= 0)
+            return { before: seq };
+        await new Promise((resolve) => setTimeout(resolve, Math.min(interval, Math.max(0, deadline - Date.now()))));
+    }
+}
+export async function waitForSettled(exec, request, before, deadline, maxOutputBytes) {
+    const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
+    let lastActivityAt = Date.now();
+    let lastPane;
+    let lastMarker;
+    // 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 sixty minutes by default.
+    //
+    // 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;
+    let staleTerminalSince;
+    for (;;) {
+        if (request.signal?.aborted)
+            return { aborted: true };
+        if (Date.now() >= deadline)
+            return { timedOut: true };
+        if (request.idleTimeoutMs !== undefined && Date.now() - lastActivityAt >= request.idleTimeoutMs)
+            return { timedOut: true, idle: 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 ?? {});
+        if (request.idleTimeoutMs !== undefined) {
+            // The pane is read below only when a display wants it; the probe is the executor-independent signal.
+            let marker;
+            try {
+                marker = await request.activityProbe?.();
+            }
+            catch {
+                marker = undefined; // unreadable is "no activity seen", never a control decision
+            }
+            if (marker !== undefined && marker !== lastMarker) {
+                lastMarker = marker;
+                lastActivityAt = Date.now();
+            }
+        }
+        observeHerdrSession(agent, request.nativePaneId, request.onSessionReference);
+        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);
+            if (!read.readFailed && read.text !== lastPane) {
+                lastPane = read.text;
+                lastActivityAt = Date.now();
+            }
+            if (!read.readFailed) {
+                try {
+                    request.onObservation?.(Buffer.from(read.text));
+                }
+                catch {
+                    /* observation only */
+                }
+            }
+            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)) {
+            if (seq > before)
+                return { status };
+            // Do not turn this pane's text into a completion signal. A known agent whose screen rule misses a new
+            // UI shape falls back to idle, precisely the state R-33 says is unsafe to accept. A stable stale
+            // terminal state for this bounded interval is instead a loud compatibility refusal (issue #43).
+            staleTerminalSince ??= Date.now();
+            if (Date.now() - staleTerminalSince >= FRESH_LIFECYCLE_TIMEOUT_MS) {
+                return {
+                    spawnError: `herdr reported ${status} without a post-prompt lifecycle change for ${FRESH_LIFECYCLE_TIMEOUT_MS}ms; ` +
+                        "refusing to treat the pre-prompt terminal state as completion. Update Herdr's Pi detector or inspect its lifecycle reporting.",
+                };
+            }
+        }
+        else {
+            staleTerminalSince = undefined;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 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/executors/herdr-poll.js.map

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

package/dist/executors/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/executors/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/executors/herdr-stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-stage.d.ts","sourceRoot":"","sources":["../../src/executors/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/executors/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/executors/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/executors/herdr-stage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-stage.js","sourceRoot":"","sources":["../../src/executors/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/executors/herdr-start.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-start.d.ts","sourceRoot":"","sources":["../../src/executors/herdr-start.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE5D,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,wBAAsB,eAAe,CACnC,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EAAE,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAO/D"}

package/dist/executors/herdr-start.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"herdr-start.js","sourceRoot":"","sources":["../../src/executors/herdr-start.ts"],"names":[],"mappings":"AAAA,uFAAuF;AACvF,OAAO,EAAE,UAAU,EAAkB,MAAM,gBAAgB,CAAC;AAE5D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAEtC,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAe,EACf,IAAY,EACZ,MAAc,EACd,IAAc,EACd,QAAgB;IAEhB,SAAS,CAAC;QACR,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAChH,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QAC/B,IAAI,CAAC,wCAAwC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;YAAE,OAAO,KAAK,CAAC;QACxG,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,CAAC;IAChF,CAAC;AACH,CAAC"}

package/dist/executors/native-session-target.d.ts

@@ -0,0 +1,9 @@
+export { ENV_RETAIN_NATIVE_SESSIONS } from "../kernel/env-names.ts";
+export interface NativeSessionHost {
+    /** Explicit host opt-in captured once, not model-supplied. */ readonly nativeSessionRoot?: string;
+}
+export declare const nativeSessionRootFromEnv: (env: NodeJS.ProcessEnv) => string | undefined;
+/** Explicit ordinary-host opt-in only. Never read a destination from tool/model parameters.
+ * Allocate a fresh per-occurrence directory; no scan, existing-session takeover or transcript creation. */
+export declare function allocateNativeSessionTarget(root: string, executionId: string): Promise<string>;
+//# sourceMappingURL=native-session-target.d.ts.map

package/dist/executors/native-session-target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-session-target.d.ts","sourceRoot":"","sources":["../../src/executors/native-session-target.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,MAAM,WAAW,iBAAiB;IAChC,8DAA8D,CAAC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACpG;AACD,eAAO,MAAM,wBAAwB,GAAI,KAAK,MAAM,CAAC,UAAU,uBAC6B,CAAC;AAC7F;2GAC2G;AAC3G,wBAAsB,2BAA2B,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBpG"}

package/dist/executors/native-session-target.js

@@ -0,0 +1,30 @@
+import { lstat, realpath, mkdir } from "node:fs/promises";
+import { dirname, isAbsolute, join, parse, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { ENV_NATIVE_SESSION_ROOT } from "../governance/native-session.js";
+import { ENV_RETAIN_NATIVE_SESSIONS } from "../kernel/env-names.js";
+export { ENV_RETAIN_NATIVE_SESSIONS } from "../kernel/env-names.js";
+export const nativeSessionRootFromEnv = (env) => env[ENV_RETAIN_NATIVE_SESSIONS] === "1" ? (env[ENV_NATIVE_SESSION_ROOT] ?? "") : undefined;
+/** Explicit ordinary-host opt-in only. Never read a destination from tool/model parameters.
+ * Allocate a fresh per-occurrence directory; no scan, existing-session takeover or transcript creation. */
+export async function allocateNativeSessionTarget(root, executionId) {
+    if (!isAbsolute(root) || resolve(root) !== root || !/^[a-zA-Z0-9:_-]{1,128}$/.test(executionId))
+        throw new Error("explicit native root/execution identity required");
+    for (let p = root;; p = dirname(p)) {
+        const s = await lstat(p);
+        if (!s.isDirectory() || s.isSymbolicLink())
+            throw new Error("native target ancestor changed");
+        if (p === parse(p).root)
+            break;
+    }
+    const before = await lstat(root);
+    if ((await realpath(root)) !== root || before.mode & 0o077 || before.uid !== process.getuid?.())
+        throw new Error("private owned native target root required");
+    const directory = join(root, "execution-" + createHash("sha256").update(executionId).digest("hex"));
+    await mkdir(directory, { mode: 0o700 }); // EEXIST is a refusal, never permission to append an old occurrence.
+    const after = await lstat(root);
+    if (before.dev !== after.dev || before.ino !== after.ino || (await realpath(directory)) !== directory)
+        throw new Error("native target root replaced");
+    return join(directory, "session.jsonl");
+}
+//# sourceMappingURL=native-session-target.js.map

package/dist/executors/native-session-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-session-target.js","sourceRoot":"","sources":["../../src/executors/native-session-target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAC;AAC1E,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AACpE,OAAO,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAC;AAIpE,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,GAAsB,EAAE,EAAE,CACjE,GAAG,CAAC,0BAA0B,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,uBAAuB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AAC7F;2GAC2G;AAC3G,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAAC,IAAY,EAAE,WAAmB;IACjF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,yBAAyB,CAAC,IAAI,CAAC,WAAW,CAAC;QAC7F,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,KAAK,IAAI,CAAC,GAAG,IAAI,GAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC;QACzB,IAAI,CAAC,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,cAAc,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;QAC9F,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI;YAAE,MAAM;IACjC,CAAC;IACD,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,MAAM,CAAC,IAAI,GAAG,KAAK,IAAI,MAAM,CAAC,GAAG,KAAK,OAAO,CAAC,MAAM,EAAE,EAAE;QAC7F,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACpG,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,qEAAqE;IAC9G,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;IAChC,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,IAAI,MAAM,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,IAAI,CAAC,MAAM,QAAQ,CAAC,SAAS,CAAC,CAAC,KAAK,SAAS;QACnG,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,OAAO,IAAI,CAAC,SAAS,EAAE,eAAe,CAAC,CAAC;AAC1C,CAAC"}

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

@@ -0,0 +1,111 @@
+/**
+ * Close herdr panes this process opened but never got to close.
+ *
+ * **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
+ * termination*, so a library that adds one takes over an application-level decision it has no standing to
+ * make: pi uses SIGINT to interrupt a turn, and a listener here that re-raised would turn "cancel this
+ * delegation" into "exit pi". A governance package quietly changing the host's interrupt semantics is a
+ * worse defect than the leak it fixes, and it would land on **every** session rather than the opt-in ones.
+ *
+ * So the coverage is exact and stated rather than implied:
+ *
+ *  - **Covered:** normal exit, `process.exit()`, an uncaught exception that unwinds to the default handler.
+ *  - **NOT covered:** SIGKILL, and SIGTERM/SIGINT where nothing else in the process has installed a
+ *    listener. Node terminates without running `exit` handlers in those cases, by design. A pane can still
+ *    be orphaned there, and `herdr tab close <id>` is the manual remedy.
+ *
+ * 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;
+    /** 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_DADDY_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. */
+export declare function untrackPane(tab: string): void;
+/** How many panes are currently outstanding — for tests and for `/grants`. */
+export declare function openPaneCount(): number;
+/**
+ * Close every outstanding pane and return the tab ids closed.
+ *
+ * Exported and parameterised so it can be tested without herdr installed: the exit hook is unreachable from
+ * a test (registering a real `exit` handler would run during the test runner's own shutdown), so the hook is
+ * one line and *this* is where the behaviour lives.
+ *
+ * Failures are swallowed per pane rather than per call — one pane herdr will not close must not strand the
+ * 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/executors/pane-reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pane-reaper.d.ts","sourceRoot":"","sources":["../../src/executors/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"}