cartethyia 2.7.9 → 2.8.0

package/src/providers/provider-metadata.ts

@@ -490,6 +490,31 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   // rows are served by `/v1/search`, never by the canonical chat pipeline.
   { id: "exa", displayName: "Exa", baseUrl: "https://mcp.exa.ai", serviceKinds: ["websearch"], requiresAccount: false, credentialHint: "No API key. Search goes through the public MCP." },
   { id: "parallel", displayName: "Parallel", baseUrl: "https://search.parallel.ai", serviceKinds: ["websearch"], requiresAccount: false, credentialUrl: "https://platform.parallel.ai/settings?tab=api-keys", credentialHint: "Optional. Leave empty for the public MCP, or paste an API key for the higher-limit search API." },
+  {
+    // Freebuff (Codebuff Desktop). OAuth code flow → bearer token; every
+    // dispatch carries the desktop identity group + Ed25519 device signature
+    // (see documentation/research/freebuff/). The chat surface is
+    // OpenAI-compatible on `/api/v1/chat/completions` but requires a stateful
+    // session admission + agent-runs preflight — handled by the custom adapter.
+    id: "freebuff",
+    displayName: "Freebuff",
+    baseUrl: "https://www.codebuff.com",
+    hasAdapterUserAgent: true,
+    credentialUrl: "https://www.codebuff.com/login",
+    credentialHint: "Sign in with your Freebuff account (Desktop/CLI code flow).",
+  },
+  {
+    // Zro (moonmath). Fast, private, multi-region inference for open models.
+    // Claude Code connects via the Messages wire with a plain bearer key; the
+    // provider's own Claude Code docs configure `ANTHROPIC_BASE_URL` +
+    // `ANTHROPIC_AUTH_TOKEN`. No quota endpoint exists — entitlement is the
+    // `/v1/models` list itself (a key only sees the models it may call).
+    id: "zro",
+    displayName: "Zro",
+    baseUrl: "https://zro.moonmath.ai",
+    credentialUrl: "https://zro.moonmath.ai/docs/key-controls",
+    credentialHint: "Create or copy an API key (sk-...) from the Zro key controls page (docs/key-controls).",
+  },
 ] as const;
 
 /**
@@ -617,6 +642,11 @@ const ADAPTER_USER_AGENT_PROVIDER_IDS: ReadonlySet<string> = new Set(
   BUNDLED_PROVIDER_METADATA.filter((provider) => provider.hasAdapterUserAgent).map((provider) => provider.id),
 );
 
+/** Bundled metadata keyed by provider id for O(1) lookups. */
+const BUNDLED_PROVIDER_BY_ID: ReadonlyMap<BundledProviderId, BundledProviderMetadata> = new Map(
+  BUNDLED_PROVIDER_METADATA.map((definition) => [definition.id, definition]),
+);
+
 /** Whether the bundled adapter provides its own upstream User-Agent. */
 export function providerHasAdapterUserAgent(providerId: string): boolean {
   return ADAPTER_USER_AGENT_PROVIDER_IDS.has(providerId);
@@ -628,7 +658,7 @@ export function providerHasAdapterUserAgent(providerId: string): boolean {
  * minted inside a device/browser flow with no dedicated key page).
  */
 export function providerCredentialUrl(providerId: string): string | undefined {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.credentialUrl;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.credentialUrl;
 }
 
 /**
@@ -636,18 +666,18 @@ export function providerCredentialUrl(providerId: string): string | undefined {
  * `undefined` where the link alone is self-explanatory.
  */
 export function providerCredentialHint(providerId: string): string | undefined {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.credentialHint;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.credentialHint;
 }
 
 /** Presentation-only limitation for the provider detail page. */
 export function providerOperatorNotice(providerId: string): string | undefined {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.operatorNotice;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.operatorNotice;
 }
 
 /** Canonical builtin display name; falls back to the provider id for unknowns. */
 export function providerDisplayName(providerId: string): string {
   return (
-    BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.displayName ??
+    BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.displayName ??
     providerId
   );
 }
@@ -679,7 +709,7 @@ export function providerDisplayName(providerId: string): string {
  * gateway guessing it will not.
  */
 export function providerServiceKinds(providerId: string): readonly ServiceKind[] {
-  const declared = BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)
+  const declared = BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)
     ?.serviceKinds;
   // Bundled providers are explicit: they say which surfaces they serve, and a
   // bundled provider without the declaration serves LLM only.
@@ -708,7 +738,7 @@ export function customProviderServiceKinds(
 
 /** Canonical builtin base URL used by adapters, discovery, and quota clients. */
 export function providerBaseUrl(providerId: string): string {
-  const entry = BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId);
+  const entry = BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId);
   if (!entry) throw new Error(`Unknown builtin provider "${providerId}"`);
   return entry.baseUrl.replace(/\/+$/, "");
 }
