actual-mcp-server 0.12.0 → 0.14.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. An account with NO transactions is REMOVED by Actual, not closed |
-| `actual_accounts_reopen` | Reopen closed account |
+| `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,7 +774,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.12.0 | **Tool Count:** 74 (verified LibreChat-compatible)
+**Version:** 0.14.0 | **Tool Count:** 74 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -11,7 +11,8 @@ import { EventEmitter } from 'events';
 import observability from '../observability.js';
 import { retry, isRetryableError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
-import { notFoundMsg } from './errors.js';
+import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg } from './errors.js';
+import { findMatchingRule } from './rule-matching.js';
 import logger from '../logger.js';
 import { checkServerVersionOnce } from './server-version-guard.js';
 import config from '../config.js';
@@ -833,8 +834,7 @@ export async function addTransactions(txs, options = {}) {
         // 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 ' +
+            throw new NotFoundRefusal('Account', accountId, 'actual_accounts_list', '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
@@ -997,7 +997,28 @@ export async function setBudgetAmount(month, categoryId, amount) {
         const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === categoryId);
         if (!exists) {
-            throw new Error(`Category "${categoryId}" not found. Use actual_categories_get to list available categories.`);
+            // #377: MUST be a typed refusal. `budgets_setAmount` is one of the two tools whose
+            // published contract is the SHAPE (#89: an unknown category returns
+            // { success: false, error }, it does not throw), and the tool decides that by type
+            // now. Leaving this as a bare Error silently undid #89, and the unit test did not
+            // catch it because it stubbed the adapter and threw the refusal itself, reproducing
+            // the fixture on both sides. There is a real-adapter case for it now.
+            throw new NotFoundRefusal('Category', String(categoryId), 'actual_categories_get');
+        }
+        // #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 OutOfRangeRefusal(`Month "${month}" is outside this budget's range, which runs from ${months[0]} to ` +
+                `${months[months.length - 1]}. Use actual_budgets_getMonths to see the months you can budget to.`, String(month));
         }
         const result = await withConcurrency(() => retry(() => rawSetBudgetAmount(month, categoryId, amount), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return result;
@@ -1052,6 +1073,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 NotFoundRefusal('Account', id, 'actual_accounts_list');
+        }
         await withConcurrency(() => retry(() => rawUpdateAccount(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
         return null;
     });
@@ -1213,6 +1243,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 NotFoundRefusal('Category', id, 'actual_categories_get');
+        }
         await withConcurrency(() => retry(() => rawUpdateCategory(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
@@ -1223,7 +1262,7 @@ export async function deleteCategory(id) {
         const categories = await withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 }));
         const exists = categories.some((c) => c.id === id);
         if (!exists) {
-            throw new Error(`Category "${id}" not found. Use actual_categories_get to list available categories.`);
+            throw new NotFoundRefusal('Category', id, 'actual_categories_get');
         }
         await withConcurrency(() => retry(() => rawDeleteCategory(id), { retries: 0, backoffMs: 200 }));
     });
