pi-daddy 0.15.0 → 0.16.0

package/extensions/grants-command.ts

@@ -13,6 +13,7 @@
  */
 
 import type { Capability } from "../src/resolve.ts";
+import type { ExecutorChoice } from "../src/executor.ts";
 import type { Catalog } from "../src/catalog.ts";
 import type { SkillDefinition } from "../src/definitions.ts";
 import type { GatedPlan } from "./run-delegation.ts";
@@ -23,6 +24,13 @@ export interface GrantsCommandContext {
   cwd: string;
   governed: boolean;
   ownGrant: Capability[];
+  /**
+   * Which executor this session settled on, and why — ADR-0031.
+   *
+   * The whole `ExecutorChoice` rather than a rendered string, so this command cannot compose a different
+   * sentence from the one the session banner printed. Two spellings of one fact is R-28.
+   */
+  executor: ExecutorChoice;
   observed: boolean;
   depth: number;
   maxDepth: number;
@@ -71,7 +79,7 @@ handler: async (args: string, ctx: any) => {
     // Everything this command may see, named in one place. Previously these were whatever happened to be in
     // the enclosing closure — which is how a diagnostic came to disagree with the enforcer (R-28).
     const {
-      cwd, governed, ownGrant, observed, depth, maxDepth, ledgerPath,
+      cwd, governed, ownGrant, executor, observed, depth, maxDepth, ledgerPath,
       catalog, definitions, sessionApprovals, inheritedApprovals, snapshotOf, previewDelegation,
     } = ctx.grants as GrantsCommandContext;
 
@@ -102,6 +110,17 @@ handler: async (args: string, ctx: any) => {
         `  integrity  ${report.ok ? "OK" : `${report.corrupt.length} UNPARSEABLE LINE(S)`}`,
       ];
       for (const bad of report.corrupt.slice(0, 5)) lines.push(`    line ${bad.line}: ${bad.text}`);
+      // ADR-0031, and R-51's lesson applied on the day the field was added rather than a release later: a field
+      // the writer sets and no diagnostic reads is one that needs `jq`, and `docs/SPEC.md` claims the executor is
+      // announced "per child in the ledger". `unknown` is shown only when present, because on a fresh ledger it
+      // is always zero and a permanent zero is noise; on an upgraded one it is the count of pre-0.16 lines, which
+      // is worth seeing.
+      lines.push(
+        `  executors  ${report.executors.herdr} herdr pane(s) · ${report.executors.process} subprocess(es)` +
+          (report.executors.unknown > 0
+            ? ` · ${report.executors.unknown} not recorded (written before 0.16.0, which added the field)`
+            : ""),
+      );
       // R-51. ADR-0018 advertises that the ledger answers "did these four children run the same
       // instructions?" and "has this definition changed since?" — and nothing read `definitionDigest`, so
       // both needed hand-written jq and the second was not reproducible with `sha256sum` (the digest covers
@@ -300,6 +319,12 @@ handler: async (args: string, ctx: any) => {
     const lines = [
       governed ? "grants: ACTIVE" : "grants: inactive (set PI_GRANTS_GRANT to govern this session)",
       `  holding    ${ownGrant.join(", ") || "(nothing)"}${observed ? " (observed)" : " (inherited, not yet observed)"}`,
+      // ADR-0031/0032. This screen named the grant, the depth, the ledger, the approvals and the catalog, and
+      // never said WHERE children run — so an operator on a machine where herdr hosts their whole workspace
+      // could not discover that their children were invisible subprocesses. That gap is what produced
+      // ADR-0031, and its probe is only defensible because this line exists. Placed next to `holding` so the
+      // two facts about what a spawn will be sit together.
+      `  executor   ${executor.disclosure}`,
       `  depth      ${depth} of max ${maxDepth}${maxDepth <= 0 ? " (spawning disabled)" : ""}`,
       `  ledger     ${ledgerPath ?? "(not recording — set PI_GRANTS_LEDGER)"}`,
       `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +

package/extensions/grants.ts

@@ -21,28 +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 { 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 type { Capability } from "../src/resolve.ts";
-
 import { planWithApprovals } from "./run-delegation.ts";
-import { createGrantsSession, loadProjectDefinitions, type GrantsSession } 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>`.
@@ -70,6 +64,10 @@ export default function (pi: ExtensionAPI) {
     // 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 ` +
@@ -97,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
@@ -273,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) => {
@@ -321,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
@@ -339,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: [] },
@@ -371,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,

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