pi-daddy 0.13.0

package/dist/resolve.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Grant resolution — the entire security surface of capability governance, as a pure function.
+ *
+ * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
+ * tree. Escalation is impossible by construction rather than by policy, because a parent can never
+ * confer what it does not itself hold.
+ *
+ *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
+ *
+ * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
+ * is the only place an escalation could be introduced.
+ */
+/** `tool:read` · `ext:pi-web-access/web_search` · `skill:review` · `agent:researcher` */
+export type Capability = string;
+/**
+ * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
+ * whole catalog, so they can never be a *narrowing* grant.
+ *
+ * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
+ * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
+ * spawned a grandchild that wrote to disk. See docs/probes/pi-fabric-eval (probes 2, 4, 7, 8).
+ */
+export declare const UNIVERSAL_CAPABILITIES: readonly Capability[];
+/**
+ * Capabilities that functionally contain others.
+ *
+ * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
+ * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
+ * two purposes:
+ *
+ *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
+ *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
+ *     look like an escalation from any normal parent — despite being strictly weaker.
+ *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
+ *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
+ */
+export declare const SUBSUMPTION: Readonly<Record<Capability, readonly Capability[]>>;
+/** Expand a grant to everything it functionally confers. */
+export declare function expandSubsumed(grant: Capability[]): Capability[];
+/**
+ * "Any definition" — ADR-0023, and one of two wildcards this module understands.
+ *
+ * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
+ * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
+ * what makes importing `WILDCARD` back safe.
+ *
+ * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
+ * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
+ * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
+ */
+export declare const AGENT_WILDCARD: Capability;
+export interface ResolveInput {
+    /** What the delegating agent asked to give the child. */
+    requested: Capability[];
+    /** What the delegating agent itself holds. The root's grant is configured, never defaulted to all. */
+    parentGrant: Capability[];
+    /** Declarative maximum for the child's agent type (its frontmatter). Omit for no ceiling. */
+    ceiling?: Capability[];
+    /** Destructive capabilities that may never enter a grant without explicit human approval. */
+    gated?: Capability[];
+    /** Gated capabilities a human has approved for this specific spawn. */
+    approved?: Capability[];
+    /**
+     * Honour functional subsumption when deciding what the parent covers (default true).
+     * Set false for a strict name-equality check.
+     */
+    subsumption?: boolean;
+}
+export interface ResolveResult {
+    /** The capability set the child may hold. */
+    effective: Capability[];
+    /** Requested but NOT held by the parent — the escalation-attempt signal. Log every one. */
+    denied: Capability[];
+    /** Held by the parent but outside the child type's declared ceiling. */
+    clipped: Capability[];
+    /** Allowed by the tree but gated and unapproved. */
+    gatedBlocked: Capability[];
+    /** Universal capabilities that survived resolution — see `assertNarrowing`. */
+    universal: Capability[];
+    /**
+     * Capabilities the parent covers only through subsumption, not by holding them directly — e.g. `grep`
+     * covered because the parent holds `bash`. Non-empty means the grant is broader than its list suggests.
+     */
+    subsumedBy: Capability[];
+}
+/**
+ * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
+ * than silently dropped, because a grant nobody can audit proves nothing.
+ */
+export declare function resolve(input: ResolveInput): ResolveResult;
+/**
+ * Fail closed on a grant that cannot actually narrow anything.
+ *
+ * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
+ * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
+ * discover this at runtime.
+ */
+export declare function assertNarrowing(result: ResolveResult, allowUniversal?: boolean): void;
+/**
+ * Project an effective grant onto pi's `--tools` allowlist.
+ *
+ * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
+ * (docs/probes/pi-fabric-eval probes 9–11). That is why enforcement needs no in-descendant runtime.
+ *
+ * Returns `null` when the grant contains no callable tools, meaning the caller should pass
+ * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
+ */
+export declare function toPiToolsAllowlist(effective: Capability[]): string[] | null;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC;AAEhC;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,UAAU,EAGvD,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,UAAU,EAAE,CAAC,CAU3E,CAAC;AAEF,4DAA4D;AAC5D,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,UAAU,EAAE,CAMhE;AAID;;;;;;;;;;GAUG;AACH,eAAO,MAAM,cAAc,EAAE,UAAsB,CAAC;AAEpD,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,sGAAsG;IACtG,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,6FAA6F;IAC7F,OAAO,CAAC,EAAE,UAAU,EAAE,CAAC;IACvB,6FAA6F;IAC7F,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,UAAU,EAAE,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,2FAA2F;IAC3F,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,wEAAwE;IACxE,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,oDAAoD;IACpD,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB;;;OAGG;IACH,UAAU,EAAE,UAAU,EAAE,CAAC;CAC1B;AAID;;;GAGG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CA6E1D;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,aAAa,EAAE,cAAc,UAAQ,GAAG,IAAI,CAQnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,UAAU,EAAE,GAAG,MAAM,EAAE,GAAG,IAAI,CAQ3E"}

