clauderipple 0.2.0 → 0.3.0

package/dist/router/src/proxy.js

@@ -20,16 +20,21 @@ import tls from "node:tls";
 import zlib from "node:zlib";
 import { UpstreamHealth } from "./health.js";
 import { BOOTSTRAP_PATH, injectBootstrap } from "./bootstrap.js";
-import { THREAD_UNSUPPORTED, effortOf, resolve, rewriteBody, stripThreadFields, threadDecision } from "./routing.js";
+import { THREAD_UNSUPPORTED, effortOf, resolve, rewriteBody, stripThreadFields, threadDecision, unroutableReason } from "./routing.js";
+import { defaultAgentDir, withAgentAliases } from "./agents.js";
 import { forwardCompatibleHeader, resolveCompatibleCaps, sanitizeForCompatible } from "./compat.js";
 import { applyIdentityToAnthropicBody } from "./identity.js";
+import { anthropicServerToolBackend, webPluginBackend, webSearchBlocks, webSearchErrorBlocks, webSearchMessage, webSearchQuery, webSearchSse } from "./websearch.js";
+import { classify, CredentialPool, retryAfterMs } from "./pool.js";
 import { PRESETS } from "./presets.js";
 import { ChatGptAdapter } from "./providers/chatgpt/index.js";
 import { OpenAiCompatibleAdapter } from "./providers/openai/index.js";
-import { terminateHosts } from "./config.js";
+import { conversationKey } from "./providers/chatgpt/translate.js";
+import { providerFor, terminateHosts } from "./config.js";
 import { injectPickerModels, isBootstrapPath } from "./picker.js";
 import { ResponseUsageTap } from "./requestlog.js";
 import { credentialHeaderValues, redactErrorText, redactHeaders } from "./redact.js";
+import { ClaudeAccountAuthPool } from "./providers/anthropic-account-pool.js";
 const MAX_BODY = 64 * 1024 * 1024;
 const HOP_BY_HOP = new Set(["connection", "keep-alive", "proxy-connection", "transfer-encoding", "upgrade", "host", "content-length"]);
 // The caller's own Anthropic credentials. A routed request authenticates as the provider, so these
