pi-daddy 0.13.0

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { resolve, assertNarrowing, toPiToolsAllowlist, UNIVERSAL_CAPABILITIES, type Capability, type ResolveInput, type ResolveResult, } from "./resolve.ts";
+export { appendRecord, buildRecord, isEscalationAttempt, type GrantRecord, type LedgerOptions, } from "./ledger.ts";
+export { planSpawn, type SpawnPlan, type SpawnPlanInput } from "./spawn.ts";
+export { APPROVAL_TTL_DAYS, DELEGATE_SUBJECT, approvalKey, entryVerdict, expiryFor, inheritApprovals, offeredScopes, resolveApprovals, shouldSeekApproval, type ApprovalEntry, type ApprovalPath, type ApprovalScope, type ApprovalSource, type EntryVerdict, type SubjectSnapshot, } from "./approval.ts";
+export { approvalsPath, loadApprovals, revokeAll, revokeApproval, saveApproval, type DroppedApproval, type SubjectLookup, } from "./approval-store.ts";
+export { createApprovalGate, createApprovalGateProvider, timeoutMsFromEnv, type ApprovalGate, type InFlightApprovals, type ApprovalUI, type PromptOutcome, type PromptOutcomeKind, type PromptRequest, } from "./approval-prompt.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,sBAAsB,EACtB,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,mBAAmB,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,EAChB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { resolve, assertNarrowing, toPiToolsAllowlist, UNIVERSAL_CAPABILITIES, } from "./resolve.js";
+export { appendRecord, buildRecord, isEscalationAttempt, } from "./ledger.js";
+export { planSpawn } from "./spawn.js";
+export { APPROVAL_TTL_DAYS, DELEGATE_SUBJECT, approvalKey, entryVerdict, expiryFor, inheritApprovals, offeredScopes, resolveApprovals, shouldSeekApproval, } from "./approval.js";
+export { approvalsPath, loadApprovals, revokeAll, revokeApproval, saveApproval, } from "./approval-store.js";
+export { createApprovalGate, createApprovalGateProvider, timeoutMsFromEnv, } from "./approval-prompt.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,eAAe,EACf,kBAAkB,EAClB,sBAAsB,GAIvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,YAAY,EACZ,WAAW,EACX,mBAAmB,GAGpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,WAAW,EACX,YAAY,EACZ,SAAS,EACT,gBAAgB,EAChB,aAAa,EACb,gBAAgB,EAChB,kBAAkB,GAOnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,aAAa,EACb,aAAa,EACb,SAAS,EACT,cAAc,EACd,YAAY,GAGb,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,GAOjB,MAAM,sBAAsB,CAAC"}

