cartethyia 2.4.5 → 2.5.0

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

@@ -0,0 +1,458 @@
+// Trae adapter.
+//
+// Realm-aware: `trae` (intl) and `traecn` (CN) share this code but nothing of
+// the address, the authorization scheme, or the roster. The intl deployment
+// additionally gates on the *current* client version, which is why the version
+// here comes from `getTraeVersion()` (a live resolver) rather than a constant.
+
+import { GatewayError } from "../../../protocol/gateway-error";
+import type { CanonicalEvent, CanonicalRequest, CanonicalStopReason } from "../../../protocol/canonical-model";
+import { usageFromProvider } from "../../provider-usage";
+import {
+  readCredentialSecret,
+  type ProviderAdapter,
+  type ProviderDispatchContext,
+  type ProviderDispatchTarget,
+  type ProviderId,
+} from "../../provider-contracts";
+import { mapUpstreamHttpError } from "../../../transport/failure-policy";
+import { getTraeVersion } from "../../operations/client-versions";
+import { abortGatewayError, createUpstreamDeadlineLifecycle } from "../../operations/upstream-deadline";
+import { TRAE_CN_MODELS, TRAE_INTL_MODELS, traeMaxContextWindow } from "./trae-catalog";
+import { buildTraeHeaders } from "./trae-headers";
+import {
+  buildTraeChatBody,
+  isTraeAgentEndpoint,
+  parseTraeSse,
+  toTraeAgentBody,
+  TRAE_AGENT_ENDPOINT,
+  TRAE_CHAT_ENDPOINT,
+} from "./trae-protocol";
+import { TRAE_REGION_CORE_HOSTS, traeCoreCandidates, type TraeRealm } from "./trae-realm";
+
+export interface TraeAdapterOptions {
+  readonly providerId?: string;
+  readonly realm?: TraeRealm;
+  readonly fetch?: typeof fetch;
+}
+
+/** Identity resolved from a persisted credential. */
+interface TraeAuth {
+  readonly token: string;
+  readonly uid: string;
+}
+
+const TRAE_PROVIDER_ID = "trae";
+const TRAE_CN_PROVIDER_ID = "traecn";
+
+/** Upstream finish reason → canonical stop reason. */
+const STOP_REASONS: Readonly<Record<string, CanonicalStopReason>> = {
+  stop: "stop",
+  length: "length",
+  tool_calls: "tool_use",
+  function_call: "tool_use",
+  content_filter: "content_filter",
+};
+
+/**
+ * Reads the credential.
+ *
+ * Trae credentials are OAuth token pairs, so the whole JSON export is the
+ * secret: extracting only the access token would drop the refresh token and
+ * leave the account permanently unrefreshable. The refresh itself runs through
+ * the registered OAuth refresher (`trae-oauth.ts`), not here — this only needs
+ * the access token to authorize a request.
+ */
+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");
+  }
+  return { token, uid: accountId ?? "" };
+}
+
+function extractToken(secret: string): string | undefined {
+  const trimmed = secret.trim();
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed) as Record<string, unknown>;
+      const candidates = ["accessToken", "access_token", "token", "x-ide-token"];
+      for (const key of candidates) {
+        const value = parsed[key];
+        if (typeof value === "string" && value.length > 0) return value;
+      }
+    } catch {
+      // Fall through to the bare-token reading below.
+    }
+  }
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+class TraeAdapter implements ProviderAdapter {
+  readonly provider_id: ProviderId;
+  private readonly realm: TraeRealm;
+  private readonly fetchFn: typeof fetch;
+  /**
+   * Maps a frame's `index` to the call id seen for it.
+   *
+   * Argument fragments arrive without the id, so the association has to be
+   * remembered between frames rather than read from the fragment itself.
+   */
+  readonly #toolCallIds = new Map<string, string>();
+
+  constructor(options: TraeAdapterOptions = {}) {
+    this.provider_id = (options.providerId ?? TRAE_PROVIDER_ID) as ProviderId;
+    this.realm = options.realm ?? "intl";
+    this.fetchFn = options.fetch ?? globalThis.fetch;
+  }
+
+  async *dispatch(
+    request: CanonicalRequest,
+    candidate: ProviderDispatchTarget,
+    context: ProviderDispatchContext,
+  ): AsyncIterable<CanonicalEvent> {
+    if (candidate.wire_family !== "chat") {
+      throw new GatewayError(
+        "capability_unsupported",
+        400,
+        `trae supports chat only, got ${candidate.wire_family}`,
+      );
+    }
+    const secret = readCredentialSecret(context.credential, "Trae credential is required");
+    const modelId = candidate.model_id || request.model;
+    const lifecycle = createUpstreamDeadlineLifecycle(context);
+    const outboundFetch =
+      (context.outbound_fetch as unknown as typeof fetch | undefined) ?? this.fetchFn;
+
+    // intl refuses a stale client version with 4015, so the resolved version is
+    // part of every request rather than a startup detail.
+    const version = getTraeVersion();
+    const auth = traeAuth(secret, context.credential.account_id);
+    const body = buildTraeChatBody(modelId, request, this.realm);
+    /**
+     * The endpoint follows the model, not the provider.
+     *
+     * Trae's two surfaces are disjoint and neither serves the other's ids, so
+     * the roster's own `endpoint_path` decides. Falling back to the agent path
+     * rather than the chat one matters: the intl catalog is agent-only, and a
+     * caller whose target carries no route would otherwise land on a surface
+     * that rejects every model in it.
+     */
+    const agentSurface = isTraeAgentEndpoint(candidate.endpoint_path);
+    const payload = agentSurface ? toTraeAgentBody(body) : body;
+    const headers = buildTraeHeaders({
+      realm: this.realm,
+      token: auth.token,
+      uid: auth.uid,
+      clientVersion: version,
+      stream: true,
+    });
+
+    const primary = traeCoreForAccount(this.realm, context.credential.auth_state);
+    const path = agentSurface ? TRAE_AGENT_ENDPOINT : TRAE_CHAT_ENDPOINT;
+    const url =
+      candidate.endpoint_path && candidate.endpoint_path.startsWith("http")
+        ? candidate.endpoint_path
+        : `${primary}${path}`;
+
+    try {
+      const response = await outboundFetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: lifecycle.signal,
+      });
+      if (!response.ok) throw await mapUpstreamHttpError(response, this.provider_id);
+      if (!response.body) {
+        throw new GatewayError("platform_unavailable", 502, "Trae returned empty body", {}, "upstream");
+      }
+      // Headers arrived, so the pre-stream deadline has served its purpose;
+      // from here the gateway's own stall watchdog governs the body.
+      lifecycle.release();
+      yield* this.#events(
+        response.body as ReadableStream<Uint8Array>,
+        lifecycle.signal,
+        request.model,
+      );
+    } catch (err: unknown) {
+      const abortError = abortGatewayError(lifecycle, err, context.abort_signal);
+      if (abortError) throw abortError;
+      throw err;
+    } finally {
+      lifecycle.release();
+    }
+  }
+
+  async *#events(
+    body: ReadableStream<Uint8Array>,
+    _signal: AbortSignal,
+    requestModel: string,
+  ): AsyncIterable<CanonicalEvent> {
+    let seq = 1;
+    yield { type: "response_start", sequence_number: seq++, model: requestModel } as CanonicalEvent;
+    let stopReason: CanonicalStopReason = "stop";
+    let usage: Record<string, unknown> | undefined;
+    /**
+     * Tool calls arrive fragmented across frames and the id is not repeated.
+     *
+     * Upstream streams one `tool_calls` array per frame where only the first
+     * carries `id`, only early frames carry `name`, and `arguments` arrives as
+     * successive JSON fragments. So name is announced once on first sight of
+     * the id and arguments are accumulated; emitting each frame verbatim would
+     * produce several calls with empty ids.
+     */
+    const announced = new Set<string>();
+
+    for await (const frame of parseTraeSse(body)) {
+      if (frame.event === "done") {
+        const data = frame.data as { finish_reason?: unknown };
+        if (typeof data.finish_reason === "string") {
+          stopReason = STOP_REASONS[data.finish_reason] ?? "stop";
+        }
+        continue;
+      }
+      if (frame.event === "error") {
+        const data = frame.data as { message?: unknown };
+        const message = typeof data.message === "string" ? data.message : "Trae stream error";
+        throw new GatewayError("platform_unavailable", 502, message, {}, "upstream");
+      }
+      if (typeof frame.data !== "object" || frame.data === null) continue;
+      const record = frame.data as Record<string, unknown>;
+      /**
+       * Two frame layouts reach here and both are live.
+       *
+       * The donor's client nests the answer under `chunk`; the region host this
+       * gateway talks to sends it flat — `event: output` with
+       * `{"response":"…"}` — and reports usage as a separate `token_usage`
+       * frame with the OpenAI spelling at the top level. Reading only `chunk`
+       * made a working upstream look like an empty stream.
+       */
+      const chunk = record["chunk"];
+      if (typeof chunk !== "object" || chunk === null) {
+        const flat = record["response"];
+        if (typeof flat === "string" && flat.length > 0) {
+          yield {
+            type: "content_delta",
+            sequence_number: seq++,
+            content: { kind: "text", text: flat },
+          } as CanonicalEvent;
+        }
+        const flatReasoning = record["reasoning_content"];
+        if (typeof flatReasoning === "string" && flatReasoning.length > 0) {
+          yield {
+            type: "content_delta",
+            sequence_number: seq++,
+            content: { kind: "reasoning", payload: flatReasoning, summary: flatReasoning },
+          } as CanonicalEvent;
+        }
+        yield* this.#toolCallDeltas(record["tool_calls"], announced, () => seq++);
+        if (typeof record["finish_reason"] === "string") {
+          stopReason = STOP_REASONS[record["finish_reason"] as string] ?? "stop";
+        }
+        // `token_usage` frames carry the counters themselves, not under `usage`.
+        const counters =
+          record["usage"] !== undefined && typeof record["usage"] === "object"
+            ? (record["usage"] as Record<string, unknown>)
+            : frame.event === "token_usage" || record["prompt_tokens"] !== undefined
+              ? record
+              : undefined;
+        if (counters !== undefined) usage = counters;
+        continue;
+      }
+      const payload = chunk as Record<string, unknown>;
+      const text = payload["content"];
+      if (typeof text === "string" && text.length > 0) {
+        yield {
+          type: "content_delta",
+          sequence_number: seq++,
+          content: { kind: "text", text },
+        } as CanonicalEvent;
+      }
+      const reasoning = payload["reasoning_content"];
+      if (typeof reasoning === "string" && reasoning.length > 0) {
+        yield {
+          type: "content_delta",
+          sequence_number: seq++,
+          content: { kind: "reasoning", payload: reasoning, summary: reasoning },
+        } as CanonicalEvent;
+      }
+      if (typeof payload["finish_reason"] === "string") {
+        stopReason = STOP_REASONS[payload["finish_reason"]] ?? "stop";
+      }
+      if (typeof payload["usage"] === "object" && payload["usage"] !== null) {
+        usage = payload["usage"] as Record<string, unknown>;
+      }
+    }
+
+    if (usage !== undefined) {
+      yield* this.#usageEvent(usage, seq++);
+    }
+    // The canonical terminal is `terminal`; a stream that ends without one is
+    // read as "the upstream never reported a result".
+    yield {
+      type: "terminal",
+      sequence_number: seq,
+      state: "complete",
+      stop_reason: stopReason,
+    } as unknown as CanonicalEvent;
+  }
+
+  /**
+   * Emits canonical tool-call deltas from one `tool_calls` array.
+   *
+   * Upstream nests the payload under `function_call`, not OpenAI's `function`,
+   * and spreads one call over many frames with three different shapes: the
+   * first carries id and name, the middle ones carry `arguments` as successive
+   * JSON fragments with an **empty** id, and the last repeats the id with no
+   * arguments. Grouping by `index` is what ties them together — the id is
+   * absent exactly when the arguments are present, so keying on id would drop
+   * every fragment and yield `arguments: "{}"`.
+   */
+  async *#toolCallDeltas(
+    raw: unknown,
+    announced: Set<string>,
+    nextSeq: () => number,
+  ): AsyncIterable<CanonicalEvent> {
+    if (!Array.isArray(raw)) return;
+    for (const entry of raw) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const call = entry as Record<string, unknown>;
+      const fn = call["function_call"];
+      const fnRecord = typeof fn === "object" && fn !== null ? (fn as Record<string, unknown>) : undefined;
+      const name = typeof fnRecord?.["name"] === "string" ? (fnRecord["name"] as string) : undefined;
+      const args = typeof fnRecord?.["arguments"] === "string" ? (fnRecord["arguments"] as string) : "";
+      const declaredId = typeof call["id"] === "string" ? call["id"] : "";
+      const index = typeof call["index"] === "number" ? call["index"] : 0;
+      const slot = `idx:${index}`;
+
+      if (declaredId.length > 0) {
+        this.#toolCallIds.set(slot, declaredId);
+        // The closing frame repeats a known id with no payload; emitting it
+        // again would append a duplicate empty call.
+        if (announced.has(declaredId)) continue;
+        announced.add(declaredId);
+        yield {
+          type: "tool_call_delta",
+          sequence_number: nextSeq(),
+          call_id: declaredId,
+          name: name ?? "",
+          arguments_delta: "",
+        } as CanonicalEvent;
+        continue;
+      }
+
+      if (args.length === 0) continue;
+      const id = this.#toolCallIds.get(slot);
+      if (id === undefined) continue;
+      yield {
+        type: "tool_call_delta",
+        sequence_number: nextSeq(),
+        call_id: id,
+        arguments_delta: args,
+      } as CanonicalEvent;
+    }
+  }
+
+  /**
+   * Emits the terminal usage event, or none at all.
+   *
+   * Trae reports usage with the OpenAI spelling (`prompt_tokens` /
+   * `completion_tokens`). `usageFromProvider` normalizes both spellings and
+   * returns `undefined` when nothing was actually reported, and an absent
+   * usage event is correct in that case — emitting zeros would record a
+   * request that cost nothing.
+   */
+  async *#usageEvent(usage: Record<string, unknown>, seq: number): AsyncIterable<CanonicalEvent> {
+    const record = usageFromProvider(usage);
+    if (record === undefined) return;
+    yield { type: "usage", sequence_number: seq, usage: record } as unknown as CanonicalEvent;
+  }
+}
+
+export function createTraeAdapter(options: TraeAdapterOptions = {}): ProviderAdapter {
+  return new TraeAdapter(options);
+}
+
+/** Adapter for the China deployment: different host, auth scheme, and roster. */
+export function createTraeCnAdapter(options: TraeAdapterOptions = {}): ProviderAdapter {
+  return new TraeAdapter({
+    ...options,
+    realm: "cn",
+    providerId: TRAE_CN_PROVIDER_ID,
+  });
+}
+
+/**
+ * Live model discovery.
+ *
+ * The listing is per account region, not per realm: it answers on CN and on the
+ * intl region host that serves the account (`coresg-normal.trae.ai` verified),
+ * while the generic intl core answers `403 no schema found`. An empty result is
+ * therefore a real "this account has no listing", and the static roster stays
+ * the fallback rather than being replaced by nothing.
+ */
+export async function discoverTraeModels(input: {
+  readonly realm: TraeRealm;
+  readonly token: string;
+  readonly uid: string;
+  readonly fetcher: typeof fetch;
+  readonly signal?: AbortSignal;
+  readonly providerId?: string;
+  /** Account region, so the listing is asked of the host that serves it. */
+  readonly region?: string;
+}): Promise<readonly { id: string; ctx: number | undefined }[]> {
+  const headers = buildTraeHeaders({
+    realm: input.realm,
+    token: input.token,
+    uid: input.uid,
+  });
+  const url = `${traeCoreForAccount(input.realm, input.region === undefined ? undefined : { region: input.region })}/api/ide/v1/model_list`;
+  const response = await input.fetcher(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({ type: "chat" }),
+    ...(input.signal ? { signal: input.signal } : {}),
+  });
+  if (!response.ok) return [];
+  const parsed = (await response.json()) as {
+    data?: unknown;
+    models?: unknown;
+    model_configs?: unknown;
+  };
+  const rows = Array.isArray(parsed.model_configs)
+    ? parsed.model_configs
+    : Array.isArray(parsed.models)
+      ? parsed.models
+      : Array.isArray(parsed.data)
+        ? parsed.data
+        : [];
+  return rows
+    .filter((row): row is Record<string, unknown> => typeof row === "object" && row !== null)
+    .map((row) => ({
+      // `model_name` is the key upstream's listing uses; the others are the
+      // spellings the older donors assumed.
+      id: String(row["model_name"] ?? row["name"] ?? row["id"] ?? "").trim(),
+      ctx: traeMaxContextWindow(row),
+    }))
+    .filter((row) => row.id.length > 0);
+}
+
+export { TRAE_CN_MODELS, TRAE_INTL_MODELS };
+
+/**
+ * Core host for one account.
+ *
+ * An intl account is provisioned into a region and its token only authenticates
+ * against that region's host, so the account's own `region` wins over the
+ * realm default. Falling back to the realm keeps older accounts (stored before
+ * the region was captured) working exactly as before.
+ */
+function traeCoreForAccount(
+  realm: TraeRealm,
+  authState: Readonly<Record<string, unknown>> | undefined,
+): string {
+  const region = typeof authState?.["region"] === "string" ? authState["region"].toLowerCase() : "";
+  const regional = TRAE_REGION_CORE_HOSTS[region];
+  if (regional !== undefined) return regional;
+  return traeCoreCandidates(realm)[0] ?? "";
+}

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

