pi-daddy 0.28.0 → 0.32.0

package/dist/executors/pane-reaper.js

@@ -0,0 +1,242 @@
+/**
+ * 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 { execFileSync } from "node:child_process";
+import { rmSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { MAX_CHILDREN_PER_CALL } from "../kernel/fanout.js";
+import { defaultExec, parseReply } from "./herdr-cli.js";
+/**
+ * How many panes may be open at once — ADR-0032.
+ *
+ * **Derived from `MAX_CHILDREN_PER_CALL` rather than declared, so the two cannot drift.** The bound is not
+ * decoration: `delegate_all` is capped per call and the fan-out budget bounds a subtree, but a plain blocking
+ * `delegate` spends **nothing** from that budget by design — so thirty sequential `delegate` calls in one agent
+ * run would otherwise hold thirty panes open until it settled.
+ */
+export const MAX_OPEN_PANES = MAX_CHILDREN_PER_CALL;
+/** A run has finished with its pane: the trim may now reclaim it. */
+export function markPaneSettled(tab) {
+    const pane = open.get(tab);
+    if (pane)
+        pane.settled = true;
+}
+/**
+ * Panes opened by THIS process and not yet closed. Keyed by tab id, so a double close is impossible.
+ *
+ * **That keying rests on tab ids being unique, which was measured rather than assumed** (herdr 0.7.5): ids
+ * are `w<workspace>:t<counter>`, allocated by the single server, and **not recycled** — creating a tab,
+ * closing it, and creating again yields the next counter value, never the freed one. If that ever changed,
+ * concurrent panes would collapse into one entry and an early finisher's `untrackPane` would drop a live
+ * sibling. Recorded because the hazard is invisible in the code and the precondition lives in another
+ * project.
+ */
+const open = new Map();
+let hookInstalled = false;
+/** A run has opened a pane. Idempotent per tab, and installs the exit hook on first use only. */
+export function trackPane(pane) {
+    open.set(pane.tab, pane);
+    if (hookInstalled)
+        return;
+    hookInstalled = true;
+    // `once`, and only ever one, so a fan-out of eight children does not install eight handlers and trip
+    // Node's MaxListenersExceededWarning — which would be this package printing a warning about itself.
+    process.once("exit", () => void reapOpenPanes());
+}
+/** A run closed its own pane the normal way. */
+export function untrackPane(tab) {
+    open.delete(tab);
+}
+/** How many panes are currently outstanding — for tests and for `/grants`. */
+export function openPaneCount() {
+    return open.size;
+}
+/** Per-command wall clock. `SIGKILL` because `timeout` alone is not a bound — see `TOTAL_BUDGET_MS`. */
+const PER_CALL_MS = 2000;
+/**
+ * Total wall clock the whole sweep may add to process exit.
+ *
+ * **Measured, and the reason this exists.** With eight panes and a hung herdr, a per-call timeout of 5s
+ * across two calls per pane is **80 seconds of silent hang at shutdown** — `stdio: "ignore"`, so the process
+ * looks wedged with no output. Worse, `timeout` is not a hard bound at all: `spawnSync` sends `SIGTERM` and
+ * then waits for the child to actually die, so a process ignoring `SIGTERM` runs to its own completion
+ * (measured: a 3s timeout took 59.8s against `trap '' TERM; sleep 60`). Hence `killSignal: "SIGKILL"` **and**
+ * a budget across the whole sweep rather than per call.
+ *
+ * A pane left open because the budget ran out is the failure this whole module downgrades to, and it is the
+ * right one: `herdr tab close <id>` is a five-second manual fix, whereas a shell that will not exit is not.
+ */
+const TOTAL_BUDGET_MS = 6000;
+/** Run one herdr command synchronously, swallowing everything: at exit there is nowhere to report. */
+const defaultSyncExec = (args) => {
+    execFileSync("herdr", args, { stdio: "ignore", timeout: PER_CALL_MS, killSignal: "SIGKILL" });
+};
+/**
+ * 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 function reapOpenPanes(syncExec = defaultSyncExec, now = Date.now) {
+    const closed = [];
+    const deadline = now() + TOTAL_BUDGET_MS;
+    for (const pane of [...open.values()]) {
+        // Checked BEFORE each pane rather than after, so the budget bounds what we start, not what we finish.
+        // 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;
+        // 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_DADDY_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 */
+        }
+        // **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, pane) {
+    // **No `agent stop`.** It is not a herdr command — measured against 0.7.5, where it prints the usage banner
+    // and exits 0, which `defaultExec` reports as success. Two call sites here and one in `run-herdr.ts` issued it
+    // for nothing, and `docs/probes/g16-herdr` asserted it worked from a block that was never run. Closing the tab
+    // is the only kill herdr offers, and it does kill the child.
+    const reply = await exec(["tab", "close", pane.tab]).catch(() => undefined);
+    const closed = reply !== undefined && !parseReply(reply).error;
+    if (!closed)
+        return false;
+    if (pane.promptDir)
+        await rm(pane.promptDir, { recursive: true, force: true }).catch(() => undefined);
+    open.delete(pane.tab);
+    return true;
+}
+/**
+ * Close every outstanding pane — the `agent_settled` path (ADR-0032).
+ *
+ * **A separate function from `reapOpenPanes` rather than a shared implementation**, and the reason is not
+ * style. The sync one is `execFileSync` with a six-second total budget *by necessity*: an `exit` handler cannot
+ * await. Running that at `agent_settled` would freeze pi for up to six seconds **every time the operator gets
+ * their prompt back** — turning a feature that exists to make work visible into a stall.
+ *
+ * Both drain the same `Map`, keyed by tab id, so a double close is impossible and a pane herdr refused stays
+ * registered for whichever sweep runs next.
+ *
+ * Sequential rather than concurrent: a fan-out's panes are at most `MAX_OPEN_PANES`, and eight `tab close`
+ * calls in parallel against one herdr server buys nothing worth the burst.
+ */
+export async function reapOpenPanesAsync(exec = defaultExec) {
+    const closed = [];
+    for (const pane of [...open.values()]) {
+        // `keepTab` panes are registered only so their staged prompt can be reaped at `exit`; the tab itself is the
+        // operator's to close.
+        if (pane.keepTab)
+            continue;
+        if (await closePane(exec, pane))
+            closed.push(pane.tab);
+    }
+    return closed;
+}
+/**
+ * Keep at most `MAX_OPEN_PANES` open, closing the oldest first.
+ *
+ * The `Map`'s insertion order **is** the age order, so no timestamp is needed — and that is why `trackPane`
+ * must never re-`set` an existing tab, which would move it to the back of the queue and make an old pane look
+ * new.
+ *
+ * Whatever it closes is returned so the caller can **say so** rather than silently dropping a pane the operator
+ * was reading (R-48's rule, applied to a display).
+ */
+export async function trimOpenPanes(exec = defaultExec) {
+    if (open.size <= MAX_OPEN_PANES)
+        return [];
+    const closed = [];
+    // **Only SETTLED panes are candidates, oldest first.** A live sibling's pane is its child's only terminal, and
+    // closing a tab kills the child — see `OpenPane.settled`. If every open pane is live the cap is exceeded and
+    // nothing is closed, which is the right failure: a pane too many costs an operator a keystroke, and a killed
+    // child costs them the work.
+    //
+    // **Walks past what it cannot close**, rather than attempting `excess` panes from the front and calling it
+    // done. A pane herdr refuses to close used to sit at the head forever, so the cap silently stopped holding
+    // (measured: 30 panes for 30 delegates when every close was refused) and the same corpse was re-attacked on
+    // every spawn — O(n²) round-trips.
+    for (const pane of [...open.values()]) {
+        if (open.size - closed.length <= MAX_OPEN_PANES)
+            break;
+        if (!pane.settled || pane.keepTab)
+            continue;
+        if (await closePane(exec, pane))
+            closed.push(pane.tab);
+    }
+    return closed;
+}
+//# sourceMappingURL=pane-reaper.js.map