@@ -1231,6 +1270,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 NotFoundRefusal('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).
@@ -1292,7 +1345,7 @@ export async function deletePayee(id) {
         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.`);
+            throw new NotFoundRefusal('Payee', id, 'actual_payees_get');
         }
         // #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
@@ -1376,10 +1429,96 @@ export async function updateRule(id, fields) {
  * 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.
  */
+/**
+ * Idempotent rule upsert (#376): update the rule whose conditions match, or create one.
+ *
+ * Moved here from `src/tools/rules_create_or_update.ts`, which ran the read and the write
+ * inside its own `withWriteSession` using raw api calls. Same single-cycle property, but the
+ * read now goes through `retry` and there is one observability call site.
+ *
+ * The caller has already validated the payload; this owns identity and merge only.
+ */
+export async function upsertRule(input, stageWasSupplied) {
+    observability.incrementToolCall('actual.rules.create_or_update').catch(() => { });
+    return queueWriteOperation(async () => {
+        const existingRules = await withConcurrency(() => retry(() => rawGetRules(), { retries: 2, backoffMs: 200 }));
+        const matchedRule = findMatchingRule(existingRules, input.conditions, input.conditionsOp);
+        const ruleData = JSON.parse(JSON.stringify(input)); // deep clone for the API call
+        if (matchedRule) {
+            // The Actual Budget API expects the FULL merged rule object as one argument.
+            //
+            // #342: `??` is WRONG for stage. null is a MEANINGFUL value here (Actual's default
+            // stage), not an absent one, so `ruleData.stage ?? existing` would silently discard
+            // an explicit `stage: null` and keep the old stage, making it impossible to move a
+            // rule back to the default. Decide on PRESENCE instead. That presence test used to
+            // be `'stage' in ruleData`, which worked only because the tool passed its parsed
+            // input straight through; it is now an explicit parameter so the meaning survives
+            // the extra call boundary.
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const merged = {
+                id: matchedRule.id,
+                stage: stageWasSupplied ? ruleData.stage : matchedRule.stage,
+                conditionsOp: ruleData.conditionsOp ?? matchedRule.conditionsOp,
+                conditions: ruleData.conditions ?? matchedRule.conditions ?? [],
+                actions: ruleData.actions ?? matchedRule.actions ?? [],
+            };
+            // Non-idempotent from upstream's point of view: do not retry the write.
+            await withConcurrency(() => retry(() => rawUpdateRule(merged), { retries: 0, backoffMs: 200 }));
+            return { id: matchedRule.id, created: false };
+        }
+        // #342: stage has no Zod default on this tool, so an omitted stage arrives as
+        // undefined. Actual's validator ALWAYS runs on a create and rejects undefined with
+        // `Invalid rule stage: undefined`, so the key must be present. null is the correct
+        // value: Actual's default stage.
+        if (ruleData.stage === undefined)
+            ruleData.stage = null;
+        const rawId = await withConcurrency(() => retry(() => rawCreateRule(ruleData), { retries: 0, backoffMs: 200 }));
+        return { id: normalizeToId(rawId), created: true };
+    });
+}
+/**
+ * #376: the existence guard and the schedule-owned refusal moved here from
+ * `src/tools/rules_delete.ts`, which held them inside its own `withWriteSession`.
+ *
+ * WHY THE ADAPTER. Doing it in the tool meant reaching past `adapter.*` for the read, so
+ * the read had no `retry` at all, and it left THIS method reachable and unguarded: calling
+ * it directly silently failed to delete a schedule-owned rule, which is the #355 defect the
+ * tool had already fixed. See "Where a read-then-write guard belongs" in CLAUDE.md.
+ *
+ * Both halves stay inside ONE `queueWriteOperation`, so the read, the decision and the
+ * write share a single api lock cycle (#142). That excludes other SESSIONS; it does not
+ * serialise against other operations in the same drain (see `reopenAccount` for the long
+ * form of that caveat).
+ */
 export async function deleteRule(id) {
     observability.incrementToolCall('actual.rules.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        return await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const allRules = await withConcurrency(() => retry(() => rawGetRules(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!Array.isArray(allRules) || !allRules.some((r) => r?.id === id)) {
+            throw new NotFoundRefusal('Rule', id, 'actual_rules_get');
+        }
+        // #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 check above cannot catch that case, because the rule
+        // genuinely exists. Reporting success there was a lie (CWE-252).
+        //
+        // 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.
+        //
+        // Not a PreflightRefusal: the write WAS attempted and upstream declined it. A
+        // PreflightRefusal means nothing was tried. See the taxonomy in
+        // .claude/skills/api-design-principles/SKILL.md.
+        const deleted = await withConcurrency(() => retry(() => rawDeleteRule(id), { retries: 0, backoffMs: 200 }));
+        if (deleted === false) {
+            throw new Error(`Rule "${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.');
+        }
     });
 }
 export async function getSchedules() {
@@ -1405,10 +1544,28 @@ export async function updateSchedule(id, fields, resetNextDate) {
         await withConcurrency(() => retry(() => rawUpdateSchedule(id, fields, resetNextDate), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
+/**
+ * #376: the existence guard and the constraint-error translation moved here from
+ * `src/tools/schedules_delete.ts`. The translation stays wrapped tightly around the delete
+ * call so the message cannot regress into the raw SQLite text.
+ */
 export async function deleteSchedule(id) {
     observability.incrementToolCall('actual.schedules.delete').catch(() => { });
     return queueWriteOperation(async () => {
-        await withConcurrency(() => retry(() => rawDeleteSchedule(id), { retries: 0, backoffMs: 200 }));
+        const schedules = await withConcurrency(() => retry(() => rawGetSchedules(), { retries: 2, backoffMs: 200 }));
+        if (!Array.isArray(schedules) || !schedules.some((sch) => sch?.id === id)) {
+            throw new NotFoundRefusal('Schedule', id, 'actual_schedules_get');
+        }
+        try {
+            await withConcurrency(() => retry(() => rawDeleteSchedule(id), { retries: 0, backoffMs: 200 }));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('NOT NULL constraint') || msg.includes('messages_crdt')) {
+                throw new Error(constraintErrorMsg('Schedule', id, 'actual_schedules_get'));
+            }
+            throw err;
+        }
     });
 }
 export async function setBudgetCarryover(month, categoryId, flag) {
@@ -1418,27 +1575,127 @@ export async function setBudgetCarryover(month, categoryId, flag) {
     });
 }
 /**
- * #357: forwards the two transfer arguments the published API documents.
+ * #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.
  *
- * `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.
+ * 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.
  *
- * Both remain OPTIONAL. A zero-balance account still closes with the id alone.
+ * 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, transferAccountId, transferCategoryId), { 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 };
     });
 }
 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.');
+        }
+        // #369 item 5: an already-open account needs no write. Upstream `reopenAccount` is a
+        // db.update, which in Actual means a CRDT MESSAGE that syncs to every other client, so
+        // issuing it for a no-op is not free: it is sync traffic and a device-state bump for a
+        // change nobody made. Reporting the non-change is also the taxonomy's rule 1 (the
+        // requested end state already holds, so this is a SUCCESS naming what did not happen),
+        // and it matches what closeAccount already does with `already-closed`.
+        if (target.closed !== true) {
+            return { outcome: 'already-open', name: target.name };
+        }
         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.');
+        }
+        return { outcome: 'reopened', name: survivor.name };
     });
 }
 export async function getCategoryGroups() {
@@ -1459,12 +1716,31 @@ 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 NotFoundRefusal('Category group', id, 'actual_category_groups_get');
+        }
         await withConcurrency(() => retry(() => rawUpdateCategoryGroup(id, fields), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
+/**
+ * #376: the existence guard moved here from `src/tools/category_groups_delete.ts`. Same
+ * reasoning as `deleteRule` above: the tool-layer version forwent `retry` on the read and
+ * left this method reachable with no guard at all.
+ */
 export async function deleteCategoryGroup(id) {
     observability.incrementToolCall('actual.category_groups.delete').catch(() => { });
     return queueWriteOperation(async () => {
+        const groups = await withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 }));
+        if (!Array.isArray(groups) || !groups.some((g) => g?.id === id)) {
+            throw new NotFoundRefusal('Category group', id, 'actual_category_groups_get');
+        }
         // Non-idempotent: do not retry (#165).
         await withConcurrency(() => retry(() => rawDeleteCategoryGroup(id), { retries: 0, backoffMs: 200 }));
     });
