pi-daddy 0.19.0 → 0.20.0

package/extensions/grants-command.ts

@@ -60,6 +60,8 @@ export interface GrantsCommandContext {
    * from the caller, visibly.
    */
   runInit: () => Promise<void>;
+  /** Open or reuse the read-only Herdr dashboard; injected so this diagnostic never becomes enforcement. */
+  openDashboard: () => Promise<{ kind: "opened" | "reused"; paneId: string; visibleBesideCaller: boolean }>;
 }
 
 /**
@@ -69,12 +71,12 @@ export interface GrantsCommandContext {
 const PREVIEW_LIMIT = 12;
 
 /** The verbs `/grants` answers to. Anything else is refused rather than silently treated as no verb. */
-const KNOWN_SUBCOMMANDS: readonly string[] = ["init", "ledger", "approvals", "revoke"];
+const KNOWN_SUBCOMMANDS: readonly string[] = ["init", "dashboard", "ledger", "approvals", "revoke"];
 
 export const grantsCommand = {
   description:
     "Show this session's capability grant, delegation depth, and known agent-type ceilings; " +
-    "/grants approvals | /grants ledger | /grants revoke <key>|--all",
+    "/grants dashboard | /grants approvals | /grants ledger | /grants revoke <key>|--all",
 handler: async (args: string, ctx: any) => {
     // Everything this command may see, named in one place. Previously these were whatever happened to be in
     // the enclosing closure — which is how a diagnostic came to disagree with the enforcer (R-28).
@@ -90,6 +92,20 @@ handler: async (args: string, ctx: any) => {
       return;
     }
 
+    if (sub === "dashboard") {
+      try {
+        const opened = await ctx.grants.openDashboard();
+        ctx.ui.notify(
+          `grants: dashboard ${opened.kind} in Herdr pane ${opened.paneId} without changing focus` +
+            (opened.visibleBesideCaller ? "." : " (the existing pane is in another tab)."),
+          "info",
+        );
+      } catch (error) {
+        ctx.ui.notify(`grants: dashboard unavailable — ${error instanceof Error ? error.message : String(error)}`, "error");
+      }
+      return;
+    }
+
     if (sub === "ledger") {
       // The detector, made reachable. `verifyLedger` exists because nothing in this package had ever read
       // a ledger back, so a torn line was indistinguishable from a spawn that never happened — and a
@@ -109,7 +125,7 @@ handler: async (args: string, ctx: any) => {
         `  escalation ${report.escalationAttempts} attempt(s) — grants refused for exceeding what the session held`,
         `  integrity  ${report.ok ? "OK" : `${report.corrupt.length} UNPARSEABLE LINE(S)`}`,
       ];
-      for (const bad of report.corrupt.slice(0, 5)) lines.push(`    line ${bad.line}: ${bad.text}`);
+      for (const bad of report.corrupt.slice(0, 5)) lines.push(`    line ${bad.line}: ${bad.reason}`);
       // ADR-0031, and R-51's lesson applied on the day the field was added rather than a release later: a field
       // the writer sets and no diagnostic reads is one that needs `jq`, and `docs/SPEC.md` claims the executor is
       // announced "per child in the ledger". `unknown` is shown only when present, because on a fresh ledger it
@@ -121,6 +137,9 @@ handler: async (args: string, ctx: any) => {
             ? ` · ${report.executors.unknown} not recorded (written before 0.16.0, which added the field)`
             : ""),
       );
+      if (report.workflowFacts > 0) {
+        lines.push(`  workflow   ${report.workflowFacts} provenance-labelled fact(s) — not counted as enforced children`);
+      }
       // R-51. ADR-0018 advertises that the ledger answers "did these four children run the same
       // instructions?" and "has this definition changed since?" — and nothing read `definitionDigest`, so
       // both needed hand-written jq and the second was not reproducible with `sha256sum` (the digest covers

package/extensions/grants.ts

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

package/extensions/run-delegation.ts

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

package/extensions/session.ts

@@ -31,6 +31,7 @@ import {
   gatedFromEnv,
   ENV_APPROVED,
   ENV_DEPTH,
+  ENV_EXECUTION_ID,
   ENV_FANOUT,
   ENV_GATED,
   ENV_GRANT,
@@ -95,7 +96,8 @@ export interface GrantsSession {
   /** Bound variables that could not be read as non-negative integers — spawning is disabled, loudly. */
   readonly malformedBounds: string[];
   readonly gated: Capability[];
-  readonly ledgerPath?: string;
+  /** Resolved against the actual pi cwd at session start, then inherited verbatim by every descendant. */
+  ledgerPath?: string;
   /**
    * Which executor runs this session's children — ADR-0031.
    *
@@ -108,8 +110,10 @@ export interface GrantsSession {
    * before the probe, which is the same hazard as capturing `ownGrant` before the tool surface is observed.
    */
   executor: ExecutorChoice;
-  /** This session's ledger identity; children descend from it (F8). */
+  /** This session's readable logical ledger identity; children descend from it (F8). */
   readonly ownSpawnId: string;
+  /** Unique identity when this session is itself a governed child; roots have no governed parent. */
+  readonly ownExecutionId?: string;
   /** Descendants this subtree may still create — the cardinality bound ADR-0008 never had. */
   readonly fanoutBudget: number;
   /** Whether `delegate` / `delegate_all` are registered at all (S-5). Decided on the INHERITED grant. */
@@ -284,6 +288,7 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
     // `ownSpawnId` comes from the parent (F8), so ids form one tree across process boundaries instead of
     // every level restarting at `d0` and the ledger becoming unjoinable.
     ownSpawnId: process.env[ENV_PARENT_ID]?.trim() || `d${depth}`,
+    ownExecutionId: process.env[ENV_EXECUTION_ID]?.trim() || undefined,
     // The cardinality bound ADR-0008 never had: it attenuates downward like depth, so a subtree can never
     // create more descendants than its root was given — with no shared state, no lock and no counter file.
     fanoutBudget: budgetFromEnv(process.env[ENV_FANOUT]),

package/extensions/workspace-runtime.ts

@@ -69,6 +69,8 @@ export async function prepareDelegationWorkspace(input: {
   spec: DelegationWorkspaceSpec;
   correlation?: CorrelationMetadata;
   childId: string;
+  executionId: string;
+  parentExecutionId: string | null;
   signal?: AbortSignal;
   ledgerPath?: string;
 }): Promise<PreparedWorkspace> {
@@ -102,6 +104,8 @@ export async function prepareDelegationWorkspace(input: {
       await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          executionId: input.executionId,
+          parentExecutionId: input.parentExecutionId,
           childId: input.childId,
           workspaceId: workspace.workspaceId,
           root: workspace.root,
@@ -125,6 +129,8 @@ export async function prepareDelegationWorkspace(input: {
       await appendLedgerEvent(
         { path: input.ledgerPath, strict: true },
         buildWorkspaceLeaseEvent({
+          executionId: input.executionId,
+          parentExecutionId: input.parentExecutionId,
           childId: input.childId,
           workspaceId: workspace.workspaceId,
           root: workspace.root,
@@ -151,6 +157,8 @@ export async function prepareDelegationWorkspace(input: {
 export async function releaseDelegationWorkspace(input: {
   prepared: PreparedWorkspace | undefined;
   childId: string;
+  executionId: string;
+  parentExecutionId: string | null;
   ledgerPath?: string;
   reason: string;
   /** Deliberately keep the lease: a herdr writer tab would not close, so the pane may still be live. */
@@ -170,6 +178,8 @@ export async function releaseDelegationWorkspace(input: {
     await appendLedgerEvent(
       { path: input.ledgerPath, strict: true },
       buildWorkspaceLeaseEvent({
+        executionId: input.executionId,
+        parentExecutionId: input.parentExecutionId,
         childId: input.childId,
         workspaceId: input.prepared.workspace.workspaceId,
         root: input.prepared.workspace.root,

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.19.0",
+  "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",
@@ -129,27 +129,39 @@
       "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-v2-contract.ts",
+    "contracts:generate": "node scripts/generate-ledger-v3-contract.ts",
     "prepack": "npm run build",
     "test:smoke": "node scripts/smoke-installed.mjs",
     "test:mutation": "node scripts/mutation-audit.mjs"

package/src/check-runner.ts

@@ -19,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. */
@@ -85,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 },
@@ -147,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;
@@ -163,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(),
@@ -178,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(),
@@ -256,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(),
       }),
@@ -274,6 +287,7 @@ export async function runNamedCheck(input: {
       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,
         }),
@@ -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/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;