pi-daddy 0.27.4 → 0.32.0

package/src/governance/execution-retention.ts

@@ -0,0 +1,372 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, writeFile, rename } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { buildExecutionRetentionManifest } from "./retention-contract.ts";
+import {
+  missingNativeSession,
+  readNativeSession,
+  type NativeSessionObservation,
+  type NativeSessionManager,
+  type NativeSessionCapture,
+} from "./native-session.ts";
+export {
+  buildExecutionRetentionManifest,
+  parseExecutionRetentionManifest,
+  RETENTION_SCHEMA,
+} from "./retention-contract.ts";
+export {
+  ENV_NATIVE_SESSION_ROOT,
+  readNativeSession,
+  parseNativeSessionBytes,
+  type NativeSessionObservation,
+  type NativeSessionManager,
+} from "./native-session.ts";
+import { ENV_EXECUTION_ARCHIVE } from "../kernel/env-names.ts";
+export { ENV_EXECUTION_ARCHIVE } from "../kernel/env-names.ts";
+import { isUnderPiProjectDir } from "../kernel/project-paths.ts";
+
+/** Operator-owned archive boundary; never a model-facing parameter or an authority source. */
+export const RETENTION_VERSION = "2.0";
+const LIMIT = 1024 * 1024;
+const MAX_ACTIVE = 32;
+let active = 0;
+const digest = (bytes: Uint8Array | string) => createHash("sha256").update(bytes).digest("hex");
+export interface RetentionIdentity {
+  executionId: string;
+  parentExecutionId: string | null;
+  childId: string;
+  toolCallId: string | null;
+  executor: "process" | "herdr" | "check";
+  taskDigest: string | null;
+  definitionDigest: string | null;
+  configurationDigest: string;
+  workspaceId: string | null;
+}
+export interface RetainedContent {
+  status: "retained" | "missing";
+  path: string | null;
+  sha256: string | null;
+  bytes: number | null;
+}
+export interface ExecutionRetentionManifest {
+  version: "2.0";
+  archiveId: string;
+  identity: RetentionIdentity;
+  native: {
+    pid: number | null;
+    paneId: string | null;
+    agentName: string | null;
+    tabId: string | null;
+    sessionId: string | null;
+    sessionPath: string | null;
+    branchLeafId: string | null;
+  };
+  nativeSession: NativeSessionObservation;
+  state: "running" | "terminal";
+  outcome: {
+    code: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    aborted: boolean;
+    truncated: boolean;
+    failed: boolean;
+  } | null;
+  content: Record<"stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result" | "session", RetainedContent>;
+  coverage: { complete: false; losses: string[] };
+  /** Retention is observation, never a work-v4 acceptance decision. */
+  acceptance: "not-assessed";
+}
+export interface RetentionStatus {
+  manifestPath: string | null;
+  status: "disabled" | "pending" | "retained" | "lost";
+}
+const drains = new WeakMap<RetentionStatus, () => Promise<RetentionStatus>>();
+/** Original live status only; drains admitted observations, not producer completeness or fsync. */
+export function drainExecutionRetention(status: RetentionStatus): Promise<RetentionStatus> {
+  const drain = drains.get(status);
+  if (!drain) return Promise.reject(new TypeError("original live retention status required"));
+  return drain();
+}
+const missing = (): RetainedContent => ({ status: "missing", path: null, sha256: null, bytes: null });
+
+/** Hash only an explicitly selected configuration. Callers must not pass environment/auth objects. */
+export const retentionConfigurationDigest = (configuration: unknown): string => digest(JSON.stringify(configuration));
+
+/**
+ * A bounded, coalescing observation queue. No worker-control path awaits publication. A failed or stalled
+ * archive never changes required ledger/lease semantics. `flush` is exclusively for external archival at
+ * quiescence; it is NOT called by the spawner. Missing terminal publication means incomplete observation.
+ */
+export function beginExecutionRetention(identity: RetentionIdentity, directory = process.env[ENV_EXECUTION_ARCHIVE]) {
+  const archiveId = randomUUID();
+  const valid = Boolean(directory && isAbsolute(directory) && !isUnderPiProjectDir(directory));
+  const admitted = valid && active < MAX_ACTIVE;
+  const root = admitted ? join(directory!, archiveId) : null;
+  const manifestPath = root ? join(root, "manifest.json") : null;
+  let status: RetentionStatus["status"] = !directory ? "disabled" : admitted ? "pending" : "lost";
+  const manifest: ExecutionRetentionManifest = {
+    version: RETENTION_VERSION,
+    archiveId,
+    identity: {
+      executionId: identity.executionId,
+      parentExecutionId: identity.parentExecutionId,
+      childId: identity.childId,
+      toolCallId: identity.toolCallId,
+      executor: identity.executor,
+      taskDigest: identity.taskDigest,
+      definitionDigest: identity.definitionDigest,
+      configurationDigest: identity.configurationDigest,
+      workspaceId: identity.workspaceId,
+    },
+    native: {
+      pid: null,
+      paneId: null,
+      agentName: null,
+      tabId: null,
+      sessionId: null,
+      sessionPath: null,
+      branchLeafId: null,
+    },
+    nativeSession: missingNativeSession(),
+    state: "running",
+    outcome: null,
+    content: {
+      stdout: missing(),
+      stderr: missing(),
+      paneSnapshot: missing(),
+      checkReceipt: missing(),
+      result: missing(),
+      session: missing(),
+    },
+    coverage: { complete: false, losses: ["native-session-content-unavailable", "active-branch-unknown"] },
+    acceptance: "not-assessed",
+  };
+  const buffers = new Map<keyof typeof manifest.content, Buffer>();
+  const written = new Set<string>();
+  let total = 0;
+  let dirty = false;
+  let running: Promise<void> | undefined;
+  let finished = false;
+  let released = false;
+  let nativeTask: Promise<void> | undefined;
+  let nextNative:
+    | {
+        source: "herdr-id" | "herdr-path" | "pi-session-file" | "pi-session-manager";
+        value: string;
+        manager?: NativeSessionManager;
+      }
+    | undefined;
+  let pinnedSessionId: string | undefined;
+  let pinnedFile: NativeSessionCapture["fileIdentity"];
+  const loss = (reason: string) => {
+    if (!manifest.coverage.losses.includes(reason)) manifest.coverage.losses.push(reason);
+  };
+  const release = () => {
+    if (admitted && !released) {
+      active--;
+      released = true;
+    }
+  };
+  if (admitted) active++;
+  else if (directory) loss("archive-unavailable-or-capacity-exceeded");
+  const publish = async () => {
+    try {
+      await mkdir(root!, { recursive: true, mode: 0o700 });
+      while (dirty) {
+        dirty = false;
+        // Detached checkpoint: asynchronous I/O cannot mix later outcome/content into this generation.
+        const checkpoint: ExecutionRetentionManifest = JSON.parse(JSON.stringify(manifest));
+        const contents = [...buffers];
+        for (const [kind, bytes] of contents) {
+          const sha256 = digest(bytes);
+          const name = `${kind}-${sha256}.bin`;
+          if (!written.has(name)) {
+            await writeFile(join(root!, name), bytes, { flag: "wx", mode: 0o600 });
+            written.add(name);
+          }
+          checkpoint.content[kind] = { status: "retained", path: name, sha256, bytes: bytes.length };
+        }
+        await writeFile(
+          join(root!, "manifest.pending"),
+          JSON.stringify(buildExecutionRetentionManifest(checkpoint)) + "\n",
+          { mode: 0o600 },
+        );
+        await rename(join(root!, "manifest.pending"), manifestPath!);
+        status = "retained";
+      }
+    } catch {
+      status = "lost";
+      loss("archive-write-failed");
+      buffers.clear();
+      release();
+    } finally {
+      running = undefined;
+      if (finished && !nativeTask) {
+        buffers.clear();
+        release();
+      }
+    }
+  };
+  const schedule = () => {
+    if (!admitted || status === "lost" || released) return;
+    dirty = true;
+    status = "pending";
+    if (!running) running = Promise.resolve().then(publish);
+  };
+  const observeSession = (reference: NonNullable<typeof nextNative>) => {
+    if (finished || !admitted || released || status === "lost") return;
+    if (nextNative && (nextNative.source !== reference.source || nextNative.value !== reference.value))
+      loss("native-session-reference-coalesced");
+    nextNative = {
+      source: reference.source,
+      value: reference.value,
+      ...(reference.manager ? { manager: reference.manager } : {}),
+    };
+    if (nativeTask) return;
+    nativeTask = Promise.resolve()
+      .then(async () => {
+        while (nextNative) {
+          const current = nextNative;
+          nextNative = undefined;
+          const captured: NativeSessionCapture =
+            current.source === "herdr-id"
+              ? {
+                  observation: {
+                    ...missingNativeSession(),
+                    source: current.source,
+                    status: "missing" as const,
+                    sessionId: current.value,
+                    reason: "native-session-path-unavailable",
+                  },
+                }
+              : await readNativeSession({
+                  path: current.value,
+                  source: current.source,
+                  manager: current.manager,
+                  expectedSessionId: pinnedSessionId,
+                  expectedFile: pinnedFile,
+                });
+          if (captured.observation.sessionId && captured.fileIdentity) pinnedFile ??= captured.fileIdentity;
+          let observation = captured.observation;
+          if (pinnedSessionId && observation.sessionId && pinnedSessionId !== observation.sessionId) {
+            observation = {
+              ...missingNativeSession(),
+              source: current.source,
+              status: "changed",
+              reason: "native-session-id-changed",
+            };
+          }
+          if (observation.sessionId) pinnedSessionId ??= observation.sessionId;
+          manifest.nativeSession = { ...observation };
+          manifest.native.sessionId = observation.sessionId;
+          manifest.native.sessionPath = observation.sessionPath;
+          manifest.native.branchLeafId = observation.branchLeafId;
+          buffers.delete("session");
+          if (captured.bytes && observation === captured.observation) buffers.set("session", captured.bytes);
+          if (observation.reason) loss(observation.reason);
+          schedule();
+        }
+      })
+      .catch(() => {
+        loss("native-session-observation-failed");
+      })
+      .finally(() => {
+        nativeTask = undefined;
+        schedule();
+      });
+  };
+  const drain = async (): Promise<RetentionStatus> => {
+    while (nativeTask || running) {
+      if (nativeTask) await nativeTask;
+      if (running) await running;
+    }
+    return { manifestPath, status };
+  };
+  schedule();
+  return {
+    /** Read-only native API reference; never derive IDs from the locator or a displayed name. */
+    observeSession,
+    observeSessionManager(manager: NativeSessionManager) {
+      try {
+        const value = manager.getSessionFile();
+        if (value) observeSession({ source: "pi-session-manager", value, manager });
+        else {
+          loss("native-session-not-persisted");
+          schedule();
+        }
+      } catch {
+        loss("native-session-manager-unavailable");
+        schedule();
+      }
+    },
+    status: (): RetentionStatus => {
+      const value = { manifestPath, status };
+      drains.set(value, drain);
+      return value;
+    },
+    native(value: Partial<Pick<ExecutionRetentionManifest["native"], "pid" | "paneId" | "agentName" | "tabId">>) {
+      if (finished) return;
+      for (const key of ["pid", "paneId", "agentName", "tabId"] as const) {
+        const item = value[key];
+        if (key === "pid") {
+          if (typeof item === "number" && Number.isSafeInteger(item) && item > 0) manifest.native.pid = item;
+        } else if (typeof item === "string" && item.length <= 4096) manifest.native[key] = item;
+      }
+      schedule();
+    },
+    capture(
+      kind: "stdout" | "stderr" | "paneSnapshot" | "checkReceipt" | "result",
+      bytes: Uint8Array,
+      replace = false,
+    ) {
+      if (finished || !admitted || status === "lost") return;
+      const indivisible = kind === "checkReceipt" || kind === "result";
+      if (indivisible) replace = true;
+      const old = buffers.get(kind) ?? Buffer.alloc(0);
+      const available = indivisible ? LIMIT : LIMIT - total + (replace ? old.length : 0);
+      // Receipts and assembled results each have reserved capacity and are never partially published.
+      if (indivisible && bytes.length > available) {
+        loss(`${kind === "checkReceipt" ? "check-receipt" : kind}-not-retained-capacity`);
+        schedule();
+        return;
+      }
+      const kept = Buffer.from(bytes.subarray(0, Math.max(0, available)));
+      if (kept.length !== bytes.length) loss(`${kind}-observation-dropped`);
+      if (kind === "paneSnapshot") loss("pane-snapshot-not-full-transcript");
+      const next = replace ? kept : Buffer.concat([old, kept]);
+      if (!indivisible) total += next.length - old.length;
+      buffers.set(kind, next);
+      schedule();
+    },
+    finish(outcome: NonNullable<ExecutionRetentionManifest["outcome"]>) {
+      if (finished) return;
+      manifest.outcome = {
+        code: outcome.code,
+        signal: outcome.signal,
+        timedOut: outcome.timedOut,
+        aborted: outcome.aborted,
+        truncated: outcome.truncated,
+        failed: outcome.failed,
+      };
+      manifest.state = "terminal";
+      if (outcome.truncated) loss("executor-output-truncated");
+      if (outcome.aborted || outcome.timedOut) loss("execution-interrupted");
+      finished = true;
+      schedule();
+    },
+    /** Observation-only diagnostic; never establishes successful execution or accepted work. */
+    coverage: () => ({ complete: false as const, losses: [...manifest.coverage.losses] }),
+    flush: drain,
+  };
+}
+export type ExecutionRetention = ReturnType<typeof beginExecutionRetention>;
+
+/** Public consumer check: neither a reference nor a wire status supplies the missing bytes. */
+export function verifyRetainedBytes(
+  reference: RetainedContent,
+  bytes?: Uint8Array,
+): "retained" | "missing" | "mismatch" {
+  if (reference.status !== "retained" || bytes === undefined) return "missing";
+  if (reference.bytes !== bytes.byteLength || reference.sha256 !== digest(bytes)) return "mismatch";
+  return "retained";
+}

