cartethyia 2.7.2 → 2.7.4

package/src/providers/integrations/qoder/qoder.ts

@@ -23,14 +23,19 @@ import type {
 import { toolResultParts, toolCallParts } from "../../../protocol/canonical-model";
 import { decodeSseEvents } from "../../../protocol/sse-decoder";
 import { usageFromProvider, readReasoningText } from "../../provider-usage";
-import { readCredentialSecret, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type ProviderId } from "../../provider-contracts";
+import { readCredentialSecret, assertWireFamily, type ProviderDispatchTarget, type ProviderAdapter, type ProviderDispatchContext, type ProviderId } from "../../provider-contracts";
 import type { ModelDefinition } from "../../provider-model-definition";
 import { parseQoderOAuthState } from "./qoder-oauth";
 import { getQoderVersion } from "../../operations/client-versions";
 import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
 import { qoderMachineOs } from "../../operations/cli-platform";
-import { qoderInferenceCandidates, QODER_CHAT_PATH, QODER_REALMS, type QoderRealm } from "./qoder-realm";
-import { QODER_CN_MODEL_CONFIGS, QODER_INTL_MODEL_CONFIGS, QODER_INTL_MODELS } from "./qoder-catalog";
+import { qoderIdeChatUrl, qoderInferenceCandidates, QODER_CHAT_PATH, QODER_REALMS, type QoderRealm } from "./qoder-realm";
+import {
+  QODER_CN_MODEL_CONFIGS,
+  QODER_INTL_MODEL_CONFIGS,
+  QODER_INTL_MODELS,
+  qoderDiscoveredMaxContexts,
+} from "./qoder-catalog";
 import { isQoderVirtualModel, qoderDispatchModelId } from "./qoder-virtual";
 import {
   LEAK_MARKER_ANY_RE,
@@ -46,7 +51,7 @@ const LEAK_HOLD_MAX_CHARS = 32_768;
 const LEAK_HOLD_MAX_FRAMES = 200;
 
 const BAD_ECHO_MESSAGE =
-  "Qoder returned an unparseable tool-call echo; no tools were emitted";
+  "Qoder returned an unparseable tool-call echo (request {requestId}); no tools were emitted. The upstream came back empty-handed — retry 🌙";
 
 function badEchoError(): GatewayError {
   return new GatewayError(
@@ -232,7 +237,9 @@ export function qoderMachineIdForAccount(accountId: string): string {
  * directly as the COSY identity's oauth token; the user id and machine id
  * come from the `auth_state` the login persisted. Fails closed with a
  * reconnect prompt when the identity is absent (e.g. an account created
- * before `auth_state` existed) instead of signing with a guessed id.
+ * before `auth_state` existed, or an import that dropped the field) instead
+ * of signing with a guessed id. The message names the missing field so an
+ * operator can fix the export instead of re-logging blind.
  */
 export function qoderOAuthAuth(
   secret: string,
@@ -240,11 +247,11 @@ export function qoderOAuthAuth(
   accountId: string | undefined,
 ): QoderAuth {
   const state = parseQoderOAuthState(authState);
-  if (state === undefined || !state.userId) {
+  if (state === undefined) {
     throw new GatewayError(
       "authentication_failed",
       401,
-      "Qoder OAuth account is missing its user identity; sign in again",
+      "Qoder OAuth account is missing its user identity (request {requestId}) (auth_state.userId/machineId absent or empty — re-login, or re-export with authState included); sign in again. Wrong key, right door — check the credential 🔑",
     );
   }
   return {
@@ -385,14 +392,14 @@ async function exchangeQoderPat(
   try {
     responseBody = await response.json();
   } catch {
-    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned invalid JSON", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned invalid JSON (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
   if (typeof responseBody !== "object" || responseBody === null || Array.isArray(responseBody)) {
-    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned unexpected response", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned unexpected response (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
   const rec = responseBody as Record<string, unknown>;
   if (typeof rec["id"] !== "string" || typeof rec["securityOauthToken"] !== "string") {
-    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned incomplete credentials", {}, "upstream");
+    throw new GatewayError("platform_unavailable", 502, "Qoder PAT exchange returned incomplete credentials (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
   }
   return {
     userId: rec["id"] as string,
@@ -479,7 +486,7 @@ function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data
     throw new GatewayError(
       classification.code,
       classification.status,
-      detail.length > 0 ? detail : `Qoder stream envelope returned HTTP ${status}`,
+      detail.length > 0 ? `${detail} (request {requestId}). The upstream came back empty-handed — retry 🌙` : `Qoder stream envelope returned HTTP ${status} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
       {
         providerId: QODER_PROVIDER_ID,
         providerStatus: status,
@@ -496,8 +503,11 @@ function qoderEnvelopeToFrames(data: string): Array<{ event: string | null; data
   }
   const body = rec["body"];
   if (body === "[DONE]") return [{ event: null, data: "[DONE]" }];
-  if (typeof body !== "string") return [];
-  return [{ event: null, data: body.replace(/\r?\n/g, "") }];
+  if (typeof body === "string") return [{ event: null, data: body.replace(/\r?\n/g, "") }];
+  // Direct OpenAI chunk (IDE surface): no envelope body, but a `choices` array
+  // is present. Pass the raw data through so the chunk parser sees it.
+  if (Array.isArray(rec["choices"])) return [{ event: null, data }];
+  return [];
 }
 
 function qoderStableHash(prefix: string, ...parts: string[]): string {
@@ -538,6 +548,21 @@ function qoderStableRecordId(modelId: string, messages: CanonicalRequest["messag
   return h.digest("hex").slice(0, 16);
 }
 
+/**
+ * The widest selectable context window for one model key.
+ *
+ * The live list's `context_config` is the authority when discovery has run:
+ * it names every window the account can switch to, and the widest one is what
+ * a dispatch should send (`model_config.max_input_tokens`) so a conversation is
+ * never capped at the *currently active* window (often 180k) when the account
+ * can use 1M. Falls back to the static roster's stated window otherwise.
+ */
+function qoderMaxContextFor(modelId: string, modelConfig: QoderModelConfig, realm: QoderRealm): number {
+  const discovered = qoderDiscoveredMaxContexts(realm).get(modelId);
+  if (discovered !== undefined) return discovered;
+  return modelConfig.max_input_tokens;
+}
+
 function qoderRequestedMaxTokens(request: CanonicalRequest, modelConfig: QoderModelConfig): number {
   /**
    * The ceiling is the roster's stated one. A fixed 32k fallback would clamp
@@ -925,7 +950,11 @@ export function buildQoderRequest(
       url: "",
       is_vl: modelConfig.is_vl,
       is_reasoning: modelConfig.is_reasoning,
-      max_input_tokens: modelConfig.max_input_tokens,
+      // Send the widest selectable window from the live list's `context_config`
+      // (falling back to the static roster's stated window). Without this, the
+      // request would declare the *currently active* window — often 180k — even
+      // when the account can use 1M, capping the conversation the upstream sees.
+      max_input_tokens: qoderMaxContextFor(modelId, modelConfig, realm),
       // Mirrors the roster's stated ceiling. A fixed 32k fallback would be sent
       // for every model alike, so the request would declare a cap the catalog
       // does not publish.
@@ -949,9 +978,89 @@ export function buildQoderRequest(
   };
 }
 
+/**
+ * Builds the modern model-server (`/model/v1/chat/completions`) request body.
+ *
+ * It reuses the message translation from `buildQoderRequest` (tool turns,
+ * reasoning echo, image parts) and wraps the result in the OpenAI-shaped body
+ * the IDE surface expects: top-level `model`, `messages`, `stream_options`,
+ * and a `metadata.context`/`metadata.business` block. `model` is the roster
+ * key after virtual-name resolution, so the upstream never sees a virtual id
+ * (which it answers by falling back to `auto`).
+ */
+export function buildQoderIdeRequest(
+  modelId: string,
+  request: CanonicalRequest,
+  modelConfig: QoderModelConfig,
+  auth: QoderAuth,
+  realm: QoderRealm = "intl",
+  version = getQoderVersion(),
+): Record<string, unknown> {
+  const legacy = buildQoderRequest(modelId, request, modelConfig, auth, realm);
+  const messages = legacy.messages as Array<Record<string, unknown>>;
+  return {
+    model: modelId,
+    messages,
+    stream: true,
+    stream_options: { include_usage: true },
+    metadata: {
+      context: {
+        request_id: legacy.request_id,
+        request_set_id: legacy.request_set_id,
+        session_id: legacy.session_id,
+        source_session_id: "",
+        task_id: "common",
+        client_type: "5",
+      },
+      business: {
+        business_product: "cli",
+        business_type: "agent",
+        business_version: version,
+        scene: "assistant",
+      },
+    },
+    max_tokens: (legacy.max_tokens as number) ?? 65_536,
+  };
+}
+
+/** Identity headers for the modern model-server surface (plain bearer). */
+function qoderIdeHeaders(auth: QoderAuth, version: string): Record<string, string> {
+  return {
+    Authorization: `Bearer ${auth.securityOauthToken}`,
+    "Content-Type": "application/json",
+    Accept: "text/event-stream",
+    "X-Request-ID": randomUUID(),
+    "X-Session-ID": randomUUID(),
+    "Cosy-Version": version,
+    "Cosy-ClientType": "5",
+    "Cosy-MachineOS": qoderMachineOs(),
+    "Cosy-MachineHostname": "DESKTOP-QODER",
+    "Cosy-MachineId": auth.machineId,
+    "Cosy-MachineToken": auth.machineId,
+    "Cosy-MachineType": "5",
+  };
+}
+
+async function callQoderIde(
+  url: string,
+  body: Record<string, unknown>,
+  auth: QoderAuth,
+  signal: AbortSignal,
+  fetcher: QoderFetcher,
+  version = getQoderVersion(),
+): Promise<Response> {
+  return fetcher(url, {
+    method: "POST",
+    headers: qoderIdeHeaders(auth, version),
+    body: JSON.stringify(body),
+    signal,
+  });
+}
+
 // Stream transformation — decode SSE, unwrap COSY envelope, map OpenAI chat chunks to CanonicalEvent
 
 function mapQoderFinishReason(raw: unknown): CanonicalStopReason | undefined {
+  if (raw === "stop") return "stop";
   if (raw === "length") return "length";
   if (raw === "tool_calls") return "tool_use";
   if (raw === "content_filter") return "content_filter";
@@ -1000,7 +1109,39 @@ export async function* qoderBodyToCanonicalEvents(
       } catch {
         continue;
       }
+      // IDE surface error event: `{"code":"invalid_model_error","message":"..."}`
+      // carries no choices. Surface it as an upstream failure instead of an
+      // empty successful stream.
+      if (json["error"] !== undefined && json["choices"] === undefined) {
+        const error = json["error"] as Record<string, unknown> | string;
+        const message =
+          typeof error === "string"
+            ? error
+            : typeof error?.["message"] === "string"
+              ? (error["message"] as string)
+              : typeof json["message"] === "string"
+                ? (json["message"] as string)
+                : "Qoder model server error";
+        const code = typeof json["code"] === "string" ? (json["code"] as string) : undefined;
+        throw new GatewayError(
+          code === "invalid_model_error" ? "model_not_found" : "platform_unavailable",
+          code === "invalid_model_error" ? 404 : 502,
+          `${message} (request {requestId}). The upstream came back empty-handed — retry 🌙`,
+          { providerId: QODER_PROVIDER_ID, ...(code === undefined ? {} : { providerCode: code }) },
+          "upstream",
+        );
+      }
       if (json["usage"] && typeof json["usage"] === "object") rawUsage = json["usage"] as Record<string, unknown>;
+      // IDE surface terminal event: `choices:[]` + `raw_usage`. It carries the
+      // final usage and confirms the turn ended, so record it and synthesize a
+      // stop reason — the terminal event has no `choices[].finish_reason`.
+      if (json["raw_usage"] && typeof json["raw_usage"] === "object") {
+        const rawUsageObj = json["raw_usage"] as Record<string, unknown>;
+        rawUsage = (rawUsageObj["data"] as Record<string, unknown> | undefined) ?? rawUsageObj;
+        if (json["choices"] === undefined || (json["choices"] as unknown[]).length === 0) {
+          finishReason = finishReason ?? "stop";
+        }
+      }
       const choices = (json["choices"] as Array<Record<string, unknown>>) ?? [];
       for (const choice of choices) {
         const delta = choice["delta"] as Record<string, unknown> | undefined;
@@ -1126,12 +1267,16 @@ export async function* qoderBodyToCanonicalEvents(
           }
         }
         const fr = choice["finish_reason"];
-        if (fr !== null && fr !== undefined) finishReason = fr;
+        // The IDE surface sends an empty string (`""`) for the per-delta finish
+        // reason, which is not a real stop signal — only a value that maps to a
+        // canonical stop reason (or the terminal `[DONE]` frame) ends the turn.
+        if (fr !== null && fr !== undefined && fr !== "") finishReason = fr;
         // Some providers send usage in choices[0].usage or top-level
         if (choice["usage"] && typeof choice["usage"] === "object") rawUsage = choice["usage"] as Record<string, unknown>;
       }
-      // Some Qoder chunks carry finish_reason at top level
-      if (json["finish_reason"] !== undefined) finishReason = json["finish_reason"];
+      // Some Qoder chunks carry finish_reason at top level (empty string means
+      // no stop signal, same as the per-delta field).
+      if (json["finish_reason"] !== undefined && json["finish_reason"] !== "") finishReason = json["finish_reason"];
     }
   }
   // End of stream: recover a held-back marker+JSON echo. A valid echo becomes
@@ -1166,7 +1311,12 @@ export async function* qoderBodyToCanonicalEvents(
       }
     }
   }
-  // If no terminal arrived, synthesize one (prevents truncation error)
+  // A `[DONE]` frame from the IDE surface may be the only terminal signal (the
+  // per-delta `finish_reason` is empty and `raw_usage` is not always sent), so
+  // a clean end-of-stream with no finish reason is a normal stop, not a
+  // truncation. If no terminal arrived at all, still synthesize one (prevents
+  // truncation error).
+  if (hasTerminal && finishReason === undefined) finishReason = "stop";
   const stopReason = mapQoderFinishReason(finishReason);
   const _providerStop = typeof finishReason === "string" ? finishReason : undefined;
   void hasTerminal;
@@ -1202,16 +1352,28 @@ interface QoderAdapterOptions {
   readonly realm?: QoderRealm;
   /** Bundled provider id, so the adapter's own id matches the route's. */
   readonly providerId?: string;
+  /**
+   * Which chat surface to dispatch on.
+   *
+   * `ide` (default) uses the modern model-server surface
+   * (`/model/v1/chat/completions`, plain bearer, OpenAI-shaped chunks): it
+   * streams immediately. The legacy `cosy` surface (`/algo/.../agent_chat_generation`)
+   * answers `10605 isQueued` and parks requests in a server queue, so it is a
+   * fallback, not a default.
+   */
+  readonly surface?: "ide" | "cosy";
 }
 
 class QoderAdapter implements ProviderAdapter {
   readonly provider_id: ProviderId;
   private readonly realm: QoderRealm;
+  private readonly surface: "ide" | "cosy";
   private readonly fetchFn: typeof fetch;
 
   constructor(options: QoderAdapterOptions = {}) {
     this.provider_id = (options.providerId ?? QODER_PROVIDER_ID) as ProviderId;
     this.realm = options.realm ?? "intl";
+    this.surface = options.surface ?? "ide";
     this.fetchFn = options.fetch ?? globalThis.fetch;
   }
 
@@ -1234,7 +1396,7 @@ class QoderAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat") {
-      throw new GatewayError("capability_unsupported", 400, `qoder supports chat only, got ${candidate.wire_family}`);
+      assertWireFamily(candidate, "chat", "qoder");
     }
     const secret = readCredentialSecret(context.credential, "Qoder credential is required");
 
@@ -1251,7 +1413,7 @@ class QoderAdapter implements ProviderAdapter {
       throw new GatewayError(
         "model_not_found",
         404,
-        `Qoder virtual model ${requestedModelId} resolves to a roster key this realm does not serve`,
+        `Qoder virtual model ${requestedModelId} resolves to a roster key this realm does not serve (request {requestId}). Try another model — this one's off the menu 📚`,
         { virtual_model: requestedModelId, target: qoderDispatchModelId(requestedModelId) },
         "upstream",
       );
@@ -1281,7 +1443,6 @@ class QoderAdapter implements ProviderAdapter {
       const auth = isQoderPat(secret)
         ? await exchangeQoderPat(secret, lifecycle.signal, fetcher, version, this.realm)
         : qoderOAuthAuth(secret, context.credential.auth_state, context.credential.account_id);
-      const qoderBody = buildQoderRequest(modelId, request, modelConfig, auth, this.realm);
       // A full URL from the route wins, but the fallback is this realm's
       // gateway — not the intl host hardcoded into `MODERN_PROFILE`. Dispatching
       // a CN credential to `*.qoder.sh` is refused outright. The host order
@@ -1290,11 +1451,18 @@ class QoderAdapter implements ProviderAdapter {
       const url =
         candidate.endpoint_path && candidate.endpoint_path.startsWith("http")
           ? candidate.endpoint_path
-          : `${qoderInferenceCandidates(this.realm, auth.securityOauthToken)[0] ?? ""}${QODER_CHAT_PATH}`;
+          : this.surface === "ide"
+            ? qoderIdeChatUrl(this.realm)
+            : `${qoderInferenceCandidates(this.realm, auth.securityOauthToken)[0] ?? ""}${QODER_CHAT_PATH}`;
 
-      const response = await callQoder(url, qoderBody, modelId, auth, lifecycle.signal, fetcher, version);
+      // The modern IDE surface streams immediately and needs no COSY signing;
+      // the legacy COSY surface is kept as an explicit fallback.
+      const response =
+        this.surface === "ide"
+          ? await callQoderIde(url, buildQoderIdeRequest(modelId, request, modelConfig, auth, this.realm, version), auth, lifecycle.signal, fetcher, version)
+          : await callQoder(url, buildQoderRequest(modelId, request, modelConfig, auth, this.realm), modelId, auth, lifecycle.signal, fetcher, version);
       if (!response.ok) throw await mapUpstreamHttpError(response, "qoder");
-      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Qoder returned empty body", {}, "upstream");
+      if (!response.body) throw new GatewayError("platform_unavailable", 502, "Qoder returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       // Headers arrived: the pre-stream deadline has served its purpose.
       // From here the gateway stall/first-chunk watchdog (propagated via
       // context.abort_signal) governs the body. Keeping this timer armed

package/src/providers/integrations/tokenharbor.ts

@@ -71,11 +71,11 @@ export const TOKENHARBOR_FALLBACK_MODELS: readonly ModelDefinition[] = [
 function tokenharborPrePayload(payload: Record<string, unknown>): void {
   const model = payload["model"];
   if (typeof model !== "string" || model.length === 0) {
-    throw new GatewayError("invalid_request", 400, "TokenHarbor model is required");
+    throw new GatewayError("invalid_request", 400, "TokenHarbor model is required (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
   // Strip accidental query-string smuggling (mirrors the factory's own guard)
   if (model.includes("?")) {
-    throw new GatewayError("invalid_request", 400, "TokenHarbor model must not contain query string");
+    throw new GatewayError("invalid_request", 400, "TokenHarbor model must not contain query string (request {requestId}). Check the shape of what you sent — then resend 🪞");
   }
 }
 

package/src/providers/integrations/trae/trae.ts

@@ -10,6 +10,7 @@ import type { UsageRecord } from "../../../protocol/canonical-model";
 import { usageFromProvider } from "../../provider-usage";
 import {
   readCredentialSecret,
+  assertWireFamily,
   type ProviderAdapter,
   type ProviderDispatchContext,
   type ProviderDispatchTarget,
@@ -67,7 +68,7 @@ const STOP_REASONS: Readonly<Record<string, CanonicalStopReason>> = {
 function traeAuth(secret: string, accountId: string | undefined): TraeAuth {
   const token = extractToken(secret);
   if (token === undefined) {
-    throw new GatewayError("authentication_failed", 401, "Trae credential has no access token", {}, "upstream");
+    throw new GatewayError("authentication_failed", 401, "Trae credential has no access token (request {requestId}). Wrong key, right door — check the credential 🔑", {}, "upstream");
   }
   return { token, uid: accountId ?? "" };
 }
@@ -116,7 +117,7 @@ function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
     throw new GatewayError(
       "authentication_failed",
       401,
-      `Trae could not authenticate the account (upstream code 1001): ${message}`,
+      `Trae could not authenticate the account (upstream code 1001): ${message} (request {requestId}). Wrong key, right door — check the credential 🔑`,
       { providerCode: "1001", providerStatus: 1001, credentialEvidence: true },
       "upstream",
     );
@@ -127,7 +128,7 @@ function throwTraeUpstreamError(codeRaw: unknown, messageRaw: unknown): never {
     throw new GatewayError(
       "quota_exceeded",
       429,
-      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message}`,
+      `Trae quota exceeded (upstream code ${code ?? "unknown"}): ${message} (request {requestId}). You've maxed this window — pace yourself ⏳`,
       { providerCode: code ?? "4008", providerStatus: code === "4008" ? 4008 : 429 },
       "upstream",
     );
@@ -152,11 +153,7 @@ class TraeAdapter implements ProviderAdapter {
     context: ProviderDispatchContext,
   ): AsyncIterable<CanonicalEvent> {
     if (candidate.wire_family !== "chat") {
-      throw new GatewayError(
-        "capability_unsupported",
-        400,
-        `trae supports chat only, got ${candidate.wire_family}`,
-      );
+      assertWireFamily(candidate, "chat", "trae");
     }
     const secret = readCredentialSecret(context.credential, "Trae credential is required");
     const modelId = candidate.model_id || request.model;
@@ -214,7 +211,7 @@ class TraeAdapter implements ProviderAdapter {
       });
       if (!response.ok) throw await mapUpstreamHttpError(response, this.provider_id);
       if (!response.body) {
-        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body", {}, "upstream");
+        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body (request {requestId}). The upstream came back empty-handed — retry 🌙", {}, "upstream");
       }
       // Headers arrived, so the pre-stream deadline has served its purpose;
       // from here the gateway's own stall watchdog governs the body.

package/src/providers/integrations/zcode/oauth.ts

@@ -78,7 +78,7 @@ function unwrapEnvelope(body: unknown, operation: string): unknown {
       // codebase is 401. A 400 told the client to fix its body when the real
       // action is to fix the credential — and HTTP itself reserves 401 for
       // exactly this, so a standard client reads the class from the status.
-      throw new GatewayError("authentication_failed", 401, `Z.AI ${message}`, { providerId: "zcode" });
+      throw new GatewayError("authentication_failed", 401, `Z.AI ${message} (request {requestId}). Wrong key, right door — check the credential 🔑`, { providerId: "zcode" });
     }
   }
   return root.data ?? body;

package/src/providers/operations/account-error-classification.ts

@@ -251,15 +251,13 @@ export interface AccountErrorClassification {
   /**
    * True when this write changed a field the routing snapshot actually reads.
    *
-   * The snapshot projects `provider_accounts.status` and
-   * `.cooldownUntil` and nothing else (`route-catalog.ts:286-287`), so only a
-   * write that moves one of those has to drop it. Everything else a failure
-   * persists — the failure streak, the error text, the category, a
-   * model-scoped cooldown — is invisible to routing, and invalidating for it
-   * forced the next request to rebuild an 11-SELECT snapshot for no reason.
+   * Routing reads account-wide `status`/`cooldownUntil` and the per-model
+   * `modelCooldowns` map (`route-catalog.ts`). Writes to any of those must drop
+   * the snapshot; failure streaks and diagnostic text remain invisible to
+   * routing.
    *
-   * That made a failure wave self-sustaining: N failed attempts produced N
-   * invalidations, and every following request paid the full rebuild.
+   * Only a changed deadline is routing-visible. Re-reporting the same active
+   * model cooldown must not rebuild the snapshot again.
    */
   readonly routesVisible: boolean;
   /**

package/src/providers/operations/account-health-service.ts

@@ -147,13 +147,13 @@ export async function recordAccountFailure(
       // Monotonic: never move an in-force window earlier (see `latestDeadlineMs`).
       // A provider-stated deadline wins outright because it is already the later
       // of the two whenever the provider really parked the pair longer.
-      const nextUntil = new Date(
-        latestDeadlineMs(
-          effective.retryAt?.getTime(),
-          Date.now() + (unsupportedCooldownMs ?? escalatedCooldownMs),
-          existing[modelId] ? Date.parse(existing[modelId]!) : undefined,
-        ),
-      ).toISOString();
+      const previousDeadline = existing[modelId] === undefined ? undefined : Date.parse(existing[modelId]);
+      const nextDeadline = latestDeadlineMs(
+        effective.retryAt?.getTime(),
+        Date.now() + (unsupportedCooldownMs ?? escalatedCooldownMs),
+        previousDeadline,
+      );
+      const nextUntil = new Date(nextDeadline).toISOString();
       const previousUntil = existing[modelId];
       // A re-statement is not an event: what the audit row reports is the
       // *entry* into a cooling episode, and the deadline itself is not a
@@ -213,10 +213,10 @@ export async function recordAccountFailure(
           createdAt: now,
         });
       }
-      // `status` and `cooldownUntil` are untouched on this path — only the
-      // (account, model) pair backed off — so the snapshot is still accurate
-      // and must not be dropped.
-      return { ...classification, routesVisible: false };
+      // The route catalog projects modelCooldowns and stamps this candidate as
+      // model_cooldown. Invalidate when its deadline changes, or the cached
+      // snapshot keeps routing this pair until some unrelated write rebuilds it.
+      return { ...classification, routesVisible: previousDeadline !== nextDeadline };
     }
 
     await client
@@ -550,11 +550,9 @@ export async function reportAttemptOutcome(
     ...report.evidence,
     ...(report.modelId === undefined ? {} : { modelId: report.modelId }),
   }).catch(() => null);
-  // Gated on `routesVisible`, not on `mutatesAccount`: a failure that only
-  // cooled one (account, model) pair, or only advanced the streak, changed
-  // nothing routing reads. Invalidating for those rebuilt an 11-SELECT snapshot
-  // on the next request, and under a failure wave each rebuild fed the next
-  // invalidation.
+  // Gated on `routesVisible`, not on `mutatesAccount`: a model cooldown changes
+  // routing, while a repeated report with the same deadline or a streak-only
+  // write does not.
   if (classification?.routesVisible) await report.snapshotService?.invalidate();
 }