cbrowser 18.72.5 → 18.73.0

package/dist/mcp-server-remote.d.ts

@@ -6,6 +6,7 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { CBrowser } from "./browser.js";
+import type { PricingTier } from "./mcp-tools/tool-categories.js";
 import type { ToolRegistrationContext } from "./mcp-tools/types.js";
 /**
  * Generate a short browser token that maps to a session's browser.
@@ -19,6 +20,50 @@ export declare function getBrowserByToken(token?: string): Promise<{
     browser: CBrowser;
     token: string;
 }>;
+/**
+ * Verdict for an account key. Separates IDENTITY ("is this a real key?") from
+ * PRICING ("what plan is it on?"). Those were the same question until 2026-07-26,
+ * and conflating them was a complete authentication bypass — see validateAccountKey.
+ */
+export type KeyVerdict = {
+    valid: true;
+    tier: PricingTier;
+} | {
+    valid: false;
+    reason: "unknown_key" | "backend_unreachable" | "not_an_account_key";
+};
+/**
+ * Test seam — drop cached tier entries.
+ *
+ * Exists so the revocation-eviction path can be exercised without a 30-second
+ * sleep. Note the accepted consequence it makes visible: while a cache entry is
+ * fresh, `validateAccountKey` returns before asking the CMS, so a revoked key
+ * keeps working for up to TIER_CACHE_TTL_MS. That bounded delay is deliberate;
+ * the invariant that matters is that once the CMS SAYS invalid, the entry is
+ * evicted and the outage grace can never resurrect it.
+ */
+export declare function _clearTierCache(): void;
+export declare function validateAccountKey(apiKey: string, deps?: {
+    fetch?: typeof fetch;
+    cmsUrl?: string;
+}): Promise<KeyVerdict>;
+/**
+ * Start the server's background timers.
+ *
+ * Both of these used to run at MODULE SCOPE, so merely IMPORTING this file
+ * started them — including the session reaper, which closes browsers and
+ * SIGKILLs Chrome pids every 30 seconds. A unit test importing the module for a
+ * single exported function therefore got a Chrome-killing reaper running inside
+ * its own process for the rest of the suite. That is how a 267s test run became
+ * 438s with intermittent 180s browser timeouts: the reaper was reaping other
+ * tests' browsers, and whichever browser-heavy test was unlucky absorbed it.
+ * (Diagnosed 2026-07-27 by bisecting a clean 556-pass/0-fail baseline.)
+ *
+ * A library module must not start lifecycle timers on import. Both handles are
+ * unref'd so they can never hold the event loop open on their own, and the
+ * function is idempotent so repeated calls are harmless.
+ */
+export declare function startBackgroundTimers(): void;
 /**
  * Options for starting the remote MCP server
  */

package/dist/mcp-server-remote.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server-remote.d.ts","sourceRoot":"","sources":["../src/mcp-server-remote.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAmCH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAkBxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAoBpE;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCrG;AA6iCD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9F;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAGD,YAAY,EAAE,uBAAuB,EAAE,CAAC;AAExC;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAs2B1F"}
+{"version":3,"file":"mcp-server-remote.d.ts","sourceRoot":"","sources":["../src/mcp-server-remote.ts"],"names":[],"mappings":";AACA;;;;GAIG;AAmCH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAiBxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAoBpE;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCrG;AAmhBD;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAClB;IAAE,KAAK,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAClC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,GAAG,qBAAqB,GAAG,oBAAoB,CAAA;CAAE,CAAC;AA2C3F;;;;;;;;;GASG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAWD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,OAAO,CAAC,UAAU,CAAC,CAuDrB;AAsJD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAS5C;AAseD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,uBAAuB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9F;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAGD,YAAY,EAAE,uBAAuB,EAAE,CAAC;AAExC;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CA24B1F"}

package/dist/mcp-server-remote.js

@@ -46,7 +46,7 @@ import { VERSION } from "./version.js";
 // getActiveKeyHash is deliberately no longer imported: billing identity is per-request
 // (see resolveRequestKeyHash). setActiveKeyHash stays for the usage-logging path, which
 // is per-session rather than per-charge.
