actual-mcp-server 0.23.3 → 0.24.0

package/README.md

@@ -512,6 +512,7 @@ All configuration is via environment variables. Copy `.env.example` to `.env` to
 | **Session Management** ||||
 | `USE_CONNECTION_POOL` | `true` | No | Enable session-based connection pooling |
 | `MAX_CONCURRENT_SESSIONS` | `15` | No | Maximum concurrent MCP sessions allowed |
+| `MAX_SESSIONS_PER_PRINCIPAL` | unset | No | Maximum concurrent sessions per OIDC subject or named `MCP_STATIC_TOKENS` entry; unset means no per-principal cap. The legacy token and unauthenticated requests are not capped |
 | `SESSION_IDLE_TIMEOUT_MINUTES` | `5` | No | Minutes before idle session cleanup |
 | **Security & Authentication** ||||
 | `AUTH_PROVIDER` | `none` | No | Auth mode: `none` (static Bearer) or `oidc` (JWKS-validated JWT) |
@@ -838,7 +839,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.23.3 | **Tool Count:** 84 (verified LibreChat-compatible)
+**Version:** 0.24.0 | **Tool Count:** 84 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualConnection.js

@@ -16,6 +16,10 @@ let initializing = false;
 let initializationError = null;
 // Feature flag to enable connection pooling - can be disabled via environment variable
 let useConnectionPool = process.env.USE_CONNECTION_POOL !== 'false';
+// #577: the per-principal cap is a pool feature; with pooling off nothing is capped at all.
+if (!useConnectionPool && config.MAX_SESSIONS_PER_PRINCIPAL !== undefined) {
+    log.warn('MAX_SESSIONS_PER_PRINCIPAL is set but USE_CONNECTION_POOL=false, so it has no effect');
+}
 /** #530: httpServer registers sessions with the pool only when the pool is in use. */
 export function isConnectionPoolEnabled() {
     return useConnectionPool;
@@ -187,9 +191,18 @@ export function getConnectionState() {
         idleTimeoutMinutes: useConnectionPool ? connectionPool.getIdleTimeoutMinutes() : null,
     };
 }
