usertrust 0.2.2 → 0.2.4

package/dist/govern.js

@@ -27,8 +27,8 @@
  * ```
  */
 import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { existsSync, mkdirSync } from "node:fs";
+import { readFile, rename, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { createAuditWriter } from "./audit/chain.js";
 import { writeReceipt } from "./audit/rotation.js";
@@ -36,16 +36,71 @@ import { detectClientKind } from "./detect.js";
 import { TrustTBClient, XFER_SPEND } from "./ledger/client.js";
 import { estimateCost, estimateInputTokens } from "./ledger/pricing.js";
 import { recordPattern } from "./memory/patterns.js";
-import { DecayRateCalculator } from "./policy/decay.js";
 import { evaluatePolicy, loadPolicies } from "./policy/gate.js";
 import { detectPII } from "./policy/pii.js";
 import { connectProxy } from "./proxy.js";
 import { CircuitBreakerRegistry } from "./resilience/circuit.js";
 import { DEFAULT_BUDGET, VAULT_DIR } from "./shared/constants.js";
+/** Base URL for receipt verification links (used in proxy mode). */
+const VERIFY_URL_BASE = "https://verify.usertrust.dev";
 import { LedgerUnavailableError, PolicyDeniedError } from "./shared/errors.js";
 import { trustId } from "./shared/ids.js";
 import { TrustConfigSchema } from "./shared/types.js";
 import { createGovernedStream } from "./streaming.js";
+// ── AUD-453: Async mutex for budget atomicity ──
+// Prevents concurrent interceptCall invocations from racing through
+// the budget-check + PENDING hold sequence.
+class AsyncMutex {
+    queue = Promise.resolve();
+    async acquire() {
+        let release;
+        const next = new Promise((resolve) => {
+            release = resolve;
+        });
+        const prev = this.queue;
+        this.queue = next;
+        await prev;
+        return release;
+    }
+}
+async function loadSpendLedger(vaultBase) {
+    const ledgerPath = join(vaultBase, VAULT_DIR, "spend-ledger.json");
+    try {
+        const raw = await readFile(ledgerPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed != null &&
+            typeof parsed === "object" &&
+            "budgetSpent" in parsed &&
+            typeof parsed.budgetSpent === "number") {
+            return parsed.budgetSpent;
+        }
+    }
+    catch {
+        // No ledger file or corrupt — start from zero
+    }
+    return 0;
+}
+async function persistSpendLedger(vaultBase, budgetSpent) {
+    const dir = join(vaultBase, VAULT_DIR);
+    const ledgerPath = join(dir, "spend-ledger.json");
+    const tmpPath = join(dir, "spend-ledger.json.tmp");
+    const data = {
+        budgetSpent,
+        updatedAt: new Date().toISOString(),
+    };
+    try {
+        // Ensure vault dir exists
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        // Atomic write: write tmp then rename
+        await writeFile(tmpPath, JSON.stringify(data), "utf-8");
+        await rename(tmpPath, ledgerPath);
+    }
+    catch {
+        // Best-effort — do not fail the LLM call over ledger persistence
+    }
+}
 // ── trust() ──
 export async function trust(client, opts) {
     // 1. Load config
@@ -65,26 +120,27 @@ export async function trust(client, opts) {
         });
     }
     const isDryRun = opts?.dryRun ?? process.env.USERTRUST_DRY_RUN === "true";
+    // AUD-470: Only accept injected _engine/_audit in test environments.
+    // In production, silently ignore them to prevent governance bypass.
+    const isTestEnv = process.env.USERTRUST_TEST === "1" || process.env.NODE_ENV === "test";
     // 2. Initialise subsystems
     const vaultPath = vaultBase;
-    const audit = opts?._audit ?? createAuditWriter(vaultPath);
+    const audit = (isTestEnv ? opts?._audit : undefined) ?? createAuditWriter(vaultPath);
     const policiesPath = join(vaultPath, VAULT_DIR, config.policies);
     const policyRules = existsSync(policiesPath) ? loadPolicies(policiesPath) : [];
     const breaker = new CircuitBreakerRegistry({
         failureThreshold: config.circuitBreaker.failureThreshold,
         resetTimeoutMs: config.circuitBreaker.resetTimeout,
     });
-    // Decay-weighted budget calculator (1-hour half-life)
-    const decayCalc = new DecayRateCalculator({ halfLifeMs: 3_600_000 });
-    const spendHistory = [];
     // 3. Proxy connection (if proxy mode)
     let proxyConn = null;
     if (opts?.proxy) {
         proxyConn = connectProxy(opts.proxy, opts.key);
     }
     // 4. Engine (injected for tests, real TB client in production, null in dry-run/proxy)
+    // AUD-470: _engine injection only accepted in test environments
     let engine;
-    if (opts?._engine !== undefined) {
+    if (isTestEnv && opts?._engine !== undefined) {
         engine = opts._engine;
     }
     else if (!isDryRun && proxyConn == null) {
@@ -102,306 +158,342 @@ export async function trust(client, opts) {
     const kind = detectClientKind(client);
     // 6. Track state
     let destroyed = false;
-    let budgetSpent = 0;
+    let budgetSpent = await loadSpendLedger(vaultBase); // AUD-457: restore from disk
+    const budgetMutex = new AsyncMutex(); // AUD-453: serialise budget-check + hold
+    let inFlightCount = 0; // AUD-462: track in-flight calls for graceful destroy
     // 7. Two-phase intercept
     async function interceptCall(originalFn, thisArg, args) {
         if (destroyed) {
             throw new Error("TrustedClient has been destroyed");
         }
-        const params = (args[0] ?? {});
-        const model = params.model ?? "unknown";
-        const messages = params.messages ?? [];
-        // Per-call audit degradation flag (not sticky across calls)
-        let callAuditDegraded = false;
-        // a. Circuit breaker check
-        const cb = breaker.get(kind);
-        cb.allowRequest();
-        // b. Estimate cost (before policy, so cost fields are available in context)
-        const transferId = trustId("tx");
-        const estimatedInputTokens = estimateInputTokens(messages);
-        const maxOutputTokens = params.max_tokens ?? 4096;
-        const estimatedCost = estimateCost(model, estimatedInputTokens, maxOutputTokens);
-        // c. Policy gate
-        const policyResult = evaluatePolicy(policyRules, {
-            model,
-            tier: config.tier,
-            estimated_cost: estimatedCost,
-            budget_remaining: config.budget - budgetSpent,
-            ...params,
-        });
-        if (policyResult.decision === "deny") {
-            const reason = policyResult.reasons.length > 0 ? policyResult.reasons.join("; ") : "Policy denied";
-            throw new PolicyDeniedError(reason);
-        }
-        // d. PII check
-        if (config.pii !== "off") {
-            const piiResult = detectPII(messages);
-            if (piiResult.found && config.pii === "block") {
-                throw new PolicyDeniedError(`PII detected: ${piiResult.types.join(", ")}`);
-            }
-            // "warn" and "redact" modes: continue (redact is not implemented at SDK level)
-        }
-        // d2. Failure mode 15.4: TigerBeetle / engine unreachable — PENDING hold
-        if (proxyConn != null && !isDryRun) {
+        // AUD-462: Track in-flight calls so destroy() can wait for them
+        inFlightCount++;
+        try {
+            const params = (args[0] ?? {});
+            const model = params.model ?? "unknown";
+            const messages = params.messages ?? [];
+            // Per-call audit degradation flag (not sticky across calls)
+            let callAuditDegraded = false;
+            // a. Circuit breaker check
+            const cb = breaker.get(kind);
+            cb.allowRequest();
+            // b. Estimate cost (before policy, so cost fields are available in context)
+            const transferId = trustId("tx");
+            const estimatedInputTokens = estimateInputTokens(messages);
+            const maxOutputTokens = params.max_tokens ?? 4096;
+            const estimatedCost = estimateCost(model, estimatedInputTokens, maxOutputTokens);
+            // AUD-453: Acquire mutex to serialise budget-check + PENDING hold.
+            // This prevents concurrent calls from both passing the budget check
+            // and overshooting the budget.
+            const releaseBudgetLock = await budgetMutex.acquire();
+            // AUD-460: Track the proxy's transferId separately for settle/void
+            let proxyTransferId;
             try {
-                await proxyConn.spend({
+                // c. Policy gate
+                const policyResult = evaluatePolicy(policyRules, {
                     model,
-                    estimatedCost,
-                    actor: "local",
+                    tier: config.tier,
+                    estimated_cost: estimatedCost,
+                    budget_remaining: config.budget - budgetSpent,
+                    ...params,
                 });
+                if (policyResult.decision === "deny") {
+                    const reason = policyResult.reasons.length > 0 ? policyResult.reasons.join("; ") : "Policy denied";
+                    throw new PolicyDeniedError(reason);
+                }
+                // d. PII check
+                if (config.pii !== "off") {
+                    const piiResult = detectPII(messages);
+                    if (piiResult.found && config.pii === "block") {
+                        throw new PolicyDeniedError(`PII detected: ${piiResult.types.join(", ")}`);
+                    }
+                    // "warn" and "redact" modes: continue (redact is not implemented at SDK level)
+                }
+                // d2. Failure mode 15.4: TigerBeetle / engine unreachable — PENDING hold
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        // AUD-460: Capture the proxy's returned transferId
+                        const proxyResult = await proxyConn.spend({
+                            model,
+                            estimatedCost,
+                            actor: "local",
+                        });
+                        proxyTransferId = proxyResult.transferId;
+                    }
+                    catch (holdErr) {
+                        throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
+                    }
+                }
+                else if (engine != null && !isDryRun) {
+                    try {
+                        await engine.spendPending({
+                            transferId,
+                            amount: estimatedCost,
+                        });
+                    }
+                    catch (holdErr) {
+                        // Ledger unreachable — do NOT forward to provider
+                        throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
+                    }
+                }
             }
-            catch (holdErr) {
-                throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
+            finally {
+                // AUD-453: Release lock after budget check + hold are complete
+                releaseBudgetLock();
             }
-        }
-        else if (engine != null && !isDryRun) {
+            // e. Forward to original SDK
+            let settled = true;
             try {
-                await engine.spendPending({
-                    transferId,
-                    amount: estimatedCost,
-                });
-            }
-            catch (holdErr) {
-                // Ledger unreachable — do NOT forward to provider
-                throw new LedgerUnavailableError(holdErr instanceof Error ? holdErr.message : String(holdErr));
-            }
-        }
-        // e. Forward to original SDK
-        let settled = true;
-        try {
-            const response = await originalFn.apply(thisArg, args);
-            // e2. Streaming detection: if response is an async iterable, wrap with
-            // token accumulation. Settlement and audit happen when the stream ends.
-            if (response != null &&
-                typeof response === "object" &&
-                Symbol.asyncIterator in response) {
-                const stream = response;
-                const governedStream = createGovernedStream(stream, kind, async (usage) => {
-                    const streamCost = estimateCost(model, usage.inputTokens, usage.outputTokens);
-                    budgetSpent += streamCost;
-                    cb.recordSuccess();
-                    if (proxyConn != null && !isDryRun) {
-                        try {
-                            await proxyConn.settle(transferId, streamCost);
+                const response = await originalFn.apply(thisArg, args);
+                // e2. Streaming detection: if response is an async iterable, wrap with
+                // token accumulation. Settlement and audit happen when the stream ends.
+                if (response != null &&
+                    typeof response === "object" &&
+                    Symbol.asyncIterator in response) {
+                    const stream = response;
+                    const governedStream = createGovernedStream(stream, kind, async (usage) => {
+                        const streamCost = estimateCost(model, usage.inputTokens, usage.outputTokens);
+                        budgetSpent += streamCost;
+                        // AUD-457: Persist cumulative spend to disk
+                        await persistSpendLedger(vaultBase, budgetSpent);
+                        cb.recordSuccess();
+                        if (proxyConn != null && !isDryRun) {
+                            try {
+                                // AUD-460: Use the proxy's transferId for settlement
+                                await proxyConn.settle(proxyTransferId ?? transferId, streamCost);
+                            }
+                            catch {
+                                settled = false;
+                            }
                         }
-                        catch {
-                            settled = false;
+                        else if (engine != null && !isDryRun) {
+                            try {
+                                await engine.postPendingSpend(transferId);
+                            }
+                            catch {
+                                settled = false;
+                            }
                         }
-                    }
-                    else if (engine != null && !isDryRun) {
+                        const syntheticHash = createHash("sha256").update(transferId).digest("hex");
+                        let auditHash = syntheticHash;
                         try {
-                            await engine.postPendingSpend(transferId);
+                            const auditEvent = await audit.appendEvent({
+                                kind: "llm_call",
+                                actor: "local",
+                                data: { model, cost: streamCost, settled, transferId },
+                            });
+                            auditHash = auditEvent.hash;
                         }
                         catch {
-                            settled = false;
+                            callAuditDegraded = true;
                         }
-                    }
-                    const syntheticHash = createHash("sha256").update(transferId).digest("hex");
-                    let auditHash = syntheticHash;
-                    try {
-                        const auditEvent = await audit.appendEvent({
-                            kind: "llm_call",
-                            actor: "local",
-                            data: { model, cost: streamCost, settled, transferId },
-                        });
-                        auditHash = auditEvent.hash;
-                    }
-                    catch {
-                        callAuditDegraded = true;
-                    }
-                    return {
+                        return {
+                            transferId,
+                            cost: streamCost,
+                            budgetRemaining: config.budget - budgetSpent,
+                            auditHash,
+                            chainPath: join(VAULT_DIR, "audit"),
+                            receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
+                            settled,
+                            model,
+                            provider: kind,
+                            timestamp: new Date().toISOString(),
+                            ...(callAuditDegraded ? { auditDegraded: true } : {}),
+                            // AUD-456: Flag proxy stub receipts
+                            ...(proxyConn != null ? { proxyStub: true } : {}),
+                        };
+                    }, (error) => {
+                        cb.recordFailure();
+                        if (proxyConn != null && !isDryRun) {
+                            // AUD-460: Use the proxy's transferId for void
+                            proxyConn.void(proxyTransferId ?? transferId).catch(() => { });
+                        }
+                        else if (engine != null && !isDryRun) {
+                            engine.voidPendingSpend(transferId).catch(() => { });
+                        }
+                    });
+                    // AUD-454: For streaming responses, settlement has NOT happened yet.
+                    // Set settled: false — the real settlement status will be on
+                    // governedStream.receipt after the stream is fully consumed.
+                    const auditHash = createHash("sha256").update(transferId).digest("hex");
+                    const estimatedReceipt = {
                         transferId,
-                        cost: streamCost,
+                        cost: estimatedCost,
                         budgetRemaining: config.budget - budgetSpent,
                         auditHash,
                         chainPath: join(VAULT_DIR, "audit"),
-                        receiptUrl: opts?.proxy != null ? `https://verify.usertools.dev/${transferId}` : null,
-                        settled,
+                        receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
+                        settled: false, // AUD-454: not settled yet — stream hasn't been consumed
                         model,
                         provider: kind,
                         timestamp: new Date().toISOString(),
                         ...(callAuditDegraded ? { auditDegraded: true } : {}),
