pi-daddy 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -12,6 +12,24 @@ 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.21.0 — one project init enables its ledger (2026-09-01)
+
+- `/grants init` now atomically persists one project choice containing both the capability grant and default
+  `.pi/grants.jsonl`, then adopts both after that write succeeds. Future plain `pi` starts load both, so
+  `/grants ledger` and `/grants dashboard` need no repeated shell export.
+- Merely installing pi-daddy still initializes nothing. `PI_GRANTS_GRANT` bypasses the project store for
+  children/CI, and `PI_GRANTS_LEDGER` overrides the stored default, including `""` for a one-run opt-out.
+- Existing version-1 grant stores retain their no-ledger behavior until the operator explicitly reruns
+  `/grants init`; an upgrade never converts prior governance consent into recording consent.
+- Newly generated `.pi/grants.env` files export the project ledger. Existing reviewed files remain untouched.
+- **First-review repair:** remember whether the ledger came from the environment before publishing a stored
+  default, so a later init after a cwd change can replace pi-daddy's own old path without overriding a real
+  operator value. A second review made v1 lookalike `projectLedger` fields an explicit inert case after its
+  mutation survived the first tests. Review also exposed pre-existing malformed-store fail-open behavior
+  (R-175); it remains open and is not presented as fixed by this release.
+- **Final-quality repair:** installed smoke now matches the active ledger export as a complete line; the old
+  commented `#export` contained the previous substring and falsely passed.
+
 ## 0.20.1 — open the dashboard with Herdr's split-pane contract (2026-09-01)
 
 - Fix `/grants dashboard` on Herdr 0.8+: a split plugin pane targets the verified caller pane and must not

package/README.md

@@ -6,7 +6,8 @@ tree, so a sub-agent can never hold more of the **tool surface** than its parent
 configured.
 
 Both qualifiers are load-bearing and are not buried: a child granted `bash` can escape governance entirely
-(ADR-0012, measured), and the ledger is opt-in. See *What this governs, and what it does not*.
+(ADR-0012, measured), and recording is opt-in — explicitly by environment or by running `/grants init` once
+for this project. See *What this governs, and what it does not*.
 
 > **0.13.0 was the first published release.** Earlier versions were developed in-repo and never shipped, so
 > the breaking changes in the changelog describe how this package arrived at its current behaviour rather
@@ -475,9 +476,12 @@ pi                      # then, inside pi:
 
 **`pi install`, not `npm install`** — it registers the package with pi, which is what makes the extension
 auto-load; presence in `node_modules` alone does nothing. `/grants init` asks only about the capabilities
-that can change your machine and applies the answer to the running session, no restart (ADR-0030).
-`npx pi-daddy init` does the same scaffolding from a shell, and both search pi's install root as well as
-the project's.
+that can change your machine and applies the answer to the running session, no restart (ADR-0030). That one
+project opt-in now also enables `.pi/grants.jsonl` immediately and for every later plain `pi` start
+(ADR-0037), so `/grants ledger` and `/grants dashboard` need no shell export. Merely installing the package
+does not initialize unrelated directories. `npx pi-daddy init` does the same scaffolding from a shell, and
+both search pi's install root as well as the project's. A pre-0.21 stored grant is not retroactive recording
+consent; run `/grants init` once after upgrading to enable its default ledger.
 
 ```
 found principal-pi-skills@2.3.1 — 7 skill(s), 0 declaring allowed-tools
@@ -579,13 +583,13 @@ everything below it.
 
 | Variable | Default | Notes |
 | :--- | :--- | :--- |
-| `PI_GRANTS_GRANT` | unset → ungoverned | Presence is what switches governance on. |
+| `PI_GRANTS_GRANT` | unset → use this directory's stored init choice, or ungoverned when none exists | Presence switches governance on and bypasses the whole cwd store; this is how children and CI stay environment-only. |
 | `PI_GRANTS_MAX_DEPTH` | `2` | Child-depth bound. `0` disables spawning. |
 | `PI_GRANTS_DEPTH` | `0` | This session's own depth; set by the parent, not by hand. |
 | `PI_GRANTS_GATED` | **`tool:bash`** in a governed session | Capabilities needing human approval. Set to `""` to gate nothing. Gating is closed under subsumption, so this also covers `write`/`edit`/`read`/`grep`/`find`/`ls` (ADR-0012). |
 | `PI_GRANTS_APPROVED` | unset | Inherited `capability@subject#sha256` entries; set by the parent, clamped to the child's own grant, and honoured only against the definition body the child itself loaded (ADR-0022). |
 | `PI_GRANTS_APPROVAL_TIMEOUT` | `120` (seconds) | How long a dialog waits. `0` or an unreadable value means **no timeout**: waiting forever denies nothing, so it is the safe reading of a value we do not understand. |
