actual-mcp-server 0.16.7 → 0.16.8

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.8 | **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,10 +546,20 @@ 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
+            // Try to shutdown the API if it was left initialized.
+            //
+            // #411: this was the LAST api.shutdown() in the codebase running without the api mutex.
+            // #392 established that there should be none. The exposure was small (this runs at pool
+            // construction, before anything else is live) but "small" is not "absent", and an exception
+            // that exists only because nobody got round to it is indistinguishable from one that exists
+            // for a reason. Swallowed like every other cleanup acquisition: a stuck load must not stop
+            // construction.
             const maybeApi = api;
             if (typeof maybeApi.shutdown === 'function') {
-                await maybeApi.shutdown();
+                await withApiLock(() => maybeApi.shutdown()).catch(async (err) => {
+                    logger.debug(`[ConnectionPool] Could not take the api lock to close a stale connection: ${err}`);
+                    await maybeApi.shutdown().catch(() => { });
+                });
                 logger.info('[ConnectionPool] Successfully closed stale API connection');
             }
         }
@@ -596,13 +633,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

@@ -200,6 +200,25 @@ 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
+    }
+}
 function _resolveSessionId() {
     return requestContext.getStore()?.sessionId;
 }
@@ -331,6 +350,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 +376,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 +390,7 @@ export async function withActualApi(rawOperation) {
         finally {
             await shutdownActualApi();
         }
-    });
+    }, { budget: _affinityBudget() });
 }
 /**
  * Variant of `withActualApi` for write operations. Identical to `withActualApi`
@@ -431,7 +452,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 +465,7 @@ export async function withActualApiWrite(operation) {
         finally {
             await shutdownActualApi();
         }
-    });
+    }, { budget: _affinityBudget() });
 }
 /**
  * Test-only: reset the connection-reuse counter. NOT exported via the package
@@ -1398,7 +1419,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,204 @@ 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 write drain, the pool's session open, and
+            // `shutdownAll`. 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/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.8",
   "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/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",