actual-mcp-server 0.16.0 → 0.16.1

package/README.md

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

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

@@ -537,6 +537,49 @@ let writeConnectionReuseCount = 0;
 // A fix that drained on every enqueue would close the deadlock and silently turn one
 // batch into N; nothing else in the suite would notice.
 let writeQueueBatchCount = 0;
+let drainListingCache = null;
+/**
+ * Read one entity listing, memoised for the life of the current drain.
+ *
+ * Outside a drain the cache is null and this is a straight pass-through, so non-queued
+ * callers (CLI scripts, startup health checks, the read path) are unaffected and can never
+ * see a cached value.
+ *
+ * The PROMISE is cached, not the resolved value. Two guards that start concurrently inside
+ * one drain therefore share a single in-flight listing rather than racing to start two.
+ */
+async function readDrainListing(kind, fetch) {
+    if (!drainListingCache)
+        return await fetch();
+    const cached = drainListingCache.get(kind);
+    if (cached)
+        return (await cached);
+    const inFlight = fetch();
+    drainListingCache.set(kind, inFlight);
+    try {
+        return await inFlight;
+    }
+    catch (error) {
+        // A failed listing must not be cached: the next guard in this drain would inherit the
+        // failure and refuse a write for a reason that has nothing to do with its own target.
+        if (drainListingCache?.get(kind) === inFlight)
+            drainListingCache.delete(kind);
+        throw error;
+    }
+}
+/**
+ * Drop a cached listing after a write that could have changed it.
+ *
+ * Call this AFTER the write commits, never before: dropping early reopens the window this
+ * exists to close. Over-invalidating is safe and merely costs one listing; under-invalidating
+ * is a false not-found, so when in doubt, invalidate.
+ */
+function invalidateDrainListing(...kinds) {
+    if (!drainListingCache)
+        return;
+    for (const kind of kinds)
+        drainListingCache.delete(kind);
+}
 /**
  * #278: the ONLY place a write-queue drain is scheduled.
  *
@@ -586,10 +629,18 @@ async function processWriteQueue() {
     // the legacy branch, never that we attribute one session's writes to
     // another's pool entry.
     const batchSessionId = batch[0]?.sessionId;
+    // #378: every distinct session represented in this batch, computed once. See the touch call
+    // in the dispatch loop for why batchSessionId alone is not enough there.
+    const batchSessionIds = [...new Set(batch.map((b) => b.sessionId).filter((x) => !!x))];
     const usePoolBranch = !!batchSessionId && _hasPooledConnection(batchSessionId);
     logger.debug(`[WRITE QUEUE] Processing batch of ${batch.length} operations ` +
         `(sessionId=${batchSessionId ?? 'none'}, poolBranch=${usePoolBranch})`);
     try {
+        // #378 (L7): opened INSIDE the try whose `finally` nulls it. Created earlier it would
+        // survive a throw between creation and the try, which is benign today only because
+        // isProcessingWrites would wedge the queue first and make the stuck cache unreachable.
+        // Not worth depending on that accident.
+        drainListingCache = new Map();
         await withApiLock(async () => {
             try {
                 if (usePoolBranch) {
@@ -609,11 +660,32 @@ async function processWriteQueue() {
                 }
                 // Process all queued writes in the same session
                 // Each operation handles its own success/failure
-                await Promise.allSettled(batch.map(async ({ operation, resolve, reject }) => {
+                // #378: SEQUENTIAL, in enqueue order. This was `Promise.allSettled(batch.map(...))`,
+                // which dispatched the whole batch concurrently inside the one api lock.
+                //
+                // The api lock makes a drain atomic against OTHER DRAINS. It never made an operation
+                // atomic against its SIBLINGS in the same batch, and every read-then-write guard
+                // moved into this adapter by #371 and #376 assumed it did. Reproduced on develop
+                // before this change: an `actual_payees_delete` and an `actual_payees_update` of the
+                // SAME payee, issued as parallel tool calls, land in one drain; the update's
+                // pre-read sees the payee, the guard passes, and rawUpdatePayee then runs against a
+                // payee the sibling already removed. Per #360 the CRDT apply path INSERTs when the
+                // row is absent, so that is the phantom partial row the guard exists to prevent. It
+                // reproduced at every timing tested, including a zero-delay delete.
+                //
+                // Caching cannot fix that: it is an ORDERING problem, not a staleness problem. A
+                // read that happens before the sibling's write is equally wrong whether it came from
+                // a cache or the database. Ordering the batch is what makes read-decide-write hold.
+                //
+                // The concurrency lost is worth very little. Every op in a batch targets the same
+                // in-process SQLite through one api singleton, so they contend rather than overlap,
+                // and the memoisation above removes the O(n) listing cost that dominated a bulk
+                // batch: 200 guarded payee updates now pay ONE listing instead of 200.
+                //
+                // 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 } of batch) {
                     try {
-                        // Bound each queued write (#270): a stalled op must reject its own
-                        // promise (so withWriteSession callers don't hang) and let the
-                        // batch settle so the api mutex releases.
                         const result = await withOpTimeout(operation);
                         resolve(result);
                     }
@@ -621,7 +693,47 @@ async function processWriteQueue() {
                         logger.error('[WRITE QUEUE] Operation failed:', error);
                         reject(error);
                     }
-                }));
+                    finally {
+                        // #378: drop everything this operation did not explicitly promise to leave alone,
+                        // and do it whether the op resolved OR THREW. A failed op may still have written
+                        // before failing, so a rejection is not evidence that nothing changed.
+                        //
+                        // The default is invalidate-all, so a write method added later without an
+                        // annotation is merely slower, never wrong. Only the reverse mistake, claiming a
+                        // listing is preserved when it is not, produces a false not-found, and that
+                        // requires someone to write the claim down.
+                        const preserved = new Set(preservesListings ?? []);
+                        invalidateDrainListing(...['accounts', 'categories', 'categoryGroups', 'payees'].filter((k) => !preserved.has(k)));
+                        // #378: keep every session in this batch alive for the length of the drain.
+                        //
+                        // `connectionPool.touch()` is driven by inbound HTTP requests, not by write ops,
+                        // so `lastActivity` does not advance while a drain runs. That was harmless while
+                        // the batch ran concurrently and a drain was bounded by roughly one
+                        // ACTUAL_OP_TIMEOUT_MS. Sequential dispatch makes a drain's wall clock the SUM of
+                        // its ops, so a batch of slow ops can now outlive SESSION_IDLE_TIMEOUT_MINUTES
+                        // (default 5) and be swept mid-drain. The sweep's shutdownConnection calls
+                        // api.shutdown() WITHOUT holding withApiLock, which is the same hazard this file
+                        // already documents as the reason stdio is kept off the pool: it tears the
+                        // singleton down underneath an in-flight operation.
+                        //
+                        // THIS MUST STAY INSIDE THE LOOP. A single touch at drain start does nothing for
+                        // a drain whose wall clock is the SUM of its ops, which is the entire reason the
+                        // hazard exists. Hoisting it out as a tidy-up reopens the bug in full, and case
+                        // (8) of tests/unit/adapter_drain_listing_cache.test.js samples the pool clock
+                        // from inside the raw call specifically so that hoist goes red.
+                        //
+                        // AND IT MUST COVER EVERY SESSION IN THE BATCH, not just batchSessionId. That is
+                        // `batch[0]?.sessionId`, a heuristic that is sound for the pool-branch decision
+                        // above (a wrong guess merely falls back to the legacy path) and NOT sound here.
+                        // The write queue is process-global, so two HTTP sessions writing inside the same
+                        // WRITE_SESSION_DELAY_MS window batch together. Sweeping the untouched one calls
+                        // api.shutdown() on the PROCESS-GLOBAL singleton, which kills the other session's
+                        // in-flight operation as well. `touch` is a Map lookup that no-ops on an unknown
+                        // id and cannot throw, so covering the whole set costs nothing.
+                        for (const sid of batchSessionIds)
+                            connectionPool.touch(sid);
+                    }
+                }
                 // 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`);
@@ -684,6 +796,9 @@ async function processWriteQueue() {
         });
     }
     finally {
+        // #378: the cache dies with the drain, on every path including the fatal one. A drain
+        // that threw partway must not hand a partially-invalidated view to the next drain.
+        drainListingCache = null;
         isProcessingWrites = false;
         // #278: ALWAYS re-drain a non-empty queue. The old `&& writeSessionTimeout === null`
         // guard was the lost wakeup: a timer that fired mid-drain left a dead handle here,
@@ -694,7 +809,7 @@ async function processWriteQueue() {
             scheduleWriteQueueDrain();
     }
 }
-function queueWriteOperation(operation) {
+function queueWriteOperation(operation, options) {
     // ACL enforcement at the write-queue entry (#156). Failing here means the
     // op is never enqueued and no upstream resource is touched.
     _enforceBudgetAcl();
@@ -703,13 +818,27 @@ function queueWriteOperation(operation) {
     // decision in processWriteQueue would always miss. See #158.
     const sessionId = _resolveSessionId();
     return new Promise((resolve, reject) => {
-        const entry = { operation, resolve, reject, sessionId };
+        const entry = {
+            operation,
+            resolve,
+            reject,
+            sessionId,
+            preservesListings: options?.preservesListings,
+        };
         // #278: bound queue RESIDENCY, not just execution. #270's withOpTimeout bounds an
         // operation that is RUNNING; it cannot bound one that never starts. Reuse the same
         // knob so there is one timeout concept: ACTUAL_OP_TIMEOUT_MS, with <= 0 meaning
-        // disabled (matching withOpTimeout). Worst case for a single call is therefore
-        // residency + execution = 2 * ACTUAL_OP_TIMEOUT_MS; residency is normally under
-        // WRITE_SESSION_DELAY_MS (100ms).
+        // disabled (matching withOpTimeout). Residency is normally under WRITE_SESSION_DELAY_MS
+        // (100ms).
+        //
+        // #378 CHANGED THIS BOUND and it used to read "worst case for a single call is therefore
+        // residency + execution = 2 * ACTUAL_OP_TIMEOUT_MS". That was true while the batch ran
+        // concurrently. It now runs sequentially, and residency timers are cleared for EVERY
+        // entry at dispatch while withOpTimeout bounds only the op currently running, so the
+        // honest worst case for the k-th op in a batch is residency + k * ACTUAL_OP_TIMEOUT_MS.
+        // A drain's wall clock went from the MAX of its ops to the SUM. In practice each op is
+        // milliseconds against in-process SQLite, but see the touch() call in processWriteQueue
+        // for the one consequence that had to be closed rather than merely documented.
         const residencyLimitMs = config.ACTUAL_OP_TIMEOUT_MS;
         if (Number.isFinite(residencyLimitMs) && residencyLimitMs > 0) {
             entry.residencyTimer = setTimeout(() => {
@@ -806,6 +935,15 @@ export async function getAccounts() {
 // addTransactions returns various formats: "ok", array of IDs, or Transaction objects
 export async function addTransactions(txs, options = {}) {
     observability.incrementToolCall('actual.transactions.create').catch(() => { });
+    // #378: a transaction write cannot change the account, category or category-group
+    // listings, so a bulk import pays ONE accounts listing for its guard instead of one per
+    // transaction. `payees` is deliberately NOT claimed: upstream's addTransactions runs
+    // normalizeTransactions, which returns `payeesToCreate` and creates a payee from a raw
+    // payee name (verified in loot-core/src/server/accounts/sync.ts via the source map). There
+    // is a SECOND route too, and it is not gated on the payee_name input at all: runRules fires
+    // unconditionally, and resolvePayeeNameForRules calls insertPayee when a rule action sets
+    // `payee: 'new'`. So a transaction write CAN change the payee listing by two independent
+    // paths, and claiming otherwise would produce a false not-found for a payee it just created.
     return queueWriteOperation(async () => {
         // The Actual API expects addTransactions(accountId, transactions, options)
         // Extract accountId from the first transaction and remove it from transaction objects
@@ -830,7 +968,7 @@ export async function addTransactions(txs, options = {}) {
         // deliberately still allowed: importing history into a closed account is legitimate,
         // which is why this diverges from createTransfer, where a closed account would be an
         // odd transfer destination.
-        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const accounts = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const accountExists = accounts.some((a) => a?.id === accountId);
         if (!accountExists) {
@@ -865,7 +1003,7 @@ export async function addTransactions(txs, options = {}) {
             return [result.id];
         }
         return [];
-    });
+    }, { preservesListings: ['accounts', 'categories', 'categoryGroups'] });
 }
 export async function importTransactions(accountId, txs) {
     observability.incrementToolCall('actual.transactions.import').catch(() => { });
@@ -881,7 +1019,7 @@ export async function createTransfer(params) {
         if (params.from_account === params.to_account) {
             return { success: false, error: 'from_account and to_account must be different accounts.' };
         }
-        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const accounts = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         const fromAcc = accounts.find((a) => a.id === params.from_account);
         const toAcc = accounts.find((a) => a.id === params.to_account);
         if (!fromAcc)
@@ -892,7 +1030,7 @@ export async function createTransfer(params) {
             return { success: false, error: `Account '${params.to_account}' not found. Use actual_accounts_list to find valid accounts.` };
         if (toAcc.closed)
             return { success: false, error: `Destination account '${toAcc.name}' is closed.` };
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         const transferPayee = payees.find((p) => p.transfer_acct === params.to_account && !p.tombstone);
         if (!transferPayee) {
             return { success: false, error: `No transfer payee found for destination account '${toAcc.name}'. The account may not support transfers.` };
@@ -992,9 +1130,12 @@ export async function getBudgetMonth(month) {
 }
 export async function setBudgetAmount(month, categoryId, amount) {
     observability.incrementToolCall('actual.budgets.setAmount').catch(() => { });
+    // #378: a budget amount is written to the zero/reflect budget tables and cannot change any
+    // of the four entity listings, so a month of category budgets pays ONE categories listing
+    // for its guard rather than one per category.
     return queueWriteOperation(async () => {
         // Pre-flight: verify category exists — nil/unknown UUIDs silently no-op in Actual Budget
-        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === categoryId);
         if (!exists) {
             // #377: MUST be a typed refusal. `budgets_setAmount` is one of the two tools whose
@@ -1022,7 +1163,7 @@ export async function setBudgetAmount(month, categoryId, amount) {
         }
         const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return result;
-    });
+    }, { preservesListings: ['accounts', 'categories', 'categoryGroups', 'payees'] });
 }
 export async function transferBudgetAmount(month, fromCategoryId, toCategoryId, amount) {
     observability.incrementToolCall('actual.budgets.transfer').catch(() => { });
@@ -1073,12 +1214,15 @@ export async function createAccount(account, initialBalance) {
 export async function updateAccount(id, fields) {
     observability.incrementToolCall('actual.accounts.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
         // A CLOSED account is still updatable: getAccounts filters `tombstone = 0`, not
         // `closed = 0`, so this refuses only ids that genuinely do not exist.
-        const accounts = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const accounts = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(accounts) && accounts.some((a) => a?.id === id))) {
             throw new NotFoundRefusal('Account', id, 'actual_accounts_list');
         }
@@ -1243,12 +1387,15 @@ export async function deleteTransaction(id) {
 export async function updateCategory(id, fields) {
     observability.incrementToolCall('actual.categories.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
         // Called with no argument, upstream returns every category in every group, hidden
         // included, so a hidden category is not misreported as missing.
-        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(categories) && categories.some((c) => c?.id === id))) {
             throw new NotFoundRefusal('Category', id, 'actual_categories_get');
         }
@@ -1259,7 +1406,7 @@ export async function deleteCategory(id) {
     observability.incrementToolCall('actual.categories.delete').catch(() => { });
     return queueWriteOperation(async () => {
         // Pre-flight: verify category exists to avoid ECONNRESET on missing id (BUG-1)
-        const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+        const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === id);
         if (!exists) {
             throw new NotFoundRefusal('Category', id, 'actual_categories_get');
@@ -1270,6 +1417,9 @@ export async function deleteCategory(id) {
 export async function updatePayee(id, fields) {
     observability.incrementToolCall('actual.payees.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
@@ -1280,7 +1430,7 @@ export async function updatePayee(id, fields) {
         // strictly unreachable. It is accepted because updating an orphaned transfer payee,
         // whose account no longer exists, is not a real workflow, and because the alternative
         // is leaving four tools able to create phantom rows.
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(payees) && payees.some((p) => p?.id === id))) {
             throw new NotFoundRefusal('Payee', id, 'actual_payees_get');
         }
@@ -1340,7 +1490,7 @@ export async function deletePayee(id) {
     observability.incrementToolCall('actual.payees.delete').catch(() => { });
     return queueWriteOperation(async () => {
         // Pre-flight: verify payee exists to avoid ECONNRESET on missing id (BUG-2)
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const found = payees.find((p) => p.id === id);
         const exists = Boolean(found);
@@ -1601,7 +1751,7 @@ export async function setBudgetCarryover(month, categoryId, flag) {
 export async function closeAccount(id, transferAccountId, transferCategoryId) {
     observability.incrementToolCall('actual.accounts.close').catch(() => { });
     return queueWriteOperation(async () => {
-        const before = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const before = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         const list = Array.isArray(before) ? before : [];
         const target = list.find((a) => a?.id === id);
         if (!target) {
@@ -1630,7 +1780,7 @@ export async function closeAccount(id, transferAccountId, transferCategoryId) {
             // #359's lesson applied to the only WRITE this path can add. Upstream forwards this id
             // straight into `transaction-add` unchecked, so a bogus value writes a "Closing
             // account" transaction carrying a category that does not exist, and syncs it.
-            const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
+            const categories = await withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 }));
             const known = Array.isArray(categories) && categories.some((c) => c?.id === transferCategoryId);
             if (!known) {
                 throw new Error(`Transfer category "${transferCategoryId}" not found. Use actual_categories_get to ` +
@@ -1668,7 +1818,7 @@ export async function closeAccount(id, transferAccountId, transferCategoryId) {
 export async function reopenAccount(id) {
     observability.incrementToolCall('actual.accounts.reopen').catch(() => { });
     return queueWriteOperation(async () => {
-        const before = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const before = await withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 }));
         const target = (Array.isArray(before) ? before : []).find((a) => a?.id === id);
         if (!target) {
             throw new Error(`Account "${id}" not found, so it cannot be reopened. Use actual_accounts_list to see ` +
@@ -1716,13 +1866,16 @@ export async function createCategoryGroup(group) {
 export async function updateCategoryGroup(id, fields) {
     observability.incrementToolCall('actual.category_groups.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #378: this guard's pre-read is safe against a SIBLING operation in the same drain only
+        // because the batch dispatches sequentially. It reads a listing memoised for this drain,
+        // which the previous operation invalidated unless it declared it could not change it.
         // #360: `db.update` does not run a SQL UPDATE. It sends CRDT messages, and the apply
         // path INSERTs when the row was absent, so an unknown id CREATES a partial row rather
         // than matching nothing. Refuse first, the way updateTag and updateRule already do.
         // Called with no argument, upstream returns all groups including hidden ones, so a
         // hidden group is not misreported as missing (the same reason category_groups_delete
         // can rely on this listing).
-        const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        const groups = await withConcurrency(() => retry(() => readDrainListing('categoryGroups', () => rawGetCategoryGroups()), { retries: 2, backoffMs: 200 }));
         if (!(Array.isArray(groups) && groups.some((g) => g?.id === id))) {
             throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
         }
@@ -1737,7 +1890,7 @@ export async function updateCategoryGroup(id, fields) {
 export async function deleteCategoryGroup(id) {
     observability.incrementToolCall('actual.category_groups.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        const groups = await withConcurrency(() => retry(() => readDrainListing('categoryGroups', () => rawGetCategoryGroups()), { retries: 2, backoffMs: 200 }));
         if (!Array.isArray(groups) || !groups.some((g) => g?.id === id)) {
             throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
         }
@@ -1779,7 +1932,7 @@ function summariseIds(ids, limit = 5) {
 export async function mergePayees(targetId, mergeIds) {
     observability.incrementToolCall('actual.payees.merge').catch(() => { });
     return queueWriteOperation(async () => {
-        const payees = await withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 }));
+        const payees = await withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 }));
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const byId = new Map(payees.map((p) => [p.id, p]));
         const target = byId.get(targetId);
@@ -2479,10 +2632,10 @@ export async function updateNote(id, note) {
         if (!BUDGET_MONTH_NOTE_RE.test(id)) {
             const has = (rows) => Array.isArray(rows) && rows.some((e) => e?.id === id);
             const [accounts, categories, categoryGroups, payees] = await Promise.all([
-                withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 })),
-                withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 })),
-                withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 })),
-                withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('accounts', () => rawGetAccounts()), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('categories', () => rawGetCategories()), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('categoryGroups', () => rawGetCategoryGroups()), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => readDrainListing('payees', () => rawGetPayees()), { retries: 2, backoffMs: 200 })),
             ]);
             if (!has(accounts) && !has(categories) && !has(categoryGroups) && !has(payees)) {
                 // Guarding matters here for the same reason as #360: upstream's note write is a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "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/budget_acl_enforcement.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_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",