pi-daddy 0.17.0 → 0.18.0

package/src/lease-record.ts

@@ -0,0 +1,119 @@
+/**
+ * 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";
+import type { ValidatedWorkspace, WorkspaceAccess } from "./workspace.ts";
+
+export interface LeaseMetadata {
+  version: 1;
+  state: "active" | "released";
+  token: string;
+  owner_id: string;
+  workspace_id: string;
+  root: string;
+  pid: number;
+  acquired_at: string;
+  released_at?: string;
+  release_reason?: string;
+}
+
+export interface WorkspaceLease {
+  workspace: ValidatedWorkspace;
+  access: WorkspaceAccess;
+  ownerId: string;
+  /**
+   * `true` only when the kernel lock was free but metadata said the prior owner never released.
+   * `"unknown"` when the prior owner's record could not be read at all — that is not evidence of a
+   * clean handover and must not be recorded as one (R-100).
+   */
+  recovered: boolean | "unknown";
+  /** Attach the governed resource so parent death cleans it before the kernel lock is released. */
+  attachProcess(pid: number): void;
+  attachHerdrTab(tabId: string): void;
+  /** Resolves only when the kernel-lock helper exits before explicit release. */
+  lost: Promise<Error>;
+  /**
+   * NEVER throws. A cleanup function that can throw destroys its caller's return value — a completed
+   * child's entire output was discarded this way (R-99) — so the outcome is a VALUE the caller records:
+   *   `"released"`            the kernel lock was handed back and the handover recorded;
+   *   `"released-unrecorded"` the lock was handed back but the record failed, so the NEXT owner will
+   *                           report a recovery that did not happen unless this is ledgered;
+   *   `"lost"`                the helper was already gone, so this owner never released anything.
+   */
+  release(reason?: string): Promise<LeaseReleaseOutcome>;
+  /**
+   * Record that this lease is being kept deliberately, WITHOUT releasing the kernel lock.
+   *
+   * Needed because a retained lease never calls `release()`, so the metadata stays `state: "active"` and
+   * whoever acquires next reports `recovered: true` — blaming a crash on a known-good path.
+   */
+  markRetained(reason?: string): Promise<void>;
+  /** Reads the give-up marker the helper leaves when it could not close a herdr writer tab. */
+  readCloseFailure(): Promise<{ reason: string; herdr_tab?: string } | null>;
+}
+
+/**
+ * What a release actually did. Five members rather than three, because the first version conflated facts
+ * that call for different responses — and one of them is an alarm:
+ *   `released`             the lock went back and THIS owner wrote its own handover;
+ *   `released-unrecorded`  the lock went back and the record does not say so, so the next owner will report
+ *                          a recovery that never happened unless the caller ledgers this. **The alarm.**
+ *   `released-superseded`  the lock went back and a successor already owns the metadata, so we correctly
+ *                          declined to overwrite it. Healthy, and previously indistinguishable from the
+ *                          alarm above;
+ *   `not-held`             a read lease, which never took a kernel lock — recording it as `released`
+ *                          overstated how many handovers the kernel performed, which is R-105 on the
+ *                          release side of the same defect;
+ *   `lost`                 the helper was already gone; this owner released nothing.
+ */
+export type LeaseReleaseOutcome =
+  | "released"
+  | "released-unrecorded"
+  | "released-superseded"
+  | "not-held"
+  | "lost";
+
+export function leasePaths(leaseDir: string, root: string) {
+  // 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: string, value: LeaseMetadata): Promise<void> {
+  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: string): Promise<LeaseMetadata | null | "malformed"> {
+  let raw: string;
+  try {
+    raw = await readFile(path, "utf8");
+  } catch (error) {
+    return (error as NodeJS.ErrnoException)?.code === "ENOENT" ? null : "malformed";
+  }
+  try {
+    const value = JSON.parse(raw) as Partial<LeaseMetadata>;
+    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 as LeaseMetadata;
+  } catch {
+    return "malformed";
+  }
+}

package/src/ledger-events.ts

@@ -0,0 +1,138 @@
+/**
+ * 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 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 {
+  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: {
+  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 {
+  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) } : {}),
+  };
+}

package/src/ledger-report.ts

@@ -17,12 +17,20 @@ import { DELEGATE_SUBJECT } from "./approval.ts";
 import type { ApprovalSource } from "./approval.ts";
 import type { GrantRecord } from "./ledger.ts";
 import { isEscalationAttempt } from "./ledger.ts";
+import type { WorkspaceLeaseOutcome } from "./ledger-events.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; text: string }>;
   /** Records where an agent asked for more than it held — ADR-0008's designated signal. */
