actual-mcp-server 0.16.7 → 0.16.9

package/README.md

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

package/dist/src/lib/ActualConnectionPool.js

@@ -17,7 +17,7 @@ import path from 'path';
 import os from 'os';
 import fs from 'fs';
 import { isApiInitialized, setApiInitialized } from './apiState.js';
-import { withApiLock } from './apiLock.js';
+import { withApiLock, isApiLockHeld } from './apiLock.js';
 import { loadBudgetTracked } from './budgetLoader.js';
 import { withOpTimeout } from './opTimeout.js';
 const DEFAULT_DATA_DIR = path.resolve(os.homedir() || '.', '.actual');
@@ -417,7 +417,7 @@ class ActualConnectionPool {
         await withApiLock(() => this.shutdownConnectionLocked(sessionId, opts)).catch(async (err) => {
             logger.error(`[ConnectionPool] Could not acquire the api lock to shut down ${sessionId}; ` +
                 `tearing the entry down without it: ${err instanceof Error ? err.message : String(err)}`);
-            await this.shutdownConnectionLocked(sessionId, opts).catch(() => { });
+            await this.shutdownConnectionLocked(sessionId, { ...opts, expectUnlocked: true }).catch(() => { });
         });
     }
     /**
@@ -434,9 +434,24 @@ class ActualConnectionPool {
      *     - actual-adapter switchBudget slow path (its own withApiLock block has closed by then)
      *     - actualConnection.shutdownActualForSession (session close)
      *     - this.cleanupIdleConnections (the idle sweep)
-     *     - this.shutdownAll
+     *
+     *   Since #412, `shutdownAll` HOLDS the lock (one acquisition for the whole teardown instead of
+     *   one per session) and therefore calls this variant directly. Its fallback path runs unlocked
+     *   on purpose and passes `expectUnlocked` to say so.
      */
     async shutdownConnectionLocked(sessionId, opts = {}) {
+        // #411: assert the precondition rather than documenting it. The audit above says which callers
+        // hold the lock; this is what keeps that audit true as call sites are added.
+        //
+        // A WARNING, not a throw, and deliberately so: this is reached from cleanup paths, and a false
+        // positive that threw would turn a tidy-up into an outage, which is a worse trade than the
+        // hazard it guards. The nearest legitimate exception is the fallback in shutdownConnection
+        // itself, which runs unlocked ON PURPOSE when the acquisition failed, so it passes
+        // `expectUnlocked` to say so.
+        if (!opts.expectUnlocked && !isApiLockHeld()) {
+            logger.warn(`[ConnectionPool] shutdownConnectionLocked called for ${sessionId} without the api mutex. ` +
+                'Callers that do not hold it must use shutdownConnection, which acquires it.');
+        }
         const conn = this.connections.get(sessionId);
         // #392 review: the idle sweep decides who is expired BEFORE waiting for the mutex, and that
         // wait is no longer negligible. Re-checking here means a session that was touched while we
@@ -479,11 +494,16 @@ class ActualConnectionPool {
         }
     }
     /**
-     * Shutdown the shared connection
+     * Acquire the mutex and tear down the shared connection.
+     *
+     * #412 left this with NO caller in `src/`: `shutdownAll` now holds the lock itself and calls the
+     * Locked variant. It is kept, rather than deleted, because `USE_CONNECTION_POOL=false` uses the
+     * shared connection and a future teardown path for it must not hand-roll the acquisition. That
+     * is a deliberate decision rather than an oversight: knip does not analyse class members, so
+     * nothing else would have flagged it, and CLAUDE.md's own lesson from `adapter.deleteRule` is
+     * that a callerless wrapper left reachable is how the next caller finds the unguarded path.
      */
     async shutdownSharedConnection() {
-        // #392: same reasoning as shutdownConnection. Its only caller is shutdownAll, which does not
-        // hold the mutex.
         await withApiLock(() => this.shutdownSharedConnectionLocked()).catch(async (err) => {
             logger.error(`[ConnectionPool] Could not acquire the api lock to shut down the shared connection; ` +
                 `tearing it down without it: ${err instanceof Error ? err.message : String(err)}`);
@@ -491,7 +511,14 @@ class ActualConnectionPool {
         });
     }
     /** The body of shutdownSharedConnection, for callers that already hold the api mutex. */
-    async shutdownSharedConnectionLocked() {
+    async shutdownSharedConnectionLocked(opts = {}) {
+        // #411: same precondition check as shutdownConnectionLocked. Round 2 pointed out that keeping
+        // the callerless wrapper (M3) is only defensible if the guard that would catch a future
+        // hand-rolled caller exists on BOTH variants.
+        if (!opts.expectUnlocked && !isApiLockHeld()) {
+            logger.warn('[ConnectionPool] shutdownSharedConnectionLocked called without the api mutex. ' +
+                'Callers that do not hold it must use shutdownSharedConnection, which acquires it.');
+        }
         if (!this.sharedConnection?.initialized) {
             return;
         }
@@ -519,12 +546,38 @@ class ActualConnectionPool {
     async forceCloseStaleConnections() {
         try {
             logger.info('[ConnectionPool] Force closing any stale connections from previous instance');
-            // Try to shutdown the API if it was left initialized
-            const maybeApi = api;
-            if (typeof maybeApi.shutdown === 'function') {
-                await maybeApi.shutdown();
-                logger.info('[ConnectionPool] Successfully closed stale API connection');
-            }
+            // Try to shutdown the API if it was left initialized.
+            //
+            // #411 put this under the api mutex: it was the last api.shutdown() running without it.
+            // #416 then separated the two failures it was conflating. The body is a raw api.shutdown(),
+            // which can reject on its own, and reporting that as "could not take the api lock" sent the
+            // reader to the wrong subsystem while the retry repeated the call that had just failed.
+            //
+            // So: the guarded shutdown happens INSIDE the lock, matching every other shutdown path
+            // (which check isApiInitialized first, per #164, or a second call surfaces as
+            // "not initialized"). The catch below therefore genuinely means the ACQUISITION failed, and
+            // its fallback runs the same guarded shutdown once, unlocked and best effort.
+            const guardedShutdown = async () => {
+                if (!isApiInitialized())
+                    return;
+                const maybeApi = api;
+                if (typeof maybeApi.shutdown !== 'function')
+                    return;
+                try {
+                    await maybeApi.shutdown();
+                    logger.info('[ConnectionPool] Successfully closed stale API connection');
+                }
+                catch (shutdownErr) {
+                    logger.debug(`[ConnectionPool] Stale API connection would not close (ignoring): ${shutdownErr}`);
+                }
+                finally {
+                    setApiInitialized(false);
+                }
+            };
+            await withApiLock(guardedShutdown).catch(async (lockErr) => {
+                logger.debug(`[ConnectionPool] Could not take the api lock to close a stale connection: ${lockErr}`);
+                await guardedShutdown();
+            });
         }
         catch (err) {
             // Ignore errors - connection may not have been initialized
@@ -596,13 +649,37 @@ class ActualConnectionPool {
         // singleton ("not initialized" during graceful shutdown). Sessions are few
         // (15 max) and shutdown is rare, so sequential is fine. The first call does
         // the real shutdown; the isApiInitialized() guard makes the rest no-ops.
-        // Snapshot the keys: shutdownConnection deletes from `connections`.
-        for (const sessionId of [...this.connections.keys()]) {
-            await this.shutdownConnection(sessionId);
-        }
-        if (this.sharedConnection?.initialized) {
-            await this.shutdownSharedConnection();
-        }
+        // #412: ONE acquisition for the whole teardown, not one per session.
+        //
+        // Since #392 each shutdownConnection takes the api mutex, and since #393 acquiring it settles
+        // any abandoned budget load, bounded, and throws on timeout while KEEPING the registration. So
+        // with a stuck load, N sessions cost N times ACTUAL_OP_TIMEOUT_MS: 15 sessions at the 30s
+        // default is 450 seconds, and Docker sends SIGKILL after a 10 second grace period. The
+        // container died with a page of "could not acquire" lines and no clean api.shutdown().
+        //
+        // Acquiring once also makes the teardown ONE critical section rather than 16, which is more
+        // correct: nothing can interleave between the sessions being torn down.
+        //
+        // Swallowed for the same reason the per-session wrapper swallows: this is a cleanup path, and
+        // a stuck load must not stop the entries being removed. The fallback repeats the loop with the
+        // Locked variants, which is safe because nothing can be holding the lock while a registration
+        // is stuck (every acquisition throws in that state).
+        const teardown = async (expectUnlocked = false) => {
+            // Snapshot the keys: shutdownConnectionLocked deletes from `connections`.
+            for (const sessionId of [...this.connections.keys()]) {
+                await this.shutdownConnectionLocked(sessionId, { expectUnlocked });
+            }
+            if (this.sharedConnection?.initialized) {
+                await this.shutdownSharedConnectionLocked({ expectUnlocked });
+            }
+        };
+        await withApiLock(() => teardown()).catch(async (err) => {
+            logger.error(`[ConnectionPool] Could not acquire the api lock for shutdownAll; tearing down without it: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+            // `expectUnlocked`: this path runs without the mutex ON PURPOSE, so #411's warning would
+            // otherwise fire once per session at the exact moment the code chose not to take it.
+            await teardown(true).catch(() => { });
+        });
         logger.info('[ConnectionPool] All connections shut down');
     }
     /**

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

@@ -21,7 +21,7 @@ import { parseBudgetRegistry } from './budget-registry.js';
 import { getPreferredBudgetSyncId, setPreferredBudgetSyncId, pickAllowedPreferredBudget } from './budget-preference-store.js';
 import { requestContext } from './requestContext.js';
 import { connectionPool } from './ActualConnectionPool.js';
-import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, awaitAbandonedBudgetLoad } from './apiState.js';
+import { isApiInitialized, setApiInitialized, getLoadedBudgetSyncId, awaitAbandonedBudgetLoad, hasPendingBudgetLoad } from './apiState.js';
 import { withApiLock } from './apiLock.js';
 import { loadBudgetTracked, importBudgetTracked } from './budgetLoader.js';
 /**
@@ -200,6 +200,44 @@ let connectionReuseCount = 0;
 // update it without a circular import. The pool's hasConnection() returns
 // true based on its own per-session record; this flag is the second guard
 // — the singleton's actual state. Both must agree before reuse is safe.
+/**
+ * #391: the budget this acquisition will operate on, as an AFFINITY HINT for the api lock.
+ *
+ * Never an assertion, and never used for a correctness decision: the loaded-budget PRECONDITION
+ * (`ensureLoadedBudgetMatchesSession`) is what makes an operation safe, and it runs inside the
+ * lock regardless of how the lock chose to order us. This only lets the lock group a run of
+ * same-budget work so the process pays one re-selection instead of one per call.
+ *
+ * Resolved from the same source the precondition uses, so a hint can never name a budget the
+ * operation would not have selected anyway.
+ */
+function _affinityBudget() {
+    try {
+        return getActiveBudgetConfig().syncId;
+    }
+    catch {
+        return undefined; // no registry, no hint: FIFO is always correct
+    }
+}
+/**
+ * #417: the budget every operation in a batch resolves to, or undefined when they differ.
+ *
+ * Exported so the unanimity rule can be tested without driving the lock. NOTE the side effect,
+ * which is bounded and idempotent but worth knowing: `getActiveBudgetConfig()` memoises a restored
+ * preference into `sessionBudgetState` and may read the preference file once per un-memoised
+ * session. The operation would do exactly that anyway a moment later, so this only moves it.
+ */
+export function resolveBatchBudget(entries) {
+    const budgets = new Set(entries.map((e) => {
+        try {
+            return requestContext.run(e.requestStore ?? {}, () => getActiveBudgetConfig().syncId);
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    return budgets.size === 1 ? [...budgets][0] : undefined;
+}
 function _resolveSessionId() {
     return requestContext.getStore()?.sessionId;
 }
@@ -331,6 +369,8 @@ export async function withActualApi(rawOperation) {
     const sessionId = _resolveSessionId();
     if (_hasPooledConnection(sessionId)) {
         // Pooled mode: skip init+shutdown.
+        // #391: name the budget this operation will run against, so the lock can group a run of
+        // same-budget work and pay ONE re-selection instead of one per call.
         return withApiLock(async () => {
             try {
                 connectionReuseCount++;
@@ -355,7 +395,7 @@ export async function withActualApi(rawOperation) {
                 }
                 throw err;
             }
-        });
+        }, { budget: _affinityBudget() });
     }
     if (sessionId) {
         logger.warn(`[ADAPTER] Pool miss for session ${sessionId}; falling back to per-op init`);
@@ -369,7 +409,7 @@ export async function withActualApi(rawOperation) {
         finally {
             await shutdownActualApi();
         }
-    });
+    }, { budget: _affinityBudget() });
 }
 /**
  * Variant of `withActualApi` for write operations. Identical to `withActualApi`
@@ -431,7 +471,7 @@ export async function withActualApiWrite(operation) {
                 }
                 throw err;
             }
-        });
+        }, { budget: _affinityBudget() });
     }
     if (sessionId) {
         logger.warn(`[ADAPTER] Pool miss for session ${sessionId}; falling back to per-op init (write)`);
@@ -444,7 +484,7 @@ export async function withActualApiWrite(operation) {
         finally {
             await shutdownActualApi();
         }
-    });
+    }, { budget: _affinityBudget() });
 }
 /**
  * Test-only: reset the connection-reuse counter. NOT exported via the package
@@ -623,6 +663,26 @@ import { BANK_SYNC_SETTLE_MS, WRITE_SESSION_DELAY_MS } from './constants.js';
 // and setMaxConcurrency is re-exported.
 import { withConcurrency, setMaxConcurrency, getConcurrencySnapshot } from './actual-adapter/concurrency.js';
 export { setMaxConcurrency };
+/**
+ * #389: how long an entry may sit DISPATCHED BUT NOT STARTED before it is rejected.
+ *
+ * Armed only when ACTUAL_OP_TIMEOUT_MS is 0, which is the one configuration where a stalled
+ * operation strands the rest of its batch in silence. Deliberately not derived from the op
+ * timeout: that is the knob the operator turned off. Fifteen minutes clears the longest
+ * legitimate single operation (a budget import at ACTUAL_IMPORT_TIMEOUT_MS, default ten minutes)
+ * with room to spare, so a healthy slow batch is never falsely rejected, while an operation that
+ * genuinely never runs gets an error instead of silence.
+ */
+let STRANDED_BATCH_LIMIT_MS = 900000;
+/**
+ * Test-only: shrink the stranded bound so the arming behaviour is testable in reasonable time.
+ *
+ * Without a seam the riskiest timer in this file could only be exercised by waiting fifteen
+ * minutes, which means in practice it would never be exercised at all.
+ */
+export function _setStrandedBatchLimitForTests(ms) {
+    STRANDED_BATCH_LIMIT_MS = ms;
+}
 let writeQueue = [];
 let isProcessingWrites = false;
 let writeSessionTimeout = null;
@@ -767,6 +827,68 @@ async function processWriteQueue() {
             entry.residencyTimer = undefined;
         }
     }
+    // #389: "dispatched" stopped meaning "started" when #378 made the batch SEQUENTIAL.
+    //
+    // Before that, a hanging operation left its siblings running. Now operations k+1..N never
+    // start, and because their residency timers were cleared just above (correctly, for the
+    // concurrent model) nothing rejects them: every one of those callers waits forever and NO
+    // ERROR IS EMITTED ANYWHERE. That is #278's signature exactly, and #278 took a "flaky" E2E
+    // test to surface because the only tell was the absence of an error.
+    //
+    // It needs ACTUAL_OP_TIMEOUT_MS=0 to be reachable, which is a documented escape hatch for
+    // debugging against a slow upstream: the one situation where a stall is most likely and an
+    // operator is least likely to suspect the write queue.
+    //
+    // So each entry keeps a bound on the part that is still a QUEUE WAIT. It is cleared the
+    // moment the operation actually starts, so it can never fire on an in-flight op, and it does
+    // NOT bound the operation itself, which is what the escape hatch exists to disable.
+    //
+    // The bound cannot be ACTUAL_OP_TIMEOUT_MS, because that is exactly what the operator disabled
+    // and what makes this reachable. It is a separate, generous constant armed ONLY in that
+    // configuration: setting it to 0 asks for unbounded OPERATIONS, not for unbounded QUEUEING, and
+    // those are different promises. It must also exceed the longest LEGITIMATE batch, or it would
+    // reject work that was about to run, which the ticket names as the way to get this wrong. The
+    // longest legitimate single operation is a budget import at ACTUAL_IMPORT_TIMEOUT_MS (default
+    // 600000), so 15 minutes clears it with room and is still finite.
+    //
+    // RE-ARMED on each start, not pre-armed once (review round 1). Arming all N timers at dispatch
+    // with the same delay makes entry k's allowance "900s minus everything before it", so a batch of
+    // healthy but slow operations rejects its own tail while nothing has stalled. Four budget
+    // re-selections at four minutes each on the slow link that made the operator disable the timeout
+    // in the first place is enough. Re-arming makes the bound mean what it should: no SINGLE
+    // predecessor has been running for 15 minutes.
+    const started = new Set();
+    const strandedLimitMs = config.ACTUAL_OP_TIMEOUT_MS === 0 ? STRANDED_BATCH_LIMIT_MS : 0;
+    const armStrandedBound = (entries) => {
+        if (strandedLimitMs <= 0)
+            return;
+        for (const entry of entries) {
+            if (started.has(entry) || entry.settledEarly)
+                continue;
+            if (entry.residencyTimer)
+                clearTimeout(entry.residencyTimer);
+            entry.residencyTimer = setTimeout(() => {
+                if (started.has(entry))
+                    return;
+                logger.error(`[WRITE QUEUE] Operation never started: the operation ahead of it in this batch has not ` +
+                    `returned within ${strandedLimitMs}ms. Rejecting rather than stranding the caller (#389).`);
+                entry.reject(new Error('This write never started: an earlier operation in the same batch stalled. ' +
+                    'The batch runs sequentially (#378), so it was queued behind that operation. Retry it.'));
+                entry.settledEarly = true;
+            }, strandedLimitMs);
+            if (typeof entry.residencyTimer.unref === 'function')
+                entry.residencyTimer.unref();
+        }
+    };
+    const clearStrandedBounds = () => {
+        for (const entry of batch) {
+            if (entry.residencyTimer) {
+                clearTimeout(entry.residencyTimer);
+                entry.residencyTimer = undefined;
+            }
+        }
+    };
+    armStrandedBound(batch);
     writeQueueBatchCount++;
     // Pool-cooperation decision (#158): use the first queued op's captured
     // sessionId as the batch's sessionId. In practice all ops batched together
@@ -786,6 +908,18 @@ async function processWriteQueue() {
         // assignment to clear and therefore no path, fatal or otherwise, that can leak it: when
         // the callback returns the store is gone. This replaced a module-level variable plus a
         // `finally` that nulled it, which worked but rested on that finally being reached.
+        // #417: hint the batch's budget, but ONLY when every operation in it resolves to the same one.
+        //
+        // #391 made an unhinted waiter a BARRIER affinity may not cross, which is what stops a drain
+        // being overtaken by reads queued after it. The side effect is that an unhinted drain also
+        // blocks affinity for everything behind it: measured at 5 re-selections for an alternating load
+        // with a drain in every fourth slot, against 2 with no drains.
+        //
+        // Deliberately NOT the `batch[0]` heuristic, which CLAUDE.md already names as a hazard for the
+        // connection choice: one entry's budget says nothing about the rest, and a wrong hint would
+        // reorder a mixed batch. Unanimity or nothing. The hint is only ever an ordering preference;
+        // `ensureLoadedBudgetMatchesSession` inside the lock still decides what is safe.
+        const batchBudget = resolveBatchBudget(batch);
         await drainListingStore.run(new Map(), async () => {
             await withApiLock(async () => {
                 try {
@@ -830,7 +964,43 @@ async function processWriteQueue() {
                     //
                     // Each op keeps its own withOpTimeout (#270) and still settles individually, so one
                     // stalled or rejected operation cannot hold the api mutex or fail its siblings.
-                    for (const { operation, resolve, reject, preservesListings, requestStore, timeoutMs } of batch) {
+                    let stuckLoadError = null;
+                    // Counted so the event is logged ONCE with a total. Without this the fail-fast path sits
+                    // outside the per-operation try, so it never reaches the '[WRITE QUEUE] Operation failed'
+                    // line and N operations fail with no log entry anywhere. Given this whole ticket family
+                    // exists because absence-of-error is the failure signature, that would be the wrong silence
+                    // to introduce while removing another.
+                    let failedFast = 0;
+                    for (const entry of batch) {
+                        const { operation, resolve, reject, preservesListings, requestStore, timeoutMs } = entry;
+                        // #389: this operation is STARTING, so its queue-wait bound no longer applies. Cleared
+                        // before any await, so the timer can never fire on an in-flight op.
+                        started.add(entry);
+                        if (entry.residencyTimer) {
+                            clearTimeout(entry.residencyTimer);
+                            entry.residencyTimer = undefined;
+                        }
+                        // Restart the bound for everything still waiting, so it measures THIS operation's
+                        // runtime rather than the batch's cumulative one.
+                        armStrandedBound(batch);
+                        if (entry.settledEarly)
+                            continue; // its residency bound already rejected it
+                        // #414: fail FAST while a budget load is genuinely stuck, rather than paying the
+                        // abandoned-load bound once per remaining operation. A stuck load makes every one of
+                        // them fail identically, so N operations would hold the process-global mutex for N
+                        // times ACTUAL_OP_TIMEOUT_MS. The condition is RE-CHECKED rather than latched, because
+                        // a load can land just after a bound expires and the whole point of keeping the
+                        // registration is that a late landing is still waited for.
+                        if (stuckLoadError !== null && hasPendingBudgetLoad()) {
+                            // A DISTINCT error, not the one the earlier operation's wait produced (review round 1).
+                            // Handing this operation that error claims it waited and timed out, which it never did,
+                            // and its message matches TRANSIENT_ERROR_PATTERNS while describing something that is
+                            // not this operation's failure. `cause` keeps the real origin attached.
+                            failedFast++;
+                            reject(new Error('This write was queued behind an operation whose budget load is still outstanding, ' +
+                                'so it was failed immediately rather than waiting for the same bound. Retry it.', { cause: stuckLoadError }));
+                            continue;
+                        }
                         try {
                             // #390 round 2: run each op in the context it was ENQUEUED in.
                             //
@@ -866,7 +1036,15 @@ async function processWriteQueue() {
                                 // A rejection here is caught by this loop's own per-op catch, so a stuck load fails
                                 // ONE operation rather than the whole batch, which is the behaviour #393 round 4
                                 // established for the drain.
-                                await awaitAbandonedBudgetLoad(withOpTimeout);
+                                try {
+                                    await awaitAbandonedBudgetLoad(withOpTimeout);
+                                }
+                                catch (waitErr) {
+                                    // #414: remember it, so the rest of the batch fails fast instead of each paying
+                                    // the same bound. Still rethrown, so THIS operation fails exactly as before.
+                                    stuckLoadError = waitErr instanceof Error ? waitErr : new Error(String(waitErr));
+                                    throw waitErr;
+                                }
                                 await ensureLoadedBudgetMatchesSession();
                                 // #407: an operation may carry its OWN bound. Only a budget import does today, and
                                 // it needs one: the import is legitimately long, and bounding it at the general
@@ -931,6 +1109,10 @@ async function processWriteQueue() {
                                 connectionPool.touch(sid);
                         }
                     }
+                    if (failedFast > 0) {
+                        logger.error(`[WRITE QUEUE] ${failedFast} operation(s) failed fast because a budget load is still ` +
+                            `outstanding. They were never attempted; the stalled load is the cause (#414).`);
+                    }
                     // 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`);
@@ -994,10 +1176,19 @@ async function processWriteQueue() {
                         await shutdownActualApi();
                     }
                 }
-            });
+            }, { budget: batchBudget });
         });
+        clearStrandedBounds();
     }
     catch (lockError) {
+        // #389 review (I2): clear the stranded bounds here too. When the ACQUISITION rejects (which it
+        // can, since #393, on an abandoned-load timeout) the loop is never entered, so without this all
+        // N timers stay armed and each one logs "the operation ahead of it in this batch has not
+        // returned" fifteen minutes later, for a batch that no longer exists and whose failure was a
+        // lock acquisition rather than a stalled sibling. The rejects are harmless no-ops on settled
+        // promises; the false signal is the problem, and it is the same wrong-subsystem misdirection
+        // #416 exists to remove.
+        clearStrandedBounds();
         // #393 review: THE LOCK ITSELF CAN NOW REJECT, before `fn()` ever runs.
         //
         // The batch-rejection handler above lives INSIDE the lock callback, which was sound while
@@ -1398,7 +1589,7 @@ export async function setBudgetAmount(month, categoryId, amount) {
 export async function transferBudgetAmount(month, fromCategoryId, toCategoryId, amount) {
     observability.incrementToolCall('actual.budgets.transfer').catch(() => { });
     return queueWriteOperation(async () => {
-        // Inside processWriteQueue we already hold _apiSessionLock and the api is
+        // Inside processWriteQueue we already hold the api mutex in apiLock.ts and the api is
         // initialised. Call raw functions only: adapter wrappers would re-enter
         // queueWriteOperation / withActualApi and defeat the single-cycle goal.
         // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/dist/src/lib/apiLock.js

@@ -1,4 +1,4 @@
-import { awaitAbandonedBudgetLoad } from './apiState.js';
+import { awaitAbandonedBudgetLoad, getLoadedBudgetSyncId } from './apiState.js';
 import { withOpTimeout } from './opTimeout.js';
 import { createModuleLogger } from './loggerFactory.js';
 const logger = createModuleLogger('API LOCK');
@@ -17,44 +17,206 @@ const logger = createModuleLogger('API LOCK');
  * this first: reads via `withActualApi`, writes via `processWriteQueue`, and since #390 the
  * pool's session-open init and budget download.
  *
- * IT IS NOT REENTRANT, and that is load bearing. It is a strict FIFO chained-promise mutex, so
- * an inner acquisition waits on the outer call's own release promise, which cannot fire until
- * the outer callback resolves. The observable symptom is a stall ended by #270's operation
- * timeout, NOT a hang, and it should be read as a probable nesting bug rather than a slow
- * upstream. Before adding an acquisition, check that no caller above you already holds it.
+ * IT IS NOT REENTRANT, and that is load bearing. An inner acquisition queues behind the outer
+ * call's own release, which cannot happen until the outer callback resolves. The observable
+ * symptom is a stall ended by #270's operation timeout, NOT a hang, and it should be read as a
+ * probable nesting bug rather than a slow upstream. Before adding an acquisition, check that no
+ * caller above you already holds it.
  */
-let _apiSessionLock = Promise.resolve();
 /**
- * #393: settling an abandoned budget load is part of ACQUIRING the lock, not something call
- * sites remember to do.
- *
- * Every previous round of #390 guarded per call site and every round missed one. Round 1 missed
- * the legacy path (a silent cross-tenant read). Round 2 put the wait in the two adapter entry
- * points and missed the three `loadBudgetTracked` sites that reach the api without passing
- * through them, so a session opening during the window untracked the abandoned load and the
- * leak stayed reachable. CLAUDE.md already names this hazard class for `withOpTimeout`: the
- * protection is per-call-site rather than structural, so a new acquisition site added without
- * it fails silently.
- *
- * Putting it here makes the set of call sites stop mattering. Nothing reaches
- * `@actual-app/api` without this lock, so nothing reaches it without the wait.
- *
- * It is bounded and fails closed (see `awaitAbandonedBudgetLoad`): an unbounded wait here would
- * wedge every session on one stuck download, which is what made the round-2 version worse than
- * the bug it fixed.
+ * #391: BUDGET AFFINITY, replacing strict FIFO.
+ *
+ * The problem this solves, measured rather than asserted: with two sessions on different
+ * budgets, 20 alternating tool calls produced 19 full budget downloads, 19 syncs of the outgoing
+ * budget and 19 post-condition probes, all serialised through this mutex. That is #390's
+ * isolation working correctly and costing a re-selection per operation. On a large budget the
+ * download can exceed ACTUAL_OP_TIMEOUT_MS, at which point neither user completes anything while
+ * the other is active, and any two authenticated accounts on different budgets can hold the
+ * process there deliberately.
+ *
+ * The fix is to serialise by BUDGET rather than by operation: when the lock is released, prefer a
+ * waiter whose budget is already loaded. A run of same-budget operations then pays ONE
+ * re-selection instead of one each, so the cost tracks ALTERNATIONS rather than call count.
+ *
+ * THE MUTEX SHAPE CHANGED to make this possible. It was a chained-promise FIFO, which has no
+ * waiter list to reorder. It is now an explicit queue with a held flag. Three properties are
+ * load bearing, and each has a mutation-proven test in tests/unit/api_lock_affinity.test.js:
+ *
+ *   1. BOUNDED STARVATION. Preferring the loaded budget indefinitely starves the other one, which
+ *      is a failure mode strict FIFO did not have. At most MAX_AFFINITY_SKIPS consecutive grants
+ *      may skip the head of the queue; the next grant then goes to the head regardless of budget.
+ *   2. FIFO WITHIN A BUDGET. Among waiters on the same budget the oldest is always chosen.
+ *      Several correctness arguments elsewhere rest on same-session ordering.
+ *   3. THE ABANDONED-LOAD WAIT STILL HAPPENS on every acquisition (#393), and per operation inside
+ *      a drain (#406). Reordering acquisitions must not let one skip it.
+ */
+/**
+ * How many consecutive grants may skip the head of the queue.
+ *
+ * The trade is thrash against latency, and neither end is free. Zero is strict FIFO, which is
+ * what #391 exists to stop. Unbounded starves the other budget entirely.
+ *
+ * Eight, because a switch costs three upstream operations (sync the outgoing budget, download the
+ * incoming one, probe it), so amortising one switch over eight operations puts the per-operation
+ * cost well below the un-batched case, while the waiter at the head of the queue can be delayed by
+ * at most eight operations rather than indefinitely. It is deliberately a small number: the goal
+ * is to remove the per-CALL switch, not to let one tenant monopolise the process.
+ *
+ * The bound is in OPERATIONS, not wall clock, and the difference matters in the scenario this
+ * ticket cites. Eight operations that each run to ACTUAL_OP_TIMEOUT_MS is 240 seconds at the
+ * default, which is past most clients' own request timeouts. That is the accepted trade: bounding
+ * by time instead would need the lock to know how long an operation has left, which it cannot.
  */
-export function withApiLock(fn) {
-    let release;
-    const prevLock = _apiSessionLock;
-    _apiSessionLock = new Promise((resolve) => {
-        release = resolve;
+const MAX_AFFINITY_SKIPS = 8;
+let held = false;
+const waiters = [];
+let consecutiveSkips = 0;
+/**
+ * The release path's diagnostic, behind a seam.
+ *
+ * Not indirection for its own sake: this exists so a test can install a THROWING hook and prove
+ * the lock is still released. Round 2 caught the previous test asserting source-text ordering
+ * instead, which stayed green when the exact regression was reintroduced a few lines away.
+ */
+let onSkipGrant = (info) => {
+    logger.debug('granting out of order to keep the loaded budget', info);
+};
+export function _setApiLockLogHookForTests(hook) {
+    onSkipGrant = hook ?? ((info) => {
+        logger.debug('granting out of order to keep the loaded budget', info);
     });
-    return prevLock
-        .then(async () => {
-        if (await awaitAbandonedBudgetLoad(withOpTimeout)) {
-            logger.warn('[API LOCK] waited for an abandoned budget load before running this operation');
+}
+/** Test hook: the queue is module state, so a suite must be able to observe and reset it. */
+export function _getApiLockStateForTests() {
+    return { held, waiting: waiters.length, consecutiveSkips };
+}
+/**
+ * #411: is the api mutex currently held?
+ *
+ * Exists so the `...Locked` variants can ASSERT their precondition instead of documenting it. The
+ * audit of which callers hold the lock lives in a doc comment today, and this repo has paid four
+ * times (#371, #376, #390, #393) for the difference between a convention and a check.
+ *
+ * Deliberately coarse: it reports that SOMEONE holds the lock, not that YOU do, because a
+ * chained-promise mutex has no owner identity. That is still enough to catch the mistake that
+ * matters, which is calling a Locked variant from a path that holds nothing at all.
+ */
+export function isApiLockHeld() {
+    return held;
+}
+export function _resetApiLockForTests() {
+    // REJECT queued waiters rather than granting or dropping them.
+    //
+    // Dropping leaves promises that never settle (the hazard `_clearPendingBudgetLoadsForTests`
+    // documents in apiState.ts). Granting is worse and was the first attempt: a granted waiter RUNS
+    // ITS BODY and then calls grantNext(), releasing a lock it was never exclusively handed. Probed
+    // at four concurrent holders. Rejecting settles the promise without running anything and without
+    // a spurious release, which is what "reset" should mean.
+    const pending = waiters.splice(0, waiters.length);
+    held = false;
+    consecutiveSkips = 0;
+    for (const w of pending)
+        w.abort(new Error('api lock reset by a test hook'));
+}
+function acquire(budget) {
+    if (!held) {
+        held = true;
+        return Promise.resolve();
+    }
+    return new Promise((grant, abort) => {
+        waiters.push({ budget, grant, abort });
+    });
+}
+/**
+ * Hand the lock to exactly one waiter, or release it if none are queued.
+ *
+ * Ownership TRANSFERS: `held` stays true when a waiter is granted, so no third party can slip in
+ * between the release and the grant. That is what makes this a mutex rather than a suggestion.
+ */
+function grantNext() {
+    if (waiters.length === 0) {
+        held = false;
+        consecutiveSkips = 0;
+        return;
+    }
+    let index = 0; // strict FIFO by default, which is also the anti-starvation fallback
+    if (consecutiveSkips < MAX_AFFINITY_SKIPS) {
+        const loaded = getLoadedBudgetSyncId();
+        if (loaded !== null) {
+            // The OLDEST waiter on the loaded budget, so ordering within a budget is preserved.
+            const match = waiters.findIndex((w) => w.budget === loaded);
+            // An UNHINTED waiter is a BARRIER that affinity may not cross.
+            //
+            // Review caught this, and it was the worst thing in the change. An unhinted waiter can never
+            // equal `loaded`, so without this it was freely skipped, and the three unhinted acquisitions
+            // are the ones least able to afford it: the pool's session open, `shutdownAll`, and a write
+            // drain whose batch spans budgets. (#417 later let a UNANIMOUS drain hint its own budget, so
+            // that case is no longer a barrier. A mixed batch still is, and must stay so: one entry's
+            // budget says nothing about the rest.) Reproduced on a SINGLE-budget setup, where affinity can never save a
+            // re-selection because only one budget is ever loaded: a drain enqueued first ran ninth,
+            // behind eight reads. So the majority deployment got the reordering with none of the benefit,
+            // a write could be overtaken by reads issued after it (impossible under the old FIFO, and
+            // visible to a client issuing parallel tool calls), and #412's teardown could be delayed by
+            // eight operations at exactly the moment it is racing SIGTERM.
+            //
+            // Skipping a same-budget waiter that is merely LATER in the queue is safe; skipping one that
+            // cannot express a preference is not, because "no hint" does not mean "no ordering
+            // requirement".
+            const barrier = waiters.findIndex((w) => w.budget === undefined);
+            if (match > 0 && (barrier === -1 || match < barrier))
+                index = match;
         }
-        return await fn();
-    })
-        .finally(() => release());
+    }
+    if (index > 0) {
+        consecutiveSkips++;
+    }
+    else {
+        // The head ran, so nobody is being starved right now.
+        consecutiveSkips = 0;
+    }
+    // GRANT FIRST, log after, and never let the log break the release.
+    //
+    // This runs in a `finally`, so anything that throws here leaves `held` true with a queue nobody
+    // will ever be handed. No timeout can rescue that: the waiters never enter the lock body, so
+    // `withOpTimeout` never applies to them. It is #278's signature, and CLAUDE.md's own line is
+    // that a hang has no timeout large enough. The previous chained-promise mutex released with a
+    // bare `resolve()`, which could not throw; this queue can, so the ordering is deliberate.
+    const skipped = index;
+    const [chosen] = waiters.splice(index, 1);
+    chosen.grant();
+    if (skipped > 0) {
+        try {
+            onSkipGrant({ skipped, consecutiveSkips, waiting: waiters.length });
+        }
+        catch { /* the release path must never throw */ }
+    }
+}
+/**
+ * Run `fn` holding the api mutex.
+ *
+ * `budget` is an optional AFFINITY HINT, not an assertion: pass the syncId this acquisition will
+ * operate on when the caller can name one unambiguously. Callers that cannot (a write drain whose
+ * batch spans budgets) pass nothing and are treated as ordinary FIFO waiters, which is always
+ * correct and merely forgoes the optimisation.
+ */
+export function withApiLock(fn, opts) {
+    return acquire(opts?.budget).then(async () => {
+        try {
+            // #393: settling an abandoned budget load is part of ACQUIRING the lock, not something call
+            // sites remember to do. Every previous round of #390 guarded per call site and every round
+            // missed one. Putting it here makes the set of call sites stop mattering: nothing reaches
+            // @actual-app/api without this lock, so nothing reaches it without the wait.
+            //
+            // It is bounded and fails closed (see `awaitAbandonedBudgetLoad`): an unbounded wait here
+            // would wedge every session on one stuck download, which is what made #390's round-2
+            // version worse than the bug it fixed.
+            if (await awaitAbandonedBudgetLoad(withOpTimeout)) {
+                logger.warn('waited for an abandoned budget load before running this operation');
+            }
+            return await fn();
+        }
+        finally {
+            grantNext();
+        }
+    });
 }

package/dist/src/lib/apiState.js

@@ -127,6 +127,20 @@ export async function awaitAbandonedBudgetLoad(bound) {
     await bound(() => outstanding, 'abandoned budget load');
     return true;
 }
+/**
+ * Is a budget load currently outstanding?
+ *
+ * Production predicate (#414). The write drain uses it to FAIL FAST rather than pay the abandoned
+ * load bound once per remaining operation: a stuck load makes every one of them fail identically,
+ * so N operations cost N times ACTUAL_OP_TIMEOUT_MS holding the process-global mutex.
+ *
+ * Deliberately re-checked per operation rather than latched: a load can land just after a bound
+ * expires, and the whole point of keeping the registration is that a late landing is still waited
+ * for. Fail fast only while the condition still holds.
+ */
+export function hasPendingBudgetLoad() {
+    return _pendingBudgetLoads.size > 0;
+}
 /** Test hook: is a load currently outstanding? */
 export function _hasPendingBudgetLoadForTests() {
     return _pendingBudgetLoads.size > 0;

package/dist/src/lib/budgetLoader.js

@@ -328,10 +328,49 @@ async function trackBudgetMutation(start, describeLoaded, label, verify, onRecor
     // "first" untrue.
     setLoadedBudgetSyncId(null);
     const raw = start();
+    // #403: was this load ABANDONED by the caller's bound?
+    //
+    // The post-condition probe lives inside this chain so an abandoned load is verified when it
+    // lands rather than recording a success nobody checked (#396). The cost, raised in review, is
+    // that a LATE landing runs that probe with no lock held, against the single SQLite connection,
+    // while another session may be mid-operation inside the lock.
+    //
+    // The resolution is not to probe on that path at all. A landing whose caller has already given
+    // up leaves the record INDETERMINATE, which forces the next operation to re-select. That is the
+    // safe direction #390 established, it costs one extra re-selection after an event that is rare
+    // by construction (a load that outran its bound), and it removes the unsynchronised read
+    // entirely rather than arguing about whether it is observable.
+    let abandoned = false;
     const tracked = raw
         .then(async (result) => {
+        if (abandoned) {
+            log.warn('an abandoned budget load landed after its caller gave up; leaving the record indeterminate', {
+                label,
+            });
+            // The load itself SUCCEEDED upstream, so any cached failure reason for this budget is
+            // stale even though we are not recording the syncId. Clearing here keeps the hook's stated
+            // contract true on the abandoned path as well (see the note on `onRecorded` below).
+            try {
+                onRecorded?.();
+            }
+            catch { /* a hook cannot change the outcome */ }
+            return result;
+        }
         if (verify)
             await verify();
+        // #403 review: re-check. `abandoned` can flip DURING `verify()`, when the load resolves just
+        // before its bound expires. Without this the probe runs and the record is written on a load
+        // whose caller has gone, which contradicts the contract stated above. The value written
+        // would be true rather than false, so this is about honesty of the invariant rather than
+        // safety, but a contract the code only honours on the common path is not a contract.
+        if (abandoned) {
+            log.warn('a budget load was abandoned while its post-condition ran; leaving the record indeterminate', { label });
+            try {
+                onRecorded?.();
+            }
+            catch { /* a hook cannot change the outcome */ }
+            return result;
+        }
         setLoadedBudgetSyncId(describeLoaded(result));
         // #392 review (finding 5): this runs INSIDE the chain, not after the awaited call. On the
         // abandoned-then-eventually-successful path the caller has already thrown, so a hook placed
@@ -357,9 +396,18 @@ async function trackBudgetMutation(start, describeLoaded, label, verify, onRecor
         throw err;
     });
     registerBudgetLoad(tracked);
-    // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
-    // waits for it inside the lock rather than racing it.
-    return await withOpTimeout(() => tracked, label, timeoutMs);
+    try {
+        // On timeout the tracked promise is still running. Leave it REGISTERED: the next operation
+        // waits for it inside the lock rather than racing it.
+        return await withOpTimeout(() => tracked, label, timeoutMs);
+    }
+    catch (err) {
+        // #403: from here the caller has given up, so anything still in flight must not touch the api
+        // with no lock held. The chain checks this before probing. Set on ANY rejection, which is
+        // harmless when the chain itself already failed: it has settled, so nothing reads the flag.
+        abandoned = true;
+        throw err;
+    }
 }
 /**
  * #394: the same discipline for an IMPORT.

package/package.json

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