cartethyia 2.5.3 → 2.5.6

package/src/providers/integrations/shared/connect.ts

@@ -31,12 +31,12 @@ const FRAME_BUFFER_SPARE_BYTES = 1024 * 1024;
 /**
  * Growable byte buffer for reassembling Connect frames across stream reads.
  *
- * Streaming callers used to prepend the unconsumed tail to every read with
- * `Buffer.concat([pending, chunk])`, which copies the entire partial frame on
- * every chunk. A frame that spans many reads (the payload cap allows up to 16 MiB)
- * therefore cost O(n²) copying and peaked at twice the frame size. Appending
- * into spare capacity costs one copy per byte instead, and `consume` only
- * advances an offset, so dropping parsed bytes moves nothing.
+ * Appending into spare capacity costs one copy per byte, where prepending the
+ * unconsumed tail to every read (`Buffer.concat([pending, chunk])`) copies the
+ * entire partial frame on every chunk. A frame that spans many reads (the
+ * payload cap allows up to 16 MiB) therefore costs O(n²) copying and peaks at
+ * twice the frame size. `consume` only advances an offset, so dropping parsed
+ * bytes moves nothing.
  *
  * The view returned by {@link view} is a subarray of the backing store and
  * stays valid until the next {@link append}, which may relocate the bytes.

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

@@ -71,8 +71,7 @@ const TRAE_CN_ROWS: readonly TraeModelRow[] = [
  * are rejected here with `4001 param is invalid`, and the agent ids are
  * rejected there with `4023 model is unknown`. There is no call that serves
  * both, so a single-surface catalog is the only honest one; offering the chat
- * ids would advertise models this provider's dispatch cannot reach. See
- * `documentation/research/trae-agent-vs-chat-surface.md`.
+ * ids would advertise models this provider's dispatch cannot reach.
  *
  * `ctx` is the **selectable maximum** (`context_window_tokens.max`), not the
  * active `dev` window. Upstream advertises both and they differ by up to 5x

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

@@ -0,0 +1,384 @@
+// Trae quota.
+//
+// Two surfaces, on two different hosts, and neither is optional if the account
+// is to be read honestly:
+//
+// - `get_session_usage` on the **core** host is the running meter — what the
+//   account has left of its advanced/premium request buckets and its dollar
+//   balances.
+// - `ide_user_ent_usage` on the **pay** host is the entitlement: which package
+//   the account holds and when it lapses.
+//
+// The donor reads both and lets either fail without the other, and that
+// tolerance is load-bearing here too: entitlement is a *pay* host, which is the
+// first thing a region-blocked or unpaid account loses. Letting a dead pay host
+// fail the whole read would report "no quota" for an account whose session
+// meter is perfectly readable — and "no quota" is what the router parks on.
+//
+// Headers come from `buildTraeHeaders` rather than being rebuilt here: the
+// device fingerprint is derived from the uid, and an account that reports one
+// device here and another at dispatch is exactly the correlation this gateway
+// exists to avoid.
+
+import type {
+  FetchLike,
+  ProviderQuotaResult,
+  ProviderQuotaWindow,
+} from "../../quota/quota-contracts";
+import {
+  cleanError,
+  isoDate,
+  number,
+  percentWindow,
+  record,
+  text,
+} from "../../quota/quota-contracts";
+import type { QuotaCollectionContext } from "../../quota/quota-support";
+import { decodeJwtPayload } from "../../authentication/oauth-flow-store";
+import { buildTraeHeaders } from "./trae-headers";
+import {
+  TRAE_ENT_USAGE_PATH,
+  TRAE_REGION_CORE_HOSTS,
+  TRAE_REALMS,
+  TRAE_SESSION_USAGE_PATH,
+  type TraeRealm,
+} from "./trae-realm";
+
+/**
+ * The buckets `remain_usage` carries, in the order the donor reads them.
+ *
+ * `advanced_model` and `premium_model_*` are request counts; `dollar_basic` and
+ * `dollar_bonus` are spend balances. They are separate budgets and must never
+ * be summed — a dollar balance is not a request count.
+ */
+const REQUEST_BUCKETS: readonly (readonly [string, string])[] = [
+  ["advanced_model", "Advanced model requests"],
+  ["premium_model_fast_request", "Premium fast requests"],
+  ["premium_model_slow_request", "Premium slow requests"],
+];
+
+const DOLLAR_BUCKETS: readonly (readonly [string, string])[] = [
+  ["dollar_basic", "Basic spend"],
+  ["dollar_bonus", "Bonus spend"],
+];
+
+interface TraeQuotaAuth {
+  readonly realm: TraeRealm;
+  readonly uid: string;
+  /** Provisioned region (`sg`, `us`), which selects the core host. */
+  readonly region: string;
+}
+
+/**
+ * Reads the account's realm and uid for the quota call.
+ *
+ * Both come from `auth_state`, the same place dispatch reads them: a Trae
+ * token is realm-bound, so guessing `intl` for a CN account sends it to a host
+ * that will not authenticate it.
+ */
+function quotaAuth(context: QuotaCollectionContext | undefined): TraeQuotaAuth {
+  const raw = context?.auth_state ?? {};
+  // `realm` is not persisted by the OAuth client — it is a property of which
+  // provider id the account was registered under, so the CN wrapper forces it
+  // rather than trusting an absent field.
+  const realm = raw["realm"] === "cn" || raw["region"] === "CN" ? "cn" : "intl";
+  // The OAuth client stores the account id as `userId`; `uid` is the name the
+  // dispatch header builder uses. Reading only one of them left the device
+  // fingerprint empty for every account.
+  const uidRaw = raw["uid"] ?? raw["userId"] ?? raw["user_id"];
+  const uid = typeof uidRaw === "string" && uidRaw.trim() ? uidRaw.trim() : "";
+  // `region` is provisioned, not chosen: an intl account is created into one
+  // and its token only authenticates against that region's core host. `us` and
+  // `cn` are served by the realm's default host, but `sg` is a different host
+  // entirely — sending it to the US core answers 401 code 1001.
+  const region = typeof raw["region"] === "string" ? raw["region"].trim().toLowerCase() : "";
+  return { realm, uid, region };
+}
+
+/**
+ * The account id out of the access token itself.
+ *
+ * The device fingerprint is derived from the uid, so an empty one presents no
+ * device at all — and this surface correlates the credential against its
+ * device, answering `1001` for a token that is perfectly valid. The JWT carries
+ * the id, so it is read there when the auth state does not have it.
+ */
+function uidFromToken(credential: string): string | undefined {
+  const payload = decodeJwtPayload(credential);
+  if (!payload) return undefined;
+  // The id is nested: this token's payload is `{data:{id,type,tenant_id},exp,
+  // iat}` — there is no `sub` and no top-level `userId`, so a flat read found
+  // nothing and the request went out with no device identity at all.
+  for (const source of [payload, record(payload["data"])]) {
+    if (!source) continue;
+    for (const key of ["userId", "user_id", "uid", "sub", "id"] as const) {
+      const value = source[key];
+      if (typeof value === "string" && value.trim()) return value.trim();
+      if (typeof value === "number" && Number.isFinite(value)) return String(value);
+    }
+  }
+  return undefined;
+}
+
+/** One bucket of `remain_usage`, paired with its cap from the sibling object. */
+function bucketWindow(
+  label: string,
+  remaining: number | null,
+  limit: number | null,
+  resetsAt: string | null,
+): ProviderQuotaWindow | null {
+  if (remaining === null && limit === null) return null;
+  const used = remaining !== null && limit !== null ? limit - remaining : null;
+  return percentWindow(
+    `trae:${label}`,
+    label,
+    null,
+    resetsAt,
+    used,
+    limit,
+    // Independent: each bucket is its own budget. Summing a request count into
+    // a dollar balance would produce a number that means nothing.
+    "independent",
+  );
+}
+
+/**
+ * Pulls `remaining`/`limit` for one key out of either usage object.
+ *
+ * `remain_usage` carries a **bare number** per bucket (`advanced_model: 40`),
+ * not a nested object — the caps live in the sibling `usage` object. Reading a
+ * nested `remaining` here is what dropped every balance and left a limit with
+ * no remaining, i.e. a window that cannot say how much is left.
+ */
+function bucketValues(
+  source: Record<string, unknown>,
+  key: string,
+): { readonly remaining: number | null; readonly limit: number | null } {
+  const direct = record(source[key]);
+  if (direct) {
+    return {
+      remaining: number(direct["remaining"] ?? direct["remain"] ?? direct["remain_usage"]),
+      limit: number(direct["limit"] ?? direct["total"] ?? direct["cap"]),
+    };
+  }
+  return {
+    remaining: number(source[key] ?? source[`${key}_remaining`]),
+    limit: number(source[`${key}_limit`] ?? source[`${key}_total`]),
+  };
+}
+
+/**
+ * The session-usage meter: `remain_usage` holds the remaining balance per
+ * bucket, with the caps alongside it on the same object.
+ */
+function parseSessionUsage(payload: unknown): {
+  readonly windows: readonly ProviderQuotaWindow[];
+  readonly plan: string | null;
+} {
+  // Deliberately *not* `quotaRecord`: it unwraps a `usage` envelope, and on
+  // this surface `usage` is the sibling object holding the caps — unwrapping it
+  // discards `remain_usage` entirely and leaves a limit with no remaining.
+  const root = record(payload) ?? {};
+  const windows: ProviderQuotaWindow[] = [];
+  // The meter is nested under `data` on some realms and at the root on others;
+  // both shapes are live, so look in each rather than picking one.
+  const candidates = [root, record(root["data"]), record(root["quota"])].filter(
+    (value): value is Record<string, unknown> => value !== null,
+  );
+  const resetsAt = candidates
+    .map((value) => isoDate(value["reset_time"] ?? value["resetTime"] ?? value["next_reset_time"]))
+    .find((value) => value !== null) ?? null;
+
+  for (const source of candidates) {
+    const remain = record(source["remain_usage"]) ?? source;
+    const usage = record(source["usage"]) ?? {};
+    for (const [key, label] of [...REQUEST_BUCKETS, ...DOLLAR_BUCKETS]) {
+      // Remaining is the bare number under `remain_usage`; the cap is the
+      // sibling object under `usage`. Two objects, one per side of the same
+      // budget, so both are read before a window is built.
+      const remaining = bucketValues(remain, key).remaining ?? number(usage[key]);
+      const limit = bucketValues(usage, key).limit ?? bucketValues(remain, key).limit;
+      const window = bucketWindow(label, remaining, limit, resetsAt);
+      if (window) windows.push(window);
+    }
+    if (windows.length > 0) break;
+  }
+  const plan = candidates
+    .map((value) => text(value["plan_name"] ?? value["planName"] ?? value["user_type"]))
+    .find((value) => value !== null) ?? null;
+  return { windows, plan };
+}
+
+/** The entitlement package name and lapse, from the pay host. */
+function parseEntitlement(payload: unknown): {
+  readonly windows: readonly ProviderQuotaWindow[];
+  readonly plan: string | null;
+} {
+  const root = record(payload) ?? {};
+  const data = record(root["data"]) ?? root;
+  const items = Array.isArray(data["entitlement_list"])
+    ? data["entitlement_list"]
+    : Array.isArray(data["list"])
+      ? data["list"]
+      : [];
+  const windows: ProviderQuotaWindow[] = [];
+  let plan: string | null = null;
+  for (const entry of items) {
+    const item = record(entry);
+    if (!item) continue;
+    const name = text(item["ent_title"] ?? item["name"] ?? item["package_name"]);
+    if (!plan && name) plan = name;
+    const total = number(item["total"] ?? item["quota"] ?? item["advanced_model_request_limit"]);
+    const remaining = number(item["remain"] ?? item["remaining"] ?? item["remain_usage"]);
+    const resetsAt = isoDate(item["end_time"] ?? item["endTime"] ?? item["expires_at"]);
+    const window = bucketWindow(name ?? "Entitlement", remaining, total, resetsAt);
+    if (window) windows.push(window);
+  }
+  return { windows, plan };
+}
+
+/**
+ * Records a quiet surface where an operator can act on it.
+ *
+ * Deliberately not the returned `error`: that field is what flags the account
+ * `quota_fetch_failed` and cools it. A 403 from the wrong realm, or a pay host
+ * that is unreachable, says nothing about whether the account can serve.
+ */
+function logTraeQuotaMiss(errors: readonly string[]): void {
+  if (errors.length === 0) return;
+  console.warn(`[quota] trae surfaces unavailable: ${errors.join("; ")}`);
+}
+
+/**
+ * Reads one Trae account's quota.
+ *
+ * The session meter and the entitlement are fetched independently: whichever
+ * answers contributes, and a failure is only fatal if *both* fail. An account
+ * whose pay host is unreachable still has a readable meter, and reporting
+ * "no quota" for it would park an account that can still serve.
+ */
+/**
+ * The core host for this account.
+ *
+ * A provisioned region overrides the realm default: an `sg` account sent to the
+ * US core is answered 401 code 1001, which looks exactly like a dead token.
+ */
+function coreHost(region: string, config: (typeof TRAE_REALMS)[TraeRealm]): string {
+  return (region !== "" ? TRAE_REGION_CORE_HOSTS[region] : undefined) ?? config.core;
+}
+
+export async function fetchTraeQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  const { realm, uid, region } = quotaAuth(context);
+  const resolvedUid = uid || uidFromToken(credential) || "";
+  const errors: string[] = [];
+
+  const call = async (
+    realm: TraeRealm,
+    url: string,
+    surface: string,
+  ): Promise<unknown> => {
+    const response = await fetcher(url, {
+      // POST with an empty JSON body, not GET: this is the commercial surface
+      // the desktop client calls, and it answers a GET with an error rather
+      // than a meter — which read as "no quota" for every account.
+      method: "POST",
+      headers: {
+        // The commercial surface authenticates with `Cloud-IDE-JWT` on both
+        // realms.
+        ...buildTraeHeaders({ realm, token: credential, uid: resolvedUid }),
+        // Applied after the builder, which switches intl to `Bearer` for raw
+        // chat: a Bearer here is answered 401 code 1001, so the account shows
+        // no windows while its token is perfectly valid.
+        authorization: `Cloud-IDE-JWT ${credential}`,
+        "content-type": "application/json",
+        // The builder pins `us` for every intl account. An `sg` account sent
+        // with a US country code is refused with 401 code 1001 — the country
+        // code is part of the identity this surface checks, not a hint.
+        "store-country-code": region || "us",
+      },
+      body: "{}",
+    });
+    if (!response.ok) {
+      // 403 here is a verdict about *how we asked*, not about the balance: the
+      // commercial surface correlates the credential against its realm and its
+      // device fingerprint, and a CN token sent to an intl host — or one sent
+      // with no device id — is refused outright. Reporting that as a failed
+      // read parks the account, so it is reported as unreadable-for-now and
+      // left alone by the cooldown path.
+      const body = await response.text().catch(() => "");
+      throw new Error(
+        response.status === 403
+          ? `${surface}: HTTP 403 (realm or device mismatch, not a balance)`
+          : `${surface}: HTTP ${response.status}${body ? ` ${body.slice(0, 80)}` : ""}`,
+      );
+    }
+    return await response.json();
+  };
+
+  /**
+   * Tries the realm we believe, then the other one.
+   *
+   * A Trae token is realm-bound and the auth state does not record which — the
+   * provider id does, and a collector cannot see it. The wrong host answers 401
+   * code 1001, which is indistinguishable from a dead token unless the other
+   * realm is tried: one of them accepts, and that is the answer.
+   */
+  const tryRealms = async (
+    path: (config: (typeof TRAE_REALMS)[TraeRealm]) => string,
+    surface: string,
+    parse: (payload: unknown) => { readonly windows: readonly ProviderQuotaWindow[]; readonly plan: string | null },
+  ): Promise<{ readonly windows: readonly ProviderQuotaWindow[]; readonly plan: string | null } | null> => {
+    for (const candidate of realm === "cn" ? (["cn", "intl"] as const) : (["intl", "cn"] as const)) {
+      try {
+        const payload = await call(candidate, path(TRAE_REALMS[candidate]), surface);
+        return parse(payload);
+      } catch (error) {
+        errors.push(`${candidate} ${surface}: ${cleanError(error)}`);
+      }
+    }
+    return null;
+  };
+
+  const session = await tryRealms((config) => coreHost(region, config) + TRAE_SESSION_USAGE_PATH, "session usage", parseSessionUsage);
+  const entitlement = await tryRealms((config) => config.pay + TRAE_ENT_USAGE_PATH, "entitlement", parseEntitlement);
+
+  const windows = [...(session?.windows ?? []), ...(entitlement?.windows ?? [])];
+  if (!session && !entitlement) {
+    // No window and *no error*: a quota read that could not reach upstream is
+    // not evidence about the account, and `error` here is what flags the
+    // account `quota_fetch_failed` and cools it down. An unreachable or
+    // refusing surface must leave the account alone — otherwise an account is
+    // parked by its own monitor, for a reason that has nothing to do with it.
+    // The detail is kept for the log instead, where it cannot be read as a
+    // balance.
+    logTraeQuotaMiss(errors);
+    return { source: "trae", plan: null, windows: [], error: null };
+  }
+  return {
+    source: "trae",
+    plan: session?.plan ?? entitlement?.plan ?? null,
+    windows,
+    // A partial read is still a read, and the quiet surface is a diagnostic —
+    // never a reason to park the account.
+    error: null,
+  };
+}
+
+/**
+ * The `traecn` provider's quota.
+ *
+ * Same collector, realm forced to `cn`: a CN token is refused by the intl
+ * hosts, and the provider id is not something the collector can see — the
+ * context carries no provider, only auth state.
+ */
+export function fetchTraeCnQuota(
+  credential: string,
+  fetcher: FetchLike,
+  context?: QuotaCollectionContext,
+): Promise<ProviderQuotaResult> {
+  return fetchTraeQuota(credential, fetcher, { ...context, auth_state: { ...(context?.auth_state ?? {}), realm: "cn" } });
+}

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