package/dist/resolve.js

@@ -0,0 +1,181 @@
+/**
+ * Grant resolution — the entire security surface of capability governance, as a pure function.
+ *
+ * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
+ * tree. Escalation is impossible by construction rather than by policy, because a parent can never
+ * confer what it does not itself hold.
+ *
+ *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
+ *
+ * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
+ * is the only place an escalation could be introduced.
+ */
+/**
+ * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
+ * whole catalog, so they can never be a *narrowing* grant.
+ *
+ * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
+ * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
+ * spawned a grandchild that wrote to disk. See docs/probes/pi-fabric-eval (probes 2, 4, 7, 8).
+ */
+export const UNIVERSAL_CAPABILITIES = [
+    "ext:pi-fabric/fabric_exec",
+    "tool:fabric_exec",
+];
+/**
+ * Capabilities that functionally contain others.
+ *
+ * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
+ * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
+ * two purposes:
+ *
+ *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
+ *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
+ *     look like an escalation from any normal parent — despite being strictly weaker.
+ *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
+ *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
+ */
+export const SUBSUMPTION = {
+    "tool:bash": [
+        "tool:grep",
+        "tool:find",
+        "tool:ls",
+        "tool:read",
+        "tool:write",
+        "tool:edit",
+        "tool:edit-diff",
+    ],
+};
+/** Expand a grant to everything it functionally confers. */
+export function expandSubsumed(grant) {
+    const expanded = new Set(grant);
+    for (const held of grant) {
+        for (const implied of SUBSUMPTION[held] ?? [])
+            expanded.add(implied);
+    }
+    return [...expanded].sort();
+}
+import { WILDCARD } from "./pi-tools.js";
+/**
+ * "Any definition" — ADR-0023, and one of two wildcards this module understands.
+ *
+ * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
+ * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
+ * what makes importing `WILDCARD` back safe.
+ *
+ * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
+ * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
+ * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
+ */
+export const AGENT_WILDCARD = "agent:*";
+const unique = (xs) => [...new Set(xs)].sort();
+/**
+ * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
+ * than silently dropped, because a grant nobody can audit proves nothing.
+ */
+export function resolve(input) {
+    const requested = unique(input.requested);
+    const held = new Set(input.parentGrant);
+    const parent = input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
+    /**
+     * `agent:*` covers any `agent:<name>` — ADR-0023, and the ONLY wildcard rule in this function.
+     *
+     * `resolve` is otherwise exact-match plus subsumption, deliberately: `tool:*` works not because anything
+     * here understands it, but because `deriveOwnGrant` *enumerates* a session's observed tool names beside
+     * it. Definitions are not tools, so nothing enumerates them — which is why `maySpawnDefinition` had to
+     * special-case the wildcard, and why this needs stating rather than falling out.
+     *
+     * Scoped to one namespace on purpose. There is no generalised `<ns>:*` rule, so a namespace added later
+     * does not silently acquire a wildcard; adding one is a deliberate edit and another decision.
+     */
+    const anyDefinition = held.has(AGENT_WILDCARD);
+    /**
+     * `tool:*` satisfies **any** capability, including `skill:` and `agent:` ids.
+     *
+     * Missing until 0.11.2, and the omission broke the one rule this package must never break by accident:
+     * *governance is opt-in*. An ungoverned session holds `[tool:*, …observed tools]` and nothing else, so
+     * spawning a definition whose `allowed-tools` names `agent:worker` or `skill:review` — the composition
+     * ADR-0017 created and ADR-0023's own example uses — was refused with **"capability escalation
+     * blocked"**, and recorded as an escalation attempt, in a session that had opted out.
+     *
+     * `maySpawnDefinition` had always honoured `tool:*` for definition ids and `docs/SPEC.md` had always
+     * claimed it "satisfies any capability". This function disagreed with both, which is R-28's shape: two
+     * spellings of one rule, and the enforcing one was wrong.
+     */
+    const anyCapability = held.has(WILDCARD);
+    const covered = (c) => parent.has(c) || anyCapability || (anyDefinition && c.startsWith("agent:"));
+    const ceiling = input.ceiling === undefined ? null : new Set(input.ceiling);
+    const gated = new Set(input.gated ?? []);
+    const approved = new Set(input.approved ?? []);
+    // Order is irrelevant to the outcome (set intersection is commutative), so each rejection reason is
+    // reported independently rather than being masked by whichever filter happened to run first.
+    const denied = requested.filter((c) => !covered(c));
+    const clipped = requested.filter((c) => covered(c) && ceiling !== null && !ceiling.has(c));
+    /**
+     * Is this capability gated, directly or by subsuming something gated?
+     *
+     * ADR-0012. Exact-name gating was defeatable by handing down a broader capability: the package's own
+     * `SUBSUMPTION` table says `bash` confers `write`, so gating `write` produced **no prompt** when `bash`
+     * was granted instead. The gate read as satisfied because the string never appeared.
+     *
+     * The direction is load-bearing and easy to invert. A capability is gated when it **subsumes**
+     * something gated — never when it **is subsumed by** something gated. Gating `bash` must not quietly
+     * gate a plain `write` grant, which would make gating a broad capability restrict the narrow ones and
+     * invert least privilege.
+     */
+    const isGated = (c) => {
+        if (gated.has(c))
+            return true;
+        if (input.subsumption === false)
+            return false;
+        return (SUBSUMPTION[c] ?? []).some((implied) => gated.has(implied));
+    };
+    const gatedBlocked = requested.filter((c) => covered(c) && (ceiling === null || ceiling.has(c)) && isGated(c) && !approved.has(c));
+    const rejected = new Set([...denied, ...clipped, ...gatedBlocked]);
+    const effective = requested.filter((c) => !rejected.has(c));
+    return {
+        effective,
+        denied,
+        clipped,
+        gatedBlocked,
+        universal: effective.filter((c) => UNIVERSAL_CAPABILITIES.includes(c)),
+        // F9: capabilities covered by a WILDCARD are not "subsumed" — this field means "the grant is broader
+        // than its list suggests", which is the `bash`-covers-`grep` warning. A wildcard holder already knows
+        // its grant is broad; listing every id under it would bury the signal the field exists to carry.
+        subsumedBy: effective.filter((c) => !held.has(c) && !anyCapability && !(anyDefinition && c.startsWith("agent:"))),
+    };
+}
+/**
+ * Fail closed on a grant that cannot actually narrow anything.
+ *
+ * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
+ * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
+ * discover this at runtime.
+ */
+export function assertNarrowing(result, allowUniversal = false) {
+    if (!allowUniversal && result.universal.length > 0) {
+        throw new Error(`refusing to issue a grant containing universal capabilities: ${result.universal.join(", ")}. ` +
+            `These transitively confer the whole catalog, so the grant would not narrow anything. ` +
+            `Pass allowUniversal to override deliberately.`);
+    }
+}
+/**
+ * Project an effective grant onto pi's `--tools` allowlist.
+ *
+ * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
+ * (docs/probes/pi-fabric-eval probes 9–11). That is why enforcement needs no in-descendant runtime.
+ *
+ * Returns `null` when the grant contains no callable tools, meaning the caller should pass
+ * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
+ */
+export function toPiToolsAllowlist(effective) {
+    const names = effective
+        .filter((c) => c.startsWith("tool:") || c.startsWith("ext:"))
+        // `tool:read` -> `read`; `ext:pkg/web_search` -> `web_search` (pi matches on bare tool name)
+        .map((c) => (c.startsWith("tool:") ? c.slice(5) : c.slice(c.lastIndexOf("/") + 1)))
+        .filter((n) => n.length > 0);
+    const deduped = [...new Set(names)].sort();
+    return deduped.length > 0 ? deduped : null;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

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

package/dist/run-child.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Run a governed child process under hard limits.
+ *
+ * G8 (review findings A-R1/B-I5, A-R3). `delegate` used to spawn `pi` with no output cap, no timeout,
+ * an abort listener attached too late to observe an already-aborted signal, and a non-zero exit reported
+ * to the model as an ordinary result. Each of those is a way for a child to outlive or overwhelm the
+ * orchestrator that is supposed to be governing it — which is the whole premise of this package.
+ *
+ * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
+ */
+/**
+ * Operator override for the child wall-clock limit, in seconds.
+ *
+ * Deliberately NOT in `GRANT_ENV_KEYS`: those are stripped from a child's environment and re-supplied
+ * only by the spawn plan, which is right for capability state and wrong for an operator preference. This
+ * one should simply inherit, so a bound set at the root applies all the way down.
+ */
+export declare const ENV_CHILD_TIMEOUT = "PI_GRANTS_CHILD_TIMEOUT";
+/** Read the override, falling back to the default on absent *or* malformed input (G7's rule). */
+export declare function timeoutFromEnv(raw: string | undefined): number;
+export interface ChildRunRequest {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    signal?: AbortSignal;
+    /** Hard cap on captured output. Beyond it the child is killed and the result flagged. */
+    maxOutputBytes?: number;
+    /** Wall-clock cap. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. */
+    timeoutMs?: number;
+    killGraceMs?: number;
+}
+export interface ChildRunResult {
+    /** Exit code, or `null` when nothing was spawned or the child was killed by a signal. */
+    code: number | null;
+    text: string;
+    truncated: boolean;
+    timedOut: boolean;
+    aborted: boolean;
+    /** Set when the process could not be started at all. */
+    spawnError?: string;
+}
+/** 1 MiB. A delegation returns a summary; anything larger is a runaway, not an answer. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/** 10 minutes. Long enough for a real sub-agent task, short enough that a hang is not forever. */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** Grace between SIGTERM and SIGKILL. A child that ignores SIGTERM must not make the timeout advisory. */
+export declare const DEFAULT_KILL_GRACE_MS = 5000;
+export declare function runChild(request: ChildRunRequest): Promise<ChildRunResult>;
+//# sourceMappingURL=run-child.d.ts.map

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

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

package/dist/run-child.js

@@ -0,0 +1,109 @@
+/**
+ * Run a governed child process under hard limits.
+ *
+ * G8 (review findings A-R1/B-I5, A-R3). `delegate` used to spawn `pi` with no output cap, no timeout,
+ * an abort listener attached too late to observe an already-aborted signal, and a non-zero exit reported
+ * to the model as an ordinary result. Each of those is a way for a child to outlive or overwhelm the
+ * orchestrator that is supposed to be governing it — which is the whole premise of this package.
+ *
+ * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
+ */
+import { spawn } from "node:child_process";
+import { parseBound } from "./propagation.js";
+/**
+ * Operator override for the child wall-clock limit, in seconds.
+ *
+ * Deliberately NOT in `GRANT_ENV_KEYS`: those are stripped from a child's environment and re-supplied
+ * only by the spawn plan, which is right for capability state and wrong for an operator preference. This
+ * one should simply inherit, so a bound set at the root applies all the way down.
+ */
+export const ENV_CHILD_TIMEOUT = "PI_GRANTS_CHILD_TIMEOUT";
+/** Read the override, falling back to the default on absent *or* malformed input (G7's rule). */
+export function timeoutFromEnv(raw) {
+    const seconds = parseBound(raw);
+    // `null` (malformed) and `0` both fall back rather than disabling the limit: a timeout that can be
+    // switched off by a typo is the A-S4 defect wearing different clothes.
+    return seconds === undefined || seconds === null || seconds === 0 ? DEFAULT_TIMEOUT_MS : seconds * 1000;
+}
+/** 1 MiB. A delegation returns a summary; anything larger is a runaway, not an answer. */
+export const DEFAULT_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** 10 minutes. Long enough for a real sub-agent task, short enough that a hang is not forever. */
+export const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+/** Grace between SIGTERM and SIGKILL. A child that ignores SIGTERM must not make the timeout advisory. */
+export const DEFAULT_KILL_GRACE_MS = 5000;
+export function runChild(request) {
+    const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const killGraceMs = request.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    // A-R3: checked BEFORE spawning. `AbortSignal` does not replay, so a listener attached after an
+    // `await` cannot observe an abort that already happened — and the child would then run to completion
+    // outside the cancellation that was supposed to stop it. Nothing is started at all here.
+    if (request.signal?.aborted) {
+        return Promise.resolve({ code: null, text: "", truncated: false, timedOut: false, aborted: true });
+    }
+    return new Promise((settle) => {
+        let child;
+        try {
+            child = spawn(request.command, request.args, {
+                env: request.env,
+                cwd: request.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch (error) {
+            settle({ code: null, text: "", truncated: false, timedOut: false, aborted: false, spawnError: String(error) });
+            return;
+        }
+        let text = "";
+        let bytes = 0;
+        let truncated = false;
+        let timedOut = false;
+        let aborted = false;
+        let done = false;
+        const timers = [];
+        const clearTimers = () => timers.forEach(clearTimeout);
+        /** SIGTERM, then SIGKILL if the child is still alive — so a handler cannot ignore its way out. */
+        const stop = () => {
+            child.kill("SIGTERM");
+            timers.push(setTimeout(() => child.kill("SIGKILL"), killGraceMs));
+        };
+        const capture = (chunk) => {
+            if (truncated)
+                return;
+            const s = String(chunk);
+            bytes += Buffer.byteLength(s);
+            if (bytes > maxOutputBytes) {
+                // Keep what fits, mark it, and stop the child: an unbounded producer must not be able to
+                // exhaust the orchestrator's memory just because it was granted a tool that prints.
+                text += s;
+                text = text.slice(0, maxOutputBytes);
+                truncated = true;
+                stop();
+                return;
+            }
+            text += s;
+        };
+        child.stdout?.on("data", capture);
+        child.stderr?.on("data", capture);
+        timers.push(setTimeout(() => {
+            timedOut = true;
+            stop();
+        }, timeoutMs));
+        const onAbort = () => {
+            aborted = true;
+            stop();
+        };
+        request.signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimers();
+            request.signal?.removeEventListener("abort", onAbort);
+            settle(result);
+        };
+        child.on("error", (error) => finish({ code: null, text, truncated, timedOut, aborted, spawnError: String(error) }));
+        child.on("close", (code) => finish({ code, text, truncated, timedOut, aborted }));
+    });
+}
+//# sourceMappingURL=run-child.js.map

package/dist/run-child.js.map

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

package/dist/run-herdr.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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_GRANTS_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 "./run-child.ts";
+/** One herdr CLI invocation. Injectable so every rule below is testable without herdr installed. */
+export type HerdrExec = (args: string[]) => Promise<{
+    code: number | null;
+    stdout: string;
+    stderr: string;
+}>;
+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;
+    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;
+}
+/**
+ * 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;
+};
+/** How often to poll `agent get` while waiting for the child to settle. */
+export declare const POLL_INTERVAL_MS = 750;
+/** How often to retry `agent start` while a freshly created pane is still reaching its shell prompt. */
+export declare const PANE_READY_POLL_MS = 300;
+/**
+ * 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/run-herdr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-herdr.d.ts","sourceRoot":"","sources":["../src/run-herdr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAMH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,oGAAoG;AACpG,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7G,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,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAI3F;AAKD,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,wGAAwG;AACxG,eAAO,MAAM,kBAAkB,MAAM,CAAC;AA8BtC;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA8HpF"}