pi-daddy 0.18.1 → 0.20.0

package/extensions/grants-command.ts

@@ -60,6 +60,8 @@ export interface GrantsCommandContext {
    * from the caller, visibly.
    */
   runInit: () => Promise<void>;
+  /** Open or reuse the read-only Herdr dashboard; injected so this diagnostic never becomes enforcement. */
+  openDashboard: () => Promise<{ kind: "opened" | "reused"; paneId: string; visibleBesideCaller: boolean }>;
 }
 
 /**
@@ -69,12 +71,12 @@ export interface GrantsCommandContext {
 const PREVIEW_LIMIT = 12;
 
 /** The verbs `/grants` answers to. Anything else is refused rather than silently treated as no verb. */
-const KNOWN_SUBCOMMANDS: readonly string[] = ["init", "ledger", "approvals", "revoke"];
+const KNOWN_SUBCOMMANDS: readonly string[] = ["init", "dashboard", "ledger", "approvals", "revoke"];
 
 export const grantsCommand = {
   description:
     "Show this session's capability grant, delegation depth, and known agent-type ceilings; " +
-    "/grants approvals | /grants ledger | /grants revoke <key>|--all",
+    "/grants dashboard | /grants approvals | /grants ledger | /grants revoke <key>|--all",
 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).
@@ -90,6 +92,20 @@ handler: async (args: string, ctx: any) => {
       return;
     }
 
