actual-mcp-server 0.16.5 → 0.16.6

package/README.md

@@ -774,7 +774,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.5 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.6 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/lib/ActualConnectionPool.js

@@ -386,7 +386,65 @@ class ActualConnectionPool {
      * the connection: in those cases the transport must survive.
      */
     async shutdownConnection(sessionId, opts = {}) {
+        // #392: acquire the api mutex, because this calls api.shutdown() on the PROCESS-GLOBAL
+        // singleton. Without it, the idle sweep or an explicit session close can tear the api down
+        // while ANOTHER session's operation is in flight inside the lock, and that operation then
+        // observes a torn-down api. Reproduced during #390's security review for the sibling cleanup
+        // site, which #390 fixed; these were the paths it left behind.
+        //
+        // NOT reentrant, so this variant is for callers that do NOT hold the lock. Callers that DO
+        // must call shutdownConnectionLocked directly; wrapping there would deadlock, and the symptom
+        // is a ~30s stall ended by #270's timeout rather than an obvious hang. The audit of which is
+        // which is recorded on shutdownConnectionLocked.
+        // #392 review (BLOCKING): the acquisition itself can REJECT. Since #393, taking the api lock
+        // settles any abandoned budget load and THROWS on timeout, so this wrapper gained a rejection
+        // path the old body never had (it was try/catch/finally end to end). Its callers are cleanup
+        // paths that do not expect one: `cleanupIdleConnections` is invoked from `setInterval`
+        // unawaited, and "abandoned budget load timed out" is not in `rejection-allowlist.ts`, so the
+        // escape reached `src/index.ts`'s unhandledRejection handler and called process.exit(1). That
+        // is the exact defect #393 fixed one level up in the write drain, reintroduced at a new
+        // acquisition site.
+        //
+        // So the acquisition is swallowed, matching the established pattern in the session-open
+        // cleanup above: cleanup must not fail louder than the thing it is cleaning up after.
+        // The entry is still torn down on that path, unless the caller asked for expiry to be
+        // re-checked and the session came back, which is the sweep's own contract. Tearing down
+        // matters because a stuck load must not make idle sessions un-evictable: the pool would fill
+        // to MAX_CONCURRENT_SESSIONS and start refusing new sessions with nothing in the log saying
+        // why. The unlocked shutdown in this handler is acceptable for a specific reason worth
+        // stating: while a registration is stuck, EVERY lock acquisition throws, so no operation can
+        // be running inside the lock at the moment this path fires.
+        await withApiLock(() => this.shutdownConnectionLocked(sessionId, opts)).catch(async (err) => {
+            logger.error(`[ConnectionPool] Could not acquire the api lock to shut down ${sessionId}; ` +
+                `tearing the entry down without it: ${err instanceof Error ? err.message : String(err)}`);
+            await this.shutdownConnectionLocked(sessionId, opts).catch(() => { });
+        });
+    }
+    /**
+     * The body of shutdownConnection, for callers that ALREADY hold the api mutex.
+     *
+     * #392 call-site audit, done explicitly rather than by inspection because the mutex is not
+     * reentrant and getting it wrong produces a stall that reads as a slow upstream server:
+     *
+     *   HOLDS the lock, so calls this variant:
+     *     - actual-adapter withActualApi pooled branch, infra-error drop
+     *     - actual-adapter withActualApiWrite, sync failure and infra-error drop
+     *     - actual-adapter processWriteQueue drain, sync failure and batch error
+     *   Does NOT hold it, so calls the wrapping shutdownConnection:
+     *     - actual-adapter switchBudget slow path (its own withApiLock block has closed by then)
+     *     - actualConnection.shutdownActualForSession (session close)
+     *     - this.cleanupIdleConnections (the idle sweep)
+     *     - this.shutdownAll
+     */
+    async shutdownConnectionLocked(sessionId, opts = {}) {
         const conn = this.connections.get(sessionId);
+        // #392 review: the idle sweep decides who is expired BEFORE waiting for the mutex, and that
+        // wait is no longer negligible. Re-checking here means a session that was touched while we
+        // queued keeps its connection instead of being closed mid-conversation.
+        if (opts.onlyIfExpired && conn && !this.isExpired(conn)) {
+            logger.debug(`[ConnectionPool] ${sessionId} was touched while waiting for the api lock; not evicting`);
+            return;
+        }
         if (!conn || !conn.initialized) {
             return;
         }
@@ -424,6 +482,16 @@ class ActualConnectionPool {
      * Shutdown the shared connection
      */
     async shutdownSharedConnection() {
+        // #392: same reasoning as shutdownConnection. Its only caller is shutdownAll, which does not
+        // hold the mutex.
+        await withApiLock(() => this.shutdownSharedConnectionLocked()).catch(async (err) => {
+            logger.error(`[ConnectionPool] Could not acquire the api lock to shut down the shared connection; ` +
+                `tearing it down without it: ${err instanceof Error ? err.message : String(err)}`);
+            await this.shutdownSharedConnectionLocked().catch(() => { });
+        });
+    }
+    /** The body of shutdownSharedConnection, for callers that already hold the api mutex. */
+    async shutdownSharedConnectionLocked() {
         if (!this.sharedConnection?.initialized) {
             return;
         }
@@ -500,7 +568,15 @@ class ActualConnectionPool {
                 // in the same window (#167). This is the path that previously drifted:
                 // the pool's autonomous timer removed an entry httpServer's separate
                 // timer knew nothing about.
-                await this.shutdownConnection(sessionId, { evict: true });
+                //
+                // #392 review: RE-CHECK expiry, because the decision above was taken before the lock and
+                // the eviction now waits for it. Before #392 that wait was effectively zero; since #378
+                // made drains sequential, one lock hold is the SUM of a batch's operations, so it is
+                // bounded only by batch length times ACTUAL_OP_TIMEOUT_MS. A session that was idle when
+                // marked can be active again by the time the lock arrives, and evicting it then closes
+                // its transport mid-conversation. Deciding and acting on the same side of the mutex is
+                // what makes the decision mean anything.
+                await this.shutdownConnection(sessionId, { evict: true, onlyIfExpired: true });
             }
         }
     }

package/dist/src/lib/actual-adapter.js

@@ -23,7 +23,7 @@ import { requestContext } from './requestContext.js';
 import { connectionPool } from './ActualConnectionPool.js';
 import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, setLoadedBudgetSyncId } from './apiState.js';
 import { withApiLock } from './apiLock.js';
-import { loadBudgetTracked } from './budgetLoader.js';
+import { loadBudgetTracked, importBudgetTracked } from './budgetLoader.js';
 /**
  * Budget registry — all budgets configured via ACTUAL_* and BUDGET_n_* env vars.
  * Built once at startup; used by every withActualApi call.
@@ -347,8 +347,9 @@ export async function withActualApi(rawOperation) {
                 // re-introduce the auth-burst pattern #134 is fixing.
                 if (_shouldDropPoolOnError(err)) {
                     logger.warn(`[ADAPTER] Releasing pool connection for session ${sessionId} after infrastructure-level error`);
+                    // #392: Locked variant. We are INSIDE withApiLock here; the wrapping one would deadlock.
                     try {
-                        await connectionPool.shutdownConnection(sessionId);
+                        await connectionPool.shutdownConnectionLocked(sessionId);
                     }
                     catch (_e) { /* swallow */ }
                 }
