pi-daddy 0.14.0 → 0.16.0

package/extensions/grants.ts

@@ -21,24 +21,22 @@
  * child derives its own grant from the tool array of its first provider request.
  */
 
-import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { WILDCARD } from "../src/pi-tools.ts";
-import { AGENT_WILDCARD } from "../src/resolve.ts";
-import { legacyApprovalsPath, sharedApprovalsPath } from "../src/approval-store.ts";
 import { buildCatalog } from "../src/catalog.ts";
-import { loadDefinitions } from "../src/definitions.ts";
-import { appendRecord, buildRecord, verifyLedger } from "../src/ledger.ts";
-import { deriveOwnGrant, observeToolNames } from "../src/propagation.ts";
+import { appendRecord, buildRecord } from "../src/ledger.ts";
+import { openPaneCount, reapOpenPanesAsync } from "../src/pane-reaper.ts";
+import {
+  ENV_GRANT, deriveOwnGrant, observeToolNames } from "../src/propagation.ts";
 import { snapshotOf } from "./approvals.ts";
 import { registerDelegationTools } from "./delegation.ts";
 import { grantsCommand } from "./grants-command.ts";
+import { runInit } from "./init-command.ts";
 import { planWithApprovals } from "./run-delegation.ts";
-import { createGrantsSession } from "./session.ts";
-import { renderSpawnableSummary, summariseSpawnable } from "./spawn-summary.ts";
-
-const SPAWN_TOOLS = new Set(["Agent", "subagent", "spawn_agent"]);
+import { createGrantsSession, loadProjectDefinitions, resolveExecutor, type GrantsSession } from "./session.ts";
+import { reportSessionStart } from "./session-report.ts";
+import { SPAWN_TOOLS, tripwireReason } from "./tripwire.ts";
 
 export default function (pi: ExtensionAPI) {
   // The path pi loads as the extension, so a child granted `tool:delegate` can be started with `-e <this>`.
@@ -60,6 +58,24 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     session.cwd = ctx.cwd;
+    // The one case the stored-grant lookup can get wrong (ADR-0030). The factory reads the store keyed by
+    // `process.cwd()` because it runs before any hook and therefore before `ctx` exists — and S-5 forces
+    // that ordering, since whether `delegate` is registered is decided there. Almost always the two agree.
+    // When they do not, the session is governed by a different directory's decision than the one it is
+    // working in, which is exactly the confusion a grant must never cause, so it is said out loud rather
+    // than left to be inferred from a surprising refusal. Sync, so it is not the R-60 shape.
+    // Inside no try of its own, and that is deliberate: it is synchronous, so it cannot be the R-60 shape. A
+    // reviewer noted it sits before the try that contains `resolveExecutor` — which is the right order, because
+    // this warning is about WHICH directory's grant was read and must reach the operator even if everything
+    // after it fails.
+    if (session.storeCwd !== ctx.cwd && process.env[ENV_GRANT] === undefined) {
+      ctx.ui.notify(
+        `grants: this session's stored grant was read for ${session.storeCwd}, but pi is working in ` +
+          `${ctx.cwd}. A grant belongs to a directory, so run /grants init here, or set PI_GRANTS_GRANT ` +
+          `explicitly — the environment always wins.`,
+        "warning",
+      );
+    }
     try {
       // Guarded together, and guarded at all because of R-60 rather than because either one throws today:
       // both loaders swallow their own filesystem errors, so this catch is currently unreachable. The point
@@ -69,9 +85,7 @@ export default function (pi: ExtensionAPI) {
       // delegate by `tools:`, and an operator whose `agent:` spawns have all started failing deserves to
       // know it was the *scan* that broke rather than the grant.
       try {
-        session.definitions = await loadDefinitions(ctx.cwd);
-        session.catalogReady = buildCatalog({ cwd: ctx.cwd, observedTools: session.observedTools });
-        session.catalog = await session.catalogReady;
+        await loadProjectDefinitions(session, ctx.cwd);
       } catch (error) {
         ctx.ui.notify(
           `grants: could not read this project's definitions or capability catalog ` +
@@ -81,163 +95,62 @@ export default function (pi: ExtensionAPI) {
           "error",
         );
       }
+      // ADR-0031: probe once, HERE, before anything reports — so the disclosure line can name the executor,
+      // and so a demanded-but-unreachable herdr is reported before the operator's first prompt rather than at
+      // their first delegation. Its own try, because a failure here must not cancel the controls after it
+      // (R-60), and `probeHerdr` is documented as never throwing precisely so this is belt-and-braces.
+      try {
+        await resolveExecutor(session);
+      } catch (error) {
+        // Says what is actually true of the state left behind, which depends on the variable: with
+        // `PI_GRANTS_HERDR=1` the session holds a REFUSAL and every delegation fails, so telling the operator
+        // "using the captured subprocess" would be the opposite of what happens. The old wording asserted the
+        // fallback unconditionally.
+        ctx.ui.notify(
+          `grants: could not settle which executor to use ` +
+            `(${error instanceof Error ? error.message : String(error)}) — ` +
+            (session.executor.refusal
+              ? `PI_GRANTS_HERDR=1 still demands herdr, so every delegation in this session will refuse. ` +
+                `Unset it to let this session probe, or set 0 to choose subprocesses.`
+              : `using the captured subprocess, which needs nothing installed. Set PI_GRANTS_HERDR=0 to make ` +
+                `that explicit, or 1 to demand herdr panes.`),
+          "warning",
+        );
+      }
       session.publishChildEnv();
       // The definitions now exist, so the `delegate` schema can finally name them (R-39). pi serialises a
       // tool's schema at REQUEST time, not at registration — measured — which is what makes this reach the
       // model at all.
       delegation.refreshSpawnable();
-      // A malformed bound is now loud as well as safe. Silently disabling spawning would be just as
-      // confusing as silently disabling the limit was dangerous — the operator set the variable, so
-      // they need to know it did not take effect (G7 / A-S4).
-      if (session.malformedBounds.length > 0) {
-        ctx.ui.notify(
-          `grants: ${session.malformedBounds.join(" and ")} could not be read as a non-negative integer — ` +
-            `spawning is disabled for this session (failing closed)`,
-          "warning",
-        );
-      }
-      // ADR-0014: a pre-0.6 in-workspace approvals file is IGNORED, not migrated — importing it would
-      // import exactly the entries whose trustworthiness the move exists to remove. Say so, because an
-      // operator whose approvals silently stopped applying deserves to know why.
-      // ADR-0020: the pre-0.11 single shared store is ignored, not migrated. Same reasoning shape as the
-      // legacy file below — an operator whose approvals silently stopped applying must be told why — but a
-      // different reason for not migrating: splitting it by `cwd` would be lossless, and it is still declined
-      // because one-shot migration code in the layer with nine defects buys less than one re-approval costs.
-      try {
-        if (existsSync(sharedApprovalsPath())) {
-          ctx.ui.notify(
-            `grants: ignoring ${sharedApprovalsPath()} — approvals are now stored one file per governed ` +
-              `directory (ADR-0020), because a single shared file could not hold two projects' approvals ` +
-              `for a same-named definition. Re-approve when next asked. **Deleting the old file is ` +
-              `recommended, not merely safe**: entries written by 0.10.x may contain the task text a model ` +
-              `composed at approval time, which this version no longer stores anywhere (ADR-0021).`,
-            "warning",
-          );
-        }
-      } catch {
-        /* never throw into the agent loop */
-      }
-      try {
-        if (existsSync(legacyApprovalsPath(ctx.cwd))) {
-          ctx.ui.notify(
-            `grants: ignoring ${legacyApprovalsPath(ctx.cwd)} — approvals now live outside the workspace ` +
-              `(it was writable by the very agents it gated). Re-approve when next asked; the old file is ` +
-              `safe to delete.`,
-            "warning",
-          );
-        }
-      } catch {
-        /* never throw into the agent loop */
-      }
-      // R-47. `gatedBlocked` filters `requested`, and for a definition spawn `requested` is that
-      // definition's CEILING — which never contains `agent:<name>`, because the authorisation check
-      // (ADR-0017) is a separate, ungated branch. So `PI_GRANTS_GATED=agent:deploy`, written by an operator
-      // who read "it attenuates like any other capability" and meant "ask me before deploy runs", produces
-      // no dialog and no warning. It DOES bite when a definition passes the id down in its own
-      // `allowed-tools`, so the flag half-works — which is worse than not working, and is R-25's shape in
-      // the namespace ADR-0017 just promoted out of exactly that state.
+      // Everything an operator is TOLD at session start now lives in `./session-report.ts`. Lifted because
+      // this file had reached 398 of the 400-line ceiling and ADR-0032 adds a control to it; the split is the
+      // same move `session.ts` and `grants-command.ts` were extracted under, and the guard is obeyed rather
+      // than raised.
       //
-      // Warned rather than enforced: making it gate the spawn is a behaviour change and wants a decision.
-      // Silence is the part that is indefensible either way.
-      // `agent:*` grants no tools, but it authorises every definition in BOTH skill roots — including
-      // `~/.pi/agent/skills/`, which other software installs into, so ADR-0017's "an operator-authored
-      // file" is not true of everything it covers. Paired with a shell that is every body on disk running
-      // with `bash`. `docs/SPEC.md` calls the combination poor and nothing detected it, which is R-47's
-      // shape in a control shipped one day later.
-      if (session.ownGrant.includes(AGENT_WILDCARD) && session.gated.length === 0 && session.ownGrant.includes("tool:bash")) {
-        ctx.ui.notify(
-          `grants: PI_GRANTS_GRANT pairs agent:* with tool:bash and gates nothing — every SKILL.md in ` +
-            `this project AND in ~/.pi/agent/skills (which other tools install into) may run with a shell. ` +
-            `Enumerate the agent: ids you mean, or leave PI_GRANTS_GATED at its default so bash is asked for.`,
-          "warning",
-        );
-      }
-      const inertGates = session.gated.filter((c) => c.startsWith("agent:"));
-      if (inertGates.length > 0) {
+      // Its own try/catch, required by `test/session-start-guard.test.ts` and right on the merits: every
+      // control inside `reportSessionStart` already has one, but a throw from the reporter ITSELF would
+      // otherwise reach the blanket catch below and be reported as "session start did not complete" — which
+      // would be true and useless, because nothing about the grant or its enforcement depends on any of it.
+      // Naming that distinction is the difference between an operator checking their configuration and an
+      // operator distrusting their governance.
+      try {
+        await reportSessionStart(session, ctx);
+      } catch (error) {
         ctx.ui.notify(
-          `grants: ${inertGates.join(", ")} in PI_GRANTS_GATED does NOT gate spawning that definition — ` +
-            `the authorisation check for a definition is separate and ungated, so a human is never asked. ` +
-            `It applies only where a definition passes the id down in its own allowed-tools. To control ` +
-            `which definitions may run, withhold the agent: capability from PI_GRANTS_GRANT instead.`,
+          // Names the CHECKS as well as the display lines. The first version listed only "the grant, the
+          // executor and the spawnable definitions" — which understated it: a throw partway through the reporter
+          // also skips the legacy/shared approval-store notices and the **ledger-corruption check**, which is an
+          // error rather than an FYI. Telling an operator that three lines are missing, when a control also did
+          // not run, is the reassuring half of the truth.
+          `grants: the session-start report could not be produced ` +
+            `(${error instanceof Error ? error.message : String(error)}) — the grant, the executor and the ` +
+            `spawnable definitions were not printed, AND the checks that run alongside them did not complete: ` +
+            `ledger integrity was not verified and any ignored-approvals notices were not shown. Run /grants and ` +
+            `/grants ledger for all of it. Governance itself is unaffected: it is enforced by --tools when a ` +
+            `child is spawned.`,
           "warning",
         );
       }
-      // R-34. `verifyLedger` existed and nothing ran it, so a torn line was detectable and undetected —
-      // and a check an operator has to know to run is not a control, it is a feature. Setting
-      // `PI_GRANTS_LEDGER` already means "I want an audit trail"; noticing that the trail is damaged is
-      // part of keeping one.
-      //
-      // Corruption only, deliberately. The escalation count is a *query* — `/grants ledger` answers it —
-      // and reporting historical attempts unprompted at every start is the fatigue shape R-25 names, which
-      // ends with the operator ignoring the line that matters.
-      //
-      // Awaited rather than fired and forgotten: it is one read, on a path that already awaits two
-      // directory scans, and awaiting is what guarantees the warning reaches a live `ctx.ui`.
-      //
-      // R-60. `verifyLedger` RETHROWS every read error that is not ENOENT — right for `/grants ledger`,
-      // where an operator asked a direct question and deserves the failure — and this call is the only one
-      // that makes it inside the blanket catch below. So an unreadable ledger threw here and cancelled every
-      // remaining control **in silence**: no alarm, and not even the `holding [...]` line that is the one
-      // sign governance is on. Confirmed by execution — `PI_GRANTS_LEDGER` naming a directory produced ZERO
-      // notifications from a governed session. A trail that cannot be read at all is a worse failure than a
-      // torn line, and it was the one case this control said nothing about.
-      if (session.ledgerPath) {
-        try {
-          const report = await verifyLedger(session.ledgerPath);
-          if (report.exists && !report.ok) {
-            ctx.ui.notify(
-              `grants: ledger ${session.ledgerPath} has ${report.corrupt.length} unparseable line(s) — ` +
-                `first at line ${report.corrupt[0]?.line}. A torn line is indistinguishable from a spawn that ` +
-                `never happened, so this audit trail is incomplete. Run /grants ledger for detail; the file is ` +
-                `left alone because a corrupt line is evidence.`,
-              "error",
-            );
-          }
-        } catch (error) {
-          ctx.ui.notify(
-            `grants: ledger ${session.ledgerPath} could not be read ` +
-              `(${(error as { code?: string }).code ?? String(error)}) — nothing can be verified about this ` +
-              `audit trail, and the first spawn will refuse rather than proceed unrecorded. Check that ` +
-              `PI_GRANTS_LEDGER names a writable FILE.`,
-            "error",
-          );
-        }
-      }
-      if (session.governed) {
-        ctx.ui.notify(
-          `grants: depth ${session.depth}/${session.maxDepth}, holding [${session.ownGrant.join(", ") || "nothing"}]`,
-          "info",
-        );
-        // B1 / P4. The grant alone never named the definitions, never said where they came from, and never
-        // said which ones were being WITHHELD — so an operator who had just installed a package of
-        // `SKILL.md` files could not tell governance-is-working from did-the-install-fail. Classified by the
-        // real planner (see `./spawn-summary.ts`), never by a second reading of the rules.
-        //
-        // Its own try/catch, and not because `summariseSpawnable` throws today: this is the R-60 shape
-        // exactly — one added `await` inside the blanket catch cancelling every control below it in
-        // silence. There is nothing below it now; there will be.
-        try {
-          const line = renderSpawnableSummary(
-            await summariseSpawnable(
-              session.definitions,
-              (name) => planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
-              // The session facts that make every per-definition verdict identical. `mayDelegate` in
-              // particular: without `tool:delegate` there is no delegate tool at all, and the line used to
-              // report definitions as spawnable in the one session where nothing can ever be spawned.
-              { mayDelegate: session.mayDelegate, depth: session.depth, maxDepth: session.maxDepth },
-            ),
-            session.definitions.size,
-          );
-          if (line) ctx.ui.notify(line, "info");
-        } catch (error) {
-          ctx.ui.notify(
-            `grants: could not work out which definitions are spawnable ` +
-              `(${error instanceof Error ? error.message : String(error)}) — run /grants for the per-definition ` +
-              `verdict. Nothing about the grant or its enforcement depends on this line.`,
-            "warning",
-          );
-        }
-      }
     } catch (error) {
       // Rule 8 — fail closed, and be LOUD about it. Swallowing is still right: a startup fault must not
       // reach the agent loop. Swallowing SILENTLY is what let R-60 exist, and would let the next one exist
@@ -257,6 +170,33 @@ export default function (pi: ExtensionAPI) {
     return undefined;
   });
 
+  /**
+   * Reap the herdr panes this agent run opened — ADR-0032.
+   *
+   * **`agent_settled`, not `turn_end`, and that is the whole finding.** `turn_end` fires at the end of each
+   * provider round-trip, i.e. no later than the `finally` that used to close the pane — so building pane
+   * lifetime on it would have shipped a no-op that read like a feature. `agent_settled` is documented as firing
+   * once the run has fully settled with no retry, compaction or queued continuation: the moment the operator
+   * gets their prompt back. Independent corroboration that this is the right boundary: herdr's own pi
+   * integration drives its busy/idle display from `agent_start`/`agent_settled`.
+   *
+   * The sweep is ASYNC (`reapOpenPanesAsync`) rather than the `exit` handler's sync one, which is `execFileSync`
+   * with a six-second budget by necessity. Running that here would freeze pi for up to six seconds every time
+   * the operator gets their prompt back — a feature built to make work visible, stalling the thing it serves.
+   *
+   * `exit` remains the backstop. SIGKILL still orphans panes, exactly as R-62 records, and no signal handler is
+   * installed here for the reason R-62 gives: it would turn pi's "interrupt this turn" into "exit pi".
+   */
+  pi.on("agent_settled", async () => {
+    try {
+      if (session.executor.kind !== "herdr" || openPaneCount() === 0) return undefined;
+      await reapOpenPanesAsync();
+    } catch {
+      /* never throw into the agent loop; the exit handler is still the backstop */
+    }
+    return undefined;
+  });
+
   // Observe this session's real tool surface once, and tighten the grant to it. Authoritative because
   // it is exactly what pi sent the model.
   pi.on("before_provider_request", (event) => {
@@ -305,11 +245,7 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_call", async (event) => {
     if (!session.governed || !SPAWN_TOOLS.has(event.toolName)) return undefined;
 
-    const reason =
-      `grants: "${event.toolName}" spawns sub-agents outside this session's governance — refused. ` +
-      `This session grants capabilities by spawning them itself (\`delegate\`), so a child created by ` +
-      `another extension would hold whatever that extension decided, with no grant, no depth bound and ` +
-      `no ledger entry. Use \`delegate\` instead. If you meant to run ungoverned, unset PI_GRANTS_GRANT.`;
+    const reason = tripwireReason(event.toolName);
 
     if (session.ledgerPath) {
       // Recorded like any other refusal: an audit that omits the spawns we turned away cannot answer
@@ -323,6 +259,7 @@ export default function (pi: ExtensionAPI) {
           agentType: event.toolName,
           // The wildcard is the honest record: an unknown spawner was going to hand this child whatever
           // IT decided, and we have no way to know what that would have been.
+          executor: session.executor.kind,
           requested: [WILDCARD],
           parentGrant: session.ownGrant,
           result: { effective: [], denied: [WILDCARD], clipped: [], gatedBlocked: [], universal: [], subsumedBy: [] },
@@ -355,6 +292,7 @@ export default function (pi: ExtensionAPI) {
           cwd: session.cwd,
           governed: session.governed,
           ownGrant: session.ownGrant,
+          executor: session.executor,
           observed: session.observed,
           depth: session.depth,
           maxDepth: session.maxDepth,
@@ -368,9 +306,15 @@ export default function (pi: ExtensionAPI) {
           // says so: stored approvals count exactly as they would for a spawn, and no human is asked
           // (R-38). Passing `ctx` here would let `/grants` raise a dialog, and passing `hasUI: false` would
           // make every gated definition report "no interactive user" instead of what actually blocks it.
+          runInit: () =>
+            runInit(session, ctx, async () => {
+              await loadProjectDefinitions(session, ctx.cwd);
+              delegation.refreshSpawnable();
+            }),
           previewDelegation: (name: string) =>
             planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
         },
       }),
   });
 }
+

package/extensions/init-command.ts

@@ -0,0 +1,132 @@
+/**
+ * `/grants init` — the one command in this package that writes.
+ *
+ * Split out of `extensions/grants.ts` when the file-size guard refused it, and the seam is the right one:
+ * `grants.ts` is wiring, and this is a decision procedure that asks a human questions and stores the
+ * answer. Keeping it here means the file that registers hooks stays readable, which is the property the
+ * guard exists to defend — every wiring bug this package has had lived in that file.
+ */
+
+import { discoverSkillPackages } from "../src/skill-packages.ts";
+import { applyInit, planInit } from "../src/init.ts";
+import { saveGrant, grantStorePath } from "../src/grant-store.ts";
+import { expandSubsumed, SUBSUMPTION, type Capability } from "../src/resolve.ts";
+import type { GrantsSession } from "./session.ts";
+
+/**
+ * `/grants init` — scaffold, ask about what is withheld, store it outside the workspace, apply it now.
+ *
+ * **The dialog covers the withheld capabilities and nothing else** (ADR-0030). Asking about all of them
+ * would be a dozen questions for a first run, and this project has a name for what that produces: R-25,
+ * where the operator learns to click through and the control becomes decorative. The read-only capabilities
+ * a skill declares are already bounded by the ceiling its author wrote and by pi's `--tools`; the ones that
+ * can change the machine are the decision, so they are the question.
+ *
+ * A refusal is not a failure. Answering *no* to `tool:bash` leaves four definitions unspawnable and says so
+ * — that is the same outcome `pi-daddy init` writes by default, reached deliberately rather than by
+ * omission.
+ */
+export async function runInit(
+  session: GrantsSession,
+  ctx: any,
+  /**
+   * Reload definitions and the catalog, and re-describe the delegation tools.
+   *
+   * **Without this the grant goes live and the definitions do not** — `session.definitions` and the catalog
+   * are read at `session_start`, which is before `init` wrote a single file, so a session would hold
+   * `agent:review` while believing no definition of that name exists. `/grants` showed `0 skill,
+   * 0 agent-type` and no verdicts, and the model would have been told `Available: none` — R-39 exactly,
+   * reintroduced by a feature whose whole selling point is "no restart". Found by running it.
+   */
+  refresh: () => Promise<void>,
+): Promise<void> {
+  const packages = await discoverSkillPackages(ctx.cwd);
+  if (packages.length === 0) {
+    ctx.ui.notify(
+      "grants: no packages declaring skills found in node_modules. Install one — e.g. " +
+        "`npm i principal-pi-skills` — then run /grants init again.",
+      "warning",
+    );
+    return;
+  }
+
+  const plan = planInit(packages, ctx.cwd);
+  const outcome = await applyInit(plan);
+  const lines = [
+    `grants: ${plan.skills.length} definition(s) from ${packages.map((p) => `${p.name}@${p.version}`).join(", ")}`,
+    `  wrote ${outcome.written.length}, kept ${outcome.kept.length} already present` +
+      `${outcome.failed.length > 0 ? `, ${outcome.failed.length} FAILED` : ""}`,
+  ];
+  for (const f of outcome.failed) lines.push(`    ${f.path}: ${f.error}`);
+
+  // The grant `init` would have written to `.pi/grants.env`: read-only, nothing that can change the
+  // machine. Everything below is added to it only by an explicit yes.
+  const grant = new Set<Capability>(plan.grant);
+  const granted: string[] = [];
+  const declined: string[] = [];
+  /** Withheld capabilities a previous *yes* already conferred, so no question was asked about them. */
+  const alreadyConferred: string[] = [];
+
+  for (const [capability, neededBy] of plan.withheldCapabilities) {
+    // **Do not ask a question whose answer cannot matter.** `tool:bash` subsumes `write`, `edit` and
+    // `edit-diff` (`SUBSUMPTION`, `src/resolve.ts`), so once bash is granted those are already conferred.
+    // The first version asked anyway: an operator could answer *no* to `tool:write`, watch `/grants` allow
+    // `build` with `tool:write`, and reasonably conclude the dialog was decorative. It was — that is R-47's
+    // shape, a control that appears to do something and does not, inside a control built to prevent it.
+    //
+    // Reported rather than silently skipped, because "you already granted this" is the useful sentence and
+    // silence is what made it confusing.
+    if (expandSubsumed([...grant]).includes(capability)) {
+      alreadyConferred.push(`${capability} (via ${subsumedBy([...grant], capability) ?? "a granted capability"})`);
+      for (const name of neededBy) grant.add(`agent:${name}` as Capability);
+      continue;
+    }
+    const answer = await ctx.ui.select(
+      `grants: grant ${capability} to sub-agents?\n  needed by: ${neededBy.join(", ")}\n` +
+        `  this can change your machine — ${capability === "tool:bash" ? "and bash also confers write and edit" : "it is not gated, so no dialog at spawn time"}`,
+      ["No", "Yes"],
+    );
+    if (answer === "Yes") {
+      grant.add(capability);
+      granted.push(capability);
+      // The `agent:` ids too: a definition authorised but unable to receive what it declares would be
+      // allowed to run and then refused, which is a worse answer than not being authorised (ADR-0029).
+      for (const name of neededBy) grant.add(`agent:${name}` as Capability);
+    } else {
+      declined.push(`${capability} (${neededBy.join(", ")})`);
+    }
+  }
+
+  const finalGrant = [...grant].sort();
+  const saved = await saveGrant(ctx.cwd, finalGrant);
+  if (saved !== "saved") {
+    lines.push(
+      `  NOT STORED — ${saved === "busy" ? "another session holds the grant store" : "the store could not be written"}. ` +
+        `Nothing was changed; this session's grant is unchanged. Retry, or export PI_GRANTS_GRANT yourself.`,
+    );
+    ctx.ui.notify(lines.join("\n"), "error");
+    return;
+  }
+
+  // Live, without a restart — the whole point of the store. Only after a successful write, so what runs and
+  // what is recorded cannot disagree.
+  session.adoptGrant(finalGrant);
+  // Order matters: the grant first, then the reload, because `refreshSpawnable` filters the definitions it
+  // advertises through `maySpawnDefinition` against the grant the session now holds.
+  await refresh();
+
+  lines.push(`  stored at ${grantStorePath(ctx.cwd)} — outside this project, so no child can rewrite it`);
+  if (granted.length > 0) lines.push(`  GRANTED: ${granted.join(", ")}`);
+  if (alreadyConferred.length > 0) {
+    lines.push(`  ALREADY CONFERRED, not asked about: ${alreadyConferred.join(", ")}`);
+  }
+  if (declined.length > 0) lines.push(`  withheld: ${declined.join("; ")}`);
+  lines.push(`  live now (${finalGrant.length} capabilities) — no restart. /grants shows the verdicts.`);
+  ctx.ui.notify(lines.join("\n"), "info");
+}
+
+/** Which held capability confers `capability`, for a message that names the cause rather than the effect. */
+function subsumedBy(held: Capability[], capability: Capability): Capability | null {
+  for (const h of held) if ((SUBSUMPTION[h] ?? []).includes(capability)) return h;
+  return null;
+}

package/extensions/run-delegation.ts

@@ -22,7 +22,8 @@ import type { Capability } from "../src/resolve.ts";
 import { ENV_CHILD_TIMEOUT, runChild, timeoutFromEnv } from "../src/run-child.ts";
 import { runHerdrPane } from "../src/run-herdr.ts";
 import { obtainApprovals, republishable, snapshotOf, type ApprovalOutcome, type ApprovalUIContext } from "./approvals.ts";
-import { ENV_HERDR_KEEP_PANE, ENV_HERDR_WORKSPACE, type GrantsSession } from "./session.ts";
+import { resolveWorkspace } from "../src/herdr-cli.ts";
+import { ENV_HERDR_KEEP_PANE, type GrantsSession } from "./session.ts";
 
 /** What one child was asked to do. The shape both tools accept, per child. */
 interface ChildSpec {
@@ -156,6 +157,22 @@ export async function runOneDelegation(
   budget: number | undefined,
   ctx: DelegationToolContext,
   signal: AbortSignal | undefined,
+  /**
+   * Progress for the parent's status block (ADR-0032). Optional, so nothing here depends on being watched.
+   *
+   * One sink for both executors: the herdr path additionally reports a pane id, and the process path never
+   * has one. Every field is display-only — the child's answer is still the returned outcome.
+   */
+  onProgress?: (update: {
+    /** Appended (process executor: a genuine byte stream). */
+    chunk?: string;
+    /** Replaces (herdr executor: a snapshot of a bounded terminal). The two are NOT interchangeable. */
+    snapshot?: string[];
+    paneId?: string;
+    /** The name herdr actually knows this child by — minted in `runHerdrPane`, so it cannot be derived. */
+    agentName?: string;
+    state?: "running" | "completed" | "failed";
+  }) => void,
 ): Promise<DelegationOutcome> {
   // pi resolves a BARE model id to an unauthenticated provider and the child dies at startup — the id
   // alone is not enough, it must be qualified with its provider (`Model<Api>` carries both).
@@ -163,9 +180,32 @@ export async function runOneDelegation(
   const request = { task: spec.task, agent: spec.agent, tools: spec.tools, model: spec.model ?? defaultModel };
   const extra = { fanoutBudget: budget, spawnId: ids.parentId, childSpawnId: ids.childId };
 
+  // ADR-0031: herdr was DEMANDED (`PI_GRANTS_HERDR=1`) and is not answering. Refused rather than relocated —
+  // the operator chose that over falling back, so the ledger can never name a child that ran somewhere nobody
+  // chose.
+  //
+  // **Decided BEFORE the gate, and the ordering is a fix.** This sat after `planWithApprovals`, which opens the
+  // approval dialog — so with herdr down a human was asked to approve `tool:bash`, answered *Always*, and was
+  // then refused anyway. Measured: the answer still reached `process.env.PI_GRANTS_APPROVED`, still wrote a
+  // **30-day project-wide** entry to the persisted store, and still produced a ledger line asserting a human
+  // approved `bash` for a child that never existed. A refused operation must not leave authority behind, and
+  // asking for permission that cannot be used is R-25's fatigue shape with nothing bought.
+  //
+  // `ctx: null` rather than skipping the plan entirely: the ledger still gets a full, honest record of what was
+  // requested and refused, and stored approvals still count toward it — nothing is *hidden*, only nobody is
+  // *asked*. It is the same argument `/grants` uses for its preview.
+  const refusal = session.executor.refusal;
   // Planning and the gate live in `planWithApprovals`, shared with the `/grants` preview so the two cannot
-  // disagree (R-38). This call is the enforcing one: it passes `ctx`, so a human CAN be asked.
-  let { plan, approval: approvalOutcome } = await planWithApprovals(session, request, extra, ctx, signal);
+  // disagree (R-38). This call is the enforcing one when a human may be asked: `ctx` is passed unless the
+  // executor has already made the outcome certain.
+  let { plan, approval: approvalOutcome } = await planWithApprovals(session, request, extra, refusal ? null : ctx, signal);
+
+  // Applied in front of the ledger write below, so the record describes a refusal rather than a spawn. Turning
+  // `plan.ok` off reuses the existing blocked-record path, so this adds a reason rather than a second refusal
+  // mechanism.
+  if (refusal) {
+    plan = { ...plan, ok: false, reason: `grants: ${refusal}` };
+  }
 
   // G6 / B-I3: no `&& plan.result` guard — `planDelegation` always carries one now.
   if (session.ledgerPath) {
@@ -179,6 +219,9 @@ export async function runOneDelegation(
         childId: ids.childId,
         depth: plan.childDepth,
         agentType: spec.agent ?? "delegate",
+        // ADR-0031: where this child actually ran. Read off the live session, which the probe has settled
+        // by now, so the record and the executor cannot disagree.
+        executor: session.executor.kind,
         requested: plan.requested,
         parentGrant: session.ownGrant,
         result: plan.result,
@@ -208,10 +251,14 @@ export async function runOneDelegation(
   // G8: bounded output, a wall-clock timeout with SIGTERM->SIGKILL escalation, and an abort observed
   // even if it happened before we got here. See src/run-child.ts for why each one exists.
   //
-  // ADR-0016 point 6: two executors, one plan. `runChild` is the default because it needs nothing
-  // installed; herdr gives the same governed argv a VISIBLE, attachable pane. Opt-in per session rather
-  // than auto-detected — a governed run must not silently relocate because a binary is on PATH.
-  const output = session.useHerdr
+  // ADR-0016 point 6: two executors, one plan. `runChild` needs nothing installed; herdr gives the same
+  // governed argv a VISIBLE, attachable pane.
+  //
+  // **Which one is chosen was reversed by ADR-0031**: the session probes for a reachable herdr server at
+  // startup rather than waiting to be told. Still never detected from a binary on `PATH` — only from a server
+  // that answered — and the choice is disclosed at session start, in `/grants`, and per child in the ledger.
+  // Read live off `session.executor`, because the probe finishes after this module is loaded.
+  const output = session.executor.kind === "herdr"
     ? await runHerdrPane({
         args: plan.args.slice(0, -1),
         // The task is delivered as a prompt, so it never reaches argv at all. `plan.args` still ends
@@ -223,10 +270,22 @@ export async function runOneDelegation(
         env: plan.env,
         cwd: ctx.cwd,
         name: `${spec.agent ?? "delegate"}-${ids.childId}`,
-        workspace: process.env[ENV_HERDR_WORKSPACE],
+        // Was `process.env[ENV_HERDR_WORKSPACE]`, i.e. "omitted lets herdr choose" — which put children in a
+        // different workspace from the pi session that spawned them, so switching to one meant hopping
+        // workspaces rather than tabs. `resolveWorkspace` prefers the operator's explicit answer and otherwise
+        // inherits the parent's own `HERDR_WORKSPACE_ID` (measured; herdr sets it in every pane it creates).
+        workspace: resolveWorkspace(process.env),
         signal,
         timeoutMs: timeoutFromEnv(process.env[ENV_CHILD_TIMEOUT]),
         keepPane: process.env[ENV_HERDR_KEEP_PANE] === "1",
+        // ADR-0032. The pane id arrives first and is what a human switches to; the pane's tail follows as the
+        // child works. Both are display only.
+        //
+        // `snapshot`, not `chunk`: `agent read` returns a snapshot of a bounded terminal, and the sink must
+        // REPLACE what it holds. Treating it as a stream produced an 89,000× amplification and fabricated lines
+        // the child never printed — see `tailLines` in `src/herdr-poll.ts`.
+        onPane: onProgress ? (paneId, agentName) => onProgress({ paneId, agentName, state: "running" }) : undefined,
+        onSnapshot: onProgress ? (snapshot) => onProgress({ snapshot }) : undefined,
       })
     : await runChild({
         command: "pi",
@@ -238,6 +297,9 @@ export async function runOneDelegation(
         cwd: ctx.cwd,
         signal,
         timeoutMs: timeoutFromEnv(process.env[ENV_CHILD_TIMEOUT]),
+        // No pane on this path, so streaming is the ONLY observability a subprocess child can have — which is
+        // why ADR-0032 chose the streaming option over status lines alone.
+        onOutput: onProgress ? (chunk) => onProgress({ chunk }) : undefined,
       });
 
   // G8: a child that failed is reported as a failure. A non-zero exit, a timeout and a truncated flood