pi-daddy 0.15.0 → 0.16.0

package/src/herdr-cli.ts

@@ -0,0 +1,125 @@
+/**
+ * Talking to herdr: one command, one JSON envelope, plus the two questions ADR-0031 needs answered.
+ *
+ * Lifted out of `src/run-herdr.ts`, which was at 357 of the 400-line ceiling and gains output polling under
+ * ADR-0032. But the split is not only about lines: **the probe is not an executor concern**. It runs at session
+ * start, before any delegation exists, to decide *which* executor a session will use — so leaving it inside the
+ * herdr executor would mean the session imported the thing it was deciding whether to use.
+ *
+ * Every rule here is tested against an injected `exec`, so the suite stays fast, pi-free and herdr-free. The
+ * facts the fakes reproduce were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`).
+ */
+
+import { execFile } from "node:child_process";
+
+/** 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 const defaultExec: HerdrExec = (args) =>
+  new Promise((settle) => {
+    execFile("herdr", args, { maxBuffer: 32 * 1024 * 1024 }, (error, stdout, stderr) => {
+      const raw = (error as { code?: unknown } | null)?.code;
+      const code = typeof raw === "number" ? raw : error ? 1 : 0;
+      // **A string `code` is a spawn failure, and it used to be thrown away.** `ENOENT` — herdr not installed —
+      // arrives as `code: "ENOENT"`, so the numeric test failed, the message was dropped, and an operator with
+      // `PI_GRANTS_HERDR=1` on a machine without herdr was told *"herdr is not answering (unparseable herdr
+      // reply: (no output))"* rather than that the binary is missing. Rule 8 wants the loud version, and this is
+      // the first diagnostic such an operator meets.
+      const spawnFailure = typeof raw === "string" ? `herdr could not be run (${raw}): ${error?.message ?? ""}` : "";
+      settle({ code, stdout: String(stdout), stderr: spawnFailure || 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.
+ */
+export 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)"}` };
+  }
+}
+
+/** Bound on the session-start probe. Short: it sits in front of the operator's first prompt. */
+export const PROBE_TIMEOUT_MS = 2000;
+
+export interface HerdrProbe {
+  ok: boolean;
+  /** herdr's own words when it is not reachable. Carried so the disclosure line can name the reason. */
+  error?: string;
+}
+
+/**
+ * Is there a herdr server that will answer right now? — ADR-0031's selection input.
+ *
+ * **`tab list`, not `which herdr`.** ADR-0031 rejects `PATH` detection as option C by name: a binary on `PATH`
+ * with no server behind it would make every delegation fail at `tab create`, on a path the operator never
+ * chose, and the diagnostic would arrive at the first delegation rather than at startup. Only a parsed
+ * `result` envelope counts as reachable; an `error` envelope, a non-JSON reply, a timeout and a throwing
+ * `exec` are all "not reachable" with the reason preserved.
+ *
+ * **Zero tabs is a successful answer**, deliberately: a fresh herdr with nothing open is reachable.
+ *
+ * Never throws. A probe that threw out of `session_start` would cancel every control after it, which is
+ * R-60's shape exactly — and this one runs *before* the line that discloses what it decided.
+ */
+export async function probeHerdr(options: { exec?: HerdrExec; timeoutMs?: number } = {}): Promise<HerdrProbe> {
+  const exec = options.exec ?? defaultExec;
+  const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
+
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race<HerdrProbe>([
+      exec(["tab", "list"]).then((reply) => {
+        const parsed = parseReply(reply);
+        return parsed.error ? { ok: false, error: parsed.error } : { ok: true };
+      }),
+      new Promise<HerdrProbe>((settle) => {
+        timer = setTimeout(() => settle({ ok: false, error: `probe timed out after ${timeoutMs}ms` }), timeoutMs);
+      }),
+    ]);
+  } catch (error) {
+    return { ok: false, error: String(error) };
+  } finally {
+    // Cleared whichever branch won, so a fast probe does not hold the event loop open for the timeout's
+    // remainder — which would add up to two seconds to every `node --test` run of this file.
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/** herdr's own variable, set in every pane it creates. Measured 2026-08-17; documented nowhere. */
+export const ENV_PARENT_WORKSPACE = "HERDR_WORKSPACE_ID";
+
+/** The operator's explicit override. Defined here because this is the only module that reads it. */
+export const ENV_HERDR_WORKSPACE = "PI_GRANTS_HERDR_WORKSPACE";
+
+/**
+ * Which herdr workspace a governed child's pane belongs in.
+ *
+ * **Defaults to the parent's own workspace.** herdr tells a pane which workspace it is in
+ * (`HERDR_WORKSPACE_ID`, alongside `HERDR_TAB_ID` and `HERDR_PANE_ID`), and a child placed in a *different*
+ * workspace from the pi session that spawned it turns "switch between them" into a workspace hop — which is
+ * the entire feature ADR-0032 exists to deliver. The previous behaviour was "omitted lets herdr choose",
+ * which is that failure by default on any machine with more than one workspace.
+ *
+ * `PI_GRANTS_HERDR_WORKSPACE` still wins: it is the operator saying so explicitly, and an explicit answer
+ * beating an inference is this package's standing rule (ADR-0030 says it about the grant itself).
+ *
+ * Blank is treated as absent rather than passed through — `--workspace ""` is not a workspace, and it would
+ * fail `tab create` on a path nobody chose.
+ */
+export function resolveWorkspace(env: NodeJS.ProcessEnv): string | undefined {
+  const explicit = env[ENV_HERDR_WORKSPACE]?.trim();
+  if (explicit) return explicit;
+  return env[ENV_PARENT_WORKSPACE]?.trim() || undefined;
+}

package/src/herdr-name.ts

@@ -0,0 +1,61 @@
+/**
+ * Naming a herdr agent: the grammar herdr enforces, and uniqueness it does not.
+ *
+ * Split out of `src/run-herdr.ts` at the 400-line ceiling, and a real seam: both rules below come from **herdr's
+ * own validation and lifecycle**, not from anything this package decides. Two shipping defects lived here, and
+ * both were invisible to every test because the unit fake accepts whatever name it is handed and the integration
+ * suite never reaches a real herdr spawn. They surfaced from two real spawns against the live daemon.
+ */
+
+/** Monotonic within this process. See `uniqueAgentName`. */
+let spawnSeq = 0;
+
+/**
+ * herdr's agent-name grammar, measured from its own rejection message.
+ *
+ * `agent name must start with a lowercase letter and contain only lowercase letters, digits, '-' or '_'
+ * (1-32 characters)`.
+ */
+const AGENT_NAME_MAX = 32;
+
+/**
+ * Make a herdr agent name that is **valid** and cannot collide with a live one.
+ *
+ * **Validity is a separate, PRE-EXISTING defect, and it is the more serious half.** Callers build a name as
+ * `${definition}-${childId}`, and a ledger child id is hierarchical — `d0.1`, `d0.1.2` (ADR-0008/F8). Those dots
+ * are **not in herdr's grammar**, so `agent start review-d0.1 …` is rejected with `invalid_agent_name`. Every
+ * `delegate({agent})` on the herdr path has therefore failed at `agent start` since the executor was written.
+ *
+ * Nothing could see it. The unit fake accepts any name it is handed, and the integration suite never reaches a
+ * real herdr spawn — so both were green while the feature could not work. It surfaced only by running two real
+ * spawns against the live daemon, which is the argument for doing that at all.
+ *
+ * **Measured, and a shipping defect without it.** herdr binds an agent name to its **tab**, and only closing
+ * the tab frees the name: a second `agent start` with a name still held returns
+ * `agent_name_taken: agent <name> is already used; … tab_id=…`. `herdr agent stop` does not exist (see
+ * `cleanup`), so nothing else releases it.
+ *
+ * Callers build a name from the definition and the ledger child id — and for a plain blocking `delegate` that
+ * id is **constant** (`d0.1`, index 0 of the session), so every delegation in a session asked for the same
+ * name. That was harmless while the pane closed at the end of each call. Once ADR-0032 kept panes alive to
+ * `agent_settled`, the **first** delegation of a turn worked and every later one failed with
+ * `agent_name_taken`, on the executor ADR-0031 had just made the default.
+ *
+ * Uniquified HERE rather than at the call site, so no caller can forget: the constraint belongs to herdr, and
+ * this module is the only thing that talks to herdr. The suffix is a counter rather than a random token so a
+ * pane label stays readable and reproducible within a run.
+ */
+export function uniqueAgentName(base: string): string {
+  spawnSeq += 1;
+  const suffix = `-${spawnSeq}`;
+  const cleaned = base
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-") // dots from a child id, and anything else outside the grammar
+    .replace(/-{2,}/g, "-")
+    .replace(/^[^a-z]+/, ""); // must START with a lowercase letter, so a leading digit or dash goes
+  // Truncated so the whole name fits, and trimmed of a trailing separator so the join stays readable. The
+  // fallback covers a base that sanitises to nothing at all (a definition named entirely in non-Latin script).
+  const room = AGENT_NAME_MAX - suffix.length;
+  const head = cleaned.slice(0, room).replace(/[-_]+$/, "") || "agent";
+  return `${head}${suffix}`;
+}

package/src/herdr-poll.ts

@@ -0,0 +1,185 @@
+/**
+ * Waiting for a herdr agent to settle, and reading what it printed on the way.
+ *
+ * Split out of `src/run-herdr.ts` when that file hit **404 of the 400-line ceiling** adding ADR-0032's output
+ * polling. The seam was named in the plan before it was needed, and it is a real one: this module is about
+ * *observing* an agent, `run-herdr.ts` is about *starting and cleaning up after* one. Nothing here creates or
+ * destroys anything.
+ *
+ * The two facts it is built on were measured against real herdr 0.7.5 (`docs/probes/g16-herdr`) and both are
+ * counter-intuitive enough to be worth the module comment: `agent wait --until idle` matches the state the
+ * agent was **already** in, and `agent read` is the one command that does **not** return a JSON envelope.
+ */
+
+import { parseReply, type HerdrExec } from "./herdr-cli.ts";
+
+/**
+ * What `waitForSettled` needs from a run request.
+ *
+ * Declared here rather than importing `HerdrRunRequest`, which would make the two modules mutually dependent
+ * for no benefit. `HerdrRunRequest` satisfies it structurally, so the call site needs no adapter.
+ */
+export interface PollTarget {
+  /** herdr agent name. */
+  name: string;
+  signal?: AbortSignal;
+  /**
+   * The pane's last few lines, re-reported on every poll — a SNAPSHOT, not a stream (ADR-0032).
+   *
+   * The consumer must **replace** what it holds rather than append. `agent read` returns a snapshot of a
+   * bounded terminal, and treating it as append-only is what produced an 89,000× amplification; see
+   * `tailLines`.
+   */
+  onSnapshot?: (lines: string[]) => void;
+  /** How many lines the display wants. Bounds the per-poll cost regardless of how big the pane is. */
+  snapshotLines?: number;
+  /** Poll cadence override. Exists so tests do not wait `POLL_INTERVAL_MS` per state transition. */
+  pollIntervalMs?: number;
+}
+
+/** 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;
+/** Lines of pane tail reported per poll. Matches the status block's own tail, so nothing is fetched unused. */
+export const DEFAULT_SNAPSHOT_LINES = 3;
+
+/**
+ * Wait for the child to settle, without accepting the state it was already in.
+ *
+ * **R-33, measured.** `herdr agent wait --until idle` called right after `agent prompt` returned
+ * *immediately*, matching the agent's **pre-existing** idle state with `state_change_seq` unchanged — a
+ * reply indistinguishable from a completed run. For fan-out that is not an inconvenience but a
+ * correctness bug: an orchestrator would "collect" N children that never ran and merge N empty results
+ * into a confident summary (R-03 with a new cause).
+ *
+ * So this polls `agent get` and requires **both** that the status is terminal **and** that
+ * `state_change_seq` has advanced past the value observed before prompting. `agent wait` is deliberately
+ * not used at all: its contract cannot express "settled *after* this point".
+ */
+export async function waitForSettled(
+  exec: HerdrExec,
+  request: PollTarget,
+  before: number,
+  deadline: number,
+  maxOutputBytes: number,
+): Promise<{ status?: string; timedOut?: boolean; aborted?: boolean; spawnError?: string }> {
+  const interval = request.pollIntervalMs ?? POLL_INTERVAL_MS;
+  // ADR-0032. The pane is read on every poll so the parent can show what the child is doing, rather than the
+  // one word `delegate` for up to ten minutes.
+  //
+  // No cross-poll state is kept, deliberately: the previous design remembered what it had reported so it could
+  // send a diff, and that is what broke — see `tailLines`. A snapshot needs no memory.
+  const keep = request.snapshotLines ?? DEFAULT_SNAPSHOT_LINES;
+
+  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 (request.onSnapshot) {
+      // Read BEFORE the terminal check returns, so a child that settles on this iteration still has its last
+      // output shown. `readFailed` is passed so a failed read renders as such instead of silently freezing the
+      // block on the previous frame — and, crucially, is never mistaken for the child's output.
+      const read = await readPane(exec, request.name, maxOutputBytes);
+      try {
+        request.onSnapshot(read.readFailed ? ["[pane could not be read]"] : tailLines(read.text, keep));
+      } catch {
+        /* display only — a renderer must not break a governed run */
+      }
+    }
+
+    if (status && TERMINAL.has(status) && seq > before) return { status };
+
+    await new Promise((r) => setTimeout(r, Math.min(interval, Math.max(0, deadline - Date.now()))));
+  }
+}
+
+/**
+ * The last `keep` non-blank lines of a pane snapshot — what the display actually needs.
+ *
+ * **This replaces a `newSuffix` diff, and the replacement is a correction rather than a tune-up.** The old
+ * design treated `agent read` as a *stream* and tried to report only what was new, by testing whether the new
+ * text extended the old. That is wrong about the substrate: `agent read` returns a **snapshot of a bounded
+ * terminal**, and a snapshot is not an append-only log. Two ordinary things break the prefix test forever —
+ * the pane **scrolling** (its top lines are gone, so the new text is not an extension of the old) and
+ * `readPane` **truncating to the tail** past `maxOutputBytes` (each read is a different window of a growing
+ * buffer). Once either happens, every poll reported the whole buffer.
+ *
+ * Measured before the fix: **51 MiB streamed for ~600 bytes of real output — 89,000× amplification** in 37
+ * seconds, per child, with a scrolling pane also delivering the same real lines three times each. The old
+ * docstring named that exact failure as the thing it prevented.
+ *
+ * So the herdr path now reports a **bounded snapshot** and the consumer *replaces* rather than appends. There
+ * is no diff to get wrong, the per-poll cost is `keep` lines regardless of buffer size, and a scrolling pane
+ * simply shows its current tail — which is what a human looking at that pane would see.
+ */
+export function tailLines(snapshot: string, keep: number): string[] {
+  if (keep <= 0) return [];
+  const lines: string[] = [];
+  // Walked from the END, so a 1 MiB buffer costs the last few lines rather than a full split.
+  let end = snapshot.length;
+  while (end > 0 && lines.length < keep) {
+    const start = snapshot.lastIndexOf("\n", end - 1);
+    const line = snapshot.slice(start + 1, end).replace(/\r/g, "").trimEnd();
+    if (line.length > 0) lines.unshift(line);
+    if (start === -1) break;
+    end = start;
+  }
+  return lines;
+}
+
+/**
+ * Read the pane's contents.
+ *
+ * `agent read` is the ONE command that does not return herdr's JSON envelope — it writes the terminal's
+ * text straight to stdout. Running it through `parseReply` turned every successful read into
+ * "unparseable herdr reply", i.e. reported the child's actual answer as a failure to read it. Found by the
+ * end-to-end run; the unit fake had been written to the envelope shape and so agreed with the bug.
+ *
+ * A JSON envelope is still accepted first, because an `error` reply here IS JSON and must not be mistaken
+ * for terminal output.
+ *
+ * **`readFailed` is separate from `text`, and that separation is the fix for an R-03 defect.** A failed read
+ * used to return its own diagnostic *as* `text` — so `runHerdrPane` returned
+ * `[grants] could not read the agent pane: pane is gone` **as the child's answer, with `code: 0`**, and the
+ * orchestrator read a failure message as a completed sub-agent's report. Measured. It mattered little when this
+ * ran once per child; ADR-0032 made it run on every poll, up to 800 times for a ten-minute child, so a
+ * transient failure went from unlikely to expected. The caller must now decide, and it cannot do so by
+ * inspecting a string.
+ */
+export async function readPane(
+  exec: HerdrExec,
+  name: string,
+  maxOutputBytes: number,
+): Promise<{ text: string; truncated: boolean; readFailed?: string }> {
+  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: "", truncated: false, readFailed: parsed.error.message ?? "unknown error" };
+    }
+    const raw = parsed.result?.output ?? parsed.result?.text ?? parsed.result?.content ?? "";
+    text = typeof raw === "string" ? raw : JSON.stringify(raw);
+  } catch {
+    text = reply.stdout;
+  }
+  if (Buffer.byteLength(text) <= maxOutputBytes) return { text, truncated: false };
+  // Keep the TAIL, not the head: a terminal's useful content is its most recent output, and the head is
+  // the startup banner. `runChild` keeps the head because it streams and must stop a runaway producer;
+  // here the output is already complete, so the choice is free and the tail is the answer.
+  //
+  // Sliced by BYTES via a Buffer round trip rather than by code units, for `takeBytes`'s reason in
+  // `run-child.ts`: `slice(-maxOutputBytes)` on a CJK pane overran the cap by three times. `toString` repairs
+  // a character split at the cut by replacing it, which is the right trade for a tail — one replacement
+  // character at the boundary, versus a cap that does not hold.
+  return { text: Buffer.from(text, "utf8").subarray(-maxOutputBytes).toString("utf8"), truncated: true };
+}