@@ -1,3 +1,4 @@
+import { healthEventBuffer } from "../../persistence/health-event-flush";
 // Account health: error classification, failure/success recording, recovery and cooldown sweeps.
 import { and, desc, eq, inArray, isNotNull, lte, or, sql } from "drizzle-orm";
 import { affectedRows, pruneExpiredCooldowns } from "../../persistence/dialect";
@@ -214,6 +215,20 @@ export interface AccountErrorClassification {
   readonly reason: string;
   readonly retryAt: Date | null;
   readonly mutatesAccount: boolean;
+  /**
+   * 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.
+   *
+   * That made a failure wave self-sustaining: N failed attempts produced N
+   * invalidations, and every following request paid the full rebuild.
+   */
+  readonly routesVisible: boolean;
   /**
    * True when `cooldownMs` came from the provider's own statement — a parsed
    * `Retry-After`-family header, or a reset quoted in its message — rather than
@@ -390,6 +405,11 @@ export function classifyAccountError(
     reason: origin === "upstream" ? rawUpstreamResponse ?? message.slice(0, 160) : explanation,
     retryAt,
     mutatesAccount,
+    // Set below by the caller that knows which columns it wrote, not here:
+    // the same classification feeds both the account-wide path (status +
+    // cooldownUntil — routing-visible) and the model-scoped path (neither —
+    // invisible). Defaulting true keeps existing callers conservative.
+    routesVisible: true,
     providerStated,
     modelUnsupported,
   });
@@ -457,6 +477,16 @@ export function classifyAccountError(
     !priceRefusal &&
     !deploymentInfraError &&
     (statusCode === 402 ||
+      // Qoder answers an exhausted credit balance with
+      // `{"code":"112","message":"{\"pricingUrl\":...}"}` — the body points at
+      // the pricing page, i.e. "buy more", which is a balance verdict, not an
+      // auth one. It fell through to `auth_invalidated` and the console showed
+      // "Re-login required" on an account whose credential was fine, sending
+      // operators to re-authenticate instead of topping up.
+      // Recognising it here keeps it out of `auth_invalidated`; the branch
+      // below scopes the resulting cooldown to the model, because the account
+      // keeps serving its other models.
+      providerCode === "112" ||
       providerCode === "insufficient_quota" ||
       providerCode === "quota_exceeded" ||
       providerCode === "subscription:free-usage-exhausted" ||
@@ -489,7 +519,9 @@ export function classifyAccountError(
       lower.includes("insufficient balance") ||
       lower.includes("out of credits") ||
       lower.includes("credits exhausted") ||
-      lower.includes("spending limit"));
+      lower.includes("spending limit") ||
+      // Same Qoder family reached by body text when the code is not parsed out.
+      (lower.includes("pricingurl") && lower.includes("qoder.com/pricing")));
   // A deterministic content-policy rejection is NOT credential invalidation.
   // CodeBuddy returns HTTP 403 with provider code 11140 ("request illegal",
   // "did not pass the safety review") — refreshing the token cannot change
@@ -687,6 +719,31 @@ export function classifyAccountError(
   }
 
   if (quotaSignal) {
+    /**
+     * Qoder's `112` is a verdict on the (account, model) pair, not on the
+     * credential or the balance as a whole.
+     *
+     * The body is `{"code":"112","message":"{\"pricingUrl\":…}"}` — a link to
+     * the pricing page, i.e. "this model is not in your plan". Observed
+     * behaviour agrees: the account keeps serving every other model after the
+     * refusal. Parking the whole account therefore took healthy models down
+     * with the one that is not entitled, which is the same mistake the
+     * `model_unreachable` branch already avoids for Cursor and buddy.
+     */
+    const qoderPlanGated = providerCode === "112";
+    if (qoderPlanGated) {
+      const hits = Math.max(1, Math.floor(options?.modelBlockHits ?? 1));
+      const cooldownMs = unsupportedModelCooldownMs(hits);
+      return result(
+        "model_unreachable",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        reason("Model not included in this account's plan"),
+        origin === "upstream" && options?.modelId !== undefined,
+        true,
+      );
+    }
     // xAI Grok Build's free tier resets on a rolling window. Use a duration
     // stated by the provider when present; otherwise park for the conservative
     // 24-hour fallback.
@@ -997,8 +1054,8 @@ export async function recordAccountFailure(
           lastErrorAt: now,
         })
         .where(eq(providerAccounts.id, accountId));