+                        // AUD-456: Flag proxy stub receipts
+                        ...(proxyConn != null ? { proxyStub: true } : {}),
                     };
-                }, (error) => {
-                    cb.recordFailure();
-                    if (proxyConn != null && !isDryRun) {
-                        proxyConn.void(transferId).catch(() => { });
+                    return { response: governedStream, receipt: estimatedReceipt };
+                }
+                // f. Compute actual cost from response usage
+                let actualCost = estimatedCost;
+                if (response != null && typeof response === "object" && "usage" in response) {
+                    const usage = response.usage;
+                    if (usage != null) {
+                        const inputTokens = usage.input_tokens ??
+                            usage.prompt_tokens ??
+                            estimatedInputTokens;
+                        const outputTokens = usage.output_tokens ??
+                            usage.completion_tokens ??
+                            0;
+                        actualCost = estimateCost(model, inputTokens, outputTokens);
                     }
-                    else if (engine != null && !isDryRun) {
-                        engine.voidPendingSpend(transferId).catch(() => { });
+                }
+                // Track budget (cumulative)
+                budgetSpent += actualCost;
+                // AUD-457: Persist cumulative spend to disk
+                await persistSpendLedger(vaultBase, budgetSpent);
+                // g. Circuit breaker: record success
+                cb.recordSuccess();
+                // g2. Failure mode 15.1: POST fails after LLM success
+                if (engine != null && !isDryRun) {
+                    try {
+                        await engine.postPendingSpend(transferId);
+                    }
+                    catch (postErr) {
+                        // POST failed — LLM call succeeded but settlement is ambiguous
+                        settled = false;
+                        await audit
+                            .appendEvent({
+                            kind: "settlement_ambiguous",
+                            actor: "local",
+                            data: {
+                                model,
+                                cost: actualCost,
+                                transferId,
+                                error: postErr instanceof Error ? postErr.message : String(postErr),
+                            },
+                        })
+                            .catch(() => {
+                            // Audit also degraded — nothing more we can do
+                            callAuditDegraded = true;
+                        });
                     }
-                });
-                // For streaming responses, return the wrapped stream with an
-                // estimated trust receipt. The actual receipt (with real
-                // token counts) is available via governedStream.receipt
-                // after the stream is fully consumed.
-                const auditHash = createHash("sha256").update(transferId).digest("hex");
-                const estimatedReceipt = {
-                    transferId,
-                    cost: estimatedCost,
-                    budgetRemaining: config.budget - budgetSpent,
-                    auditHash,
-                    chainPath: join(VAULT_DIR, "audit"),
-                    receiptUrl: opts?.proxy != null ? `https://verify.usertools.dev/${transferId}` : null,
-                    settled,
-                    model,
-                    provider: kind,
-                    timestamp: new Date().toISOString(),
-                    ...(callAuditDegraded ? { auditDegraded: true } : {}),
-                };
-                return { response: governedStream, receipt: estimatedReceipt };
-            }
-            // f. Compute actual cost from response usage
-            let actualCost = estimatedCost;
-            if (response != null && typeof response === "object" && "usage" in response) {
-                const usage = response.usage;
-                if (usage != null) {
-                    const inputTokens = usage.input_tokens ??
-                        usage.prompt_tokens ??
-                        estimatedInputTokens;
-                    const outputTokens = usage.output_tokens ??
-                        usage.completion_tokens ??
-                        0;
-                    actualCost = estimateCost(model, inputTokens, outputTokens);
                 }
-            }
-            // Track budget (cumulative and decay-weighted)
-            budgetSpent += actualCost;
-            spendHistory.push({ ts: Date.now(), value: actualCost });
-            // g. Circuit breaker: record success
-            cb.recordSuccess();
-            // g2. Failure mode 15.1: POST fails after LLM success
-            if (engine != null && !isDryRun) {
-                try {
-                    await engine.postPendingSpend(transferId);
+                // g3. Proxy settlement
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        // AUD-460: Use the proxy's transferId for settlement
+                        await proxyConn.settle(proxyTransferId ?? transferId, actualCost);
+                    }
+                    catch {
+                        settled = false;
+                    }
                 }