package/dist/executors/pane-reaper.js.map

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

package/dist/executors/process-activity.d.ts

@@ -0,0 +1,3 @@
+/** utime + stime ticks and the descendant pids of `rootPid`, as one marker; `undefined` when unreadable. */
+export declare function processTreeActivity(rootPid: number): Promise<string | undefined>;
+//# sourceMappingURL=process-activity.d.ts.map

package/dist/executors/process-activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-activity.d.ts","sourceRoot":"","sources":["../../src/executors/process-activity.ts"],"names":[],"mappings":"AAgBA,4GAA4G;AAC5G,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAoCtF"}

package/dist/executors/process-activity.js

@@ -0,0 +1,59 @@
+/**
+ * Process-tree activity: the signal that is live while a tool call runs.
+ *
+ * pi appends to its session file only when a message or a tool result ends (`agent-session.js`, on `message_end`),
+ * and writes nothing before the first assistant message completes. A child running one twenty-minute `bash` call
+ * is therefore silent on stdout AND on its session file for the whole call, which is exactly the case the
+ * inactivity deadline must not mistake for a hang (review of PR 3e, finding 1). What is live during a tool call is
+ * the work itself: the CPU time consumed by the child and its descendants, and the set of descendants that exist.
+ *
+ * Linux only, read from `/proc`. Elsewhere the probe returns `undefined`, which the runner treats as "no signal",
+ * and the session file and stdout remain the activity sources. A child that consumes no CPU, spawns nothing and
+ * writes nothing for the whole bound (a `sleep`, or a wait on a remote that never answers) is stopped as idle; that
+ * is the intended meaning of the bound.
+ */
+import { readdir, readFile } from "node:fs/promises";
+/** utime + stime ticks and the descendant pids of `rootPid`, as one marker; `undefined` when unreadable. */
+export async function processTreeActivity(rootPid) {
+    if (process.platform !== "linux")
+        return undefined;
+    let entries;
+    try {
+        entries = await readdir("/proc");
+    }
+    catch {
+        return undefined;
+    }
+    const parentOf = new Map();
+    const ticksOf = new Map();
+    await Promise.all(entries
+        .filter((name) => /^\d+$/.test(name))
+        .map(async (name) => {
+        try {
+            const stat = await readFile(`/proc/${name}/stat`, "utf8");
+            // `pid (comm) state ppid ...`; comm may contain spaces or parentheses, so split after the last `)`.
+            const rest = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+            const pid = Number(name);
+            parentOf.set(pid, Number(rest[1]));
+            ticksOf.set(pid, Number(rest[11]) + Number(rest[12]));
+        }
+        catch {
+            /* the process ended between readdir and read */
+        }
+    }));
+    if (!ticksOf.has(rootPid))
+        return undefined;
+    const tree = new Set([rootPid]);
+    let grew = true;
+    while (grew) {
+        grew = false;
+        for (const [pid, ppid] of parentOf)
+            if (tree.has(ppid) && !tree.has(pid))
+                (tree.add(pid), (grew = true));
+    }
+    let ticks = 0;
+    for (const pid of tree)
+        ticks += ticksOf.get(pid) ?? 0;
+    return `${ticks}:${[...tree].sort((a, b) => a - b).join(",")}`;
+}
+//# sourceMappingURL=process-activity.js.map

