pi-daddy 0.13.0

package/dist/run-herdr.js

@@ -0,0 +1,306 @@
+/**
+ * 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 { execFile } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS } from "./run-child.js";
+import { trackPane, untrackPane } from "./pane-reaper.js";
+/**
+ * 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] };
+}
+/** Statuses herdr reports for a settled agent. `blocked` counts: it is waiting for a human, not working. */
+const TERMINAL = new Set(["idle", "done", "blocked"]);
+/** How often to poll `agent get` while waiting for the child to settle. */
+export const POLL_INTERVAL_MS = 750;
+/** How often to retry `agent start` while a freshly created pane is still reaching its shell prompt. */
+export const PANE_READY_POLL_MS = 300;
+const defaultExec = (args) => new Promise((settle) => {
+    execFile("herdr", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+        const code = error && typeof error.code === "number" ? error.code : error ? 1 : 0;
+        settle({ code, stdout: String(stdout), stderr: String(stderr) });
+    });
+});
+/**
+ * Parse herdr's JSON envelope. Every command replies `{id, result}` or `{id, error:{code,message}}`.
+ *
+ * `stderr` is folded into the message because the first end-to-end run failed with an EMPTY stdout and the
+ * real reason on stderr, producing the useless diagnostic "unparseable herdr reply: ". A wrapper that
+ * hides the substrate's own error message costs more time than it saves.
+ */
+function parseReply(reply) {
+    try {
+        const parsed = JSON.parse(reply.stdout);
+        if (parsed.error)
+            return { error: parsed.error.message ?? parsed.error.code ?? "herdr reported an error" };
+        return { result: parsed.result };
+    }
+    catch {
+        // A non-JSON reply is a herdr-version or PATH problem, not a governance decision. Surfaced as a spawn
+        // error so the caller reports "could not start" rather than "the child produced nothing".
+        const detail = [reply.stdout.trim(), reply.stderr.trim()].filter((t) => t.length > 0).join(" | ");
+        return { error: `unparseable herdr reply: ${detail.slice(0, 300) || "(no output)"}` };
+    }
+}
+/**
+ * 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 async function runHerdrPane(request) {
+    const exec = request.exec ?? defaultExec;
+    const timeoutMs = request.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxOutputBytes = request.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    const deadline = Date.now() + timeoutMs;
+    const empty = { code: null, text: "", truncated: false, timedOut: false, aborted: false };
+    // A-R3's rule, kept on this path too: checked BEFORE anything is created. An `AbortSignal` does not
+    // replay, so a check after the first `await` cannot see an abort that already happened — and we would
+    // have left a pane behind for a run that was never wanted.
+    if (request.signal?.aborted)
+        return { ...empty, aborted: true };
+    // `--print` makes pi process the prompt and exit, so it never reaches the interactive readiness that
+    // `herdr agent start` waits for — the agent is simply never detected. Found by the first end-to-end run,
+    // which failed inside herdr with an empty reply. Caught here instead, naming the flag, because a
+    // mismatch between a plan and its executor is a caller bug and should read like one.
+    if (request.args.includes("--print") || request.args.includes("-p")) {
+        return {
+            ...empty,
+            spawnError: "herdr needs an INTERACTIVE agent, but the plan contains --print, which makes pi exit immediately " +
+                "and never be detected. Build the plan with `print: false` for this executor.",
+        };
+    }
+    // A multi-line system prompt becomes a file; see `splitSystemPrompt`. Removed in `cleanup`, so a
+    // definition's instructions do not accumulate in /tmp across a fan-out.
+    const split = splitSystemPrompt(request.args);
+    let promptDir;
+    let effectiveArgs = split.args;
+    if (split.systemPrompt !== undefined) {
+        try {
+            promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
+            const file = join(promptDir, "system-prompt.md");
+            await writeFile(file, split.systemPrompt, "utf8");
+            effectiveArgs = [...split.args, "--append-system-prompt", file];
+        }
+        catch (error) {
+            return { ...empty, spawnError: `could not stage the system prompt for herdr: ${String(error)}` };
+        }
+    }
+    const create = ["tab", "create", "--label", request.name, "--cwd", request.cwd];
+    if (request.workspace)
+        create.push("--workspace", request.workspace);
+    for (const [key, value] of Object.entries(request.env))
+        create.push("--env", `${key}=${value}`);
+    const created = parseReply(await exec(create));
+    if (created.error)
+        return { ...empty, spawnError: `herdr tab create failed: ${created.error}` };
+    const rootPane = (created.result?.root_pane ?? {});
+    const paneId = rootPane.pane_id;
+    const tabId = rootPane.tab_id;
+    // **Tracked BEFORE the pane-id check, not after.** A tab can exist from the moment this reply is parsed,
+    // so registering later leaves a window — one herdr round-trip wide — in which a killed process orphans a
+    // tab nothing would reap. The normal path had no such window and the error path did, which is backwards:
+    // the error path is the one more likely to be taken while something is already going wrong.
+    if (tabId && !request.keepPane)
+        trackPane({ tab: tabId, name: request.name, promptDir });
+    if (!paneId) {
+        // The tab may exist even though the reply carried no pane id, and this return used to be BEFORE
+        // `cleanup` was defined — so the one path where herdr half-succeeded was the one that leaked a tab.
+        if (tabId && !request.keepPane) {
+            const reply = await exec(["tab", "close", tabId]).catch(() => undefined);
+            // Same rule as `cleanup`: untrack only what is provably gone, so a close herdr refused stays the
+            // reaper's problem rather than being dropped on the assumption that it worked.
+            if (reply !== undefined && !parseReply(reply).error)
+                untrackPane(tabId);
+        }
+        // `keepPane` keeps the staged prompt for the same reason `cleanup` does — a human inspecting the pane
+        // may want to see what the child was told. This branch used to remove it unconditionally, which threw
+        // that away on the one path where there is no agent in the pane to ask instead.
+        if (promptDir && !request.keepPane)
+            await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+        return { ...empty, spawnError: "herdr tab create returned no pane id" };
+    }
+    /** Close what we opened, whatever happened. A leaked pane per child is how fan-out fills a workspace. */
+    const cleanup = async () => {
+        await exec(["agent", "stop", request.name]).catch(() => undefined);
+        let closed = false;
+        if (!request.keepPane && tabId) {
+            // **The reply must be PARSED, not merely awaited.** `defaultExec` resolves with `{code: 1}` on
+            // failure and never rejects, so the `.catch` here was dead code and a herdr that REFUSED to close the
+            // pane looked identical to one that closed it. The pane was then untracked, so the exit reaper — the
+            // one thing built for exactly this failure — would not retry it. The single case the reaper exists
+            // for was the case that disabled it.
+            const reply = await exec(["tab", "close", tabId]).catch(() => undefined);
+            closed = reply !== undefined && !parseReply(reply).error;
+        }
+        // Kept when the pane is kept: a human inspecting the pane may want to see what the child was told.
+        if (promptDir && !request.keepPane)
+            await rm(promptDir, { recursive: true, force: true }).catch(() => undefined);
+        // Untrack only what is genuinely gone. A pane we failed to close stays registered so `exit` tries once
+        // more; `openPaneCount()` is what a test asserts to prove the registry does not grow per delegation.
+        if (tabId && (closed || request.keepPane))
+            untrackPane(tabId);
+    };
+    try {
+        const started = await startAgent(exec, request.name, paneId, effectiveArgs, deadline);
+        if (started.error)
+            return { ...empty, spawnError: `herdr agent start failed: ${started.error}` };
+        // The state counter BEFORE prompting is what makes the wait correct — see the R-33 note below.
+        const before = seqOf(started.result);
+        const prompted = parseReply(await exec(["agent", "prompt", request.name, request.prompt]));
+        if (prompted.error)
+            return { ...empty, spawnError: `herdr agent prompt failed: ${prompted.error}` };
+        const settled = await waitForSettled(exec, request, before, deadline);
+        if (settled.aborted || settled.timedOut) {
+            // Still read: a timed-out child usually produced something, and a partial answer labelled partial is
+            // more useful than none. R-03's rule — a missing result must never look like an empty one.
+            const partial = await readPane(exec, request.name, maxOutputBytes);
+            return { ...empty, ...settled, text: partial.text, truncated: partial.truncated };
+        }
+        if (settled.spawnError)
+            return { ...empty, spawnError: settled.spawnError };
+        const out = await readPane(exec, request.name, maxOutputBytes);
+        return {
+            code: settled.status === "blocked" ? 1 : 0,
+            text: settled.status === "blocked"
+                ? `${out.text}\n\n[grants] this agent is BLOCKED waiting for a human in pane ${paneId}.`
+                : out.text,
+            truncated: out.truncated,
+            timedOut: false,
+            aborted: false,
+        };
+    }
+    finally {
+        await cleanup();
+    }
+}
+/**
+ * Start the agent, retrying while the pane is still coming up.
+ *
+ * **Measured, and only visible once automated.** A pane created by `tab create` is not immediately at a
+ * shell prompt, and `herdr agent start` requires one — it fails with
+ * `agent_pane_busy: … is not an available shell`. Driving the two commands by hand hid this completely,
+ * because the think-time between them was longer than the shell took to start; the first scripted run hit
+ * it every time.
+ *
+ * Retried rather than preceded by a fixed sleep: a sleep long enough for a loaded machine is wasted on
+ * every spawn, and a fan-out pays it per child. Only the busy condition is retried — any other error is a
+ * real failure and returns immediately.
+ */
+async function startAgent(exec, name, paneId, args, deadline) {
+    for (;;) {
+        const reply = parseReply(await exec(["agent", "start", name, "--kind", "pi", "--pane", paneId, "--", ...args]));
+        if (!reply.error)
+            return reply;
+        const busy = /not an available shell|agent_pane_busy/.test(reply.error);
+        if (!busy || Date.now() >= deadline)
+            return reply;
+        await new Promise((r) => setTimeout(r, PANE_READY_POLL_MS));
+    }
+}
+function seqOf(result) {
+    const agent = (result?.agent ?? {});
+    return typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+}
+/**
+ * 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".
+ */
+async function waitForSettled(exec, request, before, deadline) {
+    for (;;) {
+        if (request.signal?.aborted)
+            return { aborted: true };
+        if (Date.now() >= deadline)
+            return { timedOut: true };
+        const reply = parseReply(await exec(["agent", "get", request.name]));
+        if (reply.error)
+            return { spawnError: `herdr agent get failed: ${reply.error}` };
+        const agent = (reply.result?.agent ?? reply.result ?? {});
+        const status = agent.agent_status;
+        const seq = typeof agent.state_change_seq === "number" ? agent.state_change_seq : -1;
+        if (status && TERMINAL.has(status) && seq > before)
+            return { status };
+        await new Promise((r) => setTimeout(r, Math.min(POLL_INTERVAL_MS, Math.max(0, deadline - Date.now()))));
+    }
+}
+/**
+ * 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.
+ */
+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: `[grants] could not read the agent pane: ${parsed.error.message ?? "unknown error"}`, truncated: false };
+        }
+        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.
+    return { text: text.slice(-maxOutputBytes), truncated: true };
+}
+//# sourceMappingURL=run-herdr.js.map