@@ -242,7 +242,7 @@ class TraeAdapter implements ProviderAdapter {
           yield {
             type: "content_delta",
             sequence_number: seq++,
-            content: { kind: "reasoning", payload: flatReasoning, summary: flatReasoning },
+            content: { kind: "reasoning", payload: null, summary: flatReasoning },
           } as CanonicalEvent;
         }
         yield* this.#toolCallDeltas(record["tool_calls"], announced, () => seq++);
@@ -273,7 +273,7 @@ class TraeAdapter implements ProviderAdapter {
         yield {
           type: "content_delta",
           sequence_number: seq++,
-          content: { kind: "reasoning", payload: reasoning, summary: reasoning },
+          content: { kind: "reasoning", payload: null, summary: reasoning },
         } as CanonicalEvent;
       }
       if (typeof payload["finish_reason"] === "string") {

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

@@ -73,7 +73,12 @@ function unwrapEnvelope(body: unknown, operation: string): unknown {
       const message = nonEmptyTrimmedString(root.msg) ?? `${operation} failed`;
       // `cartethyia` origin so the dialog shows the provider's own reason
       // instead of the generic "check the console log" fallback.
-      throw new GatewayError("authentication_failed", 400, `Z.AI ${message}`, { providerId: "zcode" });
+      // 401, not the 400 this used to send: an authentication failure is not a
+      // malformed request, and every other `authentication_failed` in the
+      // 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" });
     }
   }
   return root.data ?? body;

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

