actual-mcp-server 0.16.2 → 0.16.5

package/README.md

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

package/dist/src/actualConnection.js

@@ -2,6 +2,9 @@ import fs from 'fs';
 import path from 'path';
 import os from 'os';
 import api from '@actual-app/api';
+import { loadBudgetTracked } from './lib/budgetLoader.js';
+import { withApiLock } from './lib/apiLock.js';
+import { withOpTimeout } from './lib/opTimeout.js';
 import logger from './logger.js';
 import config from './config.js';
 import { connectionPool } from './lib/ActualConnectionPool.js';
@@ -24,6 +27,11 @@ export async function connectToActual() {
         return;
     }
     initializing = true;
+    // #396: reset before each attempt. It was set on failure and NEVER cleared, so once the
+    // silent-success bug is fixed and a bad load throws routinely, a single failure would poison
+    // every later session open for the process lifetime: a concurrent caller arriving while
+    // `initializing` is true rethrows whatever was left here.
+    initializationError = null;
     try {
         const SERVER_URL = config.ACTUAL_SERVER_URL;
         const PASSWORD = config.ACTUAL_PASSWORD;
@@ -36,20 +44,35 @@ export async function connectToActual() {
         if (!fs.existsSync(DATA_DIR))
             fs.mkdirSync(DATA_DIR, { recursive: true });
         log.info(`Initializing Actual API with dataDir=${DATA_DIR}`);
-        await api.init({
-            dataDir: DATA_DIR,
-            serverURL: SERVER_URL,
-            password: PASSWORD,
+        // #396: this is the SIXTH budget load site, and it is production reachable. Revision 0 of
+        // that ticket claimed it was `--test-actual-connection` only; it is not.
+        // `connectToActualForSession` below falls through to this function whenever
+        // USE_CONNECTION_POOL=false (a documented, supported variable), and httpServer calls it on
+        // every HTTP session open. It used to hand-write the download and record the loaded syncId
+        // UNCONDITIONALLY, so it had none of the guarantees the other five sites have.
+        //
+        // The lock is acquired HERE, around init plus load only, mirroring
+        // ActualConnectionPool.getConnection. Never around the `while (initializing)` spin-wait
+        // above: that would hold the mutex while waiting for its holder and deadlock. No caller of
+        // this function holds the api lock, so this acquisition is safe.
+        //
+        // This is NOT behaviour neutral, and that is intended: the download becomes bounded by
+        // ACTUAL_OP_TIMEOUT_MS with abandon-not-cancel semantics, and becomes a registered load that
+        // later lock acquisitions wait for. Both match what the pool sites already do.
+        await withApiLock(async () => {
+            // #396 review: BOUND the init. It was unbounded here before, which was survivable only
+            // because this call held no lock. Now that it does, an unbounded stalled login would never
+            // settle, `.finally(release)` would never run, and the process-global api mutex would be
+            // wedged permanently for every session: the exact #270 class. Both pool sites already bound
+            // their `api.init` this way, and this was the only `api.init` in the repo that did not.
+            await withOpTimeout(() => api.init({
+                dataDir: DATA_DIR,
+                serverURL: SERVER_URL,
+                password: PASSWORD,
+            }), 'connectToActual init');
+            log.info(`Downloading budget with sync ID: ${BUDGET_SYNC_ID}`);
+            await loadBudgetTracked(BUDGET_SYNC_ID, BUDGET_PASSWORD);
         });
-        log.info(`Downloading budget with sync ID: ${BUDGET_SYNC_ID}`);
-        // According to official docs, downloadBudget accepts optional second parameter for E2E encryption
-        if (BUDGET_PASSWORD) {
-            const apiWithOptions = api;
-            await apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD });
-        }
-        else {
-            await api.downloadBudget(BUDGET_SYNC_ID);
-        }
         if (TEST_ACTUAL_CONNECTION) {
             logger.info('Test flag detected (--test-actual-connection) — closing Actual session.');
             // Prefer the documented shutdown method only

package/dist/src/lib/ActualConnectionPool.js

@@ -17,6 +17,8 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { isApiInitialized, setApiInitialized } from './apiState.js';
+import { withApiLock } from './apiLock.js';
+import { loadBudgetTracked } from './budgetLoader.js';
 import { withOpTimeout } from './opTimeout.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
 class ActualConnectionPool {
@@ -237,27 +239,40 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            // Bound the session-open init/download (#270): this is the HTTP exposure.
-            // A stalled upstream here would otherwise hang session open unbounded and,
-            // because the api singleton is process-global, wedge other sessions too.
-            await withOpTimeout(() => api.init({
-                dataDir: DATA_DIR,
-                serverURL: SERVER_URL,
-                password: PASSWORD,
-            }), 'pool init');
-            logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
-            if (BUDGET_PASSWORD) {
-                const apiWithOptions = api;
-                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
-            }
-            else {
-                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
-            }
-            // Mark the singleton as live only AFTER the budget is downloaded (#270):
-            // setting it before downloadBudget left a poisoning window where the
-            // adapter's pool-cooperation branch could reuse a connection whose budget
-            // never loaded (a stalled/failed download would leak isApiInitialized=true).
-            setApiInitialized(true);
+            // #390 round 2: hold the api mutex across init + download.
+            //
+            // Recording the loaded budget and checking it inside the lock only NARROWED the race
+            // while this mutator stayed outside it. Reproduced: a pooled read passed the
+            // precondition, parked at an await still holding the lock, a new session opened here on
+            // a different budget, and the first session's raw call then executed against it. The
+            // window is not small: it is the whole duration of an operation, and since #378 made the
+            // drain sequential, the whole duration of a batch, with one check at the start.
+            //
+            // Safe against the non-reentrant mutex: the two callers of getConnection
+            // (actualConnection's session-open helper and switchBudget's slow path) are both OUTSIDE
+            // any withApiLock block. switchBudget's own downloadBudget takes the lock separately and
+            // has already released it before it reaches here.
+            await withApiLock(async () => {
+                // Bound the session-open init/download (#270): this is the HTTP exposure.
+                // A stalled upstream here would otherwise hang session open unbounded and,
+                // because the api singleton is process-global, wedge other sessions too.
+                await withOpTimeout(() => api.init({
+                    dataDir: DATA_DIR,
+                    serverURL: SERVER_URL,
+                    password: PASSWORD,
+                }), 'pool init');
+                logger.info(`[ConnectionPool] Downloading budget for session: ${sessionId}`);
+                // #390: the shared tracked loader, not a hand-written download. It clears the record
+                // BEFORE starting and keeps an abandoned load registered, so a session-open download that
+                // outruns ACTUAL_OP_TIMEOUT_MS cannot silently re-point the singleton later.
+                await loadBudgetTracked(BUDGET_SYNC_ID, BUDGET_PASSWORD, 'pool downloadBudget');
+                // Mark the singleton as live only AFTER the budget is downloaded (#270):
+                // setting it before downloadBudget left a poisoning window where the
+                // adapter's pool-cooperation branch could reuse a connection whose budget
+                // never loaded (a stalled/failed download would leak isApiInitialized=true).
+                setApiInitialized(true);
+            }); // #390: end of the api-mutex block. Everything after this is pool bookkeeping and
+            // touches no singleton state, so it does not need the lock.
             conn = {
                 sessionId,
                 initialized: true,
@@ -276,17 +291,29 @@ class ActualConnectionPool {
         catch (err) {
             logger.error(`[ConnectionPool] Failed to initialize connection for session ${sessionId}:`, err);
             // Clean up the failed connection attempt
-            // Try to shutdown the API to leave it in a clean state for the next attempt
-            try {
+            // Try to shutdown the API to leave it in a clean state for the next attempt.
+            //
+            // #390 round 3: UNDER THE MUTEX, like the init above it. Locking the mutator and leaving
+            // its compensating mutator unlocked closes nothing: reproduced as this cleanup's
+            // api.shutdown() firing while ANOTHER session's operation was in flight inside the lock,
+            // so that operation observed a torn-down api. The lock is re-acquired rather than held
+            // across the whole try, because the init block released it on the way out and this
+            // function is never called from inside a lock (both callers are outside one).
+            // #393 review: the lock ITSELF can reject now (it settles an abandoned budget load on
+            // acquisition), and this is a CLEANUP path. If that rejection escaped, `setApiInitialized(false)`
+            // and the connections.delete below would be skipped and the caller would receive
+            // "abandoned budget load timed out" instead of the real session-open failure. Cleanup
+            // must not be able to fail louder than the thing it is cleaning up after, so the whole
+            // acquisition is swallowed here, not just the shutdown call.
+            await withApiLock(async () => {
                 const maybeApi = api;
                 if (typeof maybeApi.shutdown === 'function') {
                     await maybeApi.shutdown();
                     logger.debug(`[ConnectionPool] Cleaned up failed connection for session: ${sessionId}`);
                 }
-            }
-            catch (cleanupErr) {
+            }).catch((cleanupErr) => {
                 logger.debug(`[ConnectionPool] Error during cleanup (ignoring): ${cleanupErr}`);
-            }
+            });
             // Singleton is back to torn-down state regardless of cleanup outcome.
             setApiInitialized(false);
             // Ensure this session is not in the connections map
@@ -312,22 +339,23 @@ class ActualConnectionPool {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
         try {
-            // Bound the session-open init/download (#270), same as getConnection.
-            await withOpTimeout(() => api.init({
-                dataDir: DATA_DIR,
-                serverURL: SERVER_URL,
-                password: PASSWORD,
-            }), 'pool init');
-            if (BUDGET_PASSWORD) {
-                const apiWithOptions = api;
-                await withOpTimeout(() => apiWithOptions.downloadBudget(BUDGET_SYNC_ID, { password: BUDGET_PASSWORD }), 'pool downloadBudget');
-            }
-            else {
-                await withOpTimeout(() => api.downloadBudget(BUDGET_SYNC_ID), 'pool downloadBudget');
-            }
-            // Mark live only after a successful download (#270): avoids the poisoning
-            // window where a stalled/failed download would leak isApiInitialized=true.
-            setApiInitialized(true);
+            // #390 round 2: same reasoning as getConnection above; this mutates the same
+            // process-global singleton, so it takes the same mutex.
+            await withApiLock(async () => {
+                // Bound the session-open init/download (#270), same as getConnection.
+                await withOpTimeout(() => api.init({
+                    dataDir: DATA_DIR,
+                    serverURL: SERVER_URL,
+                    password: PASSWORD,
+                }), 'pool init');
+                // #390: the shared tracked loader, not a hand-written download. It clears the record
+                // BEFORE starting and keeps an abandoned load registered, so a session-open download that
+                // outruns ACTUAL_OP_TIMEOUT_MS cannot silently re-point the singleton later.
+                await loadBudgetTracked(BUDGET_SYNC_ID, BUDGET_PASSWORD, 'pool downloadBudget');
+                // Mark live only after a successful download (#270): avoids the poisoning
+                // window where a stalled/failed download would leak isApiInitialized=true.
+                setApiInitialized(true);
+            }); // #390: end of the api-mutex block.
             this.sharedConnection = {
                 sessionId: 'shared',
                 initialized: true,

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

@@ -21,7 +21,9 @@ import { parseBudgetRegistry } from './budget-registry.js';
 import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
 import { requestContext } from './requestContext.js';
 import { connectionPool } from './ActualConnectionPool.js';
-import { isApiInitialized, setApiInitialized } from './apiState.js';
+import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, setLoadedBudgetSyncId } from './apiState.js';
+import { withApiLock } from './apiLock.js';
+import { loadBudgetTracked } from './budgetLoader.js';
 /**
  * Budget registry — all budgets configured via ACTUAL_* and BUDGET_n_* env vars.
  * Built once at startup; used by every withActualApi call.
@@ -86,12 +88,90 @@ function getActiveBudgetConfig() {
  * init/shutdown pairs corrupt the session.  All callers (reads via withActualApi,
  * writes via processWriteQueue) must acquire this lock before touching the API.
  */
-let _apiSessionLock = Promise.resolve();
-function withApiLock(fn) {
-    let release;
-    const prevLock = _apiSessionLock;
-    _apiSessionLock = new Promise(resolve => { release = resolve; });
-    return prevLock.then(() => fn()).finally(() => release());
+/**
+ * #390: make the loaded budget a CHECKED PRECONDITION of an operation rather than a side
+ * effect of whoever opened a session last.
+ *
+ * MUST be called inside the api lock. Outside it, another session can change the loaded budget
+ * between this check and the operation, which is the race this closes rather than narrows.
+ *
+ * The bug it fixes: `@actual-app/api` is process-global with ONE loaded budget, and both
+ * re-entry paths skip the download for good reasons of their own (`getConnection` returns
+ * early for an initialised entry; `initActualApiForOperation` returns early when the singleton
+ * is live, which is #134's fix for the #127 auth burst). Together they meant a session operated
+ * on whatever budget was loaded last, by anyone. Reproduced: session A opened on budget A and
+ * wrote to it, session B opened and switched to budget B, and session A's NEXT write landed in
+ * budget B.
+ *
+ * The budget ACL could not see this: `_enforceBudgetAcl` validates the budget the session
+ * BELIEVES it is on, while the operation executes against whatever is loaded, so the check and
+ * the effect were on different budgets.
+ *
+ * Cost in the common case is one string comparison. A single-budget deployment always resolves
+ * the same syncId, so nothing extra is downloaded and no upstream call is added.
+ */
+/**
+ * #390: make the loaded budget a CHECKED PRECONDITION of an operation rather than a side
+ * effect of whoever opened a session last.
+ *
+ * MUST be called inside the api lock. Outside it, another session can change the loaded budget
+ * between this check and the operation.
+ *
+ * The bug: `@actual-app/api` is process-global with ONE loaded budget, and both re-entry paths
+ * skip the download for good reasons of their own (`getConnection` returns early for an
+ * initialised entry; `initActualApiForOperation` returns early when the singleton is live,
+ * which is #134's fix for the #127 auth burst). Together they meant a session operated on
+ * whatever budget was loaded last, by anyone. The budget ACL could not see it: it validates the
+ * budget the session BELIEVES it is on while the operation executes against whatever is loaded.
+ *
+ * Cost in the common case is one string comparison; a single-budget deployment always resolves
+ * the same syncId and downloads nothing. The multi-budget cost is real and is tracked as #391.
+ */
+async function ensureLoadedBudgetMatchesSession() {
+    if (_skipApiInitForTests)
+        return;
+    // #393: no wait here any more. Settling an abandoned load is part of acquiring the api lock,
+    // and both callers of this function are already inside it. Guarding per call site is what
+    // produced the two P0s in #393; see withApiLock for why it moved.
+    if (!isApiInitialized()) {
+        // "The init path will download correctly" is true for the LEGACY branch and false for the
+        // POOLED one, which skips init entirely by design (#134). Returning here let a pooled
+        // operation run against a singleton nobody had loaded for it, which is how the abandoned-
+        // load test caught this: session B's failed session-open poisoned the singleton, A's
+        // precondition returned early on that, and A's raw call then ran while B's abandoned
+        // download landed. Initialise explicitly instead. No recursion: initActualApiForOperation
+        // only calls back into here when the singleton IS live, and it is not.
+        await initActualApiForOperation();
+        return;
+    }
+    const wanted = getActiveBudgetConfig();
+    const loaded = getLoadedBudgetSyncId();
+    if (loaded === wanted.syncId)
+        return;
+    // Deliberately a WARN: reaching here means two sessions are on different budgets and this
+    // one would otherwise have operated on the other's data.
+    logger.warn('[ADAPTER] loaded budget does not match this session; re-selecting before the operation', {
+        loadedSyncId: loaded ?? null,
+        wantedSyncId: wanted.syncId,
+        budget: wanted.name,
+    });
+    // Push anything pending for the budget we are about to close. Since #390 made re-selection
+    // per operation, a drain can now change budgets MID-BATCH, and the single trailing api.sync()
+    // covers only the last one. Without this, an earlier session's write is applied locally and
+    // silently waits for the next load of that budget to propagate, which an ephemeral data dir
+    // would lose entirely.
+    if (loaded) {
+        try {
+            await withOpTimeout(() => api.sync(), 'sync');
+        }
+        catch (syncErr) {
+            logger.warn('[ADAPTER] could not sync the outgoing budget before re-selecting', {
+                loadedSyncId: loaded,
+                error: syncErr instanceof Error ? syncErr.message : String(syncErr),
+            });
+        }
+    }
+    await loadBudgetTracked(wanted.syncId, wanted.encryptionPassword);
 }
 // Per-op timeout (#270) lives in ./opTimeout.ts so ActualConnectionPool can bound
 // its own session-open init/download without a circular import back into this
@@ -255,6 +335,9 @@ export async function withActualApi(rawOperation) {
             try {
                 connectionReuseCount++;
                 logger.debug(`[ADAPTER] Reusing pool connection for session ${sessionId} (reuses=${connectionReuseCount})`);
+                // #390: verify the singleton holds THIS session's budget before the operation runs.
+                // Inside the lock, so no other session can change it in between.
+                await ensureLoadedBudgetMatchesSession();
                 return await withOpTimeout(operation);
             }
             catch (err) {
@@ -308,6 +391,9 @@ export async function withActualApiWrite(operation) {
             try {
                 connectionReuseCount++;
                 logger.debug(`[ADAPTER] Reusing pool connection for write session ${sessionId} (reuses=${connectionReuseCount})`);
+                // #390: verify the singleton holds THIS session's budget before the operation runs.
+                // Inside the lock, so no other session can change it in between.
+                await ensureLoadedBudgetMatchesSession();
                 const result = await withOpTimeout(operation);
                 // Propagate the write to the server so other clients (and our next
                 // read) see it. Pre-#134 this happened implicitly via api.shutdown().
@@ -423,6 +509,9 @@ async function initActualApiForOperation() {
         setApiInitialized(true);
         return;
     }
+    // #393: the wait that used to be here moved into withApiLock. "Every path to the api has to
+    // settle it" was the right conclusion and the wrong implementation: enumerating paths is what
+    // kept missing one.
     // If the api singleton is already live (e.g. the connection pool initialised
     // it at MCP session open), don't redundantly call api.init() again — that
     // would trigger an extra upstream login and reintroduce the auth-burst
@@ -430,6 +519,17 @@ async function initActualApiForOperation() {
     // we just join in.
     if (isApiInitialized()) {
         logger.debug('[ADAPTER] api already initialised; skipping redundant init');
+        // #390 round 2: skipping the init is right (that is #134's fix for the #127 auth burst),
+        // but it also skips the downloadBudget that would have selected THIS session's budget. The
+        // legacy branch therefore leaked in both directions and, unlike the pooled branch, silently:
+        // reproduced as session A receiving session B's account list with no warning at all. It is
+        // reachable in ordinary HTTP operation because httpServer deliberately keeps an MCP session
+        // serving after its pool entry is dropped, and shutdownActualApi's sync-only branch leaves
+        // the singleton live whenever any other session still holds an entry.
+        //
+        // Checking HERE covers every legacy caller in one place: both withActualApi branches,
+        // withActualApiWrite, and the drain's legacy branch.
+        await ensureLoadedBudgetMatchesSession();
         return;
     }
     try {
@@ -452,14 +552,7 @@ async function initActualApiForOperation() {
         // Bound downloadBudget (#270): the legacy stdio path re-downloads on every
         // op, and a stall here was the production hang. On timeout it rejects and
         // the mutex releases.
-        if (budget.encryptionPassword) {
-            const encryptionPassword = budget.encryptionPassword;
-            const apiWithOptions = api;
-            await withOpTimeout(() => apiWithOptions.downloadBudget(budget.syncId, { password: encryptionPassword }), 'downloadBudget');
-        }
-        else {
-            await withOpTimeout(() => api.downloadBudget(budget.syncId), 'downloadBudget');
-        }
+        await loadBudgetTracked(budget.syncId, budget.encryptionPassword);
         setApiInitialized(true);
         logger.debug('[ADAPTER] Actual API initialized for operation');
     }
@@ -734,9 +827,26 @@ async function processWriteQueue() {
                     //
                     // Each op keeps its own withOpTimeout (#270) and still settles individually, so one
                     // stalled or rejected operation cannot hold the api mutex or fail its siblings.
-                    for (const { operation, resolve, reject, preservesListings } of batch) {
+                    for (const { operation, resolve, reject, preservesListings, requestStore } of batch) {
                         try {
-                            const result = await withOpTimeout(operation);
+                            // #390 round 2: run each op in the context it was ENQUEUED in.
+                            //
+                            // The precondition was originally checked ONCE per drain, against the ambient
+                            // context. That was wrong twice over. A batch can span sessions, so one check for
+                            // it is not well defined; and the ambient context here is NOT empty. The
+                            // long-standing comment on scheduleWriteQueueDrain claims "setTimeout strips the
+                            // ALS frame", and that is simply false: ALS propagates through timers, so the
+                            // drain inherits the context of whichever session most recently scheduled it,
+                            // which is the last enqueuer in the debounce window and is unrelated to this
+                            // operation. Reproduced: with A and B on different budgets writing in one window,
+                            // A's write landed in B's budget, and in the other ordering the precondition
+                            // actively re-pointed the singleton at the wrong session, making a write that had
+                            // been correct wrong. Re-entering the captured store makes each op resolve its own
+                            // budget, which is what #158 captured a per-entry sessionId for in the first place.
+                            const result = await requestContext.run(requestStore ?? {}, async () => {
+                                await ensureLoadedBudgetMatchesSession();
+                                return await withOpTimeout(operation);
+                            });
                             resolve(result);
                         }
                         catch (error) {
@@ -846,6 +956,31 @@ async function processWriteQueue() {
             });
         });
     }
+    catch (lockError) {
+        // #393 review: THE LOCK ITSELF CAN NOW REJECT, before `fn()` ever runs.
+        //
+        // The batch-rejection handler above lives INSIDE the lock callback, which was sound while
+        // withApiLock could only reject from the callback. Once acquiring the lock started settling
+        // an abandoned budget load, a timeout there bypasses that handler entirely, and there was
+        // no outer catch: every queued write then never settled (its residency timer was cleared at
+        // dispatch, so nothing could rescue it, which is the #278 signature), and because
+        // processWriteQueue is invoked unawaited from scheduleWriteQueueDrain the rejection escaped
+        // as an unhandledRejection that the allowlist does not cover, so src/index.ts called
+        // process.exit(1). A stalled upstream download would have taken the whole server down and
+        // every other tenant with it.
+        //
+        // Reject the batch here instead. The operations never ran and nothing was written, so this
+        // is the same contract queueWriteOperation's residency rejection uses.
+        logger.error('[WRITE QUEUE] Could not acquire the api lock for this batch:', lockError);
+        batch.forEach(({ reject }) => {
+            try {
+                reject(lockError);
+            }
+            catch (e) {
+                logger.error('[WRITE QUEUE] Error rejecting operation:', e);
+            }
+        });
+    }
     finally {
         isProcessingWrites = false;
         // #278: ALWAYS re-drain a non-empty queue. The old `&& writeSessionTimeout === null`
@@ -862,7 +997,11 @@ function queueWriteOperation(operation, options) {
     // op is never enqueued and no upstream resource is touched.
     _enforceBudgetAcl();
     // Capture sessionId from AsyncLocalStorage at enqueue time. The setTimeout
-    // below strips the ALS frame, so without capturing here the pool-branch
+    // below does NOT strip the ALS frame (that claim was here for a long time and is false:
+    // ALS propagates through timers). What it does is inherit the context of whichever session
+    // most recently SCHEDULED the drain, which is the last enqueuer in the debounce window and
+    // has nothing to do with the op being run. So capturing per entry is still exactly right,
+    // and #390 additionally re-enters the captured store per op. Without capturing, the pool-branch
     // decision in processWriteQueue would always miss. See #158.
     const sessionId = _resolveSessionId();
     return new Promise((resolve, reject) => {
@@ -871,6 +1010,7 @@ function queueWriteOperation(operation, options) {
             resolve,
             reject,
             sessionId,
+            requestStore: requestContext.getStore(),
             preservesListings: options?.preservesListings,
         };
         // #278: bound queue RESIDENCY, not just execution. #270's withOpTimeout bounds an
@@ -2512,14 +2652,7 @@ export async function switchBudget(name) {
         else {
             await withApiLock(async () => {
                 // Bound the in-place budget reload too (#270).
-                if (found.encryptionPassword) {
-                    const encryptionPassword = found.encryptionPassword;
-                    const apiWithOptions = api;
-                    await withOpTimeout(() => apiWithOptions.downloadBudget(found.syncId, { password: encryptionPassword }), 'downloadBudget');
-                }
-                else {
-                    await withOpTimeout(() => api.downloadBudget(found.syncId), 'downloadBudget');
-                }
+                await loadBudgetTracked(found.syncId, found.encryptionPassword);
             });
         }
         connectionPool.updateLoadedSyncId(sessionId, found.syncId);
@@ -2741,11 +2874,21 @@ export async function exportBudget() {
 export async function importBudget(input, opts = {}) {
     observability.incrementToolCall('actual.budgets.import').catch(() => { });
     const result = await queueWriteOperation(async () => {
-        return await withConcurrency(() => retry(() => rawImportBudget(input, opts), {
+        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}`);
+        return imported;
     });
     // #349: an import CHANGES WHICH BUDGET IS LOADED, so the pool's record of it
     // must stop naming the old one.

package/dist/src/lib/apiLock.js

@@ -0,0 +1,60 @@
+import { awaitAbandonedBudgetLoad } from './apiState.js';
+import { withOpTimeout } from './opTimeout.js';
+import { createModuleLogger } from './loggerFactory.js';
+const logger = createModuleLogger('API LOCK');
+/**
+ * The process-global @actual-app/api session mutex.
+ *
+ * WHY IT LIVES HERE rather than in actual-adapter.ts, which is where it was written and where
+ * every existing caller still reaches it from (the adapter re-exports it, so importers are
+ * unchanged). #390 needed `ActualConnectionPool` to hold this lock around its own
+ * init + downloadBudget, and the pool cannot import from the adapter: the adapter imports the
+ * pool singleton, so that edge is circular. This is the same reason `apiState.ts` and
+ * `opTimeout.ts` were split out before it, and the comments there say so.
+ *
+ * WHAT IT GUARANTEES. `@actual-app/api` is a singleton over one SQLite connection, and
+ * concurrent init/shutdown pairs corrupt the session. Every path that touches the api takes
+ * this first: reads via `withActualApi`, writes via `processWriteQueue`, and since #390 the
+ * pool's session-open init and budget download.
+ *
+ * IT IS NOT REENTRANT, and that is load bearing. It is a strict FIFO chained-promise mutex, so
+ * an inner acquisition waits on the outer call's own release promise, which cannot fire until
+ * the outer callback resolves. The observable symptom is a stall ended by #270's operation
+ * timeout, NOT a hang, and it should be read as a probable nesting bug rather than a slow
+ * upstream. Before adding an acquisition, check that no caller above you already holds it.
+ */
+let _apiSessionLock = Promise.resolve();
+/**
+ * #393: settling an abandoned budget load is part of ACQUIRING the lock, not something call
+ * sites remember to do.
+ *
+ * Every previous round of #390 guarded per call site and every round missed one. Round 1 missed
+ * the legacy path (a silent cross-tenant read). Round 2 put the wait in the two adapter entry
+ * points and missed the three `loadBudgetTracked` sites that reach the api without passing
+ * through them, so a session opening during the window untracked the abandoned load and the
+ * leak stayed reachable. CLAUDE.md already names this hazard class for `withOpTimeout`: the
+ * protection is per-call-site rather than structural, so a new acquisition site added without
+ * it fails silently.
+ *
+ * Putting it here makes the set of call sites stop mattering. Nothing reaches
+ * `@actual-app/api` without this lock, so nothing reaches it without the wait.
+ *
+ * It is bounded and fails closed (see `awaitAbandonedBudgetLoad`): an unbounded wait here would
+ * wedge every session on one stuck download, which is what made the round-2 version worse than
+ * the bug it fixed.
+ */
+export function withApiLock(fn) {
+    let release;
+    const prevLock = _apiSessionLock;
+    _apiSessionLock = new Promise((resolve) => {
+        release = resolve;
+    });
+    return prevLock
+        .then(async () => {
+        if (await awaitAbandonedBudgetLoad(withOpTimeout)) {
+            logger.warn('[API LOCK] waited for an abandoned budget load before running this operation');
+        }
+        return await fn();
+    })
+        .finally(() => release());
+}

package/dist/src/lib/apiState.js

@@ -23,4 +23,111 @@ export function isApiInitialized() {
 }
 export function setApiInitialized(value) {
     _apiInitialized = value;
+    // A singleton that is not live holds no budget. Clearing here means a shutdown can never
+    // leave a stale claim behind for the next caller to trust.
+    if (!value)
+        _loadedBudgetSyncId = null;
+}
+/**
+ * #390: the syncId of the budget the SINGLETON currently holds, as distinct from the budget
+ * any given session believes it is on.
+ *
+ * WHY THIS HAS TO EXIST. `@actual-app/api` is process-global with ONE loaded budget, while the
+ * pool tracks up to MAX_CONCURRENT_SESSIONS entries that each carry their own syncId. Before
+ * this, nothing recorded which budget was actually loaded, so no code could tell that a
+ * session was about to operate on someone else's. Both re-entry paths skip the download for
+ * good reasons of their own: `getConnection` returns early for an initialised entry, and
+ * `initActualApiForOperation` returns early when the singleton is live (which is #134's fix
+ * for the #127 auth burst). Neither is wrong; together they meant the loaded budget was
+ * whatever the last session to open had asked for.
+ *
+ * Reproduced before the fix: session A opened on budget A and wrote to it, session B opened
+ * and switched to budget B, and session A's NEXT write landed in budget B. The budget ACL
+ * could not see it, because `_enforceBudgetAcl` validates the budget the session believes it
+ * is on while the operation executes against whatever is loaded.
+ *
+ * Written by every path that downloads a budget; read inside the api lock by the adapter's
+ * precondition check. Lives here for the same reason the live flag does: the pool must update
+ * it without importing the adapter.
+ */
+let _loadedBudgetSyncId = null;
+export function getLoadedBudgetSyncId() {
+    return _loadedBudgetSyncId;
+}
+export function setLoadedBudgetSyncId(syncId) {
+    _loadedBudgetSyncId = syncId;
+}
+/**
+ * #390 round 3: an ABANDONED budget load.
+ *
+ * `withOpTimeout` races; it does not cancel. When a `downloadBudget` exceeds
+ * ACTUAL_OP_TIMEOUT_MS the underlying call KEEPS RUNNING and eventually re-points the
+ * singleton, outside the mutex, at a moment nobody is waiting for. Upstream makes this worse
+ * than a failed no-op: `handlers['api/download-budget']` begins with `close-budget`, then
+ * `load-budget` and `sync-budget`, so an abandoned download CLOSES whatever budget is loaded
+ * and opens a different one mid-flight, underneath another session's lock.
+ *
+ * Two leaks were reproduced against the previous fix. The record stayed on the old budget
+ * (only set on success), so the next matching session passed the check and read someone else's
+ * data; and even after recording the true outcome, the re-point landed BETWEEN a session's
+ * check and its raw call, so the write still went to the wrong budget. A mutex cannot serialise
+ * a promise its holder has abandoned.
+ *
+ * So the load is tracked rather than merely bounded. The record is cleared BEFORE a download
+ * starts, so an abandonment can only leave it indeterminate (the safe direction, which forces a
+ * re-select), and the abandoned promise stays registered here until it settles. No operation
+ * may proceed past a pending abandoned load: `awaitAbandonedBudgetLoad` is awaited inside the
+ * api lock, so a late landing happens BEFORE the next check rather than between a check and its
+ * use.
+ */
+const _pendingBudgetLoads = new Set();
+/**
+ * Register an in-flight budget load.
+ *
+ * A SET, and each entry removes itself once it settles. Two earlier shapes were wrong:
+ * assigning to a single slot let a session opening during the window overwrite an outstanding
+ * abandoned load, whose success then cleared it, so the abandoned promise became untracked and
+ * landed later (that was #393's second P0). Chaining fixed the overwrite but left a completed
+ * load registered forever, because a chained promise is no longer the handle its creator holds,
+ * so nothing could clear it and "is a load outstanding" stopped meaning anything.
+ *
+ * With a set, concurrent loads all stay tracked and a finished one drops out on its own, so
+ * what remains is exactly the loads that are still in flight.
+ */
+export function registerBudgetLoad(p) {
+    // Never let the registration raise an unhandled rejection: the caller races this promise and
+    // handles (or abandons) the failure on its own path.
+    const safe = p.then(() => undefined, () => undefined);
+    _pendingBudgetLoads.add(safe);
+    void safe.then(() => {
+        _pendingBudgetLoads.delete(safe);
+    });
+}
+/**
+ * Settle every outstanding load, BOUNDED, and FAIL CLOSED on timeout.
+ *
+ * #393: the unbounded version was a P0 worse than the leak it closed. Both call sites were
+ * inside the api mutex and outside any timeout, so ONE never-settling download blocked every
+ * session forever, with no error after the first line and no recovery short of a process
+ * restart. That is exactly the mode opTimeout.ts exists to remove and that #270 removed, so
+ * reintroducing it was a regression against a fixed bug.
+ *
+ * On timeout this THROWS and leaves the registrations in place. Both alternatives are worse:
+ * proceeding runs the operation against a singleton a landing download may re-point underneath
+ * it (the original leak), and clearing forgets the landing entirely. A persistent, legible
+ * per-request error with the mutex released each time is the honest failure for "an upstream
+ * load is stuck and we cannot cancel it".
+ *
+ * Returns true when it actually waited, so callers can log it and tests can assert it.
+ */
+export async function awaitAbandonedBudgetLoad(bound) {
+    if (_pendingBudgetLoads.size === 0)
+        return false;
+    const outstanding = Promise.all([..._pendingBudgetLoads]);
+    await bound(() => outstanding, 'abandoned budget load');
+    return true;
+}
+/** Test hook: is a load currently outstanding? */
+export function _hasPendingBudgetLoadForTests() {
+    return _pendingBudgetLoads.size > 0;
 }

package/dist/src/lib/budgetLoader.js

@@ -0,0 +1,295 @@
+import api from '@actual-app/api';
+import { withOpTimeout } from './opTimeout.js';
+import { setApiInitialized, setLoadedBudgetSyncId, registerBudgetLoad } from './apiState.js';
+import { createModuleLogger } from './loggerFactory.js';
+const log = createModuleLogger('BUDGET-LOADER');
+/**
+ * #390 round 3: the ONE way this codebase loads a budget.
+ *
+ * Every site used to hand-write `withOpTimeout(() => api.downloadBudget(...))` followed by a
+ * record-on-success. That shape is wrong in a way no amount of care fixes, because
+ * `withOpTimeout` races rather than cancels: on timeout the download keeps running and later
+ * re-points the singleton outside the mutex, and recording only on success leaves the record
+ * naming the PREVIOUS budget while the singleton holds the new one, which is the one direction
+ * that makes the precondition silently pass.
+ *
+ * So: clear the record BEFORE starting (an abandonment can then only leave it indeterminate,
+ * which forces a re-select), register the promise so a late landing is waited for rather than
+ * discovered, and record the true outcome when it settles whether or not anyone is still
+ * listening.
+ *
+ * #396 adds a POST-CONDITION, because a resolved download is not proof a budget is open.
+ * See `assertBudgetOpen` below.
+ *
+ * INVARIANT: nothing in this file may call anything that takes `withApiLock`. Every caller
+ * already holds that non-reentrant mutex, so `adapter.*` here would deadlock. It is also what
+ * makes this loader safe to call from `actualConnection.ts`, which acquires the lock itself.
+ * (#402 tracks making this structural rather than conventional.)
+ */
+/** The closed set of reasons upstream's `_loadBudget` can report, via `withErrorCode`. */
+const KNOWN_LOAD_REASONS = new Set([
+    'budget-not-found',
+    'opening-budget',
+    'out-of-sync-migrations',
+    'out-of-sync-data',
+    'loading-budget',
+]);
+/** Upper bound on any upstream prose we echo to the client (#396 security review). */
+const MAX_REASON_CHARS = 200;
+/** Sentinel: the diagnostic load worked, so the failure was not deterministic. */
+const RETRY_SUCCEEDED = 'the load succeeded on a second attempt, so this looks transient; retry the operation';
+/** Reported when the syncId has no LOCAL copy. Deliberately says nothing about what does exist. */
+const NO_LOCAL_COPY = 'no local copy of this budget was found';
+/**
+ * Brand for "the download resolved but no budget is open", so the caller can tell it from an
+ * upstream stall without matching prose. Deliberately NOT a PreflightRefusal: this is an
+ * infrastructure failure, not a caller-fixable refusal (`errors.ts` taxonomy).
+ */
+const BUDGET_NOT_OPEN = Symbol.for('actual-mcp.budgetNotOpen');
+function isBudgetNotOpen(err) {
+    return !!err && typeof err === 'object' && err[BUDGET_NOT_OPEN] === true;
+}
+/**
+ * Read `.message` off anything upstream throws.
+ *
+ * NO `instanceof Error` GUARD, deliberately. `checkFileOpen()` throws `APIError(...)`, which
+ * RETURNS A PLAIN OBJECT (`{ type: 'APIError', message, meta }`). Measured against
+ * @actual-app/api 26.8.0: `err instanceof Error` is false and `String(err)` is `[object Object]`,
+ * while `.message` works. Same precedent as `actual-adapter.ts` ("Handle Actual APIError plain
+ * objects").
+ */
+function messageOf(err) {
+    if (err && typeof err === 'object' && typeof err.message === 'string') {
+        return err.message;
+    }
+    return typeof err === 'string' ? err : '';
+}
+function codeOf(err) {
+    if (err && typeof err === 'object' && typeof err.code === 'string') {
+        return err.code;
+    }
+    return undefined;
+}
+/** A timeout from `withOpTimeout` is an upstream STALL, never an unloadable budget. */
+function isOpTimeout(err) {
+    return /timed out after \d+ms \(ACTUAL_OP_TIMEOUT_MS\)/.test(messageOf(err));
+}
+/**
+ * #396 POST-CONDITION: is a budget actually open?
+ *
+ * `api.downloadBudget()` can RESOLVE while leaving nothing open. Upstream's
+ * `api/download-budget` discards the `{ error }` that `load-budget` returns, in BOTH branches
+ * (loot-core `src/server/api.ts:237` for a local copy, `:261` after a fresh download), and
+ * `load-budget` does not throw: it returns an error object having already called `closeBudget()`
+ * internally, which unloads prefs. The sync that follows cannot catch it either, because
+ * `_fullSync` opens with `if (... || !currentId) return []`, so with nothing loaded it reports
+ * success by returning nothing. Reproduced two ways against a real budget (a planted unknown
+ * migration id, and a `db.sqlite` that is not a database): the download resolves, nothing is
+ * open, and every later call throws `No budget file is open` permanently for that data dir.
+ *
+ * The probe is `api.getBudgetMonths()`, and it is cheap for a reason worth stating rather than
+ * assuming: it is `checkFileOpen()` plus `createAllBudgets()`, and `createAllBudgets()` already
+ * ran once inside `_loadBudget` against the SAME in-process `Spreadsheet` singleton, while
+ * `meta.createdMonths` is never persisted, so the second call filters to zero new months and does
+ * no work beyond one indexed SQLite read. Measured at 0ms with no network call.
+ */
+async function assertBudgetOpen() {
+    try {
+        await withOpTimeout(() => api.getBudgetMonths(), 'budget-open probe');
+    }
+    catch (err) {
+        // An upstream STALL is not an unloadable budget. Propagate it unchanged so it keeps #270's
+        // semantics: diagnosing it as a version or data-dir problem would point the user at the wrong
+        // subsystem, and its message contains "timed out", which `_shouldDropPoolOnError` classes
+        // transient (correctly, for a stall).
+        if (isOpTimeout(err))
+            throw err;
+        // #396 review: classify as "not open" ONLY on the signal that actually means it. Treating
+        // EVERY probe rejection as not-open was wrong in the expensive direction: a transient
+        // getBudgetMonths failure against a perfectly healthy OPEN budget would poison the singleton,
+        // send `diagnose` off to CLOSE and reload that healthy budget, and hand the caller a
+        // permanent-sounding "no budget file is open". Anything else is a genuine failure and
+        // propagates unchanged; the enclosing `.catch` still fails closed either way.
+        if (!/no budget file is open/i.test(messageOf(err)))
+            throw err;
+        const notOpen = new Error('the budget did not load');
+        notOpen[BUDGET_NOT_OPEN] = true;
+        throw notOpen;
+    }
+}
+/**
+ * Strip anything path-shaped from upstream prose before it reaches an MCP client.
+ *
+ * There is NO redaction backstop on this path: `actualToolsManager.callTool` rethrows and
+ * `ActualMCPConnection.executeTool` propagates, so the message reaches the client verbatim, and
+ * `redactSecrets` is a winston format that covers log transports only. The five `getSyncError`
+ * strings interpolate just the budget UUID and are safe, but `_loadBudget` maps to that enum only
+ * for failures it CATCHES: `db.loadClock()`, `prefs.savePrefs` and `startBackupService(id)` sit
+ * outside every try/catch, so a raw fs or sqlite error carrying an ABSOLUTE PATH (and therefore a
+ * username) can reach here. Capping does not scrub a path, so scrub first.
+ */
+function scrubReason(prose) {
+    if (!prose)
+        return undefined;
+    // #396 review: reject on ANY separator, not just one at a word boundary. The first version
+    // required `/` at the string start or after whitespace, a quote or a paren, so
+    // `ENOENT:/home/alice/...` and `C:/Users/alice/...` both slipped through WITH the OS username,
+    // on a path that has no redaction backstop. The five known-safe upstream reasons are plain
+    // prose plus a UUID and contain none of these characters, so rejecting outright costs nothing
+    // and cannot leak.
+    if (/[/\\~]/.test(prose))
+        return undefined;
+    return prose.length > MAX_REASON_CHARS ? `${prose.slice(0, MAX_REASON_CHARS)}...` : prose;
+}
+/**
+ * Ask upstream WHY the load failed, on the deterministic failure path only.
+ *
+ * Upstream logs the real reason and throws it away, which is the whole reason a user hitting this
+ * has nothing actionable to go on. `api/load-budget` (unlike `api/download-budget`) DOES check the
+ * error and throws it with `withErrorCode`, so re-attempting the load through that entry point
+ * recovers the exact reason.
+ *
+ * Runs where a CALLER IS WAITING, never inside the promise `registerBudgetLoad` registers: every
+ * `withApiLock` acquisition settles all registrations under ONE bound and fails closed on timeout,
+ * 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.
+ */
+const reasonCache = new Map();
+/** A load that genuinely succeeded clears any cached reason for that budget. */
+function clearCachedReason(syncId) {
+    reasonCache.delete(syncId);
+}
+/** Test-only: the reason cache is module state, so a test suite must be able to reset it. */
+export function _clearReasonCacheForTests() {
+    reasonCache.clear();
+}
+async function diagnose(syncId) {
+    // #396 review: memoise the reason STRING, never the fail-closed decision. Without this, every
+    // tool call while the condition persists pays two bounded network calls WHILE HOLDING the
+    // process-global api mutex, so a single unloadable budget stalls unrelated sessions for up to
+    // 2 x ACTUAL_OP_TIMEOUT_MS per call. The condition is deterministic, so the second diagnosis
+    // would report what the first did. The ticket sanctions exactly this and nothing more: the
+    // decision stays uncached, so the load is still re-attempted and still fails closed every time,
+    // and a genuinely successful load clears the entry.
+    // An empty string means "already diagnosed, and there was nothing safe to report". It must be
+    // cached like any other outcome: review round 2 found that caching only the reportable outcomes
+    // left the two most persistent failure classes re-diagnosing on every single call, which is
+    // 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;
+    }
+    try {
+        const budgets = (await withOpTimeout(() => api.getBudgets(), 'diagnose getBudgets'));
+        // `api/get-budgets` does NO deduplication: it concatenates the local scan with
+        // `get-remote-files`, so a budget synced both ways appears TWICE and only the LOCAL entry
+        // carries `id`. Measured: [{"id":"_test-budget"},{"state":"remote"}] for one groupId.
+        // Matching on groupId alone can select the remote twin and call loadBudget(undefined).
+        const local = budgets.find((b) => b.groupId === syncId && typeof b.id === 'string');
+        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);
+            return NO_LOCAL_COPY;
+        }
+        const localId = local.id;
+        // Registered like any other load: it re-enters upstream's full `_loadBudget` against the
+        // process-global singleton, so an abandoned diagnostic could otherwise land later and
+        // re-point it outside the lock (the #390 leak with a new author).
+        const p = api.loadBudget(localId);
+        registerBudgetLoad(p);
+        try {
+            await withOpTimeout(() => p, 'diagnose loadBudget');
+            // The diagnostic load SUCCEEDED, so the singleton now holds a budget nothing selected.
+            // Record indeterminate: that forces a re-select on the next operation, which is the safe
+            // direction #390 established. This line also satisfies block (4) of
+            // budget_selection_precondition.test.js structurally rather than by exemption, and it must
+            // stay in THIS brace-balanced block: the guard's window ends at the first `}` that takes
+            // depth below zero, so a setter in a sibling `catch` or `finally` arm would be outside it.
+            setLoadedBudgetSyncId(null);
+            // #396 review: the retry SUCCEEDED, so this was not a deterministic unloadable budget. Say
+            // so rather than reporting "upstream discarded the reason", which reads as permanent. The
+            // operation still fails (the record is indeterminate by design, which forces a re-select),
+            // but the caller is told that retrying is the right move. Not cached: it is not a reason,
+            // and the condition it describes is transient.
+            return RETRY_SUCCEEDED;
+        }
+        catch (loadErr) {
+            setLoadedBudgetSyncId(null);
+            // Prefer the CODE. Upstream attaches it via `withErrorCode` precisely so callers need not
+            // parse prose, and the prose is lossy: `getSyncError` collapses out-of-sync-migrations with
+            // out-of-sync-data, and opening-budget with loading-budget, so message-only capture
+            // distinguishes at most three of the five reasons.
+            const code = codeOf(loadErr);
+            log.warn('budget load diagnosis', { syncId, code: code ?? null, reason: messageOf(loadErr) });
+            const reason = code && KNOWN_LOAD_REASONS.has(code) ? code : scrubReason(messageOf(loadErr));
+            // Cache the outcome even when there is nothing reportable. A raw fs or sqlite failure has a
+            // `.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 ?? '');
+            return reason;
+        }
+    }
+    catch (diagErr) {
+        // A failing diagnostic is LOGGED, never substituted for the post-condition error.
+        log.warn('could not diagnose why the budget did not load', { syncId, error: messageOf(diagErr) });
+        return undefined;
+    }
+}
+function postConditionError(syncId, reason) {
+    return new Error(`The budget "${syncId}" reported a successful download but no budget file is open, ` +
+        `so every subsequent operation would fail. ` +
+        (reason ? `Upstream reason: [${reason}]. ` : 'Upstream discarded the reason. ') +
+        `Two causes account for almost all of these: a version mismatch between @actual-app/api and ` +
+        `the Actual server or budget file (the server version guard logs a warning when it can detect ` +
+        `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);
+    // 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);
+    })
+        .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.
+        setApiInitialized(false);
+        throw err;
+    });
+    registerBudgetLoad(tracked);
+    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.
+    }
+    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.
+        if (isBudgetNotOpen(err)) {
+            log.error('download resolved but no budget is open', undefined, { syncId });
+            throw postConditionError(syncId, await diagnose(syncId));
+        }
+        throw err;
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.2",
+  "version": "0.16.5",
   "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_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_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",