package/src/herdr-stage.ts

@@ -0,0 +1,55 @@
+/**
+ * Staging a definition's instructions to a file, because herdr cannot carry them in argv.
+ *
+ * Split out of `src/run-herdr.ts` at the 400-line ceiling. A real seam rather than an arbitrary cut: this is
+ * the one place that works around a **herdr encoding limit**, and it is the only part of the herdr path that
+ * touches the filesystem. `run-herdr.ts` starts and reaps agents; this prepares one argument.
+ */
+
+import { mkdtemp, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Move a multi-line `--append-system-prompt` out of argv, because herdr cannot encode it.
+ *
+ * **Measured.** `herdr agent start` types the argv into the pane's shell, so a value containing newlines
+ * is rejected outright: `invalid_agent_argument — agent arguments cannot be encoded safely for the target
+ * shell`. A definition's `SKILL.md` body is always multi-line, so every `delegate({agent})` spawn would
+ * fail on this path.
+ *
+ * pi accepts a **file path** there as readily as literal text (`resolvePromptInput` + `existsSync` in
+ * `dist/core/resource-loader.js`), so the fix is to write the body to a temp file and pass its path — one
+ * short, shell-safe argument.
+ *
+ * The split lives here rather than in `planSpawn` because the constraint is **herdr's**, not pi's: the
+ * direct executor passes the same text inline with no trouble, and a plan builder that pre-emptively wrote
+ * temp files for everybody would be paying one executor's tax on both paths.
+ */
+export function splitSystemPrompt(args: 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] };
+}
+
+/**
+ * Move a multi-line system prompt into a temp file and return argv pointing at it.
+ *
+ * Returns the directory so the caller can remove it — and **every** early return on the herdr path must, because
+ * nothing else can: a reviewer measured a permanent `/tmp/grants-herdr-*` per failed `tab create`, unreachable by
+ * either pane sweep because the pane it belonged to never existed.
+ */
+export async function stageSystemPrompt(
+  args: string[],
+): Promise<{ args: string[]; promptDir?: string; error?: string }> {
+  const split = splitSystemPrompt(args);
+  if (split.systemPrompt === undefined) return { args: split.args };
+  try {
+    const promptDir = await mkdtemp(join(tmpdir(), "grants-herdr-"));
+    const file = join(promptDir, "system-prompt.md");
+    await writeFile(file, split.systemPrompt, "utf8");
+    return { args: [...split.args, "--append-system-prompt", file], promptDir };
+  } catch (error) {
+    return { args: split.args, error: `could not stage the system prompt for herdr: ${String(error)}` };
+  }
+}

