pi-daddy 0.18.1 → 0.19.0

package/extensions/grants-command.ts

@@ -330,9 +330,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

@@ -25,6 +25,7 @@ import { fileURLToPath } from "node:url";
 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 {
@@ -216,7 +217,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 {

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/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

@@ -42,6 +42,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";
 
@@ -210,7 +211,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;
 }
 

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 {
@@ -133,8 +160,11 @@ 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(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.18.1",
+  "version": "0.19.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",
@@ -128,7 +128,9 @@
     "./check-runner": {
       "types": "./dist/check-runner.d.ts",
       "default": "./dist/check-runner.js"
-    }
+    },
+    "./contracts/ledger/v2/ledger-event.schema.json": "./contracts/ledger/v2/ledger-event.schema.json",
+    "./contracts/ledger/v2/fixtures/*.json": "./contracts/ledger/v2/fixtures/*.json"
   },
   "bin": {
     "pi-daddy": "./dist/cli.js"
@@ -137,6 +139,7 @@
     "dist",
     "extensions",
     "src",
+    "contracts",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -146,8 +149,10 @@
     "typecheck": "tsc -p tsconfig.check.json",
     "test": "node --test test/*.test.ts",
     "test:integration": "node --test test-integration/*.it.ts",
+    "contracts:generate": "node scripts/generate-ledger-v2-contract.ts",
     "prepack": "npm run build",
-    "test:smoke": "node scripts/smoke-installed.mjs"
+    "test:smoke": "node scripts/smoke-installed.mjs",
+    "test:mutation": "node scripts/mutation-audit.mjs"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/approval-prompt.ts

@@ -51,7 +51,8 @@ export interface PromptRequest {
  * breaking) cannot recover that from `scope` or from parsing `reason`. Only "declined" means a human said
  * no; the other three are absence-of-signal, not a signal.
  */
-export type PromptOutcomeKind = "granted" | "no-ui" | "declined" | "dismissed" | "error";
+export const PROMPT_OUTCOME_KINDS = ["granted", "declined", "dismissed", "no-ui", "error"] as const;
+export type PromptOutcomeKind = typeof PROMPT_OUTCOME_KINDS[number];
 
 export interface PromptOutcome {
   /** The scope the human chose, or null for any form of no. */

package/src/approval.ts

@@ -14,10 +14,12 @@ import type { Capability, ResolveResult } from "./resolve.ts";
 import { approvalBindingsEqual, type ApprovalBinding } from "./correlation.ts";
 
 /** How far a single yes reaches in time. */
-export type ApprovalScope = "once" | "session" | "always";
+export const APPROVAL_SCOPES = ["once", "session", "always"] as const;
+export type ApprovalScope = typeof APPROVAL_SCOPES[number];
 
 /** Where a yes came from, for the ledger. These call for different follow-ups, so they stay distinct. */
-export type ApprovalSource = "prompt" | "session" | "persisted" | "inherited";
+export const APPROVAL_SOURCES = ["prompt", "session", "persisted", "inherited"] as const;
+export type ApprovalSource = typeof APPROVAL_SOURCES[number];
 
 /** Which call site is asking. Determines the scopes offered — see `offeredScopes`. */
 export type ApprovalPath = "definition" | "delegate";

package/src/capabilities.ts

@@ -12,7 +12,7 @@
  * *what one delegation does*.
  */
 
-import { AGENT_WILDCARD, type Capability } from "./resolve.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
 import { WILDCARD } from "./pi-tools.ts";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
 
@@ -42,15 +42,61 @@ export function maySpawnDefinition(ownGrant: Capability[], name: string): boolea
 /** The tool name that confers the ability to delegate further. */
 export const DELEGATE_CAPABILITY: Capability = "tool:delegate";
 
+/**
+ * Every namespace a capability id may carry, as its literal prefix.
+ *
+ * **One list, because there were three and adding a namespace only updated some of them.** ADR-0035 taught
+ * `normaliseCapability` about `workspace:` and left `ceilingForDefinition` (which mangled it into
+ * `tool:workspace:<id>`) and `isSafeCapability` (which called it malformed) behind. The two places that parse
+ * an id's namespace read this, so a fifth namespace is one entry rather than a third divergence.
+ *
+ * **Not every prefix decision in the package.** Inline `startsWith("` tests on a capability namespace are
+ * scattered across `src/` and `extensions/`; this list is read by two of them. **No number is written here,
+ * and the history is why:** SPEC first claimed the list was "what every site reads"; a correction said "six"
+ * while its own enumeration listed seven; this docstring then said "nine" in the sentence claiming it gave no
+ * number; and the correction to *that* said "fourteen", which counted every file containing any
+ * `startsWith("` — CLI flags, `git worktree list` parsing, an assurance sentinel and node_modules entries
+ * among them. Four numbers, four wrong. The command, so nobody has to quote a predecessor:
+ *
+ *     grep -rl 'startsWith("\(tool:\|ext:\|agent:\|skill:\|workspace:\)' src extensions
+ *
+ * Consolidating the sites is a separate change, and a count nobody re-derives is the defect this list exists
+ * to prevent.
+ *
+ * `docs/SPEC.md`'s grammar section is the prose statement of the same list and is kept in step with it.
+ */
+export const CAPABILITY_NAMESPACE_PREFIXES = ["tool:", "ext:", "skill:", "agent:", "workspace:"] as const;
+
 /** Accept `read` or `tool:read` or `ext:pkg/tool` and normalise to a capability id. */
 export function normaliseCapability(raw: string): Capability {
   const value = raw.trim();
-  if (value.startsWith("tool:") || value.startsWith("ext:") || value.startsWith("skill:") || value.startsWith("agent:")) {
-    return value;
-  }
+  if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => value.startsWith(prefix))) return value;
   return `tool:${value}`;
 }
 
+/** The capability that authorises routing a child to one registered workspace (ADR-0035). */
+export function workspaceCapability(workspaceId: string): Capability {
+  return `workspace:${workspaceId}`;
+}
+
+/**
+ * May this session route a child to workspace `id`?
+ *
+ * Mirrors `maySpawnDefinition` deliberately — same shape, same wildcard handling, same reason. Routing was
+ * the one governance dimension that did not attenuate (R-131, measured in
+ * `docs/probes/g36-workspace-attenuation`): the registry inherited into every child and nothing checked the
+ * caller's authority, so a child routed to `staging` could route its grandchild to `prod`.
+ *
+ * `tool:*` satisfies it because governance is opt-in — an ungoverned session holds the wildcard and must
+ * keep working exactly as before.
+ */
+export function mayRouteToWorkspace(ownGrant: readonly Capability[], workspaceId: string): boolean {
+  const held = new Set(ownGrant);
+  return held.has(WILDCARD)
+    || held.has(WORKSPACE_WILDCARD)
+    || held.has(workspaceCapability(workspaceId));
+}
+
 /**
  * Characters that make a capability id mean something OTHER than one capability.
  *
@@ -78,6 +124,76 @@ export function isWellFormedCapability(id: string): boolean {
   return id.length > 0 && !CAPABILITY_ID_SEPARATORS.test(id) && id.trim() === id;
 }
 
+/**
+ * The STRICT grammar: a whitelist of what a capability id may look like, not a blocklist of what it may not.
+ *
+ * **Two consumers, and they are two different reasons for the same rule.** It lives here rather than in
+ * either of them because it shipped in one and was needed by both:
+ *
+ *  1. `skill-packages.ts` — the boundary that GENERATES a grant. R-77/R-78: a package declaring
+ *     `allowed-tools: Read,ext:x";touch /tmp/pwned;PI_GRANTS_GRANT="` produced a `.pi/grants.env` that ran
+ *     arbitrary code the moment an operator sourced the line `init` prints.
+ *  2. `workspace.ts` — the operator registry, since ADR-0035 made a registry id the tail of a capability id
+ *     (`workspace:<id>`). That made the registry an input to this grammar, and it got the LOOSE
+ *     `isWellFormedCapability` blocklist instead, which review showed costs three things:
+ *     an id of literally `*` loaded and minted `WORKSPACE_WILDCARD`, so an operator naming ONE worktree held
+ *     routing authority over every id in the registry including ones added later;
+ *     an id containing a space became TWO capabilities, because `ceilingForDefinition` splits `allowed-tools`
+ *     on `[\s,]+` — `allowed-tools: read, workspace:prod bash` measured as
+ *     `['tool:bash','tool:read','workspace:prod']`, i.e. routing over production plus a shell, neither typed
+ *     by anyone (0.18.1's comma, one namespace over);
+ *     and quote/`$()`/backtick ids reached the `ROUTABLE WORKSPACES` block of the generated file, whose own
+ *     instructions tell the operator to paste them into `PI_GRANTS_GRANT`.
+ *
+ * **A blocklist was the wrong shape for this and the comment on `isWellFormedCapability` says why it is the
+ * right shape THERE**: that one guards the enforcement path, which must keep accepting whatever ids operators
+ * already have. A registry is a file the operator writes and can rename, so refusing a hostile id costs
+ * nothing — and `grant-env.ts`'s standing warning applies to it exactly: *"the third channel — whatever it
+ * turns out to be — should cost a refusal rather than an injection."* The registry was the third channel.
+ */
+/**
+ * A workspace registry id, which is NOT a tool name and needed its own rule.
+ *
+ * `isSafeCapability` was reused here first, and that was the error: it is the grammar for a *tool* name, and
+ * it refused ids that published 0.18.1 accepted — `feature/x` above all. Git worktrees are routinely named
+ * after their branch, so a slash is the ordinary case, and a slash splits nothing: not the comma-separated
+ * grant, not `allowed-tools`' `[\s,]+`. Refusing it bought no safety and broke the common setup.
+ *
+ * What is refused, and why each one earns it:
+ *  - **whitespace** — `ceilingForDefinition` splits `allowed-tools` on `[\s,]+`, so `workspace:prod bash`
+ *    measured as `['tool:bash','tool:read','workspace:prod']`: routing over production plus a shell, neither
+ *    typed by anyone. 0.18.1's comma, one namespace over.
+ *  - **comma, CR, LF, NUL** — split a grant.
+ *  - **`*`** — collides with `WORKSPACE_WILDCARD`, so registering a worktree as `*` and granting
+ *    `workspace:*` believing it named that one root minted routing authority over the whole registry.
+ *  - **quotes, `$`, backticks, `;`, `&`, `|`, `<`, `>`, `(`, `)`, `\`, `#`** — reach the ROUTABLE WORKSPACES
+ *    block of a generated `.pi/grants.env`, whose own instructions tell the operator to paste the id into
+ *    `PI_GRANTS_GRANT`. Sourcing the file was safe; following its instructions executed. R-77/R-78.
+ *  - **control characters and non-ASCII** — the generated file is reviewed in an editor and `/grants` prints
+ *    these; backspace and ANSI escapes let one id render as another. This is the one refusal that costs a
+ *    legitimate user something (a non-English worktree name), and it is a deliberate trade recorded as
+ *    breaking rather than asserted to cost nothing.
+ */
+export function isSafeWorkspaceId(id: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(id);
+}
+
+export function isSafeCapability(id: Capability): boolean {
+  const segment = "[A-Za-z0-9][A-Za-z0-9._-]*";
+  // `workspace:` delegates to the WORKSPACE grammar rather than reusing `segment`, and that is the fifth
+  // site of the same defect. `isSafeWorkspaceId` allows a slash because a git worktree is routinely named
+  // after its branch; `segment` does not, so this function refused `workspace:feature/x` — dropping the whole
+  // definition, exiting 1, and telling the operator "a capability id is tool:/skill:/agent:<name> or
+  // ext:<pkg>/<tool>", which does not even mention the namespace. Meanwhile the CHANGELOG told them slashes
+  // are fine. **The boundary that GENERATES grants could not emit the id shape the release advertises**, so
+  // the migration path for a breaking change was closed by the commit that documented it as open.
+  if (id.startsWith("workspace:")) return isSafeWorkspaceId(id.slice("workspace:".length));
+  return (
+    new RegExp(`^(tool|skill|agent):${segment}$`).test(id) ||
+    new RegExp(`^ext:(@${segment}/)?${segment}/${segment}$`).test(id)
+  );
+}
+
 /**
  * The write-side backstop, for every channel that joins capabilities into one string.
  *

package/src/catalog.ts

@@ -23,9 +23,11 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { loadDefinitions, type SkillDefinition } from "./definitions.ts";
 import { PI_BUILTIN_TOOLS, WILDCARD } from "./pi-tools.ts";
-import { AGENT_WILDCARD, type Capability } from "./resolve.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, type Capability } from "./resolve.ts";
+import { loadWorkspaceRegistry, type WorkspaceRegistryFile } from "./workspace.ts";
+import { isSafeWorkspaceId } from "./capabilities.ts";
 
-export type CapabilityKind = "builtin" | "extension" | "skill" | "agentType";
+export type CapabilityKind = "builtin" | "extension" | "skill" | "agentType" | "workspace";
 
 export interface CatalogEntry {
   capability: Capability;
@@ -112,6 +114,22 @@ export function definitionEntries(definitions: Map<string, SkillDefinition>): Ca
   }));
 }
 
+/**
+ * Registered workspaces, as `workspace:<id>` capabilities (ADR-0035).
+ *
+ * For DISPLAY and SCAFFOLDING only — `/grants` listing what this session may route to, and `init` offering
+ * the ids without choosing among them (ADR-0028). It is deliberately **not** what `unknownCapabilities`
+ * checks against; see the comment there.
+ *
+ * The operator registry is the authority on which ids exist, exactly as it is at `resolveWorkspace`. This
+ * enumerates it; it does not decide anything.
+ */
+export function workspaceEntries(registry: WorkspaceRegistryFile, source?: string): CatalogEntry[] {
+  return Object.keys(registry.workspaces)
+    .sort()
+    .map((id) => ({ capability: `workspace:${id}` as Capability, kind: "workspace" as const, ...(source ? { source } : {}) }));
+}
+
 /** Assemble a catalog from parts. Pure, so it is testable without a filesystem. */
 export function makeCatalog(entries: CatalogEntry[]): Catalog {
   const deduped = new Map<Capability, CatalogEntry>();
@@ -131,8 +149,23 @@ export function makeCatalog(entries: CatalogEntry[]): Catalog {
 export async function buildCatalog(input: {
   cwd: string;
   observedTools: string[] | null;
+  /** Operator workspace registry (`PI_GRANTS_WORKSPACE_REGISTRY`). Absent or unreadable yields no entries. */
+  registryPath?: string;
 }): Promise<Catalog> {
-  const [skills, definitions] = await Promise.all([loadSkills(input.cwd), loadDefinitions(input.cwd)]);
+  const [skills, definitions, workspaces] = await Promise.all([
+    loadSkills(input.cwd),
+    loadDefinitions(input.cwd),
+    // Fails SOFT, and only because nothing here is an authority. A malformed registry must not stop a
+    // session from starting — `loadWorkspaceRegistry` throws a GovernanceRefusal naming the file, and that
+    // refusal is the operator's signal at the point of USE, where routing actually depends on it. Swallowing
+    // it there would be unsafe; swallowing it here costs a display list.
+    input.registryPath
+      ? loadWorkspaceRegistry(input.registryPath).then(
+          (r) => workspaceEntries(r, input.registryPath),
+          () => [] as CatalogEntry[],
+        )
+      : Promise.resolve([] as CatalogEntry[]),
+  ]);
   return makeCatalog([
     // pi's built-ins are seeded unconditionally, because they are known statically and the catalog is
     // consulted BEFORE any provider request has happened — `/grants` runs at that point. Without this,
@@ -148,6 +181,7 @@ export async function buildCatalog(input: {
     ...(input.observedTools ? classifyToolNames(input.observedTools) : []),
     ...skills,
     ...definitionEntries(definitions),
+    ...workspaces,
   ]);
 }
 
@@ -165,7 +199,31 @@ export function unknownCapabilities(requested: Capability[], catalog: Catalog):
   // refused it BEFORE `resolve` could apply ADR-0023's rule. That made the ADR's "a parent holding
   // `agent:*` may hand down `agent:*`" false, and made a definition declaring `allowed-tools: agent:*`
   // unspawnable from any grant. The wildcard is live only at the root without this.
-  return requested.filter((c) => c !== WILDCARD && c !== AGENT_WILDCARD && !catalog.has(c)).sort();
+  //
+  // `workspace:` is exempt as a NAMESPACE, not merely at its wildcard, and that asymmetry is deliberate.
+  // ADR-0035 minted the namespace and taught `normaliseCapability`, `resolve` and `childEnv` about it, but
+  // not this line — so with a catalog present (and `delegationContext` always supplies one) every requested
+  // `workspace:<id>` was refused UNKNOWN_TOOL as *"a typo, or an uninstalled package"*. A child could
+  // therefore never be granted a workspace capability at all, which made routing stop dead below the root
+  // instead of attenuating, and made the ADR's own "two authorities, not one" unreachable in production.
+  //
+  // Exempt rather than catalogued-and-checked because the operator registry is the authority and it is
+  // consulted where it matters: `resolveWorkspace` refuses an unregistered id with WORKSPACE_NOT_REGISTERED,
+  // naming the registry. A second, weaker check here can only turn that precise refusal into a misleading
+  // one — and it would do so for reasons that have nothing to do with the id, like a registry this session
+  // cannot read. `buildCatalog` still ENUMERATES workspaces, for `/grants` and for `init`'s scaffold; that
+  // is display, and display is not authority. Same trade-off the built-ins comment above states and accepts.
+  // The workspace exemption requires a WELL-FORMED id, not merely the prefix. A bare `workspace:` names
+  // nothing, and exempting it let it reach a child's grant and the ledger as authority over no workspace at
+  // all — an exemption for ids the registry is authoritative about should not also cover ids no registry
+  // could contain.
+  // `WORKSPACE_WILDCARD` is listed with the other two because it is GRAMMAR, and `isSafeCapability` refuses
+  // wildcards by design — so folding it into the namespace test below un-exempts it. Caught by the tests for
+  // the previous two fixes, which is the checklist paying for itself.
+  const exempt = (c: Capability) =>
+    c === WILDCARD || c === AGENT_WILDCARD || c === WORKSPACE_WILDCARD
+    || (c.startsWith("workspace:") && isSafeWorkspaceId(c.slice("workspace:".length)));
+  return requested.filter((c) => !exempt(c) && !catalog.has(c)).sort();
 }
 
 /**

package/src/check-runner.ts

@@ -5,9 +5,8 @@ import { basename, isAbsolute, join } from "node:path";
 import { normaliseCorrelation, type CorrelationMetadata } from "./correlation.ts";
 import {
   appendLedgerEvent,
+  buildCheckReceiptLedgerEvent,
   buildWorkspaceLeaseEvent,
-  type CheckReceiptLedgerEvent,
-  LEDGER_VERSION,
 } from "./ledger.ts";
 import { computeGitCandidateIdentity } from "./git-identity.ts";
 import { runChild } from "./run-child.ts";
@@ -272,12 +271,13 @@ export async function runNamedCheck(input: {
     };
     const receipt: CheckReceipt = { receipt_id: receiptId(body), ...body };
     if (input.ledgerPath) {
-      const event: CheckReceiptLedgerEvent = {
-        ledgerVersion: LEDGER_VERSION, event: "check_receipt", ts: ended.toISOString(), childId: ownerId,
-        receiptId: receipt.receipt_id, workspaceId: input.workspace.workspaceId, checkId: input.checkId,
-        treeSha: receipt.tree_sha, ...(correlation ? { correlation } : {}),
-      };
-      await appendLedgerEvent({ path: input.ledgerPath, strict: true }, event);
+      await appendLedgerEvent(
+        { path: input.ledgerPath, strict: true },
+        buildCheckReceiptLedgerEvent({
+          childId: ownerId, receiptId: receipt.receipt_id, workspaceId: input.workspace.workspaceId,
+          checkId: input.checkId, treeSha: receipt.tree_sha, correlation, now: ended,
+        }),
+      );
     }
     return { output: result.text, exitCode: result.code, signal: result.signal ?? null, receipt };
   } catch (error) {

package/src/cli.ts

@@ -19,6 +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 { registeredWorkspaceIds } from "./workspace.ts";
 import { discoverSkillPackages, skillPackageRoots, type RefusedSkill, type SkillPackage } from "./skill-packages.ts";
 
 const USAGE = `pi-daddy — capability governance for pi sub-agents
@@ -109,7 +110,7 @@ async function init(cwd: string, force: boolean): Promise<number> {
 
   let plan: InitPlan;
   try {
-    plan = planInit(packages, cwd);
+    plan = planInit(packages, cwd, await registeredWorkspaceIds());
   } catch (error) {
     // R-78's backstop reaching the surface. Nothing is written: a grant that could mean something to a
     // shell is not a grant, and half-scaffolding a project would be worse than scaffolding none of it.
@@ -210,6 +211,28 @@ function report(plan: InitPlan): void {
     );
   }
 
+  // ROUTING, which had no line here at all — and `report()` is the output of the command the docs tell an
+  // operator to run. Keeping `workspace:` ids out of `withheldCapabilities` (so the `/grants init` dialog
+  // could not grant them off a package declaration) removed the ONLY thing this path said about a definition
+  // that cannot be spawned: `needs-withheld` is not one of the cases handled above, so a routing package
+  // produced a copied definition, an unusable grant, and total silence.
+  //
+  // The fix that caused it argued that "a breaking change whose migration is only discoverable by opening a
+  // file is not much of a migration" — and then applied that to the in-session notify and not to the CLI.
+  if (plan.routableWorkspaces.length > 0) {
+    const blocked = plan.skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name);
+    console.log(
+      `\nROUTABLE WORKSPACES: ${plan.routableWorkspaces.join(", ")}.\n` +
+        `Routing a child to one needs its id in PI_GRANTS_GRANT (ADR-0035); without it the delegation is\n` +
+        `refused WORKSPACE_NOT_AUTHORIZED. They are listed COMMENTED in .pi/grants.env and never granted for\n` +
+        `you — which worktree a child starts in is not something a package can declare.` +
+        (blocked.length > 0
+          ? `\nUntil you grant one, these cannot be spawned: ${blocked.join(", ")} — add the capability, then\n` +
+            `their \`agent:\` ids.`
+          : ""),
+    );
+  }
+
   console.log(
     `\nLive grant (${plan.grant.length} capabilities): ${plan.grant.join(", ")}\n\n` +
       `  $EDITOR .pi/grants.env         # review it, then commit it\n` +