pi-daddy 0.18.1 → 0.20.0

package/herdr-plugin/herdr-plugin.toml

@@ -0,0 +1,18 @@
+id = "pi-daddy.dashboard"
+name = "pi-daddy dashboard"
+version = "1.0.0"
+min_herdr_version = "0.8.0"
+description = "Read-only live projection of a pi-daddy governance ledger"
+platforms = ["linux", "macos", "windows"]
+
+[[panes]]
+id = "dashboard"
+title = "PI-DADDY"
+description = "Live governed execution and refusal tree"
+placement = "split"
+command = [
+  "node",
+  "--input-type=module",
+  "-e",
+  "import('node:url').then(({ pathToFileURL }) => import(pathToFileURL(process.env.HERDR_PLUGIN_ROOT + '/../dist/dashboard-cli.js').href)).then(m => m.runDashboard()).catch(e => { console.error(e); process.exitCode = 1; })"
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.18.1",
+  "version": "0.20.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,26 +128,43 @@
     "./check-runner": {
       "types": "./dist/check-runner.d.ts",
       "default": "./dist/check-runner.js"
-    }
+    },
+    "./dashboard-projection": {
+      "types": "./dist/dashboard-projection.d.ts",
+      "default": "./dist/dashboard-projection.js"
+    },
+    "./dashboard-render": {
+      "types": "./dist/dashboard-render.d.ts",
+      "default": "./dist/dashboard-render.js"
+    },
+    "./contracts/ledger/v3/ledger-event.schema.json": "./contracts/ledger/v3/ledger-event.schema.json",
+    "./contracts/ledger/v3/fixtures/*.json": "./contracts/ledger/v3/fixtures/*.json",
+    "./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"
+    "pi-daddy": "./dist/cli.js",
+    "pi-daddy-dashboard": "./dist/dashboard-cli.js"
   },
   "files": [
     "dist",
     "extensions",
     "src",
+    "contracts",
+    "herdr-plugin",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
     "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-v3-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";
@@ -20,6 +19,8 @@ import {
   leaseAcquisitionOutcome,
   leaseReleaseLedgerOutcome,
 } from "./workspace.ts";
+import { newExecutionId } from "./execution-id.ts";
+import { isLedgerDisplayIdentifier } from "./ledger-identifiers.ts";
 
 export interface CheckDefinition {
   /** Absolute operator-owned executable. PATH lookup is deliberately not part of the contract. */
@@ -86,6 +87,12 @@ export function buildCheckEnvironment(
 }
 
 function validateDefinition(checkId: string, value: CheckDefinition | undefined): CheckDefinition {
+  // `check:<id>:<uuid>` is also the v3 childId, whose closed display-identifier bound is 512 characters.
+  if (!isLedgerDisplayIdentifier(checkId) || checkId.length > 460) {
+    throw new GovernanceRefusal(refusal(
+      "CHECK_CONFIGURATION_INVALID", `check ${JSON.stringify(checkId)} must be an ASCII identifier`, { check_id: checkId },
+    ));
+  }
   if (!value) {
     throw new GovernanceRefusal(refusal(
       "CHECK_NOT_CONFIGURED", `check ${JSON.stringify(checkId)} is not present in operator-owned configuration`, { check_id: checkId },
@@ -148,6 +155,8 @@ export async function runNamedCheck(input: {
   // governed writer. `access` still records what the configured executable is intended to do.
   const leaseAccess: WorkspaceAccess = "write";
   const ownerId = `check:${input.checkId}:${randomUUID()}`;
+  const executionId = newExecutionId();
+  const parentExecutionId = null;
   const correlation = normaliseCorrelation(input.correlation);
   let lease: Awaited<ReturnType<typeof acquireWorkspaceLease>> | undefined;
   let stagedDir: string | undefined;
@@ -164,6 +173,7 @@ export async function runNamedCheck(input: {
       if (input.ledgerPath) await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          executionId, parentExecutionId,
           childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
           outcome: "refused",
           correlation, now: new Date(),
@@ -179,6 +189,7 @@ export async function runNamedCheck(input: {
         await appendLedgerEvent(
           { path: input.ledgerPath, strict: true },
           buildWorkspaceLeaseEvent({
+            executionId, parentExecutionId,
             childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
             outcome: leaseAcquisitionOutcome(leaseAccess, lease.recovered), recovered: lease.recovered,
             correlation, now: new Date(),
@@ -257,6 +268,7 @@ export async function runNamedCheck(input: {
     if (input.ledgerPath) await appendLedgerEvent(
       { path: input.ledgerPath, strict: true },
       buildWorkspaceLeaseEvent({
+        executionId, parentExecutionId,
         childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
         outcome: leaseReleaseLedgerOutcome(releaseOutcome, releaseReason), releaseReason, correlation, now: new Date(),
       }),
@@ -272,12 +284,14 @@ 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({
+          executionId, parentExecutionId,
+          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) {
@@ -304,6 +318,7 @@ export async function runNamedCheck(input: {
           onFailure: (cause) => { notes.push(`check refusal record failed: ${String(cause)}`); },
         },
         buildWorkspaceLeaseEvent({
+          executionId, parentExecutionId,
           childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
           outcome: "refused",
           refusal: error instanceof GovernanceRefusal
@@ -327,6 +342,7 @@ export async function runNamedCheck(input: {
           onFailure: (cause) => { notes.push(`check lease release record failed: ${String(cause)}`); },
         },
         buildWorkspaceLeaseEvent({
+          executionId, parentExecutionId,
           childId: ownerId, workspaceId: input.workspace.workspaceId, root: input.workspace.root, access: leaseAccess,
           outcome: outcome === "lost"
             ? "lost"

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/correlation.ts

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import type { DefinitionDigest } from "./definitions.ts";
 import type { Capability } from "./resolve.ts";
 import { GovernanceRefusal, refusal } from "./refusals.ts";
+import { isLedgerCorrelationIdentifier } from "./ledger-identifiers.ts";
 
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue = JsonPrimitive | JsonValue[] | { [key: string]: JsonValue };
@@ -71,6 +72,13 @@ const CORRELATION_NUMERIC = new Set<keyof CorrelationMetadata>([
   "event_seq", "last_change_seq", "last_authority_seq",
 ]);
 
+// These fields are rendered as labels/identities. Treating arbitrary prose as an "id" let a model copy
+// task or output text into the ledger and dashboard through correlation while staying schema-valid.
+const CORRELATION_IDENTIFIERS = new Set<keyof CorrelationMetadata>([
+  "schema_version", "run_id", "task_id", "workspace_id", "context_id", "phase", "assurance",
+  "assurance_effective", "policy_label", "assurance_source",
+]);
+
 function correlationRefusal(message: string, details?: Record<string, string | number>): GovernanceRefusal {
   return new GovernanceRefusal(refusal("CORRELATION_INVALID", `correlation metadata: ${message}`, details));
 }
@@ -147,6 +155,9 @@ export function normaliseCorrelation(input: CorrelationMetadata | undefined): Co
         { field: key, limit: MAX_CORRELATION_FIELD_CHARS, actual: value.length },
       );
     }
+    if (CORRELATION_IDENTIFIERS.has(key as keyof CorrelationMetadata) && !isLedgerCorrelationIdentifier(value)) {
+      throw correlationRefusal(`${key} must be an ASCII identifier, not free-form text`, { field: key });
+    }
     output[key] = value;
   }
   return output as CorrelationMetadata;