actual-mcp-server 0.16.5 → 0.16.7

package/README.md

@@ -476,6 +476,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | `ACTUAL_BUDGET_PASSWORD` | _(none)_ | No | Optional encryption password for encrypted budgets |
 | `ALLOW_INSECURE_UPSTREAM` | `false` | No | Allow an `http://` upstream even when `ACTUAL_BUDGET_PASSWORD` is set (#161). Off by default so a plaintext upstream plus an encryption password is refused |
 | `ACTUAL_OP_TIMEOUT_MS` | `30000` | No | Per-operation timeout (ms) for every upstream Actual API call (init, budget download, sync, and each tool operation). A stalled call rejects after this bound so it cannot hold the global API mutex forever and hang subsequent tool calls (#270). Set to `0` to disable |
+| `ACTUAL_IMPORT_TIMEOUT_MS` | `600000` | No | Separate, larger timeout (ms) for a budget import, which is legitimately long rather than stalled. An import is a tracked load, so every other session waits on it; bounding it at the general operation timeout turned one tenant's large import into a process-wide stall (#407). Set to `0` to disable |
 | **MCP Server Settings** ||||
 | `MCP_BRIDGE_PORT` | `3600` | No | Port for MCP server to listen on |
 | `MCP_BRIDGE_BIND_HOST` | `0.0.0.0` | No | Host address to bind server to (`0.0.0.0` = all interfaces) |
@@ -774,7 +775,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.16.5 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.16.7 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/config.js

@@ -30,6 +30,34 @@ export const configSchema = z.object({
             return 0;
         return Math.min(Math.max(n, 250), 2147483647);
     }),
+    /**
+     * #407: a separate, larger bound for a budget IMPORT.
+     *
+     * An import is not a stalled operation, it is a legitimately long one: a large YNAB or zip
+     * import runs for minutes. #394 made it a TRACKED load, so while it is in flight every other
+     * session's lock acquisition waits for it and then fails at ACTUAL_OP_TIMEOUT_MS. Bounding a
+     * five-minute import at the 30 second operation default therefore turned one tenant's import
+     * into a process-wide stall, with every other session failing repeatedly for the duration.
+     *
+     * Same parse-and-clamp shape as ACTUAL_OP_TIMEOUT_MS, and the same escape hatch: 0 disables the
+     * bound, which for an import means it can hold the process-global api mutex indefinitely (the
+     * #393 P0 shape), so it is for diagnosis rather than production.
+     *
+     * The clamp floor is 250ms, the same as the operation timeout. It is deliberately NOT raised to
+     * the operation timeout's configured VALUE: an earlier comment here claimed an import bound below
+     * the general one was prevented, and it was not, so the claim is removed rather than left to
+     * mislead. A smaller import bound is unusual but coherent (abandon imports sooner than ordinary
+     * reads), and enforcing an ordering between two independently configured knobs at parse time
+     * would need one to be parsed before the other.
+     */
+    ACTUAL_IMPORT_TIMEOUT_MS: z.string().default('600000').transform(val => {
+        const n = parseInt(val, 10);
+        if (!Number.isFinite(n) || n < 0)
+            return 600000;
+        if (n === 0)
+            return 0;
+        return Math.min(Math.max(n, 250), 2147483647);
+    }),
     // Escape hatch for #161: allow an http:// upstream even when an E2E encryption
     // password is set (e.g. an isolated Docker network where the hop is trusted).
     // Off by default so a plaintext upstream + encryption password is refused.

package/dist/src/lib/ActualConnectionPool.js

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

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

@@ -21,9 +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, getLoadedBudgetSyncId, setLoadedBudgetSyncId } from './apiState.js';
+import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, awaitAbandonedBudgetLoad } from './apiState.js';
 import { withApiLock } from './apiLock.js';