+    if (sub === "dashboard") {
+      try {
+        const opened = await ctx.grants.openDashboard();
+        ctx.ui.notify(
+          `grants: dashboard ${opened.kind} in Herdr pane ${opened.paneId} without changing focus` +
+            (opened.visibleBesideCaller ? "." : " (the existing pane is in another tab)."),
+          "info",
+        );
+      } catch (error) {
+        ctx.ui.notify(`grants: dashboard unavailable — ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+      return;
+    }
+
     if (sub === "ledger") {
       // The detector, made reachable. `verifyLedger` exists because nothing in this package had ever read
       // a ledger back, so a torn line was indistinguishable from a spawn that never happened — and a
@@ -109,7 +125,7 @@ handler: async (args: string, ctx: any) => {
         `  escalation ${report.escalationAttempts} attempt(s) — grants refused for exceeding what the session held`,
         `  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}`);
+      for (const bad of report.corrupt.slice(0, 5)) lines.push(`    line ${bad.line}: ${bad.reason}`);
       // 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
@@ -121,6 +137,9 @@ handler: async (args: string, ctx: any) => {
             ? ` · ${report.executors.unknown} not recorded (written before 0.16.0, which added the field)`
             : ""),
       );
+      if (report.workflowFacts > 0) {
+        lines.push(`  workflow   ${report.workflowFacts} provenance-labelled fact(s) — not counted as enforced children`);
+      }
       // 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
@@ -330,9 +349,19 @@ handler: async (args: string, ctx: any) => {
       `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +
         `${inheritedApprovals.size > 0 ? `, ${inheritedApprovals.size} inherited` : ""}` +
         ` — /grants approvals`,
+      // Every kind the catalog can hold is named, and the numbers add up to the total on purpose. `workspace`
+      // was missing when ADR-0035's review added the kind: the total counted them and the breakdown did not,
+      // so `catalog 16 capabilities — 9 builtin, 0 extension, 2 skill, 2 agent-type` printed a sum of 13. And
+      // the comment that justified putting workspaces in the catalog said it was "for `/grants` to list what
+      // this session may route to", which nothing then did — the claim was in the commit and the behaviour
+      // was not. A kind added without a term here silently stops adding up.
       `  catalog    ${catalog.all.length} capabilities — ` +
         `${catalog.byKind("builtin").length} builtin, ${catalog.byKind("extension").length} extension, ` +
-        `${catalog.byKind("skill").length} skill, ${catalog.byKind("agentType").length} agent-type`,
+        `${catalog.byKind("skill").length} skill, ${catalog.byKind("agentType").length} agent-type, ` +
+        `${catalog.byKind("workspace").length} workspace`,
+      ...(catalog.byKind("workspace").length > 0
+        ? [`  routable   ${catalog.byKind("workspace").join(", ")} — held ones only are usable (ADR-0035)`]
+        : []),
     ];
     // Runs the REAL planner AND the real approval step over each definition, so this listing cannot
     // disagree with what a spawn would do — the R-28 lesson, kept structural rather than remembered.

package/extensions/grants.ts

@@ -22,9 +22,12 @@
  */
 
 import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { WILDCARD } from "../src/pi-tools.ts";
 import { buildCatalog } from "../src/catalog.ts";
+import { ENV_WORKSPACE_REGISTRY } from "../src/workspace.ts";
 import { appendRecord, buildRecord } from "../src/ledger.ts";
 import { openPaneCount, reapOpenPanesAsync } from "../src/pane-reaper.ts";
 import {
@@ -37,6 +40,11 @@ import { planWithApprovals } from "./run-delegation.ts";
 import { createGrantsSession, loadProjectDefinitions, resolveExecutor, type GrantsSession } from "./session.ts";
 import { reportSessionStart } from "./session-report.ts";
 import { SPAWN_TOOLS, tripwireReason } from "./tripwire.ts";
+import {
+  defaultDashboardPaths,
+  offerDashboardHandshake,
+  openDashboardCommand,
+} from "../src/dashboard-handshake.ts";
 
 export default function (pi: ExtensionAPI) {
   // The path pi loads as the extension, so a child granted `tool:delegate` can be started with `-e <this>`.
@@ -50,6 +58,10 @@ export default function (pi: ExtensionAPI) {
   })();
 
   const session = createGrantsSession(extensionPath);
+  const dashboardPluginRoot = fileURLToPath(new URL("../herdr-plugin/", import.meta.url));
+  const dashboardPaths = defaultDashboardPaths(
+    process.env.PI_CODING_AGENT_DIR?.trim() || join(homedir(), ".pi", "agent"),
+  );
 
   // Filled in by `registerDelegationTools` at the bottom of this function. A holder rather than a reordering,
   // because the hooks below have to be registered before the tools and both need to call it — the tool
@@ -58,6 +70,10 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", async (_event, ctx) => {
     session.cwd = ctx.cwd;
+    // A routed child changes cwd. Publishing a relative ledger string unchanged therefore fragments one
+    // execution tree across workspaces. Resolve it once at the root's actual pi cwd; descendants inherit
+    // this absolute identity verbatim, and resolve(abs) remains abs at every deeper session start.
+    if (session.ledgerPath) session.ledgerPath = resolve(ctx.cwd, session.ledgerPath);
     // The one case the stored-grant lookup can get wrong (ADR-0030). The factory reads the store keyed by
     // `process.cwd()` because it runs before any hook and therefore before `ctx` exists — and S-5 forces
     // that ordering, since whether `delegate` is registered is decided there. Almost always the two agree.
@@ -151,6 +167,27 @@ export default function (pi: ExtensionAPI) {
           "warning",
         );
       }
+      // Explicit installation handshake. It only runs in a Herdr-hosted TUI, asks once, and the only branch
+      // that links software is the literal human choice "Install and open".
+      try {
+        await offerDashboardHandshake({
+          mode: ctx.mode,
+          env: process.env,
+          pid: process.pid,
+          cwd: ctx.cwd,
+          ledgerPath: session.ledgerPath,
+          pluginRoot: dashboardPluginRoot,
+          preferencePath: dashboardPaths.preferencePath,
+          paneStatePath: dashboardPaths.paneStatePath,
+          ui: ctx.ui,
+        });
+      } catch (error) {
+        ctx.ui.notify(
+          `grants: dashboard installation handshake could not run (${error instanceof Error ? error.message : String(error)}). ` +
+            `Nothing was installed; /grants dashboard will report manual setup.`,
+          "warning",
+        );
+      }
     } catch (error) {
       // Rule 8 — fail closed, and be LOUD about it. Swallowing is still right: a startup fault must not
       // reach the agent loop. Swallowing SILENTLY is what let R-60 exist, and would let the next one exist
@@ -216,7 +253,11 @@ export default function (pi: ExtensionAPI) {
       // Keep the handle: a concurrent `delegate` awaits this rather than reading a half-built catalog.
       // The `catch` resolves to the CURRENT catalog rather than rejecting, so a failed refresh degrades
       // to the previous view instead of failing every delegation in the session.
-      session.catalogReady = buildCatalog({ cwd: session.cwd, observedTools: names })
+      session.catalogReady = buildCatalog({
+        cwd: session.cwd,
+        observedTools: names,
+        registryPath: process.env[ENV_WORKSPACE_REGISTRY],
+      })
         .then((c) => (session.catalog = c))
         .catch(() => session.catalog);
     } catch {
@@ -311,6 +352,14 @@ export default function (pi: ExtensionAPI) {
               await loadProjectDefinitions(session, ctx.cwd);
               delegation.refreshSpawnable();
             }),
+          openDashboard: () => openDashboardCommand({
+            env: process.env,
+            pid: process.pid,
+            cwd: ctx.cwd,
+            ledgerPath: session.ledgerPath,
+            pluginRoot: dashboardPluginRoot,
+            paneStatePath: dashboardPaths.paneStatePath,
+          }),
           previewDelegation: (name: string) =>
             planWithApprovals(session, { task: "(preview)", agent: name }, {}, null),
         },