package/dist/ledger-report.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Reading a ledger back — integrity, instruction versions, and the ADR-0020 approval tally.
+ *
+ * Split from `ledger.ts` when the file-size guard refused it at 419 lines. The seam is real rather than
+ * arbitrary: `ledger.ts` **writes** one record at a time and fails closed when it cannot, while everything
+ * here **reads** a whole file and must never fail at all — a report is a diagnostic, and a diagnostic that
+ * throws on damaged input is useless on exactly the input it exists for. Every defect this half has had
+ * (R-63's bias, R-64's three malformed shapes) was a *reporting* defect, and none of them could have
+ * touched the write path.
+ *
+ * Re-exported from `./ledger` so the published subpath is unchanged.
+ */
+import type { ApprovalSource } from "./approval.ts";
+export interface LedgerReport {
+    /** False when the file is absent — a configuration state, not damage. */
+    exists: boolean;
+    /** Lines that parsed as records. */
+    records: number;
+    /** Lines that did not, with 1-based line numbers so the report is actionable. */
+    corrupt: Array<{
+        line: number;
+        text: string;
+    }>;
+    /** Records where an agent asked for more than it held — ADR-0008's designated signal. */
+    escalationAttempts: number;
+    /**
+     * Every distinct set of instructions this ledger saw run, with how many spawns used it (R-51).
+     *
+     * ADR-0018 advertises that a record answers *"did these four children run the same instructions?"* and
+     * *"has this definition changed since?"* — and until this existed **nothing read `definitionDigest` at
+     * all**, so both questions required hand-written `jq` and the second was not even reproducible with
+     * `sha256sum`, because the digest covers the body and not the frontmatter. A field no tool reads is a
+     * field that quietly becomes decoration.
+     *
+     * Grouped by `name` + `sha256`, so two entries with one name are exactly the evidence that a definition
+     * changed mid-ledger. Sorted by name then digest so two runs of the same fan-out produce a diffable
+     * report, like the ids themselves.
+     */
+    definitions: Array<{
+        name: string;
+        source: string;
+        sha256: string;
+        spawns: number;
+    }>;
+    /**
+     * Where the yes came from, per approved capability, tallied across the whole ledger.
+     *
+     * **This is the measurement ADR-0020 asks for.** That ADR keeps the persistence layer on R-25's fatigue
+     * argument with *no number behind it*, and named the evidence that would settle it: counting `persisted`
+     * against `prompt` over a few weeks of real use. It also said this "needs no new machinery" — true of the
+     * data and false of the answer, which required hand-written `jq`. Same shape as R-51: a field no tool
+     * reads becomes decoration, and a measurement nobody can run does not get run.
+     *
+     * **`bySource` counts RECORDS and is an upper bound, not an answer.** Deleting the persistence layer does
+     * not turn every `persisted` record back into a prompt: precedence is `inherited → session → persisted →
+     * prompt`, and `session` approvals live in memory and do not depend on the store at all. So a session that
+     * spawns `deploy` twenty times under one persisted entry writes twenty `persisted` records, while without
+     * the store it would raise **one** prompt and satisfy the other nineteen from the session cache. Reporting
+     * twenty prompts avoided would overstate the layer's value twentyfold, on the one number that decides
+     * whether to keep it — the same direction of bias `unattributed` exists to avoid, arrived at a different way.
+     *
+     * `distinctBySource` is the closer estimate: distinct `capability@subject` pairs, which bounds the cost of
+     * deletion at one prompt per pair per session. The ledger carries no session id, so the exact figure is not
+     * computable from it; both numbers are printed and labelled rather than one being presented as the truth.
+     *
+     * Counted from `approvalSources` **only**. `approvalSource` is deliberately not used as a fallback: before
+     * 0.11.1 that scalar was written for the whole set even when the sources differed (R-46), so folding it in
+     * would report humans as having been asked about capabilities they were never asked about — biasing the
+     * one direction this measurement must not be biased in. Those records are counted as `unattributed`
+     * instead, so the sample size is visible rather than silently smaller.
+     */
+    approvals: {
+        /** Raw record counts. An UPPER bound on prompts avoided — see above before quoting one. */
+        bySource: Record<ApprovalSource, number>;
+        /** Distinct `capability@subject` pairs per source. The closer estimate. */
+        distinctBySource: Record<ApprovalSource, number>;
+        /** Records carrying approvals from before per-capability sources existed. Not attributable; see above. */
+        unattributed: number;
+        /** Records where a human was asked and said no — the fatigue argument's other half. */
+        humanDenied: number;
+        /**
+         * Distinct `capability@subject` pairs a human declined.
+         *
+         * Same reason `distinctBySource` exists: R-29 shares a decline across every concurrent caller, so one
+         * click of *Deny* under an eight-wide fan-out writes eight `humanDenied` records. Reporting the raw
+         * count as "times a human declined" is the per-record bias R-63 removed from `persisted`, left in place
+         * on the number that argues hardest FOR the layer — which is the direction that flatters this package's
+         * own gating and therefore the one to be most careful with.
+         */
+        humanDeniedPairs: number;
+    };
+    ok: boolean;
+}
+/**
+ * Read the ledger back and report what is wrong with it.
+ *
+ * **This is the gap that mattered most.** `appendRecord`'s strict mode catches write *errors*, never
+ * corruption, and nothing in this package had ever read a ledger back — so a torn line was silently
+ * indistinguishable from a spawn that never happened. An audit trail whose damage is invisible is not a
+ * compensating control, and ADR-0008 leans on the ledger as exactly that.
+ *
+ * Deliberately reports rather than repairs. A corrupt line is evidence; rewriting the file to make it parse
+ * would destroy the one artifact an investigation has.
+ */
+export declare function verifyLedger(path: string): Promise<LedgerReport>;
+//# sourceMappingURL=ledger-report.d.ts.map

