actual-mcp-server 0.16.8 → 0.16.10

package/README.md

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

package/dist/src/lib/ActualConnectionPool.js

@@ -548,20 +548,36 @@ class ActualConnectionPool {
             logger.info('[ConnectionPool] Force closing any stale connections from previous instance');
             // 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 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');
-            }
+            // #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

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

@@ -0,0 +1,85 @@
+/**
+ * #388: what an OPTIONAL FILTER id means when the caller passes a NAME.
+ *
+ * The surface used to answer that question three different ways, and the inconsistency was the
+ * real defect rather than the schema question that surfaced it:
+ *
+ *   1. `transactions_search_by_amount` DETECTED the name, looked it up, and answered with the
+ *      correct UUID. Strictly the most useful thing any of them did.
+ *   2. `transactions_get` pre-flighted and returned `notFoundMsg`, naming the entity and the
+ *      listing tool but not resolving the name.
+ *   3. Everything else silently returned an EMPTY result set, which is the worst of the three:
+ *      a plausible-looking wrong answer that reads as "no transactions match".
+ *
+ * #380 swept the REQUIRED lookup ids onto `CommonSchemas` and deliberately left these behind,
+ * because tightening them is a contract decision rather than a sweep. Tightening alone (making
+ * the schema reject a non-UUID) would have deleted accommodation 1, trading the best message on
+ * the surface for a ZodError. So the schema stays a bare string and the answer moves here.
+ *
+ * THE FAST PATH READS NOTHING. A value that is already a UUID is returned untouched, without a
+ * listing call, so a correct call costs exactly what it costs today. The listing read happens
+ * only on the unhappy path, where the caller has already made a mistake and the alternative is
+ * a wrong answer.
+ *
+ * This module is deliberately PURE so it can be unit-tested without an api session; the adapter
+ * owns the impure half (fetching the listing) because that is where a listing read gets `retry`
+ * and the observability call site, and because #371 and #376 concluded that a check the tools
+ * share belongs in the adapter rather than copied into ten tool files.
+ */
+import { UUID_PATTERN } from '../constants.js';
+/** Human-readable entity name and the tool that lists it, for the refusal message. */
+export const FILTER_ID_ENTITIES = {
+    account: { entity: 'Account', listTool: 'actual_accounts_list' },
+    category: { entity: 'Category', listTool: 'actual_categories_get' },
+    payee: { entity: 'Payee', listTool: 'actual_payees_get' },
+};
+/**
+ * Is this value already a well-formed entity id?
+ *
+ * When it is, NOTHING else in this module runs: the value is handed straight back and no
+ * listing is read. That is what keeps the change free for every correct call, and it is also
+ * why a non-existent but well-formed UUID still behaves exactly as it does today (an empty
+ * result). Checking existence would mean a listing read on EVERY call, which is a cost this
+ * ticket explicitly declined to impose to fix a mistake nobody makes: the failure being fixed
+ * is a name passed where an id belongs, not a mistyped UUID.
+ */
+export function isEntityId(value) {
+    return UUID_PATTERN.test(value);
+}
+/**
+ * Find the row whose NAME is what the caller passed.
+ *
+ * Case-insensitive and trimmed, matching the accommodation this generalises. Returns undefined
+ * rather than throwing so the caller decides between "resolved" and "no such name", which are
+ * two different messages.
+ *
+ * Ambiguity is resolved by taking the FIRST match, deliberately. Actual permits two categories
+ * with the same name in different groups, so a name is not a key. Reporting the first is still
+ * strictly better than the empty result set this replaces, and the message names the id it
+ * chose, so a caller who meant the other one can see that it is not theirs.
+ */
+export function matchByName(rows, value) {
+    const wanted = value.trim().toLowerCase();
+    if (wanted === '')
+        return undefined;
+    return rows.find((r) => typeof r.name === 'string' && r.name.trim().toLowerCase() === wanted);
+}
+/**
+ * The refusal text for a name that DID resolve.
+ *
+ * It names the id rather than silently substituting it. Substituting would be friendlier for
+ * one call and wrong as a contract: the caller's next call would still pass the name, and a
+ * server that quietly accepts names has no way to report the ambiguity above.
+ */
+export function resolvedNameDetail(kind, name, id) {
+    const { entity, listTool } = FILTER_ID_ENTITIES[kind];
+    const noun = entity.toLowerCase();
+    // The article matters here only because getting it wrong ("a account") reads as a bug in the
+    // server to the person who hits this, and this string is the one they see.
+    const article = /^[aeiou]/.test(noun) ? 'an' : 'a';
+    // The ANSWER comes first, deliberately. The generic not-found prefix would otherwise put "use
+    // the listing tool" ahead of the id we already resolved, and that is the instruction a model
+    // follows.
+    return (`"${name}" is ${article} ${noun} NAME, not an id. Use "${id}" instead ` +
+        `(${listTool} lists them if that is not the ${noun} you meant).`);
+}

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';
 /**
@@ -219,6 +219,25 @@ function _affinityBudget() {
         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;
 }
@@ -644,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;
@@ -788,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
@@ -807,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 {
@@ -851,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.
                             //
@@ -887,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
@@ -952,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`);
@@ -1015,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
@@ -1175,6 +1345,7 @@ export const notifications = new EventEmitter();
 // Extracted to ./actual-adapter/normalize.ts (#166). Imported for internal use
 // and re-exported so the public surface and external importers are unchanged.
 import { normalizeToTransactionArray, normalizeToId, normalizeImportResult } from './actual-adapter/normalize.js';
+import { isEntityId, matchByName, resolvedNameDetail, FILTER_ID_ENTITIES } from './actual-adapter/filter-ids.js';
 export { normalizeToTransactionArray, normalizeToId, normalizeImportResult };
 // ---------------------------------------------------------------------------
 export async function getAccounts() {
@@ -1354,6 +1525,64 @@ export async function getPayees() {
         return await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
     });
 }
+/**
+ * #388: turn an optional FILTER id that is actually a NAME into a refusal that names the id.
+ *
+ * Every Category B field routes through here, so the surface has ONE answer to the single most
+ * likely caller mistake instead of the three it had (a helpful resolution in one tool, a bare
+ * not-found in another, and a silent empty result set in the other nine).
+ *
+ * COSTS NOTHING ON THE HAPPY PATH. A well-formed id returns immediately, with no listing read,
+ * so a correct call is byte-identical to before. Only a non-id value pays a listing, and only
+ * because the alternative is answering it with an empty result the caller will read as "no
+ * matches".
+ *
+ * It lives in the adapter rather than in the ten tool files for the reason #371 and #376 both
+ * landed on: a check the tools share belongs where the reads keep `retry` and the observability
+ * call site, and where the next caller of the same listing cannot skip it by accident.
+ *
+ * It THROWS rather than returning a result envelope, per #377's taxonomy: does-not-exist throws,
+ * and `{ success: false }` is only for a genuine multi-outcome contract. A filter id that names
+ * nothing is not a multi-outcome contract. That is also why the four tools that already had an
+ * accommodation stop returning `{ transactions: [], count: 0, error }`: an empty result set with
+ * an error tucked inside it is the shape this ticket exists to remove, not a milder version of it.
+ *
+ * `verifyExists` EXISTS SO THIS CHANGE REMOVES NOTHING, and the asymmetry is deliberate rather
+ * than an oversight, so do not "tidy" it into one behaviour without deciding the same question
+ * again. Five tools already read the listing unconditionally and already refuse a well-formed id
+ * that names nothing; they pass `verifyExists: true` and keep exactly that, with a better message.
+ * The rest never paid a listing read, and making them pay one on EVERY call to catch a mistyped
+ * UUID would impose a cost on every correct call to fix a mistake nobody makes. The mistake that
+ * actually happens, and that this ticket is about, is a NAME passed where an id belongs, which is
+ * caught on both paths because a name is never a UUID.
+ */
+export async function resolveFilterId(kind, value, opts) {
+    // The free path, and the one every correct call takes.
+    if (!opts?.verifyExists && isEntityId(value))
+        return value;
+    const { entity, listTool } = FILTER_ID_ENTITIES[kind];
+    // `rows` lets a caller that ALREADY holds the listing avoid a second read of it. Without it,
+    // `transactions_search_by_category` (which fetches accounts anyway, for off-budget filtering
+    // and enrichment) would pay two listing calls on every filtered call, which is a cost this
+    // change is supposed to avoid rather than introduce.
+    const rows = opts?.rows
+        ?? (kind === 'account' ? await getAccounts()
+            : kind === 'category' ? await getCategories()
+                : await getPayees());
+    if (isEntityId(value)) {
+        // Only reachable under verifyExists. A well-formed id that names nothing is a not-found,
+        // not a name to resolve.
+        if (rows.some((r) => r.id === value))
+            return value;
+        throw new NotFoundRefusal(entity, value, listTool);
+    }
+    const hit = matchByName(rows, value);
+    if (hit && typeof hit.id === 'string') {
+        const resolved = resolvedNameDetail(kind, String(hit.name), hit.id);
+        throw new NotFoundRefusal(entity, value, listTool, undefined, resolved);
+    }
+    throw new NotFoundRefusal(entity, value, listTool);
+}
 export async function getCommonPayees() {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.payees.commonList').catch(() => { });
@@ -3026,6 +3255,7 @@ export async function getPreferences() {
 }
 export default {
     getAccounts,
+    resolveFilterId,
     getAccountsWithBalances,
     addTransactions,
     importTransactions,

package/dist/src/lib/apiLock.js

@@ -149,8 +149,10 @@ function grantNext() {
             //
             // 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
+            // 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

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/errors.js

@@ -60,8 +60,17 @@ export class NotFoundRefusal extends PreflightRefusal {
      * @param listTool  MCP tool name the caller should use to get valid ids
      * @param detail    Optional extra sentence, e.g. what was NOT written as a result
      */
-    constructor(entity, id, listTool, detail) {
-        super(notFoundMsg(entity, id, listTool) + (detail ? ` ${detail}` : ''), 'not-found');
+    /**
+     * `overrideMessage` is for the one case where we can say something strictly MORE useful than
+     * "not found, go and list them": we already know the answer. #388 resolves a NAME passed where
+     * an id belongs, so telling the caller to list the accounts buries the id we just found behind
+     * an instruction they no longer need, and a model reading top to bottom will follow the
+     * instruction rather than the answer. The TYPE is unchanged, because the request still names
+     * something that does not exist under that identifier, and #377 is explicit that callers branch
+     * on the type rather than on message prose.
+     */
+    constructor(entity, id, listTool, detail, overrideMessage) {
+        super(overrideMessage ?? (notFoundMsg(entity, id, listTool) + (detail ? ` ${detail}` : '')), 'not-found');
         this.entity = entity;
         this.id = id;
         this.listTool = listTool;

package/dist/src/tools/bank_sync.js

@@ -9,6 +9,14 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
+        // #388: the one Category B field where `verifyExists: true` is worth a listing read on the
+        // HAPPY path too. Every other filter id costs at most a wrong-looking local result; this one
+        // reaches a THIRD PARTY, so an id that names nothing spends a provider call (and, with
+        // GoCardless, part of a rate-limited quota) to accomplish nothing. Omitting accountId still
+        // means "sync everything" and is not validated, because there is nothing to validate.
+        if (input.accountId) {
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
+        }
         try {
             await adapter.runBankSync(input.accountId ?? undefined);
             return { result: 'Bank sync initiated successfully' };

package/dist/src/tools/transactions_filter.js

@@ -19,6 +19,15 @@ const tool = {
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
         // Convert null to undefined for adapter (LibreChat sends null, adapter expects undefined)
+        // #388: these three filters silently returned an EMPTY result set when given a NAME, which
+        // is the worst of the three answers the surface used to give: a plausible-looking wrong
+        // answer. No listing is read for a well-formed id, so a correct call costs what it did.
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
+        if (input.categoryId)
+            await adapter.resolveFilterId('category', input.categoryId);
+        if (input.payeeId)
+            await adapter.resolveFilterId('payee', input.payeeId);
         const accountId = input.accountId ?? undefined;
         const startDate = input.startDate ?? undefined;
         const endDate = input.endDate ?? undefined;

package/dist/src/tools/transactions_get.js

@@ -1,6 +1,5 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-import { notFoundMsg } from '../lib/errors.js';
 const InputSchema = z.object({ accountId: z.string().optional(), startDate: z.string().optional(), endDate: z.string().optional() });
 const tool = {
     name: 'actual_transactions_get',
@@ -8,13 +7,13 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Pre-flight: verify account exists when accountId is provided (BUG-7)
+        // Pre-flight: verify the account exists when accountId is provided (BUG-7, then #388).
+        // This tool already refused a well-formed id that names nothing, and `verifyExists: true`
+        // keeps exactly that. What it gains is the third case: a NAME passed where an id belongs
+        // now comes back with the id it resolves to, instead of a refusal that only says not found.
+        // It also stops returning `{ error }` and THROWS, per #377: does-not-exist throws.
         if (input.accountId) {
-            const accounts = await adapter.getAccounts();
-            const accountExists = accounts.some((a) => a.id === input.accountId);
-            if (!accountExists) {
-                return { error: notFoundMsg('Account', input.accountId, 'actual_accounts_list') };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
         }
         const result = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
         return { result };

package/dist/src/tools/transactions_search_by_amount.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import { isPreflightRefusal } from '../lib/errors.js';
 const InputSchema = z.object({
     minAmount: z.number().optional().describe('Minimum amount in cents (use negative for expenses, e.g., -10000 for $-100.00). For expenses, use negative values (e.g., -5000 for -$50.00)'),
     maxAmount: z.number().optional().describe('Maximum amount in cents (e.g., 10000 for $100.00). For expenses, use negative values (e.g., -5000 for -$50.00)'),
@@ -23,36 +24,17 @@ const tool = {
                 throw new Error('Unbounded query: provide at least one of accountId, startDate, or endDate ' +
                     'to limit the scan scope. Full-database scans without filters can exhaust memory.');
             }
-            // Validate accountId exists if provided
+            // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+            // This block used to return an empty result set with the error tucked inside it, which reads
+            // to a model as "no transactions match". `verifyExists: true` keeps the existence check this
+            // tool already paid for.
+            // Fetched HERE rather than at the enrichment step below so the guard can reuse it.
+            // Both need the same listing, and reading it twice on every filtered call is a cost this
+            // change is meant to avoid rather than introduce.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const accounts = await adapter.getAccounts();
             if (input.accountId) {
-                const accounts = await adapter.getAccounts();
-                const accountExists = accounts.some((acc) => acc.id === input.accountId);
-                if (!accountExists) {
-                    // Check if user provided account name instead of UUID
-                    const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                    if (accountByName) {
-                        return {
-                            transactions: [],
-                            count: 0,
-                            totalAmount: 0,
-                            amountRange: {
-                                min: input.minAmount,
-                                max: input.maxAmount,
-                            },
-                            error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                        };
-                    }
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        amountRange: {
-                            min: input.minAmount,
-                            max: input.maxAmount,
-                        },
-                        error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                    };
-                }
+                await adapter.resolveFilterId('account', input.accountId, { verifyExists: true, rows: accounts });
             }
             // Get base transactions (filtered by account and date range if provided)
             const allTransactions = await adapter.getTransactions(input.accountId, input.startDate, input.endDate);
@@ -111,8 +93,7 @@ const tool = {
                 return amountB - amountA;
             });
             const limited = filtered.slice(0, input.limit || 100);
-            // Enrich transactions with account names
-            const accounts = await adapter.getAccounts();
+            // Enrich transactions with account names (listing already in hand, see above)
             const accountMap = new Map(accounts.map((acc) => [acc.id, acc.name]));
             const enrichedTransactions = limited.map((t) => ({
                 ...t,
@@ -131,6 +112,12 @@ const tool = {
         }
         catch (error) {
             const message = error?.message || String(error);
+            // #377/#388: a PREFLIGHT REFUSAL is not a crash and must not be flattened into one.
+            // This guard exists so an unexpected failure does not take the server down. A refusal is
+            // the opposite: a deliberate answer that the request cannot be served, and burying it here
+            // would restore exactly the empty-result-with-an-error shape #388 removed.
+            if (isPreflightRefusal(error))
+                throw error;
             // Don't crash the server — return structured error
             return {
                 transactions: [],

package/dist/src/tools/transactions_search_by_category.js

@@ -18,29 +18,12 @@ const tool = {
         // Fetch accounts once — used for validation, off-budget filtering (issue #81), and enrichment
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const allAccounts = await adapter.getAccounts();
-        // Step 0: Validate accountId exists if provided
+        // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+        // This block used to return an empty result set with the error tucked inside it, which reads
+        // to a model as "no transactions match". `verifyExists: true` keeps the existence check this
+        // tool already paid for.
         if (input.accountId) {
-            const accountExists = allAccounts.some((acc) => acc.id === input.accountId);
-            if (!accountExists) {
-                // Check if user provided account name instead of UUID
-                const accountByName = allAccounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                if (accountByName) {
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        categoryName: input.categoryName,
-                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                    };
-                }
-                return {
-                    transactions: [],
-                    count: 0,
-                    totalAmount: 0,
-                    categoryName: input.categoryName,
-                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true, rows: allAccounts });
         }
         // Step 1: Find category ID by name
         let categoryId;

package/dist/src/tools/transactions_search_by_month.js

@@ -15,31 +15,17 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Step 0: Validate accountId exists if provided
+        // Fetched HERE rather than further down so the #388 guard below can reuse it. The guard
+        // needs the listing and so does the off-budget filtering, and without sharing them this
+        // handler read the same listing twice on every filtered call.
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await adapter.getAccounts();
+        // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+        // This block used to return { transactions: [], count: 0, ..., error }, an empty result set
+        // with the error tucked inside it, which reads to a model as "no transactions match".
+        // `verifyExists: true` keeps the existence check this tool already paid for.
         if (input.accountId) {
-            const accounts = await adapter.getAccounts();
-            const accountExists = accounts.some((acc) => acc.id === input.accountId);
-            if (!accountExists) {
-                // Check if user provided account name instead of UUID
-                const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                const month = input.month || `${new Date().getFullYear()}-${String(new Date().getMonth() + 1).padStart(2, '0')}`;
-                if (accountByName) {
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        month,
-                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                    };
-                }
-                return {
-                    transactions: [],
-                    count: 0,
-                    totalAmount: 0,
-                    month,
-                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true, rows: accounts });
         }
         // Default to current month if not provided
         const today = new Date();
@@ -60,9 +46,6 @@ const tool = {
                 month,
             };
         }
-        // Fetch accounts once — used for off-budget filtering (issue #81) and enrichment
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const accounts = await adapter.getAccounts();
         // Exclude off-budget accounts (issue #81) — their transactions cannot have
         // categories set; any update is silently discarded by Actual Budget.
         const offBudgetIds = new Set(

package/dist/src/tools/transactions_search_by_payee.js

@@ -16,30 +16,12 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        // Step 0: Validate accountId exists if provided
+        // #388: ONE answer to a name passed where an id belongs, shared by every Category B field.
+        // This block used to return an empty result set with the error tucked inside it, which reads
+        // to a model as "no transactions match". `verifyExists: true` keeps the existence check this
+        // tool already paid for.
         if (input.accountId) {
-            const accounts = await adapter.getAccounts();
-            const accountExists = accounts.some((acc) => acc.id === input.accountId);
-            if (!accountExists) {
-                // Check if user provided account name instead of UUID
-                const accountByName = accounts.find((acc) => acc.name && acc.name.toLowerCase() === input.accountId.toLowerCase());
-                if (accountByName) {
-                    return {
-                        transactions: [],
-                        count: 0,
-                        totalAmount: 0,
-                        payeeName: input.payeeName,
-                        error: `Account '${input.accountId}' appears to be a name, not an ID. Use account UUID '${accountByName.id}' instead.`,
-                    };
-                }
-                return {
-                    transactions: [],
-                    count: 0,
-                    totalAmount: 0,
-                    payeeName: input.payeeName,
-                    error: `Account '${input.accountId}' not found. Did you mean to use account UUID instead of name? Use actual_accounts_list to get valid account UUIDs.`,
-                };
-            }
+            await adapter.resolveFilterId('account', input.accountId, { verifyExists: true });
         }
         // Step 1: Find payee ID by name
         let payeeId;

package/dist/src/tools/transactions_summary_by_category.js

@@ -12,6 +12,11 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
+        // #388: this filter silently returned an EMPTY result set when given an account NAME, a
+        // plausible-looking wrong answer. A well-formed id reads no listing, so a correct call is
+        // unchanged.
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
         // Default to current month if dates not provided
         const today = new Date();
         const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);

package/dist/src/tools/transactions_summary_by_payee.js

@@ -12,6 +12,11 @@ const tool = {
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
+        // #388: this filter silently returned an EMPTY result set when given an account NAME, a
+        // plausible-looking wrong answer. A well-formed id reads no listing, so a correct call is
+        // unchanged.
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
         // Build ActualQL query with groupBy and aggregation
         const api = await import('@actual-app/api');
         const q = api.q;

package/dist/src/tools/transactions_uncategorized.js

@@ -15,7 +15,12 @@ import { CommonSchemas } from '../lib/schemas/common.js';
 const InputSchema = z.object({
     startDate: CommonSchemas.date.optional().describe('Start date in YYYY-MM-DD format (default: all-time)'),
     endDate: CommonSchemas.date.optional().describe('End date in YYYY-MM-DD format (default: today)'),
-    accountId: CommonSchemas.accountId.optional().describe('Filter to a specific account ID (optional)'),
+    // #388: an OPTIONAL FILTER, so it belongs with the other twelve rather than with the required
+    // lookup ids #380 tightened. Under `CommonSchemas.accountId` a caller passing an account NAME
+    // got "Invalid uuid" and no way to learn the id, which is the answer this ticket argues is worse
+    // than resolving the name. The schema is bare so the handler runs and can resolve it; the
+    // exception entry in tool_id_schema_drift records that this is deliberate.
+    accountId: z.string().optional().describe('Filter to a specific account ID (optional)'),
     includeTransactions: z.boolean().optional().default(false).describe('When true, include paginated transaction rows in the response (default: false)'),
     limit: z.number().int().min(1).max(1000).optional().default(50).describe('Max transactions per page when includeTransactions is true (default: 50, max: 1000)'),
     offset: z.number().int().min(0).optional().default(0).describe('Pagination start index when includeTransactions is true (default: 0)'),
@@ -46,6 +51,8 @@ const tool = {
         const today = new Date();
         const startDate = input.startDate || '2000-01-01';
         const endDate = input.endDate || today.toISOString().split('T')[0];
+        if (input.accountId)
+            await adapter.resolveFilterId('account', input.accountId);
         const accountId = input.accountId ?? undefined;
         // Full table scan when no accountId — reliably returns newly written transactions
         // across separate WAL sessions in CI Docker. Filtering by accountId uses an index

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.8",
+  "version": "0.16.10",
   "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/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: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/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.test.js && node tests/unit/api_coverage_baseline.test.js && node tests/unit/train_preflight.test.js && node tests/unit/verify_published_artifacts.test.js && node tests/unit/report_train_stale.test.js && node tests/unit/stdio_framing_check.test.js && node tests/unit/server_info.test.js && node tests/unit/transfers_create.test.js && node tests/unit/bot_target_branch.test.js && node tests/unit/auth_posture.test.js && node tests/unit/auth_posture_wiring.test.js && node tests/unit/auth-acl.test.js && node tests/unit/bug76.test.js && node tests/unit/budgets_setAmount.test.js && node tests/unit/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",