pi-daddy 0.15.0 → 0.17.0

package/extensions/delegate-chain.ts

@@ -0,0 +1,357 @@
+/**
+ * `delegate_chain` — a governed sequential pipeline, planned and gated as one unit (ADR-0033).
+ *
+ * Its own file rather than a third tool in `delegation.ts`, which is near the 400-line ceiling. The seam is real
+ * anyway: `delegate` and `delegate_all` differ only in cardinality, while a chain differs in **composition** — each
+ * step's task is built from the previous step's output, and the whole thing is planned before any of it runs.
+ *
+ * **Nothing here re-implements a governance rule.** Every step goes through `runOneDelegation`, so the grant, the
+ * ceiling, `agent:<name>` authorisation, the depth bound, the ledger and `--tools` enforcement are exactly what a
+ * single `delegate` gets. What a chain adds is the handoff (`src/chain.ts`), one gate instead of N, a budget unit
+ * per step, and abort-on-failure.
+ *
+ * **Why the upfront gate is exact rather than an approximation**, which is the least obvious thing here: an approval
+ * is keyed `capability@subject` and **the task is never part of it** (ADR-0021 — the task is not stored anywhere). So
+ * the union of a chain's gated capabilities is fully determined before any step's task exists, even though steps
+ * 2..N have no task until their predecessor runs. That is what makes asking once honest instead of optimistic.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { InheritableApproval } from "../src/approval.ts";
+import { DELEGATE_SUBJECT, shouldSeekApproval } from "../src/approval.ts";
+import { chainStepSpec, PLACEHOLDER } from "../src/chain.ts";
+import { planDelegation } from "../src/delegate.ts";
+import { MAX_CHAIN_STEPS, childSpawnId, splitBudget } from "../src/fanout.ts";
+import { PAINT_INTERVAL_MS, appendTail, emptyTail, renderProgress, replaceTail, throttle, type ChildProgress } from "../src/progress.ts";
+import type { Capability } from "../src/resolve.ts";
+import { appendRecord, buildRecord } from "../src/ledger.ts";
+import { obtainApprovals, snapshotOf } from "./approvals.ts";
+import { runOneDelegation } from "./run-delegation.ts";
+import type { GrantsSession } from "./session.ts";
+
+/** One step of a chain, as the model describes it. */
+interface StepSpec {
+  task: string;
+  agent?: string;
+  tools?: string[];
+  model?: string;
+}
+
+/**
+ * One dialog's worth of gate: a single capability, for a single subject, described by the step that needs it.
+ *
+ * **One request per `capability@subject`, not per subject.** Grouping by subject alone merged every `tools:`-only
+ * step under the constant `<delegate>` and froze the *first* step's task into the dialog — so an operator approved
+ * `tool:write` while reading a task that only listed files. The dialog is the one place a human learns what they are
+ * authorising, so it names the step that actually needs the capability.
+ */
+interface GateRequest {
+  subject: string;
+  /** `"definition"` offers `always`; `"delegate"` must not (ADR-0019). Derived from the subject, never assumed. */
+  path: "definition" | "delegate";
+  capability: Capability;
+  /** The task of the step that needs this capability. */
+  task: string;
+}
+
+/** Either every gate the chain will hit, or the first step that can never run and why. */
+interface ChainPlan {
+  requests: GateRequest[];
+  /** Set when a step is refused for a reason no approval can fix. The chain must refuse before asking anyone. */
+  doomed?: { step: number; reason: string };
+}
+
+/**
+ * Plan every step and collect the gates — or find a step that can never run.
+ *
+ * **`plan.ok` is honoured here, and ignoring it was a privilege path.** The first version read only
+ * `gatedBlocked`, so a step refused for an unheld `agent:` id, an unknown definition, an empty task or a universal
+ * capability still raised its gate and the answer was still banked. Measured: `delegate({tools:["bash","agent:x"]})`
+ * asks nobody and refuses, while the same step inside a chain raised a dialog, took *Allow for this session*, refused
+ * anyway — and left `tool:bash` pre-approved for every later delegation in the session. On the `agent:` path it
+ * banked a **30-day** entry, including for a step whose task was whitespace, whose dialog therefore read `task:`
+ * followed by nothing.
+ *
+ * `shouldSeekApproval` is the rule every other gate in this package already applies, and its own docstring names
+ * this hazard: *"both banked against a spawn that never happened, and both reachable by a model that appends one
+ * unheld capability to an otherwise ordinary request."* The chain reimplemented the decision beside it instead of
+ * routing through it. So a doomed step now refuses the whole chain **before any dialog**, which is the same
+ * principle the executor check follows.
+ *
+ * Planned with no UI: `planWithApprovals` would open a dialog per step during the very phase whose purpose is to ask
+ * upfront. A step's task is unknown for everything after the first, which is fine — an approval key never contains
+ * the task (ADR-0021), so the set of gates is fully determined without it.
+ */
+async function planChain(session: GrantsSession, steps: StepSpec[], perStepBudget: number): Promise<ChainPlan> {
+  const requests: GateRequest[] = [];
+  const seen = new Set<string>();
+  const context = await session.delegationContext();
+
+  for (const [index, step] of steps.entries()) {
+    // The real task, not a placeholder: the planner's own empty-task guard must run here rather than at spawn time,
+    // or a step with a whitespace task raises a dialog and is refused afterwards. The handoff is absent at planning
+    // time and cannot change which capabilities are gated.
+    const plan = planDelegation(
+      { task: step.task, agent: step.agent, tools: step.tools, model: step.model },
+      { ...context, spawnId: session.ownSpawnId, childSpawnId: childSpawnId(session.ownSpawnId, index) },
+    );
+
+    // A gate is the ONLY refusal an approval can lift. Anything else is doomed, and asking about it banks authority
+    // for a spawn that will never happen.
+    if (!plan.ok && !shouldSeekApproval(plan.result)) {
+      return { requests: [], doomed: { step: index + 1, reason: plan.reason ?? "this step cannot run" } };
+    }
+
+    const subject = step.agent ?? DELEGATE_SUBJECT;
+    for (const capability of plan.result.gatedBlocked) {
+      const key = `${capability}@${subject}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      requests.push({ subject, path: step.agent ? "definition" : "delegate", capability, task: step.task });
+    }
+  }
+  return { requests };
+}
+
+export function registerChainTool(pi: ExtensionAPI, session: GrantsSession): void {
+  // No `mayDelegate` guard here: `registerDelegationTools` already returns before calling this, so a second check
+  // was dead code that made the leaf half of a wiring test pass for the wrong reason. The guard lives in one place.
+
+  const stepShape = Type.Object({
+    task: Type.String({
+      description:
+        `What this step should do. Write ${PLACEHOLDER} where the previous step's output belongs; if you omit it, ` +
+        `that output is appended instead. The first step never receives one.`,
+    }),
+    agent: Type.Optional(Type.String({ description: "Definition to spawn for this step." })),
+    tools: Type.Optional(Type.Array(Type.String(), { description: "Capabilities, when no 'agent' fits." })),
+    model: Type.Optional(Type.String({ description: "Model as provider/id. Defaults to this session's." })),
+  });
+
+  const params = Type.Object({
+    steps: Type.Array(stepShape, {
+      minItems: 1,
+      maxItems: MAX_CHAIN_STEPS,
+      description: "The steps to run IN ORDER. Each one sees the previous one's output.",
+    }),
+  });
+
+  pi.registerTool({
+    name: "delegate_chain",
+    label: "Delegate a chain of sub-agents (governed, sequential)",
+    description:
+      "Run sub-agents ONE AFTER ANOTHER, each receiving the previous one's output. Use this when a step needs " +
+      "what an earlier step produced — a decision feeding a design feeding an implementation. Use `delegate_all` " +
+      "instead when the tasks are independent and can run at the same time, and `delegate` for a single child. " +
+      `At most ${MAX_CHAIN_STEPS} steps, each spending one unit of the session's fan-out budget. Every step is ` +
+      "governed exactly as a single `delegate` is: it holds only what you grant it, and you cannot grant what you " +
+      "do not hold. A failed step ABORTS the rest, and you still receive everything that completed.",
+    parameters: params,
+    async execute(_toolCallId, args, signal, onUpdate, ctx) {
+      const steps = args.steps ?? [];
+
+      // **Every cheap refusal happens before any human is asked.** Yesterday's lesson on the `delegate` path: with
+      // `PI_GRANTS_HERDR=1` and herdr down, the gate ran first, an operator approved `bash`, a 30-day entry was
+      // written, and the delegation was then refused anyway. `runOneDelegation` checks the executor before its own
+      // gate; a chain hoists its gate above `runOneDelegation`, so the check has to be repeated here or that
+      // ordering is simply bypassed.
+      if (session.executor.refusal) throw new Error(`chain refused: ${session.executor.refusal}`);
+
+      // Cardinality next, still before the gate. `splitBudget` is reused rather than re-derived, so a chain and a
+      // fan-out cannot disagree about what the budget means.
+      const split = splitBudget(session.fanoutBudget, steps.length);
+      if (!split.ok) throw new Error(`chain refused: ${split.reason}`);
+
+      // Plan every step first. A step that can never run refuses the chain HERE, before anyone is asked — see
+      // `planChain`.
+      const chainPlan = await planChain(session, steps, split.perChild);
+      if (chainPlan.doomed) {
+        throw new Error(
+          `chain refused at step ${chainPlan.doomed.step}: ${chainPlan.doomed.reason} No step ran, and nobody was ` +
+            `asked to approve anything — a step that cannot run must not bank authority for a spawn that will ` +
+            `never happen.`,
+        );
+      }
+
+      // One dialog per `capability@subject`, each naming the step that needs it, all before the first step runs.
+      const preApproved: InheritableApproval[] = [];
+      let declined: { capability: Capability; subject: string } | undefined;
+      let humanDenied = false;
+
+      for (const request of chainPlan.requests) {
+        const outcome = await obtainApprovals(session, [request.capability], request.subject, request.path, ctx, request.task, signal);
+        humanDenied = humanDenied || outcome.humanDenied;
+        if (!outcome.approved.includes(request.capability)) {
+          // **Stop asking.** The chain's outcome is already fixed, and every further dialog banks authority — a
+          // `session` yes into `sessionApprovals` and an `always` yes onto disk for 30 days — for a chain that will
+          // not run. The single-delegate path breaks on the first no for the same reason.
+          declined = { capability: request.capability, subject: request.subject };
+          break;
+        }
+        preApproved.push({
+          capability: request.capability,
+          subject: request.subject,
+          scope: outcome.scopes[request.capability] ?? ("once" as const),
+          // Pinned to THIS subject's body (ADR-0022). Stamped from a single shared subject, the pin was verified
+          // against one definition's instructions while the capability was spent on another's.
+          bodySha256: snapshotOf(session, request.subject)?.bodySha256,
+        });
+      }
+
+      if (declined) {
+        // Recorded before it is thrown, and recorded against the subject that was actually refused. The first version
+        // hardcoded step 1's identity, so the trail asserted a human had denied a capability for `digger` when they
+        // had *approved* it for `digger` and denied it for `shaper` — the ledger and the approval store asserting
+        // opposite facts about the same key, which is R-28's shape.
+        if (session.ledgerPath) {
+          const at = steps.findIndex((step) => (step.agent ?? DELEGATE_SUBJECT) === declined.subject);
+          await appendRecord(
+            { path: session.ledgerPath, strict: true },
+            buildRecord({
+              parentId: session.ownSpawnId,
+              childId: childSpawnId(session.ownSpawnId, Math.max(0, at)),
+              depth: session.depth + 1,
+              agentType: declined.subject === DELEGATE_SUBJECT ? "delegate" : declined.subject,
+              requested: [declined.capability],
+              parentGrant: session.ownGrant,
+              result: { effective: [], denied: [], clipped: [], gatedBlocked: [declined.capability], universal: [], subsumedBy: [] },
+              blocked: true,
+              humanDenied,
+              reason: `chain refused: ${declined.capability} not approved for ${declined.subject}; no step ran`,
+              executor: session.executor.kind,
+              now: new Date(),
+            }),
+          ).catch((error) => {
+            // Not swallowed. Everywhere else a `strict` ledger failure fails closed, and losing the one line that
+            // records a human's refusal is the direction rule 8 forbids — the chain refuses either way, so saying so
+            // costs nothing.
+            ctx.ui?.notify?.(
+              `grants: the chain was refused AND its ledger line could not be written (${String(error)}) — the ` +
+                `refusal happened, but this audit trail does not show it.`,
+              "error",
+            );
+          });
+        }
+        throw new Error(
+          `chain refused: ${declined.capability} was not approved for ${declined.subject}, so no step ran. A chain ` +
+            `is gated as a unit — running only its approved steps would return a partial result that reads like a ` +
+            `complete one.`,
+        );
+      }
+
+      const children: ChildProgress[] = steps.map((step) => ({
+        label: step.agent ?? "delegate",
+        state: "starting",
+        startedAt: Date.now(),
+        tail: emptyTail,
+      }));
+      const paint = throttle(() => {
+        (onUpdate as ((partial: { content: Array<{ type: "text"; text: string }> }) => void) | undefined)?.({
+          content: [{ type: "text", text: renderProgress(children, session.executor.kind, Date.now()) }],
+        });
+      }, PAINT_INTERVAL_MS);
+
+      const outcomes: Array<{ ok: boolean; text: string; reason?: string; step: number; agent?: string }> = [];
+      let previous: string | undefined;
+      let aborted = false;
+      /**
+       * Approvals still available to later steps.
+       *
+       * **`once` is consumed by the first step that spends it, and not honouring that was a confused deputy.**
+       * Measured: three steps of one definition, one dialog naming step 1's task — *"survey the north field"* — and
+       * three children spawned, the last of which had been told *"…and burn the evidence"*. Steps 2 and 3 were never
+       * described to anyone. Two sequential plain `delegate` calls raise two dialogs, because a `once` answer never
+       * enters `sessionApprovals`; the chain was the outlier. R-29 exists for this exact shape one level down.
+       *
+       * A later step needing the same capability now reaches its own gate and prompts with its OWN task, which is
+       * what `once` means.
+       */
+      let available = [...preApproved];
+
+      for (const [index, step] of steps.entries()) {
+        const childId = childSpawnId(session.ownSpawnId, index);
+        const outcome = await runOneDelegation(
+          session,
+          chainStepSpec(step, previous),
+          { parentId: session.ownSpawnId, childId },
+          split.perChild,
+          ctx,
+          signal,
+          {
+            preApproved: available,
+            approvalFacts: {
+              // Only this step's subject, so the record says what was authorised for THIS child rather than for the
+              // chain as a whole.
+              approved: available.filter((a) => a.subject === (step.agent ?? DELEGATE_SUBJECT)).map((a) => a.capability),
+              sources: Object.fromEntries(
+                available
+                  .filter((a) => a.subject === (step.agent ?? DELEGATE_SUBJECT))
+                  .map((a) => [a.capability, "prompt" as const]),
+              ),
+              scopes: Object.fromEntries(
+                available.filter((a) => a.subject === (step.agent ?? DELEGATE_SUBJECT)).map((a) => [a.capability, a.scope]),
+              ),
+              humanDenied: false,
+            },
+            onProgress: (update) => {
+              const child = children[index];
+              if (!child) return;
+              if (update.paneId) child.paneId = update.paneId;
+              if (update.agentName) child.agentName = update.agentName;
+              if (update.chunk) child.tail = appendTail(child.tail, update.chunk);
+              if (update.snapshot) child.tail = replaceTail(update.snapshot);
+              if (update.state) child.state = update.state;
+              else if (child.state === "starting") child.state = "running";
+              paint.call();
+            },
+            // Provenance: which child's output composed THIS step's task (ADR-0033). Absent for step 1.
+            taskFrom: index === 0 ? undefined : childSpawnId(session.ownSpawnId, index - 1),
+          },
+        );
+
+        children[index].state = outcome.ok ? "completed" : "failed";
+        children[index].settledAt = Date.now();
+        outcomes.push({ ok: outcome.ok, text: outcome.text, reason: outcome.reason, step: index + 1, agent: step.agent });
+
+        // Spend any `once` this step was handed, before the next step sees the list.
+        const spentSubject = step.agent ?? DELEGATE_SUBJECT;
+        available = available.filter((a) => !(a.scope === "once" && a.subject === spentSubject));
+
+        if (!outcome.ok) {
+          // **Abort, and mark the rest.** Continuing would make the next step's task an error message, which is
+          // never what an orchestrator wants. Everything completed is still returned — R-03's rule.
+          aborted = true;
+          for (let rest = index + 1; rest < children.length; rest += 1) children[rest].state = "failed";
+          break;
+        }
+        previous = outcome.text;
+      }
+      paint.flush();
+
+      const report = outcomes
+        .map((o) => {
+          const label = `### step ${o.step}${o.agent ? ` (${o.agent})` : ""}`;
+          return o.ok ? `${label} — completed\n\n${o.text || "(no output)"}` : `${label} — FAILED: ${o.reason}${o.text ? `\n\n${o.text}` : ""}`;
+        })
+        .join("\n\n---\n\n");
+
+      const skipped = steps.length - outcomes.length;
+      const tail = aborted
+        ? `\n\n---\n\n**The chain stopped at step ${outcomes.length}.** ${skipped} later step(s) did not run, ` +
+          `because each one's task is built from the previous step's output and there was none to pass on.`
+        : "";
+
+      if (outcomes.length === 1 && !outcomes[0].ok) {
+        // Nothing completed at all, so there is no partial result to hand back — and a tool that returns text when
+        // nothing ran is how a wrong summary gets written.
+        throw new Error(`chain failed at its first step.\n\n${report}`);
+      }
+
+      return {
+        content: [{ type: "text", text: `${report}${tail}` }],
+        details: { steps: steps.length, completed: outcomes.filter((o) => o.ok).length, aborted, budgetPerStep: split.perChild },
+      };
+    },
+  });
+}

