pi-daddy 0.18.0 → 0.19.0

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

package/src/definitions.ts

@@ -23,6 +23,7 @@ import { createHash } from "node:crypto";
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 import { skillDirs } from "./catalog.ts";
+import { CAPABILITY_NAMESPACE_PREFIXES } from "./capabilities.ts";
 import type { Capability } from "./resolve.ts";
 
 /**
@@ -182,7 +183,12 @@ export function ceilingForDefinition(definition: SkillDefinition): DefinitionCei
       patterns.push(entry);
       continue;
     }
-    if (entry.startsWith("ext:") || entry.startsWith("skill:") || entry.startsWith("agent:")) {
+    // Every namespaced id passes through untouched; only a BARE tool name gets the `tool:` prefix and the
+    // lowercasing. `workspace:` was missing here after ADR-0035 taught `normaliseCapability` about it, so a
+    // definition declaring `allowed-tools: workspace:prod` produced `tool:workspace:prod` — a capability
+    // that names nothing, refused as unknown, and dropped by `init` as "probably a typo or an attack". Two
+    // spellings of one grammar with this one wrong is R-28's shape; the list is now shared.
+    if (CAPABILITY_NAMESPACE_PREFIXES.some((prefix) => entry.startsWith(prefix))) {
       capabilities.add(entry);
       continue;
     }

package/src/delegate.ts

@@ -6,13 +6,22 @@
 import { planSpawn } from "./spawn.ts";
 import { ceilingForDefinition, digestDefinition, type DefinitionDigest, type SkillDefinition } from "./definitions.ts";
 import { assertNarrowing, type Capability, type ResolveResult } from "./resolve.ts";
-import { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
+import { checkRoutingAuthority, checkWorkspaceWildcardRequest } from "./routing-authority.ts";
+import {
+  DELEGATE_CAPABILITY,
+  agentCapability,
+  maySpawnDefinition,
+  normaliseCapability,
+} from "./capabilities.ts";
 
 // Re-exported so the split stays internal: `delegate.ts` has been the import site for these since 0.6.0 and
 // four modules plus the test suite name it. Moving the definitions without moving the door would be churn
 // charged to every caller for a line count they did not cause.
 export { DELEGATE_CAPABILITY, agentCapability, maySpawnDefinition, normaliseCapability } from "./capabilities.ts";
-import { ENV_APPROVED, ENV_DEPTH, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH, ENV_PARENT_ID } from "./propagation.ts";
+import {
+  ENV_APPROVED, ENV_DEPTH, ENV_FANOUT, ENV_GATED, ENV_GRANT, ENV_LEDGER, ENV_MAX_DEPTH, ENV_PARENT_ID,
+  inheritableGrant,
+} from "./propagation.ts";
 import { inheritApprovals, type InheritableApproval } from "./approval.ts";
 import { suggestForUnknown, unknownCapabilities, type Catalog } from "./catalog.ts";
 import { GovernanceRefusal, refusal, type RefusalCode, type StructuredRefusal } from "./refusals.ts";
@@ -24,6 +33,7 @@ import {
 } from "./correlation.ts";
 import { resolveDelegationApproval } from "./delegation-approval.ts";
 import type { Delegation, DelegationContext, DelegationRequest } from "./delegate-types.ts";
+import { assertCapabilitiesArePropagatable } from "./capabilities.ts";
 export type { Delegation, DelegationContext, DelegationRequest } from "./delegate-types.ts";
 
 export function planDelegation(request: DelegationRequest, ctx: DelegationContext): Delegation {
@@ -71,6 +81,17 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   }
   if (!request.task?.trim()) return denied({ ...empty, reason: "a delegation needs a task" }, "TASK_MISSING");
 
+  // ADR-0035's routing guards live in `routing-authority.ts` with their rationale; both are checked here,
+  // before anything is said about the target, because they are governance questions about the SESSION.
+  const routing = checkRoutingAuthority(request.boundWorkspaceId, ctx.ownGrant);
+  if (routing) {
+    return denied({
+      ...empty,
+      ...(routing.denied ? { requested: routing.denied, result: { ...empty.result, denied: routing.denied } } : {}),
+      reason: routing.reason,
+    }, routing.code);
+  }
+
   // ADR-0016. A named definition replaces the model's tool list with an operator-authored ceiling.
   let requested: Capability[];
   let systemPrompt: string | undefined;
@@ -180,6 +201,13 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     }
   }
 
+  // See `checkWorkspaceWildcardRequest`: refused for a HOLDER (the ledger must not record authority the
+  // child will not receive), and left to `resolve()` for anyone else, so the probe lands in `denied`.
+  const wildcardRequest = checkWorkspaceWildcardRequest(requested, ctx.ownGrant);
+  if (wildcardRequest) {
+    return denied({ ...empty, requested, reason: wildcardRequest.reason }, wildcardRequest.code);
+  }
+
   const { result, approvalBinding, bindingMismatch } = resolveDelegationApproval({
     task: request.task,
     agent: request.agent,
@@ -265,8 +293,14 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
     args.splice(args.length - 1, 0, "-e", ctx.extensionPath);
   }
 
+  // `inheritableGrant`, not `result.effective` directly: this is the path a DELEGATED child's grant
+  // actually travels, and the "held but never inherited" rule for `tool:*` and `workspace:*` was enforced
+  // only in `childEnv`. A parent holding `workspace:*` could request it for its child and this line handed
+  // it over, so the rule ADR-0035 advertises held by accident — masked downstream rather than enforced
+  // here. One spelling of the rule, called from both paths.
+  const inheritable = inheritableGrant(result.effective);
   const env: Record<string, string> = {
-    [ENV_GRANT]: result.effective.join(","),
+    [ENV_GRANT]: (assertCapabilitiesArePropagatable(inheritable), inheritable.join(",")),
     [ENV_DEPTH]: String(childDepth),
     [ENV_MAX_DEPTH]: String(ctx.maxDepth),
   };
@@ -280,7 +314,11 @@ export function planDelegation(request: DelegationRequest, ctx: DelegationContex
   // `approved ⊆ grant` holds at every level (ADR-0010). Written even when empty, so this object states
   // the child's approval set outright rather than leaving it to whatever the caller merges over; see
   // `mergeChildEnv`, which is what actually stops the parent's value leaking through.
-  env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], result.effective).join(",");
+  // Clamped to what the child actually INHERITS, not to what it was granted. The two differ only for a
+  // non-inheritable wildcard, and passing down an approval for a capability the child does not hold would
+  // leave banked authority with nothing to spend it on — `childEnv` clamps to `inheritable` for the same
+  // reason on the other path.
+  env[ENV_APPROVED] = inheritApprovals(ctx.approved ?? [], inheritable).join(",");
   if (ctx.ledgerPath) env[ENV_LEDGER] = ctx.ledgerPath;
 
   return {

package/src/delegation-approval.ts

@@ -1,5 +1,5 @@
 import { DELEGATE_SUBJECT, type InheritableApproval } from "./approval.ts";
-import { agentCapability } from "./capabilities.ts";
+import { agentCapability, workspaceCapability } from "./capabilities.ts";
 import {
   approvalBindingsEqual,
   buildApprovalBinding,
@@ -7,7 +7,7 @@ import {
   type CorrelationMetadata,
 } from "./correlation.ts";
 import type { DefinitionDigest, SkillDefinition } from "./definitions.ts";
-import { AGENT_WILDCARD, resolve, type Capability, type ResolveResult } from "./resolve.ts";
+import { AGENT_WILDCARD, WORKSPACE_WILDCARD, resolve, type Capability, type ResolveResult } from "./resolve.ts";
 
 /**
  * Resolve the approval half of one delegation after its requested capability set is known.
@@ -44,15 +44,32 @@ export function resolveDelegationApproval(input: {
     approved: [],
   });
 
-  // ADR-0024: a definition's authorising id is gated as the PARENT's authority to run it now. It never
-  // joins requested/effective, because that would hand the child authority to recursively spawn itself.
-  let authorisingCapability: Capability | undefined;
-  if (input.spawned) {
-    const authorising = agentCapability(input.spawned.name);
-    if (input.gated.includes(authorising) || input.gated.includes(AGENT_WILDCARD)) {
-      authorisingCapability = authorising;
+  /**
+   * Authorities the PARENT is spending on this one delegation, gated as such.
+   *
+   * ADR-0024 established the shape for `agent:<name>`: the id is gated as the parent's authority to run
+   * that definition *now*, and never joins requested/effective, because that would hand the child authority
+   * to recursively spawn itself. ADR-0035 added a second member of the category — `workspace:<id>`, the
+   * authority to route this child somewhere — and shipped without it, so `PI_GRANTS_GATED=workspace:prod`
+   * was accepted, recorded, and silently inert: no human was ever asked. The ADR claimed the opposite in
+   * three places.
+   *
+   * A LIST rather than two variables on purpose. This is the third namespace whose authorising id is gated
+   * per-delegation rather than granted downward, and the first two were written as one special case each;
+   * a fourth should extend an array, not add a third `if` and a third field to thread through.
+   */
+  const authorisingCapabilities: Capability[] = [];
+  const gateAuthority = (authorising: Capability, wildcard: Capability) => {
+    if (input.gated.includes(authorising) || input.gated.includes(wildcard)) {
+      authorisingCapabilities.push(authorising);
       unapproved.gatedBlocked = [...unapproved.gatedBlocked, authorising];
     }
+  };
+  if (input.spawned) gateAuthority(agentCapability(input.spawned.name), AGENT_WILDCARD);
+  // Trusted: `boundWorkspaceId` is set only from a routing spec resolved against the operator registry,
+  // never from a model-supplied `correlation` claim (R-110).
+  if (input.boundWorkspaceId) {
+    gateAuthority(workspaceCapability(input.boundWorkspaceId), WORKSPACE_WILDCARD);
   }
 
   const potential = resolve({
@@ -92,8 +109,16 @@ export function resolveDelegationApproval(input: {
     gated: input.gated,
     approved: approvedCapabilities,
   });
-  if (authorisingCapability && !approvedCapabilities.includes(authorisingCapability)) {
-    result.gatedBlocked = [...result.gatedBlocked, authorisingCapability];
-  }
+  // Filtered against what `resolve()` already listed, not just against approvals. In the ORDINARY chained
+  // configuration — route the child to `prod` AND grant it `workspace:prod` so it can route onward — the
+  // authorising id and the requested id are spelled identically, so appending unconditionally produced
+  // `gatedBlocked: ["workspace:prod","workspace:prod"]`, which reached the refusal text a model reads
+  // (*"workspace:prod, workspace:prod requires explicit approval"*) and the append-only ledger, whose schema
+  // has no `uniqueItems`. The old `agent:`-only code had the same shape and never hit it, because a
+  // self-recursive `agent:X` ceiling is not a thing anybody writes.
+  const stillGated = authorisingCapabilities.filter(
+    (c) => !approvedCapabilities.includes(c) && !result.gatedBlocked.includes(c),
+  );
+  if (stillGated.length > 0) result.gatedBlocked = [...result.gatedBlocked, ...stillGated];
   return { result, ...(approvalBinding ? { approvalBinding } : {}), bindingMismatch };
 }

package/src/executor.ts

@@ -18,7 +18,8 @@ import type { HerdrProbe } from "./herdr-cli.ts";
 
 export const ENV_HERDR = "PI_GRANTS_HERDR";
 
-export type ExecutorKind = "herdr" | "process";
+export const EXECUTOR_KINDS = ["process", "herdr"] as const;
+export type ExecutorKind = typeof EXECUTOR_KINDS[number];
 
 export interface ExecutorChoice {
   kind: ExecutorKind;

package/src/grant-env.ts

@@ -42,6 +42,12 @@ export const WITHHELD_BY_DEFAULT: readonly Capability[] = [
 
 /** Would `init` put this capability in the live grant? */
 export function isLiveByDefault(capability: Capability): boolean {
+  // No `workspace:<id>` is ever live by default (ADR-0035), and this is the same rule the list above states
+  // rather than a new one: authority "does not become live because a package asked for it". A registry id is
+  // a *choice of where a child runs*, which is the operator's to make and cannot be inferred from a
+  // declaration — ADR-0028's whole position. Enumerated ids are unbounded, so this is a namespace test and
+  // not a list membership.
+  if (capability.startsWith("workspace:")) return false;
   return !WITHHELD_BY_DEFAULT.includes(capability);
 }
 
@@ -87,6 +93,8 @@ export interface GrantEnvInput {
   withheld: Map<Capability, string[]>;
   /** Definitions whose `agent:` id is withheld because they need a withheld capability. */
   withheldDefinitions: string[];
+  /** `workspace:<id>` ids this project could route to (ADR-0035). Rendered commented, never granted. */
+  routableWorkspaces?: Capability[];
   /** `agent:<name>` ids a ceiling names that `init` did not write here. Reported, never granted. */
   crossReferences: { from: string; capability: Capability }[];
   cautions: string[];
@@ -140,13 +148,37 @@ export function renderGrantEnv(input: GrantEnvInput): string {
     for (const [capability, needed] of [...input.withheld].sort()) {
       lines.push(`#   ${capability.padEnd(width)}  (${needed.join(", ")})`);
     }
-    if (input.withheldDefinitions.length > 0) {
-      lines.push(
-        `#   …and then: ${input.withheldDefinitions.map((n) => `agent:${n}`).join(",")}`,
-        "#   Their `agent:` ids are withheld too: a definition that cannot receive what it declares would",
-        "#   be authorised to run and then refused, which is a worse answer than not being authorised.",
-      );
-    }
+    lines.push("#");
+  }
+
+  // OUTSIDE the block above, and that is the fix. This is the file's only statement that a withheld
+  // definition's `agent:` id must be granted too — and it used to render only when `withheld` was non-empty,
+  // so a package whose sole withheld capability is a ROUTING id (the common read-only routing case) lost it
+  // entirely once `workspace:` ids stopped going into that map. The reason line above still said "see below"
+  // and pointed at nothing.
+  if (input.withheldDefinitions.length > 0) {
+    lines.push(
+      `#   …and then: ${input.withheldDefinitions.map((n) => `agent:${n}`).join(",")}`,
+      "#   Their `agent:` ids are withheld too: a definition that cannot receive what it declares would",
+      "#   be authorised to run and then refused, which is a worse answer than not being authorised.",
+      "#",
+    );
+  }
+
+  // ADR-0035. Routing became a capability in 0.19.0, which made every existing grant that routes start
+  // refusing — so the migration has to be visible from the file the operator already opens. Listed and NOT
+  // granted: which worktree a child starts in is the operator's decision and cannot be read off a
+  // declaration (ADR-0028), and granting one because a package named it is the "does not become live because
+  // a package asked for it" rule that `WITHHELD_BY_DEFAULT` above states.
+  if (input.routableWorkspaces && input.routableWorkspaces.length > 0) {
+    lines.push(
+      "# ROUTABLE WORKSPACES — routing a child to a registered worktree needs the id in PI_GRANTS_GRANT",
+      "# (ADR-0035, 0.19.0). Without it a delegation naming one is refused WORKSPACE_NOT_AUTHORIZED. Add the",
+      "# ones this project's children may start in; a child can only pass on ids it holds itself, so this is",
+      "# also the list of what any DESCENDANT could reach. Not granted for you: `workspace:*` exists but is",
+      "# held and never inherited, which makes it the wrong answer for anything but a single-worktree setup.",
+    );
+    for (const capability of input.routableWorkspaces) lines.push(`#   ${capability}`);
     lines.push("#");
   }
 

package/src/index.ts

@@ -11,6 +11,7 @@ export {
 export {
   appendLedgerEvent,
   appendRecord,
+  buildCheckReceiptLedgerEvent,
   buildChildLifecycleEvent,
   buildRecord,
   buildWorkspaceLeaseEvent,

package/src/init.ts

@@ -24,7 +24,7 @@
 
 import { mkdir, open, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { agentCapability } from "./capabilities.ts";
+import { agentCapability, workspaceCapability } from "./capabilities.ts";
 import { ceilingForDefinition } from "./definitions.ts";
 import { ALWAYS_LIVE, assertGrantIsWritable, isLiveByDefault, renderGrantEnv, type GrantEnvSkill } from "./grant-env.ts";
 import { PI_BUILTIN_TOOLS } from "./pi-tools.ts";
@@ -78,6 +78,8 @@ export interface InitPlan {
   grant: Capability[];
   /** Withheld capability → the definitions that declared it (ADR-0029). Emitted commented. */
   withheldCapabilities: Map<Capability, string[]>;
+  /** `workspace:<id>` this project could route to (ADR-0035). Always commented — `init` does not choose. */
+  routableWorkspaces: Capability[];
   grantEnvPath: string;
   grantEnvContent: string;
   /** Capabilities a declared ceiling names that pi 0.84.1 has no tool for — a caution, not a verdict. */
@@ -143,7 +145,20 @@ function unknownToolIds(capabilities: Capability[]): Capability[] {
  * tools at all and the whole file is inert. Everything else is emitted commented, named, and one uncomment
  * away (ADR-0029).
  */
-export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
+export function planInit(
+  packages: SkillPackage[],
+  cwd: string,
+  /**
+   * Ids from the operator's workspace registry, when one is configured — read by the CALLER, because
+   * `planInit` is pure and stays that way.
+   *
+   * ADR-0035 made routing a capability and said `init` "scaffolds the registered ids so the common path is a
+   * one-line grant edit". It did not: `init` had never heard of the registry, so the ADR's own stated
+   * migration path for a breaking change did not exist. These are emitted **commented**, never live —
+   * offering the ids while refusing to choose among them is exactly ADR-0028's position.
+   */
+  registeredWorkspaceIds: readonly string[] = [],
+): InitPlan {
   const skills: PlannedSkill[] = [];
   const collisions: string[] = [];
   const seen = new Set<string>();
@@ -190,6 +205,20 @@ export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
   for (const skill of declared) {
     for (const capability of skill.ceiling) {
       if (isLiveByDefault(capability)) continue;
+      // A routing destination is withheld but does NOT belong in this map, and the difference is not
+      // cosmetic. This map drives two things: the "WITHHELD BY DEFAULT — these can change your machine"
+      // block, and `/grants init`'s dialog. Review found a `workspace:` id reaching both — described to the
+      // operator with `tool:bash`'s rationale (routing does not change your machine, and unlike `bash` it
+      // *is* gateable), and then granted **live and persisted** on one "Yes", off a third-party package's
+      // declaration. That is the rule `grant-env.ts` states — "does not become live because a package asked
+      // for it" — honoured by the rendered file and broken by the dialog beside it: two surfaces of one
+      // command disagreeing, which is R-28's shape inside the fix for R-28.
+      //
+      // Which worktree a child starts in is not derivable from a declaration (ADR-0028), so `init` lists
+      // routing and never grants it. `routableWorkspaces` below is where these go; the definition that
+      // declared one still loses its live `agent:` id via the `needs-withheld` pass, so nothing becomes
+      // spawnable behind the operator's back either.
+      if (capability.startsWith("workspace:")) continue;
       withheldCapabilities.set(capability, [...(withheldCapabilities.get(capability) ?? []), skill.name]);
     }
   }
@@ -246,11 +275,19 @@ export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
     ...(s.withheld ? { unspawnable: describe[s.withheld](s) } : {}),
   }));
 
+  // Registry ids the operator could route to, plus any a copied definition actually declares — a package
+  // naming `workspace:prod` is evidence that id matters here, and it must still be uncommented by hand.
+  const declaredWorkspaces = skills.flatMap((s) => s.ceiling.filter((c) => c.startsWith("workspace:")));
+  const routableWorkspaces = [
+    ...new Set([...registeredWorkspaceIds.map(workspaceCapability), ...declaredWorkspaces]),
+  ].sort();
+
   return {
     skills,
     collisions,
     grant,
     withheldCapabilities,
+    routableWorkspaces,
     grantEnvPath: join(cwd, ".pi", "grants.env"),
     grantEnvContent: renderGrantEnv({
       skills: grantEnvSkills,
@@ -259,6 +296,7 @@ export function planInit(packages: SkillPackage[], cwd: string): InitPlan {
       withheldDefinitions: skills.filter((s) => s.withheld === "needs-withheld").map((s) => s.name),
       crossReferences,
       cautions,
+      routableWorkspaces,
     }),
     cautions,
   };