@@ -1,6 +1,6 @@
 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 { and, count, desc, eq, inArray, isNotNull, lte, or, sql } from "drizzle-orm";
 import { affectedRows, pruneExpiredCooldowns } from "../../persistence/dialect";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { isRecord } from "../../protocol/codecs";
@@ -310,9 +310,9 @@ function latestDeadlineMs(...candidates: readonly (number | undefined | null)[])
  * {@link latestDeadlineMs} cannot express *no* deadline — it floors at 0 — and
  * the account-wide write has one state that needs it. With
  * `CARTETHYIA_ACCOUNT_DISABLED_RECOVERY_MS=0` an automatic disable is meant to
- * be terminal again, and the classifier correctly reports `retryAt: null`; the
- * write used to derive the deadline from `Date.now() + cooldownMs` anyway,
- * which stamps *now*. The recovery sweep then treats that elapsed deadline as
+ * be terminal again, and the classifier correctly reports `retryAt: null`.
+ * Deriving the deadline from `Date.now() + cooldownMs` instead stamps *now*.
+ * The recovery sweep then treats that elapsed deadline as
  * an automatic disable awaiting recovery and returns the row to rotation on its
  * next tick — the escape hatch enabled exactly the behavior it documents
  * itself as disabling.
@@ -515,6 +515,15 @@ export function classifyAccountError(
       lower.includes("free-usage") ||
       lower.includes("free usage") ||
       lower.includes("exceeded your current quota") ||
+      // Trae answers an exhausted quota with **HTTP 502** and the body `Your
+      // requests have exceeded the quota.` The status is what misled the
+      // classifier: 502 read as a gateway failure, so this fell through to
+      // `server_error` — a 30s cooldown that does not mutate the account, so
+      // the account stayed in rotation and every other model on it kept being
+      // invoked inside a window the provider had already closed. The body is
+      // the verdict; the 502 is incidental. Matched on the phrase, not on the
+      // status, which is why this sits in `quotaSignal` ahead of the 5xx arm.
+      lower.includes("have exceeded the quota") ||
       lower.includes("balance exhausted") ||
       lower.includes("insufficient balance") ||
       lower.includes("out of credits") ||
@@ -539,11 +548,12 @@ export function classifyAccountError(
     options?.providerId !== undefined &&
     BUDDY_PROVIDER_IDS.has(options.providerId.toLowerCase());
   if (policyBlock) {
+    const policyBlockMs = resolveAccountPolicyBlockCooldownMs();
     return result(
       "policy_blocked",
       "cooldown",
-      resolveAccountPolicyBlockCooldownMs(),
-      new Date(Date.now() + resolveAccountPolicyBlockCooldownMs()),
+      policyBlockMs,
+      new Date(Date.now() + policyBlockMs),
       reason("Provider content-policy block"),
       origin === "upstream",
     );
@@ -590,10 +600,10 @@ export function classifyAccountError(
   }
   // A channel rejection (`11128`) is the same shape: the upstream is refusing
   // the caller for this account, not this particular prompt, and it keeps
-  // refusing on every invocation. It used to fall through to `unknown` with
-  // `mutates=false`, so the account stayed in rotation and failed every
-  // request — and since every account failed the same way, the whole pool
-  // looked dead with nothing ever parked.
+  // refusing on every invocation. Classifying it as `unknown` with
+  // `mutates=false` would leave the account in rotation failing every request —
+  // and since every account fails the same way, the whole pool looks dead with
+  // nothing ever parked.
   const channelRejection =
     providerCode === "11128" || lower.includes("unapproved channel");
   const channelBlock =
@@ -601,11 +611,12 @@ export function classifyAccountError(
     options?.providerId !== undefined &&
     BUDDY_PROVIDER_IDS.has(options.providerId.toLowerCase());
   if (channelBlock) {
+    const channelBlockMs = resolveAccountPolicyBlockCooldownMs();
     return result(
       "policy_blocked",
       "cooldown",
-      resolveAccountPolicyBlockCooldownMs(),
-      new Date(Date.now() + resolveAccountPolicyBlockCooldownMs()),
+      channelBlockMs,
+      new Date(Date.now() + channelBlockMs),
       reason("Provider channel rejection"),
       origin === "upstream",
     );
@@ -691,10 +702,11 @@ export function classifyAccountError(
     // rotated a moment ago, an edge answering before the credential loads) and
     // cools down instead.
     //
-    // This distinction is the whole fix. The generic `401`/`403` branch used to
-    // reach `disabled` too, which no sweep recovers, so one transient rejection
-    // removed the account from rotation until an operator noticed — the exact
-    // outcome the comment above says a static token must not suffer.
+    // This distinction is the whole fix. Reaching `disabled` from the generic
+    // `401`/`403` branch would be unrecoverable by any sweep, so one transient
+    // rejection would remove the account from rotation until an operator
+    // noticed — the exact outcome the comment above says a static token must
+    // not suffer.
     const revoked = revocationNamed;
     const recoverable = staticTokenRecovery || oauthRecovery || !revoked;
     // An automatic disable is **not** terminal any more, but the deadline is what
@@ -918,13 +930,14 @@ export function classifyAccountError(
     // scoped to the account (an edge/WAF challenge answered to one account's
     // requests while its siblings on the same egress served fine) must cool
     // that account down, or it stays `active` and is re-dialled for as long as
-    // the block lasts. Provider-scoped 5xx keeps the old behavior: the upstream
-    // is indiscriminately failing and no single account is at fault.
+    // the block lasts. Provider-scoped 5xx does not: the upstream is
+    // indiscriminately failing and no single account is at fault.
+    const transientMs = TRANSIENT_ERROR_COOLDOWN_MS();
     return result(
       lower.includes("timeout") ? "timeout" : "server_error",
       "cooldown",
-      TRANSIENT_ERROR_COOLDOWN_MS(),
-      new Date(Date.now() + TRANSIENT_ERROR_COOLDOWN_MS()),
+      transientMs,
+      new Date(Date.now() + transientMs),
       reason(`Provider ${statusCode ?? "network"} failure`),
       canMutate,
     );
@@ -932,11 +945,12 @@ export function classifyAccountError(
 
   // Same reasoning as above, with the shortest backoff: an unmapped failure
   // must still be retried automatically rather than parked forever.
+  const unclassifiedMs = UNCLASSIFIED_COOLDOWN_MS();
   return result(
     "unknown",
     "cooldown",
-    UNCLASSIFIED_COOLDOWN_MS(),
-    new Date(Date.now() + UNCLASSIFIED_COOLDOWN_MS()),
+    unclassifiedMs,
+    new Date(Date.now() + unclassifiedMs),
     reason("Unclassified provider failure"),
     false,
   );
@@ -1303,8 +1317,8 @@ export async function sweepExpiredCooldowns(db: CartethyiaDatabase): Promise<num
             isNotNull(providerAccounts.cooldownUntil),
             lte(providerAccounts.cooldownUntil, now),
           ),
-          // An **automatic** disable, which used to be terminal. Selected only
-          // when it carries a deadline: an operator's disable leaves
+          // An **automatic** disable. Selected only when it carries a deadline:
+          // an operator's disable leaves
           // `cooldownUntil` null, so a human's decision still outranks the
           // machine and is never swept away. The deadline is written by the two
           // paths that disable on evidence — the classifier's revocation branch
@@ -1362,9 +1376,9 @@ export async function sweepExpiredCooldowns(db: CartethyiaDatabase): Promise<num
     // its locks for the whole pass. Recomputing the object in SQL does the same
     // work in one statement.
     //
-    // `jsonb_typeof(...) = 'object'` guards the shape the same way the old
-    // `typeof raw !== "object"` check did: a malformed value must not abort the
-    // whole sweep. `IS DISTINCT FROM` keeps the update from rewriting rows it
+    // `jsonb_typeof(...) = 'object'` guards the shape: a malformed value must
+    // not abort the whole sweep. `IS DISTINCT FROM` keeps the update from
+    // rewriting rows it
     // did not change, so the returned row count is the number of accounts whose
     // cooldown set actually shrank — the same thing the loop counted.
     const pruning = pruneExpiredCooldowns(sql`${providerAccounts.modelCooldowns}`, sql`${nowIso}`);
@@ -1478,3 +1492,37 @@ export async function listAccountHealthEvents(
     return [];
   }
 }
+
+/** Every stored row across accounts and pools — the size the purge offers to delete. */
+export async function countAllHealthEvents(db: CartethyiaDatabase): Promise<number> {
+  try {
+    const rows = await db.select({ total: count() }).from(healthEvents);
+    return rows[0]?.total ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Deletes stored health & error rows.
+ *
+ * Unlike the read above, a failed delete surfaces: an operator who purged
+ * believes the trail is gone, so "it failed" must not read as "it succeeded
+ * with zero rows". Callers own the flush-buffer barrier (`drain`) so a queued
+ * write cannot land after these rows are gone.
+ */
+export async function deleteAccountHealthEvents(
+  db: CartethyiaDatabase,
+  accountId: string,
+): Promise<number> {
+  const rows = await db
+    .delete(healthEvents)
+    .where(and(eq(healthEvents.entityKind, "account"), eq(healthEvents.accountId, accountId)))
+    .returning({ id: healthEvents.id });
+  return rows.length;
+}
+
+export async function deleteAllHealthEvents(db: CartethyiaDatabase): Promise<number> {
+  const rows = await db.delete(healthEvents).returning({ id: healthEvents.id });
+  return rows.length;
+}

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

@@ -608,7 +608,7 @@ function describeResetCode(code: string): string {
 /**
  * Writes the outcome to `health_events` and, on success, restores the account to
  * `active` so it rejoins dispatch rotation immediately rather than waiting out a
- * cooldown that no longer reflects reality.
+ * cooldown that the reset has already cleared.
  */
 async function recordResetActivity(
   db: CartethyiaDatabase,