pi-daddy 0.17.0 → 0.18.0

package/dist/lease-record.js

@@ -0,0 +1,52 @@
+/**
+ * The lease's RECORD: what a workspace lease writes down about who holds it and how they let it go.
+ *
+ * Split from `./workspace-lease.ts` to stay under the 400-line module ceiling, along the seam this
+ * review round kept finding defects on — absent vs unreadable metadata, a swallowed handover write, a
+ * successor's token — all of which are about what the record SAYS rather than about the kernel lock.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+export function leasePaths(leaseDir, root) {
+    // Canonical root, never caller-chosen workspace ID: aliases for one worktree must contend.
+    const key = createHash("sha256").update(root, "utf8").digest("hex");
+    return {
+        lock: join(leaseDir, `${key}.lock`),
+        metadata: join(leaseDir, `${key}.json`),
+        marker: join(leaseDir, `${key}.close-failed.json`),
+    };
+}
+export async function atomicMetadata(path, value) {
+    const temp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await writeFile(temp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", flag: "wx", mode: 0o600 });
+    await rename(temp, path);
+}
+/**
+ * `null` means no prior owner was recorded. `"malformed"` means a record exists and cannot be read,
+ * which is strictly LESS evidence than a readable "active" one and must never read as a clean handover
+ * (R-100). Absent and unreadable are different facts; conflating them silently erases a real recovery.
+ */
+export async function readMetadata(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch (error) {
+        return error?.code === "ENOENT" ? null : "malformed";
+    }
+    try {
+        const value = JSON.parse(raw);
+        if (value?.version !== 1)
+            return "malformed";
+        if (value.state !== "active" && value.state !== "released")
+            return "malformed";
+        if (typeof value.token !== "string" || !value.token)
+            return "malformed";
+        return value;
+    }
+    catch {
+        return "malformed";
+    }
+}
+//# sourceMappingURL=lease-record.js.map

package/dist/lease-record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-record.js","sourceRoot":"","sources":["../src/lease-record.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAwEjC,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,IAAY;IACvD,2FAA2F;IAC3F,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpE,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QACnC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC;QACvC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,GAAG,oBAAoB,CAAC;KACnD,CAAC;AACJ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,KAAoB;IACrE,MAAM,IAAI,GAAG,GAAG,IAAI,IAAI,OAAO,CAAC,GAAG,IAAI,UAAU,EAAE,MAAM,CAAC;IAC1D,MAAM,SAAS,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAC5G,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY;IAC7C,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAQ,KAA+B,EAAE,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC;IAClF,CAAC;IACD,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA2B,CAAC;QACxD,IAAI,KAAK,EAAE,OAAO,KAAK,CAAC;YAAE,OAAO,WAAW,CAAC;QAC7C,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,KAAK,KAAK,UAAU;YAAE,OAAO,WAAW,CAAC;QAC/E,IAAI,OAAO,KAAK,CAAC,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK;YAAE,OAAO,WAAW,CAAC;QACxE,OAAO,KAAsB,CAAC;IAChC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC;IACrB,CAAC;AACH,CAAC"}