@@ -1598,16 +1874,38 @@ export async function batchBudgetUpdates(fn) {
  * `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 () => {
+        // `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. 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 }));
+        // 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) {
@@ -2133,7 +2431,7 @@ export async function updateTag(id, fields) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const exists = tags.some((t) => t.id === id);
         if (!exists) {
-            throw new Error(notFoundMsg('Tag', id, 'actual_tags_list'));
+            throw new NotFoundRefusal('Tag', id, 'actual_tags_list');
         }
         await withConcurrency(() => retry(() => rawUpdateTag(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
@@ -2146,7 +2444,7 @@ export async function deleteTag(id) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const exists = tags.some((t) => t.id === id);
         if (!exists) {
-            throw new Error(notFoundMsg('Tag', id, 'actual_tags_list'));
+            throw new NotFoundRefusal('Tag', id, 'actual_tags_list');
         }
         await withConcurrency(() => retry(() => rawDeleteTag(id), { retries: 0, backoffMs: 200 }));
     });
@@ -2157,9 +2455,42 @@ export async function getNote(id) {
         return await withConcurrency(() => retry(() => rawGetNote(id), { retries: 2, backoffMs: 200 }));
     });
 }
+/** A note id of this shape is a budget MONTH note and resolves to no entity row. */
+const BUDGET_MONTH_NOTE_RE = /^budget-\d{4}-\d{2}$/;
+/**
+ * #376: the orphan-id guard moved here from `src/tools/notes_update.ts`.
+ *
+ * WHY THIS ONE MATTERS MOST OF THE FIVE. The tool version issued FOUR `adapter.get*` calls
+ * through `Promise.all`, each opening its own `withActualApi` cycle, and then a fifth cycle
+ * for the write: five api lock acquisitions for one logical operation. `Promise.all` made it
+ * look concurrent, but the api mutex is process-global, so they serialised anyway. Reading
+ * inside one `queueWriteOperation` makes it ONE cycle, and the guard now sees the same
+ * snapshot the write lands on.
+ *
+ * The refusal is a NotFoundRefusal so the tool can recognise it by type (#377). The tool
+ * converts it to its published `{ error }` shape, which is a known deviation from the
+ * refusal taxonomy and is tracked on #377 rather than changed here.
+ */
 export async function updateNote(id, note) {
     observability.incrementToolCall('actual.notes.update').catch(() => { });
     return queueWriteOperation(async () => {
+        // A budget-YYYY-MM id is synthetic: it names a month, not a row, so there is nothing
+        // to look up and the four reads below would all miss.
+        if (!BUDGET_MONTH_NOTE_RE.test(id)) {
+            const has = (rows) => Array.isArray(rows) && rows.some((e) => e?.id === id);
+            const [accounts, categories, categoryGroups, payees] = await Promise.all([
+                withConcurrency(() => retry(() => rawGetAccounts(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => rawGetCategories(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => rawGetCategoryGroups(), { retries: 2, backoffMs: 200 })),
+                withConcurrency(() => retry(() => rawGetPayees(), { retries: 2, backoffMs: 200 })),
+            ]);
+            if (!has(accounts) && !has(categories) && !has(categoryGroups) && !has(payees)) {
+                // Guarding matters here for the same reason as #360: upstream's note write is a
+                // CRDT message, and the apply path INSERTs when the row is absent, so an unknown
+                // id creates an orphan note that no tool can ever read back.
+                throw new NotFoundRefusal('Entity', id, 'actual_accounts_list, actual_categories_get, actual_category_groups_get or actual_payees_get', 'A budget month note uses an id like "budget-2026-01".');
+            }
+        }
         await withConcurrency(() => retry(() => rawUpdateNote(id, note), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
     });
 }
@@ -2285,6 +2616,7 @@ export default {
     createRule,
     updateRule,
     deleteRule,
+    upsertRule,
     setBudgetCarryover,
     closeAccount,
     reopenAccount,