package/extensions/delegation.ts

@@ -13,9 +13,91 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { maySpawnDefinition } from "../src/delegate.ts";
 import { MAX_CHILDREN_PER_CALL, childSpawnId, splitBudget } from "../src/fanout.ts";
+import {
+  PAINT_INTERVAL_MS,
+  appendTail,
+  emptyTail,
+  renderProgress,
+  replaceTail,
+  throttle,
+  type ChildProgress,
+} from "../src/progress.ts";
+import { registerChainTool } from "./delegate-chain.ts";
 import { runOneDelegation } from "./run-delegation.ts";
 import { type GrantsSession } from "./session.ts";
 
+/**
+ * Wire a set of children to pi's partial-result channel — ADR-0032.
+ *
+ * **One block for the whole call**, not one per child: `onUpdate` replaces the tool's rendered result, so N
+ * independent painters would each overwrite the others and the operator would see one child flickering.
+ * `delegate` is simply the one-child case of the same thing, which is why both tools come through here.
+ *
+ * Painting is throttled, and the trailing frame matters more than the throttling: without it the final paint —
+ * the one showing every child settled — is the one most likely to be dropped, so the block would freeze
+ * mid-run. `flush()` at the end is what guarantees the last state is the one left on screen.
+ *
+ * **Nothing here is the result.** The tool's content still comes from each child's returned text.
+ */
+function progressReporter(
+  session: GrantsSession,
+  labels: string[],
+  onUpdate: ((partial: { content: Array<{ type: "text"; text: string }> }) => void) | undefined,
+) {
+  const started = Date.now();
+  const children: ChildProgress[] = labels.map((label) => ({
+    label,
+    state: "starting",
+    startedAt: started,
+    tail: emptyTail,
+  }));
+
+  const paint = throttle(() => {
+    onUpdate?.({
+      content: [{ type: "text", text: renderProgress(children, session.executor.kind, Date.now()) }],
+    });
+  }, PAINT_INTERVAL_MS);
+
+  return {
+    /** One sink per child index, shaped for `runOneDelegation`'s `onProgress`. */
+    sink: (index: number) => (update: {
+      chunk?: string;
+      snapshot?: string[];
+      paneId?: string;
+      agentName?: string;
+      state?: ChildProgress["state"];
+    }) => {
+      const child = children[index];
+      if (!child) return;
+      if (update.paneId) child.paneId = update.paneId;
+      // **Reported, not derived.** It used to be rebuilt here from the label and the child id, which was true
+      // until `runHerdrPane` began uniquifying the name to stop herdr's `agent_name_taken` — after which the
+      // block named an agent that did not exist, and an operator following it would find nothing. The name is
+      // known only where it is minted, so it travels from there.
+      if (update.agentName) child.agentName = update.agentName;
+      // Two shapes, deliberately distinct, because the two executors are: a subprocess APPENDS bytes, a pane
+      // reports a SNAPSHOT that replaces. Collapsing them into one "output" field is what caused the herdr
+      // path's amplification, so the difference is spelled out in the type rather than remembered.
+      if (update.chunk) child.tail = appendTail(child.tail, update.chunk);
+      if (update.snapshot) child.tail = replaceTail(update.snapshot);
+      if (update.state) child.state = update.state;
+      else if (child.state === "starting") child.state = "running";
+      paint.call();
+    },
+    /** Record how each child ended and leave the final frame on screen. */
+    settle: (outcomes: Array<{ ok: boolean }>) => {
+      const at = Date.now();
+      outcomes.forEach((outcome, index) => {
+        const child = children[index];
+        if (!child) return;
+        child.state = outcome.ok ? "completed" : "failed";
+        child.settledAt = at;
+      });
+      paint.flush();
+    },
+  };
+}
+
 export interface DelegationRegistration {
   /**
    * Re-derive "which definitions may this session spawn?" into the registered tool schemas.
@@ -113,7 +195,10 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
       "written by the operator. Use 'tools' only when no definition fits. Grant 'delegate' if the " +
       "sub-agent must itself delegate further; withhold it to make the sub-agent a leaf.",
     parameters: delegateParams,
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      // ADR-0032: one child, same block. `_onUpdate` was discarded here, so a delegation showed the bare word
+      // `delegate` for up to DEFAULT_TIMEOUT_MS — ten minutes of nothing.
+      const progress = progressReporter(session, [params.agent ?? "delegate"], onUpdate as never);
       const outcome = await runOneDelegation(
         session,
         { task: params.task, agent: params.agent, tools: params.tools, model: params.model },
@@ -124,7 +209,9 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
         session.fanoutBudget,
         ctx,
         signal,
+        { onProgress: progress.sink(0) },
       );
+      progress.settle([outcome]);
 
       if (!outcome.ok) {
         // THROW, do not return. `AgentToolResult` has no `isError` field: pi sets it only when `execute`
@@ -168,7 +255,7 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
       "when independent tasks can proceed in parallel — several reviewers over one diff, say — and read " +
       "every child's outcome, because one can be refused while the others succeed.",
     parameters: delegateAllParams,
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const children = params.children ?? [];
       const split = splitBudget(session.fanoutBudget, children.length);
       if (!split.ok) {
@@ -177,6 +264,10 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
         throw new Error(`fan-out refused: ${split.reason}`);
       }
 
+      // ADR-0032: ONE status block covering every child. `onUpdate` replaces the tool's rendered result, so a
+      // painter per child would have each overwriting the others.
+      const progress = progressReporter(session, children.map((c) => c.agent ?? "delegate"), onUpdate as never);
+
       // Concurrent by construction. Each child gets its own budget share and its own ledger id, so the
       // records form a tree and two siblings can never be confused for one another.
       const outcomes = await Promise.all(
@@ -188,9 +279,11 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
             split.perChild,
             ctx,
             signal,
+            { onProgress: progress.sink(index) },
           ),
         ),
       );
+      progress.settle(outcomes);
 
       const failed = outcomes.filter((o) => !o.ok);
       // Every child is reported, including the ones that failed. R-03's rule: a missing result must never
@@ -223,6 +316,11 @@ export function registerDelegationTools(pi: ExtensionAPI, session: GrantsSession
     },
   });
 
+  // ADR-0033. Registered here so all three tools appear together and share the `mayDelegate` guard, but its logic
+  // lives in its own file: `delegate` and `delegate_all` differ only in cardinality, while a chain differs in
+  // composition, and this file is near the 400-line ceiling.
+  registerChainTool(pi, session);
+
   return {
     // Written through the CONSTRUCTED schema (`properties.agent`) rather than the object handed to
     // `Type.Optional`, because `Optional` shallow-copies — mutating the input would update a discarded

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` +