cartethyia 2.7.9 → 2.8.1

package/src/providers/operations/oauth-refresh-lead.ts

@@ -1,22 +1,43 @@
 /**
  * Per-provider proactive OAuth refresh lead.
  *
- * A single global "refresh 5 minutes before expiry" window is wrong for two
- * reasons. Some providers issue short-lived tokens that a 5-minute lead can
- * miss entirely under a loaded sweep, while others issue long-lived tokens
- * where re-minting every few minutes is pointless traffic. And some providers
- * (Google-backed) rate-limit the token endpoint aggressively, so refreshing
- * only when genuinely close to expiry matters more than reacting fast.
+ * The lead is how long *before* expiry a token becomes eligible for the
+ * scheduled refresh sweep. It exists so the sweep re-mints a token before it
+ * dies — never to push refreshes any more often than that.
  *
- * The lead is how long *before* expiry the token becomes eligible for
- * proactive refresh. It is a floor: a caller may pass a larger `skewMs`
- * explicitly, and `DEFAULT_REFRESH_LEAD_MS` applies to any provider not listed.
+ * Buckets are deliberately coarse. A single global "5 minutes before expiry"
+ * window is wrong: some providers issue short-lived tokens that a 5-minute
+ * lead can miss under a loaded sweep, while others issue very long-lived
+ * tokens where re-minting days early is pointless traffic. Three buckets cover
+ * both ends without a hand-tuned value per provider:
  *
- * Values mirror the leads published by the upstream clients these providers
- * model (Claude Code ~4h, Codex ~5 days, Antigravity/Kimi ~5 min), so a token
- * is re-minted on the same schedule the first-party tooling uses.
+ *   - daily (default): tokens that live hours to days — refresh once a day at
+ *     most, or when the sweep sees the token enter its final 24h.
+ *   - 3 days: multi-day tokens — refresh at most ~3 days before expiry.
+ *   - 7 weeks: very long-lived tokens — refresh ~7 weeks before expiry, so a
+ *     ~6-month token is touched roughly once a quarter.
+ *
+ * Short-lived tokens (below the daily bucket) keep tighter leads because the
+ * invariant is "never let the token expire": a lead larger than the token
+ * lifetime would make the token permanently due and the sweep would re-mint it
+ * on every tick, which is the wasteful behavior these buckets exist to remove.
+ *
+ * Real expiries (from the first-party clients these providers model):
+ *   - Google-backed (Antigravity): access tokens live ~1h; 5 min lead.
+ *   - Claude Code: CLI session tokens live ~8h; 4h lead keeps one work
+ *     session on a single token.
+ *   - xAI/Grok CLI and Kimi: short-lived tokens; 5 min lead.
+ *   - ChatGPT/Codex: access tokens live ~5 days; 3-day lead re-mints ~2 days
+ *     before expiry.
+ *   - iFlow: very long-lived tokens; 7-week lead.
  */
-export const DEFAULT_REFRESH_LEAD_MS = 5 * 60 * 1000;
+export const DEFAULT_REFRESH_LEAD_MS = 24 * 60 * 60 * 1000;
+
+/** 3-day lead for multi-day tokens. */
+export const REFRESH_LEAD_3DAY_MS = 3 * 24 * 60 * 60 * 1000;
+
+/** 7-week lead for very long-lived tokens. */
+export const REFRESH_LEAD_7WEEK_MS = 7 * 7 * 24 * 60 * 60 * 1000;
 
 /**
  * Per-provider refresh lead in milliseconds. Providers absent here use
@@ -24,19 +45,22 @@ export const DEFAULT_REFRESH_LEAD_MS = 5 * 60 * 1000;
  * `provider_accounts.provider_id`.
  */
 export const REFRESH_LEAD_MS: Readonly<Record<string, number>> = Object.freeze({
-  // Google-backed token endpoints throttle; a wide lead with infrequent
-  // refreshes is safer than a tight one that retries often.
+  // Google-backed token endpoints throttle, and the access token itself lives
+  // only ~1h — a tight lead (below the token lifetime) is what keeps the
+  // sweep from re-minting on every tick.
   antigravity: 5 * 60 * 1000,
-  // Claude Code access tokens live ~8h and the CLI re-mints well ahead of
-  // expiry; 4h keeps a full work session on one token.
+  // Claude Code access tokens live ~8h; 4h keeps a full work session on one
+  // token without permanent due-state.
   claude: 4 * 60 * 60 * 1000,
-  // Codex/ChatGPT access tokens live for days; refresh on a 5-day lead.
-  codex: 5 * 24 * 60 * 60 * 1000,
-  // xAI/Grok CLI and Kimi both re-mint on a 5-minute lead.
+  // xAI/Grok CLI and Kimi re-mint on a 5-minute lead (short-lived tokens).
   grok: 5 * 60 * 1000,
   kimi: 5 * 60 * 1000,
-  // iFlow tokens are long-lived; a 1-day lead avoids pointless churn.
-  iflow: 24 * 60 * 60 * 1000,
+  // ChatGPT/Codex access tokens live ~5 days; a 3-day lead re-mints ~2 days
+  // before expiry — one refresh per weekend, not per request.
+  codex: REFRESH_LEAD_3DAY_MS,
+  // iFlow tokens are very long-lived; a 7-week lead avoids pointless churn
+  // while still re-minting well before expiry.
+  iflow: REFRESH_LEAD_7WEEK_MS,
 });
 
 /** The refresh lead for `providerId`, falling back to the shared default. */

