actual-mcp-server 0.20.0 → 0.22.0

package/README.md

@@ -24,13 +24,13 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 ┌─────────────┐   MCP/HTTP    ┌──────────────────┐   Actual API   ┌──────────────┐
 │  LibreChat  │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  LobeChat   │               │  Server          │               │   Budget     │
-│  (remote)   │               │  (77 tools)      │               │   Server     │
+│  (remote)   │               │  (81 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 
 ┌─────────────┐   MCP/stdio   ┌──────────────────┐   Actual API   ┌──────────────┐
 │  Claude     │ ◄───────────► │  Actual MCP      │ ◄───────────► │   Actual     │
 │  Desktop    │               │  Server          │               │   Budget     │
-│  (local)    │               │  (77 tools)      │               │   Server     │
+│  (local)    │               │  (81 tools)      │               │   Server     │
 └─────────────┘               └──────────────────┘               └──────────────┘
 ```
 
@@ -38,14 +38,14 @@ Actual MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io/
 
 Most Actual Budget MCP implementations are simple stdio bridges designed for single-user, local use with Claude Desktop. This project goes further:
 
-- **77 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
+- **81 tools, the most comprehensive coverage available.** Accounts, transactions, categories, payees, tags, notes, rules, budgets, batch operations, bank sync, and more. Covers the reachable Actual Budget API with no genuine gaps.
 - **HTTP and stdio transport.** Runs as a real remote server for LibreChat/LobeChat (`--http`), or as a direct local process for Claude Desktop (`--stdio`). No Docker or HTTP server is needed for local use.
 - **6 exclusive ActualQL-powered tools.** Search and summarise transactions by month, amount, category, or payee using Actual Budget's native query engine. Aggregated results, no raw data dumped into the AI context window.
 - **Multi-budget switching at runtime.** Configure multiple budget files and let the AI switch between them mid-conversation with `actual_budgets_switch`. Works on both transports: HTTP keys the active budget to the MCP session, and stdio (Claude Desktop, Claude Code, Cursor) gets a synthetic per-process session so a switch is scoped to that process rather than shared globally (#348).
 - **Multi-user ready with OIDC.** Secure every session with JWKS-validated JWTs and per-user budget ACLs. No shared tokens required.
 - **Production-grade reliability on both transports.** HTTP connection pooling (up to 15 concurrent sessions), and a long-lived stdio process that logs in ONCE and reuses that connection for every tool call instead of re-authenticating per call, so Claude Desktop and Claude Code stay fast and a burst of calls no longer risks a per-call login storm against the upstream limiter. Automatic retry with exponential backoff, and a full test suite (unit + E2E + integration).
 
-> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 77 tools tested end-to-end. Any MCP-compatible client should work.
+> **Verified working** with [LibreChat](https://www.librechat.ai/), [LobeChat](https://lobehub.com/home), and [Claude Desktop](https://claude.ai/download). All 81 tools tested end-to-end. Any MCP-compatible client should work.
 
 ---
 
@@ -182,7 +182,7 @@ Add to `claude_desktop_config.json` (see [docs/guides/MCP_CLIENTS_SETUP.md](docs
 }
 ```
 
-> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 77 tools are available.
+> **No token needed.** stdio runs as a local process owned by your user. The transport itself is the security boundary. All 81 tools are available.
 >
 > **`MCP_BRIDGE_DATA_DIR` should be an absolute path.** Without one, the data directory resolves relative to wherever the client spawns the process, which can be unpredictable. The directory is created automatically on first run.
 
@@ -308,9 +308,9 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 
 ## Available Tools
 
-**77 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
+**81 tools** across all categories. All tools use the `actual_<category>_<action>` naming convention.
 
-### Accounts (8)
+### Accounts (12)
 
 | Tool | Description |
 |------|-------------|
@@ -322,6 +322,10 @@ For Claude Desktop (stdio), restart Claude after upgrading.
 | `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 |
 | `actual_account_flow_summary` | Explain the exact balance change across a set of accounts over a date range: external income, expense outflow, credits, uncategorized inflows, and transfers into, out of, or within the selection, with an exact reconciliation |
+| `actual_account_groups_list` | List the custom account groups used to organise accounts in the sidebar (Actual 26.9.0+) |
+| `actual_account_groups_create` | Create an account group. Assigning accounts to it is a separate `actual_accounts_update` call |
+| `actual_account_groups_update` | Rename an account group or change its sidebar position. A group that does not exist is refused, writing nothing |
+| `actual_account_groups_delete` | Delete an account group. Its accounts are NOT deleted, they become ungrouped |
 
 ### Transactions (16)
 
@@ -594,7 +598,7 @@ stdio is the simplest way to connect Claude Desktop directly to Actual Budget. T
 - No auth token. Process ownership is the security boundary.
 - All logs go to stderr so they never corrupt the JSON-RPC framing on stdout
 - The process exits when stdin closes (Claude Desktop shutting down)
-- All 77 tools are available, identical to HTTP mode
+- All 81 tools are available, identical to HTTP mode
 
 **Start manually to verify:**
 
@@ -693,7 +697,7 @@ See [AI Client Setup, OIDC](docs/guides/AI_CLIENT_SETUP.md#oidc-authentication-m
 | Command | What It Tests | Requires Live Server |
 |---------|---------------|---------------------|
 | `npm run build` | TypeScript compilation | No |
-| `npm run test:unit-js` | 77-tool smoke, schema validation, auth ACL | No |
+| `npm run test:unit-js` | 81-tool smoke, schema validation, auth ACL | No |
 | `npm run test:adapter` | Adapter, retry logic, concurrency | No |
 | `npm run test:e2e` | MCP protocol compliance (Playwright) | No |
 | `npm run test:e2e:docker:full` | Full stack integration | Yes (Docker) |
@@ -777,7 +781,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.20.0 | **Tool Count:** 77 (verified LibreChat-compatible)
+**Version:** 0.22.0 | **Tool Count:** 81 (verified LibreChat-compatible)
 
 ## Sponsor
 

package/dist/src/actualToolsManager.js

@@ -10,6 +10,10 @@ const IMPLEMENTED_TOOLS = [
     'actual_accounts_create',
     'actual_accounts_delete',
     'actual_accounts_get_balance',
+    'actual_account_groups_list',
+    'actual_account_groups_create',
+    'actual_account_groups_update',
+    'actual_account_groups_delete',
     'actual_accounts_list',
     'actual_accounts_reopen',
     'actual_accounts_update',

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

@@ -5,13 +5,14 @@ import api from '@actual-app/api';
 // cannot expose its named exports via static import syntax. At runtime the default import
 // IS module.exports, so all methods are accessible as properties.
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences,
+const { addTransactions: rawAddTransactions, getAccounts: rawGetAccounts, importTransactions: rawImportTransactions, getTransactions: rawGetTransactions, getCategories: rawGetCategories, createCategory: rawCreateCategory, getPayees: rawGetPayees, getCommonPayees: rawGetCommonPayees, createPayee: rawCreatePayee, getBudgetMonths: rawGetBudgetMonths, getBudgetMonth: rawGetBudgetMonth, setBudgetAmount: rawSetBudgetAmount, createAccount: rawCreateAccount, updateAccount: rawUpdateAccount, getAccountBalance: rawGetAccountBalance, updateTransaction: rawUpdateTransaction, deleteTransaction: rawDeleteTransaction, updateCategory: rawUpdateCategory, deleteCategory: rawDeleteCategory, updatePayee: rawUpdatePayee, deletePayee: rawDeletePayee, deleteAccount: rawDeleteAccount, getRules: rawGetRules, createRule: rawCreateRule, updateRule: rawUpdateRule, deleteRule: rawDeleteRule, setBudgetCarryover: rawSetBudgetCarryover, closeAccount: rawCloseAccount, reopenAccount: rawReopenAccount, getCategoryGroups: rawGetCategoryGroups, createCategoryGroup: rawCreateCategoryGroup, updateCategoryGroup: rawUpdateCategoryGroup, deleteCategoryGroup: rawDeleteCategoryGroup, mergePayees: rawMergePayees, getPayeeRules: rawGetPayeeRules, batchBudgetUpdates: rawBatchBudgetUpdates, holdBudgetForNextMonth: rawHoldBudgetForNextMonth, resetBudgetHold: rawResetBudgetHold, runQuery: rawRunQuery, runBankSync: rawRunBankSync, getBudgets: rawGetBudgets, getIDByName: rawGetIDByName, getServerVersion: rawGetServerVersion, getSchedules: rawGetSchedules, createSchedule: rawCreateSchedule, updateSchedule: rawUpdateSchedule, deleteSchedule: rawDeleteSchedule, getTags: rawGetTags, createTag: rawCreateTag, updateTag: rawUpdateTag, deleteTag: rawDeleteTag, getNote: rawGetNote, updateNote: rawUpdateNote, exportBudget: rawExportBudget, importBudget: rawImportBudget, getPreferences: rawGetPreferences, getAccountGroups: rawGetAccountGroups, createAccountGroup: rawCreateAccountGroup, updateAccountGroup: rawUpdateAccountGroup, deleteAccountGroup: rawDeleteAccountGroup,
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
  } = api;
 import { EventEmitter } from 'events';
 import observability from '../observability.js';
 import { retry, isRetryableError, isRateLimitError } from './retry.js';
 import { withOpTimeout } from './opTimeout.js';
+import { markInitFailure } from './init-failure.js';
 import { NotFoundRefusal, OutOfRangeRefusal, constraintErrorMsg } from './errors.js';
 import { findMatchingRule } from './rule-matching.js';
 import logger from '../logger.js';
@@ -628,7 +629,15 @@ async function initActualApiForOperation() {
         //
         // Checking HERE covers every legacy caller in one place: both withActualApi branches,
         // withActualApiWrite, and the drain's legacy branch.
-        await ensureLoadedBudgetMatchesSession();
+        // #452: branded on the same terms as the full-init path below. This branch skips api.init()
+        // but ensureLoadedBudgetMatchesSession can still DOWNLOAD a budget (after a budgets_switch,
+        // or when another session moved the singleton), so it raises the same load failures.
+        try {
+            await ensureLoadedBudgetMatchesSession();
+        }
+        catch (err) {
+            throw markInitFailure(err);
+        }
         return;
     }
     try {
@@ -657,7 +666,12 @@ async function initActualApiForOperation() {
     }
     catch (err) {
         logger.error('[ADAPTER] Error initializing Actual API:', err);
-        throw err;
+        // #452: mark it as an INITIALISATION failure before it leaves this function. stdio has one
+        // catch for every tool error and cannot otherwise tell "the connection could not be
+        // established" from "the tool failed", and guessing from the message misfires: a #270 op
+        // timeout reads as `timeout` and a #422 rate-limit reads as `auth_failed`. The mark is
+        // additive and non-enumerable, so nothing about the error's own propagation changes.
+        throw markInitFailure(err);
     }
 }
 async function shutdownActualApi(opts) {
@@ -2683,7 +2697,11 @@ export async function runQuery(queryString) {
                         });
                     }
                     catch (error) {
-                        throw new Error(`Query execution failed: ${error.message}`);
+                        // #452 review: `cause` preserves the ORIGINAL error, so an init-failure BRAND survives
+                        // the rewrap. Without it, actual_query_run reported a failed connection as
+                        // "Query execution failed: <raw upstream text>" and stdio could not recognise it,
+                        // silently exempting this tool from the fix.
+                        throw new Error(`Query execution failed: ${error.message}`, { cause: error });
                     }
                 }
                 const trimmed = queryString.trim();
@@ -2818,7 +2836,7 @@ export async function runQuery(queryString) {
         if (errorMsg.includes('Invalid SQL query:') && (errorMsg.includes('Available fields:') || errorMsg.includes('Available tables:'))) {
             throw error; // Re-throw the well-formatted validation error without wrapping
         }
-        throw new Error(`Query execution failed: ${errorMsg}`);
+        throw new Error(`Query execution failed: ${errorMsg}`, { cause: error }); // #452: keep the brand
     }
 }
 /**
@@ -2990,9 +3008,9 @@ export async function runBankSync(accountId) {
             errorMsg.includes('BankSyncError') ||
             errorMsg.includes('NORDIGEN_ERROR') ||
             errorMsg.includes('Failed syncing account')) {
-            throw new Error(`Bank sync failed: Provider error — ${errorMsg}`);
+            throw new Error(`Bank sync failed: Provider error — ${errorMsg}`, { cause: error });
         }
-        throw new Error(`Bank sync failed: ${errorMsg}`);
+        throw new Error(`Bank sync failed: ${errorMsg}`, { cause: error }); // #452: keep the brand
     }
 }
 export async function getBudgets() {
@@ -3200,6 +3218,65 @@ export async function getServerVersion() {
     });
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
+/**
+ * Account groups (#429). Upstream added these in 26.9.0; the schema arrives through a
+ * migration SHIPPED IN `@actual-app/api` and applied to the LOCAL budget file, so these
+ * work against an older sync server too: the server relays messages and does not execute
+ * the queries.
+ *
+ * One semantic worth carrying into the tool descriptions, taken from upstream's own
+ * comment on the delete path: clearing member refs is best effort under CRDT sync, so a
+ * concurrent assignment on another device can win against those nulls. Consumers must
+ * treat an account whose `account_group_id` points at a missing or tombstoned group as
+ * UNGROUPED rather than as an error.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export async function getAccountGroups() {
+    return withActualApi(async () => {
+        observability.incrementToolCall('actual.account_groups.list').catch(() => { });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return await withConcurrency(() => retry(() => rawGetAccountGroups(), { retries: 2, backoffMs: 200 }));
+    });
+}
+export async function createAccountGroup(group) {
+    observability.incrementToolCall('actual.account_groups.create').catch(() => { });
+    return queueWriteOperation(async () => {
+        const raw = await withConcurrency(() => retry(() => rawCreateAccountGroup(group), { retries: 2, backoffMs: 200, isRetryable: isRetryableError }));
+        return normalizeToId(raw);
+        // Lands in account_groups only, so the four entity listings are untouched.
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
+}
+export async function updateAccountGroup(id, fields) {
+    observability.incrementToolCall('actual.account_groups.update').catch(() => { });
+    return queueWriteOperation(async () => {
+        // Read, decide and write inside ONE queued operation, so the existence check and the
+        // write are a single api-lock cycle and cannot be interleaved by a sibling (#371/#378).
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const groups = await withConcurrency(() => retry(() => rawGetAccountGroups(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!groups.some((g) => g.id === id)) {
+            throw new NotFoundRefusal('Account group', id, 'actual_account_groups_list');
+        }
+        await withConcurrency(() => retry(() => rawUpdateAccountGroup(id, fields), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+        // Renames the group row itself; no account row changes, so listings are preserved.
+    }, { preservesListings: PRESERVES_ALL_ENTITY_LISTINGS });
+}
+export async function deleteAccountGroup(id) {
+    observability.incrementToolCall('actual.account_groups.delete').catch(() => { });
+    return queueWriteOperation(async () => {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const groups = await withConcurrency(() => retry(() => rawGetAccountGroups(), { retries: 2, backoffMs: 200 }));
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (!groups.some((g) => g.id === id)) {
+            throw new NotFoundRefusal('Account group', id, 'actual_account_groups_list');
+        }
+        await withConcurrency(() => retry(() => rawDeleteAccountGroup(id), { retries: 0, backoffMs: 200, isRetryable: isRetryableError }));
+        // NO preservesListings claim, deliberately: upstream's delete UPDATES every member
+        // account to null its account_group_id before removing the group, so the accounts
+        // listing CONTENT changes even though its id set does not. Claiming preservation here
+        // would serve a stale accounts listing to the next guard in the same drain.
+    });
+}
 export async function getTags() {
     return withActualApi(async () => {
         observability.incrementToolCall('actual.tags.get').catch(() => { });
@@ -3421,6 +3498,10 @@ export default {
     getPayees,
     getCommonPayees,
     createPayee,
+    getAccountGroups,
+    createAccountGroup,
+    updateAccountGroup,
+    deleteAccountGroup,
     getTags,
     createTag,
     updateTag,

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

@@ -52,6 +52,19 @@ export const ACTUAL_SCHEMA = {
         mask: { type: 'string' },
         bank: { type: 'id', ref: 'banks' },
         account_sync_source: { type: 'string' },
+        // #429: these four exist in upstream's ActualQL schema but were missing here, so
+        // actual_query_run rejected valid queries against them. account_group_id arrived with
+        // account groups in 26.9.0; the other three predate it and were simply never added.
+        account_group_id: { type: 'id', ref: 'account_groups' },
+        last_reconciled: { type: 'string' },
+        last_sync: { type: 'string' },
+        bank_sync_status: { type: 'string' },
+    },
+    account_groups: {
+        id: { type: 'id' },
+        name: { type: 'string', required: true },
+        sort_order: { type: 'float' },
+        tombstone: { type: 'boolean' },
     },
     categories: {
         id: { type: 'id' },

package/dist/src/lib/budgetLoader.js

@@ -3,6 +3,8 @@ import { withOpTimeout } from './opTimeout.js';
 import config from '../config.js';
 import { setApiInitialized, setLoadedBudgetSyncId, registerBudgetLoad } from './apiState.js';
 import { createModuleLogger } from './loggerFactory.js';
+import { checkServerVersionOnce } from './server-version-guard.js';
+import { markInitFailure } from './init-failure.js';
 const log = createModuleLogger('BUDGET-LOADER');
 /**
  * #390 round 3: the ONE way this codebase loads a budget.
@@ -409,6 +411,13 @@ async function trackBudgetMutation(start, describeLoaded, label, verify, onRecor
         throw err;
     }
 }
+/**
+ * How long the #453 pre-download version probe may take before it is abandoned. Deliberately a
+ * CONSTANT and not an env var: it is an advisory diagnostic, nobody should have to tune it, and
+ * a new config key would need to be threaded through config.ts, .env.example and the README
+ * table (the config-drift guard enforces all three) to buy nothing.
+ */
+const SERVER_VERSION_PROBE_TIMEOUT_MS = 5000;
 /**
  * #394: the same discipline for an IMPORT.
  *
@@ -447,6 +456,43 @@ export async function importBudgetTracked(start, label = 'importBudget') {
     return trackBudgetMutation(start, (result) => `imported:${result.id}`, label, undefined, undefined, config.ACTUAL_IMPORT_TIMEOUT_MS);
 }
 export async function loadBudgetTracked(syncId, encryptionPassword, label = 'downloadBudget') {
+    // #453: warn BEFORE the download, not after a successful operation.
+    //
+    // #276's guard fires from `withActualApi` AFTER `rawOperation()` resolves, so it cannot reach
+    // the one case it would help most: a download that FAILS because the server's schema is newer
+    // than the bundled `@actual-app/api` (the #427 shape, which recurs on every Actual release that
+    // adds a column, for anyone who upgrades inside the dependency soak window). Nothing warned at
+    // all when the operation died.
+    //
+    // HERE rather than in `initActualApiForOperation`, which is the legacy path only: a pooled HTTP
+    // session downloads without passing through it, so a probe there would be silent for exactly the
+    // multi-user deployments most likely to run a separately-upgraded server. This function is the
+    // single funnel every load must pass through, enforced by budget_selection_precondition.test.js.
+    //
+    // Three properties hold it in place:
+    //   - OUTSIDE the tracked chain (before the try), because nothing in that chain may take the
+    //     api lock or extend the window an abandoned load holds open.
+    //   - BOUNDED by withOpTimeout: this runs inside the process-global api mutex, so an
+    //     unbounded advisory GET would stall every session. If /info is stalled the download was
+    //     going to fail anyway, so the bound costs nothing real.
+    //   - ONCE per process, via the guard's own synchronous flag, which is shared with the post-op
+    //     call site in actual-adapter.ts. Whichever fires first wins; the other becomes a no-op, so
+    //     there is no double warning. This one normally fires first, being earlier.
+    //
+    // `api.getServerVersion` is read at call time (not destructured) so it needs only the server URL
+    // that api.init() already established: NO budget has to be loaded, which is what makes a probe
+    // before the download possible at all.
+    await checkServerVersionOnce(() => withOpTimeout(() => api
+        .getServerVersion(), 'server-version-probe', 
+    // A SHORT dedicated bound, not the general ACTUAL_OP_TIMEOUT_MS (30s by default).
+    //
+    // Review of the first version caught the reason: `/info` is an unauthenticated GET on a
+    // different route from the sync endpoints, so it can stall while the login and download
+    // are perfectly healthy. At the general bound that stall costs 30s of the process-global
+    // api mutex, and since a failed probe leaves the guard armed it would be paid again on
+    // each of the next two loads. An ADVISORY diagnostic must never be able to do that. If
+    // the probe cannot answer in 5 seconds it has nothing useful to say.
+    SERVER_VERSION_PROBE_TIMEOUT_MS, 'the server-version probe bound (fixed, not configurable)'), log);
     try {
         await trackBudgetMutation(
         // #410: no redundant clear here any more. `trackBudgetMutation` owns the clear-before, and
@@ -467,10 +513,16 @@ export async function loadBudgetTracked(syncId, encryptionPassword, label = 'dow
         // all registrations under ONE bound and fails closed on timeout, so two network calls inside
         // the tracked chain would extend the window in which unrelated sessions' lock acquisitions
         // throw, to build a message an abandoned load has no caller to read.
+        // #452 review: brand EVERY failed budget load, not just the ones that happen to pass through
+        // initActualApiForOperation. The write drain calls ensureLoadedBudgetMatchesSession directly
+        // per operation, and the pooled precondition sites do too, so a load failure there escaped
+        // unbranded and stdio handed the user the raw upstream sentence the fix exists to suppress.
+        // This function is the funnel every load passes through, so branding here needs no list of
+        // call sites, which is the same argument that put the version probe above.
         if (isBudgetNotOpen(err)) {
             log.error('download resolved but no budget is open', undefined, { syncId });
-            throw postConditionError(syncId, await diagnose(syncId));
+            throw markInitFailure(postConditionError(syncId, await diagnose(syncId)));
         }
-        throw err;
+        throw markInitFailure(err);
     }
 }

package/dist/src/lib/init-failure.js

@@ -0,0 +1,240 @@
+/**
+ * Initialisation-failure classification, shared by BOTH transports.
+ *
+ * #438 built this for HTTP and left it inside `httpServer.ts`. #452 moved it here
+ * unchanged, because stdio needs the same answers and a transport importing another
+ * transport for a domain concept is the wrong dependency. `httpServer.ts` re-exports
+ * `classifyInitFailure` and `InitFailureCause`, so every existing importer is unaffected.
+ *
+ * The BRAND at the bottom of this file is the #452 addition. Read its comment before
+ * calling the classifier from any new site: the classifier is only safe where the caller
+ * already knows it is holding an initialisation failure.
+ */
+/**
+ * #438: classify a session-init failure into a CLOSED enum plus our own sentence.
+ *
+ * PURE and TOTAL: it never throws, never reads I/O, and never returns anything
+ * derived from the caught value. That last property is the wire contract: the
+ * response carries the enum member and the fixed sentence below and nothing
+ * else, so no upstream string reaches a remote client and no scrubber has to be
+ * correct. Upstream strings can carry a stack, raw SQL (`SyncError.meta.query`),
+ * an `EACCES ... mkdir '/home/<user>/.actual'` path, and a configured server URL.
+ *
+ * Exported for tests: there is NO fault-injection seam in actualConnection.ts or
+ * the pool, and booting against a closed port reaches only `network-failure`, so
+ * every other class is covered by calling this directly with synthetic values.
+ */
+// The rate-limit decision is IMPORTED, never copied. #177 collapsed the retry decision and the
+// pool-drop decision onto one authored pattern source precisely so a second list could not drift
+// from the first, and a classifier holding its own near-miss copy would reintroduce that.
+import { isRateLimitError } from './retry.js';
+const INIT_FAILURE_SENTENCES = {
+    schema_too_new: "The Actual server's database schema is newer than the @actual-app/api this build bundles. Upgrade actual-mcp-server, or hold the server upgrade until its dependency update ships.",
+    auth_failed: 'Authentication against the Actual server failed. Check ACTUAL_PASSWORD and the budget password.',
+    // Deliberately not asserting permanence: ECONNRESET and ETIMEDOUT are classed
+    // TRANSIENT by isRetryableError, so this can be a blip rather than misconfiguration.
+    network_unreachable: 'The Actual server could not be reached, which may be transient. If it persists, check ACTUAL_SERVER_URL and that the server is running.',
+    // Deliberately does NOT name a single env var. `loadBudgetTracked` brands every failed load,
+    // and actual_budgets_switch loads a budget the CALLER named, so on a multi-budget deployment
+    // "check ACTUAL_BUDGET_SYNC_ID" sent a user who asked to switch to their household budget to
+    // the wrong variable entirely. The sync id is what is wrong either way; which setting holds
+    // it depends on how the budget was selected.
+    budget_not_found: 'The requested budget was not found on the Actual server. Check the sync id it was selected by: ACTUAL_BUDGET_SYNC_ID for the default budget, or the matching BUDGET_n_SYNC_ID in a multi-budget setup.',
+    out_of_sync: 'The local budget copy is out of sync with the Actual server and could not be reconciled.',
+    encryption_error: "The budget's end-to-end encryption password is wrong or missing.",
+    clock_drift: "The host clock differs too far from the Actual server's. Fix the system time.",
+    // A filesystem permission error, WITHOUT claiming which path: the classifier
+    // sees only the errno, and EACCES can come from the data directory, TLS
+    // material, or a socket during api.init.
+    permission_denied: 'The server was denied filesystem access while initialising. Check the data directory mount and its ownership first, then any TLS material.',
+    timeout: 'Initialising the Actual connection ran out of time, which may be transient.',
+    // Deliberately NOT phrased as a credential problem: the credentials are fine, the login
+    // window is full. Actual's limiter is 500 requests per minute and is not configurable.
+    rate_limited: 'The Actual server rejected the login because too many requests were made in a short window. Nothing is misconfigured: wait a minute and retry.',
+    unknown: 'The Actual connection for this session could not be initialised. See the server log for the cause.',
+};
+/** Actual's own reason strings, from `withErrorCode` and SyncError, to our enum.
+ *  `out-of-sync-migrations` maps to schema_too_new, NOT out_of_sync: `invalid-schema`
+ *  is absent from budgetLoader's KNOWN_LOAD_REASONS, so migrations is the only route
+ *  by which a too-new schema surfaces on the post-condition path, and upstream's own
+ *  sentence for it is "This budget cannot be loaded with this version of the app." */
+const REASON_TO_CAUSE = {
+    'invalid-schema': 'schema_too_new',
+    'out-of-sync-migrations': 'schema_too_new',
+    'out-of-sync': 'out_of_sync',
+    'out-of-sync-data': 'out_of_sync',
+    'budget-not-found': 'budget_not_found',
+    'clock-drift': 'clock_drift',
+    'encrypt-failure': 'encryption_error',
+    'decrypt-failure': 'encryption_error',
+    'missing-key': 'encryption_error',
+};
+/** Node fs/net codes. A DIFFERENT namespace from Actual's reasons, deliberately
+ *  kept in its own table so the two can never be conflated. */
+const SYSTEM_CODE_TO_CAUSE = {
+    EACCES: 'permission_denied',
+    EPERM: 'permission_denied',
+    EROFS: 'permission_denied',
+    ECONNREFUSED: 'network_unreachable',
+    ENOTFOUND: 'network_unreachable',
+    ECONNRESET: 'network_unreachable',
+    EHOSTUNREACH: 'network_unreachable',
+    ETIMEDOUT: 'timeout',
+};
+/**
+ * Walks the `cause` chain, for the same reason `isInitFailure` does and discovered the same way:
+ * `runQuery` and `bankSync` rewrap into a friendlier message, and the rewrapped error carries
+ * neither the upstream `.code` nor the reason in its own text. Recognising it as an init failure
+ * while classifying it `unknown` would leave those tools propagating the raw upstream sentence,
+ * which is the exact defect #452 exists to remove. The FIRST named answer in the chain wins;
+ * `unknown` means keep looking rather than give up.
+ */
+export function classifyInitFailure(err) {
+    let current = err;
+    const seen = new Set();
+    for (let depth = 0; depth < 10; depth++) {
+        const verdict = classifyOne(current);
+        if (verdict.cause !== 'unknown')
+            return verdict;
+        if (!current || (typeof current !== 'object' && typeof current !== 'function'))
+            break;
+        if (seen.has(current))
+            break;
+        seen.add(current);
+        current = current.cause;
+        if (current === undefined || current === null)
+            break;
+    }
+    return { cause: 'unknown', sentence: INIT_FAILURE_SENTENCES.unknown };
+}
+function classifyOne(err) {
+    const done = (cause) => ({ cause, sentence: INIT_FAILURE_SENTENCES[cause] });
+    try {
+        const e = err;
+        // `.code` FIRST: upstream's api/download-budget and api/load-budget never let a
+        // SyncError escape, they throw a plain Error carrying .code via withErrorCode.
+        const code = typeof e?.code === 'string' ? e.code : undefined;
+        if (code && REASON_TO_CAUSE[code])
+            return done(REASON_TO_CAUSE[code]);
+        if (code && SYSTEM_CODE_TO_CAUSE[code])
+            return done(SYSTEM_CODE_TO_CAUSE[code]);
+        // `.reason` only as a defensive fallback, for a SyncError that reaches us by
+        // some path that does not go through those two handlers.
+        const reason = typeof e?.reason === 'string' ? e.reason : undefined;
+        if (reason && REASON_TO_CAUSE[reason])
+            return done(REASON_TO_CAUSE[reason]);
+        const message = typeof e?.message === 'string' ? e.message : '';
+        // Our OWN synthesized post-condition error (#396) embeds the upstream reason
+        // in prose. On a resync of an existing local copy this is the shape that
+        // actually arrives for the schema and migration classes, so a classifier that
+        // handled only the upstream shapes would answer `unknown` for exactly the
+        // failures this ticket is about.
+        const embedded = /Upstream reason: \[([a-z-]+)\]/.exec(message)?.[1];
+        if (embedded && REASON_TO_CAUSE[embedded])
+            return done(REASON_TO_CAUSE[embedded]);
+        // Last resort, message shapes. `network-failure` is tested BEFORE the auth
+        // wording because upstream reports an unreachable server as
+        // "Authentication failed: network-failure", where the actionable half is the
+        // network, not the credentials.
+        if (/network-failure|ECONNREFUSED|ENOTFOUND/i.test(message))
+            return done('network_unreachable');
+        if (/timed out|ETIMEDOUT/i.test(message))
+            return done('timeout');
+        // #452 review: BEFORE the auth branch. A throttled login surfaces as
+        // "Authentication failed: Too many requests" (retry.ts documents that exact shape), and
+        // withAuthRetry rethrows it once its budget is exhausted, so it reaches here as a genuine
+        // INITIALISATION failure and is branded. Classifying it `auth_failed` told a rate-limited
+        // user to check their password, which is a wrong answer in the same family this whole
+        // classifier exists to remove. It affects HTTP identically; that was live before #452.
+        if (isRateLimitError(err))
+            return done('rate_limited');
+        if (/Authentication failed|invalid-password|Invalid password/i.test(message))
+            return done('auth_failed');
+        if (/invalid-schema/i.test(message))
+            return done('schema_too_new');
+        return done('unknown');
+    }
+    catch {
+        // TOTAL by construction: a classifier that throws would land on the outer POST
+        // catch and egress as raw String(err), defeating this contract through the one
+        // line deliberately left to #446.
+        return done('unknown');
+    }
+}
+/**
+ * #452: the brand that says "this error came from establishing the Actual connection".
+ *
+ * WHY A BRAND AND NOT THE MESSAGE. `classifyInitFailure` falls back to matching message
+ * prose, which is safe at the HTTP call site because that site is reached ONLY from the
+ * catch around session init, so anything it sees IS an init failure. The stdio call site
+ * is every tool error, and there the prose branches misfire on errors that are not init
+ * failures at all. Measured on v0.21.0:
+ *
+ *   `Actual API operation timed out after 30000ms (ACTUAL_OP_TIMEOUT_MS)`  -> `timeout`
+ *   `Authentication failed: Too many requests` (the #422 rate-limit tail)   -> `auth_failed`
+ *
+ * The first is the #270 nesting-bug signal, which CLAUDE.md instructs a reader to
+ * interpret as a probable deadlock rather than a slow server. The second would tell a
+ * rate-limited user their password is wrong. Both replace a true message with a false one.
+ *
+ * So classification is gated on ORIGIN, not wording, which is the same rule #377 applies
+ * to refusals: decide by TYPE, never by matching prose.
+ *
+ * The mark is applied at the CHOKEPOINTS, not at call sites: the api-init try/catch in
+ * `initActualApiForOperation`, and both branches of `loadBudgetTracked`'s catch. The second was
+ * added in review, and the reason generalises: the write drain calls
+ * `ensureLoadedBudgetMatchesSession` directly per operation, and the pooled precondition does
+ * too, so a budget-load failure on those paths reached stdio UNBRANDED and handed the user the
+ * raw upstream sentence this exists to suppress. Branding the funnel every load passes through
+ * means the set of call sites stops mattering, which is the same argument #393 used for the
+ * abandoned-load wait.
+ *
+ * `Symbol.for` rather than a class or `instanceof`: the error object is raised by
+ * `@actual-app/api` and merely passes through us, so it cannot be OUR type, and a symbol
+ * survives being rethrown by `toolFactory` and `actualToolsManager` untouched.
+ */
+const INIT_FAILURE_BRAND = Symbol.for('actual-mcp.init-failure');
+/** Tag an error as having come from connection initialisation. Returns the same object. */
+export function markInitFailure(err) {
+    try {
+        if (err && (typeof err === 'object' || typeof err === 'function')) {
+            Object.defineProperty(err, INIT_FAILURE_BRAND, {
+                value: true,
+                enumerable: false, // never serialised into a response or a log line
+                configurable: true,
+            });
+        }
+    }
+    catch {
+        // A frozen or exotic error stays unbranded, which degrades to today's behaviour
+        // (the raw error propagates) rather than to a wrong sentence. Never let the mark
+        // itself become a failure path.
+    }
+    return err;
+}
+/**
+ * True only for an error raised while establishing the Actual connection.
+ *
+ * WALKS `cause`, because several adapter paths REWRAP an error into a new one with a friendlier
+ * message (`runQuery` and `bankSync` both do), and a rewrap that dropped the object would drop
+ * the brand with it, silently disabling #452 for exactly those tools. Those sites now pass the
+ * original as `cause`, so the mark survives one hop or many.
+ *
+ * Depth bounded, and cycle safe: an error whose `cause` points back at itself (or a long chain
+ * built by a retry wrapper) must not spin here. A diagnostic helper is never worth a hang.
+ */
+export function isInitFailure(err) {
+    let current = err;
+    const seen = new Set();
+    for (let depth = 0; depth < 10; depth++) {
+        if (!current || (typeof current !== 'object' && typeof current !== 'function'))
+            return false;
+        if (seen.has(current))
+            return false;
+        seen.add(current);
+        if (current[INIT_FAILURE_BRAND] === true)
+            return true;
+        current = current.cause;
+    }
+    return false;
+}