@@ -407,8 +408,9 @@ export async function withActualApiWrite(operation) {
                     // Sync failure on a write IS infrastructure-level — drop the pool
                     // connection so the next call re-inits, then surface the error.
                     logger.error(`[ADAPTER] api.sync() failed after write in session ${sessionId}; releasing pool connection`);
+                    // #392: Locked variant. We are INSIDE withApiLock here; the wrapping one would deadlock.
                     try {
-                        await connectionPool.shutdownConnection(sessionId);
+                        await connectionPool.shutdownConnectionLocked(sessionId);
                     }
                     catch (_e) { /* swallow */ }
                     throw syncErr;
@@ -421,8 +423,9 @@ export async function withActualApiWrite(operation) {
                 // leave the connection fine.
                 if (_shouldDropPoolOnError(err)) {
                     logger.warn(`[ADAPTER] Releasing pool connection for write session ${sessionId} after infrastructure-level error`);
+                    // #392: Locked variant. We are INSIDE withApiLock here; the wrapping one would deadlock.
                     try {
-                        await connectionPool.shutdownConnection(sessionId);
+                        await connectionPool.shutdownConnectionLocked(sessionId);
                     }
                     catch (_e) { /* swallow */ }
                 }
@@ -871,10 +874,12 @@ async function processWriteQueue() {
                             // the batch ran concurrently and a drain was bounded by roughly one
                             // ACTUAL_OP_TIMEOUT_MS. Sequential dispatch makes a drain's wall clock the SUM of
                             // its ops, so a batch of slow ops can now outlive SESSION_IDLE_TIMEOUT_MINUTES
-                            // (default 5) and be swept mid-drain. The sweep's shutdownConnection calls
-                            // api.shutdown() WITHOUT holding withApiLock, which is the same hazard this file
-                            // already documents as the reason stdio is kept off the pool: it tears the
-                            // singleton down underneath an in-flight operation.
+                            // (default 5) and be swept mid-drain. The sweep would then evict the session and
+                            // fire its eviction listeners, closing the transport under a drain that is still
+                            // running. Since #392 the sweep takes the api mutex and re-checks expiry, so it can
+                            // no longer tear the singleton down mid-operation, but an unrefreshed entry is still
+                            // MARKED expired, so the touch below is what keeps an active session out of the
+                            // sweep's list at all.
                             //
                             // THIS MUST STAY INSIDE THE LOOP. A single touch at drain start does nothing for
                             // a drain whose wall clock is the SUM of its ops, which is the entire reason the
@@ -909,7 +914,9 @@ async function processWriteQueue() {
                         if (usePoolBranch && _shouldDropPoolOnError(syncError)) {
                             logger.warn(`[WRITE QUEUE] Releasing pool connection for session ${batchSessionId} after sync failure`);
                             try {
-                                await connectionPool.shutdownConnection(batchSessionId);
+                                // #392: Locked variant; the drain holds withApiLock across this whole block, and
+                                // the mutex is not reentrant, so the wrapping variant would deadlock here.
+                                await connectionPool.shutdownConnectionLocked(batchSessionId);
                             }
                             catch (_e) {
                                 /* swallow */
@@ -942,7 +949,9 @@ async function processWriteQueue() {
                     if (usePoolBranch) {
                         if (_shouldDropPoolOnError(error)) {
                             try {
-                                await connectionPool.shutdownConnection(batchSessionId);
+                                // #392: Locked variant; the drain holds withApiLock across this whole block, and
+                                // the mutex is not reentrant, so the wrapping variant would deadlock here.
+                                await connectionPool.shutdownConnectionLocked(batchSessionId);
                             }
                             catch (_e) {
                                 /* swallow */
@@ -2684,8 +2693,9 @@ export async function switchBudget(name) {
     // init/shutdown cycle. A pooled entry for stdio would be created here and then
     // NEVER refreshed, because connectionPool.touch() is called only from
     // httpServer.ts; it would expire after SESSION_IDLE_TIMEOUT_MINUTES and
-    // cleanupIdleConnections would api.shutdown() it WITHOUT holding withApiLock,
-    // which can tear the singleton down underneath an in-flight operation. The
+    // cleanupIdleConnections would tear it down. Since #392 that teardown takes the api mutex and
+    // re-checks expiry, so it is no longer a mid-operation hazard, but an entry that is never
+    // refreshed still expires, and that is the reason that matters here. The
     // legacy path re-reads getActiveBudgetConfig() on every call, so the switch
     // still takes effect; it just costs an init per operation, which is what stdio
     // already did before this ticket.
@@ -2874,20 +2884,29 @@ export async function exportBudget() {
 export async function importBudget(input, opts = {}) {
     observability.incrementToolCall('actual.budgets.import').catch(() => { });
     const result = await queueWriteOperation(async () => {
-        const imported = await withConcurrency(() => retry(() => rawImportBudget(input, opts), {
-            retries: 0,
-            backoffMs: 200,
-            isRetryable: isRetryableError,
-        }));
-        // #390: an import CHANGES the loaded budget (upstream documents importBudget as "loads the
-        // imported budget"), and the singleton's record kept naming the pre-import one. That is the
-        // unsafe direction: the precondition compares against it, passes, and a session then reads
-        // the imported file while believing it is on its own budget. A sentinel rather than a real
-        // syncId, because an imported file is outside the budget registry and outside the ACL, so
-        // no session can ever legitimately match it and every session's next operation re-selects
-        // its own budget. Recorded AT the call site so the guard in
-        // tests/unit/budget_selection_precondition.test.js can see it.
-        setLoadedBudgetSyncId(`imported:${imported.id}`);
+        // #394: an import re-points the process-global singleton exactly as a download does, so it
+        // gets the SAME tracking discipline, through the same helper, rather than a hand-written
+        // approximation of it.
+        //
+        // What was wrong before: nothing cleared the record before the import started, nothing
+        // registered the promise, and the sentinel was written AFTER the await, so a timeout skipped
+        // it entirely. A large YNAB or zip import exceeding ACTUAL_OP_TIMEOUT_MS is the expected case,
+        // not a rare one. The record therefore went on naming the PRE-IMPORT budget while the
+        // singleton moved to an out-of-registry, un-ACL'd imported file, and a victim session passed
+        // the #390 precondition legitimately and had its reads served from the importer's file.
+        //
+        // #390 still holds at this call site: `importBudgetTracked` records the `imported:` sentinel
+        // when the promise settles, whichever way, and the clear below states the same fact at the
+        // call site where the guard in tests/unit/budget_selection_precondition.test.js can see it.
+        const imported = await importBudgetTracked(() => {
+            const started = withConcurrency(() => retry(() => rawImportBudget(input, opts), {
+                retries: 0,
+                backoffMs: 200,
+                isRetryable: isRetryableError,
+            }));
+            setLoadedBudgetSyncId(null);
+            return started;
+        });
         return imported;
     });
     // #349: an import CHANGES WHICH BUDGET IS LOADED, so the pool's record of it

package/dist/src/lib/budgetLoader.js

@@ -154,6 +154,23 @@ function scrubReason(prose) {
  * so putting two network calls in there would extend the window in which unrelated sessions' lock
  * acquisitions throw, to build a message an abandoned load has no caller to read.
  */
+/**
+ * #404: the cached reason is re-derived every REDIAGNOSE_AFTER_USES failures.
+ *
+ * The cache exists because `diagnose()` runs INSIDE the process-global api mutex and makes two
+ * bounded network calls, so re-running it per failed tool call stalls unrelated sessions. But an
+ * entry was previously dropped only by a genuinely successful load or a process restart, so if a
+ * budget's failure MODE changed with no success in between, the message reported the first reason
+ * indefinitely.
+ *
+ * Bounding by USES rather than by wall-clock is deliberate: the cost this cache avoids is paid per
+ * CALL, so capping in calls bounds staleness in the same unit, needs no clock, and is
+ * deterministic under test. At 20, a persistent failure pays the diagnosis roughly 5 percent of
+ * the time (the saving the cache exists for is kept) while no operator can see a stale reason for
+ * more than 20 failed calls. The fail-closed DECISION is still never cached: every call
+ * re-attempts the load and still fails.
+ */
+const REDIAGNOSE_AFTER_USES = 20;
 const reasonCache = new Map();
 /** A load that genuinely succeeded clears any cached reason for that budget. */
 function clearCachedReason(syncId) {
@@ -177,8 +194,18 @@ async function diagnose(syncId) {
     // precisely the cost this memo exists to remove.
     const cached = reasonCache.get(syncId);
     if (cached !== undefined) {
-        log.debug('reusing the cached load-failure reason', { syncId });
-        return cached || undefined;
+        cached.uses += 1;
+        if (cached.uses <= REDIAGNOSE_AFTER_USES) {
+            log.debug('reusing the cached load-failure reason', { syncId, uses: cached.uses });
+            return cached.reason || undefined;
+        }
+        // #404: the entry has served its budget of calls. Drop it and fall through to a fresh
+        // diagnosis, so a failure mode that changed without an intervening success is picked up.
+        reasonCache.delete(syncId);
+        log.debug('re-diagnosing the load failure after the cached reason served its budget', {
+            syncId,
+            afterUses: REDIAGNOSE_AFTER_USES,
+        });
     }
     try {
         const budgets = (await withOpTimeout(() => api.getBudgets(), 'diagnose getBudgets'));
@@ -190,7 +217,7 @@ async function diagnose(syncId) {
         if (!local) {
             // Deliberately does NOT list what IS available: that would enumerate every budget on the
             // server to a caller the ACL scopes to one.
-            reasonCache.set(syncId, NO_LOCAL_COPY);
+            reasonCache.set(syncId, { reason: NO_LOCAL_COPY, uses: 0 });
             return NO_LOCAL_COPY;
         }
         const localId = local.id;
@@ -228,7 +255,7 @@ async function diagnose(syncId) {
             // `.code` outside KNOWN_LOAD_REASONS and path-shaped prose that `scrubReason` drops, so it
             // yields `undefined`, and that is the ticket's own reproduced "db.sqlite is not a database"
             // case: the one most likely to persist. Storing '' records "diagnosed" without reporting.
-            reasonCache.set(syncId, reason ?? '');
+            reasonCache.set(syncId, { reason: reason ?? '', uses: 0 });
             return reason;
         }
     }
@@ -247,45 +274,122 @@ function postConditionError(syncId, reason) {
         `this), and a local budget copy that cannot be opened (check the directory configured by ` +
         `MCP_BRIDGE_DATA_DIR, and note that two server processes sharing one data dir will do this).`);
 }
-export async function loadBudgetTracked(syncId, encryptionPassword, label = 'downloadBudget') {
-    const raw = encryptionPassword
-        ? api
-            .downloadBudget(syncId, { password: encryptionPassword })
-        : api.downloadBudget(syncId);
+/**
+ * The tracking discipline EVERY singleton-mutating load must follow (#390, #393, #394).
+ *
+ * Extracted so the two callers cannot drift. `downloadBudget` and `importBudget` are different
+ * upstream calls with different failure shapes, but the discipline is identical and getting it
+ * subtly different at one site is exactly how #390 stayed reachable for three rounds:
+ *
+ *   1. Clear the record BEFORE starting, so an abandonment can only leave it INDETERMINATE.
+ *      That is the safe direction: it forces a re-select. Recording only on success leaves the
+ *      record naming the PREVIOUS budget while the singleton moves to a new one, which is the one
+ *      direction that makes the #390 precondition silently pass.
+ *   2. Register the promise, so a late landing is WAITED FOR by the next lock acquisition rather
+ *      than discovered mid-operation. `withOpTimeout` races; it does not cancel.
+ *   3. Record the true outcome when it settles, whether or not anyone is still listening, and
+ *      poison the singleton on failure, because upstream closes the current budget before opening
+ *      the new one, so "failed" does not mean "unchanged".
+ *
+ * `verify` is #396's post-condition, and it runs BEFORE the record is written, so the record can
+ * only ever describe a mutation that actually took effect.
+ */
+async function trackBudgetMutation(start, describeLoaded, label, verify, onRecorded) {
+    const raw = start();
     // Indeterminate from here until it settles. Cleared first, deliberately.
     setLoadedBudgetSyncId(null);
-    // #396: `.then(onFulfilled).catch(onRejected)`, NOT the two-argument `.then`. A throw from the
-    // `onFulfilled` argument of `.then(onFulfilled, onRejected)` is NOT caught by that same
-    // `onRejected`, so with the old shape a probe failure would skip the fail-closed
-    // `setApiInitialized(false)` below: exactly the new failure path this adds.
-    //
-    // The probe lives INSIDE this chain so an ABANDONED load is verified when it lands, rather than
-    // recording a false success nobody checked. The network enrichment deliberately does not.
     const tracked = raw
-        .then(async () => {
-        await assertBudgetOpen();
-        setLoadedBudgetSyncId(syncId);
-        clearCachedReason(syncId);
+        .then(async (result) => {
+        if (verify)
+            await verify();
+        setLoadedBudgetSyncId(describeLoaded(result));
+        // #392 review (finding 5): this runs INSIDE the chain, not after the awaited call. On the
+        // abandoned-then-eventually-successful path the caller has already thrown, so a hook placed
+        // after the await would never run and the cached failure reason would outlive the load that
+        // actually succeeded.
+        // Wrapped: a hook cannot be allowed to change the recorded outcome. Unwrapped, a throwing
+        // hook would be caught by the trailing .catch, reported as a load failure, and would leave
+        // the record written while setApiInitialized(false) says the singleton is dead: an
+        // incoherent pair rather than a fail-safe one.
+        try {
+            onRecorded?.();
+        }
+        catch (hookErr) {
+            log.warn('post-record hook threw; the recorded outcome stands', { error: String(hookErr) });
+        }
+        return result;
     })
         .catch((err) => {
         // A failed load leaves the singleton in a state nobody can describe: upstream's
-        // download handler closes the current budget before opening the new one, so "failed"
-        // does not mean "unchanged". Poison it so the next operation re-inits from scratch.
+        // download and import handlers both close the current budget before opening the new one,
+        // so "failed" does not mean "unchanged". Poison it so the next operation re-inits.
         setApiInitialized(false);
         throw err;
     });
     registerBudgetLoad(tracked);
+    // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
+    // waits for it inside the lock rather than racing it.
+    return await withOpTimeout(() => tracked, label);
+}
+/**
+ * #394: the same discipline for an IMPORT.
+ *
+ * Upstream's `importBudget` LOADS the imported budget, so it re-points the process-global
+ * singleton exactly as a download does, and a large YNAB or zip import exceeding
+ * ACTUAL_OP_TIMEOUT_MS is the expected case rather than a rare one. Before this, nothing cleared
+ * the record before it started, nothing registered the promise, and the sentinel was written
+ * AFTER the await, so a timeout skipped it entirely and the record went on naming the PRE-IMPORT
+ * budget while the singleton moved to an out-of-registry, un-ACL'd file. A victim session then
+ * passed the #390 precondition legitimately and had its reads served from the importer's file.
+ *
+ * ACCEPTED COST, recorded because nothing else states it. Registering the import means every
+ * subsequent `withApiLock` acquisition waits for it, bounded, and throws on timeout. An import is
+ * not "stuck", it is legitimately long: a large YNAB or zip import can run for minutes. So while
+ * one runs past ACTUAL_OP_TIMEOUT_MS, other sessions stall for that bound and then fail with
+ * "abandoned budget load timed out", and write drains reject their batch. That is a strictly
+ * better failure than the silent cross-tenant read it replaces (a victim reading the importer's
+ * un-ACL'd file), and it is the same trade #393 accepted for downloads. It is NOT free, and the
+ * operator-facing consequence is a process-wide stall for the duration of one tenant's import.
+ * Giving imports their own larger bound is tracked separately rather than bolted on here.
+ *
+ * No `verify` here, deliberately: unlike `download-budget`, upstream's `importBudget` already
+ * asserts its own post-condition. It checks `result.error` and then `!result.id`, throwing
+ * "no budget was loaded", so it cannot resolve without having loaded something. Verified in the
+ * shipped upstream source. Adding a probe would be duplicate work on the write path.
+ */
+export async function importBudgetTracked(start, label = 'importBudget') {
+    // A sentinel rather than a real syncId: an imported file is outside the budget registry and
+    // outside the ACL, so no session can ever legitimately match it and every session's next
+    // operation re-selects its own budget. Configured sync ids are UUIDs, so an `imported:` prefix
+    // can never compare equal to one.
+    return trackBudgetMutation(start, (result) => `imported:${result.id}`, label);
+}
+export async function loadBudgetTracked(syncId, encryptionPassword, label = 'downloadBudget') {
     try {
-        await withOpTimeout(() => tracked, label);
-        // #393 review (P3-4): NOT clearBudgetLoad(tracked). `registerBudgetLoad` registers a
-        // derived promise, not this handle, so that delete could never match and read as a working
-        // belt-and-braces path a later change might lean on. Self-removal on settle is what
-        // actually deregisters a completed load, and it has already happened by the time the
-        // awaited promise resolves here.
+        await trackBudgetMutation(() => {
+            const started = encryptionPassword
+                ? api
+                    .downloadBudget(syncId, { password: encryptionPassword })
+                : api.downloadBudget(syncId);
+            // Indeterminate from the moment the download starts. `trackBudgetMutation` clears the
+            // record too; this repeats it at the CALL SITE on purpose, AFTER the call, because block
+            // (4) of tests/unit/budget_selection_precondition.test.js scans FORWARD from the matched
+            // line to the end of its brace-balanced block and requires a record there. Satisfying
+            // that structurally, rather than exempting this file from the guard, is what keeps the
+            // #390 protection worth having.
+            setLoadedBudgetSyncId(null);
+            return started;
+        }, () => syncId, label, 
+        // #396: the post-condition runs INSIDE the tracked chain, before the record is written, so
+        // an ABANDONED load is verified when it lands rather than recording a success nobody
+        // checked. The network enrichment below deliberately does NOT run there.
+        assertBudgetOpen, () => clearCachedReason(syncId));
     }
     catch (err) {
-        // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
-        // waits for it inside the lock rather than racing it.
+        // Enrich HERE, where a caller is actually waiting. Every `withApiLock` acquisition settles
+        // all registrations under ONE bound and fails closed on timeout, so two network calls inside
+        // the tracked chain would extend the window in which unrelated sessions' lock acquisitions
+        // throw, to build a message an abandoned load has no caller to read.
         if (isBudgetNotOpen(err)) {
             log.error('download resolved but no budget is open', undefined, { syncId });
             throw postConditionError(syncId, await diagnose(syncId));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.5",
+  "version": "0.16.6",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/generated_tools.smoke.test.js && node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/budgets_hold_for_next_month.test.js && node tests/unit/budgets_transfer.test.js && node tests/unit/transactions_uncategorized.test.js && node tests/unit/httpServer_session_init.test.js && node tests/unit/httpServer_session_not_found.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/budget_preference_store.test.js && node tests/unit/budget_preference_restore.test.js && node tests/unit/tags_list.test.js && node tests/unit/tags_create.test.js && node tests/unit/tags_update.test.js && node tests/unit/tags_delete.test.js && node tests/unit/notes_get.test.js && node tests/unit/notes_update.test.js && node tests/unit/payees_common_list.test.js && node tests/unit/transactions_update_guard.test.js && node tests/unit/transactions_update_splits.test.js && node tests/unit/entities_search.test.js && node tests/unit/transactions_import_schema.test.js && node tests/unit/tool_schema_shape.test.js && node tests/unit/zod_error_format.test.js && node tests/unit/tool_count_sync.test.js && node tests/unit/stdio_transport.test.js && node tests/unit/stdio_budget_switch.test.js && node tests/unit/logger_structured.test.js && node tests/unit/logger_redaction.test.js && node tests/unit/logger_correlation.test.js && node tests/unit/check_coverage.test.js && node tests/unit/adapter_op_timeout.test.js && node tests/unit/adapter_write_queue_wakeup.test.js && node tests/unit/ci_workflow_guards.test.js && node tests/unit/node_version_guard.test.js && node tests/unit/node_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/dual_transport_gate.test.js && node tests/unit/manual_assertions_use_helper.test.js && node tests/unit/server_version_guard.test.js && node tests/unit/payee_rules_reference_filter.test.js && node tests/unit/oidc_metadata_discovery.test.js && node tests/unit/httpServer_oauth_metadata_route.test.js && node tests/unit/httpServer_mcp_info_route.test.js && node tests/unit/residue_sweep_balance_account.test.js && node tests/unit/tool_factory.test.js && node tests/unit/budget_registry_parse.test.js && node tests/unit/preferences_get.test.js && node tests/unit/budgets_export.test.js && node tests/unit/budgets_import.test.js && node tests/unit/budgets_import_syncid.test.js && node tests/unit/budget_acl_dynamic.test.js && node tests/unit/budget_acl_identity_map.test.js && node tests/unit/budget_acl_userinfo.test.js && node tests/unit/acl_e2e_fixture_contract.test.js && node tests/unit/budget_acl_middleware.test.js && node tests/unit/rules_stage.test.js",
     "test:adapter": "npm run build && node dist/src/tests_adapter_runner.js",
     "test:e2e": "npx playwright test",
     "test:e2e:docker": "./tests/e2e/run-docker-e2e.sh",