pi-daddy 0.18.1 → 0.20.0

package/CHANGELOG.md

@@ -12,6 +12,207 @@ the record of how the package got here and are worth keeping; they are not worth
 > the record of how the package arrived at what it does, and because the reasoning behind each one is
 > usually the clearest statement of why the current behaviour is what it is.
 
+## 0.20.0 — live governance dashboard and ledger v3 (2026-08-31)
+
+- Ship a Herdr 0.8+ plugin inside the trusted pi-daddy package. A Herdr-hosted pi asks once before linking it;
+  **Install and open** is the only choice that installs anything. **Not now** and **Never ask** are persisted.
+- Add `/grants dashboard`: verify this exact pi PID is in its declared Herdr pane, require a configured ledger,
+  diagnose missing/disabled/incompatible plugin state, then open or reuse a right split with `--no-focus`.
+- Add a pure `ledger -> projection -> terminal renderer` path. Active ancestry stays visible, old completed
+  subtrees collapse, durations and Herdr pane identity render live, and corrupt lines are reported without
+  showing raw content or modifying the file.
+- **BREAKING — production events now use the closed ledger v3 contract.** Every governed occurrence has a
+  globally unique `executionId` and explicit `parentExecutionId`; readable `childId` remains and may repeat.
+  Lifecycle/lease joins by `childId` are invalid. Frozen v2 and legacy lines remain readable but v2 lifecycle
+  is shown historical/unjoined rather than guessed.
+- Lifecycle adds `running`, `deadlineAt`, and optional `herdrPaneId`/`herdrAgentName`, so an abandoned start
+  becomes incomplete and a live Herdr child can be focused by identity.
+- Add identifier-only workflow facts with explicit `planned`, `observed`, or `controller_validated`
+  provenance. Enforced children remain a separate event class. Principal runs receive labels through existing
+  correlation fields; no workflow prompt prose is parsed.
+- Add packaged v3 schema and generated fixtures while preserving the v2 artifact paths unchanged.
+- **First-review hardening:** keep routed descendants on one absolute ledger; consolidate mixed chain gates
+  into one decision per execution; share strict runtime v3 validation across both readers; runtime-check
+  workflow vocabularies; isolate display callbacks from child execution; verify plugin provenance before
+  enabled state; and persist only literal installation choices.
+- **Second-review hardening:** remove raw corrupt bytes from the canonical `/grants ledger` report; recheck
+  workspace/tab on reuse and returned open identity; validate every nested pane-state entry; reject prose in
+  v3 display/capability fields and strip all Unicode control/format characters; share one absolute child
+  deadline and running-before-terminal append order; and make public builders assert the exact closed wire.
+- **Third-review hardening:** pane reuse keys exactly on workspace/tab/ledger rather than invocation `cwd`, and
+  the workflow-fact builder joins every other public v3 builder at the final closed-wire assertion.
+- **Whole-change-review hardening:** reject stored pane entries whose workspace/tab/ledger disagrees with their
+  key, and validate explicit v2 against the frozen schema before presenting it as historical/unjoinable.
+- **Critical-retry hardening:** align all seven v3 schema timestamp sites with runtime's seconds `00`–`59`
+  profile; reject a running lifecycle event that changes its occurrence deadline; reserve SIGTERM grace inside
+  the remaining process budget and enforce the recorded hard deadline with an independent SIGKILL timer.
+- **Deadline race repairs:** soft and hard deadline callbacks allow pending child exit delivery one event-loop
+  turn before acting, then refuse to rewrite a completed PID as timed out merely because descendant pipes delay
+  `close`. A genuinely live PID remains subject to SIGTERM and absolute-deadline SIGKILL. Soft and hard routes
+  each have their own child-synchronized regression and mutation. The soft timer begins after a real ready
+  marker; the hard route uses a detached Linux process-state observer to establish OS exit before overdue timer
+  delivery. Tests use `Atomics.wait` rather than scheduler assumptions or busy-spinning, while a direct
+  request-mutation guard forces production to snapshot the hard deadline before spawn. The Linux observer is
+  independently bounded and accepts only zombie state or `ENOENT` as exit. The hard proof requires that exit
+  before a future recorded epoch, then delays controller delivery across it; observer status is published by
+  newline-terminated complete-status polling. An unexported AsyncLocalStorage test clock establishes the proof
+  epoch only after readiness without weakening public `runChild` snapshot semantics; synchronization searches
+  across arbitrary output chunk boundaries before retaining a bounded overlap suffix. Dedicated mutations
+  force internal-control consultation, cross-chunk matching and complete terminal-status grammar. Deterministic
+  status tests cover partial/complete writes, timeout, observer error, transient/permanent reads and expiry;
+  same-process control tests use a two-party barrier for real controlled/uncontrolled overlap and also cover
+  nesting, rejection and post-settlement cleanup. Polling has an independent attempt ceiling; AsyncLocalStorage
+  ownership lives only under `test/`; build cleans stale `dist/` first and installed smoke refuses the former
+  artifact, leaving no control module in the published package.
+- **BREAKING — `LedgerReport.corrupt[]` now exposes `{line, reason}` rather than `{line, text}`.** Raw corrupt
+  bytes can contain task/output material and are no longer retained by the public integrity result. Consumers
+  that need forensic bytes must read the ledger itself at the reported line; pi-daddy never repairs it.
+- **BREAKING — correlation fields rendered as labels/IDs now require the ASCII identifier grammar
+  `[A-Za-z0-9@*][A-Za-z0-9@*._:/-]{0,127}`.** Replace spaces with `-` or `_` before delegating. This prevents a
+  model-facing `policy_label`/phase/run ID from becoming a free-text task/output channel into the append-only
+  ledger and terminal. Other bounded correlation strings remain unchanged. A top-level
+  `assurance_scope: null` is normalized away and is not a valid v3 wire value; omit it instead.
+- **BREAKING — named check IDs must use the same ASCII identifier alphabet and be at most 460 characters.**
+  Rename prose/whitespace keys before calling `runNamedCheck`; invalid IDs now refuse before the executable
+  or lease starts rather than failing only when a v3 receipt is appended.
+
+
+## 0.19.0 — workspace routing is a capability (2026-08-23)
+
+**The four hang fixes below were staged for a 0.18.2 and are released here instead — a decision reversed
+deliberately, so the reversal is recorded rather than the reason vanishing.** The paragraph that stood here
+argued for cutting them as a patch so a fix for released code would not be gated on a breaking change. The
+counter-argument won: **R-131 — workspace routing does not attenuate — is a live escalation in published
+0.18.0 and 0.18.1**, a child routed to `staging` can route its grandchild to `prod` with a real lease and a
+ledger line that reads as authorised, and the fix for it *is* the breaking change. A 0.18.2 would have fixed
+one defect and left that one open, on a line that then needed supporting alongside this one. Shipping once
+fixes all three.
+
+- **FIX — a retained lease no longer reports a retention that did not happen (R-152).** `markRetained`
+  returned `void` and `releaseDelegationWorkspace` hardcoded the ledger word, so a `workspace_lease` event
+  said `retained` — *"the pane may still be live"* — for a helper that had already died (the fact is `lost`),
+  for a lease already cleanly released, and for a retention whose record could not be written. It now answers
+  in the release vocabulary and the caller ledgers what it says. **Breaking for direct library callers only:**
+  `WorkspaceLease.markRetained` returns `Promise<LeaseReleaseOutcome>` instead of `Promise<void>`, and
+  `LeaseReleaseOutcome` gained `retained` (so `| "retained"` unions are now redundant, not wrong).
+- **FIX — an impossible `herdr tab close` bound is rejected at both ends, and as a `RangeError` (R-152).**
+  Above `2^31 - 1` the timeout truncates — `Number.MAX_SAFE_INTEGER` becomes 1ms and SIGKILLs every close
+  attempt before herdr can act (measured: callback at 3ms for a 3s sleep) — the mirror of the `0` case, which
+  means no bound at all. Fractional counts were accepted too. **The exception type changed on purpose:** this
+  was a `GovernanceRefusal` carrying `WORKSPACE_LEASE_STALE`, which elsewhere means the lease went stale, so a
+  controller switching on codes would retry a permanent caller bug. Both bounds are now validated for read
+  leases as well, where the check previously sat below an early return and validated nothing.
+- **FIX — a retained writer lease no longer stops its own process from exiting (R-146).** `markRetained`
+  leaves the kernel lock and the pane alone by design; it also left the parent's three pipes to the lock
+  helper referenced, and the helper was never `unref`ed, so node's event loop stayed alive and `pi` could
+  never exit. Measured: `exit=124` (timed out) against `exit=0` for the same sequence ending in `release()`.
+  Reached whenever the herdr executor's `tab close` fails. **Which hosts it wedged:** those that let the loop
+  drain — pi's `-p`/print mode, and library consumers such as an ADR-0034 external controller. Interactive and
+  rpc mode call `process.exit()`, so there the process still left and the on-exit pane sweep still ran.
+  Present in 0.18.0 and 0.18.1. Retention still holds the lock: on the parent's exit the helper makes its
+  bounded close attempts and then releases, so the worktree is recoverable (R-102) rather than stranded.
+- **FIX — one `herdr tab close` attempt is now bounded in wall clock, not only in count (R-146).** The
+  helper's `execFile` had no `timeout`, so a herdr that accepted the close and never answered never called
+  back: the retry budget was unreachable, no marker was written, and the lock was held **forever** — R-102's
+  explicitly rejected outcome. Measured with a `herdr` that sleeps: before, `LOCK=HELD` with no marker
+  indefinitely; after, released with the marker written. Tunable via `herdrCloseTimeoutMs` (default 15s).
+
+
+- Ship a canonical JSON Schema draft 2020-12 contract for `ledgerVersion: 2` plus deterministic fixtures for
+  all four event types, generated through the production builders. Stable package export paths let external
+  harnesses pin the real contract instead of maintaining a parallel format.
+- Add a check-receipt event builder and use it on the production named-check path, so every checked-in fixture
+  is produced by the same builder that emits the corresponding ledger line.
+- Document strict version dispatch: legacy 0.17 grant records have no explicit version; unsupported explicit
+  versions fail closed and are never reinterpreted as legacy.
+
+- **BREAKING — routing a child to a registered workspace now requires `workspace:<id>` in the caller's
+  grant.** Every grant that routes must add it; a delegation naming a workspace the session does not hold
+  is refused `WORKSPACE_NOT_AUTHORIZED`, with the id recorded in `denied` so it counts as an escalation.
+
+  Until now this was the one governance dimension that did **not** attenuate: the registry inherited into
+  every governed child and nothing checked the caller's authority, so a child routed to `staging` could
+  route its grandchild to `prod` — with a real lease, a validated CWD, and a ledger line naming `prod`.
+  Measured in `docs/probes/g36-workspace-attenuation`, decided in ADR-0035, tracked as R-131.
+
+  Failing open for compatibility was considered and rejected: it would have made an attenuation fix opt-in.
+  The migration is one line per grant, and `pi-daddy init` now lists the registered ids commented in
+  `.pi/grants.env` so the edit is visible from the file you already open.
+
+- `PI_GRANTS_GATED=workspace:prod` asks a human before a child is routed there, through ADR-0024's existing
+  mechanism — the id is the caller's authority for that one delegation and never joins the child's grant.
+  `workspace:*` in the gate covers every id.
+- `workspace:*` covers the namespace but is **held, never inherited** — R-26's rule, because a descendant
+  holding it could route anywhere the registry lists. `agent:*` is unchanged and still inherits. Asking to
+  hand `workspace:*` to a child is refused (`NARROWING_VIOLATED`) rather than silently stripped, so the
+  ledger never records authority the child did not receive.
+- `tool:*` still satisfies a workspace capability: governance is opt-in and an ungoverned session must keep
+  routing anywhere.
+- A `workspace:` id never reaches pi's `--tools`. It is enforced by pi-daddy before the spawn, which is a
+  different and weaker class than the `--tools` allowlist; `docs/SPEC.md` now states both classes explicitly.
+- **BREAKING — a registry id must now match `[A-Za-z0-9][A-Za-z0-9._/-]*`.** The registry became an input to
+  the grant grammar when an id became the tail of a capability id, so ids that 0.18.0/0.18.1 accepted are now
+  refused `GRANT_ID_MALFORMED` at load, naming the file and the id. **Slashes and dots are fine** — a worktree
+  named after its branch (`feature/x`) works, and an earlier build of this release wrongly refused it by
+  reusing the tool-name grammar. Refused: whitespace (it splits `allowed-tools`), commas and newlines (they
+  split a grant — 0.18.1's defect), `*` (it collided with `workspace:*`, so registering a worktree as `*` and
+  granting `workspace:*` minted routing over the whole registry), shell metacharacters (they reach the
+  `ROUTABLE WORKSPACES` block of a generated `.pi/grants.env`, which tells you to paste them into your
+  grant), and non-ASCII (the generated file is reviewed in an editor, where control characters and
+  homoglyphs let one id render as another). One bad entry refuses the whole file, so rename before upgrading.
+- **The registry must be a regular file under 1 MiB** — a FIFO there blocked session start indefinitely, and
+  the read is bounded by one handle `fstat`-ed as a descriptor. **Ownership and mode are NOT checked.** An
+  earlier draft of this release added a uid/world-writable guard and this bullet promised it; `e1937cf`
+  removed the code when the change was narrowed to ADR-0035 and left the promise here for a day. Nothing in
+  0.19.0 checks who may write the registry, and a mode check would not reach the attack that matters — a
+  governed child runs as the same uid as its parent. Tracked as R-137.
+- No `workspace:` id is live by default in a generated grant, including one a package's `allowed-tools`
+  declares. Which worktree a child starts in is the operator's decision (ADR-0028).
+
+### Fixed before release — found reviewing this change
+
+The first group never shipped — they were defects in 0.19.0's own development, caught by two review passes
+and a mutation battery, and are listed because ADR-0035 claimed three of them as done (R-133, and that ADR's
+amendment). **The entries under "Present in earlier releases" below DID ship**, and an earlier draft of this section put
+them under this heading, telling operators the `tool:*` attenuation escape could not affect them. (That draft
+then said "two" while three bullets sat under the heading, one of which — the v2 enum — is the single item
+here that provably did *not* ship. It has moved back.)
+
+- **Routing terminated below the root instead of attenuating.** `unknownCapabilities` did not know the
+  namespace, and a catalog is always present in a real session, so every requested `workspace:<id>` was
+  refused as an unknown capability. No child could be granted one, which made the "two authorities" model
+  unreachable. This was the headline defect.
+- The `PI_GRANTS_GATED=workspace:<id>` gate above was claimed and inert.
+- `pi-daddy init` had never heard of the workspace registry.
+- `allowed-tools: workspace:prod` in a `SKILL.md` became `tool:workspace:prod`, which names nothing.
+- `isSafeCapability` rejected the namespace, so the boundary that generates grants could not emit the
+  capability this release makes mandatory.
+- `subsumedBy` reported `workspace:*`-covered ids as subsumed, contradicting its own rule.
+- The v2 ledger contract's `refusalCode` enum is now **generated** from `REFUSAL_CODES` by
+  `scripts/generate-ledger-v2-contract.ts` instead of hand-maintained beside it. `WORKSPACE_NOT_AUTHORIZED`
+  joins the enum in this release; `contracts/ledger/v2/README.md` records why that is a legitimate v2 edit
+  rather than a v3 — v2 has never been published, so nothing can have pinned it. It is **not** the last such
+  edit: every other closed enum in that schema is still hand-maintained beside its source array — `test/ledger-contract.test.ts`
+  asserts each equality, so the same ambush waits for whoever adds an executor kind or a lease outcome. (First
+  written as "five"; the figure is larger and is not worth restating, since the test file is the list.)
+
+### Present in earlier releases — read these before upgrading
+
+**Upgrade if you run governed delegation trees, and read R-135 first.**
+
+- **R-135, and it is not part of this feature.** `tool:*` was reaching delegated children. R-26's rule —
+  a wildcard is held, never inherited — was enforced only in `childEnv`, the interceptor path, while
+  `delegate.ts` (the path that spawns, since 0.7.0 — ADR-0016) applied no filter, and `tool:*` is not universal enough
+  for `assertNarrowing` to stop. A parent holding `tool:*` and delegating `tools: ["tool:*"]` gave its child
+  `tool:*`, so attenuation ended at the root. **Present in every published version.** One shared
+  `inheritableGrant` now serves both paths. If you run governed delegation trees, this is the entry to read.
+
+- **R-134.** Session start no longer warns that a gated `agent:` id "does NOT gate spawning that definition".
+  That was R-47's partial fix in 0.11.1 and false from 0.12.0, when ADR-0024's gate landed. The warning
+  outlived the defect across eight published versions (0.13.0 through 0.18.1), and the integration suite
+  required it to, while advising operators to
+  remove a control that works.
+
 ## 0.18.1 — SECURITY: a capability id containing a comma minted authority
 
 **Upgrade if you use `tool:*` or `agent:*` in any grant.** Present in 0.18.0 and every earlier published

