actual-mcp-server 0.21.0 → 0.22.1

package/README.md

@@ -781,7 +781,7 @@ The software is provided **as-is**, without warranty of any kind. The author acc
 
 ---
 
-**Version:** 0.21.0 | **Tool Count:** 81 (verified LibreChat-compatible)
+**Version:** 0.22.1 | **Tool Count:** 81 (verified LibreChat-compatible)
 
 ## Sponsor
 

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

@@ -12,6 +12,7 @@ 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';
@@ -388,13 +389,29 @@ export async function withActualApi(rawOperation) {
     // Denial here means the lock is never acquired and no upstream resource is
     // touched.
     _enforceBudgetAcl();
-    // #276: on the FIRST successful op, warn (once) if the Actual server version is outside
-    // the range this build supports. It runs inside the op while the connection is live and
-    // reuses it via rawGetServerVersion (NOT the withActualApi-wrapped getServerVersion, which
-    // would re-enter the lock). The once-guard flips its flag synchronously, so this never
-    // repeats per session or op. It is advisory: it never throws and never blocks the op.
-    const operation = async () => {
-        const result = await rawOperation();
+    // #276: on the FIRST successful op, warn (once) if the Actual server version is outside the
+    // range this build supports, reusing the live connection via rawGetServerVersion (NOT the
+    // withActualApi-wrapped getServerVersion, which would re-enter the lock).
+    //
+    // It runs AFTER withOpTimeout, not inside it. Review caught that bounding the probe was not
+    // enough while it still sat inside the operation's own timeout: its 5 seconds came out of the
+    // operation's 30, so an op that took more than ~25s and SUCCEEDED was still reported to the
+    // caller as "Actual API operation timed out", and on a deliberately lowered
+    // ACTUAL_OP_TIMEOUT_MS the probe alone could consume the entire budget. The timeout text is
+    // classed transient, so it would also drop the pooled connection. Still inside withApiLock,
+    // because it needs the connection the operation established.
+    //
+    // WHAT THIS DOES AND DOES NOT BUY, stated precisely because the first version of this comment
+    // overclaimed. The probe can no longer FAIL an operation that succeeded. It can still SLOW one,
+    // by up to SERVER_VERSION_PROBE_TIMEOUT_MS, and that bound is FIXED: it does not scale down
+    // with ACTUAL_OP_TIMEOUT_MS, so an operator who sets the 250ms floor for a fast-fail posture
+    // still pays up to ~5s of api-mutex hold against a stalled /info, and on the legacy path can
+    // pay it twice in one call (the pre-download site, then here). It is bounded and finite (at
+    // most MAX_PROBE_ATTEMPTS times per process, then never again), which is the trade being made:
+    // a diagnostic that is occasionally slow beats one that is silently disabled by a single
+    // transient failure, which is what the previous design did.
+    const runOperation = async () => {
+        const result = await withOpTimeout(rawOperation);
         await checkServerVersionOnce(() => rawGetServerVersion(), logger);
         return result;
     };
@@ -410,7 +427,7 @@ export async function withActualApi(rawOperation) {
                 // #390: verify the singleton holds THIS session's budget before the operation runs.
                 // Inside the lock, so no other session can change it in between.
                 await ensureLoadedBudgetMatchesSession();
-                return await withOpTimeout(operation);
+                return await runOperation();
             }
             catch (err) {
                 // Only drop the pool connection on errors that suggest the api
@@ -441,7 +458,7 @@ export async function withActualApi(rawOperation) {
         let forceFullShutdown = false;
         try {
             await initActualApiForOperation();
-            return await withOpTimeout(operation);
+            return await runOperation();
         }
         catch (err) {
             // #419: the stdio keep-alive branch leaves the singleton live; on an
@@ -628,7 +645,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 +682,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 +2713,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 +2852,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
     }
 }
 /**
@@ -2984,15 +3018,15 @@ export async function runBankSync(accountId) {
             const reset = error?.details?.rateLimitHeaders?.http_x_ratelimit_account_success_reset;
             const retryIn = reset ? ` Retry in ~${Math.ceil(Number(reset) / 60)} minute(s).` : '';
             throw new Error(`Bank sync failed: GoCardless rate limit exceeded for this account.${retryIn} ` +
-                `(NORDIGEN RATE_LIMIT_EXCEEDED — account success quota exhausted)`);
+                `(NORDIGEN RATE_LIMIT_EXCEEDED: account success quota exhausted)`);
         }
         if (error?.type === 'BankSyncError' ||
             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() {

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.
@@ -447,6 +449,39 @@ 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 the GUARD itself, not here. Review of the first version moved it: this runs
+    //     inside the process-global api mutex, so an unbounded advisory GET would stall every
+    //     session, and a bound each call site has to remember is one a call site will forget.
+    //   - ONCE per process ON SUCCESS, and the qualifier matters. The guard's latch is set only
+    //     when a version was actually READ (#453 review: latching on the attempt meant one failed
+    //     probe disabled the warning for the life of the process). It is shared with the post-op
+    //     call site in actual-adapter.ts, so on success whichever fires first wins and the other is
+    //     a no-op, and this one normally fires first, being earlier. On FAILURE both sites keep
+    //     retrying until MAX_PROBE_ATTEMPTS, so an unreachable /info costs up to three bounded
+    //     probes rather than one. That is the deliberate trade: a bounded, finite cost in exchange
+    //     for not being silenced by a single transient failure.
+    //
+    // `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(() => api
+        .getServerVersion(), log);
     try {
         await trackBudgetMutation(
         // #410: no redundant clear here any more. `trackBudgetMutation` owns the clear-before, and
@@ -467,10 +502,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,246 @@
+/**
+ * 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.
+        // `Object.hasOwn`, never a bare truthiness test on the lookup: these are object literals, so
+        // they inherit Object.prototype and an error carrying `code: 'constructor'` (or 'toString',
+        // 'valueOf') would match, returning a `cause` that is not an InitFailureCause and a sentence
+        // that is `undefined`. The stdio handler would then answer a tool call with
+        // `{ isError: true, content: [{ type: 'text', text: undefined }] }`. Pre-existing from #438,
+        // but #452 is what routes EVERY stdio tool error through here, so it is reachable now.
+        const code = typeof e?.code === 'string' ? e.code : undefined;
+        if (code && Object.hasOwn(REASON_TO_CAUSE, code))
+            return done(REASON_TO_CAUSE[code]);
+        if (code && Object.hasOwn(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 && Object.hasOwn(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 && Object.hasOwn(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;
+}

package/dist/src/lib/query-validator.js

@@ -5,12 +5,92 @@
  * to prevent server crashes from invalid table/field references.
  */
 import { getTableFields, getTableNames, isValidTable, isValidField, isValidJoinPath, } from './actual-schema.js';
+/**
+ * Blank the CONTENTS of quoted literals, keeping the quotes.
+ *
+ * #450 round 2: every extractor below scans for keywords (`FROM`, `JOIN`, `GROUP BY`,
+ * `ORDER BY`, `LIMIT`) and must not see one that lives inside a string value. Word boundaries
+ * fixed the column-name instance of that; they cannot fix the literal instance, which is both
+ * the same defect and far more reachable. Measured on v0.21.0, before this:
+ *
+ *   WHERE notes LIKE '%limit%' AND catgeory = 'groceries'   ACCEPTED, typo never validated
+ *   WHERE notes = 'order by z' AND made_up_col = 'x'        ACCEPTED
+ *   SELECT 'a from b', made_up_col FROM transactions        rejected as Table "b" does not exist
+ *   WHERE notes = 'join secrets'                            rejected as Table "secrets" does not exist
+ *
+ * The last two are FALSE REJECTIONS of legitimate queries, so this is not only a bypass fix.
+ *
+ * `validateQueryShape` has done exactly this since #162 for the same reason; extracting it
+ * here means the shape gate and the schema validator can never disagree about what is a
+ * literal. Lengths change, so never map an index from the blanked copy back onto the raw SQL.
+ * Nothing here does: the extractors read identifiers, which never live inside a literal.
+ */
+function blankStringLiterals(sql) {
+    // ONE left-to-right pass. The two obvious shortcuts are both wrong, and both were shipped
+    // and caught in review of the first attempt at this:
+    //
+    //   1. TWO INDEPENDENT REGEX PASSES (single quotes, then double quotes) let one pass match
+    //      ACROSS the other's literals. `WHERE notes = "it's" AND made_up_col = "don't"` had its
+    //      middle blanked by the single-quote pass, deleting `made_up_col` before the extractor
+    //      could see it. An apostrophe in a note search is ordinary input, not an edge case.
+    //   2. TREATING `\` AS AN ESCAPE. SQL escapes a quote by DOUBLING it, not with a backslash,
+    //      so in `'a\'` the literal ENDS at the second quote. Reading it as escaped swallowed the
+    //      rest of the clause, which both hid an unknown column from this validator and let
+    //      `'a\' ; DELETE FROM accounts; --'` past the #162 stacked-statement gate.
+    //
+    // So: whichever quote opens first wins, and it closes on the next matching quote unless that
+    // quote is doubled. Quotes are kept, contents are dropped.
+    let out = '';
+    let i = 0;
+    while (i < sql.length) {
+        const ch = sql[i];
+        if (ch !== "'" && ch !== '"') {
+            out += ch;
+            i++;
+            continue;
+        }
+        const quote = ch;
+        const quoteStart = i;
+        out += quote;
+        i++;
+        while (i < sql.length) {
+            if (sql[i] === quote) {
+                if (sql[i + 1] === quote) {
+                    i += 2; // a doubled quote is an escaped quote: still inside the literal
+                    continue;
+                }
+                break; // closing quote
+            }
+            i++; // literal content: dropped
+        }
+        if (i < sql.length) {
+            out += quote;
+            i++;
+        }
+        else {
+            // UNTERMINATED literal (no closing quote). The tail must stay VISIBLE, and this branch is
+            // the one that matters most: dropping it made `validateQueryShape` fail OPEN. Verified on
+            // the built module while it did:
+            //   WHERE notes = 'x ; DROP TABLE accounts     was rejected, became ACCEPTED
+            //   WHERE notes = 'x AND DELETE FROM accounts  was rejected, became ACCEPTED
+            // The regex this scanner replaced never matched an unterminated literal, so the tail
+            // stayed visible and the #162 gate still saw the stacked statement and the write keyword.
+            // Moving a security gate in the fail-open direction to tidy up a scanner is a bad trade,
+            // so the remainder is emitted RAW, exactly as the old behaviour left it.
+            out += sql.slice(quoteStart + 1);
+        }
+    }
+    return out;
+}
 /**
  * Extract table name from SQL query
  * Handles: FROM table, FROM table1, table2, JOIN table
  */
 function extractTableNames(sql) {
     const tables = new Set();
+    // #450: literals blanked first, so `WHERE notes = 'join secrets'` no longer reports
+    // `Table "secrets" does not exist` for a perfectly legitimate query.
+    sql = blankStringLiterals(sql);
     const normalized = sql.toUpperCase();
     // Extract FROM clause tables - handle queries without WHERE/ORDER/LIMIT
     const fromMatch = normalized.match(/FROM\s+(\w+)/i);
@@ -31,11 +111,19 @@ function extractTableNames(sql) {
 function extractSelectFields(sql) {
     const fields = [];
     // Handle SELECT *
+    // #450: see blankStringLiterals. A literal beginning with `from` truncated the clause and
+    // reported the literal's own words as a missing table.
+    sql = blankStringLiterals(sql);
     if (/SELECT\s+\*/i.test(sql)) {
         return [{ field: '*' }];
     }
-    // Extract SELECT clause
-    const selectMatch = sql.match(/SELECT\s+(.*?)\s+FROM/is);
+    // Extract SELECT clause.
+    // #450: `FROM` carries a trailing word boundary. Without it the lazy match terminates at the
+    // letters `from` inside any identifier, so `SELECT made_up_col AS from_x FROM accounts`
+    // truncated the clause to `made_up_col AS`, which fails the `^\w+$` test below and therefore
+    // extracted ZERO fields, skipping the allowlist loop entirely. Same defect class as the WHERE
+    // terminator below, reachable through an alias rather than a column name.
+    const selectMatch = sql.match(/SELECT\s+(.*?)\s+FROM\b/is);
     if (!selectMatch)
         return fields;
     const selectClause = selectMatch[1];
@@ -63,7 +151,22 @@ function extractSelectFields(sql) {
  */
 function extractWhereFields(sql) {
     const fields = [];
-    const whereMatch = sql.match(/WHERE\s+(.*?)(?:GROUP|ORDER|LIMIT|;|$)/is);
+    // #450: every keyword terminator carries word boundaries. Without them the lazy match cuts the
+    // clause at the first occurrence of the LETTERS `GROUP`, `ORDER` or `LIMIT` anywhere, including
+    // inside a column name, and every field after that point escaped schema validation silently.
+    // Reachable with columns this project's own schema defines: `sort_order` and `balance_limit`
+    // (accounts), `account_group_id` (accounts), and `group` (categories), which IS the keyword.
+    // The terminator anchors on the FULL two-word clause (`GROUP BY`, `ORDER BY`) rather than the bare
+    // keyword, because `group` is itself a column on `categories`: with word boundaries alone,
+    // `WHERE group = "x" AND bogus = "y"` still truncated to the empty string, since the column name
+    // and the keyword are the same token. `LIMIT` stays a single word because it is one in SQL too,
+    // and it is safe: no schema column is named exactly `limit`, and `balance_limit` has no word
+    // boundary before its `limit` (the preceding `_` is a word character).
+    // #450: literals blanked BEFORE the terminator match. Word boundaries alone left the whole
+    // bypass reachable through a string value, which is the likelier route by far: a search for
+    // notes containing the word "limit" truncated the clause and let every later field through.
+    sql = blankStringLiterals(sql);
+    const whereMatch = sql.match(/WHERE\s+(.*?)(?:\bGROUP\s+BY\b|\bORDER\s+BY\b|\bLIMIT\b|;|$)/is);
     if (!whereMatch)
         return fields;
     const whereClause = whereMatch[1];
@@ -248,9 +351,7 @@ export function formatValidationErrors(result) {
 export function validateQueryShape(query) {
     // Blank out single- and double-quoted literals (keep the quotes so positions
     // are roughly preserved, but drop their contents).
-    const stripped = query
-        .replace(/'(?:[^'\\]|\\.)*'/g, "''")
-        .replace(/"(?:[^"\\]|\\.)*"/g, '""');
+    const stripped = blankStringLiterals(query);
     // Stacked statements: a semicolon followed by more non-whitespace.
     if (/;\s*\S/.test(stripped)) {
         throw new Error('actual_query_run does not allow stacked statements (multiple statements separated by ";").');

package/dist/src/lib/server-version-guard.js

@@ -11,12 +11,19 @@
  *  - The comparator is PURE (no I/O, no logging), so its truth table is unit-testable.
  *  - It FAILS OPEN: an unparseable version produces no warning. A spurious warning on a
  *    healthy deployment would be worse than staying quiet.
- *  - The firing is a per-PROCESS once-guard: the flag is flipped SYNCHRONOUSLY before any
- *    await, so the check runs exactly once no matter how many ops or sessions occur, and it
- *    reuses the connection the triggering op already established (no extra auth burst,
- *    avoiding the #127/#134 class). There is NO boot-time probe: index.ts deliberately has
- *    no startup connection, and a naive boot call would double-init then be torn down by
- *    shutdownActualApi.
+ *  - The firing is a per-PROCESS once-guard ON SUCCESS, and the qualifier is #453's change:
+ *    `checked` is set only once a version has actually been READ, with `inFlight` providing the
+ *    concurrency property the old synchronous latch provided and `attempts` capping the retries
+ *    at MAX_PROBE_ATTEMPTS. A FAILING probe is therefore retried up to that cap instead of
+ *    silencing the warning for the life of the process, which is what the synchronous latch did
+ *    once the probe moved ahead of the first budget download. There are TWO call sites now: the
+ *    pre-download one in budgetLoader (which issues its own bounded /info read) and the original
+ *    post-op one in withActualApi (which reuses the connection the triggering op established, so
+ *    it adds no auth burst, avoiding the #127/#134 class). NEITHER call site bounds its reader:
+ *    the bound lives in `raceWithBound` below, deliberately, so the set of call sites cannot
+ *    matter. Do not delete it on the strength of a caller looking safe. There is still NO boot-time probe:
+ *    index.ts deliberately has no startup connection, and a naive boot call would double-init
+ *    then be torn down by shutdownActualApi.
  */
 import { SUPPORTED_ACTUAL_SERVER_RANGE } from './constants.js';
 import { INSTALLED_API_VERSION } from './installed-api-version.js';
@@ -77,10 +84,12 @@ export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANG
     // api patches, so comparing patches would be pure false-positive volume. It is
     // silent when equal and silent when the server is behind.
     //
-    // Scope, stated because it is narrower than it looks: this fires only when ops
-    // still SUCCEED, since the caller runs after a completed operation. A server so
-    // far ahead that budget download already fails never reaches it, and that case
-    // is #438's (surface the real session-init error) rather than this one's.
+    // Scope: this USED to fire only when ops still SUCCEEDED, because the only caller ran after a
+    // completed operation, so a server far enough ahead that the budget download already failed
+    // never reached it. #453 removed that limit by adding a call site BEFORE the download in
+    // loadBudgetTracked, which is the case this branch most wanted to reach. The verdict is
+    // unchanged; only WHEN it can be asked changed. #438 still owns surfacing the real error
+    // AFTER a failure; this warns before one.
     const bundled = parseVersion(bundledApi ?? '');
     if (bundled && (have[0] > bundled[0] || (have[0] === bundled[0] && have[1] > bundled[1]))) {
         return {
@@ -97,7 +106,63 @@ export function checkServerVersion(running, range = SUPPORTED_ACTUAL_SERVER_RANG
 // ---------------------------------------------------------------------------
 // Per-process once-guard.
 // ---------------------------------------------------------------------------
-let checked = false;
+/**
+ * How long a 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 threading through config.ts, .env.example and the README table (the config-drift guard
+ * enforces all three) to buy nothing. 5 seconds is far more than a healthy /info needs.
+ */
+export const SERVER_VERSION_PROBE_TIMEOUT_MS = 5000;
+let checked = false; // a version WAS read and judged: never check again
+let inFlight = false; // a check is running right now: a concurrent caller must not duplicate it
+let attempts = 0; // failed attempts, so an unreachable /info cannot be probed forever
+/** Failed probes tolerated before the check gives up for the process. */
+const MAX_PROBE_ATTEMPTS = 3;
+/**
+ * Bound the read WITHOUT importing `withOpTimeout`.
+ *
+ * The obvious implementation reuses that helper, and review caught what it drags in: `opTimeout`
+ * imports `config.ts`, which Zod-validates the environment AT MODULE LOAD and hard-exits when it
+ * is missing. That breaks this module's own design note, that the comparator is PURE and
+ * unit-testable without I/O, and it makes `tests/unit/server_version_guard.test.js` unable to
+ * load at all without an environment.
+ *
+ * ONE CORRECTION to how this was first justified, since a wrong reason in a comment outlives the
+ * observation that produced it: the original wording claimed the import turned the unit chain
+ * "red locally, green in CI". The chain ALREADY dies without env vars, earlier, at
+ * `config_https_validation.test.js`. So the import does not change what the chain does on a bare
+ * machine. The property is still worth enforcing (a pure comparator that any harness can import
+ * and test in isolation), the drama was not.
+ *
+ * So the bound is an inline race with a fixed constant, and this module keeps importing nothing
+ * but its two pure siblings. The timer is always cleared, so a fast read leaves nothing pending
+ * to hold the process open.
+ */
+async function raceWithBound(read) {
+    let timer;
+    try {
+        return await Promise.race([
+            read(),
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`server-version probe exceeded ${SERVER_VERSION_PROBE_TIMEOUT_MS}ms`)), SERVER_VERSION_PROBE_TIMEOUT_MS);
+                // NOT unref'd, and that is deliberate. `unref` was the first instinct ("never hold the
+                // process open for an advisory diagnostic") and it quietly breaks the bound: an unref'd
+                // timer does not keep the event loop alive, so in a process with nothing else pending
+                // Node exits before it fires and the race never rejects. The test that pins this bound
+                // caught exactly that, as an unsettled top-level await. A live server always has other
+                // work, so it would have fired there and the hazard would have stayed hidden.
+                //
+                // The cost of keeping it ref'd is bounded by construction: at most
+                // SERVER_VERSION_PROBE_TIMEOUT_MS, and the `finally` below clears it as soon as the read
+                // answers, so a healthy probe leaves nothing pending at all.
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
 /**
  * Run the compatibility check at most once per process. Call this from inside a successful
  * `withActualApi` operation (while the connection is live), passing a function that reads the
@@ -114,26 +179,58 @@ export async function checkServerVersionOnce(readVersion, log,
 // the process-global api mutex. Tests pass an explicit literal so no in-chain
 // assertion depends on what is installed (#321).
 bundledApi = INSTALLED_API_VERSION) {
-    if (checked)
+    if (checked || inFlight || attempts >= MAX_PROBE_ATTEMPTS)
         return;
-    checked = true; // set synchronously, before any await, so a concurrent op cannot double-fire
+    // #453 review: the latch used to be set here, synchronously, before the await. That was right
+    // while this ran only AFTER a successful operation. Once the probe moved BEFORE the first
+    // download it became the most failure-prone moment available (a slow or unreachable /info, or
+    // the op timeout firing), and a single failure then disabled the warning for the LIFETIME of
+    // the process, including #276's surviving post-op call site. The deployment that silenced it
+    // is precisely the one the guard exists for.
+    //
+    // THE BOUND IS APPLIED HERE, not by the caller. It started at the call sites and review was
+    // right that prose cannot hold it: `inFlight` is cleared in a `finally`, so a reader whose
+    // promise NEVER settles leaves it true for the life of the process and permanently disables the
+    // warning, which is the very failure this rework removed, just relocated. Bounding inside makes
+    // the set of call sites stop mattering, the same argument #393 used for the abandoned-load wait.
+    //
+    // So: `inFlight` keeps the concurrency property the synchronous latch was actually providing,
+    // `checked` is now set only once a version was really read and judged, and `attempts` bounds
+    // the retries so an unreachable server costs at most MAX_PROBE_ATTEMPTS extra /info calls per
+    // process rather than one per budget load.
+    inFlight = true;
     try {
-        const result = await readVersion();
+        const result = await raceWithBound(readVersion);
         if (!result || 'error' in result || typeof result.version !== 'string') {
+            attempts++;
             log.debug('[server-version] could not read the Actual server version; skipping the compatibility check');
             return;
         }
+        checked = true; // a real answer: this is the one and only judgement
         const verdict = checkServerVersion(result.version, SUPPORTED_ACTUAL_SERVER_RANGE, bundledApi);
         if (!verdict.ok && verdict.message) {
             log.warn(verdict.message);
         }
     }
-    catch {
+    catch (err) {
         // Advisory only: a failure to check must never surface as an error or affect the op.
-        log.debug('[server-version] compatibility check threw; ignored');
+        //
+        // NAME THE CAUSE. Once the bound moved inside this function, "probe exceeded 5000ms" became
+        // the most common way through here, and it is indistinguishable from `rawGetServerVersion`
+        // being undefined (it is destructured from `api as any` at module load, so an upstream build
+        // that stops exporting it throws a TypeError down this same path). An operator wondering why
+        // the compatibility warning never appears would have had nothing to go on.
+        attempts++;
+        const reason = err instanceof Error ? err.message : String(err);
+        log.debug(`[server-version] compatibility check failed; ignored: ${reason}`);
+    }
+    finally {
+        inFlight = false;
     }
 }
 /** Test-only: reset the once-guard between cases. */
 export function _resetForTests() {
     checked = false;
+    inFlight = false;
+    attempts = 0;
 }

package/dist/src/server/httpServer.js

@@ -25,97 +25,11 @@ import * as fs from 'node:fs';
 // `requestContext` from this module.
 import { requestContext } from '../lib/requestContext.js';
 import { buildToolListEntries } from '../lib/tool-list-entry.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.',
-    budget_not_found: 'The configured budget was not found on the Actual server. Check ACTUAL_BUDGET_SYNC_ID.',
-    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.',
-    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',
-};
-export function classifyInitFailure(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');
-        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');
-    }
-}
+// #438 / #452: the init-failure classifier now lives in src/lib/init-failure.ts so BOTH
+// transports can reach it (stdio could not, which was the whole of #452). Re-exported here
+// unchanged so existing importers and tests are unaffected.
+import { classifyInitFailure } from '../lib/init-failure.js';
+export { classifyInitFailure };
 export { requestContext };
 // Resolve the authenticated principal for the per-principal budget preference
 // (#189). OIDC: the verified JWT subject. Static-bearer: a single shared

package/dist/src/server/stdioServer.js

@@ -7,6 +7,83 @@ import logger from '../logger.js';
 import actualToolsManager from '../actualToolsManager.js';
 import { requestContext } from '../lib/requestContext.js';
 import { buildToolListEntries } from '../lib/tool-list-entry.js';
+import { classifyInitFailure, isInitFailure } from '../lib/init-failure.js';
+/**
+ * The stdio `tools/call` handler, built as a named factory so #452's error mapping can be driven
+ * by a unit test with a stubbed connection, instead of only by starting a real process against a
+ * real server. `startStdioServer` registers exactly this.
+ */
+export function createStdioCallToolHandler(mcp, stdioSessionId) {
+    return async (request) => {
+        const req = request;
+        const params = req?.params ?? {};
+        const rawName = params.name;
+        const args = params.arguments;
+        if (typeof rawName !== 'string') {
+            throw new Error('Tool name must be a string');
+        }
+        logger.debug(`[STDIO] tools/call ${rawName}`);
+        // Wrap the DISPATCH, not server.connect(). The transport invokes this handler
+        // from an I/O event, which is outside any scope established around connect(),
+        // so an AsyncLocalStorage context opened there would not be visible here.
+        // Everything downstream is awaited inside this callback, so it propagates.
+        //
+        // Only `sessionId` is placed in the store, deliberately:
+        //   - no `principal`, or getActiveBudgetConfig() would attempt the #189
+        //     preferred-budget restore for a caller that has no authenticated
+        //     identity, and the env default would stop being authoritative.
+        //   - `transport: 'stdio'` is what keeps stdio OFF the pooled path, and it
+        //     stays that way after #419. switchBudget's slow path calls
+        //     connectionPool.getConnection(), so WITHOUT this marker the first switch
+        //     would silently move stdio onto the pooled branch, and the entry would
+        //     never be touched (touch() is called only from httpServer.ts), so it
+        //     would expire after the idle timeout and be torn down by the cleanup
+        //     sweep without the api lock, possibly mid-operation. That is a far larger
+        //     change than we want by accident.
+        //     #419 solved the per-call upstream login WITHOUT pooling stdio: a stdio
+        //     process keeps the api singleton alive between ops in shutdownActualApi
+        //     (see _shouldKeepSingletonAlive), so the legacy branch's init no-ops
+        //     after the first login. No pool entry is created, so there is nothing for
+        //     the sweep to evict and this comment's hazard never arises.
+        //   - `allowedBudgets` is absent, so under AUTH_PROVIDER=oidc switchBudget
+        //     still denies. Fail closed: a local pipe must not gain budget access an
+        //     HTTP caller would need an ACL for.
+        try {
+            const result = await requestContext.run({ sessionId: stdioSessionId, transport: 'stdio' }, () => mcp.executeTool(rawName, args ?? {}));
+            return {
+                content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            // #452: give a FAILED CONNECTION the same named causes an HTTP client gets. Until this,
+            // stdio let the raw upstream sentence through, and for the #427 case that sentence
+            // ("Make sure you are using the latest version") names the wrong component: the user has
+            // already upgraded Actual, and the thing to upgrade is actual-mcp-server.
+            //
+            // GATED ON THE BRAND, never on the message. This catch sees EVERY tool error, and the
+            // classifier's last-resort branches match prose: a #270 op timeout would read as `timeout`
+            // and a #422 rate-limit as `auth_failed`, replacing a true message with a false one. Only an
+            // error marked by initActualApiForOperation is classified here. See src/lib/init-failure.ts.
+            if (isInitFailure(err)) {
+                const { cause, sentence } = classifyInitFailure(err);
+                if (cause !== 'unknown') {
+                    // stderr only: stdout is JSON-RPC framing (scripts/stdio-framing-check.mjs).
+                    logger.warn('[STDIO] tool call failed while establishing the Actual connection', {
+                        tool: rawName,
+                        cause,
+                    });
+                    // An MCP tool error, not a thrown exception, so the client renders the sentence as the
+                    // tool's result. The upstream string is deliberately dropped rather than appended: a
+                    // stdio tool error is handed to a cloud model, and #438's fixed-sentence contract exists
+                    // so no upstream stack, SQL, filesystem path or server URL has to be scrubbed correctly.
+                    // The raw error is still in the stderr log above the operator's own terminal.
+                    return { isError: true, content: [{ type: 'text', text: sentence }] };
+                }
+            }
+            throw err;
+        }
+    };
+}
 export async function startStdioServer(mcp, capabilities, implementedTools, serverDescription, serverInstructions, toolSchemas, version) {
     const toolsList = Array.isArray(implementedTools) ? implementedTools : [];
     // #348: a synthetic session identity for this stdio process.
@@ -45,45 +122,7 @@ export async function startStdioServer(mcp, capabilities, implementedTools, serv
         return { tools };
     });
     // Call tool handler — delegates to ActualMCPConnection.executeTool()
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const req = request;
-        const params = req?.params ?? {};
-        const rawName = params.name;
-        const args = params.arguments;
-        if (typeof rawName !== 'string') {
-            throw new Error('Tool name must be a string');
-        }
-        logger.debug(`[STDIO] tools/call ${rawName}`);
-        // Wrap the DISPATCH, not server.connect(). The transport invokes this handler
-        // from an I/O event, which is outside any scope established around connect(),
-        // so an AsyncLocalStorage context opened there would not be visible here.
-        // Everything downstream is awaited inside this callback, so it propagates.
-        //
-        // Only `sessionId` is placed in the store, deliberately:
-        //   - no `principal`, or getActiveBudgetConfig() would attempt the #189
-        //     preferred-budget restore for a caller that has no authenticated
-        //     identity, and the env default would stop being authoritative.
-        //   - `transport: 'stdio'` is what keeps stdio OFF the pooled path, and it
-        //     stays that way after #419. switchBudget's slow path calls
-        //     connectionPool.getConnection(), so WITHOUT this marker the first switch
-        //     would silently move stdio onto the pooled branch, and the entry would
-        //     never be touched (touch() is called only from httpServer.ts), so it
-        //     would expire after the idle timeout and be torn down by the cleanup
-        //     sweep without the api lock, possibly mid-operation. That is a far larger
-        //     change than we want by accident.
-        //     #419 solved the per-call upstream login WITHOUT pooling stdio: a stdio
-        //     process keeps the api singleton alive between ops in shutdownActualApi
-        //     (see _shouldKeepSingletonAlive), so the legacy branch's init no-ops
-        //     after the first login. No pool entry is created, so there is nothing for
-        //     the sweep to evict and this comment's hazard never arises.
-        //   - `allowedBudgets` is absent, so under AUTH_PROVIDER=oidc switchBudget
-        //     still denies. Fail closed: a local pipe must not gain budget access an
-        //     HTTP caller would need an ACL for.
-        const result = await requestContext.run({ sessionId: stdioSessionId, transport: 'stdio' }, () => mcp.executeTool(rawName, args ?? {}));
-        return {
-            content: [{ type: 'text', text: typeof result === 'string' ? result : JSON.stringify(result) }],
-        };
-    });
+    server.setRequestHandler(CallToolRequestSchema, createStdioCallToolHandler(mcp, stdioSessionId));
     const transport = new StdioServerTransport();
     // server.connect() calls transport.start() internally — do NOT call transport.start() manually
     await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "actual-mcp-server",
   "displayName": "Actual MCP Server",
-  "version": "0.21.0",
+  "version": "0.22.1",
   "engines": {
     "node": ">=22.0.0",
     "npm": ">=10.0.0"
@@ -30,7 +30,7 @@
     "verify-tools": "npm run build && node scripts/verify-tools.js",
     "check:coverage": "node scripts/list-actual-api-methods.mjs",
     "direct-sync": "node scripts/direct-sync/bank-sync-direct.mjs",
-    "test:unit-js": "node tests/unit/transactions_create.test.js && node tests/unit/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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/httpServer_init_failure_report.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/playwright_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/transactions_aggregate.test.js && node tests/unit/account_flow_summary.test.js && node tests/unit/recurring_expenses_summary.test.js && node tests/unit/generated_tools.smoke.test.js &&node tests/unit/schema_validation.test.js && node tests/unit/schema_json_openai_compat.test.js && node tests/unit/config_https_validation.test.js && node tests/unit/config_data_dir.test.js && node tests/unit/config_drift.test.js && node tests/unit/port_alignment.test.js && node tests/unit/dockerfile_data_dir_alignment.test.js && node tests/unit/unraid_template_alignment.test.js && node tests/unit/entrypoint_invariants.test.js && node tests/unit/e2e_spec_collection.test.js && node tests/unit/compose_profile_sync.test.js && node tests/unit/advertised_tools_sync.test.js && node tests/unit/new_tool_completeness.test.js && node tests/unit/knip_config.test.js && node tests/unit/readme_stats_sync.test.js && node tests/unit/config_insecure_upstream.test.js && node tests/unit/workflow_release_guards.test.js && node tests/unit/report_train_failure.test.js && node tests/unit/unit_chain_membership.test.js && node tests/unit/api_surface_drift.test.js && node tests/unit/write_effect_audit_staleness.test.js && node tests/unit/write_effect_audit_membership.test.js && node tests/unit/tool_annotations.test.js && node tests/unit/tool_id_schema_drift.test.js && node tests/unit/filter_id_resolution.test.js && node tests/unit/filter_id_tool_wiring.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/httpServer_init_failure_report.test.js && node tests/unit/stdio_init_failure_report.test.js && node tests/unit/manual_mcp_client_retry.test.js && node tests/unit/manual_mcp_client_session.test.js && node tests/unit/manual_mcp_client_circuit.test.js && node tests/unit/manual_runner_killswitch.test.js && node tests/unit/adapter_auth_rate_limit.test.js && node tests/unit/adapter_session_reuse.test.js && node tests/unit/retry_classifier.test.js && node tests/unit/adapter_module_surface.test.js && node tests/unit/adapter_nonidempotent_no_retry.test.js && node tests/unit/pool_liveness.test.js && node tests/unit/pool_shutdown_all.test.js && node tests/unit/query_where_operators.test.js && node tests/unit/query_run_validation.test.js && node tests/unit/adapter_with_write_session.test.js && node tests/unit/category_groups_delete.test.js && node tests/unit/rules_delete.test.js && node tests/unit/schedules_delete.test.js && node tests/unit/accounts_delete.test.js && node tests/unit/update_tools_not_found.test.js && node tests/unit/accounts_close.test.js && node tests/unit/accounts_reopen.test.js && node tests/unit/payees_delete.test.js && node tests/unit/payees_merge.test.js && node tests/unit/rules_create_or_update.test.js && node tests/unit/unhandled-rejection.test.js && node tests/unit/rejection-allowlist-purity.test.js && node tests/unit/httpServer_bearer_auth.test.js && node tests/unit/httpServer_oidc_audience.test.js && node tests/unit/httpServer_oidc_auth_verification.test.js && node tests/unit/httpServer_oidc_jwks_discovery.test.js && node tests/unit/httpServer_body_limit.test.js && node tests/unit/httpServer_bind_host.test.js && node tests/unit/adapter_write_pool_cooperation.test.js && node tests/unit/adapter_drain_listing_cache.test.js && node tests/unit/budget_acl_enforcement.test.js && node tests/unit/budget_selection_precondition.test.js && node tests/unit/budget_load_abandonment.test.js && node tests/unit/budget_loader_postcondition.test.js && node tests/unit/budget_loader_import_allowlist.test.js && node tests/unit/budget_import_tracking.test.js && node tests/unit/pool_shutdown_under_lock.test.js && node tests/unit/api_lock_affinity.test.js && node tests/unit/commit_message_closing_keyword.test.js && node tests/unit/write_queue_stranding.test.js && node tests/unit/write_queue_stranded_bound.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/playwright_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/server_version_probe_outside_op_timeout.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",