actual-mcp-server 0.6.11 → 0.6.15

package/README.md

@@ -730,4 +730,4 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.6.11 | **Tool Count:** 63 (verified LibreChat-compatible)
+**Version:** 0.6.15 | **Tool Count:** 63 (verified LibreChat-compatible)

package/dist/package.json

@@ -1,7 +1,7 @@
 {
     "name": "actual-mcp-server",
     "displayName": "Actual MCP Server",
-    "version": "0.6.11",
+    "version": "0.6.15",
     "engines": {
         "node": ">=20.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.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/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/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/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.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/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/pool_liveness.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/payees_delete.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/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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",

package/dist/src/actualConnection.js

@@ -130,7 +130,12 @@ export async function shutdownActualForSession(sessionId) {
         return;
     }
     try {
-        await connectionPool.shutdownConnection(sessionId);
+        // evict: true so the pool tears down the matching httpServer transport too
+        // (#167). This wrapper is only used for session-ending events (explicit
+        // session_close, server shutdown); the adapter's switchBudget / infra-drop
+        // paths call connectionPool.shutdownConnection directly without evict so the
+        // transport survives a budget switch or transient error.
+        await connectionPool.shutdownConnection(sessionId, { evict: true });
         logger.info(`Actual API connection shutdown for session: ${sessionId}`);
     }
     catch (err) {

package/dist/src/lib/ActualConnectionPool.js

@@ -23,9 +23,16 @@ class ActualConnectionPool {
     cleanupInterval = null;
     IDLE_TIMEOUT; // Configurable via SESSION_IDLE_TIMEOUT_MINUTES env var (default: 5 minutes)
     CLEANUP_INTERVAL; // Check frequency (default: 2 minutes)
-    MAX_CONCURRENT_SESSIONS; // Configurable via MAX_CONCURRENT_SESSIONS env var (default: 1)
+    MAX_CONCURRENT_SESSIONS; // Configurable via MAX_CONCURRENT_SESSIONS env var (default: 15)
     sharedConnection = null;
     initializationPromise = null;
+    // Eviction listeners. The pool is the single source of truth for session
+    // liveness and idle timing (#167); when it removes a session it notifies the
+    // transport layer (httpServer) so the transport object is torn down in the
+    // same window. This is callback-based eager teardown, not lazy query-on-demand:
+    // a lazily-cleaned table would leak transport objects for sessions a client
+    // abandons without reconnecting.
+    evictionCallbacks = [];
     constructor() {
         // Read from environment variable or default to 15
         // @actual-app/api is a singleton, so concurrent sessions cause conflicts
@@ -76,6 +83,61 @@ class ActualConnectionPool {
         const conn = this.connections.get(sessionId);
         return conn?.initialized ?? false;
     }
+    /**
+     * Single source of truth for session liveness (#167). Returns true only if
+     * the session has an initialized connection that has not passed the idle
+     * timeout. Returns false for unknown or expired sessions, and never creates
+     * an entry as a side effect. httpServer uses this as a per-request defensive
+     * guard against the race where the idle sweep evicts a session while a
+     * request for it is already in flight.
+     */
+    isLive(sessionId) {
+        const conn = this.connections.get(sessionId);
+        if (!conn || !conn.initialized)
+            return false;
+        return !this.isExpired(conn);
+    }
+    /**
+     * Single definition of "past the idle window". Shared by isLive and the idle
+     * sweep so the two can never disagree about where the boundary is (#167).
+     */
+    isExpired(conn) {
+        return (Date.now() - conn.lastActivity) > this.IDLE_TIMEOUT;
+    }
+    /**
+     * Refresh a session's activity timestamp. Called by the transport layer on
+     * every request so the pool's idle clock reflects real usage (#167). Before
+     * this, the pool only stamped lastActivity at init/switch, so an actively
+     * used session's pool clock never advanced; httpServer kept a parallel
+     * activity map to compensate, which is the drift this consolidation removes.
+     * No-op for unknown sessions (does NOT create an entry).
+     */
+    touch(sessionId) {
+        const conn = this.connections.get(sessionId);
+        if (conn) {
+            conn.lastActivity = Date.now();
+        }
+    }
+    /**
+     * Register a listener invoked when the pool removes a session (idle sweep or
+     * explicit close). httpServer registers one that closes the transport and
+     * drops its table entries, keeping both tables consistent (#167). Listeners
+     * must not throw; any error is logged and swallowed so one bad listener
+     * cannot abort the removal of others.
+     */
+    onSessionEvicted(cb) {
+        this.evictionCallbacks.push(cb);
+    }
+    fireEviction(sessionId) {
+        for (const cb of this.evictionCallbacks) {
+            try {
+                cb(sessionId);
+            }
+            catch (err) {
+                logger.error(`[ConnectionPool] Eviction listener threw for session ${sessionId} (ignoring):`, err);
+            }
+        }
+    }
     /**
      * Check if we can accept a new session (under the concurrent limit)
      * Returns true if limit not reached, false otherwise
@@ -85,9 +147,36 @@ class ActualConnectionPool {
         return activeConnections < this.MAX_CONCURRENT_SESSIONS;
     }
     /**
-     * Get or create a connection for an MCP session
+     * Read-only view of the pool entry for a session. Used by switchBudget to
+     * compare the incoming budget's auth descriptor against the current entry's
+     * descriptor before deciding whether to reuse (fast path) or release+recreate
+     * (slow path). See #172.
+     */
+    getConnectionInfo(sessionId) {
+        return this.connections.get(sessionId);
+    }
+    /**
+     * Update the syncId tracked on a pool entry after a successful in-place
+     * downloadBudget(newSyncId) call. switchBudget's fast path uses this so
+     * subsequent comparisons reflect the loaded budget. See #172.
+     */
+    updateLoadedSyncId(sessionId, newSyncId) {
+        const entry = this.connections.get(sessionId);
+        if (entry) {
+            entry.syncId = newSyncId;
+            entry.lastActivity = Date.now();
+        }
+    }
+    /**
+     * Get or create a connection for an MCP session.
+     *
+     * Optional `budgetOverride` lets callers bind the new pool entry to a
+     * specific budget (used by `switchBudget` in actual-adapter.ts so the
+     * post-switch entry hits the correct upstream). Without it, defaults
+     * come from env (`ACTUAL_SERVER_URL` / `ACTUAL_PASSWORD` / `ACTUAL_BUDGET_SYNC_ID`
+     * / `ACTUAL_BUDGET_PASSWORD`), matching pre-#172 behaviour. See #172.
      */
-    async getConnection(sessionId) {
+    async getConnection(sessionId, budgetOverride) {
         let conn = this.connections.get(sessionId);
         if (conn && conn.initialized) {
             conn.lastActivity = Date.now();
@@ -103,12 +192,12 @@ class ActualConnectionPool {
         }
         // Create new connection for this session
         logger.info(`[ConnectionPool] Creating Actual connection for session: ${sessionId} (${activeConnections + 1}/${this.MAX_CONCURRENT_SESSIONS})`);
-        const SERVER_URL = config.ACTUAL_SERVER_URL;
-        const PASSWORD = config.ACTUAL_PASSWORD;
-        const BUDGET_SYNC_ID = config.ACTUAL_BUDGET_SYNC_ID;
-        const BUDGET_PASSWORD = process.env.ACTUAL_BUDGET_PASSWORD;
+        const SERVER_URL = budgetOverride?.serverUrl ?? config.ACTUAL_SERVER_URL;
+        const PASSWORD = budgetOverride?.password ?? config.ACTUAL_PASSWORD;
+        const BUDGET_SYNC_ID = budgetOverride?.syncId ?? config.ACTUAL_BUDGET_SYNC_ID;
+        const BUDGET_PASSWORD = budgetOverride?.encryptionPassword ?? process.env.ACTUAL_BUDGET_PASSWORD;
         // Use shared data directory so changes persist across sessions
-        // This is critical - all sessions must share the same database to avoid data loss
+        // This is critical: all sessions must share the same database to avoid data loss
         const DATA_DIR = config.MCP_BRIDGE_DATA_DIR || DEFAULT_DATA_DIR;
         if (!fs.existsSync(DATA_DIR)) {
             fs.mkdirSync(DATA_DIR, { recursive: true });
@@ -134,7 +223,13 @@ class ActualConnectionPool {
                 sessionId,
                 initialized: true,
                 lastActivity: Date.now(),
-                dataDir: DATA_DIR
+                dataDir: DATA_DIR,
+                // Track auth descriptor + currently-loaded budget on the pool entry
+                // so switchBudget can decide whether to reuse this entry (#172).
+                serverUrl: SERVER_URL,
+                password: PASSWORD,
+                encryptionPassword: BUDGET_PASSWORD,
+                syncId: BUDGET_SYNC_ID,
             };
             this.connections.set(sessionId, conn);
             logger.info(`[ConnectionPool] Connection ready for session: ${sessionId}`);
@@ -195,7 +290,11 @@ class ActualConnectionPool {
                 sessionId: 'shared',
                 initialized: true,
                 lastActivity: Date.now(),
-                dataDir: DATA_DIR
+                dataDir: DATA_DIR,
+                serverUrl: SERVER_URL,
+                password: PASSWORD,
+                encryptionPassword: BUDGET_PASSWORD,
+                syncId: BUDGET_SYNC_ID,
             };
             logger.info('[ConnectionPool] Shared connection ready');
         }
@@ -206,9 +305,17 @@ class ActualConnectionPool {
         }
     }
     /**
-     * Shutdown connection for a specific session
+     * Shutdown connection for a specific session.
+     *
+     * `opts.evict` controls whether eviction listeners fire (#167). Pass `true`
+     * when the session itself is ending (idle sweep, explicit session close) so
+     * the transport layer tears down its transport. Leave it false (default) when
+     * the pool entry is being recycled but the MCP session continues, e.g.
+     * switchBudget's slow path which shuts the entry down and immediately
+     * recreates it, or an infra-error drop where the next request re-establishes
+     * the connection: in those cases the transport must survive.
      */
-    async shutdownConnection(sessionId) {
+    async shutdownConnection(sessionId, opts = {}) {
         const conn = this.connections.get(sessionId);
         if (!conn || !conn.initialized) {
             return;
@@ -219,17 +326,23 @@ class ActualConnectionPool {
             if (typeof maybeApi.shutdown === 'function') {
                 await maybeApi.shutdown();
             }
-            conn.initialized = false;
-            this.connections.delete(sessionId);
-            setApiInitialized(false);
-            // NOTE: We do NOT delete the data directory because it's shared across all sessions
-            // Deleting it would cause data loss for other active sessions
             logger.info(`[ConnectionPool] Connection shutdown complete for session: ${sessionId}`);
         }
         catch (err) {
             logger.error(`[ConnectionPool] Error shutting down connection for session ${sessionId}:`, err);
-            // Even on error, the singleton is in an unknown state — don't reuse.
+        }
+        finally {
+            // Remove the entry in all cases so liveness can never report a session
+            // alive after its shutdown was attempted. On error the singleton is in
+            // an unknown state, so we must not leave it reusable either.
+            conn.initialized = false;
+            this.connections.delete(sessionId);
             setApiInitialized(false);
+            // NOTE: We do NOT delete the data directory because it's shared across all sessions
+            // Deleting it would cause data loss for other active sessions
+            if (opts.evict) {
+                this.fireEviction(sessionId);
+            }
         }
     }
     /**
@@ -298,17 +411,20 @@ class ActualConnectionPool {
      * Clean up idle connections that haven't been used recently
      */
     async cleanupIdleConnections() {
-        const now = Date.now();
         const connectionsToRemove = [];
         for (const [sessionId, conn] of this.connections.entries()) {
-            if (now - conn.lastActivity > this.IDLE_TIMEOUT) {
+            if (this.isExpired(conn)) {
                 connectionsToRemove.push(sessionId);
             }
         }
         if (connectionsToRemove.length > 0) {
             logger.info(`[ConnectionPool] Cleaning up ${connectionsToRemove.length} idle connections`);
             for (const sessionId of connectionsToRemove) {
-                await this.shutdownConnection(sessionId);
+                // evict: true so the transport layer tears down the matching transport
+                // 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 });
             }
         }
     }

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

@@ -31,15 +31,37 @@ const budgetRegistry = parseBudgetRegistry(process.env, {
 logger.info(`[ADAPTER] Budget registry: ${budgetRegistry.size} budget(s) — ` +
     [...budgetRegistry.values()].map(b => `"${b.name}" (${b.serverUrl})`).join(', '));
 /**
- * Key (lowercased budget name) of the currently active budget.
- * Null = use the first entry in the registry (the default budget).
+ * Per-session active budget. Map from sessionId to lowercased budget key
+ * (matches the keys in budgetRegistry).
+ *
+ * Issue #156: previously a single module-level `activeBudgetKey` was shared
+ * across all sessions. In multi-user OIDC mode that meant one user's
+ * actual_budgets_switch silently flipped the active budget for every other
+ * concurrent session, leaking financial data across tenants. The per-session
+ * map closes that hole: each MCP sessionId has its own slot.
+ *
+ * Sessions without an entry (or callers outside any requestContext.run scope:
+ * stdio mode, startup health checks) fall back to the env-default budget
+ * (first entry in budgetRegistry).
+ *
+ * Lifecycle: entries are removed on session close via session_close.ts and
+ * implicitly when connectionPool.shutdownConnection runs (switchBudget calls
+ * it to drop the stale pool entry bound to the previous syncId).
  */
-let activeBudgetKey = null;
+const sessionBudgetState = new Map();
 function getActiveBudgetConfig() {
-    if (activeBudgetKey) {
-        const found = budgetRegistry.get(activeBudgetKey);
-        if (found)
-            return found;
+    // _resolveSessionId is declared below; function declarations hoist so this
+    // call works at runtime. If we're not in any requestContext.run scope (stdio,
+    // startup health checks), sessionId is undefined and we fall back to the
+    // env-default budget (first registry entry).
+    const sessionId = requestContext.getStore()?.sessionId;
+    if (sessionId) {
+        const key = sessionBudgetState.get(sessionId);
+        if (key) {
+            const found = budgetRegistry.get(key);
+            if (found)
+                return found;
+        }
     }
     return [...budgetRegistry.values()][0];
 }
@@ -120,6 +142,65 @@ function _shouldDropPoolOnError(err) {
         msg.includes('out of memory') ||
         msg.includes('ENOMEM'));
 }
+/**
+ * Enforce per-request budget ACL before any pool branching or lock acquisition.
+ *
+ * Issue #156: the documented isolation model (CF-5 OIDC + AUTH_BUDGET_ACL)
+ * was never wired through to tool dispatch. canAccessBudget() in
+ * src/auth/budget-acl.ts had zero call sites; budgetAclMiddleware only
+ * attached req.allowedBudgets and trusted callers to honour it.
+ *
+ * This function is the single enforcement choke point: every withActualApi /
+ * withActualApiWrite call passes through it. If the resolved active budget's
+ * syncId is not in the request's allowedBudgets list, we throw with a clear
+ * message and log at warn level with structured fields.
+ *
+ * stdio short-circuit: when there's no sessionId in context AND AUTH_PROVIDER
+ * is not 'oidc', we treat the caller as trusted-local. stdio mode runs
+ * outside requestContext.run by design (the transport handler is single-user
+ * local on a process the user already controls), so requiring allowedBudgets
+ * there would break stdio entirely. This short-circuit is load-bearing for
+ * Claude Desktop / Claude Code compatibility.
+ */
+function _enforceBudgetAcl(toolName) {
+    const store = requestContext.getStore();
+    const sessionId = store?.sessionId;
+    const allowedBudgets = store?.allowedBudgets;
+    // Trusted-local short-circuit. stdio and startup health checks run with no
+    // sessionId; in non-OIDC modes those are by-construction trusted (single
+    // user, local process). The ACL only applies when an authenticated multi-
+    // user context is in play (AUTH_PROVIDER === 'oidc').
+    if (!sessionId && config.AUTH_PROVIDER !== 'oidc') {
+        return;
+    }
+    // OIDC + no allowedBudgets in context: the request slipped past the
+    // middleware. Defence-in-depth: refuse rather than fail open.
+    if (config.AUTH_PROVIDER === 'oidc' && !allowedBudgets) {
+        logger.warn(JSON.stringify({
+            event: 'acl_denied',
+            reason: 'no_allowed_budgets_in_context',
+            sessionId: sessionId ?? null,
+            tool: toolName ?? null,
+        }));
+        throw new Error('Budget ACL: no allowedBudgets in request context. ' +
+            'This request bypassed the budget-acl middleware. Refusing for safety. See #156.');
+    }
+    // No restriction.
+    if (!allowedBudgets || allowedBudgets.includes('*'))
+        return;
+    const target = getActiveBudgetConfig();
+    if (!allowedBudgets.includes(target.syncId)) {
+        logger.warn(JSON.stringify({
+            event: 'acl_denied',
+            principal: null,
+            attemptedBudget: target.syncId,
+            allowedBudgets,
+            sessionId: sessionId ?? null,
+            tool: toolName ?? null,
+        }));
+        throw new Error(`Budget ACL: budget "${target.name}" (${target.syncId}) is not in this session's allowedBudgets.`);
+    }
+}
 /**
  * Helper to run an operation with the Actual API ready, deciding the lifecycle
  * mode automatically:
@@ -139,6 +220,10 @@ function _shouldDropPoolOnError(err) {
  * `@actual-app/api` is a process-wide singleton.
  */
 export async function withActualApi(operation) {
+    // ACL enforcement BEFORE pool branching or lock acquisition (#156).
+    // Denial here means the lock is never acquired and no upstream resource is
+    // touched.
+    _enforceBudgetAcl();
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         // Pooled mode: skip init+shutdown.
@@ -191,6 +276,8 @@ export async function withActualApi(operation) {
  * generalised to single-write call sites.
  */
 export async function withActualApiWrite(operation) {
+    // ACL enforcement BEFORE pool branching or lock acquisition (#156).
+    _enforceBudgetAcl();
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         return withApiLock(async () => {
@@ -475,6 +562,9 @@ const queue = [];
 let writeQueue = [];
 let isProcessingWrites = false;
 let writeSessionTimeout = null;
+// Counter for diagnostic: writes that reused an existing pool connection
+// (skipped the per-op init). Surfaces in getConcurrencyState(). See #158.
+let writeConnectionReuseCount = 0;
 async function processWriteQueue() {
     // Atomically check and set processing flag to prevent race conditions
     if (isProcessingWrites || writeQueue.length === 0)
@@ -486,12 +576,34 @@ async function processWriteQueue() {
         writeSessionTimeout = null;
     }
     const batch = writeQueue.splice(0, writeQueue.length); // Take all current items
-    logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations`);
+    // Pool-cooperation decision (#158): use the first queued op's captured
+    // sessionId as the batch's sessionId. In practice all ops batched together
+    // came from the same setTimeout window and same request, so they share
+    // a session. The heuristic is safe: a stale sessionId just means we take
+    // the legacy branch, never that we attribute one session's writes to
+    // another's pool entry.
+    const batchSessionId = batch[0]?.sessionId;
+    const usePoolBranch = !!batchSessionId && _hasPooledConnection(batchSessionId);
+    logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations ` +
+        `(sessionId=${batchSessionId ?? 'none'}, poolBranch=${usePoolBranch})`);
     try {
         await withApiLock(async () => {
             try {
-                // Initialize API once for all queued writes
-                await initActualApiForOperation();
+                if (usePoolBranch) {
+                    // Pool branch: api singleton already live for this session, no need
+                    // to init or shutdown around the batch. Sync at the end to commit
+                    // writes upstream. On infrastructure-level errors, release the pool
+                    // entry so the next call materialises a fresh connection.
+                    writeConnectionReuseCount++;
+                    logger.debug(`[WRITE QUEUE] Reusing pool connection for session ${batchSessionId} ` +
+                        `(writeReuses=${writeConnectionReuseCount})`);
+                }
+                else {
+                    // Legacy branch: no pool entry, init+shutdown around the batch as
+                    // before. initActualApiForOperation() still short-circuits if the
+                    // api is somehow already live (e.g. another path init'd it).
+                    await initActualApiForOperation();
+                }
                 // Process all queued writes in the same session
                 // Each operation handles its own success/failure
                 await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
@@ -504,8 +616,8 @@ async function processWriteQueue() {
                         reject(error);
                     }
                 }));
-                // Explicitly sync changes to server before shutdown
-                // This ensures all write operations are persisted
+                // Explicitly sync changes to server before shutdown (legacy) or just
+                // before returning (pool). Persistence guarantee in both branches.
                 logger.debug(`[WRITE QUEUE] Syncing ${batch.length} operations to server`);
                 try {
                     await api.sync();
@@ -513,11 +625,27 @@ async function processWriteQueue() {
                 }
                 catch (syncError) {
                     logger.error('[WRITE QUEUE] Sync failed:', syncError);
+                    // Pool branch: drop the connection on infrastructure-level sync
+                    // failure so the next write re-initialises cleanly. Mirrors
+                    // withActualApiWrite's policy.
+                    if (usePoolBranch && _shouldDropPoolOnError(syncError)) {
+                        logger.warn(`[WRITE QUEUE] Releasing pool connection for session ${batchSessionId} after sync failure`);
+                        try {
+                            await connectionPool.shutdownConnection(batchSessionId);
+                        }
+                        catch (_e) {
+                            /* swallow */
+                        }
+                    }
                     // Don't throw - we still want to shutdown cleanly
                     // Individual operation errors were already reported to callers
                 }
-                // Shutdown after all writes complete and sync
-                await shutdownActualApi();
+                if (!usePoolBranch) {
+                    // Legacy branch only: actually shut the singleton down.
+                    // shutdownActualApi() itself short-circuits to sync-only if another
+                    // path has active pool sessions, so this is safe under contention.
+                    await shutdownActualApi();
+                }
                 logger.debug(`[WRITE QUEUE] Batch completed successfully`);
             }
             catch (error) {
@@ -531,7 +659,21 @@ async function processWriteQueue() {
                         logger.error('[WRITE QUEUE] Error rejecting operation:', e);
                     }
                 });
-                await shutdownActualApi();
+                // Pool branch: drop the pool entry if the error suggests infrastructure
+                // corruption. Legacy branch: full shutdown.
+                if (usePoolBranch) {
+                    if (_shouldDropPoolOnError(error)) {
+                        try {
+                            await connectionPool.shutdownConnection(batchSessionId);
+                        }
+                        catch (_e) {
+                            /* swallow */
+                        }
+                    }
+                }
+                else {
+                    await shutdownActualApi();
+                }
             }
         });
     }
@@ -546,8 +688,15 @@ async function processWriteQueue() {
     }
 }
 function queueWriteOperation(operation) {
+    // ACL enforcement at the write-queue entry (#156). Failing here means the
+    // 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
+    // decision in processWriteQueue would always miss. See #158.
+    const sessionId = _resolveSessionId();
     return new Promise((resolve, reject) => {
-        writeQueue.push({ operation, resolve, reject });
+        writeQueue.push({ operation, resolve, reject, sessionId });
         // Clear existing timeout
         if (writeSessionTimeout) {
             clearTimeout(writeSessionTimeout);
@@ -638,6 +787,11 @@ export function getConcurrencyState() {
         // structurally always 0; post-#134 it should grow at least linearly with
         // tool-call volume on healthy MCP sessions.
         connectionReuses: connectionReuseCount,
+        // Pool-cooperation observability for WRITES (issue #158). Before #158 the
+        // write path (processWriteQueue) never used the pool branch explicitly,
+        // so this counter stayed at 0 even when reads were reusing the pool.
+        // Post-#158 it grows with write volume on pooled sessions.
+        writeConnectionReuses: writeConnectionReuseCount,
     };
 }
 /**
@@ -1595,35 +1749,149 @@ export async function getBudgets() {
     });
 }
 /**
- * Switch the active budget by name (case-insensitive, partial match supported).
+ * Switch the active budget by name (case-insensitive, EXACT match only).
  * The budget must be pre-configured via BUDGET_n_NAME env vars.
- * Switching is instant — no API call required; the next withActualApi
- * call will automatically connect to the new budget's server and sync ID.
+ *
+ * Issue #156:
+ *   * Per-session: writes to the per-session map keyed by current sessionId.
+ *     Stdio / non-session callers fall back to the env-default budget and
+ *     cannot switch (returns an error).
+ *   * ACL: refuses when the target budget's syncId is not in this session's
+ *     allowedBudgets.
+ *   * Exact match only (substring matching removed: it was a sharp edge that
+ *     allowed an LLM prompt-injection to walk the registry).
+ *   * Pool release: BEFORE mutating the session map, releases the existing
+ *     pool entry bound to the previous syncId. The next withActualApi call
+ *     materialises a fresh pool entry against the new budget. Without this,
+ *     the stale pool entry would serve the new request against the old
+ *     upstream.
  */
-export function switchBudget(name) {
-    const key = name.toLowerCase();
-    let found = budgetRegistry.get(key);
-    let foundKey = key;
-    if (!found) {
-        // Partial / substring match
-        for (const [k, v] of budgetRegistry) {
-            if (k.includes(key) || key.includes(k)) {
-                found = v;
-                foundKey = k;
-                break;
-            }
-        }
+export async function switchBudget(name) {
+    const store = requestContext.getStore();
+    const sessionId = store?.sessionId;
+    const allowedBudgets = store?.allowedBudgets;
+    // Stdio / no-session callers: per-session map has no slot for them, so the
+    // switch would have no effect. Refuse explicitly rather than silently no-op.
+    if (!sessionId) {
+        throw new Error('Budget switch requires an MCP session. Stdio/local callers operate on the env-default budget; ' +
+            'configure ACTUAL_BUDGET_SYNC_ID (or the BUDGET_n_* variants) to select a different default.');
     }
+    const key = name.toLowerCase();
+    const found = budgetRegistry.get(key);
     if (!found) {
         const available = [...budgetRegistry.values()].map(b => `"${b.name}"`).join(', ');
         throw new Error(`Budget "${name}" not found in configuration. ` +
             `Available budgets: ${available}. ` +
             `Add BUDGET_n_NAME/SYNC_ID/SERVER_URL vars to configure additional budgets.`);
     }
-    activeBudgetKey = foundKey;
-    logger.info(`[ADAPTER] Active budget switched to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
+    // ACL enforcement: the target budget must be in this session's allowedBudgets.
+    // OIDC mode: explicit ACL required. Non-OIDC: short-circuit allow (single-user).
+    if (config.AUTH_PROVIDER === 'oidc') {
+        if (!allowedBudgets) {
+            logger.warn(JSON.stringify({
+                event: 'acl_denied',
+                reason: 'no_allowed_budgets_in_context',
+                attemptedBudget: found.syncId,
+                sessionId,
+                tool: 'actual_budgets_switch',
+            }));
+            throw new Error(`Budget ACL: cannot switch to "${found.name}". No allowedBudgets in request context.`);
+        }
+        if (!allowedBudgets.includes('*') && !allowedBudgets.includes(found.syncId)) {
+            logger.warn(JSON.stringify({
+                event: 'acl_denied',
+                attemptedBudget: found.syncId,
+                allowedBudgets,
+                sessionId,
+                tool: 'actual_budgets_switch',
+            }));
+            throw new Error(`Budget ACL: budget "${found.name}" (${found.syncId}) is not in this session's allowedBudgets.`);
+        }
+    }
+    // Fast path (#172): if the current pool entry's auth descriptor matches the
+    // target budget's (same serverUrl + password + encryptionPassword), skip
+    // release + re-auth. Just download the new budget file on the already-
+    // authenticated api singleton. Eliminates the upstream login burst when
+    // switching between budgets hosted on the same Actual server.
+    const currentEntry = connectionPool.getConnectionInfo(sessionId);
+    const sameAuth = !!currentEntry &&
+        currentEntry.serverUrl === found.serverUrl &&
+        currentEntry.password === (found.password || '') &&
+        (currentEntry.encryptionPassword ?? '') === (found.encryptionPassword ?? '');
+    if (sameAuth && currentEntry.syncId === found.syncId) {
+        // No-op: already on this exact budget. Keep session map consistent and return.
+        sessionBudgetState.set(sessionId, key);
+        logger.info(`[ADAPTER] switchBudget no-op for session ${sessionId}: already on "${found.name}" (${found.syncId})`);
+        return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+    }
+    if (sameAuth) {
+        // Same server + creds, different syncId. Reload budget file in place.
+        logger.info(`[ADAPTER] switchBudget fast path for session ${sessionId}: ` +
+            `same server, reloading budget "${found.name}" (${found.syncId})`);
+        if (_skipApiInitForTests) {
+            // Skip the real downloadBudget call in tests; tests verify the fast
+            // path was taken by spying on connectionPool.shutdownConnection.
+        }
+        else {
+            await withApiLock(async () => {
+                if (found.encryptionPassword) {
+                    const apiWithOptions = api;
+                    await apiWithOptions.downloadBudget(found.syncId, { password: found.encryptionPassword });
+                }
+                else {
+                    await api.downloadBudget(found.syncId);
+                }
+            });
+        }
+        connectionPool.updateLoadedSyncId(sessionId, found.syncId);
+        sessionBudgetState.set(sessionId, key);
+        logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
+        return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
+    }
+    // Slow path: different server or credentials. Release the existing pool
+    // entry (bound to the previous syncId / server) BEFORE mutating the session
+    // map. Swallow shutdown errors: a stale or missing pool entry is benign.
+    try {
+        await connectionPool.shutdownConnection(sessionId);
+    }
+    catch (e) {
+        logger.debug(`[ADAPTER] switchBudget: shutdownConnection raised (likely no prior entry): ${e}`);
+    }
+    // Update the per-session active-budget slot. Subsequent getActiveBudgetConfig
+    // calls for this session now return the new budget.
+    sessionBudgetState.set(sessionId, key);
+    // Materialise a fresh pool entry bound to the new budget. Without this, the
+    // next withActualApi call would find no pool entry and fall back to the
+    // legacy init+shutdown path. Failure here is logged but not fatal: the
+    // legacy fallback still works, just less efficiently.
+    if (_skipApiInitForTests) {
+        setApiInitialized(true);
+    }
+    else {
+        try {
+            await connectionPool.getConnection(sessionId, {
+                serverUrl: found.serverUrl,
+                password: found.password || '',
+                syncId: found.syncId,
+                encryptionPassword: found.encryptionPassword,
+            });
+        }
+        catch (poolErr) {
+            logger.warn(`[ADAPTER] switchBudget: failed to materialise new pool entry for session ${sessionId}: ${poolErr}. ` +
+                'Subsequent calls will use the legacy init+shutdown fallback.');
+        }
+    }
+    logger.info(`[ADAPTER] Active budget switched for session ${sessionId} to: "${found.name}" (${found.syncId}) on ${found.serverUrl}`);
     return { name: found.name, syncId: found.syncId, serverUrl: found.serverUrl };
 }
+/**
+ * Clear the per-session budget state for a session. Called from
+ * session_close so the per-session map does not accumulate stale entries
+ * after a session ends. See #156.
+ */
+export function clearSessionBudgetState(sessionId) {
+    sessionBudgetState.delete(sessionId);
+}
 /**
  * Return all configured budgets from the registry (for listing in actual_budgets_list_available).
  */

package/dist/src/lib/node-polyfills.js

@@ -3,7 +3,14 @@
  *
  * @actual-app/api v26.3.0 introduced `navigator.platform` usage at the module
  * top level (inside the Electron/browser bundle) which crashes on Node.js with
- * `ReferenceError: navigator is not defined`.
+ * `ReferenceError: navigator is not defined`. v26.6.0 additionally reads
+ * `navigator.userAgent` at the top level (`navigator.userAgent.includes(...)`
+ * plus a UAParser call), so the polyfill must define `userAgent` too or the
+ * bundle throws `Cannot read properties of undefined (reading 'includes')`.
+ *
+ * Node 21+ ships a native `navigator` that already carries both fields, so this
+ * polyfill only fires on Node 20 (still inside the documented "Node.js 20+"
+ * support range, and the version several CI workflows run on).
  *
  * This file must be imported BEFORE any `@actual-app/api` import so that the
  * global is defined when the bundle is first evaluated.
@@ -12,6 +19,7 @@ if (typeof globalThis.navigator === 'undefined') {
     Object.defineProperty(globalThis, 'navigator', {
         value: {
             platform: process.platform === 'win32' ? 'Win32' : 'Linux',
+            userAgent: `Node.js/${process.version}`,
         },
         writable: true,
         configurable: true,

package/dist/src/lib/rejection-allowlist.js

@@ -4,6 +4,27 @@
  * Returns true when a rejection should be logged but the server should keep
  * running. Centralised here so it can be unit-tested without importing the
  * full server entrypoint.
+ *
+ * INVARIANT: this module MUST remain side-effect-free.
+ *
+ * src/index.ts registers the process.on('unhandledRejection', ...) handler
+ * AFTER importing this module (ESM static imports are evaluated before the
+ * top-level body runs). Any side effect introduced here, e.g. importing a
+ * logger that performs winston/file-handle init, importing dotenv, or any
+ * code that runs at module load, opens a window during ESM evaluation in
+ * which an unhandled rejection bypasses this allow-list and crashes the
+ * server. That is exactly the latent regression the #152 fix was meant to
+ * prevent.
+ *
+ * Concretely:
+ *   - No imports (static, dynamic, require, await import) of project modules.
+ *   - Only node: builtins are permitted, and only if strictly necessary.
+ *   - No top-level statements other than function/export declarations.
+ *
+ * Enforcement: tests/unit/rejection-allowlist-purity.test.js parses this
+ * source file and exits non-zero if any forbidden construct is present, or
+ * if the sentinel below is missing. The sentinel makes deletion of this
+ * docblock a hard-fail at CI time.
  */
 export function isKnownBenignRejection(reason) {
     const reasonStr = String(reason);

package/dist/src/lib/requestContext.js

@@ -1,17 +1,26 @@
 import { AsyncLocalStorage } from 'async_hooks';
 /**
- * Per-request AsyncLocalStorage. Carries the active MCP sessionId across
- * async boundaries so adapter / tool code can identify which session is
- * making the call without threading an argument through every layer.
+ * Per-request AsyncLocalStorage. Carries the active MCP sessionId and the
+ * allow-listed budget sync IDs across async boundaries so adapter / tool
+ * code can identify the request without threading arguments through every
+ * layer.
  *
  * Producer: src/server/httpServer.ts wraps each `transport.handleRequest()`
- * call in `requestContext.run({ sessionId }, …)`.
+ * call in `requestContext.run({ sessionId, allowedBudgets }, …)`.
  *
- * Consumer: src/lib/actual-adapter.ts uses `requestContext.getStore()?.sessionId`
- * to decide whether the session has an initialised pool connection it can
- * reuse (eliminating the per-op login burst — see #134).
+ * Consumers:
+ *   * src/lib/actual-adapter.ts: pool-vs-legacy branch decision via
+ *     `requestContext.getStore()?.sessionId` (see #134).
+ *   * src/lib/actual-adapter.ts: ACL enforcement at the top of withActualApi
+ *     via `requestContext.getStore()?.allowedBudgets` (see #156).
  *
  * Lives in src/lib/ rather than src/server/ to avoid the circular import that
  * would otherwise exist between httpServer.ts and actual-adapter.ts.
+ *
+ * Note: `allowedBudgets` semantics mirror the budget-acl middleware output.
+ * `['*']` means unrestricted; `[]` means no access. When `allowedBudgets` is
+ * undefined (e.g. stdio mode or no requestContext.run wrapper), the adapter
+ * falls back to its trusted-local short-circuit when AUTH_PROVIDER is not
+ * 'oidc'.
  */
 export const requestContext = new AsyncLocalStorage();

package/dist/src/server/httpServer.js

@@ -1,5 +1,5 @@
 import express from 'express';
-import { randomUUID } from 'crypto';
+import { randomUUID, timingSafeEqual } from 'node:crypto';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
@@ -7,6 +7,7 @@ import logger from '../logger.js';
 import { getLocalIp } from '../utils.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, canAcceptNewSession } from '../actualConnection.js';
+import { connectionPool } from '../lib/ActualConnectionPool.js';
 import observability from '../observability.js';
 import config from '../config.js';
 import { createRemoteJWKSet, jwtVerify } from 'jose';
@@ -75,31 +76,30 @@ bindHost = 'localhost', advertisedUrl) {
         }
     }
     const transports = new Map();
-    const sessionLastActivity = new Map();
     const sessionInitPromises = new Map(); // Track session init completion
-    // Use same timeout as ConnectionPool (SESSION_IDLE_TIMEOUT_MINUTES env var, default: 2 minutes)
-    const idleTimeoutMinutes = parseInt(process.env.SESSION_IDLE_TIMEOUT_MINUTES || '2', 10);
-    const SESSION_TIMEOUT_MS = idleTimeoutMinutes * 60 * 1000;
-    const SESSION_CLEANUP_INTERVAL_MS = 30 * 1000; // Check every 30 seconds
     // safe fallback if index didn't provide implementedTools
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
-    // Session cleanup: check for idle sessions periodically
-    const cleanupInterval = setInterval(async () => {
-        const now = Date.now();
-        const sessionsToCleanup = [];
-        for (const [sessionId, lastActivity] of sessionLastActivity.entries()) {
-            if (now - lastActivity > SESSION_TIMEOUT_MS) {
-                sessionsToCleanup.push(sessionId);
+    // Session liveness and idle timing are owned solely by the connection pool
+    // (#167). httpServer no longer runs its own idle timer or activity map; it
+    // owns only the transport objects. When the pool removes a session (idle
+    // sweep or explicit close) it fires this eviction listener, which tears down
+    // the matching transport in the same window. This is what keeps the two
+    // tables from drifting: no "alive in httpServer, dead in the pool" state, and
+    // no transport object left behind for a session the client abandoned.
+    connectionPool.onSessionEvicted((sessionId) => {
+        const transport = transports.get(sessionId);
+        if (transport) {
+            try {
+                transport.close?.();
+            }
+            catch (err) {
+                logger.debug(`[SESSION] Error closing transport for evicted session ${sessionId} (ignoring): ${err}`);
             }
         }
-        for (const sessionId of sessionsToCleanup) {
-            logger.info(`[SESSION] Cleaning up idle session: ${sessionId}`);
-            transports.delete(sessionId);
-            sessionLastActivity.delete(sessionId);
-            sessionInitPromises.delete(sessionId);
-            await shutdownActualForSession(sessionId);
-        }
-    }, SESSION_CLEANUP_INTERVAL_MS);
+        transports.delete(sessionId);
+        sessionInitPromises.delete(sessionId);
+        logger.info(`[SESSION] Transport torn down for evicted session: ${sessionId}`);
+    });
     // Authentication middleware
     const authenticateRequest = (req, res) => {
         // OIDC mode: mcp-auth middleware has already validated the JWT and populated req.auth.
@@ -124,14 +124,15 @@ bindHost = 'localhost', advertisedUrl) {
             return false;
         }
         const token = match[1];
-        // Debug logging for token comparison
-        logger.debug(`[HTTP] Auth header received: "${authHeader}"`);
-        logger.debug(`[HTTP] Extracted token: "${token}" (length: ${token.length})`);
-        logger.debug(`[HTTP] Expected token: "${config.MCP_SSE_AUTHORIZATION}" (length: ${config.MCP_SSE_AUTHORIZATION?.length || 0})`);
-        logger.debug(`[HTTP] Tokens equal: ${token === config.MCP_SSE_AUTHORIZATION}`);
-        logger.debug(`[HTTP] Token hex dump (received): ${Buffer.from(token).toString('hex')}`);
-        logger.debug(`[HTTP] Token hex dump (expected): ${Buffer.from(config.MCP_SSE_AUTHORIZATION || '').toString('hex')}`);
-        if (token !== config.MCP_SSE_AUTHORIZATION) {
+        const expected = config.MCP_SSE_AUTHORIZATION;
+        // Constant-time comparison to defeat timing oracles (#157).
+        // Length-equality short-circuit precedes timingSafeEqual because the
+        // function requires equal-length buffers. Token length is observable
+        // via response timing regardless; the secret bytes are not.
+        const tokenBuf = Buffer.from(token, 'utf8');
+        const expectedBuf = Buffer.from(expected, 'utf8');
+        const equal = tokenBuf.length === expectedBuf.length && timingSafeEqual(tokenBuf, expectedBuf);
+        if (!equal) {
             logger.warn(`[HTTP] Unauthorized request from ${req.ip || req.connection.remoteAddress}: Invalid token`);
             res.status(401).json({ error: 'Unauthorized: Invalid token' });
             return false;
@@ -332,9 +333,10 @@ bindHost = 'localhost', advertisedUrl) {
                         // Initialize connection pool for this session
                         try {
                             await connectToActualForSession(sid);
-                            // Only add to transports/activity map if connection successful
+                            // Only register the transport if the pool connection succeeded.
+                            // The pool stamped lastActivity when it created the entry, so it
+                            // is already the source of truth for this session's idle clock.
                             transports.set(sid, transport);
-                            sessionLastActivity.set(sid, Date.now());
                             logger.info(`[SESSION] Actual connection initialized for session: ${sid}`);
                             resolveInit?.();
                         }
@@ -354,7 +356,9 @@ bindHost = 'localhost', advertisedUrl) {
                 await server.connect(transport);
                 try {
                     // Run in AsyncLocalStorage context so tools can access sessionId
-                    await requestContext.run({ sessionId: undefined }, async () => {
+                    // and the adapter can enforce per-request budget ACL (#156).
+                    const allowedBudgetsInit = req.allowedBudgets;
+                    await requestContext.run({ sessionId: undefined, allowedBudgets: allowedBudgetsInit }, async () => {
                         await transport.handleRequest(req, res, req.body);
                     });
                 }
@@ -367,7 +371,18 @@ bindHost = 'localhost', advertisedUrl) {
                 }
                 return;
             }
-            // sessionId present -> reuse
+            // sessionId present -> reuse. Transport presence is the liveness signal:
+            // the pool's eviction listener (#167) removes the transport the moment a
+            // session is genuinely evicted (idle sweep or explicit close), so a
+            // missing transport means "expired" and a present one means "serve it".
+            //
+            // We deliberately do NOT additionally gate on connectionPool.isLive() here.
+            // A pool entry can be absent while the MCP session is still perfectly
+            // usable: after a transient infra error the adapter drops the pool entry
+            // (without evicting the transport) so the next call re-establishes it via
+            // the legacy fallback. Rejecting those requests as "expired" would force a
+            // needless client re-initialize on every transient blip, re-introducing
+            // the session churn this server works to avoid.
             let transport = transports.get(sessionId);
             if (!transport) {
                 // Check if session is currently being initialized
@@ -428,10 +443,12 @@ bindHost = 'localhost', advertisedUrl) {
                     return;
                 }
             }
-            // Update activity timestamp for valid session
-            sessionLastActivity.set(sessionId, Date.now());
-            // Run in AsyncLocalStorage context so tools can access sessionId
-            await requestContext.run({ sessionId }, async () => {
+            // Refresh the pool's idle clock for this session (single source of truth, #167).
+            connectionPool.touch(sessionId);
+            // Run in AsyncLocalStorage context so tools and the adapter can access
+            // sessionId (pool branch, #134) and allowedBudgets (ACL enforcement, #156).
+            const allowedBudgets = req.allowedBudgets;
+            await requestContext.run({ sessionId, allowedBudgets }, async () => {
                 await transport.handleRequest(req, res, req.body);
             });
         }
@@ -452,7 +469,7 @@ bindHost = 'localhost', advertisedUrl) {
             res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'No session id' }, id: null });
             return;
         }
-        sessionLastActivity.set(sessionId, Date.now()); // Track activity
+        connectionPool.touch(sessionId); // Refresh the pool's idle clock (#167)
         const transport = transports.get(sessionId);
         if (!transport) {
             res.status(400).json({ jsonrpc: '2.0', error: { code: -32000, message: 'Transport not ready' }, id: null });
@@ -533,12 +550,13 @@ bindHost = 'localhost', advertisedUrl) {
     // Cleanup on server shutdown
     const cleanup = async () => {
         logger.info('[SERVER] Shutting down, cleaning up sessions...');
-        clearInterval(cleanupInterval);
-        for (const sessionId of transports.keys()) {
+        // Snapshot the keys: shutdownActualForSession evicts, and the eviction
+        // listener deletes from `transports`, so iterating the live map would
+        // mutate it mid-iteration.
+        for (const sessionId of [...transports.keys()]) {
             await shutdownActualForSession(sessionId);
         }
         transports.clear();
-        sessionLastActivity.clear();
         sessionInitPromises.clear();
         // Also shut down the shared/pooled connections
         await shutdownActual();

package/dist/src/tools/budgets_switch.js

@@ -1,26 +1,35 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+// Tightened Zod schema (#156): bounded length and restricted character class.
+// Previously z.string().min(1) accepted arbitrarily long inputs with any
+// characters, which is exactly the kind of unbounded surface a prompt-injection
+// attack would target.
 const InputSchema = z.object({
-    budgetName: z.string().min(1, 'budgetName must not be empty').describe('The name of the budget to switch to, as configured via BUDGET_n_NAME environment variables. ' +
+    budgetName: z
+        .string()
+        .min(1, 'budgetName must not be empty')
+        .max(120, 'budgetName must be at most 120 characters')
+        .regex(/^[\p{L}\p{N} ._\-]+$/u, 'budgetName must contain only letters, digits, spaces, dots, underscores, and hyphens')
+        .describe('The exact name of the budget to switch to, as configured via BUDGET_n_NAME environment variables. ' +
         'Use actual_budgets_list_available to see all available budget names. ' +
-        'Partial / case-insensitive match is supported (e.g. "office" matches "Office Budget").'),
+        'Matching is case-insensitive but exact (no partial / substring match).'),
 });
 const tool = {
     name: 'actual_budgets_switch',
-    description: 'Switch to a different pre-configured budget for all subsequent operations. ' +
+    description: 'Switch to a different pre-configured budget for all subsequent operations in this session. ' +
         'Each budget can target a different Actual Budget server, sync ID, and encryption password. ' +
         'Call actual_budgets_list_available first to see the available budget names. ' +
-        'The switch is instant and takes effect immediately — no server restart required.',
+        'The switch is per-session and takes effect immediately; no server restart required.',
     inputSchema: InputSchema,
     call: async (args) => {
         const { budgetName } = InputSchema.parse(args);
-        const result = await Promise.resolve(adapter.switchBudget(budgetName));
+        const result = await adapter.switchBudget(budgetName);
         return {
             success: true,
             budgetName: result.name,
             budgetId: result.syncId,
             serverUrl: result.serverUrl,
-            message: `Switched to budget '${result.name}' (${result.syncId}) on ${result.serverUrl}. All subsequent operations now target this budget.`,
+            message: `Switched to budget '${result.name}' (${result.syncId}) on ${result.serverUrl}. All subsequent operations in this session now target this budget.`,
         };
     },
 };

package/dist/src/tools/session_close.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { connectionPool } from '../lib/ActualConnectionPool.js';
 import { shutdownActualForSession } from '../actualConnection.js';
+import { clearSessionBudgetState } from '../lib/actual-adapter.js';
 const InputSchema = z.object({
     sessionId: z.string().optional().describe('Session ID to close (partial match). If not provided, closes the oldest idle session.'),
 });
@@ -78,6 +79,9 @@ const tool = {
                 };
             }
             await shutdownActualForSession(targetSessionId);
+            // Clear the per-session active-budget state so the map does not
+            // accumulate stale entries after a session ends. See #156.
+            clearSessionBudgetState(targetSessionId);
             const newStats = connectionPool.getStats();
             return {
                 success: true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.6.11",
+  "version": "0.6.15",
   "engines": {
     "node": ">=20.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.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/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/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/payees_delete.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.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/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.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/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/pool_liveness.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/payees_delete.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/adapter_write_pool_cooperation.test.js && node tests/unit/budget_acl_enforcement.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",