-import { registerAllPublicTools, setRemoteMode, setActiveTier as setTierGate, setActiveKeyHash } from "./mcp-tools/index.js";
+import { registerAllPublicTools, setRemoteMode, setActiveTier as setTierGate, setActiveKeyHash, isToolAccessible, upgradePrompt } from "./mcp-tools/index.js";
 // Shared browser instance (single Chromium process)
 let browser = null;
 // Stealth state (enterprise integration)
@@ -322,7 +322,9 @@ async function killOrphanedChromeProcesses() {
  * Periodic cleanup of idle sessions, memory hogs, expired session tracking,
  * and orphaned Chrome processes.
  */
-setInterval(async () => {
+let sessionCleanupTimer = null;
+let rateLimitCleanupTimer = null;
+const makeSessionCleanupTimer = () => setInterval(async () => {
     const now = Date.now();
     // Clean up expired session tracking (older than retention period)
     for (const [sessionId, info] of expiredSessions) {
@@ -412,12 +414,34 @@ async function validateAuth0Token(token) {
         return payload;
     }
     catch (jwtError) {
-        // If JWT validation fails, try opaque token validation via userinfo
+        // Opaque-token fallback via /userinfo — OFF by default since 2026-07-26.
+        //
+        // The JWT branch above validates `audience`. This one structurally cannot:
+        // /userinfo answers 200 for ANY access token the tenant issued, for any
+        // application in it, and returns no audience to check. So it authenticated
+        // tokens minted for a different app in the same tenant with zero CMS
+        // involvement — the one remaining route to valid:true that the account-key
+        // fix did not touch.
+        //
+        // Defaulting it off is reasoned, not cautious-by-reflex: Auth0 issues an
+        // OPAQUE token precisely when no audience was requested, which is exactly the
+        // case the audience check exists to reject. And cbrowser's own OAuth flow
+        // hands out `cbk_` keys as access tokens, so real customers take the
+        // account-key path and are unaffected. AUTH0_ALLOW_OPAQUE_TOKENS=true
+        // restores the old behaviour if some integration turns out to need it, and
+        // the rejection is logged either way so it is diagnosable, not mysterious.
+        if (process.env.AUTH0_ALLOW_OPAQUE_TOKENS !== "true") {
+            console.error("[Auth0] Rejected an opaque access token: /userinfo exposes no audience to verify. Set AUTH0_ALLOW_OPAQUE_TOKENS=true to permit it.");
+            return null;
+        }
         try {
             const userinfoResponse = await fetch(`https://${auth0.domain}/userinfo`, {
                 headers: {
                     Authorization: `Bearer ${token}`,
                 },
+                // Attacker-triggered outbound request on a pre-auth path: it must not be
+                // able to hold the request open indefinitely.
+                signal: AbortSignal.timeout(AUTH_BACKEND_TIMEOUT_MS),
             });
             if (userinfoResponse.ok) {
                 const userinfo = await userinfoResponse.json();
@@ -426,10 +450,11 @@ async function validateAuth0Token(token) {
                     email: userinfo.email,
                     name: userinfo.name,
                 };
-                // Cache opaque tokens for 30 minutes
+                // 5 minutes, not 30: an opaque token carries no readable expiry, so a
+                // long cache means a revoked token keeps working for that whole window.
                 tokenCache.set(token, {
                     payload,
-                    expiry: Date.now() + 30 * 60 * 1000 - TOKEN_CACHE_MARGIN,
+                    expiry: Date.now() + 5 * 60 * 1000 - TOKEN_CACHE_MARGIN,
                 });
                 return payload;
             }
@@ -503,6 +528,10 @@ const tokenToKeyHash = new Map();
  * cache is a micro-optimisation and a short window costs almost nothing.
  */
 const tierCache = new Map();
+/** Pre-auth request bodies are capped; see the read loop in handleMcpRequest. */
+const MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024;
+/** Bound the CMS deduct call; an unanswered one used to hang the whole request. */
+const CREDIT_DEDUCT_TIMEOUT_MS = 5_000;
 const TIER_CACHE_TTL_MS = 30 * 1000;
 /**
  * Extract the raw API key from an incoming HTTP request.
@@ -542,10 +571,131 @@ async function resolveRequestKeyHash(req) {
         return mapped.keyHash;
     return null;
 }
+/**
+ * Validate an account key against the CMS and report BOTH validity and tier.
+ *
+ * Why this exists (2026-07-26): `validateAuth` used to authenticate with
+ *
+ *     const tier = await resolveApiKeyTier(rawKey);
+ *     if (tier) return { valid: true };
+ *
+ * and `resolveApiKeyTier` returns the string "free" on every failure path — CMS
+ * says the key is unknown, CMS returns non-2xx, CMS is unreachable. "free" is
+ * truthy, so EVERY `cbk_`-prefixed string authenticated, and the `valid: false`
+ * line below that call was unreachable code. Probed live on 2026-07-26:
+ * Verified live before the fix: a syntactically well-formed account key that the
+ * backend did not recognise was nonetheless authenticated, while tokens without
+ * the account-key prefix were correctly rejected. The prefix was the entire
+ * check. (Reproduction detail withheld until the fix is published and adopted.)
+ *
+ * The failure branches are enumerated explicitly rather than collapsed into a
+ * catch-all, because a catch-all here is precisely what failed open:
+ *   - CMS answers, key unknown      -> unknown_key         (reject)
+ *   - CMS answers non-2xx           -> backend_unreachable (reject, do not guess)
+ *   - CMS unreachable / throws      -> backend_unreachable (reject; a CMS outage
+ *                                      must stop auth, not open it)
+ * Only an explicit `valid: true` from the CMS authenticates.
+ */
+/** How long to wait on the CMS before treating it as unreachable. */
+const AUTH_BACKEND_TIMEOUT_MS = 3_000;
+/**
+ * How long past its TTL a previously-validated key may be served when the CMS
+ * cannot be reached.
+ *
+ * Without this, failing closed turns a routine 40-second CMS redeploy into a
+ * total auth outage for every MCP user, because a cache entry can only be
+ * created by a live success. This does NOT reopen the bypass: the entry cannot
+ * exist unless the CMS once answered `valid: true` for that exact key in this
+ * process. It converts a hard outage into a bounded revocation delay, and an
+ * explicit "invalid" answer still evicts immediately.
+ */
+const AUTH_STALE_GRACE_MS = 5 * 60_000;
+/**
+ * Test seam — drop cached tier entries.
+ *
+ * Exists so the revocation-eviction path can be exercised without a 30-second
+ * sleep. Note the accepted consequence it makes visible: while a cache entry is
+ * fresh, `validateAccountKey` returns before asking the CMS, so a revoked key
+ * keeps working for up to TIER_CACHE_TTL_MS. That bounded delay is deliberate;
+ * the invariant that matters is that once the CMS SAYS invalid, the entry is
+ * evicted and the outage grace can never resurrect it.
+ */
+export function _clearTierCache() {
+    tierCache.clear();
+}
+/** Serve a previously-validated key during a backend outage, or reject. */
+function staleServe(keyHash) {
+    const cached = tierCache.get(keyHash);
+    if (cached && cached.expiresAt + AUTH_STALE_GRACE_MS > Date.now()) {
+        return { valid: true, tier: cached.tier };
+    }
+    return { valid: false, reason: "backend_unreachable" };
+}
+export async function validateAccountKey(apiKey, deps = {}) {
+    if (!apiKey.startsWith("cbk_"))
+        return { valid: false, reason: "not_an_account_key" };
+    const { createHash } = await import("crypto");
+    const keyHash = createHash("sha256").update(apiKey).digest("hex").slice(0, 16);
+    const cached = tierCache.get(keyHash);
+    if (cached && cached.expiresAt > Date.now())
+        return { valid: true, tier: cached.tier };
+    const doFetch = deps.fetch ?? fetch;
+    const cmsUrl = deps.cmsUrl ?? process.env.CMS_URL ?? "http://localhost:3200";
+    let res;
+    try {
+        // A timeout is not optional here. Without one, a CMS whose event loop is
+        // blocked (a long SQLite write, a wedged worker) accepts the connection and
+        // never answers, so EVERY MCP request hangs at auth instead of returning a
+        // clean 401. A hang is worse than either the bypass or the rejection,
+        // because clients retry and pile up. (2026-07-26, cross-vendor audit.)
+        res = await doFetch(`${cmsUrl}/api/accounts/validate-key`, {
+            headers: { "X-API-Key": apiKey },
+            signal: AbortSignal.timeout(AUTH_BACKEND_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return staleServe(keyHash);
+    }
+    // The CMS answers an unknown or revoked key with 401 (and a missing one with
+    // 400) — NOT 200-with-valid:false. Verified against
+    // cbrowser-web/cms/routes/accounts.ts:403. Those are explicit answers, so they
+    // must evict and reject, never route to the outage grace: mapping a 401 to
+    // "backend unreachable" would let a key revoked seconds ago ride the 5-minute
+    // stale-serve window. Only 5xx and transport failures are genuine outages.
+    // (2026-07-26, caught by probing the live CMS after the deploy rather than
+    // trusting the shape the fix assumed.)
+    if (res.status === 400 || res.status === 401 || res.status === 403) {
+        tierCache.delete(keyHash);
+        return { valid: false, reason: "unknown_key" };
+    }
+    if (!res.ok)
+        return staleServe(keyHash);
+    let data;
+    try {
+        data = await res.json();
+    }
+    catch {
+        return staleServe(keyHash);
+    }
+    // An explicit "this key is not valid" is a DIFFERENT answer from "I could not
+    // ask" — it must never fall through to the stale-serve grace, or a revoked key
+    // would keep working for the whole grace window.
+    if (data.valid !== true) {
+        tierCache.delete(keyHash);
+        return { valid: false, reason: "unknown_key" };
+    }
+    const tier = data.tier || "free";
+    tierCache.set(keyHash, { tier, expiresAt: Date.now() + TIER_CACHE_TTL_MS });
+    return { valid: true, tier };
+}
 /**
  * Resolve the pricing tier for an API key by calling the CMS backend.
  * Returns null for non-cbk keys (server admin keys pass through as-is).
  * Caches results for 5 minutes.
+ *
+ * PRICING ONLY. This runs AFTER authentication has already succeeded, so its
+ * "free" fallback is a safe-by-default *billing* decision. It must never be used
+ * to decide whether a caller is authenticated — use validateAccountKey for that.
  */
 async function resolveApiKeyTier(apiKey) {
     // Only resolve cbk_ keys (user account keys)
@@ -656,7 +806,7 @@ function checkRateLimit(req, tier) {
     return { allowed: true, remaining: remaining - 1, resetTime, limit: limits.requests };
 }
 // Cleanup old rate limit entries every 10 minutes
-setInterval(() => {
+const makeRateLimitCleanupTimer = () => setInterval(() => {
     const now = Date.now();
     for (const [key, entry] of rateLimitStore.entries()) {
         entry.requests = entry.requests.filter(t => t > now - RATE_LIMIT_WINDOW_MS);
@@ -665,6 +815,32 @@ setInterval(() => {
         }
     }
 }, 10 * 60 * 1000);
+/**
+ * Start the server's background timers.
+ *
+ * Both of these used to run at MODULE SCOPE, so merely IMPORTING this file
+ * started them — including the session reaper, which closes browsers and
+ * SIGKILLs Chrome pids every 30 seconds. A unit test importing the module for a
+ * single exported function therefore got a Chrome-killing reaper running inside
+ * its own process for the rest of the suite. That is how a 267s test run became
+ * 438s with intermittent 180s browser timeouts: the reaper was reaping other
+ * tests' browsers, and whichever browser-heavy test was unlucky absorbed it.
+ * (Diagnosed 2026-07-27 by bisecting a clean 556-pass/0-fail baseline.)
+ *
+ * A library module must not start lifecycle timers on import. Both handles are
+ * unref'd so they can never hold the event loop open on their own, and the
+ * function is idempotent so repeated calls are harmless.
+ */
+export function startBackgroundTimers() {
+    if (!sessionCleanupTimer) {
+        sessionCleanupTimer = makeSessionCleanupTimer();
+        sessionCleanupTimer.unref();
+    }
+    if (!rateLimitCleanupTimer) {
+        rateLimitCleanupTimer = makeRateLimitCleanupTimer();
+        rateLimitCleanupTimer.unref();
+    }
+}
 async function validateAuth(req, apiKeys, auth0Enabled) {
     // Try static API key first (fastest — for admin/server keys)
     if (apiKeys && validateApiKey(req, apiKeys)) {
@@ -673,10 +849,15 @@ async function validateAuth(req, apiKeys, auth0Enabled) {
     // Try cbk_ account key (validates against CMS)
     const rawKey = extractApiKey(req);
     if (rawKey?.startsWith("cbk_")) {
-        const tier = await resolveApiKeyTier(rawKey);
-        if (tier)
+        const verdict = await validateAccountKey(rawKey);
+        if (verdict.valid)
             return { valid: true };
-        return { valid: false, reason: "Invalid or expired API key" };
+        return {
+            valid: false,
+            reason: verdict.reason === "backend_unreachable"
+                ? "Authentication backend is unavailable — try again shortly."
+                : "Invalid or expired API key",
+        };
     }
     // Try Auth0 / OAuth token (includes tokens from our /authorize flow)
     const authHeader = req.headers.authorization;
@@ -684,10 +865,15 @@ async function validateAuth(req, apiKeys, auth0Enabled) {
         const token = authHeader.slice(7);
         // Check if it's a cbk_ key returned by our OAuth flow
         if (token.startsWith("cbk_")) {
-            const tier = await resolveApiKeyTier(token);
-            if (tier)
+            const verdict = await validateAccountKey(token);
+            if (verdict.valid)
                 return { valid: true };
-            return { valid: false, reason: "Invalid or expired API key" };
+            return {
+                valid: false,
+                reason: verdict.reason === "backend_unreachable"
+                    ? "Authentication backend is unavailable — try again shortly."
+                    : "Invalid or expired API key",
+            };
         }
         // Try Auth0 if enabled
         if (auth0Enabled) {
@@ -878,10 +1064,28 @@ async function handleMcpRequest(req, res, transport) {
     }
     // Parse body for POST requests
     if (req.method === "POST") {
+        // Cap the body. This read happens BEFORE authentication, so an unauthenticated
+        // POST to /mcp with a multi-gigabyte body was buffered into memory in full
+        // before anything looked at its size — and after the auth fix it is the path
+        // every REJECTED key walks down, which makes it the cheapest way to hurt the
+        // box. 4MB is far above any real JSON-RPC payload. (2026-07-26)
         const chunks = [];
+        let received = 0;
+        let tooLarge = false;
         for await (const chunk of req) {
+            received += chunk.length;
+            if (received > MAX_REQUEST_BODY_BYTES) {
+                tooLarge = true;
+                break;
+            }
             chunks.push(chunk);
         }
+        if (tooLarge) {
+            req.destroy();
+            res.writeHead(413, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Payload Too Large", message: `Request body exceeds ${MAX_REQUEST_BODY_BYTES} bytes.` }));
+            return;
+        }
         const body = Buffer.concat(chunks).toString("utf-8");
         // Safely parse JSON - reject malformed requests gracefully
         let parsedBody;
@@ -914,6 +1118,25 @@ async function handleMcpRequest(req, res, transport) {
             const targetUrl = (toolArgs?.url || (Array.isArray(toolArgs?.sites) ? toolArgs.sites[0] : "") || "");
             // Derived from THIS request, not from the module global — see resolveRequestKeyHash.
             const keyHash = await resolveRequestKeyHash(req);
+            // GATE BEFORE CHARGE. The CMS credit catalog and the package's tier catalog
+            // are two independent lists, and they disagree: CMS lists
+            // agent_ready_audit as a free-tier tool costing 5 credits, while the
+            // package gates it as "pro". A free account with credits was therefore
+            // debited 5 and then handed the upgrade prompt that createGatedServer had
+            // substituted for the handler — paying for an advertisement. Checking
+            // accessibility BEFORE the deduct fixes every present and future
+            // disagreement between the two lists, not just the one instance we found.
+            // (2026-07-26)
+            if (keyHash && !isToolAccessible(toolName)) {
+                console.log(`[Credits] ${toolName}: unavailable at this tier — upgrade prompt returned WITHOUT charging`);
+                res.writeHead(200, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    jsonrpc: "2.0",
+                    id: parsedBody?.id ?? null,
+                    result: upgradePrompt(toolName),
+                }));
+                return;
+            }
             if (keyHash) {
                 const cmsUrl = process.env.CMS_URL || "http://localhost:3200";
                 const deductParams = new URLSearchParams({
@@ -928,8 +1151,20 @@ async function handleMcpRequest(req, res, transport) {
                         // Omitting it made the CMS return 403 → parsed as {allowed: undefined} →
                         // every tool call denied ("Tool execution denied", reason undefined).
                         headers: { "X-Internal-Secret": process.env.CMS_INTERNAL_SECRET || "" },
+                        // Without this, a CMS that accepts the connection and never answers
+                        // hangs the MCP request forever, before the handler is ever reached.
+                        signal: AbortSignal.timeout(CREDIT_DEDUCT_TIMEOUT_MS),
                     });
-                    if (creditRes.ok || creditRes.status === 402 || creditRes.status === 403) {
+                    // Every status must land in a branch. Previously anything outside
+                    // {ok, 402, 403} — a 500, or an nginx 502 during a CMS restart — fell
+                    // straight through to execution with NO LOG LINE AT ALL, because the
+                    // deliberate loud fail-open message below only fires on a THROWN fetch.
+                    // That is the most likely outage shape, and it was the one shape that
+                    // stayed invisible, which defeats the point of the loud message.
+                    if (!(creditRes.ok || creditRes.status === 402 || creditRes.status === 403)) {
+                        console.warn(`[Credits] FAIL-OPEN: ${toolName} ran unbilled — CMS returned HTTP ${creditRes.status}`);
+                    }
+                    else if (creditRes.ok || creditRes.status === 402 || creditRes.status === 403) {
                         const data = await creditRes.json();
                         // Only deny on an EXPLICIT allowed:false from the deduct endpoint.
                         // A missing `allowed` field means the response was not a real deduct
@@ -1033,6 +1268,10 @@ async function handleMcpRequest(req, res, transport) {
 export async function startRemoteMcpServer(options) {
     // Auto-initialize all data directories on server start
     ensureDirectories();
+    // Session reaper + rate-limit sweeper. Started HERE rather than at module
+    // import, so loading this file no longer spins up a Chrome-killing reaper in
+    // whatever process happened to import it. See startBackgroundTimers.
+    startBackgroundTimers();
     // Enable remote mode for screenshot handling (returns base64 images instead of paths)
     setRemoteMode(true);
     const port = parseInt(process.env.PORT || "3000", 10);
@@ -1788,51 +2027,81 @@ ${VERSION}
         res.end(JSON.stringify({ error: "Not found" }));
     });
     httpServer.listen(port, host, () => {
-        console.log(`\nCognitive Browser Remote MCP Server running at http://${host}:${port}`);
-        console.log(`\nEndpoints:`);
-        console.log(`  MCP:      http://${host}:${port}/mcp`);
-        console.log(`  Health:   http://${host}:${port}/health`);
-        console.log(`  Info:     http://${host}:${port}/info`);
-        if (auth0Enabled) {
-            console.log(`  OAuth:    http://${host}:${port}/.well-known/oauth-protected-resource`);
-        }
-        if (authEnabled) {
-            console.log(`\nAuthentication:`);
-            if (apiKeyAuthEnabled) {
-                console.log(`  API Key:  Authorization: Bearer <your-api-key>`);
-                console.log(`            X-API-Key: <your-api-key>`);
+        void (async () => {
+            console.log(`\nCognitive Browser Remote MCP Server running at http://${host}:${port}`);
+            console.log(`\nEndpoints:`);
+            console.log(`  MCP:      http://${host}:${port}/mcp`);
+            console.log(`  Health:   http://${host}:${port}/health`);
+            console.log(`  Info:     http://${host}:${port}/info`);
+            if (auth0Enabled) {
+                console.log(`  OAuth:    http://${host}:${port}/.well-known/oauth-protected-resource`);
             }
+            if (authEnabled) {
+                console.log(`\nAuthentication:`);
+                if (apiKeyAuthEnabled) {
+                    console.log(`  API Key:  Authorization: Bearer <your-api-key>`);
+                    console.log(`            X-API-Key: <your-api-key>`);
+                }
+                if (auth0Enabled) {
+                    console.log(`  OAuth:    Authorization: Bearer <jwt-token>`);
+                    console.log(`            Auth0 Domain: ${auth0?.domain}`);
+                }
+            }
+            console.log(`\nFor claude.ai custom connector:`);
+            console.log(`  URL: http://${host}:${port}/mcp`);
             if (auth0Enabled) {
-                console.log(`  OAuth:    Authorization: Bearer <jwt-token>`);
-                console.log(`            Auth0 Domain: ${auth0?.domain}`);
+                console.log(`  OAuth metadata: http://${host}:${port}/.well-known/oauth-protected-resource`);
             }
-        }
-        console.log(`\nFor claude.ai custom connector:`);
-        console.log(`  URL: http://${host}:${port}/mcp`);
-        if (auth0Enabled) {
-            console.log(`  OAuth metadata: http://${host}:${port}/.well-known/oauth-protected-resource`);
-        }
-        // Cache tool manifest for unauthenticated tools/list (discovery surface is public).
-        // Create a temporary server to extract the registered tool list directly.
-        // Tool registration works without a browser — only tool execution needs one.
-        try {
-            const dummyContext = { getBrowser: () => null };
-            const tempServer = createMcpServer(options?.registerTools, "manifest-cache", null);
-            const toolMap = tempServer._registeredTools;
-            if (toolMap && typeof toolMap === "object") {
-                cachedToolManifest = Object.entries(toolMap)
-                    .filter(([, tool]) => tool.enabled !== false)
-                    .map(([name, tool]) => ({
-                    name,
-                    description: tool.description || "",
-                    inputSchema: tool.inputSchema || { type: "object" },
-                }));
-                console.log(`[tools/list] Public manifest cached: ${cachedToolManifest.length} tools`);
+            // Cache tool manifest for unauthenticated tools/list (discovery surface is public).
+            // Create a temporary server to extract the registered tool list directly.
+            // Tool registration works without a browser — only tool execution needs one.
+            try {
+                const dummyContext = { getBrowser: () => null };
+                const tempServer = createMcpServer(options?.registerTools, "manifest-cache", null);
+                // Ask the server for its tool list the way a client does, rather than
+                // reading `_registeredTools` and publishing `tool.inputSchema` directly.
+                //
+                // That internal field holds the ZodRawShape/ZodObject, NOT JSON Schema —
+                // the SDK converts it only while serving tools/list. Publishing it raw put
+                // Zod internals (`_def`, `~standard`, `_cached`) on the wire for every tool
+                // whose schema is a ZodObject: measured 17 of 122 on demo and 14 of 125 on
+                // enterprise. Because this manifest serves the UNAUTHENTICATED tools/list,
+                // that was the first thing any prospective MCP client saw, while
+                // authenticated clients got correct schemas from the SDK's own path — two
+                // sources of truth for one contract, and the public one was the broken one.
+                //
+                // Driving the real handler means the public manifest cannot diverge from
+                // the authenticated one again, because it is now the same code path.
+                // (2026-07-26)
+                const { InMemoryTransport } = await import("@modelcontextprotocol/sdk/inMemory.js");
+                const { Client } = await import("@modelcontextprotocol/sdk/client/index.js");
+                const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+                const manifestClient = new Client({ name: "manifest-cache", version: "1" });
+                await Promise.all([
+                    tempServer.connect(serverTransport),
+                    manifestClient.connect(clientTransport),
+                ]);
+                const listed = await manifestClient.listTools();
+                await manifestClient.close();
+                if (listed?.tools?.length) {
+                    cachedToolManifest = listed.tools.map((tool) => ({
+                        name: tool.name,
+                        description: tool.description || "",
+                        inputSchema: tool.inputSchema || { type: "object" },
+                    }));
+                    const malformed = cachedToolManifest.filter((t) => !t.inputSchema || typeof t.inputSchema !== "object"
+                        || t.inputSchema.type !== "object");
+                    console.log(`[tools/list] Public manifest cached: ${cachedToolManifest.length} tools`);
+                    if (malformed.length) {
+                        // Loud, because a silently malformed public contract is what this fix replaced.
+                        console.error(`[tools/list] WARNING: ${malformed.length} tool(s) have a non-JSON-Schema inputSchema: ${malformed.map((t) => t.name).join(", ")}`);
+                    }
+                }
             }
-        }
-        catch (err) {
-            console.log(`[tools/list] Direct cache failed, will cache on first authenticated request`);
-        }
+            catch (err) {
+                console.log(`[tools/list] Direct cache failed, will cache on first authenticated request`);
+            }
+        })();
     });
     // Graceful shutdown
     const shutdown = async () => {