@@ -744,7 +774,7 @@ export const PROVIDER_COMPATIBILITY_PROFILES: Record<string, CompatibilityProfil
 
 /** Default wire family for a builtin provider. */
 export function providerDefaultWireFamily(providerId: string): WireFamily {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.wireFamilyDefault ?? "chat";
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.wireFamilyDefault ?? "chat";
 }
 
 /**
@@ -754,12 +784,12 @@ export function providerDefaultWireFamily(providerId: string): WireFamily {
  * OpenAI-compatible adapter.
  */
 export function providerUsesBespokeWire(providerId: string): boolean {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.bespokeWire ?? false;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.bespokeWire ?? false;
 }
 
 /** Whether a builtin provider requires a persisted account row. */
 export function providerRequiresAccount(providerId: string): boolean {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.requiresAccount ?? true;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.requiresAccount ?? true;
 }
 
 /**
@@ -769,7 +799,7 @@ export function providerRequiresAccount(providerId: string): boolean {
  */
 export function providerJwtVerification(providerId: string): ProviderJwtVerification {
   return (
-    BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.jwtVerification ?? {}
+    BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.jwtVerification ?? {}
   );
 }
 

package/src/providers/provider-probe.ts

@@ -16,7 +16,21 @@ import { resolveDialect } from "../protocol/translation/dialect/resolver";
 import type { CanonicalRequest } from "../protocol/canonical-model";
 import type { ProviderDispatchContext } from "./provider-contracts";
 import { providerBaseUrl, providerRateLimitIsIpScoped } from "./provider-metadata";
-import type { ProviderDispatchTarget, ProviderId } from "./provider-contracts";
+import type { ProviderDispatchTarget, ProviderId, ValidatedOutboundFetch } from "./provider-contracts";
+
+/**
+ * Probe fetch wrapper: merges `Request`-carried headers with per-call init
+ * headers before delegating to the validated fetch. Required wherever the
+ * fetch is handed to adapters as `outbound_fetch`, because adapters may call
+ * it with a `Request` whose headers would otherwise be dropped.
+ */
+export function createProbeFetch(fetcher: ValidatedOutboundFetch): ValidatedOutboundFetch {
+  return (input, init) => {
+    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
+    return fetcher(input, { ...init, headers });
+  };
+}
 
 
 /**

package/src/providers/provider-registry.ts

@@ -58,6 +58,36 @@ export interface ProviderAuthentication {
   readonly refresher?: OAuthTokenRefresher;
 }
 
+/** Provider implementation fields composed with canonical metadata. */
+export type ProviderModuleCapabilities = Partial<Omit<ProviderModule, "loadAdapter">> &
+  Pick<ProviderModule, "loadAdapter">;
+
+/**
+ * Creates a lazy authentication loader from a dynamic import and client export.
+ * Most OAuth clients also refresh their own tokens.
+ */
+export function oauthCapability<M, K extends keyof M>(
+  loader: () => Promise<M>,
+  exportName: K,
+  options: { readonly withRefresher?: boolean } = {},
+): () => Promise<ProviderAuthentication> {
+  return async () => {
+    const module = await loader();
+    const client = (module as Record<string, unknown>)[exportName as string] as OAuthLoginClient & { refresh: unknown };
+    return options.withRefresher
+      ? ({ client, refresher: client } as ProviderAuthentication)
+      : ({ client } as ProviderAuthentication);
+  };
+}
+
+/** Creates a lazy quota collector loader from a dynamic import and export name. */
+export function quotaCapability<M, K extends keyof M>(
+  loader: () => Promise<M>,
+  exportName: K,
+): () => Promise<QuotaFetcher> {
+  return () => loader().then((module) => (module as Record<string, unknown>)[exportName as string] as QuotaFetcher);
+}
+
 /**
  * Derives a registry registration from a fully populated provider module.
  * Keeps the registration shape in one place so the default registry and any
@@ -95,12 +125,6 @@ function assertAdapterIdentity(expected: ProviderId, adapter: ProviderAdapter):
   });
 }
 
-/** Result of loading the configured provider registrations. */
-export interface ProviderRegistrySnapshot {
-  readonly revision: number;
-  readonly adapters: ReadonlyMap<ProviderId, ProviderAdapter>;
-}
-
 /**
  * Single provider-registration authority. Every registration loads on
  * demand through its own loader; registrations that are not added are
@@ -116,7 +140,6 @@ export class ProviderRegistry {
   #quotaLoading = new Map<ProviderId, Promise<QuotaFetcher>>();
   #modelDiscovery = new Map<ProviderId, ProviderModelDiscovery>();
   #modelDiscoveryLoading = new Map<ProviderId, Promise<ProviderModelDiscovery>>();
-  #revision = 0;
 
   /** Adds one registration and rejects duplicate canonical IDs. */
   register(registration: ProviderRegistration): void {
@@ -132,7 +155,6 @@ export class ProviderRegistry {
       });
     }
     this.#registrations.set(providerId, registration);