-                catch (postErr) {
-                    // POST failed — LLM call succeeded but settlement is ambiguous
-                    settled = false;
-                    await audit
-                        .appendEvent({
-                        kind: "settlement_ambiguous",
+                // h. Audit event — failure mode 15.3: audit write failure
+                const syntheticHash = createHash("sha256").update(transferId).digest("hex");
+                let auditHash = syntheticHash;
+                try {
+                    const auditEvent = await audit.appendEvent({
+                        kind: "llm_call",
                         actor: "local",
                         data: {
                             model,
                             cost: actualCost,
+                            settled,
                             transferId,
-                            error: postErr instanceof Error ? postErr.message : String(postErr),
                         },
-                    })
-                        .catch(() => {
-                        // Audit also degraded — nothing more we can do
-                        callAuditDegraded = true;
                     });
-                }
-            }
-            // g3. Proxy settlement
-            if (proxyConn != null && !isDryRun) {
-                try {
-                    await proxyConn.settle(transferId, actualCost);
+                    auditHash = auditEvent.hash;
                 }
                 catch {
-                    settled = false;
+                    // Failure mode 15.3: Audit degraded — do not fail the response
+                    callAuditDegraded = true;
+                    process.stderr.write(`[usertrust] audit degraded: failed to write llm_call event for ${transferId}\n`);
                 }
-            }
-            // h. Audit event — failure mode 15.3: audit write failure
-            const syntheticHash = createHash("sha256").update(transferId).digest("hex");
-            let auditHash = syntheticHash;
-            try {
-                const auditEvent = await audit.appendEvent({
-                    kind: "llm_call",
-                    actor: "local",
-                    data: {
+                // i. Daily-rotated audit receipt (non-blocking)
+                if (config.audit.rotation !== "none") {
+                    writeReceipt(vaultPath, {
+                        kind: "llm_call",
+                        subsystem: "trust",
+                        actor: "local",
+                        data: { model, cost: actualCost, settled, transferId },
+                    }, config.audit.indexLimit);
+                }
+                // i2. Pattern memory
+                if (config.patterns.enabled) {
+                    const promptHash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+                    await recordPattern({
+                        promptHash,
                         model,
                         cost: actualCost,
-                        settled,
-                        transferId,
-                    },
-                });
-                auditHash = auditEvent.hash;
-            }
-            catch {
-                // Failure mode 15.3: Audit degraded — do not fail the response
-                callAuditDegraded = true;
-                process.stderr.write(`[usertrust] audit degraded: failed to write llm_call event for ${transferId}\n`);
-            }
-            // i. Daily-rotated audit receipt (non-blocking)
-            if (config.audit.rotation !== "none") {
-                writeReceipt(vaultPath, {
-                    kind: "llm_call",
-                    subsystem: "trust",
-                    actor: "local",
-                    data: { model, cost: actualCost, settled, transferId },
-                }, config.audit.indexLimit);
-            }
-            // i2. Pattern memory
-            if (config.patterns.enabled) {
-                const promptHash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
-                await recordPattern({
-                    promptHash,
-                    model,
+                        success: true,
+                    }).catch(() => { });
+                }
+                const budgetRemaining = config.budget - budgetSpent;
+                const receipt = {
+                    transferId,
                     cost: actualCost,
-                    success: true,
-                }).catch(() => { });
+                    budgetRemaining,
+                    auditHash,
+                    chainPath: join(VAULT_DIR, "audit"),
+                    receiptUrl: opts?.proxy != null ? `${VERIFY_URL_BASE}/${transferId}` : null,
+                    settled,
+                    model,
+                    provider: kind,
+                    timestamp: new Date().toISOString(),
+                    ...(callAuditDegraded ? { auditDegraded: true } : {}),
+                    // AUD-456: Flag proxy stub receipts
+                    ...(proxyConn != null ? { proxyStub: true } : {}),
+                };
+                return { response, receipt };
             }
-            const budgetRemaining = config.budget - budgetSpent;
-            const receipt = {
-                transferId,
-                cost: actualCost,
-                budgetRemaining,
-                auditHash,
-                chainPath: join(VAULT_DIR, "audit"),
-                receiptUrl: opts?.proxy != null ? `https://verify.usertools.dev/${transferId}` : null,
-                settled,
-                model,
-                provider: kind,
-                timestamp: new Date().toISOString(),
-                ...(callAuditDegraded ? { auditDegraded: true } : {}),
-            };
-            return { response, receipt };
-        }
-        catch (err) {
-            // j. Circuit breaker: record failure
-            cb.recordFailure();
-            // j2. Failure mode 15.2: LLM fails — VOID the pending hold
-            if (engine != null && !isDryRun) {
-                try {
-                    await engine.voidPendingSpend(transferId);
-                }
-                catch {
-                    // Best-effort void — log and continue
+            catch (err) {
+                // j. Circuit breaker: record failure
+                cb.recordFailure();
+                // j2. Failure mode 15.2: LLM fails — VOID the pending hold
+                if (engine != null && !isDryRun) {
+                    try {
+                        await engine.voidPendingSpend(transferId);
+                    }
+                    catch {
+                        // Best-effort void — log and continue
+                    }
                 }
-            }
-            // j3. Proxy void
-            if (proxyConn != null && !isDryRun) {
-                try {
-                    await proxyConn.void(transferId);
+                // j3. Proxy void
+                if (proxyConn != null && !isDryRun) {
+                    try {
+                        // AUD-460: Use the proxy's transferId for void
+                        await proxyConn.void(proxyTransferId ?? transferId);
+                    }
+                    catch {
+                        // Best-effort void
+                    }
                 }
-                catch {
-                    // Best-effort void
+                // k. Audit the failure
+                await audit
+                    .appendEvent({
+                    kind: "llm_call_failed",
+                    actor: "local",
+                    data: { model, error: String(err), transferId },
+                })
+                    .catch(() => {
+                    callAuditDegraded = true;
+                });
+                // l. Pattern memory: record failure
+                if (config.patterns.enabled) {
+                    const promptHash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+                    await recordPattern({
+                        promptHash,
+                        model,
+                        cost: 0,
+                        success: false,
+                    }).catch(() => { });
                 }
+                throw err;
             }
-            // k. Audit the failure
-            await audit
-                .appendEvent({
-                kind: "llm_call_failed",
-                actor: "local",
-                data: { model, error: String(err), transferId },
-            })
-                .catch(() => {
-                callAuditDegraded = true;
-            });
-            // l. Pattern memory: record failure
-            if (config.patterns.enabled) {
-                const promptHash = createHash("sha256").update(JSON.stringify(messages)).digest("hex");
-                await recordPattern({
-                    promptHash,
-                    model,
-                    cost: 0,
-                    success: false,
-                }).catch(() => { });
-            }
-            throw err;
+        }
+        finally {
+            // AUD-462: Decrement in-flight count so destroy() knows when it's safe
+            inFlightCount--;
         }
     }
     // 8. Safety net: clean up on process exit if destroy() was never called
@@ -412,11 +504,23 @@ export async function trust(client, opts) {
             if (destroyed)
                 return;
             destroyed = true;
+            // AUD-462: Wait up to 5 seconds for in-flight calls to complete.
+            // After the deadline, proceed with teardown anyway.
+            const deadline = Date.now() + 5_000;
+            while (inFlightCount > 0 && Date.now() < deadline) {
+                await new Promise((r) => setTimeout(r, 50));
+            }
             // Remove beforeExit safety net
             if (beforeExitHandler != null) {
                 process.removeListener("beforeExit", beforeExitHandler);
                 beforeExitHandler = null;
             }
+            // AUD-461: Void any remaining pending transfers (best-effort).
+            // TigerBeetle auto-voids pending transfers after 300s, but
+            // explicit voiding releases holds immediately.
+            if (engine != null && typeof engine.voidAllPending === "function") {
+                await engine.voidAllPending();
+            }
             // Flush audit writes
             await audit.flush();
             // Release audit lock
@@ -496,6 +600,20 @@ async function createTBEngine(config) {
             await tbClient.voidTransfer(tbId);
             pendingMap.delete(transferId);
         },
+        // AUD-461: Void all remaining pending transfers on destroy.
+        // Best-effort — TigerBeetle auto-voids after 300s regardless.
+        async voidAllPending() {
+            const entries = [...pendingMap.entries()];
+            for (const [trustIdKey, tbTransferId] of entries) {
+                try {
+                    await tbClient.voidTransfer(tbTransferId);
+                }
+                catch {
+                    // Best-effort — ignore individual void failures
+                }
+                pendingMap.delete(trustIdKey);
+            }
+        },
         destroy() {
             tbClient.destroy();
         },