actual-mcp-server 0.11.6 → 0.13.0

package/README.md

@@ -312,10 +312,10 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 |------|-------------|
 | `actual_accounts_list` | List all accounts |
 | `actual_accounts_create` | Create new account |
-| `actual_accounts_update` | Update account details |
+| `actual_accounts_update` | Update account details. An id that does not exist is refused rather than creating a partial record |
 | `actual_accounts_delete` | Permanently delete account |
-| `actual_accounts_close` | Close account (soft delete) |
-| `actual_accounts_reopen` | Reopen closed account |
+| `actual_accounts_close` | Close account. An account with NO transactions is REMOVED by Actual, not closed |
+| `actual_accounts_reopen` | Reopen closed account. An id that is not an account is refused rather than creating one |
 | `actual_accounts_get_balance` | Get account balance at a date |
 
 ### Transactions (14)
@@ -406,10 +406,10 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `actual_budgets_get_all` | List available budget files |
 | `actual_budgets_getMonths` | List budget months |
 | `actual_budgets_getMonth` | Get budget for a specific month |
-| `actual_budgets_setAmount` | Set category budget amount |
+| `actual_budgets_setAmount` | Set category budget amount. The month must be one the budget has (see `actual_budgets_getMonths`) |
 | `actual_budgets_transfer` | Transfer amount between categories |
 | `actual_budgets_setCarryover` | Enable/disable carryover |
-| `actual_budgets_holdForNextMonth` | Hold funds for next month |
+| `actual_budgets_holdForNextMonth` | Hold funds for next month. Actual clamps the hold to what is left to budget, so the response reports the amount actually held |
 | `actual_budgets_resetHold` | Reset hold status |
 | `actual_budgets_export` | Export the active budget as a `.zip` into `ACTUAL_EXPORT_DIR`; returns path, byte size and sha256, never the file contents |
 | `actual_budgets_import` | Restore a budget from an Actual `.zip` or a YNAB4/YNAB5 export. **Destructive:** the budget id comes from the archive, so re-importing an export *replaces* that budget's data rather than making a copy. Also loads the imported budget, changing the session's active budget |
@@ -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.13.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;
@@ -978,6 +999,21 @@ export async function setBudgetAmount(month, categoryId, amount) {
         if (!exists) {
             throw new Error(`Category "${categoryId}" not found. Use actual_categories_get to list available categories.`);
         }
+        // #361: the MONTH is unvalidated, in format AND range. `api/budget-set-amount` is the
+        // one budget handler that does not call upstream's `validateMonth`, unlike
+        // budget-set-carryover, budget-hold-for-next-month and budget-reset-hold, and the
+        // tool's schema is a bare `z.string().min(1)`, so even 'banana' reaches this point.
+        // Upstream then runs `dbMonth(month)` and INSERTs a row keyed `<month>-<category>`.
+        //
+        // A membership test against the budget's own months covers both halves at once:
+        // upstream's `validateMonth` and `api/budget-months` share the same
+        // `get-budget-bounds()` plus `range()` computation, so this reproduces its range check
+        // exactly, and a malformed string cannot be a member either.
+        const months = await withConcurrency(() => retry(() => rawGetBudgetMonths(), { retries: 2, backoffMs: 200 }));
+        if (Array.isArray(months) && months.length > 0 && !months.includes(String(month))) {
+            throw new Error(`Month "${month}" is not in this budget. It runs from ${months[0]} to ${months[months.length - 1]}. ` +
+                'Use actual_budgets_getMonths to see the months you can budget to.');
+        }
         const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return result;
     });