-      if (!alreadyCooling && typeof client.insert === "function") {
-        await client.insert(healthEvents).values({
+      if (!alreadyCooling) {
+        await writeHealthEvent(client, {
           entityKind: "account",
           accountId,
           // The account's own status, on both sides: a model-scoped throttle
@@ -1015,7 +1072,10 @@ export async function recordAccountFailure(
           createdAt: now,
         });
       }
-      return classification;
+      // `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 };
     }
 
     await client
@@ -1042,8 +1102,8 @@ export async function recordAccountFailure(
       })
       .where(eq(providerAccounts.id, accountId));
 
-    if (typeof client.insert === "function") {
-      await client.insert(healthEvents).values({
+    {
+      await writeHealthEvent(client, {
         entityKind: "account",
         accountId,
         fromStatus: fromStatus as "active" | "cooldown" | "disabled",
@@ -1054,7 +1114,9 @@ export async function recordAccountFailure(
         createdAt: now,
       });
     }
-    return classification;
+    // This path wrote `status` and `cooldownUntil`, both of which the snapshot
+    // projects, so routing has to see it.
+    return { ...classification, routesVisible: true };
   };
 
   try {
@@ -1176,8 +1238,8 @@ export async function recoverAccount(
         lastErrorAt: null,
       })
       .where(eq(providerAccounts.id, accountId));
-    if (typeof client.insert === "function") {
-      await client.insert(healthEvents).values({
+    {
+      await writeHealthEvent(client, {
         entityKind: "account",
         accountId,
         fromStatus: fromStatus as "active" | "cooldown" | "disabled",
@@ -1314,6 +1376,36 @@ export interface AttemptHealthReport {
   readonly snapshotService?: { invalidate(): unknown };
 }
 
+/**
+ * Writes one health audit row, off the request path when a buffer is installed.
+ *
+ * `health_events` is append-only and read by nobody in the request path, so it
+ * does not need to land before the request finishes — unlike the
+ * `provider_accounts` UPDATE beside it, which routing reads and which therefore
+ * stays synchronous and transactional.
+ */
+async function writeHealthEvent(
+  client: CartethyiaDatabase,
+  row: {
+    readonly entityKind: "account";
+    readonly accountId: string;
+    readonly fromStatus: string;
+    readonly toStatus: string;
+    readonly reason: string;
+    readonly errorCategory: string | null;
+    readonly modelId?: string | null;
+    readonly createdAt: Date;
+  },
+): Promise<void> {
+  const buffer = healthEventBuffer();
+  if (buffer !== undefined) {
+    buffer.enqueue({ ...row, modelId: row.modelId ?? null });
+    return;
+  }
+  if (typeof client.insert !== "function") return;
+  await client.insert(healthEvents).values(row as never);
+}
+
 export async function reportAttemptOutcome(
   db: CartethyiaDatabase,
   report: AttemptHealthReport,
@@ -1328,7 +1420,12 @@ export async function reportAttemptOutcome(
     ...report.evidence,
     ...(report.modelId === undefined ? {} : { modelId: report.modelId }),
   }).catch(() => null);
-  if (classification?.mutatesAccount) await report.snapshotService?.invalidate();
+  // 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.
+  if (classification?.routesVisible) await report.snapshotService?.invalidate();
 }
 
 export async function listAccountHealthEvents(