actual-mcp-server 0.11.6 → 0.12.0

package/README.md

@@ -314,7 +314,7 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_accounts_create` | Create new account |
 | `actual_accounts_update` | Update account details |
 | `actual_accounts_delete` | Permanently delete account |
-| `actual_accounts_close` | Close account (soft delete) |
+| `actual_accounts_close` | Close account. An account with NO transactions is REMOVED by Actual, not closed |
 | `actual_accounts_reopen` | Reopen closed account |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
@@ -774,4 +774,10 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.11.6 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.12.0 | **Tool Count:** 74 (verified LibreChat-compatible)
+
+## Sponsor
+
+I build and maintain this in my own time. It is free, it stays free, and it gets maintained either way.
+
+If it saved you some time and you feel like saying thanks, you can do that at [github.com/sponsors/agigante80](https://github.com/sponsors/agigante80). Entirely optional, and nothing about the project changes either way.

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

@@ -816,6 +816,27 @@ export async function addTransactions(txs, options = {}) {
         if (!accountId) {
             throw new Error('Transaction must include account or accountId');
         }
+        // #359: upstream never validates the account. `addTransactions`
+        // (loot-core/src/server/accounts/sync.ts) takes acctId, normalises, runs rules and
+        // inserts, and `api/transactions-add` returns the string 'ok' unconditionally. Rule
+        // evaluation does not rescue us either: prepareTransactionForRules resolves the
+        // account with `r._account?.name || ''`. So a bogus account id produced rows with a
+        // dangling `account` column that NO listing tool can return (they all filter by
+        // account), that sync to every other client, and the tool reported success.
+        //
+        // This is the same guard `createTransfer` has performed since it was written, using
+        // the same single accounts read inside the same write cycle. A CLOSED account is
+        // 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 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accountExists = accounts.some((a) => a?.id === accountId);
+        if (!accountExists) {
+            throw new Error(`Account "${accountId}" not found. Use actual_accounts_list to find valid accounts. ` +
+                'No transactions were created: Actual would otherwise have written them against an ' +
+                'account that does not exist, where no tool could retrieve them.');
+        }
         // Remove account/accountId from transaction objects as they're passed separately
         const cleanedTxs = txArray.map(tx => {
             const { account, accountId: _, ...rest } = tx;
@@ -1267,10 +1288,26 @@ export async function deletePayee(id) {
     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 exists = payees.some((p) => p.id === id);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const found = payees.find((p) => p.id === id);
+        const exists = Boolean(found);
         if (!exists) {
             throw new Error(`Payee "${id}" not found. Use actual_payees_get to list available payees.`);
         }
+        // #356: the existence check above is not enough. Actual refuses to delete a
+        // TRANSFER payee (the payee it auto-creates for each account) and refuses
+        // SILENTLY: `db.deletePayee` opens with `if (transfer_acct) { return; }`, so the
+        // call returns normally having done nothing and the tool reported success.
+        //
+        // `getPayees()` deliberately INCLUDES transfer payees, which is why they reach
+        // this point at all, and it selects `COALESCE(a.name, p.name) AS name`, so a
+        // transfer payee's own `name` is already the owning account's name. No second
+        // lookup is needed to write a useful message.
+        if (found?.transfer_acct) {
+            throw new Error(`Payee "${found.name ?? id}" is a TRANSFER payee: it belongs to the account of the ` +
+                'same name and Actual will not delete it on its own. Delete the account instead ' +
+                'with actual_accounts_delete, which removes its transfer payee too.');
+        }
         await withConcurrency(() => retry(() => rawDeletePayee(id), { retries: 0, backoffMs: 200 }));
     });
 }
@@ -1325,10 +1362,24 @@ export async function updateRule(id, fields) {
         logger.debug(`[UPDATE RULE] Update completed for rule ${id}`);
     });
 }
+/**
+ * #355: RETURNS the upstream verdict instead of discarding it, for the same reason
+ * as `holdBudgetForNextMonth` above. Upstream `deleteRule`
+ * (loot-core/src/server/transactions/transaction-rules.ts) returns `false` without
+ * throwing when a schedule owns the rule, because Actual keeps a schedule and its
+ * generated rule in step and will not let the rule be removed on its own.
+ *
+ * `actual_rules_delete` does not route through here (it calls the raw API inside one
+ * `withWriteSession` cycle, per #142), so this method currently has NO caller, and the
+ * same is true of `holdBudgetForNextMonth` below since #355 moved that tool to the same
+ * pattern. Both are kept, and both carry the verdict, so that the next caller inherits
+ * the correct contract instead of rediscovering this the hard way. Neither widening is
+ * exercised by a test today, for the same reason: nothing calls them.
+ */
 export async function deleteRule(id) {
     observability.incrementToolCall('actual.rules.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
+        return await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function getSchedules() {
@@ -1366,11 +1417,22 @@ export async function setBudgetCarryover(month, categoryId, flag) {
         await withConcurrency(() => retry(() => rawSetBudgetCarryover(month, categoryId, flag), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
-export async function closeAccount(id) {
+/**
+ * #357: forwards the two transfer arguments the published API documents.
+ *
+ * `closeAccount(id, transferAccountId?, transferCategoryId?)` is the documented
+ * signature, and upstream throws `balance is non-zero: transferAccountId is required`
+ * when an account with a balance is closed without one. This adapter used to pass the
+ * id alone, so an account with a non-zero balance could not be closed through this
+ * server at all: the caller was told to supply a parameter no tool accepted.
+ *
+ * Both remain OPTIONAL. A zero-balance account still closes with the id alone.
+ */
+export async function closeAccount(id, transferAccountId, transferCategoryId) {
     observability.incrementToolCall('actual.accounts.close').catch(() => { });
     return queueWriteOperation(async () => {
         // Non-idempotent: do not retry (#165).
-        await withConcurrency(() => retry(() => rawCloseAccount(id), { retries: 0, backoffMs: 200 }));
+        await withConcurrency(() => retry(() => rawCloseAccount(id, transferAccountId, transferCategoryId), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function reopenAccount(id) {
@@ -1407,12 +1469,72 @@ export async function deleteCategoryGroup(id) {
         await withConcurrency(() => retry(() => rawDeleteCategoryGroup(id), { retries: 0, backoffMs: 200 }));
     });
 }
+/**
+ * #356: bound what an error message echoes back. The caller supplies these ids, they end
+ * up in the tool response AND in `logger.error` via actualToolsManager, and `mergeIds`
+ * accepts up to 50 of them at 64 characters each. Naming a handful is enough to act on;
+ * naming all of them is an unbounded echo of caller-controlled input.
+ */
+function summariseIds(ids, limit = 5) {
+    const shown = ids.slice(0, limit).map((id) => (id.length > 64 ? `${id.slice(0, 64)}...` : id));
+    const rest = ids.length - shown.length;
+    return rest > 0 ? `${shown.join(', ')} (and ${rest} more)` : shown.join(', ');
+}
+/**
+ * #356: merge, with the pre-flight it never had.
+ *
+ * Upstream `db.mergePayees` fails silently in two ways and throws unhelpfully in a
+ * third:
+ *
+ *   if (payees[target].transfer_acct != null) { return; }          // silent no-op
+ *   ids = ids.filter(id => payees[id].transfer_acct == null);      // sources dropped
+ *
+ * A transfer-payee target makes the whole call a no-op; transfer-payee sources are
+ * dropped from the list without a word, while the tool still reported "merged N
+ * payee(s)" using the length of its own INPUT. And an id that does not exist at all
+ * is indexed straight off the map, so it surfaces as
+ * `TypeError: Cannot read properties of undefined (reading 'transfer_acct')`.
+ *
+ * One `getPayees()` read inside this same write cycle answers all three. It returns the
+ * de-duplicated ids it ACCEPTED for merge, which after those three refusals is the set
+ * upstream will act on. Note what it is not: there is no post-write read here, unlike
+ * close, reopen and hold, so a drop reason nobody has enumerated would still go unnoticed.
+ */
 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 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const byId = new Map(payees.map((p) => [p.id, p]));
+        const target = byId.get(targetId);
+        if (!target) {
+            throw new Error(`Payee "${targetId}" not found. Use actual_payees_get to list available payees.`);
+        }
+        if (target.transfer_acct) {
+            throw new Error(`Target payee "${target.name ?? targetId}" is a TRANSFER payee and cannot be merged ` +
+                'into. Actual silently ignores such a merge. Pick a normal payee as the target.');
+        }
+        const missing = mergeIds.filter((id) => !byId.has(id));
+        if (missing.length > 0) {
+            throw new Error(`Payee(s) not found: ${summariseIds(missing)}. Use actual_payees_get to list available payees.`);
+        }
+        const transfers = mergeIds.filter((id) => byId.get(id)?.transfer_acct);
+        if (transfers.length > 0) {
+            const names = transfers.map((id) => String(byId.get(id)?.name ?? id));
+            throw new Error(`Cannot merge TRANSFER payee(s): ${summariseIds(names)}. They belong to accounts of the ` +
+                'same name, and Actual silently drops them from a merge rather than merging them. ' +
+                'Remove them from mergeIds, or delete the account with actual_accounts_delete.');
+        }
+        if (mergeIds.includes(targetId)) {
+            throw new Error(`Payee "${targetId}" appears as both the merge target and a merge source.`);
+        }
+        // De-duplicate before reporting, or `['p','p']` claims two merges for one. The whole
+        // point of returning ids is that the count describes what happened.
+        const unique = [...new Set(mergeIds)];
         // Non-idempotent: do not retry (#165). A second merge against an
         // already-removed source payee can corrupt merge state or mislead.
-        await withConcurrency(() => retry(() => rawMergePayees(targetId, mergeIds), { retries: 0, backoffMs: 200 }));
+        await withConcurrency(() => retry(() => rawMergePayees(targetId, unique), { retries: 0, backoffMs: 200 }));
+        return unique;
     });
 }
 /**
@@ -1463,10 +1585,29 @@ export async function batchBudgetUpdates(fn) {
         await withConcurrency(() => retry(() => rawBatchBudgetUpdates(fn), { retries: 2, backoffMs: 200 }));
     });
 }
+/**
+ * #355: RETURNS the upstream verdict instead of discarding it.
+ *
+ * Upstream `holdForNextMonth` (loot-core/src/server/budget/actions.ts) returns a
+ * BOOLEAN: `true` when it buffered the amount, `false` when the month's To Budget
+ * is not positive and it held nothing. It does not throw in the second case. The
+ * published reference documents the method as `Promise<null>`, which is why the
+ * value was being thrown away here and the tool reported success for a hold that
+ * never happened (CWE-252, unchecked return value).
+ *
+ * `undefined` is deliberately NOT treated as a refusal: an older or future build
+ * that returns nothing must keep working. Only an explicit `false` is a verdict.
+ */
 export async function holdBudgetForNextMonth(month, amount) {
     observability.incrementToolCall('actual.budgets.holdForNextMonth').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawHoldBudgetForNextMonth(month, amount), { retries: 2, backoffMs: 200 }));
+        // Non-idempotent: do not retry (#165). `calcBufferedAmount` is ADDITIVE
+        // (`return buffered + amount`), so a second attempt after a committed first does not
+        // re-set the buffer, it adds to it. The window is narrow, because the call runs
+        // against local SQLite and no `TRANSIENT_ERROR_PATTERNS` message can arise inside
+        // it, but the operation is non-idempotent by construction and belongs on the same
+        // footing as `deleteRule` and `closeAccount`.
+        return await withConcurrency(() => retry(() => rawHoldBudgetForNextMonth(month, amount), { retries: 0, backoffMs: 200 }));
     });
 }
 export async function resetBudgetHold(month) {

package/dist/src/tools/accounts_close.js

@@ -1,16 +1,172 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-const InputSchema = z.object({
-    id: z.string().describe('Account ID to close'),
+import * as observability from '../observability.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getAccounts: rawGetAccounts, getCategories: rawGetCategories, closeAccount: rawCloseAccount } = api;
+const InputSchema = z
+    .object({
+    id: z.string().min(1).max(64).describe('Account ID to close'),
+    // #357: documented by the Actual API reference as required when the account's
+    // balance is non-zero, and previously not exposed at all, which made such an
+    // account impossible to close through this server.
+    transferAccountId: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe('Account ID to move the remaining balance to. REQUIRED when the account has a non-zero balance.'),
+    transferCategoryId: z
+        .string()
+        .min(1)
+        .max(64)
+        .optional()
+        .describe('Category to assign the balancing transaction to. Optional, used with transferAccountId.'),
+})
+    .superRefine((val, ctx) => {
+    if (val.transferAccountId && val.transferAccountId === val.id) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['transferAccountId'],
+            message: 'transferAccountId must be a different account from the one being closed',
+        });
+    }
 });
+/**
+ * #357: three defects on one code path, fixed together because any one of them
+ * rewrites this handler.
+ *
+ * (a) FALSE SUCCESS. Upstream `closeAccount` opens with
+ *     `if (!account || account.closed === 1) { return; }`, so closing an unknown id
+ *     or an already-closed account did nothing and reported success. Same upstream
+ *     early-return that produced #347.
+ *
+ * (b) CLOSE CAN DELETE. `if (numTransactions === 0) { await db.deleteAccount({id}); }`.
+ *     An account with no transactions is TOMBSTONED rather than closed, it disappears
+ *     from every listing, and `actual_accounts_reopen` cannot bring it back. The old
+ *     description promised "their transaction history is preserved", which is false in
+ *     exactly this case. The repo already knew: tests/manual/tests/account.js adds a
+ *     dummy transaction with a comment explaining it.
+ *
+ * (c) A BALANCE MADE IT UNCLOSABLE. `transferAccountId` and `transferCategoryId` are
+ *     documented parameters, the schema did not accept them, and upstream throws
+ *     `balance is non-zero: transferAccountId is required` without them. The caller
+ *     was told to supply something no tool would take.
+ *
+ * The read, the write and the verification run inside ONE `withWriteSession` cycle
+ * (#142). A read-BEFORE is required here, unlike #347's pure verify-after, because (b)
+ * makes "absent afterwards" ambiguous: an account deleted by the close and an id that
+ * never existed look identical from a single post-read.
+ *
+ * Going through the raw api inside the session means this path no longer gets the
+ * adapter's `retry`. That is inherent to the #142 pattern, shared with every tool using
+ * it, and it is the half of #368 that still stands. The per-tool counter is NOT lost:
+ * it is incremented in the handler below.
+ *
+ * Already-closed is reported as success rather than as an error, deliberately. The
+ * caller's intent ("this account should be closed") is already satisfied, which is the
+ * same idempotence argument #347 used for delete. What changes is that the response no
+ * longer CLAIMS a state change that did not happen.
+ */
 const tool = {
     name: 'actual_accounts_close',
-    description: `Mark an account as closed in Actual Budget. Closed accounts are hidden from most views but their transaction history is preserved. Useful for accounts that are no longer active but you want to keep the historical data.`,
+    description: 'Mark an account as closed in Actual Budget. Closed accounts are hidden from most views. ' +
+        'IMPORTANT: an account with NO transactions is REMOVED by Actual rather than closed, and cannot ' +
+        'be reopened; an account that has transactions keeps them. If the account has a non-zero balance, ' +
+        'transferAccountId is required and the remaining balance is moved there as a dated "Closing account" ' +
+        'transaction. Closing an already-closed account reports that rather than claiming a change.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.closeAccount(input.id);
-        return { success: true };
+        // #368: the adapter method that used to own this counter is no longer on the path,
+        // because this tool reads and writes through the raw api inside one session. Counting
+        // here keeps `actual.accounts.close` honest; the retry half of #368 still stands.
+        observability.incrementToolCall('actual.accounts.close').catch(() => { });
+        return await adapter.withWriteSession(async () => {
+            const before = (await rawGetAccounts());
+            const target = Array.isArray(before) ? before.find((a) => a?.id === input.id) : undefined;
+            if (!target) {
+                throw new Error(`Account "${input.id}" not found. Use actual_accounts_list to see the accounts that ` +
+                    'exist. Note that an account closed while it had no transactions was REMOVED by ' +
+                    'Actual, not closed, so it will not appear there.');
+            }
+            if (target.closed === true) {
+                // Idempotent and truthful: the requested state already holds, and the response
+                // says so instead of implying this call changed anything.
+                return {
+                    success: true,
+                    alreadyClosed: true,
+                    message: `Account "${target.name ?? input.id}" was already closed. Nothing changed.`,
+                };
+            }
+            if (input.transferAccountId) {
+                const destination = Array.isArray(before)
+                    ? before.find((a) => a?.id === input.transferAccountId)
+                    : undefined;
+                if (!destination) {
+                    throw new Error(`Transfer destination account "${input.transferAccountId}" not found. Use ` +
+                        'actual_accounts_list to pick an account to move the remaining balance to.');
+                }
+                if (destination.closed === true) {
+                    // The balancing transaction would land in a closed account, where it is hidden
+                    // from most views. Upstream does not stop this; refusing is the kinder answer.
+                    throw new Error(`Transfer destination account "${destination.name ?? input.transferAccountId}" is ` +
+                        'CLOSED, so the closing balance would be moved somewhere hidden from most views. ' +
+                        'Pick an open account, or reopen that one with actual_accounts_reopen first.');
+                }
+            }
+            if (input.transferCategoryId) {
+                // #359's lesson, applied to the only NEW write this change adds. Upstream forwards
+                // this id straight into `transaction-add` without checking it (api.ts's
+                // account-close passes it as `categoryId`, and addTransaction is a bare batch
+                // update), so a bogus value writes a "Closing account" transaction carrying a
+                // category that does not exist, and syncs it to every client. Same dangling
+                // reference the transactions_create guard exists to prevent.
+                const categories = (await rawGetCategories());
+                const categoryExists = Array.isArray(categories)
+                    ? categories.some((c) => c?.id === input.transferCategoryId)
+                    : false;
+                if (!categoryExists) {
+                    throw new Error(`Transfer category "${input.transferCategoryId}" not found. Use ` +
+                        'actual_categories_get to pick a category for the closing transaction, or omit ' +
+                        'transferCategoryId to leave it uncategorised.');
+                }
+            }
+            try {
+                await rawCloseAccount(input.id, input.transferAccountId, input.transferCategoryId);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (/balance is non-zero/i.test(msg)) {
+                    // Translate upstream's message into one the caller can act on, now that the
+                    // parameter it asks for actually exists on this tool.
+                    throw new Error(`Account "${target.name ?? input.id}" has a non-zero balance, so closing it requires ` +
+                        'transferAccountId: the id of the account to move the remaining balance to. ' +
+                        'Optionally pass transferCategoryId to categorise the balancing transaction. ' +
+                        'Use actual_accounts_list to pick a destination.');
+                }
+                throw err;
+            }
+            // Verify the effect rather than the call returning (#347).
+            const after = (await rawGetAccounts());
+            const survivor = Array.isArray(after) ? after.find((a) => a?.id === input.id) : undefined;
+            if (!survivor) {
+                // Defect (b): upstream tombstones a zero-transaction account instead of closing
+                // it. Saying so is the whole point; the old description claimed the opposite.
+                return {
+                    success: true,
+                    removed: true,
+                    message: `Account "${target.name ?? input.id}" had no transactions, so Actual REMOVED it ` +
+                        'rather than closing it. It will not appear in actual_accounts_list and cannot be ' +
+                        'reopened.',
+                };
+            }
+            if (survivor.closed !== true) {
+                throw new Error(`Account "${survivor.name ?? input.id}" (${input.id}) is still open after the close. ` +
+                    'The call was accepted but had no effect; check the account state in Actual.');
+            }
+            return { success: true, closed: true };
+        });
     },
 };
 export default tool;

package/dist/src/tools/accounts_reopen.js

@@ -1,16 +1,105 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import * as observability from '../observability.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getAccounts: rawGetAccounts, reopenAccount: rawReopenAccount } = api;
 const InputSchema = z.object({
-    id: z.string().describe('Account ID to reopen'),
+    // Bounded, because the id is echoed into the error message and into the structured
+    // logs. Not tightened to CommonSchemas.accountId (a UUID) here: several fixtures use
+    // short non-UUID ids, and that sweep is tracked separately alongside #365.
+    id: z.string().min(1).max(64).describe('Account ID to reopen'),
 });
+/**
+ * #358: this tool used to call reopen and return `{success: true}` unconditionally.
+ * For an id that is not an account, that was not merely a false success: it CREATED
+ * a nameless account.
+ *
+ * Verified in upstream source (26.8.0). `reopenAccount` is a bare update:
+ *
+ *   async function reopenAccount({ id }) { await db.update('accounts', { id, closed: 0 }); }
+ *
+ * `db.update` does not run a SQL UPDATE. It sends CRDT messages, and `apply()` in
+ * loot-core/src/server/sync/index.ts picks INSERT when the row was absent from the
+ * pre-read:
+ *
+ *   INSERT INTO accounts (id, closed) VALUES (?, ?)
+ *
+ * The accounts table has no NOT NULL columns and `tombstone` defaults to 0, while
+ * `getAccounts()` selects `WHERE a.tombstone = 0`. So the phantom row is a fully
+ * visible account with a null name, and because it is a CRDT message it SYNCS to
+ * every other client on the budget.
+ *
+ * WHY A PRE-CHECK HERE, WHEN #347 DELIBERATELY REJECTED ONE.
+ *
+ * The two cases look identical and are not. In #347 the caller's intent ("make this
+ * account not exist") could ALREADY be satisfied by an absent row, so refusing on
+ * absence would have failed a request that was in fact complete. Here the caller's
+ * intent ("reopen this account") cannot possibly be satisfied by an absent row, and
+ * proceeding actively creates one. Refusing is the only correct answer.
+ *
+ * The post-verify is kept as well, so the success claim is about observed state
+ * rather than about the call having returned. Read, write and re-read all run inside
+ * ONE `withWriteSession` cycle (#142), which keeps them in a single api lock cycle
+ * rather than three.
+ *
+ * What that does NOT give, stated precisely because an overstated guarantee gets relied
+ * on: `processWriteQueue` dispatches a batch with `Promise.allSettled`, so operations
+ * queued in the same drain window still interleave at await points. The single cycle
+ * excludes other SESSIONS, not other operations in the same batch. A concurrent
+ * close of the same account can therefore still land between this read and this write.
+ *
+ * TWO DELIBERATE LIMITS, recorded so they are not mistaken for oversights.
+ *
+ * The not-found message covers both reasons an id can be missing (never existed, or
+ * removed by a close while it had no transactions) rather than distinguishing them.
+ * `q().withDead()` would tell them apart by reading tombstoned rows, at the cost of an
+ * extra query on the failure path. Collapsing them was chosen because the message names
+ * both cases and the remedy is the same either way. If that proves confusing in
+ * practice, `withDead()` is the tool to reach for.
+ *
+ * Going through the raw api inside the session means this path no longer gets the
+ * adapter's `retry`. That is inherent to the #142 pattern, shared with every other tool
+ * using it (`rules_delete`, `schedules_delete`, `category_groups_delete`), and it is the
+ * half of #368 that still stands. The per-tool counter is NOT lost: it is incremented in
+ * the handler below.
+ */
 const tool = {
     name: 'actual_accounts_reopen',
-    description: `Reopen a previously closed account in Actual Budget. The account will become active again and visible in all views. All historical transactions remain intact.`,
+    description: 'Reopen a previously closed account in Actual Budget. The account becomes active again and ' +
+        'visible in all views, and all historical transactions remain intact. An id that is not an ' +
+        'account is refused: Actual would otherwise create an empty account under that id. Note that ' +
+        'an account closed while it had NO transactions was removed by Actual rather than closed, and ' +
+        'cannot be reopened.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.reopenAccount(input.id);
-        return { success: true };
+        // #368: the adapter method that used to own this counter is no longer on the path,
+        // because this tool reads and writes through the raw api inside one session. Counting
+        // here keeps `actual.accounts.reopen` honest; the retry half of #368 still stands.
+        observability.incrementToolCall('actual.accounts.reopen').catch(() => { });
+        return await adapter.withWriteSession(async () => {
+            const before = (await rawGetAccounts());
+            const target = Array.isArray(before) ? before.find((a) => a?.id === input.id) : undefined;
+            if (!target) {
+                throw new Error(`Account "${input.id}" not found, so it cannot be reopened. Use actual_accounts_list to ` +
+                    'see the accounts that exist. If this account was closed while it had no transactions, ' +
+                    'Actual removed it rather than closing it, and it cannot be reopened: create a new one ' +
+                    'with actual_accounts_create.');
+            }
+            await rawReopenAccount(input.id);
+            // Verify the effect rather than the call returning. Same reasoning as #347.
+            const after = (await rawGetAccounts());
+            const survivor = Array.isArray(after) ? after.find((a) => a?.id === input.id) : undefined;
+            if (!survivor) {
+                throw new Error(`Account "${input.id}" disappeared while being reopened. Check the account state in Actual.`);
+            }
+            if (survivor.closed === true) {
+                throw new Error(`Account "${survivor.name ?? input.id}" (${input.id}) is still closed after the reopen. ` +
+                    'The call was accepted but had no effect; check the account state in Actual.');
+            }
+            return { success: true };
+        });
     },
 };
 export default tool;

package/dist/src/tools/budgets_holdForNextMonth.js

@@ -1,19 +1,83 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+import * as observability from '../observability.js';
+import api from '@actual-app/api';
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const { getBudgetMonth: rawGetBudgetMonth, holdBudgetForNextMonth: rawHold } = api;
 const InputSchema = z.object({
     month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'month must be in YYYY-MM format').describe('Budget month in YYYY-MM format'),
-    amount: z.number().int().describe('Amount in cents to hold for next month'),
+    // #355: upstream rejects a non-positive amount with
+    // APIError('Amount to hold needs to be greater than 0') BEFORE it ever reaches
+    // holdForNextMonth, so the schema rejects it here instead: same answer, no wasted
+    // round trip, and the message names the field. No working client can be sending a
+    // value upstream already refuses.
+    amount: z.number().int().positive('amount must be greater than 0 (integer cents)')
+        .describe('Amount in cents to hold for next month. Must be greater than 0.'),
 });
+/**
+ * #355: report the amount actually held, not the fact that the call returned.
+ *
+ * There are TWO ways this operation quietly does less than asked, and a boolean only
+ * catches one of them.
+ *
+ *   upstream holdForNextMonth:
+ *     if (toBudget > 0) { await setBuffer(month, calcBufferedAmount(...)); return true; }
+ *     return false;
+ *
+ *   calcBufferedAmount:
+ *     amount = Math.min(Math.max(amount, -buffered), Math.max(toBudget, 0));
+ *
+ * So `false` means nothing was held, and `true` can still mean a PARTIAL hold: ask for
+ * 100.00 when only 30.00 is left to budget and 30.00 is held, silently, with a `true`.
+ * Reporting plain success for that is the same defect in a different costume.
+ *
+ * Reading `forNextMonth` (the buffered amount) before and after settles both cases from
+ * observed state rather than from a return value, which is the #347 principle. Both
+ * reads and the write share ONE `withWriteSession` cycle (#142).
+ *
+ * Cost and trade-off, recorded: two extra reads on a low-frequency budget tool, and the
+ * raw-call path forgoes the adapter's retry, which is inherent to the #142 pattern and is
+ * the half of #368 that still stands. The per-tool counter is NOT lost: it is incremented
+ * in the handler below.
+ */
 const tool = {
     name: 'actual_budgets_holdForNextMonth',
-    description: `Hold an amount from this month's budget to carry into next month. The amount is in cents. This moves money from the current month's available budget into next month.
-
-Note: This operates on the month as a whole, not on a specific category.`,
+    description: "Hold an amount from this month's budget to carry into next month. The amount is in cents. " +
+        'Actual can hold LESS than requested: it clamps the hold to the amount still left to budget, ' +
+        'and holds nothing at all when that is zero or negative. The response reports the amount ' +
+        'actually held and flags a partial hold, rather than reporting plain success.\n\n' +
+        'Note: This operates on the month as a whole, not on a specific category.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.holdBudgetForNextMonth(input.month, input.amount);
-        return { success: true };
+        // #368: the adapter method that used to own this counter is no longer on the path,
+        // because this tool reads and writes through the raw api inside one session. Counting
+        // here keeps `actual.budgets.holdForNextMonth` honest; the retry half of #368 stands.
+        observability.incrementToolCall('actual.budgets.holdForNextMonth').catch(() => { });
+        return await adapter.withWriteSession(async () => {
+            const before = (await rawGetBudgetMonth(input.month));
+            const heldBefore = Number(before?.forNextMonth ?? 0);
+            await rawHold(input.month, input.amount);
+            const after = (await rawGetBudgetMonth(input.month));
+            const heldAfter = Number(after?.forNextMonth ?? 0);
+            const held = heldAfter - heldBefore;
+            if (held <= 0) {
+                throw new Error(`Nothing was held for ${input.month}: that month has no positive amount left to budget, ` +
+                    'so there is nothing to carry into next month. Budget less to categories in that month, ' +
+                    'or check it with actual_budgets_getMonth first.');
+            }
+            if (held < input.amount) {
+                return {
+                    success: true,
+                    partial: true,
+                    requested: input.amount,
+                    held,
+                    message: `Held ${held} of the requested ${input.amount} cents for ${input.month}. Actual clamps ` +
+                        'the hold to the amount still left to budget in that month.',
+                };
+            }
+            return { success: true, held };
+        });
     },
 };
 export default tool;

package/dist/src/tools/payees_delete.js

@@ -1,11 +1,14 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 const InputSchema = z.object({
-    id: z.string().describe('Payee ID to delete'),
+    // #356: bounded, because the id is echoed into the error message and the logs.
+    id: z.string().min(1).max(64).describe('Payee ID to delete'),
 });
 const tool = {
     name: 'actual_payees_delete',
-    description: 'Delete a payee from Actual Budget. Transactions using this payee will have it removed. This operation cannot be undone.',
+    description: 'Delete a payee from Actual Budget. Transactions using this payee will have it removed. This ' +
+        'operation cannot be undone. A TRANSFER payee (the payee Actual creates for each account, named ' +
+        'after it) cannot be deleted on its own: the call is refused and points at actual_accounts_delete.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});

package/dist/src/tools/payees_merge.js

@@ -1,17 +1,53 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
+// #356: bounded on both axes. The ids are echoed back in error messages and into the
+// structured logs, so an unbounded string or array is an unbounded echo. Actual's ids
+// are UUIDs, so 64 characters is already generous, and no legitimate merge consolidates
+// more than a few hundred payees in one call.
+const PayeeIdSchema = z.string().min(1).max(64);
 const InputSchema = z.object({
-    targetId: z.string().describe('ID of the target payee to merge into (this payee will be retained)'),
-    mergeIds: z.array(z.string()).describe('Array of payee IDs to merge into the target payee (these will be consolidated)'),
+    targetId: PayeeIdSchema.describe('ID of the target payee to merge into (this payee will be retained)'),
+    mergeIds: z.array(PayeeIdSchema).min(1).max(50)
+        .describe('Array of payee IDs to merge into the target payee (these will be consolidated)'),
 });
 const tool = {
     name: 'actual_payees_merge',
-    description: `Merge one or more payees into a target payee. This consolidates duplicate payees by merging the specified payees into the target, retaining the name of the target payee. All transactions from merged payees will be reassigned to the target payee.`,
+    description: 'Merge one or more payees into a target payee. This consolidates duplicate payees by merging ' +
+        'the specified payees into the target, retaining the name of the target payee. All transactions ' +
+        'from merged payees are reassigned to the target. TRANSFER payees (the payee Actual creates for ' +
+        'each account) cannot be merged in either direction: such a merge is refused rather than ' +
+        'silently ignored. The response lists the de-duplicated ids that were ACCEPTED for merge ' +
+        'after those checks; it is not a post-write read, so verify with actual_payees_get if you ' +
+        'need proof the payees are gone.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
-        await adapter.mergePayees(input.targetId, input.mergeIds);
-        return { success: true, message: `Successfully merged ${input.mergeIds.length} payee(s) into target payee` };
+        // #356: report what HAPPENED, not what was asked for. The old message counted
+        // `input.mergeIds.length`, which is a statement about the caller's input: it said
+        // "merged 3 payees" even when Actual had silently dropped every one of them for
+        // being a transfer payee. The adapter now refuses that case outright and returns
+        // the ids it actually merged.
+        // The adapter returns the ids it merged. If a future change ever made it return
+        // something else, falling back to `input.mergeIds` would silently reinstate exactly
+        // the "report the request, not the result" bug this ticket removed, so fail loudly
+        // instead.
+        const merged = await adapter.mergePayees(input.targetId, input.mergeIds);
+        if (!Array.isArray(merged)) {
+            throw new Error('Internal: adapter.mergePayees did not report which payees were merged. Verify the ' +
+                'merge with actual_payees_get before assuming it happened.');
+        }
+        const mergedIds = merged;
+        // #356: `mergedIds` carries the full list for a caller that wants it; the human
+        // readable message names at most five, because up to 50 ids at 64 characters each
+        // is an unbounded echo into the response and the logs.
+        const shown = mergedIds.slice(0, 5).join(', ');
+        const rest = mergedIds.length - Math.min(mergedIds.length, 5);
+        return {
+            success: true,
+            mergedIds,
+            message: `Merged ${mergedIds.length} payee(s) into ${input.targetId}: ${shown}` +
+                (rest > 0 ? ` (and ${rest} more)` : ''),
+        };
     },
 };
 export default tool;

package/dist/src/tools/rules_delete.js

@@ -5,11 +5,15 @@ import api from '@actual-app/api';
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const { getRules: rawGetRules, deleteRule: rawDeleteRule } = api;
 const InputSchema = z.object({
-    id: z.string().describe('Rule ID to delete'),
+    // Bounded for the same reason as the payee ids in #356: this value is echoed into the
+    // not-found message, into the schedule-owned refusal below, and into logger.error.
+    id: z.string().min(1).max(64).describe('Rule ID to delete'),
 });
 const tool = {
     name: 'actual_rules_delete',
-    description: `Delete a budget rule from Actual Budget. The rule will no longer be applied to new or existing transactions. This operation cannot be undone.`,
+    description: 'Delete a budget rule from Actual Budget. The rule will no longer be applied to new or ' +
+        'existing transactions. This operation cannot be undone. A rule that belongs to a SCHEDULE ' +
+        'cannot be deleted on its own: the call is refused and names the schedule tool to use instead.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -24,7 +28,23 @@ const tool = {
                 // error, consistent with every other delete tool's not-found behavior.
                 throw new Error(notFoundMsg('Rule', input.id, 'actual_rules_get'));
             }
-            await rawDeleteRule(input.id);
+            // #355: the raw call RETURNS a verdict and it used to be discarded.
+            // Upstream `deleteRule` returns `false`, without throwing, when a schedule owns
+            // this rule: Actual keeps a schedule and its generated rule in step and refuses
+            // to remove the rule on its own. The existence pre-check above cannot catch that
+            // case, because the rule genuinely exists. Reporting success there was a lie
+            // (CWE-252, unchecked return value).
+            //
+            // Only an EXPLICIT `false` is a refusal. A build that returns `undefined` (the
+            // published reference documents this method as `Promise<null>`) is treated as
+            // success, so this stays correct against older and future versions.
+            const deleted = await rawDeleteRule(input.id);
+            if (deleted === false) {
+                throw new Error(`Rule "${input.id}" belongs to a schedule and cannot be deleted on its own. ` +
+                    'Actual keeps a schedule and its generated rule in step. Delete the schedule ' +
+                    'instead with actual_schedules_delete (find it with actual_schedules_get), ' +
+                    'which removes this rule too.');
+            }
             return { success: true };
         });
     },

package/dist/src/tools/transactions_create.js

@@ -51,17 +51,17 @@ const tool = {
         try {
             // Use addTransactions - it reliably creates transactions.
             // Note: API may return "ok" string instead of a UUID depending on server version.
-            // "ok" is a valid success indicator — the transaction WAS created.
+            // "ok" is a valid success indicator: the transaction WAS created.
             const result = await adapter.addTransactions(payload);
             if (!result || result.length === 0) {
                 return {
                     success: false,
-                    error: 'Failed to create transaction — no result returned from API. Use actual_accounts_list to verify the account ID.',
+                    error: 'Failed to create transaction: no result returned from API. Use actual_accounts_list to verify the account ID.',
                     id: null,
                 };
             }
             // The API sometimes returns a UUID and sometimes "ok" depending on server version.
-            // Both are success — "ok" means created but no ID available from this API version.
+            // Both are success: "ok" means created but no ID available from this API version.
             const maybeId = result[0] && result[0] !== 'ok' && result[0].length > 10
                 ? result[0]
                 : null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/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/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/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_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/payees_delete.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/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/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/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: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",
@@ -62,7 +62,8 @@
     "config-drift": "npm run build && node scripts/config-drift.mjs",
     "node-version-drift": "node scripts/node-version-drift.mjs",
     "knip": "knip",
-    "actionlint": "bash scripts/install-actionlint.sh && ./actionlint -shellcheck= -color"
+    "actionlint": "bash scripts/install-actionlint.sh && ./actionlint -shellcheck= -color",
+    "audit:write-effect": "node scripts/check-write-effect-audit.mjs"
   },
   "dependencies": {
     "@actual-app/api": "^26.8.1",