package/dist/run-herdr.js.map

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

package/dist/spawn.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Build the argv for a governed descendant pi process.
+ *
+ * The enforcement point is pi core, not this package: `--tools` and `--no-tools` hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them (verified,
+ * docs/probes/pi-fabric-eval probes 9–11). So governance reduces to "compute the allowlist correctly
+ * and hand it to pi", with no runtime inside the descendant.
+ */
+import { type Capability } from "./resolve.ts";
+export interface SpawnPlanInput {
+    effective: Capability[];
+    prompt: string;
+    model?: string;
+    provider?: string;
+    thinking?: string;
+    /** Session file path, or omit for an ephemeral child. */
+    sessionFile?: string;
+    /** Non-interactive by default: a governed child should not prompt a human. */
+    print?: boolean;
+    /**
+     * Absolute path per skill NAME (`review` -> `/…/review`), as the catalog discovered them.
+     *
+     * R-32. Only skills named by a `skill:` capability in `effective` are passed, and a granted skill
+     * absent from this map is reported in `unresolvedSkills` rather than dropped.
+     */
+    skillPaths?: Record<string, string>;
+    /**
+     * Let the child load `AGENTS.md` / `CLAUDE.md`. **Default false** — see the `--no-context-files`
+     * note in `planSpawn`.
+     */
+    contextFiles?: boolean;
+    /**
+     * Instructions appended to the child's system prompt — a definition's `SKILL.md` body (ADR-0016).
+     *
+     * Appended rather than replacing, so pi's own coding-assistant prompt survives underneath and a
+     * definition only has to describe its own job.
+     */
+    systemPrompt?: string;
+}
+export interface SpawnPlan {
+    args: string[];
+    /** The tool names pi will allow, for the ledger. `null` means no tools at all. */
+    allowlist: string[] | null;
+    /** Skill paths handed to the child, for the ledger. */
+    skills: string[];
+    /**
+     * Granted `skill:` capabilities with no known path. **Non-empty means the caller should refuse**:
+     * the child would silently lack a capability its grant says it holds.
+     */
+    unresolvedSkills: Capability[];
+}
+/**
+ * Produce `pi` arguments enforcing `effective`.
+ *
+ * Note the `--no-tools` branch: pi rejects an empty `--tools` list, and passing no flag at all would
+ * silently fall back to pi's defaults — which is the opposite of a zero grant. An empty grant must be
+ * expressed explicitly.
+ */
+export declare function planSpawn(input: SpawnPlanInput): SpawnPlan;
+//# sourceMappingURL=spawn.d.ts.map