-    this.#revision += 1;
   }
   /** Removes one registration and any cached adapter/auth/quota/discovery state. */
   unregister(providerId: string): boolean {
@@ -142,7 +164,6 @@ export class ProviderRegistry {
     this.#authentication.delete(normalized);
     this.#quotaCollectors.delete(normalized);
     this.#modelDiscovery.delete(normalized);
-    if (removed) this.#revision += 1;
     return removed;
   }
 
@@ -170,28 +191,25 @@ export class ProviderRegistry {
     this.#authentication.delete(providerId);
     this.#quotaCollectors.delete(providerId);
     this.#modelDiscovery.delete(providerId);
-    this.#revision += 1;
     return replaced;
   }
 
-  /** Loads one registered provider, or `undefined` when it is not registered. */
-  async loadOne(providerId: string): Promise<ProviderAdapter | undefined> {
-    const normalized = parseProviderId(providerId);
-    const registration = this.#registrations.get(normalized);
-    if (registration === undefined) return undefined;
-    return this.#loadRegistration(normalized, registration);
-  }
-
   /**
    * Resolves one adapter on demand, returning the cached instance when it has
-   * already loaded. This never evaluates a provider's module graph until that
-   * provider is actually dispatched to, so heavy bespoke adapters
-   * (protobuf-based providers) stay out of the startup path.
+   * already loaded — unless `force` is set, which rebuilds the adapter from
+   * the registration (single-flight, and the fresh instance replaces the
+   * cache). This never evaluates a provider's module graph until that provider
+   * is actually dispatched to, so heavy bespoke adapters (protobuf-based
+   * providers) stay out of the startup path. `force` is used by the probe
+   * path, which wants the adapter rebuilt against the latest registration
+   * rather than a cached instance.
    */
-  async resolve(providerId: string): Promise<ProviderAdapter | undefined> {
+  async resolve(providerId: string, opts: { readonly force?: boolean } = {}): Promise<ProviderAdapter | undefined> {
     const normalized = parseProviderId(providerId);
-    const cached = this.#loaded.get(normalized);
-    if (cached !== undefined) return cached;
+    if (!opts.force) {
+      const cached = this.#loaded.get(normalized);
+      if (cached !== undefined) return cached;
+    }
     const registration = this.#registrations.get(normalized);
     if (registration === undefined) return undefined;
     return this.#loadRegistration(normalized, registration);
@@ -306,7 +324,6 @@ export class ProviderRegistry {
       metrics.proxy_provider_adapter_load_ms.observe(durationMs);
       trackAdapterLoad(providerId, durationMs);
       this.#loaded.set(providerId, adapter);
-      this.#revision += 1;
       return adapter;
     })().finally(() => {
       this.#loading.delete(providerId);
@@ -315,14 +332,6 @@ export class ProviderRegistry {
     return task;
   }
 
-  /** Returns the immutable registry snapshot; disabled optional providers are absent. */
-  snapshot(): ProviderRegistrySnapshot {
-    return {
-      revision: this.#revision,
-      adapters: new Map(this.#loaded),
-    };
-  }
-
   /** Returns registration metadata without loading optional code. */
   registrations(): readonly ProviderRegistration[] {
     return [...this.#registrations.values()];

package/src/providers/quota/quota-limit-windows.ts

@@ -10,6 +10,7 @@
  */
 import type { ProviderQuotaWindow } from "./quota-contracts";
 import { isoDate, number, percentWindow, record, text } from "./quota-contracts";
+import { resolveWindowEmission } from "./quota-window-parser";
 
 /** Where one provider's limit entries and their fields live. */
 export interface LimitWindowShape {
@@ -77,14 +78,24 @@ export function parseLimitWindows(
     const kind = text(readFirst(limit, shape.kindPaths)) ?? `window-${index + 1}`;
     const percent = number(readFirst(limit, shape.percentPaths));
     const reset = isoDate(readFirst(limit, shape.resetPaths));
-    if (percent === null && reset === null) continue;
+    const rawUsed = shape.usedPaths ? number(readFirst(limit, shape.usedPaths)) : null;
     const limitValue = shape.limitPaths
       ? number(readFirst(limit, shape.limitPaths))
       : null;
-    const usedValue =
-      (shape.usedPaths ? number(readFirst(limit, shape.usedPaths)) : null) ??
-      shape.deriveUsed?.(limit, percent, limitValue) ??
-      null;
+    const { emit } = resolveWindowEmission({
+      explicitPercent: null,
+      usedPercent: percent,
+      remainingPercent: null,
+      used: rawUsed,
+      limit: limitValue,
+      reset,
+      deriveFromUsedLimit: false,
+      // The array walker has always emitted a reset-only window (percent null,
+      // reset present); only an entry with neither is dropped.
+      emitWithoutPercent: true,
+    });
+    if (!emit) continue;
+    const usedValue = rawUsed ?? shape.deriveUsed?.(limit, percent, limitValue) ?? null;
     const label =
       shape.labelFor?.(kind, limit) ?? shape.fallbackLabel?.(kind) ?? humanize(kind);
     windows.push(percentWindow(kind, label, percent, reset, usedValue, limitValue, "independent"));

package/src/providers/quota/quota-support.ts

@@ -3,7 +3,7 @@ import { cleanError, unsupportedQuota } from "./quota-contracts";
 import type { ProviderRegistry } from "../provider-registry";
 import { parseProviderId } from "../provider-contracts";
 import { providerBaseUrl } from "../provider-metadata";
-import { createProbeFetch } from "../operations/probe-fetch";
+import { createProbeFetch } from "../provider-probe";
 /**
  * Verifies an API key against the provider's OpenAI-compatible `/models`
  * endpoint. For providers that expose no billing/quota surface, a reachable

package/src/providers/quota/quota-window-parser.ts

@@ -98,6 +98,75 @@ function findReset(root: unknown, mapping: QuotaWindowMapping): string | null {
   return mapping.resetFallback ?? null;
 }
 
+/**
+ * The raw per-window candidates the shared emission core resolves.
+ *
+ * Both quota walkers (`parseQuotaWindows` and `parseLimitWindows`) feed their
+ * independently-read fields into one resolution so the percent fallback chain
+ * and the skip rule cannot drift between them.
+ */
+export interface WindowFieldCandidates {
+  /** Provider-preferred percent (e.g. a `derivePercent` result). */
+  readonly explicitPercent: number | null;
+  /** Raw used-percent read from the payload. */
+  readonly usedPercent: number | null;
+  /** Raw remaining-percent read from the payload. */
+  readonly remainingPercent: number | null;
+  /** Absolute used value. */
+  readonly used: number | null;
+  /** Absolute limit value. */
+  readonly limit: number | null;
+  /** Reset timestamp; required to emit a reset-only window. */
+  readonly reset: string | null;
+  /**
+   * Whether percent may be derived from absolute used/limit when no percentage
+   * was reported. Only `parseQuotaWindows` does this — `parseLimitWindows`
+   * reports percentages and resets the upstream gave it, never ones it
+   * invented, so Cline entries stay reset-only instead of gaining a derived
+   * percent.
+   */
+  readonly deriveFromUsedLimit: boolean;
+  /**
+   * When true, a reset-only window (percent null, reset present) is still
+   * emitted. When false/absent, an entry with neither percent nor reset is
+   * dropped — never rendered as 0% — and a reset-only window is dropped too.
+   */
+  readonly emitWithoutPercent?: boolean;
+}
+
+/**
+ * Shared per-window field resolution: the percent fallback chain plus the
+ * "emit or skip" decision.
+ *
+ * Percent resolution order is exact: explicit percent, then used-percent, then
+ * remaining-percent inverted (100 − remaining), then derived from absolute
+ * used/limit (only when the limit is positive and `deriveFromUsedLimit` is
+ * set). The result is never coerced to 0: a missing percentage stays `null`,
+ * so a window can be omitted or rendered as a countdown depending on
+ * `emitWithoutPercent`.
+ */
+export function resolveWindowEmission(candidates: WindowFieldCandidates): {
+  readonly emit: boolean;
+  readonly percent: number | null;
+} {
+  let percent = candidates.explicitPercent;
+  if (percent === null && candidates.usedPercent !== null) percent = candidates.usedPercent;
+  if (percent === null && candidates.remainingPercent !== null) {
+    percent = Math.max(0, 100 - candidates.remainingPercent);
+  }
+  if (
+    percent === null &&
+    candidates.deriveFromUsedLimit &&
+    candidates.used !== null &&
+    candidates.limit !== null &&
+    candidates.limit > 0
+  ) {
+    percent = (candidates.used / candidates.limit) * 100;
+  }
+  const emit = percent !== null || (candidates.emitWithoutPercent === true && candidates.reset !== null);
+  return { emit, percent };
+}
+
 /** Parses a generic quota payload using the provided window mappings. */
 export function parseQuotaWindows(
   body: unknown,
@@ -110,27 +179,30 @@ export function parseQuotaWindows(
   for (const mapping of windowMappings) {
     const used = findNumber(payload, mapping.usedPaths);
     const limit = findNumber(payload, mapping.limitPaths);
+    const reset = findReset(payload, mapping);
 
-    let percent: number | null = mapping.derivePercent ? mapping.derivePercent(payload) : null;
-    if (percent === null) {
-      const usedPercent = findNumber(payload, mapping.usedPercentPaths);
-      const remainingPercent = findNumber(payload, mapping.remainingPercentPaths);
-      if (usedPercent !== null) {
-        percent = usedPercent;
-      } else if (remainingPercent !== null) {
-        percent = Math.max(0, 100 - remainingPercent);
-      } else if (used !== null && limit !== null && limit > 0) {
-        percent = (used / limit) * 100;
-      }
-    }
-    if (percent !== null && mapping.valueMultiplier !== undefined && mapping.valueMultiplier !== 0) {
-      percent = Math.min(100, Math.max(0, percent * mapping.valueMultiplier));
-    }
+    const { emit, percent } = resolveWindowEmission({
+      explicitPercent: mapping.derivePercent ? mapping.derivePercent(payload) : null,
+      usedPercent: findNumber(payload, mapping.usedPercentPaths),
+      remainingPercent: findNumber(payload, mapping.remainingPercentPaths),
+      used,
+      limit,
+      reset,
+      deriveFromUsedLimit: true,
+      ...(mapping.emitWithoutPercent === undefined ? {} : { emitWithoutPercent: mapping.emitWithoutPercent }),
+    });
+    if (!emit) continue;
 
-    const reset = findReset(payload, mapping);
-    if (percent === null && !(mapping.emitWithoutPercent === true && reset !== null)) continue;
+    let resolvedPercent = percent;
+    if (
+      resolvedPercent !== null &&
+      mapping.valueMultiplier !== undefined &&
+      mapping.valueMultiplier !== 0
+    ) {
+      resolvedPercent = Math.min(100, Math.max(0, resolvedPercent * mapping.valueMultiplier));
+    }
 
-    windows.push(percentWindow(mapping.kind, mapping.label, percent, reset, used, limit, "independent"));
+    windows.push(percentWindow(mapping.kind, mapping.label, resolvedPercent, reset, used, limit, "independent"));
   }
 
   if (options.extraWindows) windows.push(...options.extraWindows(payload));

package/src/providers/quota/refresh.ts

@@ -18,6 +18,7 @@ import type { ProviderId } from "../provider-contracts";
 import type { ProviderRegistry } from "../provider-registry";
 import { quotaLens, setCachedQuota } from "./cache";
 import { persistQuotaSnapshot } from "./snapshot";
+import { applyAccountVerdict } from "../operations/account-health-service";
 import { asJsonbRecord } from "../../shared/coerce";
 import { KIRO_DEFAULT_LABELS } from "../integrations/kiro/kiro-oauth";
 
@@ -150,12 +151,52 @@ export async function recordAccountCheck(
   db: CartethyiaDatabase,
   accountId: string,
   outcome: { ok: boolean; error?: string | null; category?: string | null },
+  snapshotInvalidator?: { invalidate(): unknown },
 ): Promise<void> {
-  const activeOnly = and(
-    eq(providerAccounts.id, accountId),
-    eq(providerAccounts.status, "active"),
-  );
   if (outcome.ok) {
+    // A successful quota refresh is the freshest evidence about the account's
+    // health: heal a cooldown that the refresh shows is no longer justified, so
+    // the account returns to rotation immediately instead of waiting out the
+    // remainder of a stale fallback window. Only healable scopes heal — an
+    // auth/policy cooldown must never be lifted by a quota report (the
+    // credential is still refused). `lastErrorCategory` carries the category
+    // that parked the account, so the heal is scoped by the same verdict the
+    // health machine wrote.
+    const healableCategories = new Set([
+      "quota_exhausted",
+      "rate_limit_transient",
+      "model_capacity",
+      "model_unreachable",
+      "unknown",
+      "check_failed",
+    ]);
+    const rows = await db
+      .select({ status: providerAccounts.status, lastErrorCategory: providerAccounts.lastErrorCategory })
+      .from(providerAccounts)
+      .where(eq(providerAccounts.id, accountId))
+      .limit(1);
+    const account = rows[0];
+    const healable =
+      account?.status === "cooldown" &&
+      (account.lastErrorCategory === null || healableCategories.has(account.lastErrorCategory));
+    if (healable) {
+      const healed = await db
+        .update(providerAccounts)
+        .set({
+          status: "active",
+          lastSuccessAt: new Date(),
+          lastError: null,
+          lastErrorCategory: null,
+          lastErrorAt: null,
+          consecutiveFailures: 0,
+          cooldownUntil: null,
+          lastRecoveredAt: new Date(),
+        })
+        .where(eq(providerAccounts.id, accountId))
+        .returning({ id: providerAccounts.id });
+      if (healed.length > 0) await snapshotInvalidator?.invalidate();
+      return;
+    }
     await db
       .update(providerAccounts)
       .set({
@@ -165,7 +206,7 @@ export async function recordAccountCheck(
         lastErrorAt: null,
         consecutiveFailures: 0,
       })
-      .where(activeOnly);
+      .where(and(eq(providerAccounts.id, accountId), eq(providerAccounts.status, "active")));
     return;
   }
   const transient = isTransientTimeout(outcome.error);
@@ -186,7 +227,7 @@ export async function recordAccountCheck(
       lastErrorAt: new Date(),
       ...(transient ? {} : { consecutiveFailures: sql`${providerAccounts.consecutiveFailures} + 1` }),
     })
-    .where(activeOnly)
+    .where(and(eq(providerAccounts.id, accountId), eq(providerAccounts.status, "active")))
     .returning({ consecutiveFailures: providerAccounts.consecutiveFailures });
   if (transient) return;
   const failures = failing[0]?.consecutiveFailures ?? 0;
@@ -196,13 +237,18 @@ export async function recordAccountCheck(
   // pass. The cooldown clears itself; a success before it elapses resets the
   // count above.
   if (failures >= QUOTA_FAILURE_PARK_THRESHOLD) {
-    await db
-      .update(providerAccounts)
-      .set({
-        status: "cooldown",
-        cooldownUntil: new Date(Date.now() + QUOTA_FAILURE_COOLDOWN_MS),
-      })
-      .where(activeOnly);
+    // Converge on the health application seam (proposal §3.5): quota refresh
+    // parking is a producer into `applyAccountVerdict`, not a separate state
+    // machine.
+    const parked = await applyAccountVerdict(db, {
+      accountId,
+      status: "cooldown",
+      reason: outcome.error ?? "Account check failed",
+      category: outcome.category ?? "quota_fetch_failed",
+      cooldownUntil: new Date(Date.now() + QUOTA_FAILURE_COOLDOWN_MS),
+      fromStatus: "active",
+    });
+    if (parked) await snapshotInvalidator?.invalidate();
   }
 }
 
@@ -427,7 +473,13 @@ async function runQuotaRefresh(
     try {
       await deps.db
         .update(providerAccounts)
-        .set({ quotaPlan: quota.plan })
+        .set({
+          quotaPlan: quota.plan,
+          // Freshness stamp for the plan column: routing uses it to downgrade
+          // a plan older than the freshness horizon to `unknown` instead of
+          // trusting a weeks-old string.
+          quotaPlanFetchedAt: new Date(),
+        })
         .where(eq(providerAccounts.id, target.accountId));
     } catch (error) {
       log.warn(`[quota] failed to record plan for account=${target.accountId}`, error as Error);
@@ -469,10 +521,15 @@ async function runQuotaRefresh(
     }
   }
   try {
-    await recordAccountCheck(deps.db, target.accountId, {
-      ok: quota.error === null,
-      ...(quota.error === null ? {} : { error: quota.error, category: failure ?? "quota_fetch_failed" }),
-    });
+    await recordAccountCheck(
+      deps.db,
+      target.accountId,
+      {
+        ok: quota.error === null,
+        ...(quota.error === null ? {} : { error: quota.error, category: failure ?? "quota_fetch_failed" }),
+      },
+      deps.snapshotInvalidator,
+    );
   } catch (error) {
     // A stamp failure must not lose the freshly fetched quota.
     log.warn(`[quota] failed to stamp check outcome for account=${target.accountId}`, error as Error);

package/src/security/api-key-auth-cache.ts

@@ -1,7 +1,7 @@
 /** Bounded process-local authorization cache; shared-cache I/O stays in the auth service. */
 export const AUTH_CACHE_TTL_MS = 3_000;
 const AUTH_CACHE_MAX_ENTRIES = 10_000;
-const AUTH_NEGATIVE_CACHE_TTL_MS = 1_500;
+export const AUTH_NEGATIVE_CACHE_TTL_MS = 1_500;
 const AUTH_FAILURE_COOLDOWN_MS = 1_000;
 
 interface CacheEntry<T> {

package/src/security/api-key-auth.ts

@@ -21,8 +21,12 @@ import type { ApiKeyModelAccessMode } from "../persistence/schema";
  * snapshot's consumed value is a reference point, so a brief stale window
  * cannot meaningfully over-consume a budget.
  *
- * Negative results (unknown/revoked tokens) are deliberately NOT cached, so
- * a newly minted key is usable immediately.
+ * Unknown or revoked tokens are negative-cached for
+ * `AUTH_NEGATIVE_CACHE_TTL_MS` (1.5s): a token rejected within that window
+ * stays refused even if its key is minted or un-revoked in between. A newly
+ * minted key is usable immediately only because `invalidateApiKeyCache`
+ * clears the negative entries when a mutation lands — not because negatives
+ * are absent.
  */
 const authorizationCache = createApiKeyAuthorizationCache<ResolvedApiKey>();