pi-daddy 0.15.0 → 0.16.0

package/extensions/session-report.ts

@@ -0,0 +1,231 @@
+/**
+ * Everything this extension says at session start.
+ *
+ * Lifted out of `extensions/grants.ts` for the reason `grants-command.ts` and `session.ts` were: that file is
+ * where every wiring bug in this package has lived, and it had reached **398 of the 400-line ceiling**
+ * `test/file-size.test.ts` enforces. ADR-0032 adds a control there, so the file had to be split before it
+ * could be added — the alternative was raising the cap, which is how a guard stops guarding. This project
+ * split `delegate.ts` at 413 rather than raise it, and that precedent is the whole argument.
+ *
+ * The seam is the same one twice over: `grants.ts` keeps the HOOKS and the wiring; this module decides what an
+ * operator is **told**. Nothing here returns a value or mutates the session, which is what makes it safe to
+ * lift — a reporter cannot become a governance path by accident.
+ *
+ * **Each control keeps its own `try`.** That is R-60's lesson rather than tidiness: one added `await` inside a
+ * shared `catch` cancels every control below it with no trace, and that is exactly how an unreadable ledger
+ * came to silence the `holding [...]` line too.
+ */
+
+import { existsSync } from "node:fs";
+import { legacyApprovalsPath, sharedApprovalsPath } from "../src/approval-store.ts";
+import { verifyLedger } from "../src/ledger.ts";
+import { AGENT_WILDCARD } from "../src/resolve.ts";
+import { planWithApprovals } from "./run-delegation.ts";
+import type { GrantsSession } from "./session.ts";
+import { renderSpawnableSummary, summariseSpawnable } from "./spawn-summary.ts";
+
+/**
+ * The slice of pi's context this module needs: a working directory and somewhere to speak.
+ *
+ * Named explicitly rather than taking `ExtensionContext` whole, for `grants-command.ts`'s reason — what a
+ * read-only reporter may see is a decision, and it belongs in a type rather than in whatever happened to be
+ * in scope.
+ */
+export interface SessionReportContext {
+  cwd: string;
+  ui: { notify(message: string, level: "info" | "warning" | "error"): void };
+}
+
+export async function reportSessionStart(session: GrantsSession, ctx: SessionReportContext): Promise<void> {
+  // 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.
+  //
+  // 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) {
+    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.`,
+      "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",
+      );
+    }
+  }
+  // ADR-0031 rests on this line existing: an executor chosen by a probe is only defensible if it is announced.
+  //
+  // **`mayDelegate`, not `governed`** — and that distinction is a defect caught in review before it shipped.
+  // An UNGOVERNED session still registers `delegate` and still spawns (`mayDelegate` is true when
+  // `!governed`), so gating this on `governed` would have relocated an ungoverned session's children into
+  // herdr panes and said nothing about it. That is precisely the "silently" objection ADR-0031 claims to have
+  // discharged, reappearing inside the fix for it — R-28's shape, in the one configuration nobody tests.
+  //
+  // The guard is not simply dropped because a session that cannot spawn at all has no executor worth naming.
+  // **Every `info` line is joined into ONE notify, and that is a fix rather than formatting.**
+  //
+  // Measured against real pi 0.84.2 in a pty: `notify(…, "info")` maps to `showStatus`, which **replaces the
+  // previous status text in place** when the last two transcript children are the pair it created — which is
+  // exactly the case for back-to-back notifies. So consecutive `info` calls overwrite each other, and only the
+  // last survives. In a governed session with definitions that meant the executor line AND the
+  // `holding [...]` line were both gone, leaving only the spawnable summary — and `grants.ts` calls
+  // `holding [...]` "the one sign governance is on". **That half is a pre-existing defect**, true since the
+  // spawnable summary was added; ADR-0031's disclosure merely became its third victim.
+  //
+  // Six tests asserted these lines were *composed*. None asserted they were *delivered*: the unit harness
+  // pushes to an array and the integration harness runs `--mode rpc`, where each notify is its own JSON line.
+  // Both are replace-free, so neither could see this.
+  //
+  // Warnings and errors are NOT folded in — they go to different components (`showError`), survive on their
+  // own, and each says something an operator may need to act on separately.
+  const info: string[] = [];
+
+  if (session.mayDelegate && !session.executor.refusal) {
+    info.push(`grants: executor — ${session.executor.disclosure}`);
+  }
+  if (session.mayDelegate && session.executor.refusal) {
+    // An error, not an FYI: every delegation in this session will refuse. Emitted separately because `error`
+    // routes elsewhere and therefore is not at risk of being overwritten.
+    ctx.ui.notify(`grants: executor — ${session.executor.disclosure}`, "error");
+  }
+
+  if (session.governed) {
+    info.push(
+      `grants: depth ${session.depth}/${session.maxDepth}, holding [${session.ownGrant.join(", ") || "nothing"}]`,
+    );
+    // 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.
+    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) info.push(line);
+    } 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",
+      );
+    }
+  }
+
+  // One call, so nothing can overwrite anything else. `/grants` already worked this way, which is why its
+  // multi-line status screen has always survived while these separate lines did not.
+  if (info.length > 0) ctx.ui.notify(info.join("\n"), "info");
+}

package/extensions/session.ts

@@ -20,6 +20,8 @@ import { makeCatalog, skillPathsFromCatalog, type Catalog } from "../src/catalog
 import type { SkillDefinition } from "../src/definitions.ts";
 import { DELEGATE_CAPABILITY, type DelegationContext } from "../src/delegate.ts";
 import { budgetFromEnv } from "../src/fanout.ts";
+import { chooseExecutor, needsProbe, ENV_HERDR, type ExecutorChoice } from "../src/executor.ts";
+import { probeHerdr } from "../src/herdr-cli.ts";
 import { WILDCARD } from "../src/pi-tools.ts";
 import {
   childEnv,
@@ -43,16 +45,32 @@ import { loadGrantSync, grantStorePath } from "../src/grant-store.ts";
 import { republishable } from "./approvals.ts";
 
 /**
- * Run governed children in herdr panes instead of captured child processes (ADR-0016 point 6).
+ * Run governed children in herdr panes instead of captured child processes.
  *
- * Opt-in, and deliberately not auto-detected from `herdr` being on PATH: where a governed child executes
- * is an operator decision, and a run that silently relocates because a binary appeared is exactly the kind
- * of invisible change this package exists to prevent. Both executors enforce the identical grant — the
- * plan is the same, only the place it runs differs.
+ * **Three-state as of ADR-0031, and absent means PROBE.** It was opt-in under ADR-0016 point 6, on the
+ * reasoning that *"a run that silently relocates because a binary appeared is exactly the kind of invisible
+ * change this package exists to prevent"* — and that sentence is still honoured, because nothing is detected
+ * from `herdr` being on `PATH`. What changed is that a **server which answers** is a different and stronger
+ * test, and the "silently" half is discharged by the disclosure line ADR-0032 adds at session start and in
+ * `/grants`. Both executors still enforce the identical grant: the plan is the same, only the place it runs
+ * differs.
+ *
+ * The table itself is a pure function in `../src/executor.ts`; re-exported here because this is where every
+ * other `PI_GRANTS_*` name lives and a reader looking for it will look here.
+ */
+export { ENV_HERDR } from "../src/executor.ts";
+/**
+ * herdr workspace for spawned panes — re-exported from where it is actually READ.
+ *
+ * It was declared here and read nowhere: `resolveWorkspace` reads the string literal, so the constant and the
+ * literal could drift with nothing binding them. Re-exporting the single definition keeps this the place a reader
+ * looks for a `PI_GRANTS_*` name without letting two spellings exist.
+ *
+ * Omitting the variable no longer means "let herdr choose": it falls back to the parent's own
+ * `HERDR_WORKSPACE_ID`, because a child in a different workspace from the session that spawned it makes switching
+ * to it a workspace hop (ADR-0032). This name is the operator's explicit override.
  */
-export const ENV_HERDR = "PI_GRANTS_HERDR";
-/** herdr workspace for spawned panes. Omitted lets herdr choose. */
-export const ENV_HERDR_WORKSPACE = "PI_GRANTS_HERDR_WORKSPACE";
+export { ENV_HERDR_WORKSPACE } from "../src/herdr-cli.ts";
 /** Keep each child's pane after it finishes, for inspection. Off by default: fan-out would flood it. */
 export const ENV_HERDR_KEEP_PANE = "PI_GRANTS_HERDR_KEEP_PANE";
 
@@ -76,7 +94,18 @@ export interface GrantsSession {
   readonly malformedBounds: string[];
   readonly gated: Capability[];
   readonly ledgerPath?: string;
-  readonly useHerdr: boolean;
+  /**
+   * Which executor runs this session's children — ADR-0031.
+   *
+   * **Mutable, and for ADR-0030's reason exactly.** Settling it needs a probe, the probe is async, and this
+   * object is built *synchronously* in the extension factory — an ordering S-5 forces, since whether
+   * `delegate` is registered at all is decided there. So it starts as the un-probed reading and is replaced by
+   * `resolveExecutor` once `session_start` has probed.
+   *
+   * Nothing may capture a copy: read it through the session, live. A copy taken in the factory is a copy taken
+   * before the probe, which is the same hazard as capturing `ownGrant` before the tool surface is observed.
+   */
+  executor: ExecutorChoice;
   /** This session's ledger identity; children descend from it (F8). */
   readonly ownSpawnId: string;
   /** Descendants this subtree may still create — the cardinality bound ADR-0008 never had. */
@@ -182,6 +211,22 @@ export async function loadProjectDefinitions(session: GrantsSession, cwd: string
   session.catalog = await session.catalogReady;
 }
 
+/**
+ * Probe for herdr and settle this session's executor — ADR-0031.
+ *
+ * **Once, at session start, and never per spawn.** A fan-out whose children ran under two executors would put
+ * two different things under one call in the ledger, and the two plans differ (`--print` is withheld on the
+ * herdr path). A herdr server that dies mid-session therefore surfaces as a failed `tab create`, reported as
+ * the spawn error it is, rather than as a silent relocation of the remaining children.
+ *
+ * `probeHerdr` never throws, so this cannot either — which matters because it runs *before* the line that
+ * discloses what it decided (R-60: a throw here would cancel that line and every control after it).
+ */
+export async function resolveExecutor(session: GrantsSession): Promise<void> {
+  const raw = process.env[ENV_HERDR];
+  session.executor = chooseExecutor(raw, needsProbe(raw) ? await probeHerdr() : null);
+}
+
 export function createGrantsSession(extensionPath: string | undefined): GrantsSession {
   // Governance is opt-in: with PI_GRANTS_GRANT unset AND no stored grant for this directory, the session
   // holds the wildcard and nothing is blocked. This extension must never silently tighten a normal
@@ -221,7 +266,10 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
     // `PI_GRANTS_GATED=""` turns the default off; absent and empty are deliberately distinguishable.
     gated: governed ? gatedFromEnv(process.env[ENV_GATED]) : parseList(process.env[ENV_GATED]),
     ledgerPath: process.env[ENV_LEDGER],
-    useHerdr: process.env[ENV_HERDR] === "1",
+    // The un-probed reading. `resolveExecutor` replaces it at session start; until then a `1` already reads as
+    // a refusal, which is the safe direction — a delegation that somehow ran before the probe would refuse
+    // rather than quietly use the wrong executor.
+    executor: chooseExecutor(process.env[ENV_HERDR], null),
     // `ownSpawnId` comes from the parent (F8), so ids form one tree across process boundaries instead of
     // every level restarting at `d0` and the ledger becoming unjoinable.
     ownSpawnId: process.env[ENV_PARENT_ID]?.trim() || `d${depth}`,
@@ -267,7 +315,11 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
       // The herdr executor drives the child after starting it, so its plan must NOT carry `--print`.
       // Threaded through the plan rather than patched afterwards: the argv is what the ledger records, and
       // an executor quietly rewriting it would make the record describe a spawn that did not happen.
-      interactive: session.useHerdr,
+      //
+      // Read live off `session.executor` (ADR-0031) rather than a boolean captured in the factory: the probe
+      // has not run when this session object is built, so a captured value would plan `--print` for a session
+      // that turns out to use panes — and `runHerdrPane` refuses a plan containing `--print` by design.
+      interactive: session.executor.kind === "herdr",
       ...(approved ? { approved } : {}),
     }),
 

package/extensions/tripwire.ts

@@ -0,0 +1,44 @@
+/**
+ * The tripwire's vocabulary — which tool names count as a foreign spawner, and what to say when one appears.
+ *
+ * Lifted out of `extensions/grants.ts` so the *message* can be tested without loading pi. That is not
+ * fastidiousness: the message is the whole product of this control. A refusal nothing verifies is a refusal
+ * whose wording drifts, and the wording is what a model acts on.
+ *
+ * The hook that uses these stays in `grants.ts`, because it also writes a ledger record and that needs the
+ * session.
+ */
+
+/**
+ * Tool names that create sub-agents this package did not provision.
+ *
+ * `subagent` is the one seen in the wild — a directory drop-in at `~/.pi/agent/extensions/subagent/`, which pi
+ * auto-loads in **every** session on a machine regardless of `settings.json`. `Agent` and `spawn_agent` are the
+ * other plausible names. **Deliberately a name check and nothing more**: `subagents:rpc:spawn` reaches a
+ * manager over the event bus and never produces a `tool_call` at all (ADR-0013 Finding 6), so this catches the
+ * ordinary case loudly and is not a boundary.
+ */
+export const SPAWN_TOOLS: ReadonlySet<string> = new Set(["Agent", "subagent", "spawn_agent"]);
+
+/**
+ * Why a foreign spawn tool is refused, and what to use instead.
+ *
+ * **Both governed tools are named, and this is the fix rather than a flourish.** The text said only *"Use
+ * `delegate` instead"*. On 2026-08-17 an operator asked for parallel work, `subagent` was refused, and the model
+ * then planned a single sequential `delegate` — a reasonable reading of the only instruction it was given, and
+ * the wrong shape for the request. `delegate_all` existed the whole time.
+ *
+ * A refusal that points at the wrong replacement is a refusal that gets obeyed badly. And it names what is
+ * *lost* rather than only what is forbidden, because a control an operator cannot evaluate is one they route
+ * around — the escape hatch is one unset variable away, so it should be an informed choice.
+ */
+export function tripwireReason(toolName: string): string {
+  return (
+    `grants: "${toolName}" spawns sub-agents outside this session's governance — refused. ` +
+    `This session grants capabilities by spawning them itself, 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\` for a single sub-agent, or \`delegate_all\` to run several CONCURRENTLY — that is the ` +
+    `governed equivalent of a parallel or chained spawn, and it is what to reach for when independent tasks ` +
+    `can proceed at the same time. If you meant to run ungoverned, unset PI_GRANTS_GRANT.`
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Capability governance for pi sub-agents: spawn Agent Skills (SKILL.md) definitions whose allowed-tools becomes a grant that can only narrow going down a delegation tree, enforced by pi's own --tools allowlist, with an append-only ledger.",
   "keywords": [
     "pi-package",
@@ -69,6 +69,22 @@
       "types": "./dist/run-herdr.d.ts",
       "default": "./dist/run-herdr.js"
     },
+    "./herdr-poll": {
+      "types": "./dist/herdr-poll.d.ts",
+      "default": "./dist/herdr-poll.js"
+    },
+    "./herdr-cli": {
+      "types": "./dist/herdr-cli.d.ts",
+      "default": "./dist/herdr-cli.js"
+    },
+    "./executor": {
+      "types": "./dist/executor.d.ts",
+      "default": "./dist/executor.js"
+    },
+    "./progress": {
+      "types": "./dist/progress.d.ts",
+      "default": "./dist/progress.js"
+    },
     "./run-child": {
       "types": "./dist/run-child.d.ts",
       "default": "./dist/run-child.js"

package/src/executor.ts

@@ -0,0 +1,122 @@
+/**
+ * Which executor runs a governed child — ADR-0031.
+ *
+ * `PI_GRANTS_HERDR` is three-state, and **absent means probe**. That reverses ADR-0016 point 6's opt-in, and
+ * the reversal is narrower than it sounds: nothing is detected from `herdr` being on `PATH` (option C, rejected
+ * by name), only from a server that *answered*. The grant, the depth bound, the gate and `--tools` enforcement
+ * are identical either way — `planSpawn` produces one plan and both executors enforce it.
+ *
+ * **Pure on purpose.** The probe is I/O and lives in `herdr-cli.ts`; the DECISION is a table, and a table that
+ * fits on one screen is the only reason a reversal like this is reviewable at all.
+ *
+ * The disclosure string is part of the return value rather than composed at the call site, because ADR-0031's
+ * defence against "this relocates silently" is that every outcome says what it chose AND what to set instead.
+ * Two call sites composing that separately is how one of them comes to omit it (R-28).
+ */
+
+import type { HerdrProbe } from "./herdr-cli.ts";
+
+export const ENV_HERDR = "PI_GRANTS_HERDR";
+
+export type ExecutorKind = "herdr" | "process";
+
+export interface ExecutorChoice {
+  kind: ExecutorKind;
+  /** The operator named it: `PI_GRANTS_HERDR` was exactly `0` or `1`. */
+  forced: boolean;
+  /** Whether a probe was needed at all — false only for `0`. */
+  probed: boolean;
+  /**
+   * Set ONLY when herdr was demanded and is unreachable. Every delegation must refuse with this.
+   *
+   * Note that `kind` stays `"herdr"` in that case, deliberately: nothing downstream may mistake a refusing
+   * session for a working process-executor one.
+   */
+  refusal?: string;
+  /** One line for the session banner and `/grants`. Always present. */
+  disclosure: string;
+}
+
+/** `0` is the one value that needs no probe: the operator ruled herdr out, so asking is pure cost. */
+export function needsProbe(raw: string | undefined): boolean {
+  return raw === undefined || raw === "1";
+}
+
+export function chooseExecutor(raw: string | undefined, probe: HerdrProbe | null): ExecutorChoice {
+  if (raw === "0") {
+    return {
+      kind: "process",
+      forced: true,
+      probed: false,
+      disclosure: "captured subprocess (PI_GRANTS_HERDR=0) — children have no terminal",
+    };
+  }
+
+  if (raw === "1") {
+    if (probe?.ok) {
+      return { kind: "herdr", forced: true, probed: true, disclosure: "herdr panes (PI_GRANTS_HERDR=1)" };
+    }
+    // Refusal, not fallback — the operator's decision of 2026-08-17, against the alternative of falling back
+    // loudly. A fallback nobody reads is R-25's shape; refusing keeps the ledger unable to name a child that
+    // ran somewhere nobody chose. A `null` probe lands here too: if the probe failed so badly it produced no
+    // result, herdr was still demanded, and failing closed means refusing.
+    const why = probe?.error ?? "the herdr probe did not succeed";
+    return {
+      kind: "herdr",
+      forced: true,
+      probed: true,
+      refusal:
+        `PI_GRANTS_HERDR=1 demands the herdr executor and herdr is not answering (${why}). ` +
+        `Delegation is refused rather than quietly relocated to a captured subprocess, so this session's ` +
+        `ledger can never contain a child that ran somewhere nobody chose. Start herdr, or unset ` +
+        `PI_GRANTS_HERDR to let this session probe, or set PI_GRANTS_HERDR=0 to choose subprocesses.`,
+      disclosure: `herdr panes DEMANDED but unreachable (${why}) — every delegation will refuse`,
+    };
+  }
+
+  if (raw !== undefined) {
+    // Rule 8: fail closed and be loud. An unrecognised value must not relocate a run, and must not break
+    // delegation either — the operator meant *something*, and the dependency-free executor is the safe read.
+    // The empty string lands here rather than with `undefined`, which keeps absent-versus-empty
+    // distinguishable exactly as `PI_GRANTS_GATED` does.
+    return {
+      kind: "process",
+      forced: false,
+      probed: probe !== null,
+      disclosure:
+        `captured subprocess — PI_GRANTS_HERDR is set to an unrecognised value and was ignored. ` +
+        `Use 1 (demand herdr panes), 0 (demand subprocesses), or unset it to probe.`,
+    };
+  }
+
+  if (probe?.ok) {
+    return { kind: "herdr", forced: false, probed: true, disclosure: "herdr panes (probed — herdr is answering)" };
+  }
+  if (probe === null) {
+    // **The pre-probe seed, and it must not claim a probe happened.** `createGrantsSession` builds a choice
+    // synchronously with `probe: null` because S-5 forces the factory to run before any hook; `resolveExecutor`
+    // replaces it during `session_start`. This branch previously fell through to the one below and reported
+    // `probed: true` with the word "(probed)" in its disclosure — a fabricated observation, indistinguishable
+    // from a real negative probe.
+    //
+    // Unreachable in practice today (pi awaits the `session_start` emit before the first prompt, verified by a
+    // reviewer against real pi), which is exactly why it is worth making honest rather than leaving to be
+    // discovered: if a throw ever strands a session on this reading, the disclosure should say so.
+    return {
+      kind: "process",
+      forced: false,
+      probed: false,
+      disclosure: "not yet probed — settling at session start",
+    };
+  }
+  return {
+    kind: "process",
+    forced: false,
+    probed: true,
+    // Names the remedy on the same line as the state. The gap that produced ADR-0031 was not that the
+    // operator could not see which executor ran — it was that seeing it would not have told them what to do.
+    disclosure:
+      `captured subprocess (probed — no herdr answering${probe?.error ? `: ${probe.error}` : ""}). ` +
+      `Set PI_GRANTS_HERDR=1 to demand panes.`,
+  };
+}