package/src/ledger-report.ts

@@ -27,6 +27,20 @@ export interface LedgerReport {
   corrupt: Array<{ line: number; text: string }>;
   /** Records where an agent asked for more than it held — ADR-0008's designated signal. */
   escalationAttempts: number;
+  /**
+   * How many records ran under each executor, plus how many name none — ADR-0031.
+   *
+   * **Added because the field was written and never read, which is R-51's shape exactly.** R-51 was
+   * `definitionDigest`: recorded from the start, absent from every report, so the questions ADR-0018 advertised
+   * needed hand-written `jq`. `executor` arrived the same way — `src/ledger.ts` justifies making it *required*
+   * with "reading it back is the only reason it exists", and nothing read it back. `docs/SPEC.md` claims the
+   * executor is "announced three times… per child in the ledger"; without this the third announcement was to
+   * `jq` only.
+   *
+   * `unknown` counts pre-0.16 lines, which have no such field. Reported rather than folded into `process`,
+   * because "written before the executor was recorded" and "ran as a subprocess" are different facts.
+   */
+  executors: { herdr: number; process: number; unknown: number };
   /**
    * Every distinct set of instructions this ledger saw run, with how many spawns used it (R-51).
    *
@@ -113,6 +127,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
         records: 0,
         corrupt: [],
         escalationAttempts: 0,
+        executors: { herdr: 0, process: 0, unknown: 0 },
         definitions: [],
         approvals: {
           bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
@@ -132,6 +147,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
   const digests = new Map<string, { name: string; source: string; sha256: string; spawns: number }>();
   let records = 0;
   let escalationAttempts = 0;
+  const executors = { herdr: 0, process: 0, unknown: 0 };
   const bySource: Record<ApprovalSource, number> = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
   // `capability@subject` seen per source, so the report can state a bound as well as a raw count.
   const distinct: Record<ApprovalSource, Set<string>> = {
@@ -153,6 +169,10 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
       if (!Array.isArray(parsed.denied)) throw new Error("not a grant record");
       records += 1;
       if (isEscalationAttempt(parsed)) escalationAttempts += 1;
+      const executor = (parsed as { executor?: unknown }).executor;
+      if (executor === "herdr") executors.herdr += 1;
+      else if (executor === "process") executors.process += 1;
+      else executors.unknown += 1;
       if (parsed.humanDenied) {
         humanDenied += 1;
         const subject = parsed.agentType === undefined || parsed.agentType === "delegate" ? DELEGATE_SUBJECT : parsed.agentType;
@@ -209,6 +229,7 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
     records,
     corrupt,
     escalationAttempts,
+    executors,
     definitions: [...digests.values()].sort((a, b) => a.name.localeCompare(b.name) || a.sha256.localeCompare(b.sha256)),
     approvals: {
       bySource,

package/src/ledger.ts

@@ -23,6 +23,7 @@ import { appendFile, mkdir, readFile } from "node:fs/promises";
 import { withFileLock } from "./file-lock.ts";
 import { dirname } from "node:path";
 import type { Capability, ResolveResult } from "./resolve.ts";
+import type { ExecutorKind } from "./executor.ts";
 import type { DefinitionDigest } from "./definitions.ts";
 import { DELEGATE_SUBJECT } from "./approval.ts";
 import type { ApprovalScope, ApprovalSource } from "./approval.ts";
@@ -107,6 +108,20 @@ export interface GrantRecord {
    * it. Absent for a `tools:`-style delegation, which has no definition.
    */
   definitionDigest?: DefinitionDigest;
+  /**
+   * WHERE this child ran — ADR-0031.
+   *
+   * **Required rather than optional**, which is unusual in this record and deliberate. Before ADR-0031 the
+   * executor was a variable an operator set, so "which one ran?" was answerable from configuration after the
+   * fact. It is now decided by a **runtime probe** at session start, so nothing outside the record preserves
+   * the answer — and the two paths do not produce the same argv, because the herdr plan withholds `--print`
+   * (`delegationContext.interactive`). A trail that cannot say where a child ran cannot be read back
+   * reliably, and reading it back is the only reason it exists.
+   *
+   * Written on refusals too, including the tripwire's: the honest value there is the executor the session
+   * *would* have used, because a refused spawn has no executor of its own.
+   */
+  executor: ExecutorKind;
 }
 
 export interface LedgerOptions {
@@ -137,6 +152,8 @@ export function buildRecord(args: {
   humanDenied?: boolean;
   gateOutcome?: PromptOutcomeKind;
   definitionDigest?: DefinitionDigest;
+  /** Where the child ran (ADR-0031). Required: the probe's answer survives nowhere else. */
+  executor: ExecutorKind;
   now: Date;
 }): GrantRecord {
   // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
@@ -151,6 +168,7 @@ export function buildRecord(args: {
     childId: args.childId,
     depth: args.depth,
     agentType: args.agentType,
+    executor: args.executor,
     requested: args.requested,
     parentGrant: args.parentGrant,
     effective: args.result.effective,