@@ -116,6 +124,43 @@ export interface LedgerReport {
  * 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: Record<WorkspaceLeaseOutcome, keyof LedgerReport["workspaceLeases"]> = {
+  acquired: "acquired",
+  uncontended: "uncontended",
+  refused: "refused",
+  released: "released",
+  "released-unrecorded": "releasedUnrecorded",
+  lost: "lost",
+  retained: "retained",
+  timeout: "timeout",
+  recovered: "recovered",
+};
+
+function validV2Base(event: Record<string, unknown>): boolean {
+  return event.ledgerVersion === 2 && typeof event.ts === "string";
+}
+
+function requireV2(event: Record<string, unknown>, fields: string[]): void {
+  if (!validV2Base(event) || fields.some((field) => typeof event[field] !== "string" || event[field] === "")) {
+    throw new Error("invalid versioned ledger event");
+  }
+}
+
+function requireCapabilityDecision(event: Record<string, unknown>): void {
+  requireV2(event, ["parentId", "childId", "executor", "taskDigest"]);
+  for (const field of ["requested", "parentGrant", "effective", "denied", "clipped", "gatedBlocked"]) {
+    if (!Array.isArray(event[field]) || !(event[field] as unknown[]).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: string): Promise<LedgerReport> {
   let text: string;
   try {
@@ -125,6 +170,9 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
       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 },
@@ -146,6 +194,9 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
   // Keyed by name+digest: one name with two entries is the signal that the definition changed mid-ledger.
   const digests = new Map<string, { name: string; source: string; sha256: string; spawns: number }>();
   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: Record<ApprovalSource, number> = { prompt: 0, session: 0, persisted: 0, inherited: 0 };
@@ -165,9 +216,43 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
     // 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) as GrantRecord;
+      const event = JSON.parse(raw) as Record<string, unknown>;
+      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 as WorkspaceLeaseOutcome]
+          : 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 as keyof typeof lifecycle] += 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 as unknown as GrantRecord;
+      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 as { executor?: unknown }).executor;
       if (executor === "herdr") executors.herdr += 1;
@@ -227,6 +312,9 @@ export async function verifyLedger(path: string): Promise<LedgerReport> {
   return {
     exists: true,
     records,
+    events,
+    workspaceLeases,
+    lifecycle,
     corrupt,
     escalationAttempts,
     executors,

package/src/ledger.ts

@@ -28,9 +28,29 @@ import type { DefinitionDigest } from "./definitions.ts";
 import { DELEGATE_SUBJECT } from "./approval.ts";
 import type { ApprovalScope, ApprovalSource } from "./approval.ts";
 import type { PromptOutcomeKind } from "./approval-prompt.ts";
+import type { CorrelationMetadata } from "./correlation.ts";
+import type { StructuredRefusal } from "./refusals.ts";
+// Type-only, so the cycle with ./ledger-events.ts is erased at runtime.
+import type { RuntimeLedgerEvent } from "./ledger-events.ts";
 
-export interface GrantRecord {
+export const LEDGER_VERSION = 2 as const;
+
+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;
@@ -77,6 +97,10 @@ 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. */
@@ -134,6 +158,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 {
@@ -146,6 +174,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 function buildRecord(args: {
@@ -161,6 +194,8 @@ export 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;
@@ -168,6 +203,9 @@ export 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 {
   // R-46: the scalar is a SUMMARY, emitted only when it cannot mislead. `buildRecord` derives it rather
@@ -177,6 +215,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" as const } : {}),
     ts: args.now.toISOString(),
     parentId: args.parentId,
     childId: args.childId,
@@ -184,6 +225,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,
@@ -197,6 +241,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
@@ -228,8 +276,8 @@ export { verifyLedger, type LedgerReport } from "./ledger-report.ts";
 const withLedgerLock = <T>(path: string, write: () => Promise<T>): Promise<T> =>
   withFileLock(path, "grant ledger", write);
 
-export async function appendRecord(options: LedgerOptions, record: GrantRecord): Promise<void> {
-  const line = `${JSON.stringify(record)}\n`;
+export async function appendLedgerEvent(options: LedgerOptions, event: RuntimeLedgerEvent | GrantRecord): Promise<void> {
+  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`.
@@ -238,10 +286,27 @@ export async function appendRecord(options: LedgerOptions, record: GrantRecord):
     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: LedgerOptions, record: GrantRecord): Promise<void> {
+  return appendLedgerEvent(options, record);
+}
+
 /** True when this record shows an agent asking for more than it holds. */
 export function isEscalationAttempt(record: GrantRecord): boolean {
   return record.denied.length > 0;
 }
+
+export {
+  buildChildLifecycleEvent,
+  buildWorkspaceLeaseEvent,
+  type ChildLifecycleEvent,
+  type CheckReceiptLedgerEvent,
+  type RuntimeLedgerEvent,
+  type WorkspaceLeaseEvent,
+  type WorkspaceLeaseOutcome,
+} from "./ledger-events.ts";

package/src/refusals.ts

@@ -0,0 +1,66 @@
+export const REFUSAL_CODES = [
+  "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",
+  // Execution-phase outcomes. Without these, an external controller could distinguish a policy refusal
+  // from an internal error but not a lost writer lease from a user pressing stop (R-103).
+  "CHILD_TIMED_OUT",
+  "CHILD_CANCELLED",
+  "CHILD_EXIT_NONZERO",
+  // Planner refusals that previously carried a message and no code at all — including the narrowing
+  // violation, which is the hardest rule this package enforces (R-109).
+  "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",
+] as const;
+
+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 function refusal(
+  code: RefusalCode,
+  message: string,
+  details?: StructuredRefusal["details"],
+): StructuredRefusal {
+  return { code, message, ...(details && Object.keys(details).length > 0 ? { details: { ...details } } : {}) };
+}
+
+/** Error shape for API callers. pi-facing tools still throw, as pi requires, while retaining a stable code. */
+export class GovernanceRefusal extends Error {
+  readonly code: RefusalCode;
+  readonly details?: StructuredRefusal["details"];
+
+  constructor(value: StructuredRefusal) {
+    super(value.message);
+    this.name = "GovernanceRefusal";
+    this.code = value.code;
+    this.details = value.details;
+  }
+}

package/src/run-child.ts

@@ -81,6 +81,8 @@ export interface ChildRunRequest {
    * governed child mid-task.
    */
   onOutput?: (chunk: string) => void;
+  /** Security hook called immediately after spawn, before output handling (for lease attachment). */
+  onSpawn?: (pid: number) => void;
 }
 
 export interface ChildRunResult {
@@ -90,6 +92,8 @@ export interface ChildRunResult {
   truncated: boolean;
   timedOut: boolean;
   aborted: boolean;
+  /** Signal that ended the process, separate from the nullable numeric exit code. */
+  signal?: NodeJS.Signals | null;
   /** Set when the process could not be started at all. */
   spawnError?: string;
 }
@@ -125,6 +129,17 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       settle({ code: null, text: "", truncated: false, timedOut: false, aborted: false, spawnError: String(error) });
       return;
     }
+    try {
+      if (child.pid !== undefined) request.onSpawn?.(child.pid);
+    } catch (error) {
+      const failed = { code: null, text: "", truncated: false, timedOut: false, aborted: false, spawnError: String(error) };
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      child.once("error", () => settle(failed));
+      child.once("close", () => settle(failed));
+      child.kill("SIGKILL");
+      return;
+    }
 
     // One decoder for BOTH streams is deliberate: they are already interleaved into one `text`, and two
     // decoders would each hold their own partial character, so a split byte could surface out of order.
@@ -227,12 +242,19 @@ export function runChild(request: ChildRunRequest): Promise<ChildRunResult> {
       done = true;
       clearTimers();
       request.signal?.removeEventListener("abort", onAbort);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
       settle(result);
     };
 
     child.on("error", (error) =>
       finish({ code: null, text, truncated, timedOut, aborted, spawnError: String(error) }),
     );
-    child.on("close", (code) => finish({ code, text, truncated, timedOut, aborted }));
+    // `close` waits for every inherited pipe, including one retained by a detached grandchild. Once the
+    // governed PID exits, allow a short drain and settle anyway so timeout/output bounds remain bounds.
+    child.on("exit", (code, signal) => {
+      timers.push(setTimeout(() => finish({ code, signal, text, truncated, timedOut, aborted }), 100));
+    });
+    child.on("close", (code, signal) => finish({ code, signal, text, truncated, timedOut, aborted }));
   });
 }