-| `PI_GRANTS_LEDGER` | unset → not recording | **Setting this makes the ledger load-bearing** — see below. |
+| `PI_GRANTS_LEDGER` | unset → a v2 `/grants init` choice uses `<cwd>/.pi/grants.jsonl`; otherwise not recording | Presence overrides the project default; `""` disables it for one run. Any effective path is load-bearing. |
 | `PI_GRANTS_WORKSPACE_REGISTRY` | unset | Operator-owned `{version:1, workspaces:{id:{path}}}` file, required only for workspace-routed spawns. |
 | `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. |
@@ -595,7 +599,7 @@ everything below it.
 | `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. |
-| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi's own variable, not ours — but it decides where persisted approvals live, so it is listed here. |
+| `PI_CODING_AGENT_DIR` | `~/.pi/agent` | pi's own variable, not ours — but it decides where stored project grants/ledger consent and persisted approvals live. |
 
 **A malformed value disables spawning; it never falls back to a default.** An unreadable
 `PI_GRANTS_MAX_DEPTH` or `PI_GRANTS_DEPTH` yields `maxDepth: 0` and a startup warning naming the
@@ -603,12 +607,13 @@ variable. Before 0.5.0 these were read with `parseInt`, which accepts numeric pr
 and otherwise gives `NaN` — and since every comparison against `NaN` is false, a typo did not tighten the
 depth limit, it **removed** it.
 
-**Configuring a ledger makes it a precondition, not a log.** If `PI_GRANTS_LEDGER` is set and the write
-fails, the delegation is **refused**. Asking for an audit trail is an explicit act, and `ledger.ts` has
-always documented that an unrecorded grant should fail closed; until 0.5.0 both call sites silently
-swallowed the error. Sessions with no ledger configured are unaffected. Concurrent appends are serialised by
-a lock file with a short timeout — failing closed beats hanging — and a lock abandoned by a killed process
-is broken after 10s.
+**Configuring a ledger makes it a precondition, not a log.** This applies equally to an explicit
+`PI_GRANTS_LEDGER` and to the project default accepted through `/grants init`: if the write fails, delegation
+is **refused**. Asking for an audit trail is an explicit act, and `ledger.ts` has always documented that an
+unrecorded grant should fail closed; until 0.5.0 both call sites silently swallowed the error. Legacy v1 grant
+stores and sessions with no ledger configured are unaffected. Concurrent appends are serialised by a lock file
+with a short timeout — failing closed beats hanging — and a lock abandoned by a killed process is broken after
+10s.
 
 ## The ledger
 