package/dist/spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spawn.d.ts","sourceRoot":"","sources":["../src/spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,UAAU,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kFAAkF;IAClF,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC3B,uDAAuD;IACvD,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB;;;OAGG;IACH,gBAAgB,EAAE,UAAU,EAAE,CAAC;CAChC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,CA8D1D"}

package/dist/spawn.js

@@ -0,0 +1,116 @@
+/**
+ * Build the argv for a governed descendant pi process.
+ *
+ * The enforcement point is pi core, not this package: `--tools` and `--no-tools` hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them (verified,
+ * docs/probes/pi-fabric-eval probes 9–11). So governance reduces to "compute the allowlist correctly
+ * and hand it to pi", with no runtime inside the descendant.
+ */
+import { toPiToolsAllowlist } from "./resolve.js";
+/**
+ * Produce `pi` arguments enforcing `effective`.
+ *
+ * Note the `--no-tools` branch: pi rejects an empty `--tools` list, and passing no flag at all would
+ * silently fall back to pi's defaults — which is the opposite of a zero grant. An empty grant must be
+ * expressed explicitly.
+ */
+export function planSpawn(input) {
+    const allowlist = toPiToolsAllowlist(input.effective);
+    const args = [];
+    if (input.print !== false)
+        args.push("--print");
+    if (input.provider)
+        args.push("--provider", input.provider);
+    if (input.model)
+        args.push("--model", input.model);
+    if (input.thinking)
+        args.push("--thinking", input.thinking);
+    if (input.sessionFile)
+        args.push("--session", input.sessionFile);
+    else
+        args.push("--no-session");
+    // Disable discovery so ambient user extensions cannot widen a governed child's surface. Explicit
+    // `-e` paths would still load, so this package never passes one.
+    args.push("--no-extensions");
+    // R-32. `--no-extensions` governs EXTENSIONS ONLY — measured, not assumed: a child spawned with
+    // `--tools read` still loaded all eight of the operator's skills and `CLAUDE.md`
+    // (`docs/probes/g16-herdr` §4-5). Skills are injected into the system prompt rather than passed as
+    // tools, so `--tools` cannot reach them and the `skill:` namespace enforced nothing at all.
+    //
+    // `--no-skills` is unconditional and `--skill` is added on top, because that is exactly how pi
+    // resolves them (`dist/core/resource-loader.js:329`): with `noSkills` set, discovered skills are
+    // dropped and explicitly-passed paths are kept. Passing `--skill` WITHOUT `--no-skills` would add to
+    // the discovered set instead of replacing it — an allowlist that widens, which is the failure
+    // direction this package exists to prevent.
+    const skills = [];
+    const unresolvedSkills = [];
+    for (const capability of input.effective) {
+        if (!capability.startsWith("skill:"))
+            continue;
+        const path = input.skillPaths?.[capability.slice(6)];
+        if (path)
+            skills.push(path);
+        else
+            unresolvedSkills.push(capability);
+    }
+    args.push("--no-skills");
+    for (const path of skills)
+        args.push("--skill", path);
+    // Context files are model-directing text that NO capability describes and no ledger line records, so
+    // a child inheriting them holds influence its grant does not express. Under ADR-0012's threat model
+    // — prompt injection explicitly in scope — an untrusted repository's `CLAUDE.md` reaching a governed
+    // child is the injection vector. Off by default therefore, but deliberately still expressible:
+    // inheriting a project's conventions is often exactly what an operator wants, and that should be a
+    // decision they make rather than one this package makes silently in either direction.
+    if (!input.contextFiles)
+        args.push("--no-context-files");
+    // Prompt templates are the third resource class that `--no-extensions` does not cover — found in the
+    // banner of the very run that verified the two above. Lower risk than skills (a template is expanded
+    // when a human invokes `/name`, not injected into the system prompt) but withheld for consistency:
+    // under a herdr backend a governed child runs in an attachable pane WITH a human, so "only what the
+    // grant names" must not depend on which executor ran it.
+    args.push("--no-prompt-templates");
+    // A definition's body, so the child IS the reviewer rather than merely holding a reviewer's tools.
+    // Note this is operator-authored text from a file on disk, not a model-chosen string — the model
+    // picks WHICH definition, never its contents. That is what keeps it out of `neutralisePrompt`'s
+    // remit: the G1 hazard is a model-controlled string reaching a parser, and this is not one.
+    if (input.systemPrompt)
+        args.push("--append-system-prompt", input.systemPrompt);
+    if (allowlist)
+        args.push("--tools", allowlist.join(","));
+    else
+        args.push("--no-tools");
+    args.push(neutralisePrompt(input.prompt));
+    return { args, allowlist, skills, unresolvedSkills };
+}
+/**
+ * Make a model-controlled task unparseable by pi's CLI.
+ *
+ * pi's usage is `pi [options] [@files...] [messages...]`, and both of the non-message forms are reached
+ * by the FIRST CHARACTER of an argv element:
+ *
+ *  - `@…` is resolved as a file and its contents injected into the child's prompt — absolute paths, `~`
+ *    expansion, no sandbox. This happens in `main.js` before any tool is constructed, so `--tools` and
+ *    `--no-tools` never apply to it. A child granted nothing at all still reads the file. Verified
+ *    against pi 0.83.0 (review finding A-C1 / B-C7, and `docs/probes/g1-argv`).
+ *  - `-…` is parsed as a flag, and pi ships `--approve` ("trust project-local files for this run").
+ *
+ * The task comes from the model, so this is the one place in the package where a model-authored string
+ * would otherwise reach a parser that outranks the enforcement point. A single leading space removes it
+ * from both branches: pi does not trim before dispatching on the prefix (measured), and a leading space
+ * is semantically nil inside a prompt.
+ *
+ * **It is applied unconditionally, and that is the point.** Rewriting only arguments that start with
+ * `@` or `-` would encode pi 0.83.0's current parser into this package and silently re-open the hole
+ * the moment pi — or an extension registering its own flags — adds a third prefix. The guarantee here is
+ * positional rather than pattern-based: the first character of that argv element is never the task's.
+ *
+ * Deliberately NOT a refusal. The review also suggested rejecting `@`/`-` tasks in `planDelegation` so
+ * they land in the ledger. Neutralising costs no false refusals and needs no judgement about which
+ * prompts are legitimate, so it is the whole fix; recording an attempt is an audit question (G6), not a
+ * security one, and is left to that group.
+ */
+function neutralisePrompt(prompt) {
+    return ` ${prompt}`;
+}
+//# sourceMappingURL=spawn.js.map

package/dist/spawn.js.map

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