package/dist/ledger-events.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The v2 runtime-event half of the ledger: workspace leases, child lifecycle and check receipts, with
+ * their builders. Split out of `./ledger.ts` only to stay under the 400-line module ceiling this
+ * project enforces mechanically; `./ledger.ts` re-exports everything here, so "the ledger module"
+ * remains one import.
+ */
+import { LEDGER_VERSION, type LedgerEventBase, type GrantRecord } from "./ledger.ts";
+import type { ExecutorKind } from "./executor.ts";
+import type { CorrelationMetadata } from "./correlation.ts";
+import type { StructuredRefusal } from "./refusals.ts";
+/**
+ * `released` is a handover this owner performed. FOUR members were added by the 0.18.0 review pass, and
+ * they were not all previously recorded the same way — `uncontended` was recorded as an *acquisition*, and
+ * `lost` was recorded as nothing at all, because the old `release()` threw before the append ran:
+ *   `lost`     the kernel lock went away under a live governed writer — NOT the same fact as a user
+ *              cancelling, which is what it used to be indistinguishable from (R-103);
+ *   `retained` the lease was deliberately kept because a herdr writer tab would not close, so the
+ *              successor's `recovered: true` would otherwise blame a healthy path (R-104);
+ *   `uncontended` a read lease took no kernel lock at all, so counting it as an acquisition
+ *              overstated how many exclusions the kernel actually performed (R-105).
+ */
+export type WorkspaceLeaseOutcome = "acquired" | "uncontended" | "refused" | "released" | "released-unrecorded" | "lost" | "retained" | "timeout" | "recovered";
+export interface WorkspaceLeaseEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "workspace_lease";
+    childId: string;
+    workspaceId: string;
+    root: string;
+    access: "read" | "write";
+    outcome: WorkspaceLeaseOutcome;
+    /** `"unknown"` when the prior owner's record was unreadable — not evidence of a clean handover. */
+    recovered?: boolean | "unknown";
+    releaseReason?: string;
+    refusal?: StructuredRefusal;
+}
+export interface ChildLifecycleEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "child_lifecycle";
+    childId: string;
+    state: "starting" | "completed" | "failed";
+    executor: ExecutorKind;
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    truncated?: boolean;
+    reason?: string;
+}
+export interface CheckReceiptLedgerEvent extends LedgerEventBase {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "check_receipt";
+    childId: string;
+    receiptId: string;
+    workspaceId: string;
+    checkId: string;
+    treeSha: string;
+}
+export type RuntimeLedgerEvent = (GrantRecord & {
+    ledgerVersion: typeof LEDGER_VERSION;
+    event: "capability_decision";
+}) | WorkspaceLeaseEvent | ChildLifecycleEvent | CheckReceiptLedgerEvent;
+export declare function buildWorkspaceLeaseEvent(args: {
+    childId: string;
+    workspaceId: string;
+    root: string;
+    access: "read" | "write";
+    outcome: WorkspaceLeaseOutcome;
+    recovered?: boolean | "unknown";
+    releaseReason?: string;
+    refusal?: StructuredRefusal;
+    correlation?: CorrelationMetadata;
+    now: Date;
+}): WorkspaceLeaseEvent;
+export declare function buildChildLifecycleEvent(args: {
+    childId: string;
+    state: "starting" | "completed" | "failed";
+    executor: ExecutorKind;
+    exitCode?: number | null;
+    signal?: NodeJS.Signals | null;
+    timedOut?: boolean;
+    aborted?: boolean;
+    truncated?: boolean;
+    reason?: string;
+    correlation?: CorrelationMetadata;
+    now: Date;
+}): ChildLifecycleEvent;
+//# sourceMappingURL=ledger-events.d.ts.map

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

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

package/dist/ledger-events.js

@@ -0,0 +1,45 @@
+/**
+ * The v2 runtime-event half of the ledger: workspace leases, child lifecycle and check receipts, with
+ * their builders. Split out of `./ledger.ts` only to stay under the 400-line module ceiling this
+ * project enforces mechanically; `./ledger.ts` re-exports everything here, so "the ledger module"
+ * remains one import.
+ */
+import { LEDGER_VERSION } from "./ledger.js";
+export function buildWorkspaceLeaseEvent(args) {
+    return {
+        ledgerVersion: LEDGER_VERSION,
+        event: "workspace_lease",
+        ts: args.now.toISOString(),
+        childId: args.childId,
+        workspaceId: args.workspaceId,
+        root: args.root,
+        access: args.access,
+        outcome: args.outcome,
+        // `!== undefined`, not truthiness. `recovered: false` — a POSITIVE assertion that the predecessor
+        // handed over cleanly — was dropped while the truthy `"unknown"` survived, so absence meant both
+        // "clean" and "never supplied". R-100's whole argument is that absence of evidence is not evidence,
+        // and this was the one line discarding the evidence.
+        ...(args.recovered !== undefined ? { recovered: args.recovered } : {}),
+        ...(args.releaseReason ? { releaseReason: args.releaseReason } : {}),
+        ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
+        ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+    };
+}
+export function buildChildLifecycleEvent(args) {
+    return {
+        ledgerVersion: LEDGER_VERSION,
+        event: "child_lifecycle",
+        ts: args.now.toISOString(),
+        childId: args.childId,
+        state: args.state,
+        executor: args.executor,
+        ...(args.exitCode !== undefined ? { exitCode: args.exitCode } : {}),
+        ...(args.signal !== undefined ? { signal: args.signal } : {}),
+        ...(args.timedOut ? { timedOut: true } : {}),
+        ...(args.aborted ? { aborted: true } : {}),
+        ...(args.truncated ? { truncated: true } : {}),
+        ...(args.reason ? { reason: args.reason } : {}),
+        ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+    };
+}
+//# sourceMappingURL=ledger-events.js.map