package/dist/grant-env.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant-env.d.ts","sourceRoot":"","sources":["../src/grant-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,EAEpD,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAQ/D;AAaD,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAU/D;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,iCAAiC;IACjC,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,6GAA6G;IAC7G,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,yFAAyF;IACzF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,sGAAsG;IACtG,kBAAkB,CAAC,EAAE,UAAU,EAAE,CAAC;IAClC,kGAAkG;IAClG,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CA4G3D;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,EAAE,UAAgC,CAAC"}
+{"version":3,"file":"grant-env.d.ts","sourceRoot":"","sources":["../src/grant-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,UAAU,EAEpD,CAAC;AAEF,0DAA0D;AAC1D,wBAAgB,eAAe,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAQ/D;AAaD,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAU/D;AAED,gFAAgF;AAChF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,iCAAiC;IACjC,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,6GAA6G;IAC7G,QAAQ,EAAE,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IACpC,yFAAyF;IACzF,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,sGAAsG;IACtG,kBAAkB,CAAC,EAAE,UAAU,EAAE,CAAC;IAClC,kGAAkG;IAClG,eAAe,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAA;KAAE,EAAE,CAAC;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CA6G3D;AAED,qFAAqF;AACrF,eAAO,MAAM,WAAW,EAAE,UAAgC,CAAC"}

package/dist/grant-env.js

@@ -146,7 +146,7 @@ export function renderGrantEnv(input) {
         lines.push(`# CAUTION: ${caution}`);
     if (input.cautions.length > 0)
         lines.push("#");
-    lines.push("# tool:delegate is what registers the delegation tools at all — withhold it and this session is a leaf.", `export PI_GRANTS_GRANT="${input.live.join(",")}"`, "", "# Optional. Setting a ledger makes it LOAD-BEARING: a spawn that cannot be recorded is refused.", '#export PI_GRANTS_LEDGER=".pi/grants.jsonl"', "", "# Optional. tool:bash is ALREADY gated by default, so this line only matters if you widen it:", "# gating is closed under subsumption, so gating tool:write also gates tool:bash (bash can write).", '#export PI_GRANTS_GATED="tool:bash,tool:write"', "");
+    lines.push("# tool:delegate is what registers the delegation tools at all — withhold it and this session is a leaf.", `export PI_GRANTS_GRANT="${input.live.join(",")}"`, "", "# Init enables this project ledger. It is LOAD-BEARING: a spawn that cannot be recorded is refused.", '# PI_GRANTS_LEDGER still overrides the stored default used by plain `pi` after `/grants init`.', 'export PI_GRANTS_LEDGER=".pi/grants.jsonl"', "", "# Optional. tool:bash is ALREADY gated by default, so this line only matters if you widen it:", "# gating is closed under subsumption, so gating tool:write also gates tool:bash (bash can write).", '#export PI_GRANTS_GATED="tool:bash,tool:write"', "");
     return lines.join("\n");
 }
 /** The capability that must always be live, or the generated file is inert (S-5). */

package/dist/grant-env.js.map

@@ -1 +1 @@
-{"version":3,"file":"grant-env.js","sourceRoot":"","sources":["../src/grant-env.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grant-env.js","sourceRoot":"","sources":["../src/grant-env.ts"],"names":[],"mappings":"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"}

package/dist/grant-store.d.ts

@@ -1,9 +1,10 @@
 /**
- * The grant for a directory, stored **outside** it.
+ * The init choice for a directory, stored **outside** it: its grant and, in v2, explicit project-ledger
+ * consent.
  *
- * `PI_GRANTS_GRANT` is the propagation channel to children and stays exactly as it was — a parent writes
- * it once per session and every child inherits it. What this adds is a second *source* for the root
- * session's own grant, so an operator does not have to `source` a file and restart pi to be governed.
+ * `PI_GRANTS_GRANT` and `PI_GRANTS_LEDGER` remain the propagation channel to children — a parent writes them
+ * and every child inherits them. The store is a root-session source only, so an operator does not have to
+ * `source` a file and restart pi after making the project choice.
  *
  * **Outside the workspace, and that is the whole design.** A grant is a ceiling; a ceiling a governed child
  * can rewrite is not a ceiling. `<cwd>/.pi/grants.env` is writable by any child holding `tool:write`, so
@@ -18,6 +19,14 @@
  * of the decision, diffable in a PR. It is simply no longer the thing the enforcer reads.
  */
 import type { Capability } from "./resolve.ts";
+export interface StoredGrant {
+    grant: Capability[];
+    /** Whether a root session defaults to `<cwd>/.pi/grants.jsonl`. False for every legacy v1 store. */
+    projectLedger: boolean;
+}
+export interface SaveGrantOptions {
+    projectLedger?: boolean;
+}
 /**
  * Where this directory's grant lives.
  *
@@ -27,15 +36,17 @@ import type { Capability } from "./resolve.ts";
  */
 export declare function grantStorePath(cwd: string): string;
 /**
- * Parse a store file's text into a grant, or null.
+ * Parse a store file's text into its versioned project choice, or null.
  *
  * Split out from the readers so the **one** validation lives in one place: both the sync and async paths
  * must agree, and two parsers is how they come to disagree.
  *
- * Fails closed on every doubt — a malformed file grants nothing rather than something. The `cwd` check is
- * R-27's: a file copied to another machine or another checkout describes a directory that is not this one,
- * and honouring it would let a grant travel somewhere nobody authorised it for.
+ * Rejects every doubt at this parser boundary — it never constructs a partial ceiling. The session currently
+ * treats absent and invalid stores alike (R-175), so do not call that wider behavior fail-closed. The `cwd`
+ * check is R-27's: a copied file describes a directory nobody authorised it for.
  */
+export declare function parseStoredGrant(text: string, cwd: string): StoredGrant | null;
+/** Compatibility view for callers that need only the capability ceiling. */
 export declare function parseGrantFile(text: string, cwd: string): Capability[] | null;
 /**
  * Read this directory's stored grant, synchronously.
@@ -46,12 +57,16 @@ export declare function parseGrantFile(text: string, cwd: string): Capability[]
  * decision it exists to inform, so the store would silently fail to grant delegation — the exact class of
  * defect R-38 and R-39 were.
  */
+export declare function loadStoredGrantSync(cwd: string): StoredGrant | null;
 export declare function loadGrantSync(cwd: string): Capability[] | null;
 /** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
+export declare function loadStoredGrant(cwd: string): Promise<StoredGrant | null>;
 export declare function loadGrant(cwd: string): Promise<Capability[] | null>;
+/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
+export declare function projectLedgerPath(cwd: string): string;
 export type SaveOutcome = "saved" | "failed" | "busy";
 /**
- * Write this directory's grant.
+ * Write this directory's grant and optional project-ledger consent as one atomic choice.
  *
  * Locked with the same lock the ledger and the approval store use, for the same reason: two sessions in one
  * directory running `/grants init` concurrently must not interleave. A lock this cannot take yields `busy`
@@ -62,7 +77,7 @@ export type SaveOutcome = "saved" | "failed" | "busy";
  * filesystem, so a reader never sees a half-written grant. Both copied from `writeFileSafely`, deliberately
  * — a second, subtly different atomic-write is how the two come to disagree about what "safe" meant.
  */
-export declare function saveGrant(cwd: string, grant: Capability[]): Promise<SaveOutcome>;
+export declare function saveGrant(cwd: string, grant: Capability[], options?: SaveGrantOptions): Promise<SaveOutcome>;
 /** Remove this directory's stored grant. True when a file was there to remove. */
 export declare function clearGrant(cwd: string): Promise<boolean>;
 //# sourceMappingURL=grant-store.d.ts.map

package/dist/grant-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grant-store.d.ts","sourceRoot":"","sources":["../src/grant-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAgB/C;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAW7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAM9D;AAED,2FAA2F;AAC3F,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAMzE;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAmBtF;AAED,kFAAkF;AAClF,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS9D"}
+{"version":3,"file":"grant-store.d.ts","sourceRoot":"","sources":["../src/grant-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAoB/C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,oGAAoG;IACpG,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAOD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAIlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAoB9E;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,IAAI,CAMnE;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,EAAE,GAAG,IAAI,CAE9D;AAED,2FAA2F;AAC3F,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAM9E;AAED,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAEzE;AAED,kFAAkF;AAClF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEtD;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,UAAU,EAAE,EACnB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAED,kFAAkF;AAClF,wBAAsB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAS9D"}

package/dist/grant-store.js

@@ -1,9 +1,10 @@
 /**
- * The grant for a directory, stored **outside** it.
+ * The init choice for a directory, stored **outside** it: its grant and, in v2, explicit project-ledger
+ * consent.
  *
- * `PI_GRANTS_GRANT` is the propagation channel to children and stays exactly as it was — a parent writes
- * it once per session and every child inherits it. What this adds is a second *source* for the root
- * session's own grant, so an operator does not have to `source` a file and restart pi to be governed.
+ * `PI_GRANTS_GRANT` and `PI_GRANTS_LEDGER` remain the propagation channel to children — a parent writes them
+ * and every child inherits them. The store is a root-session source only, so an operator does not have to
+ * `source` a file and restart pi after making the project choice.
  *
  * **Outside the workspace, and that is the whole design.** A grant is a ceiling; a ceiling a governed child
  * can rewrite is not a ceiling. `<cwd>/.pi/grants.env` is writable by any child holding `tool:write`, so
@@ -22,7 +23,7 @@ import { readFileSync } from "node:fs";
 import { mkdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { withFileLock, LockTimeoutError } from "./file-lock.js";
 /** `$PI_CODING_AGENT_DIR`, or pi's default. Same resolution as the approval store. */
 function agentDir() {
@@ -41,19 +42,19 @@ export function grantStorePath(cwd) {
     return join(agentDir(), "grants", `${slug}-${hash}.json`);
 }
 /**
- * Parse a store file's text into a grant, or null.
+ * Parse a store file's text into its versioned project choice, or null.
  *
  * Split out from the readers so the **one** validation lives in one place: both the sync and async paths
  * must agree, and two parsers is how they come to disagree.
  *
- * Fails closed on every doubt — a malformed file grants nothing rather than something. The `cwd` check is
- * R-27's: a file copied to another machine or another checkout describes a directory that is not this one,
- * and honouring it would let a grant travel somewhere nobody authorised it for.
+ * Rejects every doubt at this parser boundary — it never constructs a partial ceiling. The session currently
+ * treats absent and invalid stores alike (R-175), so do not call that wider behavior fail-closed. The `cwd`
+ * check is R-27's: a copied file describes a directory nobody authorised it for.
  */
-export function parseGrantFile(text, cwd) {
+export function parseStoredGrant(text, cwd) {
     try {
         const parsed = JSON.parse(text);
-        if (parsed.version !== 1)
+        if (parsed.version !== 1 && parsed.version !== 2)
             return null;
         if (parsed.cwd !== cwd)
             return null;
@@ -61,12 +62,21 @@ export function parseGrantFile(text, cwd) {
             return null;
         if (!parsed.grant.every((c) => typeof c === "string" && c.length > 0))
             return null;
-        return parsed.grant;
+        if (parsed.version === 2 && parsed.projectLedger !== true)
+            return null;
+        return {
+            grant: parsed.grant,
+            projectLedger: parsed.version === 2,
+        };
     }
     catch {
         return null;
     }
 }
+/** Compatibility view for callers that need only the capability ceiling. */
+export function parseGrantFile(text, cwd) {
+    return parseStoredGrant(text, cwd)?.grant ?? null;
+}
 /**
  * Read this directory's stored grant, synchronously.
  *
@@ -76,25 +86,35 @@ export function parseGrantFile(text, cwd) {
  * decision it exists to inform, so the store would silently fail to grant delegation — the exact class of
  * defect R-38 and R-39 were.
  */
-export function loadGrantSync(cwd) {
+export function loadStoredGrantSync(cwd) {
     try {
-        return parseGrantFile(readFileSync(grantStorePath(cwd), "utf8"), cwd);
+        return parseStoredGrant(readFileSync(grantStorePath(cwd), "utf8"), cwd);
     }
     catch {
         return null;
     }
 }
+export function loadGrantSync(cwd) {
+    return loadStoredGrantSync(cwd)?.grant ?? null;
+}
 /** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
-export async function loadGrant(cwd) {
+export async function loadStoredGrant(cwd) {
     try {
-        return parseGrantFile(await readFile(grantStorePath(cwd), "utf8"), cwd);
+        return parseStoredGrant(await readFile(grantStorePath(cwd), "utf8"), cwd);
     }
     catch {
         return null;
     }
 }
+export async function loadGrant(cwd) {
+    return (await loadStoredGrant(cwd))?.grant ?? null;
+}
+/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
+export function projectLedgerPath(cwd) {
+    return resolve(cwd, ".pi", "grants.jsonl");
+}
 /**
- * Write this directory's grant.
+ * Write this directory's grant and optional project-ledger consent as one atomic choice.
  *
  * Locked with the same lock the ledger and the approval store use, for the same reason: two sessions in one
  * directory running `/grants init` concurrently must not interleave. A lock this cannot take yields `busy`
@@ -105,9 +125,12 @@ export async function loadGrant(cwd) {
  * filesystem, so a reader never sees a half-written grant. Both copied from `writeFileSafely`, deliberately
  * — a second, subtly different atomic-write is how the two come to disagree about what "safe" meant.
  */
-export async function saveGrant(cwd, grant) {
+export async function saveGrant(cwd, grant, options = {}) {
     const path = grantStorePath(cwd);
-    const file = { version: 1, cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
+    const common = { cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
+    const file = options.projectLedger
+        ? { version: 2, ...common, projectLedger: true }
+        : { version: 1, ...common };
     try {
         await mkdir(dirname(path), { recursive: true });
         return await withFileLock(path, "grant store", async () => {

package/dist/grant-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"grant-store.js","sourceRoot":"","sources":["../src/grant-store.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"grant-store.js","sourceRoot":"","sources":["../src/grant-store.ts"],"names":[],"mappings":"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"}

package/extensions/grants-command.ts

@@ -52,8 +52,8 @@ export interface GrantsCommandContext {
    */
   previewDelegation: (name: string) => Promise<GatedPlan>;
   /**
-   * Run `/grants init`: scaffold definitions, ask about the withheld capabilities only, store the answer
-   * outside the workspace, and apply it to this session (ADR-0030).
+   * Run `/grants init`: scaffold definitions, ask about withheld capabilities, atomically store grant plus
+   * project-ledger consent outside the workspace, and apply both now (ADR-0030, ADR-0037).
    *
    * Injected rather than imported so this module stays what it is — a read-only diagnostic that cannot
    * become a governance path by accident. The one command here that *writes* takes its ability to do so
@@ -345,7 +345,7 @@ handler: async (args: string, ctx: any) => {
       // two facts about what a spawn will be sit together.
       `  executor   ${executor.disclosure}`,
       `  depth      ${depth} of max ${maxDepth}${maxDepth <= 0 ? " (spawning disabled)" : ""}`,
-      `  ledger     ${ledgerPath ?? "(not recording — set PI_GRANTS_LEDGER)"}`,
+      `  ledger     ${ledgerPath || "(not recording — set PI_GRANTS_LEDGER)"}`,
       `  approvals  ${sessionApprovals.size} this session, ${valid.size} persisted` +
         `${inheritedApprovals.size > 0 ? `, ${inheritedApprovals.size} inherited` : ""}` +
         ` — /grants approvals`,

package/extensions/init-command.ts

@@ -10,12 +10,12 @@
 import { discoverSkillPackages } from "../src/skill-packages.ts";
 import { applyInit, planInit } from "../src/init.ts";
 import { registeredWorkspaceIds } from "../src/workspace.ts";
-import { saveGrant, grantStorePath } from "../src/grant-store.ts";
+import { grantStorePath, projectLedgerPath, saveGrant } from "../src/grant-store.ts";
 import { expandSubsumed, SUBSUMPTION, type Capability } from "../src/resolve.ts";
 import type { GrantsSession } from "./session.ts";
 
 /**
- * `/grants init` — scaffold, ask about what is withheld, store it outside the workspace, apply it now.
+ * `/grants init` — scaffold, ask about what is withheld, store grant + ledger consent, apply both now.
  *
  * **The dialog covers the withheld capabilities and nothing else** (ADR-0030). Asking about all of them
  * would be a dozen questions for a first run, and this project has a name for what that produces: R-25,
@@ -118,7 +118,8 @@ export async function runInit(
   }
 
   const finalGrant = [...grant].sort();
-  const saved = await saveGrant(ctx.cwd, finalGrant);
+  const ledger = projectLedgerPath(ctx.cwd);
+  const saved = await saveGrant(ctx.cwd, finalGrant, { projectLedger: true });
   if (saved !== "saved") {
     lines.push(
       `  NOT STORED — ${saved === "busy" ? "another session holds the grant store" : "the store could not be written"}. ` +
@@ -130,12 +131,15 @@ export async function runInit(
 
   // Live, without a restart — the whole point of the store. Only after a successful write, so what runs and
   // what is recorded cannot disagree.
-  session.adoptGrant(finalGrant);
+  session.adoptGrant(finalGrant, ledger);
   // Order matters: the grant first, then the reload, because `refreshSpawnable` filters the definitions it
   // advertises through `maySpawnDefinition` against the grant the session now holds.
   await refresh();
 
-  lines.push(`  stored at ${grantStorePath(ctx.cwd)} — outside this project, so no child can rewrite it`);
+  lines.push(
+    `  stored at ${grantStorePath(ctx.cwd)} — outside this project, so no child can rewrite it`,
+    `  ledger ${ledger} — default for future pi sessions; PI_GRANTS_LEDGER still overrides it`,
+  );
   if (granted.length > 0) lines.push(`  GRANTED: ${granted.join(", ")}`);
   if (alreadyConferred.length > 0) {
     lines.push(`  ALREADY CONFERRED, not asked about: ${alreadyConferred.join(", ")}`);

package/extensions/session.ts

@@ -44,7 +44,7 @@ import type { Capability } from "../src/resolve.ts";
 import { loadDefinitions } from "../src/definitions.ts";
 import { buildCatalog } from "../src/catalog.ts";
 import { ENV_WORKSPACE_REGISTRY } from "../src/workspace.ts";
-import { loadGrantSync, grantStorePath } from "../src/grant-store.ts";
+import { grantStorePath, loadStoredGrantSync, projectLedgerPath } from "../src/grant-store.ts";
 import { republishable } from "./approvals.ts";
 
 /**
@@ -184,7 +184,7 @@ export interface GrantsSession {
    */
   readonly storeCwd: string;
   /**
-   * Adopt a grant decided DURING the session — `/grants init` answering a human — without a restart.
+   * Adopt the project choice made DURING the session — grant plus optional default ledger — without restart.
    *
    * Narrow by design: it sets the session's own grant and republishes, so the very next spawn is bounded by
    * it. It does **not** reach children that already exist; those are separate processes whose environment
@@ -194,7 +194,7 @@ export interface GrantsSession {
    * Only a human can reach this. Slash commands are user-invoked; no tool exposes it, so a model cannot
    * widen its own session's ceiling by calling something.
    */
-  adoptGrant(grant: Capability[]): void;
+  adoptGrant(grant: Capability[], projectLedger?: string): void;
 }
 
 /**
@@ -258,9 +258,16 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
   // against each other and says so if they differ, which is the only case this can get wrong.
   const grantRaw = process.env[ENV_GRANT];
   const storeCwd = process.cwd();
-  const stored = grantRaw === undefined ? loadGrantSync(storeCwd) : null;
+  // One root-only store read supplies both decisions made by `/grants init`. A child always has ENV_GRANT,
+  // so it cannot activate a ledger merely because its routed cwd happens to have a v2 store (ADR-0037).
+  const stored = grantRaw === undefined ? loadStoredGrantSync(storeCwd) : null;
   const governed = grantRaw !== undefined || stored !== null;
-  const inherited: Capability[] = grantRaw !== undefined ? parseList(grantRaw) : (stored ?? [WILDCARD]);
+  const inherited: Capability[] = grantRaw !== undefined ? parseList(grantRaw) : (stored?.grant ?? [WILDCARD]);
+  const ledgerRaw = process.env[ENV_LEDGER];
+  // Capture provenance before publishChildEnv writes this session's derived default into process.env. A later
+  // `/grants init` for ctx.cwd must not mistake our own publication for an operator override.
+  const ledgerFromEnvironment = ledgerRaw !== undefined;
+  const storedLedger = stored?.projectLedger ? projectLedgerPath(storeCwd) : undefined;
   // G7 / A-S4 + B-I4: strict, three-way parsing that fails CLOSED. A malformed bound used to yield
   // `NaN`, and every comparison against `NaN` is false, so depth limiting switched itself off.
   const bounds = depthConfig(process.env[ENV_DEPTH], process.env[ENV_MAX_DEPTH]);
@@ -280,7 +287,9 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
     // ungoverned-descendant escape hatch, and doing that silently is what changes here.
     // `PI_GRANTS_GATED=""` turns the default off; absent and empty are deliberately distinguishable.
     gated: governed ? gatedFromEnv(process.env[ENV_GATED]) : parseList(process.env[ENV_GATED]),
-    ledgerPath: process.env[ENV_LEDGER],
+    // Presence wins, including an explicitly empty value for a one-run opt-out. The store is eligible only
+    // when ENV_GRANT was absent above, preserving the environment as the child's single authority channel.
+    ledgerPath: ledgerRaw !== undefined ? ledgerRaw : storedLedger,
     // The un-probed reading. `resolveExecutor` replaces it at session start; until then a `1` already reads as
     // a refusal, which is the safe direction — a delegation that somehow ran before the probe would refuse
     // rather than quietly use the wrong executor.
@@ -342,13 +351,18 @@ export function createGrantsSession(extensionPath: string | undefined): GrantsSe
 
     storeCwd,
 
-    adoptGrant: (grant: Capability[]) => {
+    adoptGrant: (grant: Capability[], projectLedger?: string) => {
       // Governed too, not just bounded. A session that starts with no grant and then runs `/grants init` is
       // governed from that moment: every spawn is bounded by what was just stored. Leaving this false made
       // `/grants` print "inactive" while holding thirteen capabilities — a status line contradicting the
       // enforcer, which is the defect R-28 is named for.
       session.governed = true;
       session.ownGrant = grant;
+      // An environment ledger remains the explicit answer. Otherwise init's v2 choice becomes live now,
+      // before publishChildEnv gives the same absolute path to descendants.
+      if (!ledgerFromEnvironment && projectLedger !== undefined) {
+        session.ledgerPath = projectLedger;
+      }
       session.publishChildEnv();
     },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-daddy",
-  "version": "0.20.1",
+  "version": "0.21.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",

package/src/grant-env.ts

@@ -204,8 +204,9 @@ export function renderGrantEnv(input: GrantEnvInput): string {
     "# tool:delegate is what registers the delegation tools at all — withhold it and this session is a leaf.",
     `export PI_GRANTS_GRANT="${input.live.join(",")}"`,
     "",
-    "# Optional. Setting a ledger makes it LOAD-BEARING: a spawn that cannot be recorded is refused.",
-    '#export PI_GRANTS_LEDGER=".pi/grants.jsonl"',
+    "# Init enables this project ledger. It is LOAD-BEARING: a spawn that cannot be recorded is refused.",
+    '# PI_GRANTS_LEDGER still overrides the stored default used by plain `pi` after `/grants init`.',
+    'export PI_GRANTS_LEDGER=".pi/grants.jsonl"',
     "",
     "# Optional. tool:bash is ALREADY gated by default, so this line only matters if you widen it:",
     "# gating is closed under subsumption, so gating tool:write also gates tool:bash (bash can write).",

package/src/grant-store.ts

@@ -1,9 +1,10 @@
 /**
- * The grant for a directory, stored **outside** it.
+ * The init choice for a directory, stored **outside** it: its grant and, in v2, explicit project-ledger
+ * consent.
  *
- * `PI_GRANTS_GRANT` is the propagation channel to children and stays exactly as it was — a parent writes
- * it once per session and every child inherits it. What this adds is a second *source* for the root
- * session's own grant, so an operator does not have to `source` a file and restart pi to be governed.
+ * `PI_GRANTS_GRANT` and `PI_GRANTS_LEDGER` remain the propagation channel to children — a parent writes them
+ * and every child inherits them. The store is a root-session source only, so an operator does not have to
+ * `source` a file and restart pi after making the project choice.
  *
  * **Outside the workspace, and that is the whole design.** A grant is a ceiling; a ceiling a governed child
  * can rewrite is not a ceiling. `<cwd>/.pi/grants.env` is writable by any child holding `tool:write`, so
@@ -23,11 +24,11 @@ import { readFileSync } from "node:fs";
 import { mkdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { homedir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 import { withFileLock, LockTimeoutError } from "./file-lock.ts";
 import type { Capability } from "./resolve.ts";
 
-interface GrantFile {
+interface GrantFileV1 {
   version: 1;
   /** The directory this grant is for. Checked on read — an entry copied elsewhere is refused (R-27). */
   cwd: string;
@@ -36,6 +37,25 @@ interface GrantFile {
   writtenAt: string;
 }
 
+interface GrantFileV2 {
+  version: 2;
+  cwd: string;
+  grant: Capability[];
+  /** Explicit consent from ADR-0037's `/grants init`; never inferred from a legacy file merely existing. */
+  projectLedger: true;
+  writtenAt: string;
+}
+
+export interface StoredGrant {
+  grant: Capability[];
+  /** Whether a root session defaults to `<cwd>/.pi/grants.jsonl`. False for every legacy v1 store. */
+  projectLedger: boolean;
+}
+
+export interface SaveGrantOptions {
+  projectLedger?: boolean;
+}
+
 /** `$PI_CODING_AGENT_DIR`, or pi's default. Same resolution as the approval store. */
 function agentDir(): string {
   return process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
@@ -55,28 +75,42 @@ export function grantStorePath(cwd: string): string {
 }
 
 /**
- * Parse a store file's text into a grant, or null.
+ * Parse a store file's text into its versioned project choice, or null.
  *
  * Split out from the readers so the **one** validation lives in one place: both the sync and async paths
  * must agree, and two parsers is how they come to disagree.
  *
- * Fails closed on every doubt — a malformed file grants nothing rather than something. The `cwd` check is
- * R-27's: a file copied to another machine or another checkout describes a directory that is not this one,
- * and honouring it would let a grant travel somewhere nobody authorised it for.
+ * Rejects every doubt at this parser boundary — it never constructs a partial ceiling. The session currently
+ * treats absent and invalid stores alike (R-175), so do not call that wider behavior fail-closed. The `cwd`
+ * check is R-27's: a copied file describes a directory nobody authorised it for.
  */
-export function parseGrantFile(text: string, cwd: string): Capability[] | null {
+export function parseStoredGrant(text: string, cwd: string): StoredGrant | null {
   try {
-    const parsed = JSON.parse(text) as Partial<GrantFile>;
-    if (parsed.version !== 1) return null;
+    const parsed = JSON.parse(text) as {
+      version?: unknown;
+      cwd?: unknown;
+      grant?: unknown;
+      projectLedger?: unknown;
+    };
+    if (parsed.version !== 1 && parsed.version !== 2) return null;
     if (parsed.cwd !== cwd) return null;
     if (!Array.isArray(parsed.grant)) return null;
     if (!parsed.grant.every((c) => typeof c === "string" && c.length > 0)) return null;
-    return parsed.grant as Capability[];
+    if (parsed.version === 2 && parsed.projectLedger !== true) return null;
+    return {
+      grant: parsed.grant as Capability[],
+      projectLedger: parsed.version === 2,
+    };
   } catch {
     return null;
   }
 }
 
+/** Compatibility view for callers that need only the capability ceiling. */
+export function parseGrantFile(text: string, cwd: string): Capability[] | null {
+  return parseStoredGrant(text, cwd)?.grant ?? null;
+}
+
 /**
  * Read this directory's stored grant, synchronously.
  *
@@ -86,27 +120,40 @@ export function parseGrantFile(text: string, cwd: string): Capability[] | null {
  * decision it exists to inform, so the store would silently fail to grant delegation — the exact class of
  * defect R-38 and R-39 were.
  */
-export function loadGrantSync(cwd: string): Capability[] | null {
+export function loadStoredGrantSync(cwd: string): StoredGrant | null {
   try {
-    return parseGrantFile(readFileSync(grantStorePath(cwd), "utf8"), cwd);
+    return parseStoredGrant(readFileSync(grantStorePath(cwd), "utf8"), cwd);
   } catch {
     return null;
   }
 }
 
+export function loadGrantSync(cwd: string): Capability[] | null {
+  return loadStoredGrantSync(cwd)?.grant ?? null;
+}
+
 /** Async twin, for callers that already have one. Same parser, so they cannot disagree. */
-export async function loadGrant(cwd: string): Promise<Capability[] | null> {
+export async function loadStoredGrant(cwd: string): Promise<StoredGrant | null> {
   try {
-    return parseGrantFile(await readFile(grantStorePath(cwd), "utf8"), cwd);
+    return parseStoredGrant(await readFile(grantStorePath(cwd), "utf8"), cwd);
   } catch {
     return null;
   }
 }
 
+export async function loadGrant(cwd: string): Promise<Capability[] | null> {
+  return (await loadStoredGrant(cwd))?.grant ?? null;
+}
+
+/** The one project-local default ADR-0037 binds to an explicit v2 init choice. */
+export function projectLedgerPath(cwd: string): string {
+  return resolve(cwd, ".pi", "grants.jsonl");
+}
+
 export type SaveOutcome = "saved" | "failed" | "busy";
 
 /**
- * Write this directory's grant.
+ * Write this directory's grant and optional project-ledger consent as one atomic choice.
  *
  * Locked with the same lock the ledger and the approval store use, for the same reason: two sessions in one
  * directory running `/grants init` concurrently must not interleave. A lock this cannot take yields `busy`
@@ -117,9 +164,16 @@ export type SaveOutcome = "saved" | "failed" | "busy";
  * filesystem, so a reader never sees a half-written grant. Both copied from `writeFileSafely`, deliberately
  * — a second, subtly different atomic-write is how the two come to disagree about what "safe" meant.
  */
-export async function saveGrant(cwd: string, grant: Capability[]): Promise<SaveOutcome> {
+export async function saveGrant(
+  cwd: string,
+  grant: Capability[],
+  options: SaveGrantOptions = {},
+): Promise<SaveOutcome> {
   const path = grantStorePath(cwd);
-  const file: GrantFile = { version: 1, cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
+  const common = { cwd, grant: [...grant].sort(), writtenAt: new Date().toISOString() };
+  const file: GrantFileV1 | GrantFileV2 = options.projectLedger
+    ? { version: 2, ...common, projectLedger: true }
+    : { version: 1, ...common };
   try {
     await mkdir(dirname(path), { recursive: true });
     return await withFileLock(path, "grant store", async () => {