-import { loadBudgetTracked } from './budgetLoader.js';
+import { loadBudgetTracked, importBudgetTracked } from './budgetLoader.js';
 /**
  * Budget registry — all budgets configured via ACTUAL_* and BUDGET_n_* env vars.
  * Built once at startup; used by every withActualApi call.
@@ -347,8 +347,9 @@ export async function withActualApi(rawOperation) {
                 // re-introduce the auth-burst pattern #134 is fixing.
                 if (_shouldDropPoolOnError(err)) {
                     logger.warn(`[ADAPTER] Releasing pool connection for session ${sessionId} after infrastructure-level error`);
+                    // #392: Locked variant. We are INSIDE withApiLock here; the wrapping one would deadlock.
                     try {
-                        await connectionPool.shutdownConnection(sessionId);
+                        await connectionPool.shutdownConnectionLocked(sessionId);
                     }
                     catch (_e) { /* swallow */ }
                 }
@@ -407,8 +408,9 @@ export async function withActualApiWrite(operation) {
                     // Sync failure on a write IS infrastructure-level — drop the pool
                     // connection so the next call re-inits, then surface the error.
                     logger.error(`[ADAPTER] api.sync() failed after write in session ${sessionId}; releasing pool connection`);
+                    // #392: Locked variant. We are INSIDE withApiLock here; the wrapping one would deadlock.
                     try {
-                        await connectionPool.shutdownConnection(sessionId);
+                        await connectionPool.shutdownConnectionLocked(sessionId);
                     }
                     catch (_e) { /* swallow */ }
                     throw syncErr;
@@ -421,8 +423,9 @@ export async function withActualApiWrite(operation) {
                 // leave the connection fine.
                 if (_shouldDropPoolOnError(err)) {
                     logger.warn(`[ADAPTER] Releasing pool connection for write session ${sessionId} after infrastructure-level error`);
+                    // #392: Locked variant. We are INSIDE withApiLock here; the wrapping one would deadlock.
                     try {
-                        await connectionPool.shutdownConnection(sessionId);
+                        await connectionPool.shutdownConnectionLocked(sessionId);
                     }
                     catch (_e) { /* swallow */ }
                 }
@@ -827,7 +830,7 @@ 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, requestStore } of batch) {
+                    for (const { operation, resolve, reject, preservesListings, requestStore, timeoutMs } of batch) {
                         try {
                             // #390 round 2: run each op in the context it was ENQUEUED in.
                             //
@@ -844,8 +847,40 @@ async function processWriteQueue() {
                             // 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 () => {
+                                // #406: settle any abandoned budget load PER OPERATION, not per lock acquisition.
+                                //
+                                // #393 made the wait part of acquiring the api lock, which makes the set of call
+                                // sites stop mattering: nothing reaches the api without the lock, so nothing reaches
+                                // it without the wait. That holds for every path where one acquisition serves one
+                                // operation. It does NOT hold here. This drain acquires the lock ONCE and then runs
+                                // N operations inside it, so once any op abandons a load, every LATER op in the same
+                                // batch runs against a singleton that abandoned load will re-point, having never
+                                // waited for it. Reproduced with a slow import and a following write in one debounce
+                                // window; it is the #390 class with a new author.
+                                //
+                                // Deliberately NOT inside ensureLoadedBudgetMatchesSession: that returns early when
+                                // the loaded budget already matches, and an op whose budget happens to match still
+                                // needs the wait, because the abandoned load is about to move the singleton AWAY
+                                // from it. The wait has to be unconditional, so it sits before the precondition.
+                                //
+                                // A rejection here is caught by this loop's own per-op catch, so a stuck load fails
+                                // ONE operation rather than the whole batch, which is the behaviour #393 round 4
+                                // established for the drain.
+                                await awaitAbandonedBudgetLoad(withOpTimeout);
                                 await ensureLoadedBudgetMatchesSession();
-                                return await withOpTimeout(operation);
+                                // #407: an operation may carry its OWN bound. Only a budget import does today, and
+                                // it needs one: the import is legitimately long, and bounding it at the general
+                                // operation timeout abandons it while every other session is already waiting on it
+                                // as a tracked load. Without this the raised bound inside the loader is dead letter,
+                                // because THIS wrapper would abandon the op first.
+                                //
+                                // A long op does NOT need a keep-alive heartbeat, and one was written and removed in
+                                // review. The session cannot be swept out from under it: `cleanupIdleConnections`
+                                // passes `onlyIfExpired`, so `shutdownConnectionLocked` re-checks expiry AFTER
+                                // acquiring the mutex (#392), and the `finally` below touches every session in the
+                                // batch before the lock is released. A sweep that queued behind this drain therefore
+                                // finds the entry fresh and returns without evicting.
+                                return await withOpTimeout(operation, 'operation', timeoutMs);
                             });
                             resolve(result);
                         }
@@ -871,10 +906,12 @@ async function processWriteQueue() {
                             // the batch ran concurrently and a drain was bounded by roughly one
                             // ACTUAL_OP_TIMEOUT_MS. Sequential dispatch makes a drain's wall clock the SUM of
                             // its ops, so a batch of slow ops can now outlive SESSION_IDLE_TIMEOUT_MINUTES
-                            // (default 5) and be swept mid-drain. The sweep's shutdownConnection calls
-                            // api.shutdown() WITHOUT holding withApiLock, which is the same hazard this file
-                            // already documents as the reason stdio is kept off the pool: it tears the
-                            // singleton down underneath an in-flight operation.
+                            // (default 5) and be swept mid-drain. The sweep would then evict the session and
+                            // fire its eviction listeners, closing the transport under a drain that is still
+                            // running. Since #392 the sweep takes the api mutex and re-checks expiry, so it can
+                            // no longer tear the singleton down mid-operation, but an unrefreshed entry is still
+                            // MARKED expired, so the touch below is what keeps an active session out of the
+                            // sweep's list at all.
                             //
                             // THIS MUST STAY INSIDE THE LOOP. A single touch at drain start does nothing for
                             // a drain whose wall clock is the SUM of its ops, which is the entire reason the
@@ -909,7 +946,9 @@ async function processWriteQueue() {
                         if (usePoolBranch && _shouldDropPoolOnError(syncError)) {
                             logger.warn(`[WRITE QUEUE] Releasing pool connection for session ${batchSessionId} after sync failure`);
                             try {
-                                await connectionPool.shutdownConnection(batchSessionId);
+                                // #392: Locked variant; the drain holds withApiLock across this whole block, and
+                                // the mutex is not reentrant, so the wrapping variant would deadlock here.
+                                await connectionPool.shutdownConnectionLocked(batchSessionId);
                             }
                             catch (_e) {
                                 /* swallow */
@@ -942,7 +981,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 */
@@ -1012,6 +1053,7 @@ function queueWriteOperation(operation, options) {
             sessionId,
             requestStore: requestContext.getStore(),
             preservesListings: options?.preservesListings,
+            timeoutMs: options?.timeoutMs,
         };
         // #278: bound queue RESIDENCY, not just execution. #270's withOpTimeout bounds an
         // operation that is RUNNING; it cannot bound one that never starts. Reuse the same
@@ -2684,8 +2726,9 @@ export async function switchBudget(name) {
     // init/shutdown cycle. A pooled entry for stdio would be created here and then
     // NEVER refreshed, because connectionPool.touch() is called only from
     // httpServer.ts; it would expire after SESSION_IDLE_TIMEOUT_MINUTES and
-    // cleanupIdleConnections would api.shutdown() it WITHOUT holding withApiLock,
-    // which can tear the singleton down underneath an in-flight operation. The
+    // cleanupIdleConnections would tear it down. Since #392 that teardown takes the api mutex and
+    // re-checks expiry, so it is no longer a mid-operation hazard, but an entry that is never
+    // refreshed still expires, and that is the reason that matters here. The
     // legacy path re-reads getActiveBudgetConfig() on every call, so the switch
     // still takes effect; it just costs an init per operation, which is what stdio
     // already did before this ticket.
@@ -2874,22 +2917,46 @@ export async function exportBudget() {
 export async function importBudget(input, opts = {}) {
     observability.incrementToolCall('actual.budgets.import').catch(() => { });
     const result = await queueWriteOperation(async () => {
-        const imported = await withConcurrency(() => retry(() => rawImportBudget(input, opts), {
-            retries: 0,
-            backoffMs: 200,
-            isRetryable: isRetryableError,
-        }));
-        // #390: an import CHANGES the loaded budget (upstream documents importBudget as "loads the
-        // imported budget"), and the singleton's record kept naming the pre-import one. That is the
-        // unsafe direction: the precondition compares against it, passes, and a session then reads
-        // the imported file while believing it is on its own budget. A sentinel rather than a real
-        // syncId, because an imported file is outside the budget registry and outside the ACL, so
-        // no session can ever legitimately match it and every session's next operation re-selects
-        // its own budget. Recorded AT the call site so the guard in
-        // tests/unit/budget_selection_precondition.test.js can see it.
-        setLoadedBudgetSyncId(`imported:${imported.id}`);
+        // #394: an import re-points the process-global singleton exactly as a download does, so it
+        // gets the SAME tracking discipline, through the same helper, rather than a hand-written
+        // approximation of it.
+        //
+        // What was wrong before: nothing cleared the record before the import started, nothing
+        // registered the promise, and the sentinel was written AFTER the await, so a timeout skipped
+        // it entirely. A large YNAB or zip import exceeding ACTUAL_OP_TIMEOUT_MS is the expected case,
+        // not a rare one. The record therefore went on naming the PRE-IMPORT budget while the
+        // singleton moved to an out-of-registry, un-ACL'd imported file, and a victim session passed
+        // the #390 precondition legitimately and had its reads served from the importer's file.
+        //
+        // #390 still holds at this call site: `importBudgetTracked` records the `imported:` sentinel
+        // when the promise settles, whichever way, and the clear below states the same fact at the
+        // call site where the guard in tests/unit/budget_selection_precondition.test.js can see it.
+        // #408: invalidate BEFORE the import starts, not after it resolves.
+        //
+        // The invalidation below used to run only after `queueWriteOperation` resolved, so on the
+        // TIMEOUT path it never ran at all, and a large import exceeding ACTUAL_OP_TIMEOUT_MS is the
+        // expected case rather than a rare one. Every pool entry then kept naming the pre-import
+        // syncId while the singleton moved to the imported file, and switchBudget's #172 fast path
+        // no-opped on a switch back: the reported-success-with-no-effect class #349 exists to prevent.
+        //
+        // Moving it here follows the same clear-before-you-start discipline #394 established for the
+        // record itself: a mutation that may be abandoned must leave state INDETERMINATE, never
+        // confidently wrong. It is idempotent and costs nothing on the success path, where the call
+        // after the write simply re-applies the same sentinel.
+        const preInvalidated = connectionPool.invalidateAllLoadedSyncIds('imported:pending');
+        if (preInvalidated > 0) {
+            logger.debug(`[ADAPTER] importBudget: invalidated the pooled syncId on ${preInvalidated} session(s) before starting`);
+        }
+        const imported = await importBudgetTracked(() => {
+            const started = withConcurrency(() => retry(() => rawImportBudget(input, opts), {
+                retries: 0,
+                backoffMs: 200,
+                isRetryable: isRetryableError,
+            }));
+            return started;
+        });
         return imported;
-    });
+    }, { timeoutMs: config.ACTUAL_IMPORT_TIMEOUT_MS });
     // #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/apiState.js

@@ -131,3 +131,17 @@ export async function awaitAbandonedBudgetLoad(bound) {
 export function _hasPendingBudgetLoadForTests() {
     return _pendingBudgetLoads.size > 0;
 }
+/**
+ * Test hook: drop every registration.
+ *
+ * There is deliberately no production unregister: an entry leaves this set only when its promise
+ * settles, which is what makes "is a load outstanding" mean anything (#393). But a test that
+ * registers a NEVER-settling load has no way back, and leaving one pending poisons every later
+ * lock acquisition in that file, so a later case silently exercises a poisoned lock while claiming
+ * to test something else. Both of this repo's abandoned-load test files hit exactly that.
+ *
+ * Test-only, and not exported through the package surface.
+ */
+export function _clearPendingBudgetLoadsForTests() {
+    _pendingBudgetLoads.clear();
+}

package/dist/src/lib/budgetLoader.js

@@ -1,5 +1,6 @@
 import api from '@actual-app/api';
 import { withOpTimeout } from './opTimeout.js';
+import config from '../config.js';
 import { setApiInitialized, setLoadedBudgetSyncId, registerBudgetLoad } from './apiState.js';
 import { createModuleLogger } from './loggerFactory.js';
 const log = createModuleLogger('BUDGET-LOADER');
@@ -154,6 +155,23 @@ function scrubReason(prose) {
  * so putting two network calls in there would extend the window in which unrelated sessions' lock
  * acquisitions throw, to build a message an abandoned load has no caller to read.
  */
+/**
+ * #404: the cached reason is re-derived every REDIAGNOSE_AFTER_USES failures.
+ *
+ * The cache exists because `diagnose()` runs INSIDE the process-global api mutex and makes two
+ * bounded network calls, so re-running it per failed tool call stalls unrelated sessions. But an
+ * entry was previously dropped only by a genuinely successful load or a process restart, so if a
+ * budget's failure MODE changed with no success in between, the message reported the first reason
+ * indefinitely.
+ *
+ * Bounding by USES rather than by wall-clock is deliberate: the cost this cache avoids is paid per
+ * CALL, so capping in calls bounds staleness in the same unit, needs no clock, and is
+ * deterministic under test. At 20, a persistent failure pays the diagnosis roughly 5 percent of
+ * the time (the saving the cache exists for is kept) while no operator can see a stale reason for
+ * more than 20 failed calls. The fail-closed DECISION is still never cached: every call
+ * re-attempts the load and still fails.
+ */
+const REDIAGNOSE_AFTER_USES = 20;
 const reasonCache = new Map();
 /** A load that genuinely succeeded clears any cached reason for that budget. */
 function clearCachedReason(syncId) {
@@ -164,6 +182,9 @@ export function _clearReasonCacheForTests() {
     reasonCache.clear();
 }
 async function diagnose(syncId) {
+    // #409: what the cache held before a re-diagnosis, so a failed re-diagnosis can fall back to it
+    // rather than reporting nothing.
+    let staleReason;
     // #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
@@ -177,8 +198,25 @@ async function diagnose(syncId) {
     // precisely the cost this memo exists to remove.
     const cached = reasonCache.get(syncId);
     if (cached !== undefined) {
-        log.debug('reusing the cached load-failure reason', { syncId });
-        return cached || undefined;
+        cached.uses += 1;
+        if (cached.uses <= REDIAGNOSE_AFTER_USES) {
+            log.debug('reusing the cached load-failure reason', { syncId, uses: cached.uses });
+            return cached.reason || undefined;
+        }
+        // #404: the entry has served its budget of calls, so fall through to a fresh diagnosis and
+        // pick up a failure mode that changed without an intervening success.
+        //
+        // #409: do NOT delete it here. Deleting first meant a re-diagnosis that then failed
+        // transiently (a `getBudgets` blip) left the caller with "upstream discarded the reason"
+        // despite a perfectly good cached one having existed a moment earlier, and the next call paid
+        // two more bounded network calls inside the api mutex to rediscover it. The stale entry is
+        // kept as a fallback and is only overwritten when a new answer is actually produced.
+        staleReason = cached.reason;
+        cached.uses = 0;
+        log.debug('re-diagnosing the load failure after the cached reason served its budget', {
+            syncId,
+            afterUses: REDIAGNOSE_AFTER_USES,
+        });
     }
     try {
         const budgets = (await withOpTimeout(() => api.getBudgets(), 'diagnose getBudgets'));
@@ -190,7 +228,7 @@ async function diagnose(syncId) {
         if (!local) {
             // Deliberately does NOT list what IS available: that would enumerate every budget on the
             // server to a caller the ACL scopes to one.
-            reasonCache.set(syncId, NO_LOCAL_COPY);
+            reasonCache.set(syncId, { reason: NO_LOCAL_COPY, uses: 0 });
             return NO_LOCAL_COPY;
         }
         const localId = local.id;
@@ -208,6 +246,13 @@ async function diagnose(syncId) {
             // 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);
+            // #407 review (I3): DROP any cached reason here. #409 stopped deleting the entry before a
+            // re-diagnosis, which is right for the failed-diagnosis path, but on THIS path the old
+            // reason has just been proven wrong: the load worked. Leaving it cached with uses reset
+            // meant the next 20 calls reported a permanent-sounding migration code for a condition the
+            // diagnosis had just shown to be transient, which is exactly the reading the comment below
+            // says to avoid.
+            reasonCache.delete(syncId);
             // #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),
@@ -228,13 +273,20 @@ async function diagnose(syncId) {
             // `.code` outside KNOWN_LOAD_REASONS and path-shaped prose that `scrubReason` drops, so it
             // yields `undefined`, and that is the ticket's own reproduced "db.sqlite is not a database"
             // case: the one most likely to persist. Storing '' records "diagnosed" without reporting.
-            reasonCache.set(syncId, reason ?? '');
+            reasonCache.set(syncId, { reason: reason ?? '', uses: 0 });
             return reason;
         }
     }
     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) });
+        // #409: fall back to the previous answer rather than reporting nothing. It described this same
+        // budget's failure moments ago and is far more useful than silence; the use counter was reset,
+        // so the next call re-attempts the diagnosis anyway.
+        if (staleReason !== undefined) {
+            reasonCache.set(syncId, { reason: staleReason, uses: 0 });
+            return staleReason || undefined;
+        }
         return undefined;
     }
 }
@@ -247,45 +299,126 @@ function postConditionError(syncId, reason) {
         `this), and a local budget copy that cannot be opened (check the directory configured by ` +
         `MCP_BRIDGE_DATA_DIR, and note that two server processes sharing one data dir will do this).`);
 }
-export async function loadBudgetTracked(syncId, encryptionPassword, label = 'downloadBudget') {
-    const raw = encryptionPassword
-        ? api
-            .downloadBudget(syncId, { password: encryptionPassword })
-        : api.downloadBudget(syncId);
-    // Indeterminate from here until it settles. Cleared first, deliberately.
+/**
+ * The tracking discipline EVERY singleton-mutating load must follow (#390, #393, #394).
+ *
+ * Extracted so the two callers cannot drift. `downloadBudget` and `importBudget` are different
+ * upstream calls with different failure shapes, but the discipline is identical and getting it
+ * subtly different at one site is exactly how #390 stayed reachable for three rounds:
+ *
+ *   1. Clear the record BEFORE starting, so an abandonment can only leave it INDETERMINATE.
+ *      That is the safe direction: it forces a re-select. Recording only on success leaves the
+ *      record naming the PREVIOUS budget while the singleton moves to a new one, which is the one
+ *      direction that makes the #390 precondition silently pass.
+ *   2. Register the promise, so a late landing is WAITED FOR by the next lock acquisition rather
+ *      than discovered mid-operation. `withOpTimeout` races; it does not cancel.
+ *   3. Record the true outcome when it settles, whether or not anyone is still listening, and
+ *      poison the singleton on failure, because upstream closes the current budget before opening
+ *      the new one, so "failed" does not mean "unchanged".
+ *
+ * `verify` is #396's post-condition, and it runs BEFORE the record is written, so the record can
+ * only ever describe a mutation that actually took effect.
+ */
+async function trackBudgetMutation(start, describeLoaded, label, verify, onRecorded, timeoutMs) {
+    // Indeterminate from here until it settles. Cleared BEFORE the load is even started, so the
+    // record can never name the outgoing budget while the singleton is moving away from it: that is
+    // the one direction that makes #390's precondition silently pass. It used to be cleared on the
+    // statement AFTER `start()`, which was safe in practice (both run in one synchronous turn, so
+    // nothing could observe the gap) but made the invariant untestable and the comment's own word
+    // "first" untrue.
     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 raw = start();
     const tracked = raw
-        .then(async () => {
-        await assertBudgetOpen();
-        setLoadedBudgetSyncId(syncId);
-        clearCachedReason(syncId);
+        .then(async (result) => {
+        if (verify)
+            await verify();
+        setLoadedBudgetSyncId(describeLoaded(result));
+        // #392 review (finding 5): this runs INSIDE the chain, not after the awaited call. On the
+        // abandoned-then-eventually-successful path the caller has already thrown, so a hook placed
+        // after the await would never run and the cached failure reason would outlive the load that
+        // actually succeeded.
+        // Wrapped: a hook cannot be allowed to change the recorded outcome. Unwrapped, a throwing
+        // hook would be caught by the trailing .catch, reported as a load failure, and would leave
+        // the record written while setApiInitialized(false) says the singleton is dead: an
+        // incoherent pair rather than a fail-safe one.
+        try {
+            onRecorded?.();
+        }
+        catch (hookErr) {
+            log.warn('post-record hook threw; the recorded outcome stands', { error: String(hookErr) });
+        }
+        return result;
     })
         .catch((err) => {
         // A failed load leaves the singleton in a state nobody can describe: upstream's
-        // download handler closes the current budget before opening the new one, so "failed"
-        // does not mean "unchanged". Poison it so the next operation re-inits from scratch.
+        // download and import handlers both close the current budget before opening the new one,
+        // so "failed" does not mean "unchanged". Poison it so the next operation re-inits.
         setApiInitialized(false);
         throw err;
     });
     registerBudgetLoad(tracked);
+    // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
+    // waits for it inside the lock rather than racing it.
+    return await withOpTimeout(() => tracked, label, timeoutMs);
+}
+/**
+ * #394: the same discipline for an IMPORT.
+ *
+ * Upstream's `importBudget` LOADS the imported budget, so it re-points the process-global
+ * singleton exactly as a download does, and a large YNAB or zip import exceeding
+ * ACTUAL_OP_TIMEOUT_MS is the expected case rather than a rare one. Before this, nothing cleared
+ * the record before it started, nothing registered the promise, and the sentinel was written
+ * AFTER the await, so a timeout skipped it entirely and the record went on naming the PRE-IMPORT
+ * budget while the singleton moved to an out-of-registry, un-ACL'd file. A victim session then
+ * passed the #390 precondition legitimately and had its reads served from the importer's file.
+ *
+ * ACCEPTED COST, recorded because nothing else states it. Registering the import means every
+ * subsequent `withApiLock` acquisition waits for it, bounded, and throws on timeout. An import is
+ * not "stuck", it is legitimately long: a large YNAB or zip import can run for minutes. So while
+ * one runs past ACTUAL_OP_TIMEOUT_MS, other sessions stall for that bound and then fail with
+ * "abandoned budget load timed out", and write drains reject their batch. That is a strictly
+ * better failure than the silent cross-tenant read it replaces (a victim reading the importer's
+ * un-ACL'd file), and it is the same trade #393 accepted for downloads. It is NOT free, and the
+ * operator-facing consequence is a process-wide stall for the duration of one tenant's import.
+ * Giving imports their own larger bound is tracked separately rather than bolted on here.
+ *
+ * No `verify` here, deliberately: unlike `download-budget`, upstream's `importBudget` already
+ * asserts its own post-condition. It checks `result.error` and then `!result.id`, throwing
+ * "no budget was loaded", so it cannot resolve without having loaded something. Verified in the
+ * shipped upstream source. Adding a probe would be duplicate work on the write path.
+ */
+export async function importBudgetTracked(start, label = 'importBudget') {
+    // A sentinel rather than a real syncId: an imported file is outside the budget registry and
+    // outside the ACL, so no session can ever legitimately match it and every session's next
+    // operation re-selects its own budget. Configured sync ids are UUIDs, so an `imported:` prefix
+    // can never compare equal to one.
+    // #407: the import's OWN bound. See ACTUAL_IMPORT_TIMEOUT_MS in config.ts for why a long
+    // import must not be abandoned at the ordinary operation timeout: it is tracked, so every other
+    // session waits on it, and abandoning it early turns one tenant's import into a process-wide
+    // stall without making the import itself any faster.
+    return trackBudgetMutation(start, (result) => `imported:${result.id}`, label, undefined, undefined, config.ACTUAL_IMPORT_TIMEOUT_MS);
+}
+export async function loadBudgetTracked(syncId, encryptionPassword, label = 'downloadBudget') {
     try {
-        await withOpTimeout(() => tracked, label);
-        // #393 review (P3-4): NOT clearBudgetLoad(tracked). `registerBudgetLoad` registers a
-        // derived promise, not this handle, so that delete could never match and read as a working
-        // belt-and-braces path a later change might lean on. Self-removal on settle is what
-        // actually deregisters a completed load, and it has already happened by the time the
-        // awaited promise resolves here.
+        await trackBudgetMutation(
+        // #410: no redundant clear here any more. `trackBudgetMutation` owns the clear-before, and
+        // the guard in tests/unit/budget_selection_precondition.test.js now asserts the invariant
+        // that actually holds (a raw load must be inside the tracked helper) rather than looking for
+        // a setter in the same block, which had stopped discriminating.
+        () => encryptionPassword
+            ? api
+                .downloadBudget(syncId, { password: encryptionPassword })
+            : api.downloadBudget(syncId), () => syncId, label, 
+        // #396: the post-condition runs INSIDE the tracked chain, before the record is written, so
+        // an ABANDONED load is verified when it lands rather than recording a success nobody
+        // checked. The network enrichment below deliberately does NOT run there.
+        assertBudgetOpen, () => clearCachedReason(syncId));
     }
     catch (err) {
-        // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
-        // waits for it inside the lock rather than racing it.
+        // Enrich HERE, where a caller is actually waiting. Every `withApiLock` acquisition settles
+        // all registrations under ONE bound and fails closed on timeout, so two network calls inside
+        // the tracked chain would extend the window in which unrelated sessions' lock acquisitions
+        // throw, to build a message an abandoned load has no caller to read.
         if (isBudgetNotOpen(err)) {
             log.error('download resolved but no budget is open', undefined, { syncId });
             throw postConditionError(syncId, await diagnose(syncId));

package/dist/src/lib/opTimeout.js

@@ -28,15 +28,25 @@ import config from '../config.js';
  * before `Promise.race` is built (which would orphan the armed timer and later
  * fire an unhandledRejection).
  */
-export function withOpTimeout(fn, label = 'operation') {
-    const timeoutMs = config.ACTUAL_OP_TIMEOUT_MS;
+export function withOpTimeout(fn, label = 'operation', overrideMs, overrideKnob = 'ACTUAL_IMPORT_TIMEOUT_MS') {
+    // #407: an explicit override, for an operation that is legitimately long rather than stalled.
+    // A budget import is the only one today. Everything else keeps the general bound, because the
+    // whole point of #270 is that one stalled call must not hold the process-global mutex.
+    const timeoutMs = overrideMs === undefined ? config.ACTUAL_OP_TIMEOUT_MS : overrideMs;
+    // #407 review (I4): name the knob that ACTUALLY applies. Hardcoding ACTUAL_OP_TIMEOUT_MS sent an
+    // operator whose import died at the import bound to raise a variable with no effect on imports.
+    //
+    // The name is a PARAMETER rather than inferred from "an override exists" (round 2): inferring it
+    // is correct only while exactly one call site passes an override, and the second one would
+    // silently report the import knob for a different bound, which is the same misdirection.
+    const knob = overrideMs === undefined ? 'ACTUAL_OP_TIMEOUT_MS' : overrideKnob;
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         return fn();
     }
     let timer;
     const timeout = new Promise((_, reject) => {
         timer = setTimeout(() => {
-            reject(new Error(`Actual API ${label} timed out after ${timeoutMs}ms (ACTUAL_OP_TIMEOUT_MS). ` +
+            reject(new Error(`Actual API ${label} timed out after ${timeoutMs}ms (${knob}). ` +
                 'The upstream Actual server may be unreachable or stalled; the operation was ' +
                 'aborted so the session can recover. Please retry the request.'));
         }, timeoutMs);

package/package.json

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