package/README.md

@@ -220,6 +220,39 @@ no `--env` (the grant rides on the pane, which the agent's shell inherits), `age
 shell so a multi-line argument must be staged to a file, and `agent wait --until idle` matches the state the
 agent was *already* in, so settling requires a state counter to advance.
 
+### Persistent Herdr dashboard
+
+When this pi process is itself hosted inside Herdr 0.8+, `/grants dashboard` opens a managed right split:
+
+```text
+PI-DADDY
+◆ principal-feature · critical · declared
+● plan       running   0:42 · pane w7:p13
+└─ ⛔ deploy refused   0:00
+
+depth 2 · 1 active
+```
+
+The plugin ships inside pi-daddy and is linked globally only after an explicit **Install and open** choice.
+Literal **Not now** and **Never ask** choices are persisted; dismissing or losing the dialog stores nothing.
+`/grants dashboard` never installs silently and prints the exact manual command when the plugin is absent. It
+checks the bundled plugin root and protocol before suggesting that a disabled plugin be enabled. Panes and
+ledgers stay workspace/tab-specific: reuse rechecks the pane's current workspace/tab, a wrong-host open is
+closed and rejected, and malformed nested pane state refuses rather than risking a duplicate. A stored entry's
+workspace/tab/ledger must also agree with its hash key before reuse. Invocation `cwd` sets the first pane
+process directory but is not pane identity, so the same workspace/tab/ledger still reuses one pane across caller directories. Opening uses a right split targeted at this pi pane with `--no-focus`.
+
+The view is a read-only ledger projection. Yellow is authorised/starting/running, green completed, red failed
+or refused, and grey incomplete/historical. Old completed subtrees collapse; active ancestry stays visible.
+It never displays task text, prompts, tool arguments, child output, or raw corrupt lines. Displayed ledger
+values must satisfy the v3 identifier grammars (unsafe frozen-v2 values are redacted), and Unicode C1/bidi or
+other control/format characters are removed before terminal output.
+
+Provenance markers are explicit: **P** planned phase, **O** observed inline activity, **V**
+controller-validated transition, **E** pi-daddy-enforced child, **D** caller-declared correlation. A principal
+run can label itself through `run_id`, `phase`, effective assurance and `policy_label`; pi-daddy does not parse
+principal workflow prose or invent pending/completed phases.
+
 ## Approving a gated capability
 
 `gated` capabilities are ones a session holds but may not pass on without a human saying so.
@@ -330,11 +363,36 @@ All fields are optional; existing callers behave unchanged.
   Git worktree root, and sets initial CWD. A caller cannot label a write-capable grant read-only. Kernel
   util-linux `flock` allows one **pi-daddy-governed** writer per canonical root; `setpriv --pdeathsig` plus
   helper attachment stops the writer process or herdr tab on parent death before release. This does not confine paths or exclude unrelated writers; `bash` remains an escape.
+
+  **BREAKING in 0.19.0 — routing now requires a capability.** A delegation naming `workspace_id: W` needs
+  `workspace:W` in the caller's grant, or it is refused `WORKSPACE_NOT_AUTHORIZED`. Every grant that routes
+  must add it: `PI_GRANTS_GRANT="tool:read,tool:delegate,workspace:W"`. `pi-daddy init` lists the registered
+  ids commented in `.pi/grants.env`. A child can only route on to ids it was granted itself, so this is also
+  the list of what any descendant could reach; `workspace:*` exists but is held and never inherited, which
+  makes it the wrong answer for anything but a single-worktree setup. `PI_GRANTS_GATED=workspace:W` asks a
+  human first. Enforced by pi-daddy before the spawn, not by pi's `--tools` — see `docs/SPEC.md` on the
+  enforcement classes.
+
+  **BREAKING in 0.19.0 — a registry id must match `[A-Za-z0-9][A-Za-z0-9._/-]*`.** An id is now the tail of a
+  capability id, so it has to survive the grant grammar. **Slashes and dots are fine**, so a worktree named
+  after its branch (`feature/x`) works. Refused, with the file and the id named: whitespace (it splits a
+  definition's `allowed-tools`), commas and newlines (they split a grant), `*` (it collided with
+  `workspace:*`), shell metacharacters (they reach a generated file you are told to paste from), non-ASCII,
+  and `@ + % = ^ ! ? ~ { } [ ]` or a leading `_`, `-` or `.`. **One bad entry refuses the whole registry**, so
+  rename before upgrading. The regex is the specification; that list is a summary.
+
+  **Also new in 0.19.0:** the registry must be a **regular file under 1 MiB**. A FIFO or device there would
+  block session start rather than fail, and the read is bounded so a file that grows after its size is checked
+  is refused rather than allocated. What is *not* checked: ownership, permissions, and whether a descendant
+  holding a write tool repointed an entry — routing attenuates by **id**, not by **destination**
+  (`docs/probes/g37-registry-tamper`, tracked as R-137).
 - Refusals retain current prose and add stable codes such as `CAPABILITY_ESCALATION`,
   `GATED_UNAPPROVED`, `APPROVAL_SCOPE_MISMATCH`, and `WORKSPACE_WRITE_CONFLICT`.
-- Ledger v2 adds joinable capability, lease, lifecycle and check-receipt events while reading legacy lines.
+- Ledger v3 adds unique execution/parent identity, joinable capability/lease/lifecycle/check events, and
+  provenance-labelled workflow facts while retaining frozen v2 and legacy readers.
 - `pi-daddy/check-runner` selects an operator-named absolute executable+argv definition, never a shell
-  command string. It strips sensitive inherited environment, enforces timeout/output caps, executes a
+  command string. Check IDs use the v3 ASCII identifier alphabet and are refused before execution if they do
+  not fit their generated receipt identity. It strips sensitive inherited environment, enforces timeout/output caps, executes a
   private copy of the exact executable bytes it hashed, and pre/post-verifies Git head/candidate-tree
   identity under an exclusive coordination lease. The executable remains arbitrary code; no filesystem or
   network sandbox is claimed.
@@ -342,6 +400,22 @@ All fields are optional; existing callers behave unchanged.
 Public subpaths: `pi-daddy/correlation`, `pi-daddy/refusals`, `pi-daddy/workspace`,
 `pi-daddy/check-runner`.
 
+### Canonical ledger v3 contract
+
+Machine consumers should import or resolve
+`pi-daddy/contracts/ledger/v3/ledger-event.schema.json`, not infer a format from prose. Generated fixtures for
+all five events are adjacent. v3 adds globally unique `executionId`, explicit `parentExecutionId`, bounded
+start deadlines, optional Herdr pane identity, and provenance-labelled workflow facts. `childId` remains the
+readable logical tree position and is never an occurrence join.
+
+Dispatch on version before event: no version/discriminator is a legacy 0.17 grant record; explicit v2 uses the
+frozen published v2 contract; explicit v3 uses the new closed contract; every other explicit version fails
+closed and is never read as legacy. `verifyLedger` and the dashboard share exact runtime v3 validation, so a
+lookalike string version, missing join identity or malformed nested correlation cannot be `OK` in one and
+corrupt in the other. Explicit v2 is checked against its exact frozen schema before the dashboard labels it
+historical; malformed v2 never becomes a grey row or orphan count. A field/event/enum/requiredness or semantic change requires another ledger version. See
+`contracts/ledger/v3/README.md`; the v2 path remains available unchanged.
+
 ## Running it
 
 ```bash
@@ -350,6 +424,8 @@ PI_GRANTS_GRANT="agent:review,tool:read,tool:grep,tool:find,tool:ls,tool:delegat
 PI_GRANTS_LEDGER=.pi/grants.jsonl \
 PI_GRANTS_MAX_DEPTH=2 \
 pi
+# The relative ledger is resolved once at session start and inherited as one absolute path,
+# so routed descendants changing cwd still append to this tree.
 ```
 
 **Plain `pi`, no `-e`, when you installed this from npm** — the package declares `pi.extensions` and pi
@@ -373,12 +449,15 @@ approval says so:
                         as NONE, never as everything.
 ```
 
-`/grants ledger` reads the ledger back and reports its integrity — record count, escalation attempts, any
-unparseable lines with line numbers, and **which instructions actually ran**: records grouped by definition
+`/grants dashboard` verifies that this exact pi PID is hosted in its declared Herdr pane, verifies the ledger
+and plugin, then opens or reuses a right split without changing focus. `/grants ledger` reads the audit file
+back and reports its integrity — record count, escalation attempts, any unparseable lines with line numbers
+and content-free reasons (never copied ledger bytes), and **which instructions actually ran**: records grouped by definition
 digest, each compared against the file on disk (`current` / `CHANGED since`), which is what makes ADR-0018's
 `definitionDigest` answerable rather than decorative. It exists because nothing in this package had ever read a ledger
 back, so a torn line was indistinguishable from a spawn that never happened. A corrupt line is **evidence**
-and is left alone rather than repaired. Nothing runs this check automatically.
+and is left alone rather than repaired. Session start checks integrity automatically; `/grants ledger` gives
+the full report.
 
 ## Worked example: governing `principal-pi-skills`
 
@@ -511,7 +590,8 @@ everything below it.
 | `PI_GRANTS_WORKSPACE_LEASE_DIR` | under `$PI_CODING_AGENT_DIR/pi-daddy/` | Kernel writer locks and ownership metadata. |
 | `PI_GRANTS_CHILD_TIMEOUT` | `600` (seconds) | Wall-clock limit for a child. Inherited by descendants — an operator preference, deliberately *not* attenuating state. |
 | `PI_GRANTS_FANOUT` | `8` | Per-call width and downward subtree budget; not a session-total counter. Malformed or `0` falls back to the default. |
-| `PI_GRANTS_PARENT_ID` | `d0` | This session's ledger id; set by the parent. Makes sibling records joinable into a tree. |
+| `PI_GRANTS_PARENT_ID` | `d0` | Readable logical tree position; set by the parent and allowed to repeat across calls. |
+| `PI_GRANTS_EXECUTION_ID` | unset at a root | Unique governed execution occurrence; set by the parent. Lifecycle/lease joins use this, never `PI_GRANTS_PARENT_ID`. |
 | `PI_GRANTS_HERDR` | unset ⇒ **probe** | Three-state. Unset probes for a reachable herdr and uses panes if one answers; `1` demands panes and refuses every delegation if herdr is unreachable; `0` demands captured subprocesses. Never detected from `herdr` merely being on `PATH`. |
 | `PI_GRANTS_HERDR_WORKSPACE` | the parent's `HERDR_WORKSPACE_ID` | herdr workspace for spawned panes. Defaults to the workspace this session is in, so a child is a tab away rather than a workspace away. |
 | `PI_GRANTS_HERDR_KEEP_PANE` | unset | `1` keeps each child's pane for inspection, and no sweep closes it. Off by default: a fan-out would flood the workspace. |
@@ -532,21 +612,32 @@ is broken after 10s.
 
 ## The ledger
 
-Append-only JSONL. Version 2 records capability decisions plus workspace-lease, child-lifecycle and
-check-receipt events. Every per-child capability decision is present, **including refusals**; call-level
-schema/cardinality rejections that create no child ID are not capability events. The reader still accepts
-legacy grant-only lines.
+Append-only JSONL. Version 3 records capability decisions, workspace leases, child lifecycle, check receipts
+and workflow facts. Every per-child capability decision is present, **including refusals**. The reader still
+accepts frozen v2 and legacy grant-only lines.
+
+`childId` is hierarchical and readable (`d0.1`, `d0.1.2`) but repeated/parallel calls may reuse it. v3 adds a
+random `executionId` and explicit `parentExecutionId`; those are the only lifecycle/lease occurrence join.
+A v2 lifecycle is therefore shown historical/unjoined rather than guessed. A v3 starting deadline and the
+executor timer share one absolute budget — waiting for the strict starting append consumes it, a later running
+event cannot replace it, and process SIGTERM grace stays inside it under an independent hard-kill timer. That
+timer bounds the governed PID while live. Soft and hard deadline callbacks first allow one event-loop turn for
+pending child exit delivery; retained descendant pipes cannot rewrite a PID that already exited successfully as
+timed out. A pending running append always lands before a terminal event. `denied` non-empty remains the designated escalation signal — **an agent asking for what it does not hold is an escalation attempt, and it
+is invisible without a record.**
 
-Ids are hierarchical and derived: a child of `d0` is `d0.1`, its own second child `d0.1.2`. Ancestry reads
-from the id alone with no join, and it is reproducible, so two runs of the same fan-out produce a diffable
-ledger. `denied` non-empty is the one designated escalation signal — **an agent asking for what it does not
-hold is an escalation attempt, and it is invisible without a record.**
+Workflow facts are identifier-only and mark `planned`, `observed`, or `controller_validated`; they can never
+claim pi-daddy enforcement. Capability/lifecycle records are the enforced class. Correlation remains a
+caller-declared label; fields eligible for display must use the v3 ASCII identifier grammar rather than prose.
 
 **Privacy is a property of this file, and the boundary is exact: capability ids, counts and identifiers only
 — never prompts, task text, tool arguments or results.** Trusted `definitionDigest` and `taskDigest` values
 identify the exact operator body and task. A predictable task can be guessed from SHA-256, so its digest is
 sensitive/linkable metadata, not anonymization. Caller-supplied digest-looking values remain under
-`correlation` and never authorize.
+`correlation` and never authorize. Public v3 builders validate their serialized wire form against the same
+closed runtime contract the readers use; `deadlineAt` therefore cannot be a `Date.parse` lookalike. Schema and
+runtime share the seconds `00`–`59` timestamp profile because JavaScript deadline arithmetic cannot represent
+leap seconds, and a normalized-away top-level null assurance scope is not schema-valid.
 
 ## Propagation is race-free by construction
 
@@ -624,7 +715,7 @@ The resolver, ledger, spawn planner and the whole approval model are pure functi
 without pi:
 
 ```ts
-import { resolve, assertNarrowing, planSpawn, buildRecord, appendRecord } from "pi-daddy";
+import { resolve, assertNarrowing, planSpawn, buildRecord, appendRecord, digestTask, newExecutionId } from "pi-daddy";
 
 const result = resolve({
   requested:   ["tool:read", "tool:grep"],
@@ -638,12 +729,15 @@ const plan = planSpawn({ effective: result.effective, prompt: task });
 // -> ["--print","--no-session","--no-extensions","--no-skills","--no-context-files",
 //     "--no-prompt-templates","--tools","grep,read"," summarise src/"]
 
-await appendRecord({ path: ".pi/grants.jsonl" }, buildRecord({ /* … */ result, blocked: false, now: new Date() }));
+await appendRecord({ path: ".pi/grants.jsonl" }, buildRecord({
+  /* capability fields … */ result, blocked: false, executor: "process",
+  executionId: newExecutionId(), parentExecutionId: null, taskDigest: digestTask(task), now: new Date(),
+}));
 ```
 
 Subpaths are exported individually (`pi-daddy/resolve`, `/ledger`, `/spawn`, `/delegate`, `/catalog`,
 `/propagation`, `/definitions`, `/fanout`, `/pi-tools`, `/approval`, `/approval-store`, `/approval-prompt`,
-`/run-child`, `/run-herdr`).
+`/run-child`, `/run-herdr`, `/dashboard-projection`, `/dashboard-render`).
 
 ## Design decisions worth knowing
 
@@ -673,7 +767,9 @@ npx pi-daddy init           # as a command: scaffold .pi/skills/ and .pi/grants.
                             # skill packages — see the worked example above
 ```
 
-The package is all three. pi loads `extensions/grants.ts` through its own transpiling loader, which reads
+The package is also the source of the optional Herdr plugin: the extension offers to link the trusted
+`herdr-plugin/` directory explicitly, and `pi-daddy-dashboard` is the terminal renderer binary. pi loads
+`extensions/grants.ts` through its own transpiling loader, which reads
 TypeScript from `node_modules` quite happily; **Node does not** — it refuses to strip types under
 `node_modules` — so the library entry points are compiled to `dist/`. Until 0.6.0 `exports` pointed at
 `./src/*.ts`, and every consumer import failed with `ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING` while
@@ -683,11 +779,11 @@ every in-repo test passed. `npm run test:smoke` packs a tarball, installs it int
 ## Testing
 
 ```bash
-npm test                   # 587 unit tests. Fast, pure, no pi, no network.
+npm test                   # 719 unit tests. Fast, pure, no pi, no network.
 npm run typecheck          # src + extensions + tests + integration tests
-npm run test:integration   # 44 tests against a REAL pi process. ~55s, no model tokens.
-npm run test:smoke         # pack, install into a scratch project, import and use it — and run the
-                           # installed `pi-daddy init` bin, which is how R-73 was found
+npm run test:integration   # 45 tests against a REAL pi process. ~55s, no model tokens.
+npm run test:smoke         # pack/install; exercise library exports, both bins, the v2/v3 contracts,
+                           # bundled Herdr plugin, dashboard, and `pi-daddy init`
 PI_GRANTS_IT_MODEL=1 npm run test:integration   # + 10 end-to-end tests with a real model. Costs money.
 ```
 
@@ -713,6 +809,17 @@ its own author the day after it was added: rather than raise the cap, `delegatio
 
 ## Status
 
+**0.20.0 — live Herdr dashboard and ledger v3.** Adds the explicit installation handshake,
+`/grants dashboard`, duplicate-safe right split, pure live projection, unique execution/parent identity,
+workflow provenance facts and principal correlation labels. Enforcement is unchanged.
+
+**0.19.0 — workspace routing is a capability.** Routing now attenuates through `workspace:<id>`; see the
+changelog for the breaking migration.
+
+**0.18.1 — security fix for malformed capability IDs.** Capability IDs containing comma, CR, LF, NUL or
+surrounding whitespace are refused before resolution and again before grant serialization, preventing a
+wildcard-covered string from splitting into authority the parent never held.
+
 **0.18.0 — generic runtime enforcement, still honest about scope.** The governed spawn path now includes
 optional correlation, exact task-bound approvals, registered-worktree CWD validation, OS-backed governed
 writer leases, structured refusals, lifecycle/lease ledger events, and a no-shell named-check subpath. All
@@ -737,6 +844,12 @@ Known gaps, stated because a gap nobody wrote down is the one that surprises som
 - **A running delegation is visible.** One status block per call — per child: its definition, its herdr agent, its
   pane id, its state, elapsed time, and the last three lines it printed. Bounded in height and width, so a fan-out
   cannot flood your screen. It is a **display, never the result**.
+- **The dashboard whole-file polls.** The MVP is sized for 10 MiB; 50 MiB or 100 ms p95 projection is the
+  switch point for incremental replay.
+- **v2 is historical in the dashboard.** It has no unique occurrence ID, so lifecycle is reported unjoined
+  rather than matched by reusable `childId`.
+- **principal-pi-skills does not yet publish a generated graph declaration.** Explicit correlation and
+  provenance facts render; prompt prose is never parsed into a graph.
 - **A definition's *instructions* are governed only by identity.** `agent:<name>` says which file may be
   spawned and the digest says which version ran, but nothing reads a body and judges what it says — the
   operator authorises a file, and its contents are their responsibility.

package/contracts/ledger/v2/README.md

@@ -0,0 +1,59 @@
+# pi-daddy ledger contract — version 2
+
+Canonical machine contract for one `ledgerVersion: 2` JSONL line:
+
+- `ledger-event.schema.json` — JSON Schema draft 2020-12 union, closed by event discriminator.
+- `fixtures/*.json` — deterministic examples generated in the repository by
+  `scripts/generate-ledger-v2-contract.ts` through the production builders.
+
+After the package version carrying this unreleased artifact is published, installed consumers can resolve
+`pi-daddy/contracts/ledger/v2/ledger-event.schema.json` and the four fixtures as
+`pi-daddy/contracts/ledger/v2/fixtures/{capability-decision,workspace-lease,child-lifecycle,check-receipt}.json`.
+JSON module imports require the runtime's JSON import attribute; filesystem-based validators can resolve the
+same exported package paths without importing the JSON as code.
+
+## Dispatch and compatibility
+
+1. No `ledgerVersion` and no `event` is a legacy 0.17 `GrantRecord`. It is intentionally not described by
+   the v2 schema; pi-daddy's reader continues accepting it.
+2. `ledgerVersion: 2` requires one of the four exact event discriminators and validation against this schema.
+3. Any other explicit `ledgerVersion`, a missing discriminator, or an unknown discriminator must fail closed.
+   Never reinterpret it as a legacy grant line. pi-daddy's `verifyLedger` enforces that dispatch boundary and
+   required join fields; consumers needing full nested validation use this schema.
+
+The v2 schema is closed (`additionalProperties: false`) so a pinned consumer cannot silently assign meaning
+to a field it does not know. Adding/removing a field, event, enum member, requiredness rule, or changing a
+field's meaning requires a new ledger version and a new versioned path. Correcting prose or adding a fixture
+that does not change accepted records does not.
+
+**The rule above binds from first publication, and v2 was first published in 0.19.0.** It was added to the
+repository during 0.19.0's development and no released version has ever carried it, so nothing can have
+pinned it — which is why `WORKSPACE_NOT_AUTHORIZED` (ADR-0035) could join `refusalCode`'s enum in that same
+release rather than forcing a v3 for one refusal code. Recorded here rather than left to inference, because
+the rule as written forbids exactly that edit and a reader comparing the two would be right to.
+
+This is the only such amendment for `refusalCode`: from 0.19.0 that enum is **generated** from
+`REFUSAL_CODES` by `scripts/generate-ledger-v2-contract.ts`, and `test/ledger-contract.test.ts` holds the two
+equal. So a new refusal code is now a visible, mechanical change to this artifact — which is what makes the
+rule above enforceable instead of aspirational. Before that it was hand-maintained beside the array it had to
+match, and the first code added after publication turned the suite red with no diff from the generator.
+
+## Event field inventory
+
+All v2 events require `ledgerVersion`, `event`, and RFC 3339 `ts`; all carry a joinable `childId` and may
+carry bounded, non-authoritative `correlation` metadata.
+
+- `capability_decision`: parent/child/depth, executor, requested/parent/effective/denied/clipped/gated sets,
+  blocked/reason, trusted task and optional definition digests, approval source/scope/expiry/use facts,
+  optional prior-task author, human/gate outcome, and structured refusal.
+- `workspace_lease`: workspace/root/access, acquisition or release outcome, recovery fact, release reason,
+  and structured refusal.
+- `child_lifecycle`: starting/completed/failed state, executor, nullable exit code and signal, timeout/abort/
+  truncation flags, and reason.
+- `check_receipt`: receipt/workspace/check IDs and candidate tree identity. The full named-check receipt is a
+  separate return artifact; the ledger event is its join record.
+
+Trusted fields (`taskDigest`, `definitionDigest`) are outside `correlation`. Digest-looking correlation
+values remain opaque and non-authoritative. `assurance_scope`, `schema_version`, access classification,
+workspace attenuation, approval freshness, tree identity, lease-directory identity, and runtime-cycle
+limitations remain exactly as documented in `docs/SPEC.md`; this artifact does not repair or hide them.

package/contracts/ledger/v2/fixtures/capability-decision.json

@@ -0,0 +1,95 @@
+{
+  "ledgerVersion": 2,
+  "event": "capability_decision",
+  "ts": "2026-08-20T12:00:01.000Z",
+  "parentId": "d0",
+  "childId": "d0.1",
+  "depth": 1,
+  "agentType": "build",
+  "executor": "process",
+  "taskFrom": "d0.0",
+  "taskDigest": "9999999999999999999999999999999999999999999999999999999999999999",
+  "correlation": {
+    "schema_version": "1.0",
+    "run_id": "run-contract-001",
+    "task_id": "task-contract-001",
+    "workspace_id": "workspace-contract",
+    "context_id": "context-contract",
+    "phase": "verify",
+    "assurance": "critical",
+    "assurance_effective": "critical",
+    "policy_label": "policy-contract",
+    "assurance_source": "policy",
+    "assurance_scope": {
+      "kind": "changed-files",
+      "paths": [
+        "src/**"
+      ],
+      "include_untracked": true
+    },
+    "activated_at": "2026-08-20T12:00:00.000Z",
+    "plan_digest": "1111111111111111111111111111111111111111111111111111111111111111",
+    "definition_digest": "2222222222222222222222222222222222222222222222222222222222222222",
+    "task_digest": "3333333333333333333333333333333333333333333333333333333333333333",
+    "base_sha": "4444444444444444444444444444444444444444",
+    "head_sha": "5555555555555555555555555555555555555555",
+    "tree_sha": "6666666666666666666666666666666666666666",
+    "event_seq": 21,
+    "last_change_seq": 18,
+    "last_authority_seq": 20,
+    "check_receipt_id": "7777777777777777777777777777777777777777777777777777777777777777"
+  },
+  "refusal": {
+    "code": "WORKSPACE_WRITE_CONFLICT",
+    "message": "workspace-contract already has a governed writer",
+    "details": {
+      "workspace_id": "workspace-contract",
+      "retryable": true,
+      "holder_depth": 1
+    }
+  },
+  "requested": [
+    "tool:bash",
+    "tool:read"
+  ],
+  "parentGrant": [
+    "agent:build",
+    "tool:bash",
+    "tool:read"
+  ],
+  "effective": [
+    "tool:bash",
+    "tool:read"
+  ],
+  "denied": [],
+  "clipped": [],
+  "gatedBlocked": [],
+  "blocked": true,
+  "reason": "workspace-contract already has a governed writer",
+  "approved": [
+    "tool:bash",
+    "tool:read"
+  ],
+  "approvalSources": {
+    "tool:bash": "persisted",
+    "tool:read": "prompt"
+  },
+  "approvalScopes": {
+    "tool:bash": "always",
+    "tool:read": "once"
+  },
+  "approvalExpiresAt": {
+    "tool:bash": "2026-09-19T12:00:00.000Z"
+  },
+  "approvalUses": {
+    "tool:read": {
+      "max": 1,
+      "remaining": 0
+    }
+  },
+  "definitionDigest": {
+    "name": "build",
+    "source": "/operator/skills/build/SKILL.md",
+    "sha256": "8888888888888888888888888888888888888888888888888888888888888888"
+  }
+}