pi-daddy 0.13.0

package/src/run-child.ts

@@ -0,0 +1,149 @@
+/**
+ * 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.ts";
+
+/**
+ * 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: string | undefined): number {
+  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;
+}
+
+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 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: ChildRunRequest): Promise<ChildRunResult> {
+  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<ChildRunResult>((settle) => {
+    let child: ReturnType<typeof spawn>;
+    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: NodeJS.Timeout[] = [];
+    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: unknown) => {
+      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: ChildRunResult) => {
+      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 }));
+  });
+}

package/src/run-herdr.ts

@@ -0,0 +1,357 @@
+/**
+ * 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 type { ChildRunResult } from "./run-child.ts";
+import { DEFAULT_MAX_OUTPUT_BYTES, DEFAULT_TIMEOUT_MS } from "./run-child.ts";
+import { trackPane, untrackPane } from "./pane-reaper.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 function splitSystemPrompt(args: string[]): { args: string[]; systemPrompt?: string } {
+  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: HerdrExec = (args) =>
+  new Promise((settle) => {
+    execFile("herdr", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+      const code = error && typeof (error as { code?: unknown }).code === "number" ? (error as { code: number }).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: { stdout: string; stderr: string }): { result?: Record<string, unknown>; error?: string } {
+  try {
+    const parsed = JSON.parse(reply.stdout) as { result?: Record<string, unknown>; error?: { message?: string; code?: string } };
+    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: HerdrRunRequest): Promise<ChildRunResult> {
+  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: ChildRunResult = { 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: string | undefined;
+  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 ?? {}) as { pane_id?: string; tab_id?: string };
+  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: HerdrExec,
+  name: string,
+  paneId: string,
+  args: string[],
+  deadline: number,
+): Promise<{ result?: Record<string, unknown>; error?: string }> {
+  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: Record<string, unknown> | undefined): number {
+  const agent = (result?.agent ?? {}) as { state_change_seq?: number };
+  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: HerdrExec,
+  request: HerdrRunRequest,
+  before: number,
+  deadline: number,
+): Promise<{ status?: string; timedOut?: boolean; aborted?: boolean; spawnError?: string }> {
+  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 ?? {}) as { agent_status?: string; state_change_seq?: number };
+    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: HerdrExec, name: string, maxOutputBytes: number): Promise<{ text: string; truncated: boolean }> {
+  const reply = await exec(["agent", "read", name]);
+  let text: string;
+  try {
+    const parsed = JSON.parse(reply.stdout) as { result?: Record<string, unknown>; error?: { message?: string } };
+    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 };
+}

package/src/spawn.ts

@@ -0,0 +1,156 @@
+/**
+ * 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, 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 function planSpawn(input: SpawnPlanInput): SpawnPlan {
+  const allowlist = toPiToolsAllowlist(input.effective);
+  const args: string[] = [];
+
+  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: string[] = [];
+  const unresolvedSkills: Capability[] = [];
+  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: string): string {
+  return ` ${prompt}`;
+}