@@ -38,6 +43,98 @@ const HOP_BY_HOP = new Set(["connection", "keep-alive", "proxy-connection", "tra
 const CLIENT_AUTH = new Set(["authorization", "x-api-key"]);
 /** How much of an upstream error body is kept for the log. */
 const ERROR_HEAD_MAX = 4096;
+/**
+ * Claude Code's Remote Control registration uses HTTPS absolute-form proxy requests instead of
+ * CONNECT (`POST https://api.anthropic.com/v1/environments/bridge HTTP/1.1`). Convert that legal
+ * forward-proxy form to the origin form expected inside a TLS connection. Credentials and the
+ * request body remain byte-for-byte client data; proxy-only headers never reach the destination.
+ */
+export function absoluteProxyRequest(header) {
+    const lines = header.toString("latin1").split("\r\n");
+    const first = lines.shift() ?? "";
+    const match = /^([!#$%&'*+.^_`|~0-9A-Za-z-]+)\s+(\S+)\s+(HTTP\/1\.[01])$/.exec(first);
+    if (!match)
+        return null;
+    let url;
+    try {
+        url = new URL(match[2]);
+    }
+    catch {
+        return null;
+    }
+    if (url.protocol !== "https:" || url.username || url.password || url.hash || !url.hostname)
+        return null;
+    const port = url.port ? Number(url.port) : 443;
+    if (!Number.isInteger(port) || port < 1 || port > 65535)
+        return null;
+    // URL.hostname keeps brackets around IPv6 literals; net/tls expect the bare address while the
+    // HTTP Host field requires brackets. Keep those two representations separate.
+    const host = url.hostname.startsWith("[") && url.hostname.endsWith("]") ? url.hostname.slice(1, -1) : url.hostname;
+    const headers = lines.filter((line) => !/^proxy-(?:authorization|connection)\s*:/i.test(line) &&
+        !/^host\s*:/i.test(line) &&
+        !/^connection\s*:/i.test(line));
+    const authority = url.port ? `${url.hostname}:${url.port}` : url.hostname;
+    const path = `${url.pathname || "/"}${url.search}`;
+    // One TLS connection serves one absolute-form request. Reusing it would send the next proxy-form
+    // request target directly to the origin, so explicitly ask both peers to close after the response.
+    const rewritten = [`${match[1]} ${path} ${match[3]}`, `Host: ${authority}`, "Connection: close", ...headers].join("\r\n") + "\r\n\r\n";
+    return { host, port, path, head: Buffer.from(rewritten, "latin1") };
+}
+/**
+ * The same header list with one credential swapped for another. Names carried by either credential
+ * are removed first: an observed Claude session can have fingerprint headers that a stored login
+ * does not, and leaving those behind would combine two distinct client identities on the retry.
+ */
+export function withCredential(headers, credential, previous = {}) {
+    const replaced = new Set([...Object.keys(previous), ...Object.keys(credential)].map((k) => k.toLowerCase()));
+    const out = [];
+    for (let i = 0; i < headers.length; i += 2) {
+        if (replaced.has(headers[i].toLowerCase()))
+            continue;
+        out.push(headers[i], headers[i + 1]);
+    }
+    for (const [k, v] of Object.entries(credential))
+        out.push(k, v);
+    return out;
+}
+/**
+ * A body decoded for reading, as text. Bytes that cannot be decoded are read as they arrived.
+ *
+ * Text and not bytes, deliberately. What every caller wants from a compressed body is what it
+ * says, and handing the bytes back is a one-way door: invalid UTF-8 sequences become U+FFFD and
+ * never come back, while `content-encoding` still stands in the response — which is
+ * `ERR_CONTENT_DECODING_FAILED` in the client (2026-09-22). Returning text leaves nothing here
+ * that a later caller could mistake for something a client may be given.
+ *
+ * A body read to a cap stops mid-stream, and a strict decode of that throws (`Z_BUF_ERROR`,
+ * measured Node 24), so these decode with a flush: it yields whatever completed, which is the head
+ * of the message and the whole reason the body is read. An intact stream decodes identically.
+ */
+export function decodeBodyToText(body, encoding) {
+    const enc = String(encoding ?? "").toLowerCase();
+    const zstd = zlib.zstdDecompressSync;
+    const decode = enc === "gzip" || enc === "x-gzip" ? (b) => zlib.gunzipSync(b, { finishFlush: zlib.constants.Z_SYNC_FLUSH })
+        : enc === "deflate" ? (b) => zlib.inflateSync(b, { finishFlush: zlib.constants.Z_SYNC_FLUSH })
+            : enc === "br" ? (b) => zlib.brotliDecompressSync(b, { finishFlush: zlib.constants.BROTLI_OPERATION_FLUSH })
+                // Chromium 152 asks for zstd, so anything the app talks to may answer with it.
+                : enc === "zstd" && typeof zstd === "function" ? (b) => zstd(b, { finishFlush: zlib.constants.ZSTD_e_flush })
+                    : undefined;
+    if (!decode)
+        return body.toString("utf8");
+    try {
+        const out = decode(body);
+        // A truncated zstd frame yields nothing at all and does not throw doing it, unlike the others
+        // (measured 2026-09-22). Describe that instead of returning an empty body, which would read as
+        // a provider that refused without saying anything.
+        if (out.length === 0 && body.length > 0)
+            return `(${body.length}B of ${enc} that stops mid-stream and cannot be decoded)`;
+        return out.toString("utf8");
+    }
+    catch {
+        // Nothing decodable even with a flush; fall through to what is readable in the bytes.
+        return body.toString("utf8");
+    }
+}
 /**
  * A bounded, decoded upstream error excerpt with credentials completely masked. Providers may
  * echo the key they rejected, including an opaque vendor-specific key format.
@@ -48,20 +145,7 @@ export function errorSnippet(head, encoding, secrets = [], contentType) {
     // OpenRouter answering 200 HTML when the /api prefix was lost).
     if (/text\/html/i.test(String(contentType ?? "")))
         return `HTML page (${head.length}B) — the provider URL points at a website or a login page, not an API`;
-    let out = head;
-    const enc = String(encoding ?? "").toLowerCase();
-    try {
-        if (enc === "gzip" || enc === "x-gzip")
-            out = zlib.gunzipSync(head);
-        else if (enc === "deflate")
-            out = zlib.inflateSync(head);
-        else if (enc === "br")
-            out = zlib.brotliDecompressSync(head);
-    }
-    catch {
-        // A truncated compressed body decodes to nothing; fall through to what is readable.
-    }
-    const masked = redactErrorText(out.toString("utf8"), secrets, 300);
+    const masked = redactErrorText(decodeBodyToText(head, encoding), secrets, 300);
     return masked || "(empty body)";
 }
 export class Proxy {
@@ -75,7 +159,14 @@ export class Proxy {
     providerAgents = new Map();
     chatgptAdapters = new Map();
     openaiAdapters = new Map();
+    claudeAccounts;
     deps;
+    /**
+     * Cooldowns, quarantines and conversation stickiness for provider credentials. In memory: a
+     * cooldown that outlived a restart would make restarting worse, and a rejected credential earns
+     * its quarantine again on the first request.
+     */
+    pool = new CredentialPool();
     /** Latest rate-limit snapshot reported by any chatgpt provider (for the admin GUI). */
     get chatgptRateLimits() {
         const out = {};
@@ -83,6 +174,35 @@ export class Proxy {
             out[name] = a.adapter.lastRateLimits;
         return out;
     }
+    /**
+     * Ask one chatgpt provider for its quota now. Adapters are created on first use, so a provider
+     * nobody has called yet is instantiated from config here — otherwise the admin status would
+     * report "no quota" until the first GPT turn of the day.
+     */
+    chatgptFetchRateLimits(name) {
+        const cfg = this.deps.config().providers[name];
+        if (!cfg || cfg.type !== "chatgpt")
+            return Promise.resolve(null);
+        return this.chatgpt(name, cfg).fetchRateLimits();
+    }
+    /**
+     * The models that provider can reach, from the Codex backend's own catalogue, so a model OpenAI
+     * ships appears in the GUI and the picker without a release here. Null when the catalogue cannot
+     * be read; the caller falls back to a measured list.
+     */
+    chatgptFetchModels(name) {
+        const cfg = this.deps.config().providers[name];
+        if (!cfg || cfg.type !== "chatgpt")
+            return Promise.resolve(null);
+        return this.chatgpt(name, cfg).fetchModels();
+    }
+    /** Startup refresh: every configured chatgpt provider, in the background, never awaited. */
+    chatgptRefreshAll() {
+        for (const [name, p] of Object.entries(this.deps.config().providers)) {
+            if (p.type === "chatgpt")
+                void this.chatgptFetchRateLimits(name);
+        }
+    }
     chatgptAuthStatus() {
         const out = {};
         for (const [name, a] of this.chatgptAdapters)
@@ -109,6 +229,11 @@ export class Proxy {
     }
     constructor(deps) {
         this.deps = deps;
+        this.claudeAccounts = new ClaudeAccountAuthPool({
+            home: deps.home,
+            log: deps.log,
+            ...(deps.observedClaudeCodeAuth ? { observed: deps.observedClaudeCodeAuth } : {}),
+        });
         this.httpServer = http.createServer({ maxHeaderSize: 64 * 1024 }, (req, res) => {
             void this.handle(req, res);
         });
@@ -180,6 +305,12 @@ export class Proxy {
             const line = head.subarray(0, end).toString("latin1").split("\r\n")[0] ?? "";
             const [method, target] = line.split(" ");
             if (method !== "CONNECT" || !target) {
+                const absolute = absoluteProxyRequest(head.subarray(0, end));
+                if (absolute) {
+                    log.info(`ABSOLUTE ${method ?? "?"} https://${absolute.host}:${absolute.port}${absolute.path}`);
+                    this.forwardAbsolute(sock, absolute, rest);
+                    return;
+                }
                 sock.end("HTTP/1.1 405 Method Not Allowed\r\ncontent-length: 0\r\nconnection: close\r\n\r\n");
                 return;
             }
@@ -198,6 +329,32 @@ export class Proxy {
         };
         sock.on("data", onData);
     }
+    /** Forward an HTTPS absolute-form request without terminating it through the routing layer. */
+    forwardAbsolute(sock, request, rest) {
+        const servername = net.isIP(request.host) ? undefined : request.host;
+        const up = (this.deps.tlsConnect ?? tls.connect)({ host: request.host, port: request.port, ...(servername ? { servername } : {}), ALPNProtocols: ["http/1.1"] });
+        const kill = () => {
+            sock.destroy();
+            up.destroy();
+        };
+        up.on("error", (e) => {
+            this.deps.log.warn(`absolute upstream error ${request.host}:${request.port}: ${e.message}`);
+            if (sock.writable)
+                sock.end("HTTP/1.1 502 Bad Gateway\r\ncontent-length: 0\r\nconnection: close\r\n\r\n");
+            up.destroy();
+        });
+        sock.on("error", kill);
+        up.once("secureConnect", () => {
+            up.write(request.head);
+            if (rest.length)
+                up.write(rest);
+            sock.pipe(up);
+            up.pipe(sock);
+            sock.resume();
+        });
+        up.on("close", () => sock.destroy());
+        sock.on("close", () => up.destroy());
+    }
     terminate(sock, host) {
         let ctx;
         try {
@@ -275,8 +432,10 @@ export class Proxy {
     }
     // ---- per-request handling ----------------------------------------------------------
     async handle(req, res) {
-        const cfg = this.deps.config();
         const log = this.deps.log;
+        // The agent files' derived aliases join the config's own, so a marker naming a worker resolves
+        // the same way here as it does everywhere else. Explicit aliases win; the scan is mtime-cached.
+        const cfg = withAgentAliases(this.deps.config(), this.deps.agentDir ?? defaultAgentDir(), log);
         const t0 = Date.now();
         const method = req.method ?? "?";
         const path = req.url ?? "/";
@@ -371,7 +530,41 @@ export class Proxy {
                 json = null;
             }
         }
-        const route = json ? resolve(model, json, cfg) : null;
+        // A WebSearch arrives as its own request aimed at ANTHROPIC_SMALL_FAST_MODEL, recognised by the
+        // forced `web_search` server tool rather than by its model id. Recognise it whether or not a
+        // backend is configured: `cfg.webSearch` decides who answers it, but knowing that this is a
+        // search is what lets the guard below refuse a provider that cannot run one. Tying the two
+        // together meant an unconfigured router could not tell a search from any other turn.
+        const search = json && isApiHost && pathname === "/v1/messages" ? webSearchQuery(json) : null;
+        if (search && cfg.webSearch) {
+            const served = await this.serveWebSearch(res, json, search, cfg.webSearch, record, finish);
+            if (served)
+                return;
+            // Fall through on failure: the ordinary path still answers, and a search that quietly
+            // returns nothing is worse than one that costs what it always cost.
+        }
+        const resolved = json ? resolve(model, json, cfg) : null;
+        // A non-Claude model this router cannot route is refused here, by name, instead of being
+        // forwarded to Anthropic. `PASS` on such a request answers 404 from Anthropic and looks like
+        // "the model vanished" (2026-09-20: an agent file named `deepseek` resolved, through a missing
+        // alias, to a model no provider declared — thirty of them came back 404). A native `claude-*`
+        // id is deliberately unrouted and must keep passing through (§5).
+        if (!resolved && isApiHost && isMessages && json && typeof model === "string" && !model.startsWith("claude-")) {
+            const reason = unroutableReason(model, json, cfg);
+            if (reason) {
+                const payload = JSON.stringify({ type: "error", error: { type: "invalid_request_error", message: `ClaudeRipple: ${reason}` } });
+                res.writeHead(400, { "content-type": "application/json", "content-length": String(Buffer.byteLength(payload)) }).end(payload);
+                tag = `REFUSE ${model}`;
+                record = { ...record, provider: "refused" };
+                finish("400", payload.length, `ClaudeRipple: ${reason}`, true);
+                return;
+            }
+        }
+        // A slot with fallbacks picks its provider before anything is sent, so a primary that is rate
+        // limited for the next hour is skipped rather than rediscovered once per request. Failing over
+        // mid-turn is not possible — once a byte of the answer has gone out, replacing it would splice
+        // two answers together — so the choice has to be made here or not at all.
+        const route = resolved ? this.chooseTarget(resolved, cfg, log) : null;
         const source = typeof model === "string" ? model : "-";
         record = {
             ...record,
@@ -386,16 +579,44 @@ export class Proxy {
         // Do not inspect it elsewhere: it must never enter logs, RequestLog, picker diagnostics, or admin data.
         if (isApiHost && pathname === "/v1/messages" && !route)
             this.deps.observedClaudeCodeAuth?.observe(req.rawHeaders);
+        // A `WebSearch` side request routed to a provider that cannot run the server tool must not be
+        // sent. The tool is dropped on every translated path, which leaves "you are an assistant for
+        // performing a web search tool use / perform a web search for the query: …" with no tool
+        // attached — and a model told to search with nothing to search with narrates a tool call
+        // instead. OpenCode Go's DeepSeek answered exactly that, in its own markup, as HTTP 200
+        // (measured 2026-09-18), and the session reported the search tool as unresponsive.
+        //
+        // Say so in the shape the CLI prints. A search that fails visibly can be retried by a human;
+        // one that returns prose shaped like an answer cannot.
+        if (search && route && json && !this.canRunServerTools(route.provider, cfg)) {
+            const blocks = webSearchErrorBlocks(search, "unavailable");
+            const model = typeof json.model === "string" ? json.model : "unknown";
+            const wantStream = json.stream === true;
+            const payload = wantStream ? webSearchSse(model, blocks, 0) : JSON.stringify(webSearchMessage(model, blocks, 0));
+            res.writeHead(200, wantStream
+                ? { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" }
+                : { "content-type": "application/json" }).end(payload);
+            log.warn(`web search: ${route.provider} cannot run server tools and no webSearch backend is configured; refused rather than answered with invented results`);
+            finish("200", Buffer.byteLength(payload), `web search refused: ${route.provider} runs no server tools`, false);
+            return;
+        }
         let compatCaps;
         let compatChanges = [];
+        /** The credential this attempt is using, and so the one a failure is charged to. */
+        let chosen = null;
+        let penalised = null;
         let target;
         if (route && json) {
-            const provider = cfg.providers[route.provider];
-            if (!provider) {
+            const configured = cfg.providers[route.provider];
+            if (!configured) {
                 finish("500", 0, `unknown provider ${route.provider}`);
                 res.writeHead(500, { "content-type": "application/json" }).end(JSON.stringify({ error: { type: "clauderipple_config", message: `unknown provider ${route.provider}` } }));
                 return;
             }
+            // A model may speak another wire than the rest of its provider: one subscription serving
+            // several protocols is one provider, and this is where the model's own shape is folded in so
+            // the branches below pick the adapter it actually needs.
+            const provider = providerFor(configured, route.model);
             rewriteBody(json, route, cfg.effortClamp);
             if (provider.type === "chatgpt") {
                 const td = threadDecision(json);
@@ -414,9 +635,14 @@ export class Proxy {
                 tag = `CHATGPT ${route.tag} effort=${routeEffort ?? "-"}`;
                 try {
                     const o = await this.chatgpt(route.provider, provider).handle(req, res, path, json, route.model, effortOf(json));
+                    // Without this the pool never hears about this provider, so it always looks healthy and a
+                    // slot pointing at it can never fail over — which is most of the point on a subscription
+                    // that runs out. The credential here is the adapter's own OAuth, so there is one of it.
+                    this.recordOutcome(route.provider, o.status);
                     finish(String(o.status), o.bytes, o.note, o.status >= 400, { ...(o.usage ? { usage: o.usage } : {}), ...(o.stopReason ? { stopReason: o.stopReason } : {}) });
                 }
                 catch (e) {
+                    this.recordOutcome(route.provider, 0);
                     finish("-", 0, `chatgpt error ${e.code ?? ""} ${e.message}`);
                     if (!res.headersSent)
                         res.writeHead(502, { "content-type": "application/json" }).end(JSON.stringify({ type: "error", error: { type: "api_error", message: e.message } }));
@@ -442,9 +668,11 @@ export class Proxy {
                 tag = `OPENAI ${route.tag} wire=${provider.wire ?? "chat"} effort=${routeEffort ?? "-"}`;
                 try {
                     const o = await this.openai(route.provider, provider).handle(req, res, path, json, route.model, routeEffort);
+                    this.recordOutcome(route.provider, o.status);
                     finish(String(o.status), o.bytes, o.note, o.status >= 400, { ...(o.usage ? { usage: o.usage } : {}), ...(o.stopReason ? { stopReason: o.stopReason } : {}) });
                 }
                 catch (e) {
+                    this.recordOutcome(route.provider, 0);
                     finish("-", 0, `openai error ${e.code ?? ""} ${e.message}`);
                     if (!res.headersSent)
                         res.writeHead(502, { "content-type": "application/json" }).end(JSON.stringify({ type: "error", error: { type: "api_error", message: e.message } }));
@@ -453,48 +681,97 @@ export class Proxy {
                 }
                 return;
             }
-            // Unreachable in practice: resolve() drops rules naming a native provider so the request
-            // passes through instead. Kept as a guard — reaching a native endpoint from here would send
-            // it a request assembled for a translating provider.
             if (provider.type === "anthropic") {
-                finish("400", 0, "native Anthropic provider is available through OpenAI ingress only", false);
-                res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: { type: "invalid_request_error", message: "native Anthropic provider is available through OpenAI ingress only" } }));
-                return;
+                if (!provider.accountPool || provider.auth !== "claude-code") {
+                    finish("400", 0, "native Anthropic provider is available through OpenAI ingress only", false);
+                    res.writeHead(400, { "content-type": "application/json" }).end(JSON.stringify({ error: { type: "invalid_request_error", message: "native Anthropic provider is available through OpenAI ingress only" } }));
+                    return;
+                }
+                // Native Messages need no translation. Only authentication changes, so server-side threads,
+                // prompt caching, beta features and the client's exact tool contract remain first-party.
+                const credentials = await this.claudeAccounts.credentials();
+                if (credentials.length === 0) {
+                    const out = JSON.stringify({ type: "error", error: { type: "authentication_error", message: "ClaudeRipple: no usable Claude account; sign in or reauthenticate an account" } });
+                    res.writeHead(401, { "content-type": "application/json", "content-length": String(Buffer.byteLength(out)) }).end(out);
+                    finish("401", out.length, "no usable Claude account");
+                    return;
+                }
+                body = Buffer.from(JSON.stringify(json));
+                chosen = this.pool.pick(route.provider, credentials, conversationKey(json));
+                const using = chosen ?? credentials[0];
+                chosen = using;
+                penalised = { provider: route.provider, id: using.id };
+                target = {
+                    protocol: "https:",
+                    host: cfg.upstream,
+                    port: this.deps.upstreamPort ?? 443,
+                    agent: this.deps.upstreamAgent ?? this.agentFor(route.provider, "https:"),
+                    extraHeaders: using.headers,
+                    dropClientAuth: true,
+                    dropHeaders: new Set(credentials.flatMap((credential) => Object.keys(credential.headers).map((name) => name.toLowerCase()))),
+                    dropHeaderPrefixes: ["anthropic-client-", "x-stainless-"],
+                };
+                record = { ...record, target: route.model, provider: route.provider };
+                const routeEffort = effortOf(json);
+                if (routeEffort)
+                    record.effort = routeEffort;
+                tag = `CLAUDE ${route.tag} account=${using.ownerId?.slice(0, 8) ?? "current"}`;
+            }
+            else {
+                const preset = provider.preset ? PRESETS.find((entry) => entry.id === provider.preset) : undefined;
+                const modelEffortLevels = provider.models?.find((entry) => entry.id === route.model)?.effortLevels;
+                compatCaps = resolveCompatibleCaps(preset ? { effortLevels: preset.effortLevels, thinking: preset.thinking, ...(preset.serverTools ? { serverTools: true } : {}) } : undefined, modelEffortLevels === undefined ? provider.caps : { ...provider.caps, effortLevels: modelEffortLevels });
+                const sanitized = sanitizeForCompatible(json, compatCaps);
+                json = sanitized.json;
+                compatChanges = sanitized.changes;
+                // The upstream would otherwise read Claude Code's own system prompt and answer that it is
+                // Claude. After sanitizing, so the effort named is the one the provider actually receives.
+                applyIdentityToAnthropicBody(json, {
+                    model: route.model,
+                    effort: effortOf(json),
+                    identity: provider.identity,
+                    instructionsAppend: provider.instructionsAppend,
+                });
+                body = Buffer.from(JSON.stringify(json));
+                const u = new URL(provider.url);
+                const protocol = u.protocol === "https:" ? "https:" : "http:";
+                // Which credential answers this turn. The conversation keeps the one it is on while that one
+                // is healthy, because moving it moves the prompt cache with it. Every credential cooling or
+                // quarantined leaves `chosen` null, and the request goes out on the configured headers so the
+                // provider — not us — gets to say no.
+                const credentials = this.credentialsOf(route.provider, provider);
+                // The same key the prompt cache is keyed on. `metadata.user_id` alone is one value for every
+                // conversation a user has, so using it raw would drag all of them onto one credential at once
+                // — the opposite of what stickiness is for (see conversationKey and ARCHITECTURE §4).
+                chosen = this.pool.pick(route.provider, credentials, conversationKey(json));
+                // Nothing usable means every credential is cooling, and the turn still has to go somewhere:
+                // the first one, so the request carries real credentials rather than none, and so the answer
+                // is charged to the credential that actually produced it.
+                const using = chosen ?? credentials[0];
+                chosen = using;
+                penalised = { provider: route.provider, id: using.id };
+                target = {
+                    protocol,
+                    host: u.hostname,
+                    port: Number(u.port) || (protocol === "https:" ? 443 : 80),
+                    agent: this.agentFor(route.provider, protocol),
+                    // The credential wins over the session header: they are different names in practice, but a
+                    // vendor that reused one would mean the request going out unauthenticated.
+                    extraHeaders: provider.sessionHeader
+                        ? { [provider.sessionHeader]: conversationKey(json), ...using.headers }
+                        : using.headers,
+                    dropClientAuth: true,
+                    // Providers mount their Anthropic-compatible API under a path (DeepSeek /anthropic, OpenRouter /api,
+                    // Qwen /apps/anthropic): the CLI's /v1/messages is appended to it. Dropping it sent requests to the
+                    // vendor's website, which answered 200 with HTML (measured 2026-09-13 with OpenRouter).
+                    basePath: u.pathname.replace(/\/+$/, ""),
+                };
+                record = { ...record, target: route.model, provider: route.provider };
+                const routeEffort = effortOf(json);
+                if (routeEffort)
+                    record.effort = routeEffort;
+                tag = `${route.provider.toUpperCase()} ${route.tag} effort=${routeEffort ?? "-"}`;
             }
-            const preset = provider.preset ? PRESETS.find((entry) => entry.id === provider.preset) : undefined;
-            const modelEffortLevels = provider.models?.find((entry) => entry.id === route.model)?.effortLevels;
-            compatCaps = resolveCompatibleCaps(preset ? { effortLevels: preset.effortLevels, thinking: preset.thinking } : undefined, modelEffortLevels === undefined ? provider.caps : { ...provider.caps, effortLevels: modelEffortLevels });
-            const sanitized = sanitizeForCompatible(json, compatCaps);
-            json = sanitized.json;
-            compatChanges = sanitized.changes;
-            // The upstream would otherwise read Claude Code's own system prompt and answer that it is
-            // Claude. After sanitizing, so the effort named is the one the provider actually receives.
-            applyIdentityToAnthropicBody(json, {
-                model: route.model,
-                effort: effortOf(json),
-                identity: provider.identity,
-                instructionsAppend: provider.instructionsAppend,
-            });
-            body = Buffer.from(JSON.stringify(json));
-            const u = new URL(provider.url);
-            const protocol = u.protocol === "https:" ? "https:" : "http:";
-            target = {
-                protocol,
-                host: u.hostname,
-                port: Number(u.port) || (protocol === "https:" ? 443 : 80),
-                agent: this.agentFor(route.provider, protocol),
-                extraHeaders: provider.headers ?? {},
-                dropClientAuth: true,
-                // Providers mount their Anthropic-compatible API under a path (DeepSeek /anthropic, OpenRouter /api,
-                // Qwen /apps/anthropic): the CLI's /v1/messages is appended to it. Dropping it sent requests to the
-                // vendor's website, which answered 200 with HTML (measured 2026-09-13 with OpenRouter).
-                basePath: u.pathname.replace(/\/+$/, ""),
-            };
-            record = { ...record, target: route.model, provider: route.provider };
-            const routeEffort = effortOf(json);
-            if (routeEffort)
-                record.effort = routeEffort;
-            tag = `${route.provider.toUpperCase()} ${route.tag} effort=${routeEffort ?? "-"}`;
         }
         else if (isApiHost) {
             target = { protocol: "https:", host: cfg.upstream, port: 443, agent: this.upstreamAgent, extraHeaders: {} };
@@ -517,7 +794,7 @@ export class Proxy {
                 continue;
             // Bootstrap responses are edited: keep the client's accept-encoding as-is (some edges misbehave without it)
             // and decompress whatever comes back before editing.
-            if (lk in target.extraHeaders)
+            if (lk in target.extraHeaders || target.dropHeaders?.has(lk) || target.dropHeaderPrefixes?.some((prefix) => lk.startsWith(prefix)))
                 continue;
             if (target.dropClientAuth && CLIENT_AUTH.has(lk))
                 continue;
@@ -547,22 +824,80 @@ export class Proxy {
             }
             log.info(`PICKER request ${method} ${path.slice(0, 80)} headers: ${shown.join(" | ")}`);
         }
-        // Keep only actual credentials named by the outbound headers. This covers arbitrary vendor
-        // key formats when a provider reflects the key in its error body.
-        const errorSecrets = credentialHeaderValues(Array.from({ length: headers.length / 2 }, (_, i) => [headers[i * 2], headers[i * 2 + 1]]));
+        // Keep every credential this turn sends. A retry can use an opaque token that does not match a
+        // known token shape; retaining its actual value is what keeps a reflected refusal out of logs.
+        const errorSecrets = new Set(credentialHeaderValues(Array.from({ length: headers.length / 2 }, (_, i) => [headers[i * 2], headers[i * 2 + 1]])));
+        // Every retry is rebuilt from the first attempt's header list. Keep the union of identity header
+        // names already used so a current-session fingerprint cannot reappear on a third account.
+        let usedCredentialHeaders = { ...(chosen?.headers ?? {}) };
         const lib = target.protocol === "https:" ? https : http;
-        const upReq = lib.request({
-            protocol: target.protocol,
-            host: target.host,
-            port: target.port,
-            method,
-            path: target.basePath ? target.basePath + path : path,
-            headers,
-            agent: target.agent,
-            ...(target.protocol === "https:" ? { servername: target.host } : {}),
-        });
+        /**
+         * The attempt in flight. A routed turn may make more than one: when a credential is refused and
+         * nothing has reached the client yet, the next credential takes over inside the same turn, so
+         * the client is answered on its first ask instead of having to retry. `send` below replaces
+         * this; everything that reaches for the upstream reaches for it through here.
+         */
+        let upReq;
+        /** Credentials already spent on this turn, so a retry cannot pick one of them again. */
+        const tried = new Set(penalised ? [penalised.id] : []);
+        const send = (attemptHeaders) => {
+            upReq = lib.request({
+                protocol: target.protocol,
+                host: target.host,
+                port: target.port,
+                method,
+                path: target.basePath ? target.basePath + path : path,
+                headers: attemptHeaders,
+                agent: target.agent,
+                ...(target.protocol === "https:" ? { servername: target.host } : {}),
+            });
+            upReq.on("error", onUpstreamError);
+            upReq.on("response", onUpstreamResponse);
+            upReq.end(body);
+        };
+        /**
+         * The next credential to try inside this turn, or null to answer with what the provider said.
+         * Only for a routed request whose provider has one we have not already spent — a failure that
+         * is the request's own fault is not retried at all (see `classify`).
+         */
+        const nextCredential = (status, body = "") => {
+            if (!route || !penalised || res.headersSent)
+                return null;
+            if (!classify(status, undefined, body).retryable)
+                return null;
+            const owner = cfg.providers[route.provider];
+            if (!owner)
+                return null;
+            // The model's own shape again: its credential pool is the provider's, but an auth convention
+            // this model overrides has to be the one the retry actually sends.
+            const provider = providerFor(owner, route.model);
+            const available = provider.type === "anthropic" && provider.accountPool
+                ? this.claudeAccounts.peekCredentials()
+                : this.credentialsOf(route.provider, provider);
+            const rest = available.filter((c) => !tried.has(c.id));
+            if (rest.length === 0)
+                return null;
+            return this.pool.pick(route.provider, rest, conversationKey(json));
+        };
+        // Destroying the upstream makes it emit ECONNRESET (measured, Node 24.15), which is
+        // indistinguishable from the provider dropping us unless we remember that we did it. Without
+        // this flag every cancelled turn charged the credential a failure and moved the conversation
+        // off it, which costs the prompt cache — for a turn the user cancelled on purpose.
+        let clientAborted = false;
+        // Set when a 403 body was read ahead of the forward, so the forward knows to write that body
+        // instead of the stream it came from.
+        let headFilled = false;
+        // The 403 body exactly as it arrived. It is what the client is given: the judgement below
+        // reads a decoded copy, but a compressed body cannot survive a round trip through a UTF-8
+        // string — invalid sequences become U+FFFD and never come back. Returning that while
+        // `content-encoding` still stands is `ERR_CONTENT_DECODING_FAILED` in the app (2026-09-22).
+        let errRaw = Buffer.alloc(0);
+        // Set when the body was longer than the read cap, so its bytes are no longer a whole
+        // compressed stream and only the decoded head can be forwarded.
+        let errTruncated = false;
         const abortUpstream = () => {
-            if (!upReq.destroyed)
+            clientAborted = true;
+            if (upReq && !upReq.destroyed)
                 upReq.destroy();
         };
         req.on("aborted", abortUpstream);
@@ -572,9 +907,14 @@ export class Proxy {
                 finish("-", 0, "client closed");
             }
         });
-        upReq.on("error", (e) => {
+        const onUpstreamError = (e) => {
             if (target.host === cfg.upstream)
                 this.deps.health.failure(e);
+            // Nothing reached the provider, so this says nothing about the credential — but it does say
+            // the route is unusable for a moment, and a pool with somewhere else to go should use it.
+            // Our own abort is not the provider's fault and must not be charged to it.
+            if (penalised && !clientAborted)
+                this.pool.penalise(penalised.provider, penalised.id, 0);
             finish("-", 0, `upstream error ${e.code ?? ""} ${e.message}`);
             if (!res.headersSent) {
                 res.writeHead(502, { "content-type": "application/json", connection: "close" });
@@ -583,11 +923,100 @@ export class Proxy {
             else {
                 res.destroy();
             }
-        });
-        upReq.on("response", (upRes) => {
+        };
+        const onUpstreamResponse = (upRes) => {
             if (target.host === cfg.upstream)
                 this.deps.health.success();
             const status = upRes.statusCode ?? 0;
+            // A 403 is the one status whose meaning is in its body. A relay reporting a broken upstream
+            // must not be charged to the credential — that is what made one working key answer every turn
+            // with an authentication error for a minute (2026-09-21). Every other status is judged from
+            // the status alone, and its body is left for the forward below, untouched.
+            if (status === 403) {
+                bufferBody(upRes, ERROR_HEAD_MAX).then((whole) => onUpstreamJudged(upRes, status, whole)).catch((e) => {
+                    log.warn(`upstream ${status}: could not read the body: ${e.message}`);
+                    finish(String(status), 0, `upstream ${status}: body read failed`);
+                    res.destroy();
+                });
+                return;
+            }
+            onUpstreamJudged(upRes, status, "");
+        };
+        /**
+         * The whole of a small body, read before anything is decided or written.
+         *
+         * A 403's meaning is in its body and cannot be judged before it arrives, so the bytes are read
+         * and handed back as the head: `unshift` after a stream has ended throws, and reading a head and
+         * forwarding the rest mid-flow is where a body can be lost to a pause nothing resumes. A 403 is
+         * a refusal, so its body is small.
+         *
+         * What is returned is the body **decoded for reading**, because the judgement is about what the
+         * body says. The bytes themselves are kept in `errRaw` for the client: a compressed body is
+         * arbitrary binary, and text is a one-way door for it.
+         *
+         * Past `max` there is nothing worth identifying, so the rest is dropped — but the stream is
+         * never destroyed. Tearing the connection down over a body size would turn a refusal the user
+         * can read into a socket error, which is a worse bug than the one this handles; an unbounded
+         * relay answer instead reaches the forward above the cap and is reported there.
+         */
+        const bufferBody = (stream, max) => new Promise((resolveBody) => {
+            const chunks = [];
+            let size = 0;
+            stream.on("data", (c) => {
+                const room = max - size;
+                if (room <= 0) {
+                    errTruncated = true;
+                    stream.resume();
+                    return;
+                }
+                if (c.length > room)
+                    errTruncated = true;
+                chunks.push(c.subarray(0, room));
+                size += Math.min(c.length, room);
+            });
+            const handOver = () => {
+                errRaw = Buffer.concat(chunks, size);
+                headFilled = true;
+                resolveBody(decodeBodyToText(errRaw, stream.headers["content-encoding"]));
+            };
+            stream.once("end", handOver);
+            // A dropped or failed stream still hands over what arrived; the caller's own upstream error
+            // path is already attached, and duplicating it here would race it for the same response.
+            stream.once("error", handOver);
+        });
+        const onUpstreamJudged = (upRes, status, errBody) => {
+            // Charge the answer to the credential that produced it. A rate limit parks this one until its
+            // stated reset so the next request takes another; an answer clears whatever it was carrying.
+            // A 400 is our own request and is charged to nobody (see `classify`).
+            if (penalised) {
+                if (status >= 400) {
+                    this.pool.penalise(penalised.provider, penalised.id, status, retryAfterMs(upRes.headers), errBody);
+                    if (status === 401 && cfg.providers[penalised.provider]?.type === "anthropic")
+                        this.claudeAccounts.reject(penalised.id);
+                }
+                else
+                    this.pool.succeed(penalised.provider, penalised.id);
+            }
+            // Nothing has been written to the client yet, so a refused credential can still be replaced
+            // and the client answered on its first ask. Only here: once the answer starts flowing the
+            // turn is committed, because replacing a half-sent stream splices two answers together.
+            const retry = status >= 400 ? nextCredential(status, errBody) : null;
+            if (retry) {
+                const previousId = retry.ownerId ? penalised.id.split(":", 1)[0] : penalised.id;
+                log.info(`RETRY ${route.provider}: ${previousId} answered ${status}, trying ${retry.ownerId ?? retry.id}`);
+                tried.add(retry.id);
+                usedCredentialHeaders = { ...usedCredentialHeaders, ...(chosen?.headers ?? {}), ...retry.headers };
+                chosen = retry;
+                penalised = { provider: route.provider, id: retry.id };
+                for (const secret of credentialHeaderValues(Object.entries(retry.headers)))
+                    errorSecrets.add(secret);
+                upRes.resume();
+                upRes.destroy();
+                // Remove every identity header used by any earlier attempt. The baseline is the first request,
+                // so removing only the immediately previous account would resurrect first-attempt fingerprints.
+                send(withCredential(headers, retry.headers, usedCredentialHeaders));
+                return;
+            }
             const outHeaders = [];
             const r = upRes.rawHeaders;
             for (let i = 0; i < r.length; i += 2) {
@@ -598,6 +1027,10 @@ export class Proxy {
                     continue;
                 if (isPickerBootstrap && (lk === "etag" || lk === "last-modified"))
                     continue;
+                // A truncated 403 is forwarded decoded (its bytes are no longer a whole compressed
+                // stream), so neither the upstream's encoding nor its length describes what is sent.
+                if (errTruncated && (lk === "content-length" || lk === "content-encoding"))
+                    continue;
                 outHeaders.push(r[i], r[i + 1]);
             }
             let bytes = 0;
@@ -629,7 +1062,7 @@ export class Proxy {
                         }
                     }
                     else if (isPickerBootstrap && status !== 200 && status !== 304) {
-                        log.warn(`PICKER bootstrap upstream ${status}; headers: ${JSON.stringify(redactHeaders(upRes.headers))}; body: ${redactErrorText(out.toString("utf8"), errorSecrets, 300)}`);
+                        log.warn(`PICKER bootstrap upstream ${status}; headers: ${JSON.stringify(redactHeaders(upRes.headers))}; body: ${redactErrorText(out.toString("utf8"), [...errorSecrets], 300)}`);
                     }
                     else if (status === 200 && isPickerBootstrap) {
                         try {
@@ -668,6 +1101,17 @@ export class Proxy {
             // code was recorded (2026-09-15).
             const errorHead = [];
             let errorHeadBytes = 0;
+            // The 403 body was read to judge it, so it is written here instead of read again from a
+            // stream that has already ended. The bytes go back exactly as they arrived, so a compressed
+            // body still matches the `content-encoding` and `content-length` the upstream stated; only a
+            // truncated one is sent decoded, and both headers were dropped above for it.
+            if (headFilled) {
+                const body = errTruncated ? Buffer.from(errBody, "utf8") : errRaw;
+                bytes = body.length;
+                res.end(body);
+                finish(String(status), bytes, `upstream ${status}: ${redactErrorText(errBody, [...errorSecrets], 300)}`);
+                return;
+            }
             upRes.on("data", (c) => {
                 bytes += c.length;
                 const writable = res.write(c);
@@ -686,14 +1130,185 @@ export class Proxy {
                 observedUsage = observed.usage;
                 observedStopReason = observed.stopReason;
                 res.end();
-                finish(String(status), bytes, status >= 400 ? `upstream ${status}: ${errorSnippet(Buffer.concat(errorHead), upRes.headers["content-encoding"], errorSecrets, upRes.headers["content-type"])}` : undefined);
+                finish(String(status), bytes, status >= 400 ? `upstream ${status}: ${errorSnippet(Buffer.concat(errorHead), upRes.headers["content-encoding"], [...errorSecrets], upRes.headers["content-type"])}` : undefined);
             });
             upRes.on("error", (e) => {
                 finish(String(status), bytes, `upstream stream error ${e.message}`);
                 res.destroy();
             });
-        });
-        upReq.end(body);
+        };
+        send(headers);
+    }
+    /**
+     * Answer a WebSearch side request from a provider's hosted search instead of letting it reach a
+     * model. Returns false when it could not be served, and the caller falls back to the normal path:
+     * an empty search result is the one outcome worth avoiding, because nothing anywhere reports it.
+     */
+    async serveWebSearch(res, json, query, settings, record, finish) {
+        const configured = this.deps.config().providers[settings.provider];
+        if (!configured) {
+            this.deps.log.warn(`web search: unknown provider ${settings.provider}; leaving the request alone`);
+            return false;
+        }
+        // Which backend is chosen below depends on the wire the search model speaks, which may not be
+        // the provider's own.
+        const provider = providerFor(configured, settings.model);
+        const url = "url" in provider && typeof provider.url === "string" ? provider.url : undefined;
+        if (!url && provider.type !== "chatgpt") {
+            this.deps.log.warn(`web search: provider ${settings.provider} has no url; leaving the request alone`);
+            return false;
+        }
+        // Which backend depends on how the provider is spoken to, not on the vendor. An
+        // anthropic-compatible one is asked in Anthropic's own shape and hands back the blocks the CLI
+        // already parses; an openai-compatible one is asked through its chat web plugin.
+        const common = {
+            name: settings.provider,
+            url: url ?? "",
+            headers: ("headers" in provider && provider.headers) || {},
+            model: settings.model,
+            ...(settings.maxResults ? { maxResults: settings.maxResults } : {}),
+        };
+        let backend;
+        if (provider.type === "anthropic-compatible") {
+            // Refuse before sending rather than after. A provider that cannot run the server tool is sent
+            // "perform a web search" with no tool attached, and a model told to search with nothing to
+            // search with narrates a tool call instead — an answer shaped like success, holding nothing.
+            if (!this.canRunServerTools(settings.provider, this.deps.config())) {
+                this.deps.log.warn(`web search: provider ${settings.provider} does not run server tools; leaving the request alone`);
+                return false;
+            }
+            backend = anthropicServerToolBackend(common);
+        }
+        else if (provider.type === "openai-compatible") {
+            backend = webPluginBackend(common);
+        }
+        else if (provider.type === "chatgpt") {
+            backend = this.chatgpt(settings.provider, provider).webSearch(settings.model, settings.maxResults);
+        }
+        else {
+            this.deps.log.warn(`web search: provider ${settings.provider} is a ${provider.type} provider, which has no search backend; leaving the request alone`);
+            return false;
+        }
+        const model = typeof json.model === "string" ? json.model : "unknown";
+        let blocks;
+        try {
+            const outcome = await backend.search(query);
+            blocks = webSearchBlocks(query, outcome).blocks;
+        }
+        catch (e) {
+            this.deps.log.warn(`web search via ${settings.provider}: ${e.message}`);
+            return false;
+        }
+        record.target = `${settings.provider}/${settings.model}`;
+        const wantStream = json.stream === true;
+        const payload = wantStream ? webSearchSse(model, blocks, 1) : JSON.stringify(webSearchMessage(model, blocks, 1));
+        const headers = wantStream
+            ? { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" }
+            : { "content-type": "application/json" };
+        res.writeHead(200, headers).end(payload);
+        finish("200", Buffer.byteLength(payload), `web search via ${settings.provider}`, false);
+        return true;
+    }
+    /**
+     * Whether this provider executes Anthropic's server-side tools (`web_search`) itself, rather than
+     * having them dropped on the way out. Only an anthropic-compatible provider whose preset or caps
+     * say so, measured per provider — `serverTools` in compat.ts. Two routes to the same vendor can
+     * differ: DeepSeek's own endpoint runs it, the same model through OpenCode Go does not.
+     */
+    canRunServerTools(name, cfg) {
+        const provider = cfg.providers[name];
+        // A routed native account still calls Anthropic's Messages API unchanged, so Anthropic executes
+        // its own server tools. Only translated/compatible providers need an explicit measured capability.
+        if (provider?.type === "anthropic")
+            return provider.accountPool === true && provider.auth === "claude-code";
+        if (!provider || provider.type !== "anthropic-compatible")
+            return false;
+        const preset = provider.preset ? PRESETS.find((entry) => entry.id === provider.preset) : undefined;
+        return resolveCompatibleCaps(preset ? { ...(preset.serverTools ? { serverTools: true } : {}) } : undefined, provider.caps).serverTools;
+    }
+    /**
+     * The provider this turn actually goes to. The primary unless every one of its credentials is
+     * cooling or quarantined, in which case the first fallback that has something usable takes it.
+     *
+     * When nothing anywhere is usable the primary is kept: the provider gets to refuse the request
+     * rather than the router inventing a refusal, and the answer it gives is what updates the pool.
+     */
+    chooseTarget(resolved, cfg, log) {
+        if (!resolved.fallbacks?.length)
+            return resolved;
+        const usable = (name) => {
+            const provider = cfg.providers[name];
+            if (!provider)
+                return false;
+            if (provider.type === "anthropic") {
+                if (!provider.accountPool || provider.auth !== "claude-code")
+                    return false;
+                const accounts = this.claudeAccounts.peekCredentials();
+                return accounts.length > 0 && this.pool.hasUsable(name, accounts);
+            }
+            return this.pool.hasUsable(name, this.credentialsOf(name, provider));
+        };
+        if (usable(resolved.provider))
+            return resolved;
+        for (const f of resolved.fallbacks) {
+            if (f.provider === resolved.provider && f.model === resolved.model)
+                continue;
+            if (!usable(f.provider))
+                continue;
+            log.info(`FAILOVER ${resolved.provider}/${resolved.model} exhausted → ${f.provider}/${f.model}`);
+            // The tag names the model that answers, not the one that could not: a log line saying `->m1`
+            // for a turn that ran on m2 is the kind of thing that costs an hour to disbelieve.
+            const asked = resolved.tag.split("->")[0] ?? resolved.model;
+            return {
+                provider: f.provider,
+                model: f.model,
+                effort: f.effort ?? resolved.effort,
+                tag: `${asked}->${f.model} (failover from ${resolved.provider})`,
+            };
+        }
+        return resolved;
+    }
+    /**
+     * Tell the pool how a translated provider's turn went. These adapters hold their own credential —
+     * an OAuth grant, or configured headers — so there is one of it, but the pool still has to hear
+     * about the result or `hasUsable` says yes forever and a slot can never fail over away.
+     *
+     * A status of 0 means the attempt threw before an answer, which is a connect failure.
+     */
+    recordOutcome(provider, status) {
+        const id = "default";
+        if (status >= 400 || status === 0)
+            this.pool.penalise(provider, id, status);
+        else if (status > 0)
+            this.pool.succeed(provider, id);
+    }
+    /**
+     * A provider's credentials as a pool. A provider that declares none has exactly the one it always
+     * had, under a fixed id so its health survives config edits that do not touch it.
+     */
+    credentialsOf(name, provider) {
+        const declared = provider.credentials;
+        if (declared && declared.length > 0)
+            return declared;
+        const headers = ("headers" in provider && provider.headers) || {};
+        return [{ id: "default", headers }];
+    }
+    /** Health of every credential the config declares, for the dashboard. */
+    credentialHealth() {
+        const cfg = this.deps.config();
+        const out = {};
+        for (const [name, provider] of Object.entries(cfg.providers)) {
+            const creds = provider.type === "anthropic" && provider.accountPool
+                ? this.claudeAccounts.peekCredentials()
+                : this.credentialsOf(name, provider);
+            if (creds.length === 0 || (creds.length === 1 && creds[0].id === "default"))
+                continue; // nothing to report about a pool of one
+            out[name] = this.pool.report(name, creds).map((report) => {
+                const credential = creds.find((candidate) => candidate.id === report.id);
+                return credential?.ownerId ? { ...report, id: credential.ownerId } : report;
+            });
+        }
+        return out;
     }
     agentFor(provider, protocol) {
         const key = `${provider}|${protocol}`;