package/dist/ledger-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-report.d.ts","sourceRoot":"","sources":["../src/ledger-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAIpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,yFAAyF;IACzF,kBAAkB,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;OAYG;IACH,WAAW,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACrF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,SAAS,EAAE;QACT,2FAA2F;QAC3F,QAAQ,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACzC,2EAA2E;QAC3E,gBAAgB,EAAE,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;QACjD,0GAA0G;QAC1G,YAAY,EAAE,MAAM,CAAC;QACrB,uFAAuF;QACvF,WAAW,EAAE,MAAM,CAAC;QACpB;;;;;;;;WAQG;QACH,gBAAgB,EAAE,MAAM,CAAC;KAC1B,CAAC;IACF,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA0HtE"}

package/dist/ledger-report.js

@@ -0,0 +1,157 @@
+/**
+ * Reading a ledger back — integrity, instruction versions, and the ADR-0020 approval tally.
+ *
+ * Split from `ledger.ts` when the file-size guard refused it at 419 lines. The seam is real rather than
+ * arbitrary: `ledger.ts` **writes** one record at a time and fails closed when it cannot, while everything
+ * here **reads** a whole file and must never fail at all — a report is a diagnostic, and a diagnostic that
+ * throws on damaged input is useless on exactly the input it exists for. Every defect this half has had
+ * (R-63's bias, R-64's three malformed shapes) was a *reporting* defect, and none of them could have
+ * touched the write path.
+ *
+ * Re-exported from `./ledger` so the published subpath is unchanged.
+ */
+import { readFile } from "node:fs/promises";
+import { DELEGATE_SUBJECT } from "./approval.js";
+import { isEscalationAttempt } from "./ledger.js";
+/**
+ * Read the ledger back and report what is wrong with it.
+ *
+ * **This is the gap that mattered most.** `appendRecord`'s strict mode catches write *errors*, never
+ * corruption, and nothing in this package had ever read a ledger back — so a torn line was silently
+ * indistinguishable from a spawn that never happened. An audit trail whose damage is invisible is not a
+ * compensating control, and ADR-0008 leans on the ledger as exactly that.
+ *
+ * Deliberately reports rather than repairs. A corrupt line is evidence; rewriting the file to make it parse
+ * would destroy the one artifact an investigation has.
+ */
+export async function verifyLedger(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {
+                exists: false,
+                records: 0,
+                corrupt: [],
+                escalationAttempts: 0,
+                definitions: [],
+                approvals: {
+                    bySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
+                    distinctBySource: { prompt: 0, session: 0, persisted: 0, inherited: 0 },
+                    unattributed: 0,
+                    humanDenied: 0,
+                    humanDeniedPairs: 0,
+                },
+                ok: true,
+            };
+        }
+        throw error;
+    }
+    const corrupt = [];
+    // Keyed by name+digest: one name with two entries is the signal that the definition changed mid-ledger.
+    const digests = new Map();
+    let records = 0;
+    let escalationAttempts = 0;
+    const bySource = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
+    // `capability@subject` seen per source, so the report can state a bound as well as a raw count.
+    const distinct = {
+        prompt: new Set(),
+        session: new Set(),
+        persisted: new Set(),
+        inherited: new Set(),
+    };
+    let unattributed = 0;
+    let humanDenied = 0;
+    const deniedPairs = new Set();
+    const lines = text.split("\n");
+    lines.forEach((raw, index) => {
+        // A trailing newline yields one empty final element, which is normal rather than damage.
+        if (raw.trim().length === 0)
+            return;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!Array.isArray(parsed.denied))
+                throw new Error("not a grant record");
+            records += 1;
+            if (isEscalationAttempt(parsed))
+                escalationAttempts += 1;
+            if (parsed.humanDenied) {
+                humanDenied += 1;
+                const subject = parsed.agentType === undefined || parsed.agentType === "delegate" ? DELEGATE_SUBJECT : parsed.agentType;
+                for (const capability of parsed.gatedBlocked ?? [])
+                    deniedPairs.add(`${capability}@${subject}`);
+            }
+            // A **plain, non-empty** object. Three shapes were accepted here that must not be, all of them
+            // reachable from a torn, hand-edited or foreign line — which is the input class `verifyLedger` exists
+            // for, so "this package never writes that" is not a defence:
+            //   - `{}` beside a non-empty `approved` counted NOWHERE, silently shrinking the sample the comment
+            //     below promises to keep visible;
+            //   - an ARRAY passed `typeof === "object"` and was tallied with numeric indices as capability names;
+            //   - `null` is an object.
+            const rawSources = parsed.approvalSources;
+            const sources = rawSources && typeof rawSources === "object" && !Array.isArray(rawSources) && Object.keys(rawSources).length > 0
+                ? rawSources
+                : undefined;
+            if (sources) {
+                // The subject half of `capability@subject`. `agentType` is the definition's name, or the literal
+                // `"delegate"` for the `tools:` form — which is NOT `DELEGATE_SUBJECT`, the `<delegate>` the approval
+                // layer keys on. Mapped here rather than at the write site so old ledgers read correctly too.
+                // **Stated limit:** a definition genuinely named `delegate` is indistinguishable from the `tools:`
+                // form in this field, and their two distinct approvals count as one pair. `DELEGATE_SUBJECT`'s own
+                // angle brackets exist to make that collision impossible, and the ledger drops them.
+                const subject = parsed.agentType === undefined || parsed.agentType === "delegate" ? DELEGATE_SUBJECT : parsed.agentType;
+                for (const [capability, source] of Object.entries(sources)) {
+                    // `Object.hasOwn`, never `in`: `in` walks the prototype, so a source of `"toString"` or
+                    // `"valueOf"` passed the check, wrote a STRING into a counter, made `attributed` a string, and
+                    // deleted the entire measurement from the report while marking an intact ledger corrupt.
+                    // An unrecognised source is counted as unattributed rather than dropped: a tally that silently
+                    // ignores what it does not understand reports a smaller sample as a cleaner one.
+                    if (Object.hasOwn(bySource, source)) {
+                        bySource[source] += 1;
+                        distinct[source].add(`${capability}@${subject}`);
+                    }
+                    else
+                        unattributed += 1;
+                }
+            }
+            else if (parsed.approved && parsed.approved.length > 0) {
+                unattributed += parsed.approved.length;
+            }
+            const d = parsed.definitionDigest;
+            if (d?.name && d.sha256) {
+                const key = `${d.name}\u0000${d.sha256}`;
+                const seen = digests.get(key);
+                if (seen)
+                    seen.spawns += 1;
+                else
+                    digests.set(key, { name: d.name, source: d.source, sha256: d.sha256, spawns: 1 });
+            }
+        }
+        catch {
+            corrupt.push({ line: index + 1, text: raw.slice(0, 120) });
+        }
+    });
+    return {
+        exists: true,
+        records,
+        corrupt,
+        escalationAttempts,
+        definitions: [...digests.values()].sort((a, b) => a.name.localeCompare(b.name) || a.sha256.localeCompare(b.sha256)),
+        approvals: {
+            bySource,
+            distinctBySource: {
+                prompt: distinct.prompt.size,
+                session: distinct.session.size,
+                persisted: distinct.persisted.size,
+                inherited: distinct.inherited.size,
+            },
+            unattributed,
+            humanDenied,
+            humanDeniedPairs: deniedPairs.size,
+        },
+        ok: corrupt.length === 0,
+    };
+}
+//# sourceMappingURL=ledger-report.js.map

