pi-daddy 0.14.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,
@@ -37,25 +39,53 @@ import {
   parseList,
 } from "../src/propagation.ts";
 import type { Capability } from "../src/resolve.ts";
+import { loadDefinitions } from "../src/definitions.ts";
+import { buildCatalog } from "../src/catalog.ts";
+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";
 
 export interface GrantsSession {
-  /** False when `PI_GRANTS_GRANT` is unset: the session holds the wildcard and nothing is governed. */
-  readonly governed: boolean;
+  /**
+   * False when neither `PI_GRANTS_GRANT` nor a stored grant applies: the session holds the wildcard and
+   * nothing is governed.
+   *
+   * **Mutable, because `/grants init` makes an ungoverned session governed mid-run.** The first version of
+   * ADR-0030 left this readonly on the reasoning that a store is read at creation and `init` only runs where
+   * one exists — which is false for the first `init` in a directory, the most common case there is. The
+   * session then bounded every spawn by the new grant while `/grants` reported "inactive", so the status
+   * line contradicted the enforcer. Found by running it.
+   */
+  governed: boolean;
   /** The upper bound handed down by the delegator, before this session's own tools are observed. */
   readonly inherited: Capability[];
   readonly depth: number;
@@ -64,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. */
@@ -129,6 +170,23 @@ export interface GrantsSession {
    * prompted the human. A value scoped to one specific child is never written to this global channel.
    */
   publishChildEnv(): void;
+  /**
+   * The directory whose stored grant this session read, or would read. `process.cwd()` — see the note in
+   * `createGrantsSession` for why the factory cannot use `ctx.cwd`.
+   */
+  readonly storeCwd: string;
+  /**
+   * Adopt a grant decided DURING the session — `/grants init` answering a human — without a restart.
+   *
+   * Narrow by design: it sets the session's own grant and republishes, so the very next spawn is bounded by
+   * it. It does **not** reach children that already exist; those are separate processes whose environment
+   * was fixed when they started, and reaching into them is neither possible nor desirable — a child's
+   * ceiling should not move under it mid-run.
+   *
+   * Only a human can reach this. Slash commands are user-invoked; no tool exposes it, so a model cannot
+   * widen its own session's ceiling by calling something.
+   */
+  adoptGrant(grant: Capability[]): void;
 }
 
 /**
@@ -138,12 +196,56 @@ export interface GrantsSession {
  * extension**, so a child granted `tool:delegate` can be started with `-e <that file>`. `grants.ts` is that
  * file, and only `grants.ts` can say so about itself.
  */
+/**
+ * Load this project's definitions and capability catalog into the session.
+ *
+ * **One loader, two callers.** `session_start` runs it, and so does `/grants init` — which writes the very
+ * files it reads, so a session that skipped this held `agent:review` while believing no definition of that
+ * name existed, and the model was told `Available: none` (R-39's shape, reintroduced by the feature whose
+ * selling point is "no restart"). Two copies of these three steps is how the two callers come to disagree
+ * about what loading means, so there is one.
+ */
+export async function loadProjectDefinitions(session: GrantsSession, cwd: string): Promise<void> {
+  session.definitions = await loadDefinitions(cwd);
+  session.catalogReady = buildCatalog({ cwd, observedTools: session.observedTools });
+  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 the session holds the wildcard and nothing is
-  // blocked. This extension must never silently tighten a normal workflow.
+  // 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
+  // workflow.
+  //
+  // **Two sources, and the environment always wins** (ADR-0030). The variable is how a CHILD is governed
+  // and how CI is configured, so a store that could override it would let a directory quietly widen or
+  // narrow a child its parent had already bounded. The store is consulted only when the variable is absent,
+  // which is exactly the case it was added for: a human at a terminal who ran `/grants init` here.
+  //
+  // `process.cwd()` rather than `ctx.cwd`, because this runs in the extension factory — before any hook,
+  // and therefore before `ctx` exists. That ordering is forced by S-5: whether `delegate` is registered at
+  // all is decided here, and a grant arriving later could not inform it. `session_start` re-checks the two
+  // against each other and says so if they differ, which is the only case this can get wrong.
   const grantRaw = process.env[ENV_GRANT];
-  const governed = grantRaw !== undefined;
-  const inherited: Capability[] = governed ? parseList(grantRaw) : [WILDCARD];
+  const storeCwd = process.cwd();
+  const stored = grantRaw === undefined ? loadGrantSync(storeCwd) : null;
+  const governed = grantRaw !== undefined || stored !== null;
+  const inherited: Capability[] = grantRaw !== undefined ? parseList(grantRaw) : (stored ?? [WILDCARD]);
   // G7 / A-S4 + B-I4: strict, three-way parsing that fails CLOSED. A malformed bound used to yield
   // `NaN`, and every comparison against `NaN` is false, so depth limiting switched itself off.
   const bounds = depthConfig(process.env[ENV_DEPTH], process.env[ENV_MAX_DEPTH]);
@@ -164,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}`,
@@ -210,10 +315,26 @@ 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 } : {}),
     }),
 
+    storeCwd,
+
+    adoptGrant: (grant: Capability[]) => {
+      // Governed too, not just bounded. A session that starts with no grant and then runs `/grants init` is
+      // governed from that moment: every spawn is bounded by what was just stored. Leaving this false made
+      // `/grants` print "inactive" while holding thirteen capabilities — a status line contradicting the
+      // enforcer, which is the defect R-28 is named for.
+      session.governed = true;
+      session.ownGrant = grant;
+      session.publishChildEnv();
+    },
+
     publishChildEnv: () => {
       const env = childEnv({
         ownGrant: session.ownGrant,

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.14.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/cli.ts

@@ -19,7 +19,7 @@ import { relative, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
 import { UnsafeGrantError } from "./grant-env.ts";
 import { applyInit, countDeclaring, planInit, type InitPlan } from "./init.ts";
-import { discoverSkillPackages, type RefusedSkill, type SkillPackage } from "./skill-packages.ts";
+import { discoverSkillPackages, skillPackageRoots, type RefusedSkill, type SkillPackage } from "./skill-packages.ts";
 
 const USAGE = `pi-daddy — capability governance for pi sub-agents
 
@@ -93,10 +93,16 @@ export function parseArgs(argv: string[]): ParsedArgs {
 async function init(cwd: string, force: boolean): Promise<number> {
   const packages = await discoverSkillPackages(cwd);
   if (packages.length === 0) {
+    // Names BOTH roots it looked in, and offers pi's own install command first. The previous message named
+    // only `<cwd>/node_modules` and said "npm install …" — so an operator who had just run
+    // `pi install npm:principal-pi-skills`, which installs to the agent root, was told to install a package
+    // they had already installed (R-75).
     console.log(
-      `pi-daddy init: no installed package under ${cwd}/node_modules declares skills\n` +
-        `(a package.json "pi": {"skills": [...]} field). Nothing to scaffold.\n\n` +
-        `  npm install principal-pi-skills   # seven skills; then re-run this`,
+      `pi-daddy init: no installed package declares skills (a package.json "pi": {"skills": [...]} ` +
+        `field). Nothing to scaffold.\n\nLooked in:\n` +
+        skillPackageRoots(cwd).map((r) => `  ${r}\n`).join("") +
+        `\n  pi install npm:principal-pi-skills    # seven skills, and registers it with pi\n` +
+        `  npm install principal-pi-skills      # or pin it in this project instead`,
     );
     return 0;
   }