package/src/governance/file-lock.ts

@@ -0,0 +1,210 @@
+/**
+ * One cross-process file lock, shared by producer ledgers and the approvals store.
+ *
+ * **Extracted rather than copied (R-49).** The ledger has had this lock since fan-out made a second writer
+ * possible; the approvals store had an unlocked read-modify-write, so session 1 could load, session 2 could
+ * revoke, and session 1's next save would **restore the revoked entry** — falsifying a property
+ * `approval-store.ts` documents in so many words. The mitigation already existed twenty lines away. A
+ * second implementation is how a fix comes to contain a smaller copy of the bug it fixed, which has happened
+ * twice in this package (R-38's preview, ADR-0022's republish path), so there is exactly one of these.
+ *
+ * **The two callers want opposite failure behaviour, and that is the caller's decision, not this module's.**
+ * A ledger write that cannot take the lock must fail the delegation closed — a child running with granted
+ * capabilities and no audit line is the thing the ledger exists to prevent. An approvals write that cannot
+ * take the lock must NOT fail the work: the human already said yes, and the store is a convenience cache
+ * (ADR-0020). So this throws `LockTimeoutError`, distinguishable from every other failure, and each caller
+ * decides what that means.
+ */
+
+import { open, readFile, rm, stat } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+
+/** How long to wait for another writer to finish before giving up. Short: failing closed beats hanging. */
+export const LOCK_TIMEOUT_MS = 2000;
+/** A lock older than this is treated as abandoned by a killed process and broken. */
+export const STALE_LOCK_MS = 10_000;
+
+/**
+ * Raised only when the wait ran out. Its own type so a caller can tell "somebody else is writing" from
+ * "this filesystem rejected the write", which want different messages and, for the approvals store,
+ * different outcomes.
+ */
+export class LockTimeoutError extends Error {
+  constructor(label: string) {
+    super(`${label} is locked by another writer (waited ${LOCK_TIMEOUT_MS}ms)`);
+    this.name = "LockTimeoutError";
+  }
+}
+
+export interface FileLockOptions {
+  readonly staleRecovery?: "age" | "disabled";
+}
+function lockPolicy(options: FileLockOptions | undefined): "age" | "disabled" {
+  if (options === undefined) return "age";
+  const invalid = (): never => {
+    throw new TypeError("invalid file lock options");
+  };
+  if (
+    options === null ||
+    typeof options !== "object" ||
+    Array.isArray(options) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(options))
+  )
+    return invalid();
+  const keys = Reflect.ownKeys(options);
+  if (keys.some((key) => key !== "staleRecovery")) return invalid();
+  if (!keys.length) return "age";
+  const field = Object.getOwnPropertyDescriptor(options, "staleRecovery")!;
+  if (!Object.hasOwn(field, "value") || !field.enumerable || !["age", "disabled"].includes(field.value))
+    return invalid();
+  return field.value;
+}
+
+/**
+ * Run `work` while holding an exclusive lock beside `path`.
+ * Explicit disabled recovery never reclaims by age/liveness. V4 selects it internally; an orphan
+ * requires separately authorized quiescent recovery, not a timer or automatic operator action.
+ * The age-based behavior described below remains the default for legacy callers.
+ *
+ * **Why a lock at all.** `O_APPEND` is atomic for one write to a regular file on a POSIX filesystem, and the
+ * guarantee does **not** hold on drvfs (`/mnt/c` under WSL2) or NFS — which is exactly where this project
+ * runs. The approvals store never had the guarantee anyway: read-modify-write is not one write.
+ *
+ * **A lock introduces its own failure mode and it is handled deliberately.** A process killed while holding
+ * the lock would otherwise block every future write forever, so a lock older than `STALE_LOCK_MS` is broken.
+ * Every delete proves ownership first (`removeIfOurs`) — see the token comment in the loop for the two
+ * mutual-exclusion breaks that came from not doing so, both reproduced across real OS processes.
+ *
+ * **What staleness actually measures, stated because it is not what it sounds like.** `STALE_LOCK_MS`
+ * compares the lock's mtime to now; it never checks whether the owner is alive. So *any* 10s stall of the
+ * holder hands the lock on — a `SIGSTOP`, a laptop suspend, swap thrash, a debugger breakpoint, a long GC
+ * pause. Measured on this project's own filesystems, no realistic `work()` comes near it: one ledger append
+ * is 0.1ms on ext4 and 21ms on drvfs, and a 10,000-entry `saveApproval` is 30ms / 97ms. Sixteen-way
+ * contention raises *waiters'* time, never the holder's — max hold measured at 49ms. So the threshold is
+ * two orders of magnitude clear of normal operation and is not guarded against abnormal suspension.
+ *
+ * The timeout is short *on purpose*: work refused because a file was busy is recoverable and loud, while
+ * work that hangs waiting for a lock is neither.
+ */
+export async function withFileLock<T>(
+  path: string,
+  label: string,
+  work: () => Promise<T>,
+  options?: FileLockOptions,
+): Promise<T> {
+  const staleRecovery = lockPolicy(options); // Detached once, before I/O or any wait.
+  const lockPath = `${path}.lock`;
+  const deadline = Date.now() + LOCK_TIMEOUT_MS;
+
+  for (;;) {
+    // **A token, and the reason mutual exclusion depends on it (R-67).** `rm(path)` deletes whatever is at
+    // the path *now*, not the lock this process created — so the previous version broke its own invariant
+    // two ways, both reproduced across real OS processes:
+    //
+    //  - the stale-break `stat` and `rm` are two awaits, so a process descheduled between them could delete
+    //    a LIVE lock another waiter had just created, and then succeed at its own create: two holders;
+    //  - worse, the `finally` removed the lock unconditionally. A holder whose lock had been broken out
+    //    from under it still freed the NEW owner's lock on the way out — and the damage then propagated to
+    //    processes that raced nothing and observed nothing wrong, which is how one break became a chain.
+    //
+    // Writing a unique token and re-reading it before every delete makes both inexpressible: this process
+    // only ever removes a file it can prove is its own. The docstring used to claim "whichever wins the
+    // exclusive create proceeds, which is correct because only one can" — true of the create and false of
+    // the delete, which is what made it convincing.
+    const token = `${process.pid}:${randomUUID()}`;
+    let handle: Awaited<ReturnType<typeof open>> | undefined;
+    try {
+      handle = await open(lockPath, "wx");
+      await handle.writeFile(`${token}\n`, "utf8");
+    } catch (error) {
+      // The handle may exist even though the WRITE failed (ENOSPC, EDQUOT, EFBIG). The old code jumped
+      // straight here and rethrew, so the already-created lock file was left on disk and its descriptor
+      // leaked to GC — an orphan that blocks every writer for a full STALE_LOCK_MS and feeds the EMFILE
+      // path below. Close and remove before doing anything else; `ours` is safe because we just made it.
+      if (handle) {
+        await handle.close().catch(() => undefined);
+        await removeIfOurs(lockPath, token);
+        handle = undefined;
+      }
+      const code = (error as { code?: string }).code;
+      if (code !== "EEXIST") throw error;
+
+      // Someone else holds it. Break it only if it is old enough to be abandoned — and only the exact file
+      // we judged, so a lock created in the gap survives.
+      if (staleRecovery === "age")
+        try {
+          const held = await stat(lockPath);
+          if (Date.now() - held.mtimeMs > STALE_LOCK_MS) {
+            const abandoned = await readFile(lockPath, "utf8").catch(() => undefined);
+            if (abandoned !== undefined) await removeIfOurs(lockPath, abandoned.trim());
+          }
+        } catch {
+          /* it vanished between the check and the stat — the next attempt will simply take it */
+        }
+
+      if (Date.now() >= deadline) throw new LockTimeoutError(label);
+      await new Promise((r) => setTimeout(r, 25));
+      continue;
+    }
+
+    let bodyFailed = false;
+    try {
+      return await work();
+    } catch (error) {
+      bodyFailed = true;
+      throw error;
+    } finally {
+      if (staleRecovery === "disabled") {
+        try {
+          await releaseDisabledLock(handle, lockPath, token);
+        } catch (error) {
+          if (!bodyFailed) throw error;
+        } // Preserve even a falsy primary rejection.
+      } else {
+        await handle.close().catch(() => undefined);
+        // Legacy age policy remains best effort; never remove a demonstrably different token.
+        await removeIfOurs(lockPath, token);
+      }
+    }
+  }
+}
+
+/** Disabled ownership cannot silently manufacture an indefinite orphan after a successful body.
+ * Try token-checked removal even if close failed; report the first failure after both attempts.
+ * Appended bytes are not rolled back, and a primary body error takes precedence at the caller. */
+async function releaseDisabledLock(
+  handle: Awaited<ReturnType<typeof open>>,
+  lockPath: string,
+  token: string,
+): Promise<void> {
+  let failure: { error: unknown } | null = null;
+  try {
+    await handle.close();
+  } catch (error) {
+    failure = { error };
+  }
+  try {
+    await removeIfOurs(lockPath, token, true);
+  } catch (error) {
+    failure ??= { error };
+  }
+  if (failure) throw failure.error;
+}
+
+/**
+ * Delete the lock only if it still holds `token`.
+ *
+ * Read-then-delete is itself two operations, so this is not atomic either — but it narrows the window from
+ * "the whole of `work()`" to "between a read and an unlink", and it removes the *systematic* break entirely:
+ * a process can no longer delete a lock it demonstrably never owned.
+ */
+async function removeIfOurs(lockPath: string, token: string, strict = false): Promise<void> {
+  try {
+    const held = await readFile(lockPath, "utf8");
+    if (held.trim() !== token) return;
+    await rm(lockPath, { force: true });
+  } catch (error) {
+    if (strict) throw error; // No ownership inference or force-delete after a failed read.
+    /* Legacy: already gone, or unreadable — this process must not force removal. */
+  }
+}