package/dist/ledger-report.js.map

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

package/dist/ledger.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Append-only grant ledger.
+ *
+ * Exists because pi-fabric's persisted execution trace records `args: {}` — it captures *that* a child
+ * ran, not *what it was authorised to do* (docs/probes/pi-fabric-eval probe 5). Without this record
+ * you cannot answer "what was this sub-agent permitted to do?" after the fact, which is the whole
+ * point of a governance layer.
+ *
+ * `denied` is the field that earns the file: an agent repeatedly requesting capabilities it does not
+ * hold is an escalation attempt, and it is invisible without a record.
+ *
+ * PRIVACY: capability ids, counts, and identifiers only. Never prompts, tool arguments, or results.
+ *
+ * ADR-0018 makes the boundary explicit rather than leaving it to be inferred, because a record now carries
+ * something about the child's instructions. **`definitionDigest` is an identifier**: a SHA-256 of an
+ * operator-authored file already committed to a repository, which names a version without reproducing it.
+ * **The task is not recorded, anywhere, ever** — it is assembled by the model from the parent's context and
+ * can carry anything the parent could see, so a ledger holding it would be a secrets sink. That half of
+ * "what was this child told to do?" is out of the ledger by decision, not by omission.
+ */
+import type { Capability, ResolveResult } from "./resolve.ts";
+import type { DefinitionDigest } from "./definitions.ts";
+import type { ApprovalScope, ApprovalSource } from "./approval.ts";
+import type { PromptOutcomeKind } from "./approval-prompt.ts";
+export interface GrantRecord {
+    ts: string;
+    parentId: string;
+    childId: string;
+    depth: number;
+    agentType?: string;
+    requested: Capability[];
+    parentGrant: Capability[];
+    effective: Capability[];
+    denied: Capability[];
+    clipped: Capability[];
+    gatedBlocked: Capability[];
+    /** True when the spawn was refused outright rather than narrowed. */
+    blocked: boolean;
+    /** Present when the spawn was refused, or when resolution failed. */
+    reason?: string;
+    /**
+     * Gated capabilities satisfied for this spawn.
+     *
+     * The ledger used to have ONE flavour of no. It now has three, and they call for different responses:
+     *  - `denied` non-empty            -> an agent asked for more than it holds. ESCALATION ATTEMPT.
+     *  - `humanDenied`                 -> a person was asked and said no. WORKING AS DESIGNED.
+     *  - `gatedBlocked` with no source -> nobody was there to ask. A background run hit a gate; the fix is
+     *                                     an operator pre-approving it, not an incident.
+     */
+    approved?: Capability[];
+    approvalSource?: ApprovalSource;
+    /**
+     * WHERE each approved capability's yes came from — one entry per capability (R-46).
+     *
+     * `approvalSource` above is a single scalar and was written for a set: gate `tool:bash` and `tool:write`,
+     * let a persisted entry cover `bash` while a human clicks *Allow once* for `write`, and the record read
+     * `approved: ["tool:bash","tool:write"], approvalSource: "prompt"` — **asserting a human was asked about
+     * `tool:bash`, which they were not.** The ledger's whole job is answering "did a human authorise this?",
+     * so over-claiming in that direction is the worst available failure.
+     *
+     * The scalar is kept and is now written **only when every approved capability shares one source**, so a
+     * reader of old and new lines alike can trust it; when sources differ it is omitted and this map carries
+     * the truth. Two fields, one of which is a safe summary of the other — not two competing answers.
+     */
+    approvalSources?: Record<Capability, ApprovalSource>;
+    /**
+     * How far each prompted capability's yes reaches (F5). Same shape and same reason as `approvalSources`:
+     * `approvalScope` below is a **derived summary**, emitted only when every prompted capability shares one
+     * scope. This field decides propagation — `inheritApprovals` drops `once` — so a scalar that described
+     * one capability while claiming to describe the set was not merely a reporting defect.
+     */
+    approvalScopes?: Record<Capability, ApprovalScope>;
+    /** Present only when the source was a live prompt, and only when one scope covers the whole set. */
+    approvalScope?: ApprovalScope;
+    /** A human was asked and declined. Distinct from `denied`, which is an escalation attempt. */
+    humanDenied?: boolean;
+    /**
+     * WHY a gate went unsatisfied, when the answer was not a yes.
+     *
+     * `PromptOutcomeKind` has five members and this record kept exactly one of them (`humanDenied`, from
+     * `declined`). So `no-ui`, `dismissed` (a timeout or an abort) and `error` produced **identical** records
+     * — `gatedBlocked` non-empty, no `approvalSource`, `blocked: true` — and the only thing separating them
+     * was free-text `reason`, written for a human at the call site. Given a failed run, *"was there an
+     * operator who timed out, or was there nobody to ask?"* was not answerable from any field, and the fix
+     * for each is different: one is a queue or a longer `PI_GRANTS_APPROVAL_TIMEOUT`, the other is an
+     * operator pre-approving.
+     *
+     * The discriminant was already computed and thrown away. ADR-0026 leans on this vocabulary being able to
+     * say *"nobody was there to ask"* and be believed, so it is recorded rather than inferred.
+     *
+     * **Privacy is unchanged**: this is a fixed five-member enum, not text — nothing model-authored, nothing
+     * a task could carry.
+     */
+    gateOutcome?: PromptOutcomeKind;
+    /**
+     * WHICH operator-authored instructions this child was given (ADR-0018).
+     *
+     * Identifies, never reproduces: matching digests prove two children ran the same text, and a digest that
+     * no longer matches the file proves the definition changed since. **It says nothing about whether those
+     * instructions were correct or whether the child obeyed them** — it identifies text, it does not evaluate
+     * it. Absent for a `tools:`-style delegation, which has no definition.
+     */
+    definitionDigest?: DefinitionDigest;
+}
+export interface LedgerOptions {
+    /** Path to the JSONL file. Parent directories are created on demand. */
+    path: string;
+    /**
+     * When true, a ledger write failure throws instead of being swallowed.
+     *
+     * Default is `true` and that is deliberate: for a security control, an unrecorded grant should fail
+     * closed. Set false only where the ledger is advisory.
+     */
+    strict?: boolean;
+}
+export declare function buildRecord(args: {
+    parentId: string;
+    childId: string;
+    depth: number;
+    agentType?: string;
+    requested: Capability[];
+    parentGrant: Capability[];
+    result: ResolveResult;
+    blocked: boolean;
+    reason?: string;
+    approved?: Capability[];
+    approvalSources?: Record<Capability, ApprovalSource>;
+    approvalScopes?: Record<Capability, ApprovalScope>;
+    humanDenied?: boolean;
+    gateOutcome?: PromptOutcomeKind;
+    definitionDigest?: DefinitionDigest;
+    now: Date;
+}): GrantRecord;
+export { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from "./file-lock.ts";
+export { verifyLedger, type LedgerReport } from "./ledger-report.ts";
+export declare function appendRecord(options: LedgerOptions, record: GrantRecord): Promise<void>;
+/** True when this record shows an agent asking for more than it holds. */
+export declare function isEscalationAttempt(record: GrantRecord): boolean;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

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

package/dist/ledger.js

@@ -0,0 +1,94 @@
+/**
+ * Append-only grant ledger.
+ *
+ * Exists because pi-fabric's persisted execution trace records `args: {}` — it captures *that* a child
+ * ran, not *what it was authorised to do* (docs/probes/pi-fabric-eval probe 5). Without this record
+ * you cannot answer "what was this sub-agent permitted to do?" after the fact, which is the whole
+ * point of a governance layer.
+ *
+ * `denied` is the field that earns the file: an agent repeatedly requesting capabilities it does not
+ * hold is an escalation attempt, and it is invisible without a record.
+ *
+ * PRIVACY: capability ids, counts, and identifiers only. Never prompts, tool arguments, or results.
+ *
+ * ADR-0018 makes the boundary explicit rather than leaving it to be inferred, because a record now carries
+ * something about the child's instructions. **`definitionDigest` is an identifier**: a SHA-256 of an
+ * operator-authored file already committed to a repository, which names a version without reproducing it.
+ * **The task is not recorded, anywhere, ever** — it is assembled by the model from the parent's context and
+ * can carry anything the parent could see, so a ledger holding it would be a secrets sink. That half of
+ * "what was this child told to do?" is out of the ledger by decision, not by omission.
+ */
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { withFileLock } from "./file-lock.js";
+import { dirname } from "node:path";
+import { DELEGATE_SUBJECT } from "./approval.js";
+export function buildRecord(args) {
+    // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
+    // than accepting it, so a call site cannot supply one that disagrees with the map beside it.
+    const sources = args.approvalSources ?? {};
+    const distinct = [...new Set(Object.values(sources))];
+    const scopes = args.approvalScopes ?? {};
+    const distinctScopes = [...new Set(Object.values(scopes))];
+    return {
+        ts: args.now.toISOString(),
+        parentId: args.parentId,
+        childId: args.childId,
+        depth: args.depth,
+        agentType: args.agentType,
+        requested: args.requested,
+        parentGrant: args.parentGrant,
+        effective: args.result.effective,
+        denied: args.result.denied,
+        clipped: args.result.clipped,
+        gatedBlocked: args.result.gatedBlocked,
+        blocked: args.blocked,
+        reason: args.reason,
+        ...(args.approved && args.approved.length > 0 ? { approved: args.approved } : {}),
+        ...(distinct.length === 1 ? { approvalSource: distinct[0] } : {}),
+        ...(Object.keys(sources).length > 0 ? { approvalSources: sources } : {}),
+        ...(distinctScopes.length === 1 ? { approvalScope: distinctScopes[0] } : {}),
+        ...(Object.keys(scopes).length > 0 ? { approvalScopes: scopes } : {}),
+        ...(args.humanDenied ? { humanDenied: true } : {}),
+        // Written whenever a gate was reached and not satisfied by a yes. `granted` is omitted deliberately —
+        // an approved spawn already says so through `approvalSources`, and a field that appears on every record
+        // stops being a signal.
+        ...(args.gateOutcome && args.gateOutcome !== "granted" ? { gateOutcome: args.gateOutcome } : {}),
+        ...(args.definitionDigest ? { definitionDigest: args.definitionDigest } : {}),
+    };
+}
+// R-49: the lock moved to `src/file-lock.ts` so the approvals store could use the SAME one rather than
+// grow a second copy. Re-exported because `./ledger` is a published subpath and these were part of it.
+export { LOCK_TIMEOUT_MS, STALE_LOCK_MS } from "./file-lock.js";
+// The reading half, split out under the file-size guard and re-exported so `./ledger` is unchanged for
+// anyone importing it. See `ledger-report.ts` for why the seam is where it is.
+export { verifyLedger } from "./ledger-report.js";
+/**
+ * Serialise appends across processes.
+ *
+ * **Why the ledger needs it.** For most of this package's life cardinality was bounded to one by `delegate`
+ * being blocking, so there was never a second writer. Fan-out removes that: `ENV_LEDGER` propagates to
+ * children, so a subtree can have many processes appending to one file.
+ *
+ * A ledger write that cannot take the lock **fails the delegation closed** — see `appendRecord`'s `strict`
+ * — because a child running with granted capabilities and no audit line is what the ledger exists to
+ * prevent. That is the opposite of what the approvals store does with the same lock, and deliberately so.
+ */
+const withLedgerLock = (path, write) => withFileLock(path, "grant ledger", write);
+export async function appendRecord(options, record) {
+    const line = `${JSON.stringify(record)}\n`;
+    try {
+        await mkdir(dirname(options.path), { recursive: true });
+        // O_APPEND alone is not enough once several processes write to one ledger — see `withLedgerLock`.
+        await withLedgerLock(options.path, () => appendFile(options.path, line, { encoding: "utf8", flag: "a" }));
+    }
+    catch (error) {
+        if (options.strict ?? true) {
+            throw new Error(`grant ledger write failed (failing closed): ${String(error)}`);
+        }
+    }
+}
+/** True when this record shows an agent asking for more than it holds. */
+export function isEscalationAttempt(record) {
+    return record.denied.length > 0;
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAiGjD,MAAM,UAAU,WAAW,CAAC,IAiB3B;IACC,sGAAsG;IACtG,6FAA6F;IAC7F,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,IAAI,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC;IACzC,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC3D,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;QAC1B,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS;QAChC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM;QAC1B,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO;QAC5B,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY;QACtC,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,GAAG,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,GAAG,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACjE,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxE,GAAG,CAAC,cAAc,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClD,sGAAsG;QACtG,wGAAwG;QACxG,wBAAwB;QACxB,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChG,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC9E,CAAC;AACJ,CAAC;AAED,uGAAuG;AACvG,uGAAuG;AACvG,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEhE,uGAAuG;AACvG,+EAA+E;AAC/E,OAAO,EAAE,YAAY,EAAqB,MAAM,oBAAoB,CAAC;AAErE;;;;;;;;;;GAUG;AACH,MAAM,cAAc,GAAG,CAAI,IAAY,EAAE,KAAuB,EAAc,EAAE,CAC9E,YAAY,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,CAAC;AAE5C,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAsB,EAAE,MAAmB;IAC5E,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC;IAC3C,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,kGAAkG;QAClG,MAAM,cAAc,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;IAC5G,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,+CAA+C,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAClF,CAAC;IACH,CAAC;AACH,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,mBAAmB,CAAC,MAAmB;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AAClC,CAAC"}

package/dist/pane-reaper.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Close herdr panes this process opened but never got to close.
+ *
+ * `runHerdrPane` closes its pane in a `finally`, which covers a thrown error and a timeout — **not the
+ * process being killed**. A pi session interrupted mid-fan-out left one pane per in-flight child, and
+ * `docs/probes/g16-herdr` records that an orphaned pane is not trivially closable afterwards.
+ *
+ * **Registered on `exit` only, deliberately — not on SIGINT or SIGTERM.** That is the part worth reading,
+ * because the obvious fix is the dangerous one. Adding a signal listener *suppresses Node's default
+ * termination*, so a library that adds one takes over an application-level decision it has no standing to
+ * make: pi uses SIGINT to interrupt a turn, and a listener here that re-raised would turn "cancel this
+ * delegation" into "exit pi". A governance package quietly changing the host's interrupt semantics is a
+ * worse defect than the leak it fixes, and it would land on **every** session rather than the opt-in ones.
+ *
+ * So the coverage is exact and stated rather than implied:
+ *
+ *  - **Covered:** normal exit, `process.exit()`, an uncaught exception that unwinds to the default handler.
+ *  - **NOT covered:** SIGKILL, and SIGTERM/SIGINT where nothing else in the process has installed a
+ *    listener. Node terminates without running `exit` handlers in those cases, by design. A pane can still
+ *    be orphaned there, and `herdr tab close <id>` is the manual remedy.
+ *
+ * Everything here is **synchronous**, because an `exit` handler is: a promise scheduled there never runs.
+ */
+export interface OpenPane {
+    /** herdr tab id — what `tab close` takes. */
+    tab: string;
+    /** Agent name, so the agent is stopped before its tab goes away. */
+    name: string;
+    /** Staged system-prompt directory, removed with the pane it belonged to. */
+    promptDir?: string;
+}
+/** A run has opened a pane. Idempotent per tab, and installs the exit hook on first use only. */
+export declare function trackPane(pane: OpenPane): void;
+/** A run closed its own pane the normal way. */
+export declare function untrackPane(tab: string): void;
+/** How many panes are currently outstanding — for tests and for `/grants`. */
+export declare function openPaneCount(): number;
+/**
+ * Close every outstanding pane and return the tab ids closed.
+ *
+ * Exported and parameterised so it can be tested without herdr installed: the exit hook is unreachable from
+ * a test (registering a real `exit` handler would run during the test runner's own shutdown), so the hook is
+ * one line and *this* is where the behaviour lives.
+ *
+ * Failures are swallowed per pane rather than per call — one pane herdr will not close must not strand the
+ * other seven, and nothing at exit has anywhere to report to anyway.
+ */
+export declare function reapOpenPanes(syncExec?: (args: string[]) => void, now?: () => number): string[];
+//# sourceMappingURL=pane-reaper.d.ts.map

package/dist/pane-reaper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pane-reaper.d.ts","sourceRoot":"","sources":["../src/pane-reaper.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAKH,MAAM,WAAW,QAAQ;IACvB,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAeD,iGAAiG;AACjG,wBAAgB,SAAS,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAO9C;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAyBD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAsB,EAAE,GAAG,eAAW,GAAG,MAAM,EAAE,CA6B5G"}