package/dist/executors/process-activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-activity.js","sourceRoot":"","sources":["../../src/executors/process-activity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAErD,4GAA4G;AAC5G,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACnD,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC3C,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC1C,MAAM,OAAO,CAAC,GAAG,CACf,OAAO;SACJ,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;SACpC,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QAClB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,SAAS,IAAI,OAAO,EAAE,MAAM,CAAC,CAAC;YAC1D,oGAAoG;YACpG,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YAC9D,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;YACzB,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACnC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;QACxD,CAAC;QAAC,MAAM,CAAC;YACP,gDAAgD;QAClD,CAAC;IACH,CAAC,CAAC,CACL,CAAC;IACF,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,GAAG,CAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACxC,IAAI,IAAI,GAAG,IAAI,CAAC;IAChB,OAAO,IAAI,EAAE,CAAC;QACZ,IAAI,GAAG,KAAK,CAAC;QACb,KAAK,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,IAAI,QAAQ;YAAE,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC;IAC3G,CAAC;IACD,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,GAAG,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;AACjE,CAAC"}

package/dist/executors/run-herdr.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Run a governed child in a herdr pane — ADR-0016 point 6.
+ *
+ * The second executor for the same plan. `runChild` spawns `pi` directly and captures its stdout;
+ * `runHerdrPane` asks herdr to launch it in a visible, attachable terminal pane. `planSpawn` produces the
+ * argv either way, so the grant is identical and only the *place it runs* differs.
+ *
+ * **Why go through herdr's CLI rather than the third-party `pi-herdr` extension.** That extension exposes
+ * `agentArgs` and `env` as MODEL-facing tool parameters (R-30), which hands a model an argv array and the
+ * environment variable the grant travels on. Here the model chooses a definition and a task; this package
+ * builds the argv. Measured facts this relies on (`docs/probes/g16-herdr`):
+ *
+ *  - `herdr agent start … -- <args>` delivers argv **verbatim**, echoed back in the reply.
+ *  - `--tools` is enforced inside a pane exactly as it is for a direct spawn; `--no-tools` yields none.
+ *  - `herdr agent start` has **no `--env`**, but `tab create` / `pane split` do, and a pane's environment
+ *    reaches the shell that launches the agent — verified by reading `$PI_DADDY_GRANT` back out of a
+ *    pane created with it. That is how the grant, depth and ledger path propagate on this path.
+ *
+ * **What a pane is not: a boundary.** It is a terminal. `--tools` remains the enforcement point, ADR-0012's
+ * `bash` escape is unchanged, and a pane is *attachable by design*, so a human can type into a governed
+ * child. Humans are not this project's threat model, but nothing here should be read as containing one.
+ */
+import type { ChildRunResult } from "../kernel/run-child.ts";
+import { type HerdrExec } from "./herdr-cli.ts";
+import { type PollTarget } from "./herdr-poll.ts";
+/**
+ * Re-exported so importers of the executor still reach the protocol at the name they always used.
+ *
+ * Deliberate rather than lazy: `test/run-herdr.test.ts` imports `HerdrExec` from here and must pass
+ * **unmodified** across this extraction — that is the only available proof the move changed no behaviour.
+ */
+export { type HerdrExec, parseReply } from "./herdr-cli.ts";
+/** Re-exported: `splitSystemPrompt` moved to `./herdr-stage.ts` under the ceiling, its tests import it here. */
+export { splitSystemPrompt, stageSystemPrompt } from "./herdr-stage.ts";
+/** Re-exported: the name rules moved to `./herdr-name.ts` under the ceiling; tests import them here. */
+export { uniqueAgentName } from "./herdr-name.ts";
+/** Re-exported after startup retry extraction; existing executor importers keep this public constant. */
+export { PANE_READY_POLL_MS } from "./herdr-start.ts";
+/**
+ * Re-exported so `test/run-herdr.test.ts` and any importer keep reaching these where they always were.
+ *
+ * `POLL_INTERVAL_MS` and `newSuffix` moved to `./herdr-poll.ts` under the 400-line ceiling; the names are part
+ * of this module's surface and moving a file should not move an export.
+ */
+export { DEFAULT_SNAPSHOT_LINES, POLL_INTERVAL_MS, readPane, tailLines, waitForLifecycleBaseline, waitForSettled, type PollTarget, } from "./herdr-poll.ts";
+export interface HerdrRunRequest {
+    /** `planSpawn` args **without** the prompt — see `prompt`. */
+    args: string[];
+    /**
+     * The task, delivered with `herdr agent prompt` rather than as an argv element.
+     *
+     * This is strictly safer than the direct-spawn path, which has to defend a model-authored string from
+     * pi's argv parser by prefixing a space (`neutralisePrompt`, `docs/probes/g1-argv`). Here the task never
+     * reaches argv at all, so there is no parser in front of it.
+     */
+    prompt: string;
+    /** Grant/depth/ledger variables. Set on the PANE, which the agent's shell inherits. */
+    env: Record<string, string>;
+    cwd: string;
+    /** Unique pane and agent name. */
+    name: string;
+    /** herdr workspace to create the tab in. Omitted lets herdr choose. */
+    workspace?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    /** Inactivity bound and its progress probe (PR 3e); see `PollTarget`. */
+    idleTimeoutMs?: number;
+    activityProbe?: PollTarget["activityProbe"];
+    maxOutputBytes?: number;
+    /**
+     * Leave the pane open after the run so a human can read or resume it.
+     *
+     * Default **false**: a fan-out that leaks a pane per child fills the operator's workspace, and
+     * `docs/probes/g16-herdr` records that panes are not trivially closable once orphaned.
+     */
+    keepPane?: boolean;
+    exec?: HerdrExec;
+    /**
+     * The pane's last few lines, re-reported every poll — a SNAPSHOT the consumer REPLACES, not appends.
+     *
+     * **Display only**, exactly as in `runChild`: the child's answer is still the returned `text`. Unlike
+     * `runChild`'s `onOutput`, this is not a stream: `agent read` returns a snapshot of a bounded terminal, and
+     * the previous append-shaped design produced an 89,000× amplification once a pane scrolled or passed the
+     * output cap. See `tailLines` in `./herdr-poll.ts`.
+     *
+     * Exceptions are swallowed; a renderer must not be able to break a governed run.
+     */
+    onSnapshot?: (lines: string[]) => void;
+    /** Available pane snapshots only, not a structured session transcript. Never awaited. */
+    onObservation?: (bytes: Uint8Array) => void;
+    /** How many pane lines to report per poll. Defaults to `DEFAULT_SNAPSHOT_LINES`. */
+    snapshotLines?: number;
+    /**
+     * The pane id, reported as soon as `tab create` returns it.
+     *
+     * Separate from `onOutput` because it arrives once and arrives *early*: it is what lets the parent print a
+     * name a human can switch to **while the child is alive**, which is the whole point of the pane surviving.
+     */
+    onPane?: (paneId: string, agentName: string) => void;
+    /** Called only after agent start and prompt both succeed; pane creation alone is still `starting`. */
+    onRunning?: (paneId: string, agentName: string) => void;
+    /** Security hook for attaching a writer lease to the tab. Unlike display callbacks, errors fail the run. */
+    onTab?: (tabId: string) => void;
+    /** Optional observation, unlike the required lease hook above. */
+    onNativeTab?: (tabId: string) => void;
+    onSessionReference?: PollTarget["onSessionReference"];
+    /** Close even a settled pane before releasing a writer lease; no post-lease prompt may remain live. */
+    closeOnSettle?: boolean;
+    /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
+    pollIntervalMs?: number;
+}
+export declare class HerdrWriterCloseError extends Error {
+    constructor(tabId: string);
+}
+/**
+ * Run one governed child in a pane and return its output.
+ *
+ * Deliberately returns `ChildRunResult` — the same shape as `runChild` — so the extension can choose an
+ * executor without knowing which one it got.
+ */
+export declare function runHerdrPane(request: HerdrRunRequest): Promise<ChildRunResult>;
+//# sourceMappingURL=run-herdr.d.ts.map

package/dist/executors/run-herdr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-herdr.d.ts","sourceRoot":"","sources":["../../src/executors/run-herdr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAG7D,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AACzE,OAAO,EAML,KAAK,UAAU,EAChB,MAAM,iBAAiB,CAAC;AAMzB;;;;;GAKG;AACH,OAAO,EAAE,KAAK,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5D,gHAAgH;AAChH,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACxE,wGAAwG;AACxG,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,yGAAyG;AACzG,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD;;;;;GAKG;AACH,OAAO,EACL,sBAAsB,EACtB,gBAAgB,EAChB,QAAQ,EACR,SAAS,EACT,wBAAwB,EACxB,cAAc,EACd,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,IAAI,EAAE,MAAM,EAAE,CAAC;IACf;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;IAC5C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACvC,yFAAyF;IACzF,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,oFAAoF;IACpF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACrD,sGAAsG;IACtG,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IACxD,4GAA4G;IAC5G,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,kBAAkB,CAAC,EAAE,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACtD,uGAAuG;IACvG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kGAAkG;IAClG,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,KAAK,EAAE,MAAM;CAI1B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAkRpF"}