@@ -1031,6 +1067,15 @@ export async function createAccount(account, initialBalance) {
 export async function updateAccount(id, fields) {
     observability.incrementToolCall('actual.accounts.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #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 }));
+        if (!(Array.isArray(accounts) && accounts.some((a) => a?.id === id))) {
+            throw new Error(notFoundMsg('Account', id, 'actual_accounts_list'));
+        }
         await withConcurrency(() => retry(() => rawUpdateAccount(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return null;
     });
@@ -1192,6 +1237,15 @@ export async function deleteTransaction(id) {
 export async function updateCategory(id, fields) {
     observability.incrementToolCall('actual.categories.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #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 }));
+        if (!(Array.isArray(categories) && categories.some((c) => c?.id === id))) {
+            throw new Error(notFoundMsg('Category', id, 'actual_categories_get'));
+        }
         await withConcurrency(() => retry(() => rawUpdateCategory(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
@@ -1210,6 +1264,20 @@ export async function deleteCategory(id) {
 export async function updatePayee(id, fields) {
     observability.incrementToolCall('actual.payees.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #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.
+        // Known edge, and why it is acceptable: `db.getPayees()` excludes a transfer payee whose
+        // linked account has been hard-tombstoned, so such an orphan is refused here as
+        // not-found. A caller CAN hold such an id (transaction rows carry `payee`, and
+        // actual_entities_search and actual_get_id_by_name surface ids too), so this is not
+        // 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 }));
+        if (!(Array.isArray(payees) && payees.some((p) => p?.id === id))) {
+            throw new Error(notFoundMsg('Payee', id, 'actual_payees_get'));
+        }
         const fieldsObj = fields;
         // Extract `category` — it is NOT a direct column on the payees table in Actual Budget.
         // The "default category" feature is implemented via rules (condition: payee is X → action: set category).
@@ -1267,10 +1335,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 +1409,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,17 +1464,146 @@ 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, at the adapter layer since #371.
+ *
+ * Three upstream behaviours have to be handled together, because any one of them rewrites
+ * this function:
+ *
+ *  (a) `closeAccount` opens with `if (!account || account.closed === 1) return;`, so an
+ *      unknown id or an already-closed account did nothing and reported success.
+ *  (b) `if (numTransactions === 0) await db.deleteAccount({id})`: an account with no
+ *      transactions is TOMBSTONED, not closed, and cannot be reopened.
+ *  (c) a non-zero balance throws `balance is non-zero: transferAccountId is required`, and
+ *      the transfer arguments are documented but were not exposed until #357.
+ *
+ * Read, write and re-read share ONE `queueWriteOperation` cycle. A read-BEFORE is required
+ * (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.
+ *
+ * WHY THIS LIVES HERE AND NOT IN THE TOOL. It was in the tool until #371. Keeping the read
+ * and the write in one cycle does NOT require the raw api: this is the shape
+ * `mergePayees` already used, and doing it here keeps `retry` on the reads, keeps ONE
+ * observability call site, and leaves no unguarded `adapter.closeAccount` for a future
+ * caller to reach for. The tool maps the outcome below onto its response wording.
+ */
+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 }));
+        const before = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const list = Array.isArray(before) ? before : [];
+        const target = list.find((a) => a?.id === id);
+        if (!target) {
+            throw new Error(`Account "${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 caller is told
+            // that nothing changed rather than being implied a state change happened.
+            return { outcome: 'already-closed', name: target.name };
+        }
+        if (transferAccountId) {
+            const destination = list.find((a) => a?.id === transferAccountId);
+            if (!destination) {
+                throw new Error(`Transfer destination account "${transferAccountId}" not found. Use ` +
+                    'actual_accounts_list to pick an account to move the remaining balance to.');
+            }
+            if (destination.closed === true) {
+                throw new Error(`Transfer destination account "${destination.name ?? 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 (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 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 ` +
+                    'pick a category for the closing transaction, or omit transferCategoryId to leave ' +
+                    'it uncategorised.');
+            }
+        }
+        try {
+            // Non-idempotent: do not retry (#165).
+            await withConcurrency(() => retry(() => rawCloseAccount(id, transferAccountId, transferCategoryId), { retries: 0, backoffMs: 200 }));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (/balance is non-zero/i.test(msg)) {
+                throw new Error(`Account "${target.name ?? 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;
+        }
+        const after = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const survivor = (Array.isArray(after) ? after : []).find((a) => a?.id === id);
+        if (!survivor) {
+            // (b): upstream tombstoned a zero-transaction account instead of closing it.
+            return { outcome: 'removed', name: target.name };
+        }
+        if (survivor.closed !== true) {
+            throw new Error(`Account "${survivor.name ?? id}" (${id}) is still open after the close. The call was ` +
+                'accepted but had no effect; check the account state in Actual.');
+        }
+        return { outcome: 'closed', name: survivor.name };
     });
 }
+/**
+ * #358, at the adapter layer since #371.
+ *
+ * Upstream `reopenAccount` is a bare `db.update('accounts', {id, closed: 0})`. `db.update`
+ * does not run a SQL UPDATE: it sends CRDT messages, and the apply path INSERTs when the
+ * row was absent. The accounts table has no NOT NULL columns and `tombstone` defaults to 0,
+ * while `getAccounts()` filters `tombstone = 0`, so reopening an id that is not an account
+ * CREATES a visible nameless account that syncs to every client.
+ *
+ * A pre-check is right here and was wrong in #347: there, 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 complete request. Here the intent ("reopen this account") cannot be
+ * satisfied by an absent row, and proceeding actively creates one.
+ *
+ * TWO DELIBERATE LIMITS, carried over from the tool-layer version so they are not
+ * rediscovered as oversights.
+ *
+ * One `queueWriteOperation` keeps this read, write and re-read in a single api lock cycle.
+ * It does NOT serialise against other operations in the same batch: `processWriteQueue`
+ * dispatches with `Promise.allSettled`, so operations queued in the same drain window
+ * interleave at await points. The cycle excludes other SESSIONS, not batch siblings.
+ *
+ * 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.
+ */
 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 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 ` +
+                '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 withConcurrency(() => retry(() => rawReopenAccount(id), { retries: 2, backoffMs: 200 }));
+        const after = await withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 }));
+        const survivor = (Array.isArray(after) ? after : []).find((a) => a?.id === id);
+        if (!survivor) {
+            throw new Error(`Account "${id}" disappeared while being reopened. Check the account state in Actual.`);
+        }
+        if (survivor.closed === true) {
+            throw new Error(`Account "${survivor.name ?? id}" (${id}) is still closed after the reopen. The call ` +
+                'was accepted but had no effect; check the account state in Actual.');
+        }
     });
 }
 export async function getCategoryGroups() {
@@ -1397,6 +1624,16 @@ export async function createCategoryGroup(group) {
 export async function updateCategoryGroup(id, fields) {
     observability.incrementToolCall('actual.category_groups.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // #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 }));
+        if (!(Array.isArray(groups) && groups.some((g) => g?.id === id))) {
+            throw new Error(notFoundMsg('Category group', id, 'actual_category_groups_get'));
+        }
         await withConcurrency(() => retry(() => rawUpdateCategoryGroup(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
@@ -1407,12 +1644,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 +1760,51 @@ 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.
+ */
+/**
+ * #355, at the adapter layer since #371.
+ *
+ * Upstream has TWO ways of doing less than asked, and only one of them is a boolean:
+ *
+ *   holdForNextMonth:    if (toBudget > 0) { ...; 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 with 30.00 left to budget and 30.00 is held, silently. Reading `forNextMonth`
+ * before and after settles both from observed state, which is the #347 principle and is
+ * strictly better than trusting either return value.
+ *
+ * Returns the amount ACTUALLY held. The caller compares it with what it requested.
+ */
 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 }));
+        // `isRetryable` matters here, unlike most read sites: upstream's `api/budget-month` opens
+        // with `validateMonth` and throws for an out-of-range month. Without a classifier,
+        // retry() retries EVERY rejection (see retry.ts), so a deterministic domain error would
+        // cost three upstream calls and 600ms of sleeping inside the api mutex, against the one
+        // withOpTimeout budget this whole callback shares. #177 doctrine: domain errors are
+        // terminal.
+        const before = await withConcurrency(() => retry(() => rawGetBudgetMonth(month), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
+        const heldBefore = Number(before?.forNextMonth ?? 0);
+        // 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.
+        await withConcurrency(() => retry(() => rawHoldBudgetForNextMonth(month, amount), { retries: 0, backoffMs: 200 }));
+        const after = await withConcurrency(() => retry(() => rawGetBudgetMonth(month), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
+        return Number(after?.forNextMonth ?? 0) - heldBefore;
     });
 }
 export async function resetBudgetHold(month) {

package/dist/src/tools/accounts_close.js

@@ -1,16 +1,71 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-const InputSchema = z.object({
-    id: z.string().describe('Account ID to close'),
+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. The three defects (silent no-op on unknown or already-closed, close-deletes a
+ * zero-transaction account, and the documented transfer arguments that were not exposed)
+ * are handled in `adapter.closeAccount`, which reads, writes and re-reads in one write-queue
+ * cycle and returns WHICH of the three outcomes happened.
+ *
+ * #371 moved that logic there from this file. This tool now owns only the published schema
+ * and the response wording, which is where the rest of the tool surface keeps them.
+ */
 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 };
+        const result = await adapter.closeAccount(input.id, input.transferAccountId, input.transferCategoryId);
+        const name = result.name ?? input.id;
+        switch (result.outcome) {
+            case 'already-closed':
+                return {
+                    success: true,
+                    alreadyClosed: true,
+                    message: `Account "${name}" was already closed. Nothing changed.`,
+                };
+            case 'removed':
+                return {
+                    success: true,
+                    removed: true,
+                    message: `Account "${name}" had no transactions, so Actual REMOVED it rather than closing ` +
+                        'it. It will not appear in actual_accounts_list and cannot be reopened.',
+                };
+            default:
+                return { success: true, closed: true };
+        }
     },
 };
 export default tool;

package/dist/src/tools/accounts_reopen.js

@@ -1,11 +1,27 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 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. The guard lives in `adapter.reopenAccount`, which reads, writes and re-reads inside
+ * one write-queue cycle. See that function for why a pre-check is right here and was wrong
+ * in #347.
+ *
+ * #371 moved it there from this file. The read-then-write property never needed the raw
+ * api: doing it in the adapter keeps `retry` on the reads, keeps one observability call
+ * site, and leaves no unguarded `adapter.reopenAccount` for a future caller to reach for.
+ */
 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 || {});

package/dist/src/tools/budgets_holdForNextMonth.js

@@ -2,18 +2,49 @@ import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 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.
+    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. `adapter.holdBudgetForNextMonth` reads `forNextMonth` before and after the write and
+ * returns the amount ACTUALLY held, because upstream can do less than asked in two ways: it
+ * holds nothing when the month has no positive To Budget, and it silently CLAMPS the hold to
+ * whatever is left. A boolean catches the first and misses the second.
+ *
+ * #371 moved that logic into the adapter from this file. This tool owns the schema and the
+ * wording of the three answers: held in full, held in part, held nothing.
+ */
 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 };
+        const held = await adapter.holdBudgetForNextMonth(input.month, input.amount);
+        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/budgets_setAmount.js

@@ -1,9 +1,19 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-const InputSchema = z.object({ month: z.string().min(1), categoryId: z.string().min(1), amount: z.number() });
+const InputSchema = z.object({
+    // #361: this was a bare z.string().min(1), so 'banana' parsed and reached the API. The
+    // regex matches actual_budgets_holdForNextMonth and the other month-taking tools; the
+    // adapter additionally checks the month is one this budget actually has.
+    month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'month must be in YYYY-MM format'),
+    categoryId: z.string().min(1).max(64),
+    amount: z.number().int('amount must be an integer (cents)'),
+});
 const tool = {
     name: 'actual_budgets_setAmount',
-    description: "Set the budgeted amount for a specific category in a given month. Amount in cents (e.g., 50000 = $500). Use this to allocate money to spending categories for budget planning.",
+    description: 'Set the budgeted amount for a specific category in a given month. Amount in cents ' +
+        '(e.g., 50000 = $500). Use this to allocate money to spending categories for budget planning. ' +
+        'The month must be one the budget actually has: Actual allows from three months before the ' +
+        'earliest transaction to twelve months ahead. Use actual_budgets_getMonths to see the range.',
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});
@@ -13,10 +23,20 @@ const tool = {
         }
         catch (error) {
             const msg = error instanceof Error ? error.message : String(error);
-            // The pre-flight in adapter.setBudgetAmount throws:
-            //   Category "${categoryId}" not found. Use actual_categories_get to list available categories.
-            // That string always contains BOTH "not found" AND "category", so && is the correct operator.
-            if (msg.toLowerCase().includes('not found') && msg.toLowerCase().includes('category')) {
+            const lower = msg.toLowerCase();
+            // Both PRE-FLIGHT refusals from adapter.setBudgetAmount return the same structured
+            // shape, so a caller can handle "you asked for something that does not exist" once
+            // rather than parsing two forms:
+            //
+            //   Category "<id>" not found. Use actual_categories_get ...            (#89)
+            //   Month "<month>" is not in this budget. It runs from X to Y ...      (#361)
+            //
+            // #361 added the second one, and before this it fell through to the rethrow below,
+            // so one tool answered two identical situations in two different shapes. Anything
+            // else (a genuine upstream or transport failure) still throws.
+            const isCategoryRefusal = lower.includes('not found') && lower.includes('category');
+            const isMonthRefusal = lower.includes('not in this budget');
+            if (isCategoryRefusal || isMonthRefusal) {
                 return { success: false, error: msg };
             }
             throw new Error(`Failed to set budget amount: ${msg}`);

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.13.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/write_effect_audit_membership.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: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",