package/src/providers/operations/{model-catalog-cache.ts → provider-caches.ts}

@@ -1,16 +1,17 @@
 /**
- * Process-lifetime model-catalog cache.
- *
- * `bundledModelCatalog` is called during startup seeding and again whenever a
- * caller rebuilds the routing/console catalog. Caching the loader *promise*
- * (not just the resolved value) makes concurrent and repeated calls for one
- * provider share a single load, and lets the dynamic catalog imports run once
- * per process. A rejected load is evicted so a later call can retry.
+ * In-process caches for model catalogs, model discovery, and client/provider versions.
  */
+
 import type { ModelDefinition } from "../provider-model-definition";
 import { trackModelCatalogLoad } from "../../observability/performance-metrics";
 import { resolveRedisClient } from "../../persistence/redis";
 import { cachedRead } from "../../console/shared/read-through-cache";
+import { TtlCacheFamily } from "../../persistence/ttl-cache";
+import { retryWithBackoff } from "../../network/util/retry";
+
+/* -------------------------------------------------------------------------- */
+/* 1. Model Catalog Cache                                                     */
+/* -------------------------------------------------------------------------- */
 
 /**
  * Provider entries retained before the least-recently-used catalog is evicted.
@@ -37,8 +38,7 @@ const catalogCache = new Map<string, Promise<readonly ModelDefinition[]>>();
 /**
  * Evicts the least-recently-used provider before inserting a new one once the
  * cache is at its bound. `Map` preserves insertion order and every cache hit
- * re-inserts its entry at the tail, so the head is the LRU key. Without this
- * bound the process-lifetime cache pinned one catalog per provider forever.
+ * re-inserts its entry at the tail, so the head is the LRU key.
  */
 function evictLeastRecentlyUsedCatalog(maxEntries: number): void {
   if (catalogCache.size < maxEntries) return;
@@ -87,13 +87,65 @@ export function resetModelCatalogCacheForTesting(): void {
   catalogCache.clear();
 }
 
-/**
- * Live entry count, for the `/metrics` gauge.
- *
- * Exported so a rebuild that saturates the cap is visible from outside the
- * process: before this, every in-process cache except the quota tier was
- * invisible, and growth could only be found with a heap dump.
- */
+/** Live entry count, for the `/metrics` gauge. */
 export function modelCatalogCacheSize(): number {
   return catalogCache.size;
 }
+
+/* -------------------------------------------------------------------------- */
+/* 2. Model Discovery Cache                                                   */
+/* -------------------------------------------------------------------------- */
+
+const MODEL_DISCOVERY_CACHE_TTL_MS = 10 * 60 * 1000;
+const discoveryCaches = new TtlCacheFamily<readonly ModelDefinition[]>({
+  defaultTtlMs: MODEL_DISCOVERY_CACHE_TTL_MS,
+});
+
+export interface CachedModelDiscoveryOptions {
+  readonly ttlMs?: number;
+}
+
+/** Returns cached models, retrying null/empty loads on the next call. */
+export async function getCachedModelDiscovery(
+  key: string,
+  loader: () => Promise<readonly ModelDefinition[] | null>,
+  options: CachedModelDiscoveryOptions = {},
+): Promise<readonly ModelDefinition[] | null> {
+  return discoveryCaches.for(options.ttlMs).load(key, loader, {
+    namespace: "model-discovery",
+    shouldCache: (models) => models.length > 0,
+  });
+}
+
+/** Drops all cached discoveries. Test-only. */
+export function resetModelDiscoveryCacheForTesting(): void {
+  discoveryCaches.clear();
+}
+
+/* -------------------------------------------------------------------------- */
+/* 3. Provider Version Cache                                                  */
+/* -------------------------------------------------------------------------- */
+
+const VERSION_CACHE_TTL_MS = 5 * 60 * 1000;
+const versionCaches = new TtlCacheFamily<string>({ defaultTtlMs: VERSION_CACHE_TTL_MS });
+
+export interface CachedVersionOptions {
+  readonly ttlMs?: number;
+  readonly maxRetries?: number;
+}
+
+export async function getCachedVersion(
+  key: string,
+  loader: () => Promise<string | null>,
+  options: CachedVersionOptions = {},
+): Promise<string | null> {
+  const loadWithRetry = () => retryWithBackoff(loader, { maxRetries: options.maxRetries ?? 2 });
+  return versionCaches.for(options.ttlMs).load(key, loadWithRetry, {
+    namespace: "provider-version",
+  });
+}
+
+/** Drops all cached versions. Test-only. */
+export function resetVersionCacheForTesting(): void {
+  versionCaches.clear();
+}

package/src/providers/operations/provider-catalog-service.ts

@@ -10,7 +10,7 @@ import { ProviderRegistry } from "../provider-registry";
 import { OpenAICompatibleAdapter } from "../adapters/compatible-adapter";
 import { resolveByokWireProfile } from "./byok-wire-profile";
 import { BUNDLED_PROVIDER_MODULES } from "../default-registry";
-import { getCachedModels } from "./model-catalog-cache";
+import { getCachedModels } from "./provider-caches";
 import { seedBundledModels } from "./provider-catalog-seeder";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import { providers } from "../../persistence/schema";

package/src/providers/operations/provider-credential-service.ts

@@ -6,7 +6,7 @@ import { providerAccounts, providerOauthStates } from "../../persistence/schema"
 import { decryptCredentialToString } from "../../security/crypto";
 import { GatewayError } from "../../protocol/gateway-error";
 import type { OAuthRefreshService, OAuthTokenRefresher } from "../authentication/oauth-refresh-service";
-import { CredentialResolver, type CredentialAlternative } from "../provider-credential-resolver";
+import { CredentialResolver, type CredentialAlternative } from "../provider-credentials";
 import { parseProviderId, type CredentialKind } from "../provider-contracts";
 import type { ResolvedCredential } from "../provider-contracts";
 import { refreshLeadMs } from "./oauth-refresh-lead";
@@ -145,19 +145,62 @@ export interface AccountWithFreshness {
   readonly dueAt: number | undefined;
 }
 
+/** Columns every account+OAuth-state reader selects; narrower readers pick from it. */
+export interface AccountWithOauthStateRow {
+  readonly id: string;
+  readonly providerId: string;
+  readonly credentialKind: CredentialKind;
+  readonly credentialCiphertext: Buffer | null;
+  readonly refreshCiphertext: Buffer | null;
+  readonly authState: unknown;
+  readonly clientSecretCiphertext: Buffer | null;
+  readonly staticToken: boolean;
+}
+
+/** Which optional columns a reader wants on top of the shared base. */
+export interface LoadAccountWithOauthStateOptions {
+  /** Select `status` from providerAccounts. */
+  readonly includeStatus?: boolean;
+  /** Select the last health category from providerAccounts. */
+  readonly includeLastErrorCategory?: boolean;
+  /** Select `expiresAt` from providerOauthStates. */
+  readonly includeExpiry?: boolean;
+  /** Also compute the skew-adjusted OAuth due time (see `loadAccountWithFreshness`). */
+  readonly includeDueAt?: boolean;
+  /** Refresh lead override for the `dueAt` skew; defaults to `refreshLeadMs(providerId)`. */
+  readonly skewMs?: number;
+}
+
+/** One loaded account row plus whatever optional columns were requested. */
+export interface LoadedAccountWithOauthState {
+  readonly id: string;
+  readonly providerId: string;
+  readonly credentialKind: CredentialKind;
+  readonly lastErrorCategory?: string | null;
+  readonly credentialCiphertext: Buffer | null;
+  readonly refreshCiphertext: Buffer | null;
+  readonly authState: unknown;
+  readonly clientSecretCiphertext: Buffer | null;
+  readonly staticToken: boolean;
+  readonly status?: string;
+  readonly expiresAt?: Date | null;
+  readonly dueAt?: number;
+}
+
 /**
- * Loads an account and its optional OAuth state in one query.
+ * Shared account+OAuth-state loader behind every status/health reader.
  *
- * `dueAt` is the OAuth expiry minus the provider's refresh lead
- * (`refreshLeadMs(providerId)`), so a token becomes due at the point that
- * provider re-mints its own (Claude ~4h, Codex ~5 days, Antigravity ~5 min).
- * Non-OAuth accounts and accounts without OAuth state have no due time.
+ * Builds the same `select(...).from(providerAccounts)` with the conditional
+ * `leftJoin` on `providerOauthStates` (the memory/Postgres dialect guard), so
+ * a schema or dialect change is fixed once instead of in four copies. The
+ * `dueAt` skew logic lives here too; `loadAccountWithFreshness` is a thin
+ * wrapper that returns it beside the row.
  */
-export async function loadAccountWithFreshness(
+export async function loadAccountWithOauthState(
   db: CartethyiaDatabase,
   accountId: string,
-  skewMs?: number,
-): Promise<AccountWithFreshness | undefined> {
+  options: LoadAccountWithOauthStateOptions = {},
+): Promise<LoadedAccountWithOauthState | undefined> {
   const selectBuilder = db
     .select({
       id: providerAccounts.id,
@@ -167,8 +210,14 @@ export async function loadAccountWithFreshness(
       refreshCiphertext: providerOauthStates.refreshCiphertext,
       authState: providerAccounts.authState,
       clientSecretCiphertext: providerOauthStates.clientSecretCiphertext,
-      expiresAt: providerOauthStates.expiresAt,
       staticToken: providerAccounts.staticToken,
+      ...(options.includeStatus === true ? { status: providerAccounts.status } : {}),
+      ...(options.includeLastErrorCategory === true
+        ? { lastErrorCategory: providerAccounts.lastErrorCategory }
+        : {}),
+      ...(options.includeExpiry === true || options.includeDueAt === true
+        ? { expiresAt: providerOauthStates.expiresAt }
+        : {}),
     })
     .from(providerAccounts);
   const query = "leftJoin" in selectBuilder
@@ -180,37 +229,60 @@ export async function loadAccountWithFreshness(
   const rows = await query.where(eq(providerAccounts.id, accountId)).limit(1);
   const row = rows[0];
   if (!row) return undefined;
-  const lead = skewMs ?? refreshLeadMs(row.providerId);
-  // A refresh-capable OAuth account with no stored expiry is unknown-liveness:
-  // we have no evidence the access token still works. The old rule left
-  // `dueAt` undefined for these, so `resolveCredentialForAccount` skipped the
-  // refresh branch and dispatch sent the pasted token as-is. For a token that
-  // had already expired on another installation (a 9router/Omniroute import
-  // carrying `accessToken` + `refreshToken` + a past `expiresAt` that was
-  // dropped by validation, a hand-pasted OAuth bundle with no expiry field,
-  // or an upstream that stopped minting expiries) that produced the exact
-  // "re-authenticate" refusal the refresh grant exists to prevent. Marking the
-  // token due immediately refreshes it on first use; the sweep handles the
-  // normal case where `expires_at` is populated.
-  const hasRefreshGrant = row.refreshCiphertext != null;
-  const kindOauth = row.credentialKind === "oauth";
-  const unknownExpiryButRefreshable =
-    kindOauth && !row.staticToken && hasRefreshGrant && row.expiresAt == null;
+  if (options.includeDueAt !== true) return row;
+  const lead = options.skewMs ?? refreshLeadMs(row.providerId);
+  // A refresh-capable OAuth account with no stored expiry has an unknown
+  // liveness, but the scheduled sweep is the only refresher: marking it due
+  // here would refresh on every load, and the dispatch path deliberately no
+  // longer refreshes inline. Unknown expiry therefore means "not due yet" —
+  // if the token actually died, the upstream's 401 triggers the dispatch
+  // retry refresh (see `attempt-loop.ts`).
+  // A static token is never "due": it is used as issued and there is no
+  // refresh to run, so the dispatch path must not treat it as stale.
+  const dueAt =
+    row.staticToken
+      ? undefined
+      : row.expiresAt != null
+        ? row.expiresAt.getTime() - lead
+        : undefined;
   return {
-    row,
-    // A static token is never "due": it is used as issued and there is no
-    // refresh to run, so the dispatch path must not treat it as stale.
-    dueAt:
-      row.staticToken
-        ? undefined
-        : row.expiresAt != null
-          ? row.expiresAt.getTime() - lead
-          : unknownExpiryButRefreshable
-            ? 0
-            : undefined,
+    ...row,
+    ...(dueAt === undefined ? {} : { dueAt }),
   };
 }
 
+/**
+ * Loads an account and its optional OAuth state in one query.
+ *
+ * `dueAt` is the OAuth expiry minus the provider's refresh lead
+ * (`refreshLeadMs(providerId)`), so a token becomes due at the point that
+ * provider re-mints its own (Claude ~4h, Codex ~5 days, Antigravity ~5 min).
+ * Non-OAuth accounts and accounts without OAuth state have no due time.
+ */
+export async function loadAccountWithFreshness(
+  db: CartethyiaDatabase,
+  accountId: string,
+  skewMs?: number,
+): Promise<AccountWithFreshness | undefined> {
+  const loaded = await loadAccountWithOauthState(db, accountId, {
+    includeDueAt: true,
+    ...(skewMs === undefined ? {} : { skewMs }),
+  });
+  if (!loaded) return undefined;
+  const row: AccountWithFreshnessRow = {
+    id: loaded.id,
+    providerId: loaded.providerId,
+    credentialKind: loaded.credentialKind,
+    credentialCiphertext: loaded.credentialCiphertext,
+    refreshCiphertext: loaded.refreshCiphertext,
+    authState: loaded.authState,
+    clientSecretCiphertext: loaded.clientSecretCiphertext,
+    expiresAt: loaded.expiresAt ?? null,
+    staticToken: loaded.staticToken,
+  };
+  return { row, dueAt: loaded.dueAt };
+}
+
 /** OAuth refresh collaborators, injected by the composition root. */
 export interface ResolveCredentialOAuth {
   /** Registry-backed refresher lookup; providers without a refresher are skipped. */
@@ -223,7 +295,7 @@ export async function resolveCredentialForAccount(
   db: CartethyiaDatabase,
   providerId: string,
   accountId: string,
-  oauth?: ResolveCredentialOAuth,
+  _oauth?: ResolveCredentialOAuth,
 ): Promise<ResolvedCredential> {
   // Cache hit: skip DB round-trip + AES-GCM decrypt.
   // Don't cache OAuth credentials whose token is due for refresh soon —
@@ -268,19 +340,14 @@ export async function resolveCredentialForAccount(
       );
     }
   }
-  if (row.credentialKind === "oauth" && oauth && dueAt !== undefined && dueAt <= Date.now()) {
-    const refresher = await oauth.resolveRefresher(row.providerId);
-    if (refresher) {
-      // Try to refresh. If it fails (refresh grant dead, upstream unreachable,
-      // etc.) keep the already-decrypted stale secret rather than wiping it:
-      // dispatch then sends the token we have, and the upstream's own 401 is
-      // the authoritative verdict. Wiping it here turned "token expired" into
-      // a credential-less GatewayError before the request ever left, which is
-      // worse than letting the server say so.
-      const refreshed = await oauth.refreshService.ensureFreshAccessToken(accountId, refresher);
-      if (refreshed) secret = refreshed;
-    }
-  }
+  // No inline refresh on the request path. OAuth tokens are kept fresh by the
+  // scheduled refresh sweep (`oauth-refresh-sweep`, due by `refreshLeadMs`),
+  // and a token that still expired before its sweep turn is answered by the
+  // upstream's own 401, which the dispatch attempt-loop turns into a forced
+  // refresh (see `attempt-loop.ts`). Refreshing here blocked a client request
+  // on the token endpoint — a hung endpoint held the request for the full 30 s
+  // refresh timeout — and re-minted tokens on every expired request instead of
+  // once per schedule.
 
   const authState = jsonbRecord(row.authState);
   const alternative: CredentialAlternative = {

package/src/providers/operations/provider-rules/github.ts

@@ -0,0 +1,48 @@
+import type {
+  AccountErrorRule,
+} from "../account-error-classification";
+
+/**
+ * Checks whether an upstream body indicates Copilot is not licensed.
+ * Copilot answers 401 for a bad credential and 403 for a
+ * license/entitlement refusal, so forbidden/unauthorized on this surface
+ * is the same verdict.
+ */
+export function copilotNotLicensed(lower: string): boolean {
+  return (
+    lower.includes("not licensed") ||
+    lower.includes("forbidden") ||
+    lower.includes("unauthorized") ||
+    lower.includes("license")
+  );
+}
+
+export const githubRules: readonly AccountErrorRule[] = [
+  {
+    // GitHub Copilot answers a license/entitlement refusal with 403 and
+    // "not licensed to use Copilot" / "forbidden" / "unauthorized". That is a
+    // verdict on the account: the subscription cannot serve this credential,
+    // and no amount of waiting or refreshing changes it. Cooldown cycling
+    // (auth_invalidated + 5m backoff) kept a dead account in rotation where a
+    // client's retry budget burned sibling accounts — the same failure the
+    // buddy ban exists to prevent. Disable immediately. Must run before
+    // `credential-rejected`, which would claim the bare 403 as a refreshable
+    // auth rejection.
+    name: "github-copilot-not-licensed",
+    match: (s) =>
+      s.origin === "upstream" &&
+      s.providerId === "github" &&
+      copilotNotLicensed(s.lower),
+    decide: (s) =>
+      s.result(
+        "policy_blocked_banned",
+        "disabled",
+        0,
+        null,
+        s.reason("GitHub Copilot account not licensed"),
+        // A license refusal is evidence about the account even at provider
+        // scope, for the same reason a named revocation or a buddy ban is.
+        true,
+      ),
+  },
+];

package/src/providers/operations/provider-rules/grok.ts

@@ -0,0 +1,33 @@
+import type { AccountErrorSignals } from "../account-error-classification";
+
+/**
+ * xAI Grok Build's free tier resets on a rolling 24-hour window, so its
+ * exhaustion is a full-day quota cooldown — never the generic 1h fallback,
+ * which let the account re-enter rotation inside the window.
+ */
+export const GROK_QUOTA_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Detects whether a quota failure belongs to Grok's free tier or spending limit.
+ */
+export function isGrokFreeTierExhaustion(s: AccountErrorSignals): boolean {
+  if (s.providerId !== undefined && s.providerId !== "grok") {
+    // If providerId is known and not grok, only match if the providerCode is explicitly grok subscription
+    if (!s.providerCode.startsWith("subscription:")) return false;
+  }
+  return (
+    s.providerCode === "subscription:free-usage-exhausted" ||
+    s.providerCode.startsWith("subscription:") ||
+    s.providerCode.includes("spending") ||
+    s.providerCode.includes("credits") ||
+    s.lower.includes("free-usage") ||
+    s.lower.includes("free usage") ||
+    s.lower.includes("included free usage") ||
+    s.lower.includes("rolling 24-hour") ||
+    s.lower.includes("rolling 24 hour") ||
+    s.lower.includes("spending limit") ||
+    s.lower.includes("out of credits") ||
+    s.lower.includes("run out of credits") ||
+    s.lower.includes("need a grok subscription")
+  );
+}

package/src/providers/operations/provider-rules/inception.ts

@@ -0,0 +1,49 @@
+import type {
+  AccountErrorRule,
+} from "../account-error-classification";
+
+/**
+ * Inception's per-minute limit window (1 minute).
+ *
+ * Inception's Free tier throttles per minute (1 000 requests / 1M input
+ * tokens / 100K output tokens) and the window resets every minute. The generic
+ * 15-minute rate-limit fallback would park a healthy key long after the window
+ * refilled; 1 minute is the provider's own cadence, hardcoded because it is a
+ * fact about the upstream, not a deployment knob.
+ */
+export const INCEPTION_RATE_LIMIT_COOLDOWN_MS = 60_000;
+
+export const inceptionRules: readonly AccountErrorRule[] = [
+  {
+    // Inception's Free tier throttles per minute (1 000 requests / 1M input
+    // tokens / 100K output tokens) and the window resets every minute. A
+    // generic 429 would cool the account for the 15-minute default, leaving a
+    // healthy key parked long after the window refilled — the source of
+    // "limitasiya lumayan keras". This arm must run before `rate-limit`: it
+    // matches the same signals and shortens the window to 1 minute so routing
+    // moves to the next account and the flagged one returns almost at once.
+    name: "inception-per-minute-limit",
+    match: (s) =>
+      s.origin === "upstream" &&
+      s.providerId === "inception" &&
+      (s.statusCode === 429 ||
+        s.providerCode === "rate_limit_reached" ||
+        s.providerCode === "rate_limit_exceeded" ||
+        s.lower.includes("rate_limit") ||
+        s.lower.includes("rate limit") ||
+        s.lower.includes("too many requests") ||
+        s.lower.includes("tokens per minute") ||
+        s.lower.includes("input token")),
+    decide: (s) => {
+      const cooldownMs = s.statedCooldownMs ?? INCEPTION_RATE_LIMIT_COOLDOWN_MS;
+      return s.result(
+        "rate_limit_transient",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Inception per-minute input-token limit"),
+        s.origin === "upstream",
+      );
+    },
+  },
+];

package/src/providers/operations/provider-rules/index.ts

@@ -0,0 +1,32 @@
+export {
+  TRAE_REGION_COOLDOWN_MS,
+  TRAE_QUOTA_COOLDOWN_MS,
+  traeRules,
+} from "./trae";
+
+export {
+  QODER_QUOTA_COOLDOWN_MS,
+  qoderPlanGatedRule,
+  qoderModelQuotaRule,
+  qoderRules,
+} from "./qoder";
+
+export {
+  githubRules,
+  copilotNotLicensed,
+} from "./github";
+
+export {
+  INCEPTION_RATE_LIMIT_COOLDOWN_MS,
+  inceptionRules,
+} from "./inception";
+
+export {
+  PERCH_TURN_RATE_LIMIT_COOLDOWN_MS,
+  perchRules,
+} from "./perch";
+
+export {
+  GROK_QUOTA_COOLDOWN_MS,
+  isGrokFreeTierExhaustion,
+} from "./grok";

package/src/providers/operations/provider-rules/perch.ts

@@ -0,0 +1,37 @@
+import type {
+  AccountErrorRule,
+} from "../account-error-classification";
+
+/**
+ * Perch's `turn_rate_limited` window. The upstream does not state a reset and
+ * answers the same on every ticket mint while the window is exhausted, so a
+ * day matches the practical cadence and stops the redial loop.
+ */
+export const PERCH_TURN_RATE_LIMIT_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+export const perchRules: readonly AccountErrorRule[] = [
+  {
+    // Perch's `turn_rate_limited` is a per-turn API window, not a per-request
+    // 429: the account keeps answering but every call mints another ticket
+    // into the same exhausted window. The stated remedy ("contact us for
+    // direct API access") implies the window is long — park the account for a
+    // day so routing picks a sibling instead of hammering the same key.
+    name: "perch-turn-rate-limit",
+    match: (s) =>
+      s.origin === "upstream" &&
+      s.providerId === "perch" &&
+      (s.providerCode === "turn_rate_limited" ||
+        (s.statusCode === 429 && s.lower.includes("turn rate"))),
+    decide: (s) => {
+      const cooldownMs = s.statedCooldownMs ?? PERCH_TURN_RATE_LIMIT_COOLDOWN_MS;
+      return s.result(
+        "rate_limit_transient",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Perch turn rate limit"),
+        s.origin === "upstream",
+      );
+    },
+  },
+];