-export function canAcceptNewSession() {
-    if (!useConnectionPool) {
-        return true; // Shared connection mode - always accept
-    }
-    return connectionPool.canAcceptNewSession();
+/**
+ * #581/#577: take a session slot at admission, synchronously, under the global cap and the
+ * per-principal cap (see `connectionPool.admitSession`). Pass a principal only for a request that
+ * is capped. Shared connection mode has no cap, so it always admits and records nothing.
+ */
+export function admitSession(sessionId, principal) {
+    if (!useConnectionPool)
+        return { admitted: true };
+    return connectionPool.admitSession(sessionId, principal);
+}
+/** #577: release the slot and the admission of an initialize that never registered. Idempotent. */
+export function releaseAdmission(sessionId) {
+    if (useConnectionPool)
+        connectionPool.releaseAdmission(sessionId);
 }

package/dist/src/config.js

@@ -139,6 +139,24 @@ export const configSchema = z.object({
     MCP_HTTP_BODY_LIMIT: z.string().default('512kb').refine((v) => parseStrictByteSize(v) !== null, 'MCP_HTTP_BODY_LIMIT must be a positive byte size such as 512kb, 1mb or 1048576 (units b, kb, mb, gb, tb, pb; ' +
         'no spaces around it, no separators; at least 1 byte and at most 9007199254740991 bytes) (#466)'),
     MAX_CONCURRENT_SESSIONS: z.string().default('15').transform(val => parseInt(val, 10)),
+    // #577: optional per-principal session cap under MAX_CONCURRENT_SESSIONS. Unset or empty means
+    // no per-principal cap; an empty value in a compose file must not abort startup, which
+    // z.coerce.number() would do (it turns '' into 0). Anything set must be a positive integer.
+    MAX_SESSIONS_PER_PRINCIPAL: z
+        .string()
+        .optional()
+        .transform((raw, ctx) => {
+        const v = (raw ?? '').trim();
+        if (v === '')
+            return undefined;
+        if (/^[1-9]\d*$/.test(v))
+            return parseInt(v, 10);
+        ctx.addIssue({
+            code: 'custom',
+            message: `MAX_SESSIONS_PER_PRINCIPAL must be a positive integer (unset or empty means no per-principal cap), got ${JSON.stringify(raw)}.`,
+        });
+        return z.NEVER;
+    }),
     // --- Published tool surface (#483) ---
     // Which tools this process publishes AND dispatches. Names are validated, and an unknown
     // one aborts startup, by resolvePublishedToolNames (src/lib/toolsets.ts) in

package/dist/src/lib/ActualConnectionPool.js

@@ -52,16 +52,38 @@ class ActualConnectionPool {
     // would close its transport mid-operation. Entries have the #392 lock re-check and the
     // #378 in-drain touch for the same hazard; registrations have neither.
     inFlight = new Map();
+    // #581: session ids that hold a slot under MAX_CONCURRENT_SESSIONS but have no initialized
+    // entry yet. Before this the cap counted initialized entries only, and an entry is created
+    // after the login and budget download, so every initialize that arrived while those were in
+    // flight saw the same count and was admitted: 6 parallel initializes all logged in under a cap
+    // of 2. A slot is now taken synchronously at admission (`reserveSession`) and handed over to
+    // the entry in one synchronous block in `getConnection`. Ids only: this count reaches the
+    // unauthenticated /health as a number, never as a list.
+    reservations = new Set();
+    // #577: session id to the principal its admission was capped under, for the session's whole
+    // lifetime (not the pool entry's: a mid-session pool drop keeps the session, so it keeps
+    // counting). A principal's count is the number of values equal to it, computed by iterating,
+    // so there is no counter to drift and a principal with no sessions has no value here. Only
+    // capped admissions are recorded: the cap must be set and the caller must pass a principal.
+    // Deleted by `forgetSession` (every session end) and `releaseAdmission` (an initialize that
+    // never registered). Never logged, never in getStats.
+    admissions = new Map();
+    MAX_SESSIONS_PER_PRINCIPAL;
     constructor() {
         // Read from environment variable or default to 15
         // @actual-app/api is a singleton, so concurrent sessions cause conflicts
         this.MAX_CONCURRENT_SESSIONS = parseInt(process.env.MAX_CONCURRENT_SESSIONS || '15', 10);
+        // #577: validated by the config schema, so no raw read here.
+        this.MAX_SESSIONS_PER_PRINCIPAL = config.MAX_SESSIONS_PER_PRINCIPAL;
         // Configurable idle timeout (in minutes)
         const idleTimeoutMinutes = parseInt(process.env.SESSION_IDLE_TIMEOUT_MINUTES || '5', 10);
         this.IDLE_TIMEOUT = idleTimeoutMinutes * 60 * 1000;
         // Cleanup runs at half the idle timeout (or 2 minutes minimum)
         this.CLEANUP_INTERVAL = Math.max(Math.floor(this.IDLE_TIMEOUT / 5), 2 * 60 * 1000);
         logger.info(`[ConnectionPool] Max concurrent sessions: ${this.MAX_CONCURRENT_SESSIONS}`);
+        if (this.MAX_SESSIONS_PER_PRINCIPAL !== undefined) {
+            logger.info(`[ConnectionPool] Max sessions per principal: ${this.MAX_SESSIONS_PER_PRINCIPAL}`);
+        }
         logger.info(`[ConnectionPool] Session idle timeout: ${idleTimeoutMinutes} minutes`);
         logger.info(`[ConnectionPool] Cleanup interval: ${Math.floor(this.CLEANUP_INTERVAL / 1000)}s`);
         // Initialize asynchronously (force close stale connections, then start cleanup timer)
@@ -147,9 +169,15 @@ class ActualConnectionPool {
     registerSession(sessionId) {
         this.registered.set(sessionId, Date.now());
     }
-    /** #530: drop a registration (idempotent). Every eviction path calls this itself. */
+    /**
+     * #530: drop a registration (idempotent). Every eviction path calls this itself.
+     * #577: also drops the session's per-principal admission. Every session end (DELETE, idle
+     * eviction, an evicting shutdown, the orphan sweep) reaches here through the transport's
+     * teardown; a non-evicting `shutdownConnection` does not, so the session keeps counting.
+     */
     forgetSession(sessionId) {
         this.registered.delete(sessionId);
+        this.admissions.delete(sessionId);
     }
     /**
      * Refresh a session's activity timestamp. Called by the transport layer on
@@ -219,12 +247,82 @@ class ActualConnectionPool {
         }
     }
     /**
-     * Check if we can accept a new session (under the concurrent limit)
-     * Returns true if limit not reached, false otherwise
+     * #581: slots held under MAX_CONCURRENT_SESSIONS, optionally leaving one session out: every
+     * initialized entry, plus every reservation whose id has no initialized entry (a session that
+     * holds both counts once).
+     */
+    slotsInUse(exclude) {
+        let n = 0;
+        for (const [id, c] of this.connections)
+            if (c.initialized && id !== exclude)
+                n++;
+        for (const id of this.reservations)
+            if (id !== exclude && !this.connections.get(id)?.initialized)
+                n++;
+        return n;
+    }
+    /** #581: reservations still waiting for their entry (a count only, see `reservations`). */
+    pendingReservations() {
+        let n = 0;
+        for (const id of this.reservations)
+            if (!this.connections.get(id)?.initialized)
+                n++;
+        return n;
+    }
+    /**
+     * #581: take a slot for `sessionId`, synchronously. The count and the add have no `await`
+     * between them, which is the whole fix: parallel callers cannot all see the same count.
+     * A session that already holds a slot (an initialized entry or a reservation) reserves again
+     * without counting twice, which is how switchBudget keeps its slot across its slow path.
+     * Every successful call must be paired with `releaseReservation` on the caller's exit path;
+     * `getConnection` hands a reservation over to the entry on success.
+     */
+    reserveSession(sessionId) {
+        return this.admitSession(sessionId).admitted;
+    }
+    /**
+     * #577: `reserveSession` plus the per-principal cap, in the same synchronous call. The global
+     * check runs first, then the per-principal one; a refusal of either scope records nothing.
+     * Only the initialize route passes a principal, and only for a request that is capped (see
+     * `capPrincipal` in httpServer.ts); every other caller is bounded by the global cap alone.
+     * A principal refusal carries the caller's own cap and count and nothing about anyone else.
+     */
+    admitSession(sessionId, principal) {
+        const holds = this.reservations.has(sessionId) || this.connections.get(sessionId)?.initialized === true;
+        if (!holds && this.slotsInUse() >= this.MAX_CONCURRENT_SESSIONS)
+            return { admitted: false, scope: 'global' };
+        const cap = this.MAX_SESSIONS_PER_PRINCIPAL;
+        const capped = principal !== undefined && cap !== undefined;
+        if (capped && !this.admissions.has(sessionId)) {
+            const count = this.principalSessions(principal);
+            if (count >= cap)
+                return { admitted: false, scope: 'principal', cap, count };
+        }
+        this.reservations.add(sessionId);
+        if (capped)
+            this.admissions.set(sessionId, principal);
+        return { admitted: true };
+    }
+    /** #577: sessions admitted under `principal` (iterated, see `admissions`). */
+    principalSessions(principal) {
+        let n = 0;
+        for (const p of this.admissions.values())
+            if (p === principal)
+                n++;
+        return n;
+    }
+    /** #581: give back a slot that never became an entry. Idempotent; a no-op after the hand-over. */
+    releaseReservation(sessionId) {
+        this.reservations.delete(sessionId);
+    }
+    /**
+     * #577: give back everything an initialize that never registered took: its slot and its
+     * per-principal admission. Idempotent. A session that did register keeps its admission until
+     * `forgetSession`.
      */
-    canAcceptNewSession() {
-        const activeConnections = Array.from(this.connections.values()).filter(c => c.initialized).length;
-        return activeConnections < this.MAX_CONCURRENT_SESSIONS;
+    releaseAdmission(sessionId) {
+        this.reservations.delete(sessionId);
+        this.admissions.delete(sessionId);
     }
     /**
      * Read-only view of the pool entry for a session. Used by switchBudget to
@@ -285,8 +383,11 @@ class ActualConnectionPool {
             logger.debug(`[ConnectionPool] Reusing connection for session: ${sessionId}`);
             return;
         }
-        // Check concurrent session limit
-        const activeConnections = Array.from(this.connections.values()).filter(c => c.initialized).length;
+        // Check concurrent session limit. #581: against every OTHER session's slot, reservations
+        // included, and take this session's slot in the same synchronous block, so a caller that
+        // did not reserve first (switchBudget's slow path, a non-HTTP caller) is just as atomic as
+        // the initialize route. A caller that already reserved keeps its reservation.
+        const activeConnections = this.slotsInUse(sessionId);
         if (activeConnections >= this.MAX_CONCURRENT_SESSIONS) {
             const errorMsg = `[ConnectionPool] Max concurrent sessions (${this.MAX_CONCURRENT_SESSIONS}) reached. Active: ${activeConnections}. Please close some connections or wait for idle sessions to timeout.`;
             logger.warn(errorMsg);
@@ -306,6 +407,9 @@ class ActualConnectionPool {
         if (!fs.existsSync(DATA_DIR)) {
             fs.mkdirSync(DATA_DIR, { recursive: true });
         }
+        // #581: taken here, still with no `await` since the check above, so that a throw before the
+        // try (the mkdir) cannot leave a slot behind; the catch below releases it on any failure.
+        this.reservations.add(sessionId);
         try {
             // #390 round 2: hold the api mutex across init + download.
             //
@@ -349,7 +453,10 @@ class ActualConnectionPool {
                 encryptionPassword: BUDGET_PASSWORD,
                 syncId: BUDGET_SYNC_ID,
             };
+            // #581: the hand-over. Both in one synchronous block, so the slot is never counted twice
+            // (entry plus reservation) or not at all.
             this.connections.set(sessionId, conn);
+            this.reservations.delete(sessionId);
             logger.info(`[ConnectionPool] Connection ready for session: ${sessionId}`);
         }
         catch (err) {
@@ -382,6 +489,8 @@ class ActualConnectionPool {
             setApiInitialized(false);
             // Ensure this session is not in the connections map
             this.connections.delete(sessionId);
+            // #581: and holds no slot.
+            this.reservations.delete(sessionId);
             throw err;
         }
     }
@@ -780,6 +889,7 @@ class ActualConnectionPool {
         return {
             totalSessions: this.connections.size,
             activeSessions: Array.from(this.connections.values()).filter(c => c.initialized).length,
+            pendingReservations: this.pendingReservations(),
             maxConcurrent: this.MAX_CONCURRENT_SESSIONS,
             sharedConnection: this.sharedConnection?.initialized || false,
             sessions

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

@@ -4111,55 +4111,72 @@ export async function switchBudget(name) {
         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.
-    setSessionBudget(sessionId, key);
-    setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
-    // 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.
-    //
-    // #348 EXCEPTION: never for a stdio session. stdio gained a synthetic session
-    // id so it could switch budgets at all, but it must stay on the legacy
-    // 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 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.
-    if (store?.transport === 'stdio') {
-        logger.debug(`[ADAPTER] switchBudget: session ${sessionId} is stdio; skipping pool materialisation ` +
-            '(stdio stays on the legacy init/shutdown path by design, #348).');
-    }
-    else if (_skipApiInitForTests) {
-        setApiInitialized(true);
+    // #581: hold this session's slot across the window between releasing the old entry and
+    // creating the new one, so a concurrent initialize cannot take it and leave this session over
+    // the cap. A session that holds a slot always re-reserves; one whose entry was already dropped
+    // may be refused when the pool is full, and getConnection below then fails the same way it
+    // always has (the legacy fallback). stdio never has a pool entry, so it reserves nothing.
+    const holdsSlot = store?.transport !== 'stdio' && connectionPool.reserveSession(sessionId);
+    if (store?.transport !== 'stdio' && !holdsSlot) {
+        logger.warn(`[ADAPTER] switchBudget: session ${sessionId} holds no pool slot and the pool is full; ` +
+            'the switch proceeds on the legacy init+shutdown fallback.');
     }
-    else {
+    try {
+        // 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.getConnection(sessionId, {
-                serverUrl: found.serverUrl,
-                password: found.password || '',
-                syncId: found.syncId,
-                encryptionPassword: found.encryptionPassword,
-            });
+            await connectionPool.shutdownConnection(sessionId);
         }
-        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.');
+        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.
+        setSessionBudget(sessionId, key);
+        setPreferredBudgetSyncId(store?.principal, found.syncId); // #189: persist at commit
+        // 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.
+        //
+        // #348 EXCEPTION: never for a stdio session. stdio gained a synthetic session
+        // id so it could switch budgets at all, but it must stay on the legacy
+        // 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 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.
+        if (store?.transport === 'stdio') {
+            logger.debug(`[ADAPTER] switchBudget: session ${sessionId} is stdio; skipping pool materialisation ` +
+                '(stdio stays on the legacy init/shutdown path by design, #348).');
+        }
+        else 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.');
+            }
+        }
+    }
+    finally {
+        // A no-op once getConnection handed the reservation over to the new entry.
+        if (holdsSlot)
+            connectionPool.releaseReservation(sessionId);
     }
     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 };

package/dist/src/server/httpServer.js

@@ -7,7 +7,7 @@ import logger, { resolveRequestId } from '../logger.js';
 import { attachTransportErrorLogger } from '../lib/transportErrorLogger.js';
 import { getLocalIp } from '../utils.js';
 import actualToolsManager from '../actualToolsManager.js';
-import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, canAcceptNewSession, isConnectionPoolEnabled } from '../actualConnection.js';
+import { getConnectionState, connectToActualForSession, shutdownActualForSession, shutdownActual, admitSession, releaseAdmission, isConnectionPoolEnabled } from '../actualConnection.js';
 import { connectionPool } from '../lib/ActualConnectionPool.js';
 import { clearSessionBudgetState, setSessionLivenessCheck, initialBudgetForSession, getBudgetRegistry } from '../lib/actual-adapter.js';
 import { errorLogFields } from '../lib/errors.js';
@@ -57,6 +57,18 @@ function resolvePrincipal(req) {
         return staticPrincipal;
     return config.MCP_SSE_AUTHORIZATION ? LEGACY_STATIC_PRINCIPAL : undefined;
 }
+// #577: the principal MAX_SESSIONS_PER_PRINCIPAL caps, decided by HOW the request authenticated,
+// never by the principal string (an OIDC subject that happens to read "static-bearer" is capped).
+// OIDC: the verified subject. A MCP_STATIC_TOKENS token: its own principal. Exempt, so bounded by
+// the global cap alone: the legacy MCP_SSE_AUTHORIZATION token, which every holder shares (capping
+// it would silently lower the effective global cap on every single-token deployment), and an
+// unauthenticated request, which has no principal.
+function capPrincipal(req) {
+    if (config.AUTH_PROVIDER === 'oidc') {
+        return req.auth?.subject;
+    }
+    return req.staticPrincipal;
+}
 export async function startHttpServer(mcp, port, httpPath, capabilities, // was passed by index.ts
 implementedTools, // was passed by index.ts
 serverDescription, // was passed by index.ts
@@ -497,8 +509,34 @@ advertisedUrl) {
                     });
                     return;
                 }
-                // Check if we can accept a new session (concurrent limit)
-                if (!canAcceptNewSession()) {
+                // Check if we can accept a new session (concurrent limit). #581: the session id is chosen
+                // HERE and its slot reserved synchronously under it, before anything awaits. Checking a
+                // count and reserving later (at login) admitted every initialize that arrived while
+                // earlier ones were still logging in.
+                // #577: the per-principal cap is checked in the same synchronous call, after the global one.
+                const sid = randomUUID();
+                const admission = admitSession(sid, capPrincipal(req));
+                if (!admission.admitted && admission.scope === 'principal') {
+                    const timeoutMinutes = getConnectionState().idleTimeoutMinutes || 2;
+                    // Only the caller's own cap and count: nothing here is derived from another principal,
+                    // and the log line carries no principal and no session id.
+                    logger.warn('[SESSION] Rejecting new session: per-principal cap reached', { cap: admission.cap, count: admission.count });
+                    res.status(503).json({
+                        jsonrpc: '2.0',
+                        id: payload?.id ?? null,
+                        error: {
+                            code: -32000,
+                            message: `Max sessions per principal (${admission.cap}) reached. Yours: ${admission.count}. Please close one of your sessions or wait for idle sessions to time out (${timeoutMinutes} minutes).`,
+                            data: {
+                                maxSessionsPerPrincipal: admission.cap,
+                                yourSessions: admission.count,
+                                idleTimeoutMinutes: timeoutMinutes,
+                            },
+                        },
+                    });
+                    return;
+                }
+                if (!admission.admitted) {
                     const state = getConnectionState();
                     const stats = state.connectionPool;
                     const timeoutMinutes = state.idleTimeoutMinutes || 2;
@@ -513,107 +551,121 @@ advertisedUrl) {
                             data: {
                                 maxConcurrent: stats?.maxConcurrent,
                                 activeSessions: stats?.activeSessions,
-                                availableSlots: (stats?.maxConcurrent ?? 0) - (stats?.activeSessions ?? 0),
+                                pendingReservations: stats?.pendingReservations,
+                                availableSlots: Math.max(0, (stats?.maxConcurrent ?? 0) - (stats?.activeSessions ?? 0) - (stats?.pendingReservations ?? 0)),
                                 idleTimeoutMinutes: timeoutMinutes
                             }
                         },
                     });
                     return;
                 }
-                logger.debug('[SESSION] Creating new MCP server + transport for initialize');
-                const { server } = createServerInstance();
-                // Create a promise to track session initialization completion
-                let resolveInit;
-                let rejectInit;
-                const initPromise = new Promise((resolve, reject) => {
-                    resolveInit = resolve;
-                    rejectInit = reject;
-                });
-                // Always-on safety net: if no concurrent code path is awaiting initPromise
-                // when rejectInit fires (e.g. session init fails before any tools/call
-                // arrives), the rejection would otherwise hit process.on('unhandledRejection')
-                // and exit the server. The original error is already logged inside the
-                // onsessioninitialized catch block below: we deliberately do NOT re-log here
-                // to avoid duplicate noise and any risk of leaking credentials.
-                initPromise.catch(() => { });
-                // The session belongs to the principal that initialized it. Resolved here,
-                // from this request, so the owner can never come from a later request.
-                const sessionOwner = resolvePrincipal(req);
-                const transport = new StreamableHTTPServerTransport({
-                    sessionIdGenerator: () => randomUUID(),
-                    enableJsonResponse: true,
-                    // #563: the SDK awaits this on a valid DELETE, BEFORE it answers 200, so the pool
-                    // slot is free by the time the client hears the session ended. It waits for the api
-                    // mutex (#392), so another session's call in flight finishes first. Without evict:
-                    // the DELETE route tears the session down itself after the 200.
-                    onsessionclosed: async (sid) => {
-                        if (isConnectionPoolEnabled())
-                            await connectionPool.shutdownConnection(sid);
-                    },
-                    onsessioninitialized: async (sid) => {
-                        logger.debug(`Session initialized: ${sid}`);
-                        // Store the promise before starting initialization
-                        sessionInitPromises.set(sid, initPromise);
-                        // Initialize connection pool for this session
-                        try {
-                            // #571: open on the session's own budget (a restored #189 preference may live on
-                            // another server), not on the default one.
-                            const budget = initialBudgetForSession(sid);
-                            await connectToActualForSession(sid, {
-                                serverUrl: budget.serverUrl,
-                                password: budget.password || '',
-                                syncId: budget.syncId,
-                                encryptionPassword: budget.encryptionPassword,
-                            });
-                            // 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.
-                            recordSessionOwner(sid, sessionOwner);
-                            transports.set(sid, transport);
-                            // #530: let the pool time this session even after its entry is recycled.
-                            // Pooling off (USE_CONNECTION_POOL=false) has no sweep, so nothing to register.
-                            if (isConnectionPoolEnabled())
-                                connectionPool.registerSession(sid);
-                            logger.info(`[SESSION] Actual connection initialized for session: ${sid}`);
-                            resolveInit?.();
-                        }
-                        catch (err) {
-                            logger.error(`[SESSION] Failed to initialize Actual for session ${sid}:`, err);
-                            // Don't add failed sessions to transports map - they won't be usable anyway
-                            // This prevents accumulation of dead sessions
-                            // #438: remember WHY. The transport is still deliberately not registered,
-                            // so the dead-session protection above is unchanged; without this the
-                            // cause is known here and discarded, and the client's next request gets
-                            // a bare "Session not found" that says nothing about a schema mismatch,
-                            // a bad password or an unreachable server.
-                            rememberInitFailure(sid, err, sessionOwner);
-                            rejectInit?.(err);
-                        }
-                        finally {
-                            // Clean up the promise after a short delay to allow pending requests to complete
-                            setTimeout(() => sessionInitPromises.delete(sid), 1000);
-                        }
-                    },
-                });
-                // connect transport then handle request (matching working example)
-                await server.connect(transport);
+                // #581: ONE try/finally from the reservation to the answer. The SDK answers 406 (Accept),
+                // 400 (bad JSON), an invalid JSON-RPC body and an already-initialized transport WITHOUT
+                // calling onsessioninitialized, and `server.connect` can throw; none of those reach the
+                // pool, and neither the idle sweep nor the #530 orphan sweep can see a slot that has no
+                // entry and no registration. This finally is the only thing that can give it back. The
+                // SDK awaits onsessioninitialized inside handleRequest, so here the session either
+                // registered (its reservation was handed over to the pool entry) or never will.
                 try {
-                    // Run in AsyncLocalStorage context so tools can access sessionId
-                    // and the adapter can enforce per-request budget ACL (#156).
-                    const allowedBudgetsInit = req.allowedBudgets;
-                    const requestId = resolveRequestId(req.get('x-correlation-id'));
-                    await requestContext.run({ sessionId: undefined, requestId, allowedBudgets: allowedBudgetsInit, principal: resolvePrincipal(req) }, async () => {
-                        await transport.handleRequest(req, res, req.body);
+                    logger.debug('[SESSION] Creating new MCP server + transport for initialize');
+                    const { server } = createServerInstance();
+                    // Create a promise to track session initialization completion
+                    let resolveInit;
+                    let rejectInit;
+                    const initPromise = new Promise((resolve, reject) => {
+                        resolveInit = resolve;
+                        rejectInit = reject;
                     });
+                    // Always-on safety net: if no concurrent code path is awaiting initPromise
+                    // when rejectInit fires (e.g. session init fails before any tools/call
+                    // arrives), the rejection would otherwise hit process.on('unhandledRejection')
+                    // and exit the server. The original error is already logged inside the
+                    // onsessioninitialized catch block below: we deliberately do NOT re-log here
+                    // to avoid duplicate noise and any risk of leaking credentials.
+                    initPromise.catch(() => { });
+                    // The session belongs to the principal that initialized it. Resolved here,
+                    // from this request, so the owner can never come from a later request.
+                    const sessionOwner = resolvePrincipal(req);
+                    const transport = new StreamableHTTPServerTransport({
+                        sessionIdGenerator: () => sid,
+                        enableJsonResponse: true,
+                        // #563: the SDK awaits this on a valid DELETE, BEFORE it answers 200, so the pool
+                        // slot is free by the time the client hears the session ended. It waits for the api
+                        // mutex (#392), so another session's call in flight finishes first. Without evict:
+                        // the DELETE route tears the session down itself after the 200.
+                        onsessionclosed: async (sid) => {
+                            if (isConnectionPoolEnabled())
+                                await connectionPool.shutdownConnection(sid);
+                        },
+                        onsessioninitialized: async (sid) => {
+                            logger.debug(`Session initialized: ${sid}`);
+                            // Store the promise before starting initialization
+                            sessionInitPromises.set(sid, initPromise);
+                            // Initialize connection pool for this session
+                            try {
+                                // #571: open on the session's own budget (a restored #189 preference may live on
+                                // another server), not on the default one.
+                                const budget = initialBudgetForSession(sid);
+                                await connectToActualForSession(sid, {
+                                    serverUrl: budget.serverUrl,
+                                    password: budget.password || '',
+                                    syncId: budget.syncId,
+                                    encryptionPassword: budget.encryptionPassword,
+                                });
+                                // 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.
+                                recordSessionOwner(sid, sessionOwner);
+                                transports.set(sid, transport);
+                                // #530: let the pool time this session even after its entry is recycled.
+                                // Pooling off (USE_CONNECTION_POOL=false) has no sweep, so nothing to register.
+                                if (isConnectionPoolEnabled())
+                                    connectionPool.registerSession(sid);
+                                logger.info(`[SESSION] Actual connection initialized for session: ${sid}`);
+                                resolveInit?.();
+                            }
+                            catch (err) {
+                                logger.error(`[SESSION] Failed to initialize Actual for session ${sid}:`, err);
+                                // Don't add failed sessions to transports map - they won't be usable anyway
+                                // This prevents accumulation of dead sessions
+                                // #438: remember WHY. The transport is still deliberately not registered,
+                                // so the dead-session protection above is unchanged; without this the
+                                // cause is known here and discarded, and the client's next request gets
+                                // a bare "Session not found" that says nothing about a schema mismatch,
+                                // a bad password or an unreachable server.
+                                rememberInitFailure(sid, err, sessionOwner);
+                                rejectInit?.(err);
+                            }
+                            finally {
+                                // Clean up the promise after a short delay to allow pending requests to complete
+                                setTimeout(() => sessionInitPromises.delete(sid), 1000);
+                            }
+                        },
+                    });
+                    // connect transport then handle request (matching working example)
+                    await server.connect(transport);
+                    try {
+                        // Run in AsyncLocalStorage context so tools can access sessionId
+                        // and the adapter can enforce per-request budget ACL (#156).
+                        const allowedBudgetsInit = req.allowedBudgets;
+                        const requestId = resolveRequestId(req.get('x-correlation-id'));
+                        await requestContext.run({ sessionId: undefined, requestId, allowedBudgets: allowedBudgetsInit, principal: resolvePrincipal(req) }, async () => {
+                            await transport.handleRequest(req, res, req.body);
+                        });
+                    }
+                    catch (err) {
+                        logger.error('Transport.handleRequest failed during initialize: %o', err);
+                        const e = err;
+                        if (e && typeof e.stack === 'string')
+                            logger.error(e.stack);
+                        throw err;
+                    }
+                    return;
                 }
-                catch (err) {
-                    logger.error('Transport.handleRequest failed during initialize: %o', err);
-                    const e = err;
-                    if (e && typeof e.stack === 'string')
-                        logger.error(e.stack);
-                    throw err;
+                finally {
+                    if (!transports.has(sid))
+                        releaseAdmission(sid);
                 }
-                return;
             }
             // sessionId present -> reuse. Transport presence is the liveness signal:
             // the pool's eviction listener (#167) removes the transport the moment a

package/dist/src/tools/session_close.js

@@ -9,7 +9,7 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_session_close',
-    description: 'Close one of your idle MCP sessions to free up connection slots. Useful when you get "Max concurrent sessions reached" errors. Only closes sessions you opened, other than the current one.',
+    description: 'Close one of your idle MCP sessions to free up connection slots. Useful when you get "Max concurrent sessions reached" or "Max sessions per principal reached" errors. Only closes sessions you opened, other than the current one.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.23.3",
+  "version": "0.24.0",
   "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/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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/new_tool_completeness.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/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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/adapter_set_budget_batch.test.js && node tests/unit/budget_updates_batch.test.js && node tests/unit/rules_create.test.js && node tests/unit/adapter_rule_reference_guard.test.js && node tests/unit/rules_create_batch.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/session_ownership.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpErrorHandler.test.js && node tests/unit/httpServer_error_handler_wiring.test.js && node tests/unit/httpServer_trust_proxy.test.js && node tests/unit/httpServer_batch_cap.test.js && node tests/unit/dotenv_stdout_quiet.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_acl_listing.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/multi_server_budget_selection.test.js && node tests/unit/static_tokens.test.js && node tests/unit/httpServer_static_tokens.test.js && node tests/unit/multi_server_budget_selection_stdio.test.js && node tests/unit/api_login_fetch.test.js && node tests/unit/multi_server_session_open_http.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/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/transactions_update_split_convert.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/transactions_update_batch.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/tool_content_logging.test.js && node tests/unit/adapter_error_logging.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/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/harness_cleanup.test.js && node tests/unit/harness_stdio_data_dir.test.js && node tests/unit/batch_uncategorized_cleanup.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/server_version_probe_outside_op_timeout.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 && node tests/unit/oidc_scope_list.test.js && node tests/unit/get_context.test.js && node tests/unit/contributor_docs.test.js && node tests/unit/toolsets.test.js && node tests/unit/toolsets_entrypoint.test.js && node tests/unit/tools_list_size_budget.test.js && node tests/unit/rules_update_schedules_schema.test.js && node tests/unit/schedules_update_amount_guard.test.js && node tests/unit/source_text_helper.test.js && node tests/unit/transport_onerror.test.js && node tests/unit/adapter_transaction_batch_abort.test.js && node tests/unit/transactions_merge_adapter.test.js && node tests/unit/schedules_dead_conditions.test.js && node tests/unit/session_ownership_express.test.js && node tests/unit/pool_orphan_sweep.test.js && node tests/unit/session_budget_state_cleanup.test.js && node tests/unit/http_session_delete.test.js && node tests/unit/budget_acl_parse.test.js && node tests/unit/server_instructions.test.js && node tests/unit/query_run_empty_hint.test.js",
+    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.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/new_tool_completeness.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/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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/adapter_set_budget_batch.test.js && node tests/unit/budget_updates_batch.test.js && node tests/unit/rules_create.test.js && node tests/unit/adapter_rule_reference_guard.test.js && node tests/unit/rules_create_batch.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.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/session_ownership.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/oidc_resource_identifier.test.js && node tests/unit/httpServer_oidc_resource_metadata.test.js && node tests/unit/oidc_error_cause.test.js && node tests/unit/httpServer_oidc_error_body.test.js && node tests/unit/oidc_token_source.test.js && node tests/unit/config_oidc_assertion_refines.test.js && node tests/unit/httpServer_oidc_assertion_mode.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpErrorHandler.test.js && node tests/unit/httpServer_error_handler_wiring.test.js && node tests/unit/httpServer_trust_proxy.test.js && node tests/unit/httpServer_batch_cap.test.js && node tests/unit/dotenv_stdout_quiet.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_acl_listing.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/multi_server_budget_selection.test.js && node tests/unit/static_tokens.test.js && node tests/unit/httpServer_static_tokens.test.js && node tests/unit/multi_server_budget_selection_stdio.test.js && node tests/unit/api_login_fetch.test.js && node tests/unit/multi_server_session_open_http.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/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/transactions_update_split_convert.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/transactions_update_batch.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/tool_content_logging.test.js && node tests/unit/adapter_error_logging.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/playwright_version_drift.test.js && node tests/unit/observability_smoke.test.js && node tests/unit/residue_pattern.test.js && node tests/unit/harness_cleanup.test.js && node tests/unit/harness_stdio_data_dir.test.js && node tests/unit/batch_uncategorized_cleanup.test.js && node tests/unit/rules_stage342_cleanup.test.js && node tests/unit/residue_unreadable.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/server_version_probe_outside_op_timeout.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 && node tests/unit/oidc_scope_list.test.js && node tests/unit/get_context.test.js && node tests/unit/contributor_docs.test.js && node tests/unit/toolsets.test.js && node tests/unit/toolsets_entrypoint.test.js && node tests/unit/tools_list_size_budget.test.js && node tests/unit/rules_update_schedules_schema.test.js && node tests/unit/schedules_update_amount_guard.test.js && node tests/unit/source_text_helper.test.js && node tests/unit/transport_onerror.test.js && node tests/unit/adapter_transaction_batch_abort.test.js && node tests/unit/transactions_merge_adapter.test.js && node tests/unit/schedules_dead_conditions.test.js && node tests/unit/session_ownership_express.test.js && node tests/unit/pool_orphan_sweep.test.js && node tests/unit/session_budget_state_cleanup.test.js && node tests/unit/http_session_delete.test.js && node tests/unit/budget_acl_parse.test.js && node tests/unit/server_instructions.test.js && node tests/unit/query_run_empty_hint.test.js && node tests/unit/session_admission_race.test.js && node tests/unit/pool_admission_reservation.test.js && node tests/unit/config_max_sessions_per_principal.test.js && node tests/unit/session_principal_cap.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",