actual-mcp-server 0.16.2 → 0.16.6

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, 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.
@@ -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) {
@@ -264,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 */ }
                 }
@@ -308,6 +392,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().
@@ -321,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;
@@ -335,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 */ }
                 }
@@ -423,6 +512,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 +522,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 +555,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 +830,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) {
@@ -761,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
@@ -799,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 */
@@ -832,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 */
@@ -846,6 +965,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 +1006,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 +1019,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 +2661,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);
@@ -2551,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.
@@ -2741,11 +2884,30 @@ 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), {
-            retries: 0,
-            backoffMs: 200,
-            isRetryable: isRetryableError,
-        }));
+        // #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
     // 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;
 }