package/src/governance/finalization.ts

@@ -0,0 +1,82 @@
+interface Finalizer {
+  label: string;
+  run: () => void | Promise<void>;
+}
+
+const FINALIZER_ERRORS = Symbol("pi-daddy.finalizer-errors");
+
+type ErrorWithFinalizers = Error & { [FINALIZER_ERRORS]?: unknown[] };
+
+/**
+ * Run every finalizer without allowing one of their failures to replace the operation's primary error.
+ *
+ * Error identity is preserved when possible: refusal codes and `instanceof` checks are part of callers'
+ * control flow. Finalizer failures are attached and added to the primary message instead of wrapping it.
+ */
+export async function runWithFinalizers<T>(operation: () => Promise<T>, finalizers: readonly Finalizer[]): Promise<T> {
+  let primaryPresent = false;
+  let primary: unknown;
+  let result: T | undefined;
+
+  try {
+    result = await operation();
+  } catch (error) {
+    primaryPresent = true;
+    primary = error;
+  }
+
+  const failures: Array<{ label: string; error: unknown }> = [];
+  for (const finalizer of finalizers) {
+    try {
+      await finalizer.run();
+    } catch (error) {
+      failures.push({ label: finalizer.label, error });
+    }
+  }
+
+  if (primaryPresent) {
+    if (failures.length > 0) throw appendFinalizerFailures(primary, failures);
+    throw primary;
+  }
+  if (failures.length === 1) throw failures[0].error;
+  if (failures.length > 1) {
+    throw new AggregateError(
+      failures.map((failure) => failure.error),
+      failures.map((failure) => `${failure.label}: ${String(failure.error)}`).join("; "),
+    );
+  }
+  return result as T;
+}
+
+/** True when a primary error retained a finalizer failure of the requested kind. */
+export function hasFinalizerError(error: unknown, predicate: (value: unknown) => boolean): boolean {
+  return error instanceof Error && (error as ErrorWithFinalizers)[FINALIZER_ERRORS]?.some(predicate) === true;
+}
+
+function appendFinalizerFailures(
+  primary: unknown,
+  failures: ReadonlyArray<{ label: string; error: unknown }>,
+): unknown {
+  if (primary instanceof Error) {
+    const target = primary as ErrorWithFinalizers;
+    try {
+      const prior = target[FINALIZER_ERRORS] ?? [];
+      Object.defineProperty(target, FINALIZER_ERRORS, {
+        configurable: true,
+        value: [...prior, ...failures.map((failure) => failure.error)],
+      });
+      target.message = [
+        target.message,
+        ...failures.map((failure) => `${failure.label}: ${String(failure.error)}`),
+      ].join("; ");
+      return target;
+    } catch {
+      // A frozen foreign error cannot be annotated. Keep it as the first AggregateError member and cause.
+    }
+  }
+  return new AggregateError(
+    [primary, ...failures.map((failure) => failure.error)],
+    [String(primary), ...failures.map((failure) => `${failure.label}: ${String(failure.error)}`)].join("; "),
+    { cause: primary },
+  );
+}