package/dist/ledger-events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger-events.js","sourceRoot":"","sources":["../src/ledger-events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAA0C,MAAM,aAAa,CAAC;AAuErF,MAAM,UAAU,wBAAwB,CAAC,IAWxC;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,kGAAkG;QAClG,iGAAiG;QACjG,oGAAoG;QACpG,qDAAqD;QACrD,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,IAYxC;IACC,OAAO;QACL,aAAa,EAAE,cAAc;QAC7B,KAAK,EAAE,iBAAiB;QACxB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE;QAC1B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5C,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/C,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChF,CAAC;AACJ,CAAC"}

package/dist/ledger-report.d.ts

@@ -14,8 +14,26 @@ 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. */
+    /** Capability-decision records (legacy or v2). */
     records: number;
+    /** Every parsed ledger event, including lifecycle and lease events. */
+    events: number;
+    workspaceLeases: {
+        acquired: number;
+        uncontended: number;
+        refused: number;
+        released: number;
+        releasedUnrecorded: number;
+        lost: number;
+        retained: number;
+        timeout: number;
+        recovered: number;
+    };
+    lifecycle: {
+        starting: number;
+        completed: number;
+        failed: number;
+    };
     /** Lines that did not, with 1-based line numbers so the report is actionable. */
     corrupt: Array<{
         line: number;
@@ -109,16 +127,5 @@ export interface LedgerReport {
     };
     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

@@ -1 +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,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D;;;;;;;;;;;;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,CAiItE"}
+{"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;AAKpD,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,MAAM,EAAE,OAAO,CAAC;IAChB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,MAAM,EAAE,MAAM,CAAC;IACf,eAAe,EAAE;QACf,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QACzE,kBAAkB,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;KAChG,CAAC;IACF,SAAS,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnE,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,SAAS,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D;;;;;;;;;;;;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;AAkDD,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA4KtE"}

package/dist/ledger-report.js

@@ -24,6 +24,39 @@ import { isEscalationAttempt } from "./ledger.js";
  * 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.
  */
+// Keyed by the UNION, not by `string`. Typed loosely, adding a `WorkspaceLeaseOutcome` member without a
+// counter compiled fine and then made `verifyLedger` file the package's own valid event as CORRUPTION —
+// the worst available outcome for an integrity signal, since real damage becomes noise.
+const LEASE_OUTCOME_COUNTERS = {
+    acquired: "acquired",
+    uncontended: "uncontended",
+    refused: "refused",
+    released: "released",
+    "released-unrecorded": "releasedUnrecorded",
+    lost: "lost",
+    retained: "retained",
+    timeout: "timeout",
+    recovered: "recovered",
+};
+function validV2Base(event) {
+    return event.ledgerVersion === 2 && typeof event.ts === "string";
+}
+function requireV2(event, fields) {
+    if (!validV2Base(event) || fields.some((field) => typeof event[field] !== "string" || event[field] === "")) {
+        throw new Error("invalid versioned ledger event");
+    }
+}
+function requireCapabilityDecision(event) {
+    requireV2(event, ["parentId", "childId", "executor", "taskDigest"]);
+    for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
+        if (!Array.isArray(event[field]) || !event[field].every((value) => typeof value === "string")) {
+            throw new Error("invalid capability decision arrays");
+        }
+    }
+    if (!Number.isInteger(event.depth) || typeof event.blocked !== "boolean" || !/^[a-f0-9]{64}$/i.test(String(event.taskDigest))) {
+        throw new Error("invalid capability decision identity");
+    }
+}
 export async function verifyLedger(path) {
     let text;
     try {
@@ -34,6 +67,9 @@ export async function verifyLedger(path) {
             return {
                 exists: false,
                 records: 0,
+                events: 0,
+                workspaceLeases: { acquired: 0, uncontended: 0, refused: 0, released: 0, releasedUnrecorded: 0, lost: 0, retained: 0, timeout: 0, recovered: 0 },
+                lifecycle: { starting: 0, completed: 0, failed: 0 },
                 corrupt: [],
                 escalationAttempts: 0,
                 executors: { herdr: 0, process: 0, unknown: 0 },
@@ -54,6 +90,9 @@ export async function verifyLedger(path) {
     // 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 events = 0;
+    const workspaceLeases = { acquired: 0, uncontended: 0, refused: 0, released: 0, releasedUnrecorded: 0, lost: 0, retained: 0, timeout: 0, recovered: 0 };
+    const lifecycle = { starting: 0, completed: 0, failed: 0 };
     let escalationAttempts = 0;
     const executors = { herdr: 0, process: 0, unknown: 0 };
     const bySource = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
@@ -73,10 +112,48 @@ export async function verifyLedger(path) {
         if (raw.trim().length === 0)
             return;
         try {
-            const parsed = JSON.parse(raw);
+            const event = JSON.parse(raw);
+            if (event.ledgerVersion !== undefined && event.event === undefined) {
+                throw new Error("versioned ledger line has no event discriminator");
+            }
+            if (event.event === "workspace_lease") {
+                requireV2(event, ["childId", "workspaceId", "root", "access"]);
+                const outcome = typeof event.outcome === "string" ? event.outcome : "";
+                // Explicit map, not a name match: the ledger's outcome vocabulary and these counter names are
+                // allowed to differ, and a valid event must never be counted as corruption because a counter
+                // happens to be spelled differently.
+                const counter = Object.hasOwn(LEASE_OUTCOME_COUNTERS, outcome)
+                    ? LEASE_OUTCOME_COUNTERS[outcome]
+                    : undefined;
+                if (!counter)
+                    throw new Error("invalid workspace lease event");
+                workspaceLeases[counter] += 1;
+                events += 1;
+                return;
+            }
+            if (event.event === "child_lifecycle") {
+                requireV2(event, ["childId", "executor"]);
+                const state = typeof event.state === "string" ? event.state : "";
+                if (!Object.hasOwn(lifecycle, state))
+                    throw new Error("invalid child lifecycle event");
+                lifecycle[state] += 1;
+                events += 1;
+                return;
+            }
+            if (event.event === "check_receipt") {
+                requireV2(event, ["childId", "receiptId", "workspaceId", "checkId", "treeSha"]);
+                events += 1;
+                return;
+            }
+            if (event.event !== undefined && event.event !== "capability_decision")
+                throw new Error("unknown ledger event");
+            const parsed = event;
+            if (event.event === "capability_decision")
+                requireCapabilityDecision(event);
             if (!Array.isArray(parsed.denied))
                 throw new Error("not a grant record");
             records += 1;
+            events += 1;
             if (isEscalationAttempt(parsed))
                 escalationAttempts += 1;
             const executor = parsed.executor;
@@ -145,6 +222,9 @@ export async function verifyLedger(path) {
     return {
         exists: true,
         records,
+        events,
+        workspaceLeases,
+        lifecycle,
         corrupt,
         escalationAttempts,
         executors,

package/dist/ledger-report.js.map

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

package/dist/ledger.d.ts

@@ -23,8 +23,25 @@ import type { ExecutorKind } from "./executor.ts";
 import type { DefinitionDigest } from "./definitions.ts";
 import type { ApprovalScope, ApprovalSource } from "./approval.ts";
 import type { PromptOutcomeKind } from "./approval-prompt.ts";
-export interface GrantRecord {
+import type { CorrelationMetadata } from "./correlation.ts";
+import type { StructuredRefusal } from "./refusals.ts";
+import type { RuntimeLedgerEvent } from "./ledger-events.ts";
+export declare const LEDGER_VERSION: 2;
+export interface LedgerEventBase {
+    /** Optional only on the legacy-compatible `GrantRecord` public type; every v2 event builder writes it. */
+    ledgerVersion?: typeof LEDGER_VERSION;
+    event?: "capability_decision" | "workspace_lease" | "child_lifecycle" | "check_receipt";
     ts: string;
+    childId?: string;
+    correlation?: CorrelationMetadata;
+}
+export interface GrantRecord extends LedgerEventBase {
+    /**
+     * Present only when a trusted `taskDigest` was supplied — that is what makes a line v2. `buildRecord`
+     * does NOT always emit it, and the comment here used to say it did while the emission site 200 lines
+     * down said the opposite. Two comments asserting contradictory facts about one field is R-28's shape.
+     */
+    event?: "capability_decision";
     parentId: string;
     childId: string;
     depth: number;
@@ -71,6 +88,13 @@ export interface GrantRecord {
      * one capability while claiming to describe the set was not merely a reporting defect.
      */
     approvalScopes?: Record<Capability, ApprovalScope>;
+    /** Persisted approval expiry, by capability. Session-scoped approvals have no wall-clock expiry. */
+    approvalExpiresAt?: Record<Capability, string>;
+    /** Count bounds where one exists. A consumed `once` approval records `{max:1, remaining:0}`. */
+    approvalUses?: Record<Capability, {
+        max: number;
+        remaining: number;
+    }>;
     /** 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. */
@@ -128,6 +152,10 @@ export interface GrantRecord {
      * `definitionDigest` names its instructions, and neither says where the TASK came from.
      */
     taskFrom?: string;
+    /** Trusted SHA-256 of the exact task; task text remains forbidden (ADR-0034). */
+    taskDigest?: string;
+    /** Stable machine-readable refusal accompanying `reason`. */
+    refusal?: StructuredRefusal;
 }
 export interface LedgerOptions {
     /** Path to the JSONL file. Parent directories are created on demand. */
@@ -139,6 +167,11 @@ export interface LedgerOptions {
      * closed. Set false only where the ledger is advisory.
      */
     strict?: boolean;
+    /**
+     * Called when a NON-strict append failed. Required in spirit rather than in types: a caller that opts
+     * out of failing closed still has to say something, or the ledger silently develops holes.
+     */
+    onFailure?: (error: unknown) => void;
 }
 export declare function buildRecord(args: {
     parentId: string;
@@ -153,6 +186,11 @@ export declare function buildRecord(args: {
     approved?: Capability[];
     approvalSources?: Record<Capability, ApprovalSource>;
     approvalScopes?: Record<Capability, ApprovalScope>;
+    approvalExpiresAt?: Record<Capability, string>;
+    approvalUses?: Record<Capability, {
+        max: number;
+        remaining: number;
+    }>;
     humanDenied?: boolean;
     gateOutcome?: PromptOutcomeKind;
     definitionDigest?: DefinitionDigest;
@@ -160,11 +198,16 @@ export declare function buildRecord(args: {
     executor: ExecutorKind;
     /** The child whose output composed this task (ADR-0033). Absent for anything but a chain step. */
     taskFrom?: string;
+    taskDigest?: string;
+    correlation?: CorrelationMetadata;
+    refusal?: StructuredRefusal;
     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 appendLedgerEvent(options: LedgerOptions, event: RuntimeLedgerEvent | GrantRecord): Promise<void>;
 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;
+export { buildChildLifecycleEvent, buildWorkspaceLeaseEvent, type ChildLifecycleEvent, type CheckReceiptLedgerEvent, type RuntimeLedgerEvent, type WorkspaceLeaseEvent, type WorkspaceLeaseOutcome, } from "./ledger-events.ts";
 //# sourceMappingURL=ledger.d.ts.map

package/dist/ledger.d.ts.map

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

package/dist/ledger.js

@@ -22,6 +22,7 @@ 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 const LEDGER_VERSION = 2;
 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.
@@ -30,6 +31,9 @@ export function buildRecord(args) {
     const scopes = args.approvalScopes ?? {};
     const distinctScopes = [...new Set(Object.values(scopes))];
     return {
+        // A trusted task digest is what distinguishes a v2 capability event from the legacy construction API.
+        // Production delegation always supplies it; old TypeScript callers remain able to append legacy lines.
+        ...(args.taskDigest ? { ledgerVersion: LEDGER_VERSION, event: "capability_decision" } : {}),
         ts: args.now.toISOString(),
         parentId: args.parentId,
         childId: args.childId,
@@ -37,6 +41,9 @@ export function buildRecord(args) {
         agentType: args.agentType,
         executor: args.executor,
         ...(args.taskFrom ? { taskFrom: args.taskFrom } : {}),
+        ...(args.taskDigest ? { taskDigest: args.taskDigest } : {}),
+        ...(args.correlation ? { correlation: structuredClone(args.correlation) } : {}),
+        ...(args.refusal ? { refusal: structuredClone(args.refusal) } : {}),
         requested: args.requested,
         parentGrant: args.parentGrant,
         effective: args.result.effective,
@@ -50,6 +57,10 @@ export function buildRecord(args) {
         ...(Object.keys(sources).length > 0 ? { approvalSources: sources } : {}),
         ...(distinctScopes.length === 1 ? { approvalScope: distinctScopes[0] } : {}),
         ...(Object.keys(scopes).length > 0 ? { approvalScopes: scopes } : {}),
+        ...(args.approvalExpiresAt && Object.keys(args.approvalExpiresAt).length > 0
+            ? { approvalExpiresAt: args.approvalExpiresAt }
+            : {}),
+        ...(args.approvalUses && Object.keys(args.approvalUses).length > 0 ? { approvalUses: args.approvalUses } : {}),
         ...(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
@@ -76,8 +87,8 @@ export { verifyLedger } from "./ledger-report.js";
  * 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`;
+export async function appendLedgerEvent(options, event) {
+    const line = `${JSON.stringify(event)}\n`;
     try {
         await mkdir(dirname(options.path), { recursive: true });
         // O_APPEND alone is not enough once several processes write to one ledger — see `withLedgerLock`.
@@ -87,10 +98,17 @@ export async function appendRecord(options, record) {
         if (options.strict ?? true) {
             throw new Error(`grant ledger write failed (failing closed): ${String(error)}`);
         }
+        // A non-strict append is a deliberate choice not to fail closed. It is NOT a choice to be silent:
+        // a silent safe-mode is as confusing as a silent unsafe one, so the caller is always told.
+        options.onFailure?.(error);
     }
 }
+export async function appendRecord(options, record) {
+    return appendLedgerEvent(options, record);
+}
 /** True when this record shows an agent asking for more than it holds. */
 export function isEscalationAttempt(record) {
     return record.denied.length > 0;
 }
+export { buildChildLifecycleEvent, buildWorkspaceLeaseEvent, } from "./ledger-events.js";
 //# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/refusals.d.ts

@@ -0,0 +1,16 @@
+export declare const REFUSAL_CODES: readonly ["CAPABILITY_ESCALATION", "DEFINITION_NOT_AUTHORIZED", "UNDECLARED_TOOLS", "UNKNOWN_TOOL", "GATED_UNAPPROVED", "APPROVAL_EXPIRED", "APPROVAL_SCOPE_MISMATCH", "APPROVAL_FLOW_FAILED", "DEPTH_EXCEEDED", "FANOUT_EXCEEDED", "EXECUTOR_UNAVAILABLE", "CHILD_TIMED_OUT", "CHILD_CANCELLED", "CHILD_EXIT_NONZERO", "TASK_MISSING", "UNKNOWN_DEFINITION", "CEILING_PATTERNS_UNRESOLVED", "NARROWING_VIOLATED", "DEFINITION_UNREADABLE", "CORRELATION_TOO_LARGE", "CORRELATION_INVALID", "LEDGER_WRITE_FAILED", "FANOUT_FAILED", "WORKSPACE_NOT_REGISTERED", "WORKSPACE_WRITE_CONFLICT", "WORKSPACE_LEASE_STALE", "CHECK_NOT_CONFIGURED", "CHECK_CONFIGURATION_INVALID", "CHECK_IDENTITY_UNAVAILABLE", "CHECK_IDENTITY_MISMATCH"];
+export type RefusalCode = (typeof REFUSAL_CODES)[number];
+export interface StructuredRefusal {
+    code: RefusalCode;
+    /** Existing actionable diagnostic. Codes accompany rather than replace it. */
+    message: string;
+    details?: Record<string, string | number | boolean | null>;
+}
+export declare function refusal(code: RefusalCode, message: string, details?: StructuredRefusal["details"]): StructuredRefusal;
+/** Error shape for API callers. pi-facing tools still throw, as pi requires, while retaining a stable code. */
+export declare class GovernanceRefusal extends Error {
+    readonly code: RefusalCode;
+    readonly details?: StructuredRefusal["details"];
+    constructor(value: StructuredRefusal);
+}
+//# sourceMappingURL=refusals.d.ts.map

package/dist/refusals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusals.d.ts","sourceRoot":"","sources":["../src/refusals.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,aAAa,ssBAmChB,CAAC;AAEX,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,WAAW,CAAC;IAClB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;CAC5D;AAED,wBAAgB,OAAO,CACrB,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,GACrC,iBAAiB,CAEnB;AAED,+GAA+G;AAC/G,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;gBAEpC,KAAK,EAAE,iBAAiB;CAMrC"}