package/extensions/init-command.ts

@@ -9,6 +9,7 @@
 
 import { discoverSkillPackages } from "../src/skill-packages.ts";
 import { applyInit, planInit } from "../src/init.ts";
+import { registeredWorkspaceIds } from "../src/workspace.ts";
 import { saveGrant, grantStorePath } from "../src/grant-store.ts";
 import { expandSubsumed, SUBSUMPTION, type Capability } from "../src/resolve.ts";
 import type { GrantsSession } from "./session.ts";
@@ -50,7 +51,7 @@ export async function runInit(
     return;
   }
 
-  const plan = planInit(packages, ctx.cwd);
+  const plan = planInit(packages, ctx.cwd, await registeredWorkspaceIds());
   const outcome = await applyInit(plan);
   const lines = [
     `grants: ${plan.skills.length} definition(s) from ${packages.map((p) => `${p.name}@${p.version}`).join(", ")}`,
@@ -81,9 +82,28 @@ export async function runInit(
       for (const name of neededBy) grant.add(`agent:${name}` as Capability);
       continue;
     }
+    // The consequence sentence is per capability, and it reads the gate **in effect for this session** —
+    // `session.gated`, which is `PI_GRANTS_GATED` when the operator set it and `DEFAULT_GATED` otherwise.
+    //
+    // The first version read `DEFAULT_GATED` directly, which is the compile-time constant `["tool:bash"]`, and
+    // `tool:bash` is consumed by the branch above — so the branch was **unreachable in every configuration**,
+    // and with `PI_GRANTS_GATED="tool:bash,tool:write"` (the value `renderGrantEnv` itself suggests) the
+    // dialog still printed the exact false sentence the fix claimed to remove. Dead code beside a claim that
+    // it worked, which is this project's failure mode, in the commit correcting that failure mode.
+    // No subsumption closure here, and the absence is deliberate. A `|| SUBSUMPTION[capability]…` disjunct was
+    // added and is **dead in every configuration**: `SUBSUMPTION` has one key, `tool:bash`, and `tool:bash` is
+    // consumed by the ternary below before `gatedAtSpawn` is ever read. Two reviewers and a mutation confirmed
+    // it changed no result — dead code beside a claim that it worked, in the hunk whose comment denounces
+    // exactly that. A second `SUBSUMPTION` entry is the moment to add it back.
+    const gatedAtSpawn = session.gated.includes(capability);
     const answer = await ctx.ui.select(
       `grants: grant ${capability} to sub-agents?\n  needed by: ${neededBy.join(", ")}\n` +
-        `  this can change your machine — ${capability === "tool:bash" ? "and bash also confers write and edit" : "it is not gated, so no dialog at spawn time"}`,
+        `  this can change your machine — ` +
+        (capability === "tool:bash"
+          ? "and bash also confers write and edit"
+          : gatedAtSpawn
+            ? "a human is still asked at spawn time"
+            : "it is not gated, so no dialog at spawn time"),
       ["No", "Yes"],
     );
     if (answer === "Yes") {
@@ -121,6 +141,17 @@ export async function runInit(
     lines.push(`  ALREADY CONFERRED, not asked about: ${alreadyConferred.join(", ")}`);
   }
   if (declined.length > 0) lines.push(`  withheld: ${declined.join("; ")}`);
+  // Routing is LISTED, never granted (ADR-0028) — so the operator has to be told it exists, or the listing is
+  // invisible to anyone running `/grants init` in-session rather than reading the generated file. 0.19.0 made
+  // `workspace:<id>` mandatory for routing, so this is also the migration hint, and a breaking change whose
+  // migration is only discoverable by opening a file is not much of a migration.
+  if (plan.routableWorkspaces.length > 0) {
+    lines.push(
+      `  ROUTABLE WORKSPACES, listed and NOT granted: ${plan.routableWorkspaces.join(", ")}`,
+      `    routing a child to one needs its id in the grant (ADR-0035); add the ones this project may use to ` +
+        `${plan.grantEnvPath}. Which worktree a child starts in is not something a package can declare for you.`,
+    );
+  }
   lines.push(`  live now (${finalGrant.length} capabilities) — no restart. /grants shows the verdicts.`);
   ctx.ui.notify(lines.join("\n"), "info");
 }

package/extensions/run-delegation.ts

@@ -13,7 +13,6 @@
 
 import { DELEGATE_SUBJECT, shouldSeekApproval } from "../src/approval.ts";
 import { planDelegation } from "../src/delegate.ts";
-import { appendRecord, buildRecord } from "../src/ledger.ts";
 import {
   obtainApprovals,
   republishable,
@@ -27,6 +26,8 @@ import type { GrantsSession } from "./session.ts";
 import type { CorrelationMetadata } from "../src/correlation.ts";
 import { GovernanceRefusal, refusal as structuredRefusal } from "../src/refusals.ts";
 import { executePlannedChild, type DelegationOutcome } from "./execute-child.ts";
+import { recordDelegationDecision, type ApprovalLedgerFacts } from "./delegation-ledger.ts";
+import type { ExecutionOccurrenceIds } from "./execution-occurrence.ts";
 import {
   governedWorkspaceAccess,
   prepareDelegationWorkspace,
@@ -178,7 +179,7 @@ export async function planWithApprovals(
 export async function runOneDelegation(
   session: GrantsSession,
   spec: ChildSpec,
-  ids: { parentId: string; childId: string },
+  ids: ExecutionOccurrenceIds,
   budget: number | undefined,
   ctx: DelegationToolContext,
   signal: AbortSignal | undefined,
@@ -207,7 +208,7 @@ export async function runOneDelegation(
       paneId?: string;
       /** The name herdr actually knows this child by — minted in `runHerdrPane`, so it cannot be derived. */
       agentName?: string;
-      state?: "running" | "completed" | "failed";
+      state?: "starting" | "running" | "completed" | "failed";
     }) => void;
     /** Approvals already obtained by the caller — see `planWithApprovals`. `delegate_chain` uses it. */
     preApproved?: InheritableApproval[];
@@ -218,6 +219,8 @@ export async function runOneDelegation(
      * the question the chain's framed-rather-than-enforced handoff makes worth asking.
      */
     taskFrom?: string;
+    /** Unique occurrence whose output composed this task; separate from the logical taskFrom position. */
+    taskFromExecutionId?: string;
     /**
      * What the caller's own gate decided, for the LEDGER — not for the plan.
      *
@@ -228,10 +231,10 @@ export async function runOneDelegation(
      * where nothing was ever gated — `/grants ledger` counted it in neither `bySource` nor `unattributed`, so it did
      * not even show up as a gap, and ADR-0010's compensating control was blind to every chain step.
      */
-    approvalFacts?: Pick<ApprovalOutcome, "approved" | "sources" | "scopes" | "expiresAt" | "uses" | "humanDenied">;
+    approvalFacts?: ApprovalLedgerFacts;
   } = {},
 ): Promise<DelegationOutcome> {
-  const { onProgress, preApproved, taskFrom, approvalFacts } = options;
+  const { onProgress, preApproved, taskFrom, taskFromExecutionId, approvalFacts } = options;
   // pi resolves a BARE model id to an unauthenticated provider and the child dies at startup — the id
   // alone is not enough, it must be qualified with its provider (`Model<Api>` carries both).
   const defaultModel = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
@@ -249,7 +252,12 @@ export async function runOneDelegation(
     boundWorkspaceId: spec.workspace?.workspace_id,
     boundContextId: spec.correlation?.context_id,
   };
-  const extra = { fanoutBudget: budget, spawnId: ids.parentId, childSpawnId: ids.childId };
+  const extra = {
+    fanoutBudget: budget,
+    spawnId: ids.parentId,
+    childSpawnId: ids.childId,
+    childExecutionId: ids.executionId,
+  };
 
   // ADR-0031: herdr was DEMANDED (`PI_GRANTS_HERDR=1`) and is not answering. Refused rather than relocated —
   // the operator chose that over falling back, so the ledger can never name a child that ran somewhere nobody
@@ -269,7 +277,6 @@ export async function runOneDelegation(
   let preparedWorkspace: PreparedWorkspace | undefined;
   let approvalOutcome: ApprovalOutcome | undefined;
   let plan: ReturnType<typeof planDelegation>;
-  let ledgerDenied = false;
 
   if (spec.workspace && !executorRefusal) {
     // Check non-liftable refusals before taking a lease, and take the lease before asking a human. This
@@ -283,6 +290,8 @@ export async function runOneDelegation(
           spec: { ...spec.workspace, access: governedWorkspaceAccess(spec.workspace.access, plan.requested) },
           correlation: spec.correlation,
           childId: ids.childId,
+          executionId: ids.executionId,
+          parentExecutionId: ids.parentExecutionId,
           signal,
           ledgerPath: session.ledgerPath,
         });
@@ -308,55 +317,19 @@ export async function runOneDelegation(
     plan = { ...plan, ok: false, reason: message, refusal: structuredRefusal("EXECUTOR_UNAVAILABLE", message) };
   }
 
-  // G6 / B-I3: no `&& plan.result` guard — `planDelegation` always carries one now.
-  if (session.ledgerPath) {
-    await appendRecord(
-      { path: session.ledgerPath, strict: true },
-      buildRecord({
-        // F8: real ids, not depth labels. Four concurrent siblings used to produce four lines identical
-        // except `ts`, so the ledger could not be joined to a result, a process, or the child's own
-        // lines one level down.
-        parentId: ids.parentId,
-        childId: ids.childId,
-        depth: plan.childDepth,
-        agentType: spec.agent ?? "delegate",
-        // ADR-0031: where this child actually ran. Read off the live session, which the probe has settled
-        // by now, so the record and the executor cannot disagree.
-        executor: session.executor.kind,
-        taskFrom,
-        requested: plan.requested,
-        parentGrant: session.ownGrant,
-        result: plan.result,
-        blocked: !plan.ok,
-        reason: plan.reason,
-        // `approvalOutcome` when this call's own gate ran; `approvalFacts` when a caller gated upfront on our behalf
-        // (a chain). Without the second, an approved chain step recorded nothing about the human who authorised it.
-        approved: approvalOutcome?.approved ?? approvalFacts?.approved,
-        approvalSources: approvalOutcome?.sources ?? approvalFacts?.sources,
-        approvalScopes: approvalOutcome?.recordedScopes ?? approvalFacts?.scopes,
-        approvalExpiresAt: approvalOutcome?.expiresAt ?? approvalFacts?.expiresAt,
-        approvalUses: approvalOutcome?.uses ?? approvalFacts?.uses,
-        humanDenied: approvalOutcome?.humanDenied ?? approvalFacts?.humanDenied,
-        gateOutcome: approvalOutcome?.gateOutcome,
-        // ADR-0018: taken from the PLAN, never re-derived here. The B-I3 lesson — a call site that
-        // recomputed the digest could record one the planner never used.
-        definitionDigest: plan.definitionDigest,
-        taskDigest: plan.taskDigest,
-        correlation: plan.correlation,
-        refusal: plan.refusal,
-        now: new Date(),
-      }),
-    ).catch((error) => {
-      // G6 / A-R4 + B-I2: fail closed. This path PROVISIONS, so an unrecorded delegation would be a
-      // child running with granted capabilities and no audit line.
-      plan = {
-        ...plan,
-        ok: false,
-        reason: `grants: ledger write failed, denying — ${String(error)}`,
-        refusal: structuredRefusal("LEDGER_WRITE_FAILED", `grants: ledger write failed, denying — ${String(error)}`),
-      };
-      ledgerDenied = true;
+  // The capability decision provisions the child, so this append remains load-bearing and fails closed.
+  try {
+    await recordDelegationDecision({
+      session, plan, ids, agent: spec.agent, taskFrom, taskFromExecutionId,
+      approval: approvalOutcome, approvalFacts,
     });
+  } catch (error) {
+    plan = {
+      ...plan,
+      ok: false,
+      reason: `grants: ledger write failed, denying — ${String(error)}`,
+      refusal: structuredRefusal("LEDGER_WRITE_FAILED", `grants: ledger write failed, denying — ${String(error)}`),
+    };
   }
 
   if (!plan.ok) {
@@ -368,7 +341,12 @@ export async function runOneDelegation(
     // unwritable an unguarded call replaced the governance refusal, and its code, with a ledger error.
     try {
       await releaseDelegationWorkspace({
-        prepared: preparedWorkspace, childId: ids.childId, ledgerPath: session.ledgerPath, reason: "refused",
+        prepared: preparedWorkspace,
+        childId: ids.childId,
+        executionId: ids.executionId,
+        parentExecutionId: ids.parentExecutionId,
+        ledgerPath: session.ledgerPath,
+        reason: "refused",
       });
     } catch (error) {
       plan = { ...plan, reason: `${plan.reason ?? "refused"}; workspace release record failed: ${String(error)}` };
@@ -389,6 +367,8 @@ export async function runOneDelegation(
     plan,
     agent: spec.agent,
     childId: ids.childId,
+    executionId: ids.executionId,
+    parentExecutionId: ids.parentExecutionId,
     cwd: ctx.cwd,
     preparedWorkspace,
     signal,

package/extensions/session-report.ts

@@ -80,16 +80,6 @@ export async function reportSessionStart(session: GrantsSession, ctx: SessionRep
   } 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
@@ -103,16 +93,19 @@ export async function reportSessionStart(session: GrantsSession, ctx: SessionRep
       "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",
-    );
-  }
+  // REMOVED 2026-08-21. This warned that an `agent:` id in `PI_GRANTS_GATED` "does NOT gate spawning that
+  // definition — a human is never asked". It was R-47's PARTIAL fix (0.11.1) and became false one release
+  // later at 0.12.0, when ADR-0024's gate landed (`4673348`, "gating a definition asks before it runs") and
+  // a gated `agent:<name>` began blocking the spawn until somebody approved it. ADR-0024's own Costs section
+  // leaned on this warning — "mitigated by the fact that the warning shipped hours earlier tells them it
+  // currently does nothing" — and nothing retired it when its own decision made the mitigation false.
+  //
+  // So from 0.12.0 through 0.18.1 the session banner told operators to delete a gate that works, and
+  // `test-integration/governance.it.ts` REQUIRED it to, which is how a stale claim outlives the person who
+  // notices. It is R-28's shape in the direction that talks somebody OUT of a control. ADR-0035 then
+  // repeated the pattern one namespace over by claiming a `workspace:` gate that did not exist; both are
+  // gates now, so there is nothing inert left to warn about. Deleted rather than reworded — a warning with
+  // no live case is the next stale claim. R-134.
   // 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

package/extensions/session.ts

@@ -31,6 +31,7 @@ import {
   gatedFromEnv,
   ENV_APPROVED,
   ENV_DEPTH,
+  ENV_EXECUTION_ID,
   ENV_FANOUT,
   ENV_GATED,
   ENV_GRANT,
@@ -42,6 +43,7 @@ import {
 import type { Capability } from "../src/resolve.ts";
 import { loadDefinitions } from "../src/definitions.ts";
 import { buildCatalog } from "../src/catalog.ts";
+import { ENV_WORKSPACE_REGISTRY } from "../src/workspace.ts";
 import { loadGrantSync, grantStorePath } from "../src/grant-store.ts";
 import { republishable } from "./approvals.ts";
 
@@ -94,7 +96,8 @@ export interface GrantsSession {
   /** Bound variables that could not be read as non-negative integers — spawning is disabled, loudly. */
   readonly malformedBounds: string[];
   readonly gated: Capability[];
-  readonly ledgerPath?: string;
+  /** Resolved against the actual pi cwd at session start, then inherited verbatim by every descendant. */
+  ledgerPath?: string;
   /**
    * Which executor runs this session's children — ADR-0031.
    *
@@ -107,8 +110,10 @@ export interface GrantsSession {
    * 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). */
+  /** This session's readable logical ledger identity; children descend from it (F8). */
   readonly ownSpawnId: string;
+  /** Unique identity when this session is itself a governed child; roots have no governed parent. */
+  readonly ownExecutionId?: string;
   /** Descendants this subtree may still create — the cardinality bound ADR-0008 never had. */
   readonly fanoutBudget: number;
   /** Whether `delegate` / `delegate_all` are registered at all (S-5). Decided on the INHERITED grant. */
@@ -210,7 +215,14 @@ export interface GrantsSession {
  */
 export async function loadProjectDefinitions(session: GrantsSession, cwd: string): Promise<void> {
   session.definitions = await loadDefinitions(cwd);
-  session.catalogReady = buildCatalog({ cwd, observedTools: session.observedTools });
+  session.catalogReady = buildCatalog({
+    cwd,
+    observedTools: session.observedTools,
+    // ADR-0035: `workspace:<id>` is a capability, so the registered ids belong in the catalog the same way
+    // discovered definitions do — for `/grants` to list what this session may route to and for `init` to
+    // scaffold them. Read live rather than cached at load, because the registry is an operator file.
+    registryPath: process.env[ENV_WORKSPACE_REGISTRY],
+  });
   session.catalog = await session.catalogReady;
 }
 
@@ -276,6 +288,7 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
     // `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}`,
+    ownExecutionId: process.env[ENV_EXECUTION_ID]?.trim() || undefined,
     // The cardinality bound ADR-0008 never had: it attenuates downward like depth, so a subtree can never
     // create more descendants than its root was given — with no shared state, no lock and no counter file.
     fanoutBudget: budgetFromEnv(process.env[ENV_FANOUT]),

package/extensions/workspace-runtime.ts

@@ -23,12 +23,39 @@ export interface DelegationWorkspaceSpec {
   access: WorkspaceAccess;
 }
 
+/**
+ * Tools that cannot change a worktree.
+ *
+ * **`tool:delegate` is deliberately NOT here, and that is a scope decision.** It was added, and it was true of
+ * the capability and false of the code: a routed child's cwd IS the leased root, `PI_GRANTS_LEDGER` was
+ * passed through relative (`init` scaffolds `.pi/grants.jsonl`), and a `read` lease takes no kernel lock — so
+ * two delegating children classified `read` both created `.pi/` in one worktree and neither excluded the
+ * other. Making `tool:delegate` non-writing requires first making every child-inherited path absolute, and
+ * that is a change to the ledger and lease plumbing rather than to ADR-0035. Tracked as R-141.
+ */
 const KNOWN_READ_ONLY_TOOLS = new Set(["tool:read", "tool:grep", "tool:find", "tool:ls"]);
 
-/** A model may ask for stricter coordination but cannot label a write-capable grant read-only. */
+/**
+ * A model may ask for stricter coordination but cannot label a write-capable grant read-only.
+ *
+ * **Only a TOOL is considered, and that is a fix rather than an oversight.** The check used to require *every*
+ * requested capability to be a known read-only tool, which was correct while `tool:` and `ext:` were the only
+ * things that could appear — and became wrong the moment ADR-0035's review made `workspace:<id>` grantable to
+ * a child. Measured: `governedWorkspaceAccess("read", ["tool:read", "workspace:staging"])` returned `"write"`,
+ * so the intended shape — *route this child read-only and let it route its own grandchild* — silently took an
+ * exclusive writer lease, blocked every other writer on that root, and recorded `access: "write"` in the
+ * ledger when the operator had asked for `read`. A record asserting a stronger claim than anybody made is the
+ * same failure this whole review is about, pointing the other way.
+ *
+ * A `workspace:`, `agent:` or `skill:` id confers no filesystem ability whatsoever: routing chooses a
+ * directory, `agent:` authorises a definition whose ceiling is still clipped to the child's own grant, and
+ * `skill:` loads instructions. None of them can write, so none of them should force a writer lease. If a
+ * descendant does hold a write tool, that tool is in `requested` and this check refuses on its own terms.
+ */
 export function governedWorkspaceAccess(declared: WorkspaceAccess, requested: readonly Capability[]): WorkspaceAccess {
   if (declared === "write") return "write";
-  return requested.every((capability) => KNOWN_READ_ONLY_TOOLS.has(capability)) ? "read" : "write";
+  const tools = requested.filter((c) => c.startsWith("tool:") || c.startsWith("ext:"));
+  return tools.every((capability) => KNOWN_READ_ONLY_TOOLS.has(capability)) ? "read" : "write";
 }
 
 export interface PreparedWorkspace {
@@ -42,6 +69,8 @@ export async function prepareDelegationWorkspace(input: {
   spec: DelegationWorkspaceSpec;
   correlation?: CorrelationMetadata;
   childId: string;
+  executionId: string;
+  parentExecutionId: string | null;
   signal?: AbortSignal;
   ledgerPath?: string;
 }): Promise<PreparedWorkspace> {
@@ -75,6 +104,8 @@ export async function prepareDelegationWorkspace(input: {
       await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          executionId: input.executionId,
+          parentExecutionId: input.parentExecutionId,
           childId: input.childId,
           workspaceId: workspace.workspaceId,
           root: workspace.root,
@@ -98,6 +129,8 @@ export async function prepareDelegationWorkspace(input: {
       await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          executionId: input.executionId,
+          parentExecutionId: input.parentExecutionId,
           childId: input.childId,
           workspaceId: workspace.workspaceId,
           root: workspace.root,
@@ -124,6 +157,8 @@ export async function prepareDelegationWorkspace(input: {
 export async function releaseDelegationWorkspace(input: {
   prepared: PreparedWorkspace | undefined;
   childId: string;
+  executionId: string;
+  parentExecutionId: string | null;
   ledgerPath?: string;
   reason: string;
   /** Deliberately keep the lease: a herdr writer tab would not close, so the pane may still be live. */
@@ -133,13 +168,18 @@ export async function releaseDelegationWorkspace(input: {
   // A retained lease writes no `state: "released"`, so the record stays `active` and the NEXT owner reads
   // it as a crash — the exact blame `retained` was added to remove. Marking it keeps the successor honest;
   // R-104 was fixed in the release event's wording only.
-  const outcome: LeaseReleaseOutcome | "retained" = input.retain
-    ? (await input.prepared.lease.markRetained(input.reason), "retained")
+  // **Ledger what happened, not what was intended (R-152).** This used to discard `markRetained`'s result and
+  // write the word "retained" unconditionally, so a helper that had already died, or a lease already released,
+  // was still recorded as a pane that may still be live.
+  const outcome: LeaseReleaseOutcome = input.retain
+    ? await input.prepared.lease.markRetained(input.reason)
     : await input.prepared.lease.release(input.reason);
   if (input.ledgerPath) {
     await appendLedgerEvent(
       { path: input.ledgerPath, strict: true },
       buildWorkspaceLeaseEvent({
+        executionId: input.executionId,
+        parentExecutionId: input.parentExecutionId,
         childId: input.childId,
         workspaceId: input.prepared.workspace.workspaceId,
         root: input.prepared.workspace.root,