cartethyia 2.7.3 → 2.7.5

package/src/transport/routing/route-model.ts

@@ -2,6 +2,8 @@
 import { GatewayError } from "../../protocol/gateway-error";
 import { type ServiceKind, type WireFamily } from "../../protocol/canonical-model";
 import type { CallerIdentity } from "../../security/access-control";
+import type { ProviderQuotaWindow } from "../../providers/quota/quota-contracts";
+import { log } from "../../observability/logger";
 
 export type { CallerIdentity };
 
@@ -14,6 +16,8 @@ export interface RouteCandidate {
   readonly provider_id: string;
   readonly model_id: string;
   readonly wire_family: WireFamily;
+  /** Explicit wire dialect (from `models.dialect`), when set. Absent = resolver fallback. */
+  readonly dialect?: string;
   /**
    * Protocol shape of the model. `llm` (the default) flows through the
    * canonical surface pipeline; a non-`llm` model is dispatched by its native
@@ -84,6 +88,12 @@ export interface RouteCandidate {
    * refused.
    */
   readonly pro_only?: boolean;
+  /**
+   * True when the provider publishes this model as free (its own directory
+   * statement, e.g. Qoder's `is_free`). A free model may be routed to any
+   * account — the credit-preference ordering skips it entirely.
+   */
+  readonly free_tier?: boolean;
   /**
    * The plan the provider last reported for `provider_account_id`.
    *
@@ -95,9 +105,44 @@ export interface RouteCandidate {
   readonly usage_floor?: number;
   readonly usage_floor_unit?: "credit" | "percent";
   /** Live quota windows (cache) the floor check evaluates. */
-  readonly quota_windows?: readonly unknown[];
+  readonly quota_windows?: readonly ProviderQuotaWindow[];
+  /** A successful Start Plan balance authoritatively lists its model grants. */
+  readonly quota_entitlements_known?: boolean;
 }
 
+/**
+ * A candidate as the routing engine actually evaluates it: the catalog fields
+ * above plus the health/cooling stamp `route-catalog.ts` projects onto it and
+ * the plan-time slow-lane marker.
+ *
+ * Declared here — not as a route-catalog-local intersection — so
+ * `EligibilityEvaluator.evaluate` can take the routed shape without a cast,
+ * and so every stamping site agrees on the same field set by construction.
+ */
+export type RoutedCandidate = RouteCandidate & {
+  /**
+   * Health marker the catalog projects from `provider_accounts.status` and
+   * unexpired `model_cooldowns` entries. Absent = no health exclusion known.
+   * Mutable by declaration: the catalog builds the base candidate first and
+   * stamps health/cooling onto it as account rows are walked.
+   */
+  health_status?: "cooldown" | "model_cooldown" | "disabled";
+  /** Cooldown class the catalog derives from the account's last error category. */
+  cooldown_kind?: "hard" | "soft";
+  /**
+   * Epoch milliseconds at which this candidate's cooling window ends, when one
+   * is in force. Routing-internal: it is what lets `plan()` report a real reset
+   * on the all-accounts-cooling answer, and it never reaches a client verbatim —
+   * only the derived `retry-after` does.
+   */
+  cooldown_until?: number;
+  /**
+   * Slow-lane stamp applied at plan time (test-supported; runtime slow-lane
+   * activity is read live via `sharedClaudeSlowLanes.isActive`).
+   */
+  lane?: "slow";
+};
+
 /**
  * Provider-routing strategies. The runtime tuple is the source: the console's
  * Elysia body schema builds its `t.Literal` union from these values and its
@@ -270,7 +315,6 @@ export type EligibilityReason =
   | "cooldown_hard"
   | "model_cooldown"
   | "quota_exhausted"
-  | "locked"
   | "disabled"
 
 export interface EligibilityDecision {
@@ -280,7 +324,7 @@ export interface EligibilityDecision {
   /**
    * Epoch milliseconds at which this candidate's cooling window ends, when the
    * exclusion that produced this decision carries one. Absent for a healthy
-   * candidate and for every reason with no deadline (`disabled`, `locked`,
+   * candidate and for every reason with no deadline (`disabled`,
    * `quota_exhausted` from spent windows or the usage floor). `plan()` takes the
    * minimum across the cooling set to report the earliest reset a client could
    * retry against.
@@ -328,7 +372,7 @@ export interface AdmissionController {
  * Translates the evaluator's internal reason codes into operator English.
  *
  * These names are the vocabulary the routing layers use with each other —
- * `model_cooldown`, `cooldown_hard`, `locked` — not something to print into the
+ * `model_cooldown`, `cooldown_hard` — not something to print into the
  * public message, where the client would read an enum instead of an
  * explanation. The codes stay in the envelope's `reasons` field for anyone who
  * wants them; the sentence carries what they mean.
@@ -342,9 +386,9 @@ const ELIGIBILITY_REASON_LABELS: Readonly<Record<string, string>> = {
   cooldown_hard: "every account is in a hard cooldown",
   cooldown: "accounts are cooling down",
   disabled: "all accounts are disabled",
-  locked: "all accounts are locked by another request",
   credit_floor_reached: "credit or quota is exhausted",
   quota_exhausted: "every account has an exhausted quota window or is below its configured usage floor",
+  capability_unsupported: "the accounts serving this model do not support the request's capabilities (e.g. images, tools, or reasoning)",
 };
 
 function explainEligibilityReasons(reasons: readonly string[]): string {
@@ -358,7 +402,7 @@ export function ambiguousModelError(bare: string, owners: string[]): GatewayErro
   return new GatewayError(
     "ambiguous_model",
     400,
-    `'${bare}' matches more than one provider (${owners.join(", ")}). Qualify it as '${owners[0]}/${bare}', or add an alias to pick one.`,
+    `'${bare}' matches more than one provider (${owners.join(", ")}). Qualify it as '${owners[0]}/${bare}', or add an alias to pick one. Too popular for its own good — qualify it 🧩`,
     {
       model: bare,
       owners,
@@ -380,7 +424,7 @@ export function modelNotFoundError(requested: string, resolved: readonly string[
     404,
     `'${requested}' is not routed${
       targets.length > 0 ? ` — it resolved to ${hint}, which no account serves` : ""
-    }. Enable the model on an account, or point the alias at one that exists.`,
+    } (request {requestId}). Enable the model on an account, or point the alias at one that exists. Try another model — this one's off the menu 📚`,
     {
       model: requested,
       ...(targets.length > 0 ? { resolved_models: targets } : {}),
@@ -388,15 +432,6 @@ export function modelNotFoundError(requested: string, resolved: readonly string[
   );
 }
 
-export function capabilityUnsupportedError(capability: string): GatewayError {
-  return new GatewayError(
-    "capability_unsupported",
-    400,
-    `No account serving this model supports ${capability}. Drop the ${capability} part of the request, or route to a model that accepts it.`,
-    { capability },
-  );
-}
-
 /**
  * Every candidate in the plan refused admission: each account is already
  * serving its configured max-inflight.
@@ -424,8 +459,8 @@ export function capacityExhaustedError(context?: {
     "provider_capacity_exhausted",
     429,
     onlyOne
-      ? "The only account routing this model is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add another account."
-      : "Every account is at its concurrency limit. Retry shortly; if it persists, raise the provider's max-inflight or add an account.",
+      ? "The only account routing this model is at its concurrency limit (request {requestId}). Retry shortly; if it persists, raise the provider's max-inflight or add another account. Even the machine needs a rest — chill 🦋"
+      : "Every account is at its concurrency limit (request {requestId}). Retry shortly; if it persists, raise the provider's max-inflight or add an account. Even the machine needs a rest — chill 🦋",
     {
       ...(context?.providerId !== undefined ? { providerId: context.providerId } : {}),
       ...(context?.model !== undefined ? { model: context.model } : {}),
@@ -439,7 +474,7 @@ export function capacityExhaustedError(context?: {
 
 /**
  * The model exists and is routed, but every account serving it is currently
- * unusable (disabled / locked). This is transient and
+ * unusable (disabled). This is transient and
  * retry-able, so it must NOT surface as `model_not_found` — a 404 tells the
  * client to fix its request when the real fix is to wait or add capacity.
  *
@@ -453,10 +488,18 @@ export function accountsUnavailableError(
   reasons: readonly string[],
 ): GatewayError {
   const distinct = [...new Set(reasons)].sort();
+  const capabilityBlocked = distinct.includes("capability_unsupported");
+  // When the blocker is a capability (the model exists and accounts exist, but
+  // none can carry the request's images/tools/reasoning), telling the client to
+  // "add an account" or wait out a coffee break is misleading — more accounts
+  // cannot conjure a capability the model itself lacks. Name the real fix.
+  const hint = capabilityBlocked
+    ? "Request a model that supports this capability (or a vision-capable model for images), or drop the unsupported part of the request. The model is the limit, not the pool 🧰"
+    : "Add an account, or wait for an operator to re-enable one. Every account is on a coffee break — try later ☕️";
   return new GatewayError(
     "accounts_unavailable",
     503,
-    `No account in the pool can serve '${requested}' right now (${explainEligibilityReasons(distinct)}). Add an account, or wait for an operator to re-enable one.`,
+    `No account in the pool can serve '${requested}' right now (request {requestId}) (${explainEligibilityReasons(distinct)}). ${hint}`,
     { model: requested, reasons: distinct, candidate_count: reasons.length, gateway_hint: "no_healthy_account" },
   );
 }
@@ -492,7 +535,7 @@ export function accountsRateLimitedError(
   return new GatewayError(
     "accounts_rate_limited",
     429,
-    `Every account serving '${requested}'${routeNote} is cooling down after hitting upstream limits. The request is fine — retry once the cooldown resets.`,
+    `Every account serving '${requested}'${routeNote} is cooling down after hitting upstream limits (request {requestId}). The request is fine — retry once the cooldown resets. They're resting up 🌸`,
     {
       model: requested,
       routed_model: routed,
@@ -536,42 +579,83 @@ export class InMemoryRouteSnapshotService implements RouteSnapshotService {
    * only populate the cache if no mutation happened while it ran.
    */
   private building: { revision: RoutingRevision; promise: Promise<RouteSnapshot> } | undefined;
-
-  constructor(private readonly builder: SnapshotBuilder) {
+  /**
+   * Debounced background-rebuild timer (G-02). One invalidate schedules a
+   * rebuild; a burst of invalidates within `rebuildDebounceMs` coalesces into
+   * the single latest-revision rebuild. The timer is cleared on `stop()`.
+   */
+  private rebuildTimer: ReturnType<typeof setTimeout> | undefined;
+  private stopped = false;
+
+  constructor(
+    private readonly builder: SnapshotBuilder,
+    options: { readonly rebuildDebounceMs?: number } = {},
+  ) {
+    this.rebuildDebounceMs = options.rebuildDebounceMs ?? 500;
     // Peers' mutations arrive once per process, not per instance: the handler
-    // drops this instance's copy, which is the only one there is.
+    // schedules a background rebuild, which is the only one there is.
     this.unsubscribe = subscribeRoutingInvalidation(() => {
       this.revision += 1;
-      this.snapshot = undefined;
+      this.scheduleRebuild();
     });
   }
 
-  /** Ends the peer-invalidation subscription. */
+  /** Ends the peer-invalidation subscription and clears the rebuild timer. */
   readonly unsubscribe: () => void;
 
-  async getSnapshot(): Promise<RouteSnapshot> {
-    if (this.snapshot) return this.snapshot;
-    if (this.building && this.building.revision === this.revision) return this.building.promise;
+  /** Wall-clock debounce for coalescing invalidate bursts. */
+  private readonly rebuildDebounceMs: number;
+
+  /**
+   * Schedules a background rebuild at the current revision. Debounced: while a
+   * timer is pending, further invalidates just bump the revision and the
+   * pending rebuild picks up the latest. Single-flight by construction — the
+   * rebuild itself reuses {@link building}, so concurrent callers share one
+   * promise for the same revision.
+   */
+  private scheduleRebuild(): void {
+    if (this.stopped || this.rebuildTimer !== undefined) return;
+    this.rebuildTimer = setTimeout(() => {
+      this.rebuildTimer = undefined;
+      void this.rebuildNow().catch((error: unknown) => {
+        // A background rebuild failure is a soft miss: requests served the
+        // last-completed snapshot, and the next invalidation retries.
+        log.warn("[route-snapshot] background rebuild failed", error as Error);
+      });
+    }, this.rebuildDebounceMs);
+    if (typeof this.rebuildTimer.unref === "function") this.rebuildTimer.unref();
+  }
+
+  /** Starts (or joins) the build for the current revision. */
+  private rebuildNow(): Promise<RouteSnapshot> {
     const revision = this.revision;
+    if (this.building && this.building.revision === revision) return this.building.promise;
     const promise = this.build(revision);
     this.building = { revision, promise };
-    try {
-      return await promise;
-    } finally {
+    void promise.finally(() => {
       // Only the build that is still current may clear the slot; a build
       // started after a mutation must not be dropped by an older one finishing.
       if (this.building?.promise === promise) this.building = undefined;
-    }
+    });
+    return promise;
   }
 
+  async getSnapshot(): Promise<RouteSnapshot> {
+    // G-02: serve the last-completed snapshot while a rebuild runs, so the
+    // page-open request path never pays the catalog build. Only a cold start
+    // (no snapshot at all) falls through to a synchronous build here.
+    if (this.snapshot) return this.snapshot;
+    return this.rebuildNow();
+  }
 
   async invalidate(): Promise<RoutingRevision> {
     this.revision += 1;
-    this.snapshot = undefined;
-    // Lazy: the next getSnapshot() rebuilds. Dashboard mutations only need
-    // the new revision token — they must not pay seven Postgres round-trips
-    // inside the mutating request while holding no pool pressure budget.
-    //
+    // G-02: trigger a BACKGROUND rebuild immediately instead of clearing the
+    // snapshot and making the next request pay. The rebuild is debounced so a
+    // burst of invalidates (a recovery sweep, a cascade of console writes)
+    // coalesces into one rebuild, and it never blocks the mutating request —
+    // a console write does not wait on its own rebuild here.
+    this.scheduleRebuild();
     // Broadcast, because `reusePort` runs several gateway processes and each
     // holds its own snapshot: a console write handled by one of them left the
     // others serving pre-write routing until something else invalidated them.
@@ -581,6 +665,15 @@ export class InMemoryRouteSnapshotService implements RouteSnapshotService {
     return this.revision;
   }
 
+  /** Stops background rebuilds. Test/teardown helper. */
+  stop(): void {
+    this.stopped = true;
+    if (this.rebuildTimer !== undefined) {
+      clearTimeout(this.rebuildTimer);
+      this.rebuildTimer = undefined;
+    }
+  }
+
   private async build(revision: RoutingRevision): Promise<RouteSnapshot> {
     const built = await this.builder();
     const providerRouting: ProviderRoutingMap | undefined = built.providerRouting

package/src/transport/routing/router.ts

@@ -12,6 +12,7 @@ import {
   type ProviderRoutingSetting,
   type Reservation,
   type RouteCandidate,
+  type RoutedCandidate,
   type RoutePlan,
   type EligibilityDecision,
   type RouteContinuationAffinity,
@@ -34,22 +35,100 @@ import {
 } from "./candidate-index";
 import { totalRemainingCredit, totalRemainingPercent, type ProviderQuotaWindow } from "../../providers/quota/quota-contracts";
 import { getCachedQuotaEntry, quotaLens } from "../../providers/quota/cache";
+import { readQuotaSnapshot } from "../../providers/quota/snapshot";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import type { RedisClient } from "../../persistence/redis";
 import { sharedClaudeSlowLanes } from "../../providers/integrations/claude/claude-slow-lane";
 
+/**
+ * Filters quota windows to those relevant to the candidate model.
+ * Providers like Antigravity report separate quotas for distinct model families
+ * (Gemini vs Claude/GPT), and Grok reports per-product buckets.
+ * Evaluating a Claude exhaustion against a Gemini request would incorrectly
+ * mark the account exhausted for Gemini when Gemini capacity is still available.
+ */
+export function filterCandidateQuotaWindows(
+  windows: readonly ProviderQuotaWindow[],
+  candidate: { readonly provider_id?: string; readonly model_id?: string },
+): readonly ProviderQuotaWindow[] {
+  if (windows.length === 0) return windows;
+  const providerId = candidate.provider_id?.toLowerCase() ?? "";
+  const modelId = candidate.model_id?.toLowerCase() ?? "";
+  windows = windows.filter((window) => window.modelIds === undefined || window.modelIds.includes(modelId));
+
+  if (providerId === "antigravity") {
+    const isGemini = /gemini|tab_flash/i.test(modelId);
+    const isClaude = /claude|opus|sonnet/i.test(modelId);
+    if (isGemini) {
+      return windows.filter((w) => {
+        const text = `${w.kind} ${w.label}`.toLowerCase();
+        if (text.includes("gemini") || text.includes("google")) return true;
+        return !text.includes("claude") && !text.includes("gpt");
+      });
+    }
+    if (isClaude) {
+      return windows.filter((w) => {
+        const text = `${w.kind} ${w.label}`.toLowerCase();
+        if (text.includes("claude") || text.includes("gpt")) return true;
+        return !text.includes("gemini") && !text.includes("google");
+      });
+    }
+  }
+
+  if (providerId === "grok") {
+    return windows.filter((w) => {
+      if (w.kind.startsWith("product:")) {
+        const product = w.kind.split(":")[1]?.toLowerCase();
+        return product ? modelId.includes(product) : true;
+      }
+      return true;
+    });
+  }
+
+  return windows;
+}
+
 /**
  * True when the account's remaining allowance is at or below its provider's
  * floor. Credit mode sums the absolute remaining credit; percent mode uses the
  * aggregate credit percentage and the lowest independent percentage window.
  * No reading means unknown, which is not below the floor.
  */
-function belowUsageFloor(state: {
-  readonly usage_floor?: number;
-  readonly usage_floor_unit?: "credit" | "percent";
-  readonly quota_windows?: readonly unknown[] | undefined;
-}): boolean {
-  const windows = state.quota_windows as readonly ProviderQuotaWindow[] | undefined;
-  if (windows === undefined || windows.length === 0) return false;
+function belowUsageFloor(state: RoutedCandidate): boolean {
+  const rawWindows = state.quota_windows;
+  // A successful Start Plan balance (`quota_entitlements_known`) authoritatively
+  // lists its model grants: when the provider is zcode-start and no window
+  // matches the requested model, the account is below the floor even with an
+  // empty/absent window list — there is no grant to fund the model.
+  if (state.provider_id === "zcode-start" && state.quota_entitlements_known === true) {
+    if (rawWindows === undefined || rawWindows.length === 0) return true;
+    const knownGrants = rawWindows.some((window) => window.modelIds !== undefined);
+    if (!knownGrants) return true;
+  }
+  if (rawWindows === undefined || rawWindows.length === 0) return false;
+  const relevant = filterCandidateQuotaWindows(rawWindows, state);
+  // Model-scoped grants (Start Plan) are checked separately: a grant that has
+  // not started, has expired, or is exhausted cannot fund the requested model,
+  // so it must not count as credit.
+  const now = Date.now();
+  const grants = relevant.filter((window) => window.modelIds !== undefined);
+  if (state.provider_id === "zcode-start" && grants.length === 0 && rawWindows.some((window) => window.modelIds !== undefined)) {
+    return true;
+  }
+  if (
+    grants.length > 0 &&
+    !grants.some((window) => {
+      if (window.startsAt && Date.parse(window.startsAt) > now) return false;
+      if (window.resetsAt && Date.parse(window.resetsAt) <= now) return false;
+      if (typeof window.remaining === "number" && window.remaining <= 0) return false;
+      if (typeof window.remainingPercent === "number" && window.remainingPercent <= 0) return false;
+      const remaining = state.usage_floor_unit === "credit" ? window.remaining : window.remainingPercent;
+      return state.usage_floor === undefined || remaining == null || remaining > state.usage_floor;
+    })
+  ) {
+    return true;
+  }
+  const windows = relevant.filter((window) => window.modelIds === undefined);
   const credit = totalRemainingCredit(windows);
   const percent = totalRemainingPercent(windows);
   const exhaustedIndependentWindow = windows.some(
@@ -67,6 +146,21 @@ function belowUsageFloor(state: {
   return remaining !== null && remaining <= floor;
 }
 
+/**
+ * Routing priority for an account's remaining allowance when two candidates sit
+ * in the same rank group: positive remaining credit first, then unknown, then
+ * known-zero last. Free-tier models skip the preference entirely — a free model
+ * routes to any account, as the provider's own directory stated it is free.
+ */
+function creditPriority(candidate: RoutedCandidate): number {
+  if (candidate.free_tier === true) return 0;
+  const windows = candidate.quota_windows;
+  if (windows === undefined || windows.length === 0) return 0;
+  const credit = totalRemainingCredit(windows);
+  if (credit === null) return 0;
+  return credit > 0 ? 1 : -1;
+}
+
 /**
  * Normalizes a requested model name before alias lookup. Coding-agent CLIs
  * version their model ids with variant suffixes (`claude-opus-5[1m]`,
@@ -233,10 +327,17 @@ function spreadDeadline(cooldownUntil: number | undefined): { cooldown_until?: n
 function earliestWindowResetMs(
   windows: readonly ProviderQuotaWindow[] | undefined,
   nowMs: number,
+  candidate: RouteCandidate,
 ): number | undefined {
   if (windows === undefined) return undefined;
+  windows = filterCandidateQuotaWindows(windows, candidate);
   let earliest: number | undefined;
   for (const window of windows) {
+    if (window.startsAt && Date.parse(window.startsAt) > nowMs) {
+      const at = Date.parse(window.startsAt);
+      if (earliest === undefined || at < earliest) earliest = at;
+      continue;
+    }
     if (typeof window.resetsAt !== "string" || window.resetsAt.length === 0) continue;
     const at = Date.parse(window.resetsAt);
     if (!Number.isFinite(at) || at <= nowMs) continue;
@@ -249,7 +350,7 @@ function earliestWindowResetMs(
  * The earliest instant any cooling candidate recovers, in epoch ms.
  *
  * `undefined` when no decision carries a deadline — which is the honest answer
- * for a set whose exclusions have no reset (`disabled`, `locked`), and keeps
+ * for a set whose exclusions have no reset (`disabled`), and keeps
  * `accountsRateLimitedError` from reporting a number nobody measured. The
  * minimum, not the maximum: the client can be served as soon as the *first*
  * account comes back, so quoting the slowest would hold it off longer than it
@@ -268,36 +369,22 @@ function earliestResetMs(
 }
 
 export class EligibilityEvaluator {
-  evaluate(candidate: RouteCandidate): EligibilityDecision {
-    const state = candidate as RouteCandidate & {
-      readonly health_status?: string;
-      readonly cooldown_kind?: "hard" | "soft";
-      readonly cooldown_until?: number;
-      readonly account_locked?: boolean;
-      readonly locked?: boolean;
-      readonly usage_floor?: number;
-      readonly usage_floor_unit?: "credit" | "percent";
-      readonly quota_windows?: readonly ProviderQuotaWindow[] | undefined;
-      /** Slow-lane stamp applied at plan time; see `applySlowLane`. */
-      readonly lane?: "slow";
-    };
-    if (state.account_locked || state.locked)
-      return { eligible: false, reason: "locked", candidate };
-    if (state.health_status === "disabled")
+  evaluate(candidate: RoutedCandidate): EligibilityDecision {
+    if (candidate.health_status === "disabled")
       return { eligible: false, reason: "disabled", candidate };
-    if (state.health_status === "model_cooldown")
-      return { eligible: false, reason: "model_cooldown", candidate, ...spreadDeadline(state.cooldown_until) };
-    if (state.health_status === "cooldown" && state.cooldown_kind === "hard")
-      return { eligible: false, reason: "cooldown_hard", candidate, ...spreadDeadline(state.cooldown_until) };
+    if (candidate.health_status === "model_cooldown")
+      return { eligible: false, reason: "model_cooldown", candidate, ...spreadDeadline(candidate.cooldown_until) };
+    if (candidate.health_status === "cooldown" && candidate.cooldown_kind === "hard")
+      return { eligible: false, reason: "cooldown_hard", candidate, ...spreadDeadline(candidate.cooldown_until) };
     // The floor is checked here, not after selection: an account below its
     // floor must not win the route. An account with no reading is left
     // eligible — a missing quota fetch is not proof the allowance is gone.
-    if (belowUsageFloor(state))
+    if (belowUsageFloor(candidate))
       return {
         eligible: false,
         reason: "quota_exhausted",
         candidate,
-        ...spreadDeadline(earliestWindowResetMs(state.quota_windows, Date.now())),
+        ...spreadDeadline(earliestWindowResetMs(candidate.quota_windows, Date.now(), candidate)),
       };
     // A slow lane is orthogonal to cooldown, never a member of it: the account
     // still serves on spare capacity when the request carries the slow usage
@@ -308,10 +395,10 @@ export class EligibilityEvaluator {
     // exclusion, not that it overrides one. An account with no usable allowance
     // is not rescued by the lane — the lane is a latency budget against spare
     // capacity, and an account below its floor has none.
-    if (state.lane === "slow")
+    if (candidate.lane === "slow")
       return { eligible: true, reason: "slow", candidate };
-    if (state.health_status === "cooldown")
-      return { eligible: true, reason: "cooldown", candidate, ...spreadDeadline(state.cooldown_until) };
+    if (candidate.health_status === "cooldown")
+      return { eligible: true, reason: "cooldown", candidate, ...spreadDeadline(candidate.cooldown_until) };
     return { eligible: true, reason: "healthy", candidate };
   }
 
@@ -332,6 +419,7 @@ export class RoutingEngine {
   constructor(
     private readonly admission: AdmissionController = new InMemoryAdmissionController(),
     private readonly redis?: RedisClient,
+    private readonly db?: CartethyiaDatabase,
   ) {}
 
   private getRoundRobin(key: string): RoundRobinState {
@@ -467,13 +555,32 @@ export class RoutingEngine {
       accountId,
       this.redis,
     ).catch(() => undefined);
-    const quotaWindows = cached?.quota.windows ?? [];
+    // The live cache is authoritative when warm; when it is cold (e.g. right
+    // after a restart, before the sweep re-reads accounts), fall back to the
+    // persisted quota snapshot — the durable source of truth — so routing
+    // still prefers accounts that actually have remaining credit. The snapshot
+    // is never fresher than the cache, but a stale balance beats an unknown
+    // one for ordering, and the sweep refreshes it on schedule.
+    let quota = cached?.quota;
+    if (quota === undefined && this.db !== undefined) {
+      const stored = await readQuotaSnapshot(this.db, accountId).catch(() => null);
+      quota = stored?.quota;
+    }
+    const rawWindows = quota?.windows;
+    // The cache is authoritative when it has a reading; when it does not,
+    // keep whatever the candidate already carried (the credit ordering reads
+    // these windows, and a miss must not erase a stamped value).
+    const quotaWindows =
+      rawWindows === undefined
+        ? undefined
+        : candidate.provider_id === "zcode-start" ? rawWindows : filterCandidateQuotaWindows(rawWindows, candidate);
     return {
       ...candidate,
       ...(setting?.usageFloor == null
         ? {}
         : { usage_floor: setting.usageFloor, usage_floor_unit: setting.usageFloorUnit }),
-      quota_windows: quotaWindows,
+      ...(quotaWindows === undefined ? {} : { quota_windows: quotaWindows }),
+      ...(quota?.source === "zcode-start" && quota.error === null ? { quota_entitlements_known: true } : {}),
     };
   }
 
@@ -624,7 +731,7 @@ export class RoutingEngine {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result belongs to a Cursor account that is no longer routable. Reconnect the account, or resend the complete conversation.",
+        "This tool result belongs to a Cursor account that is no longer routable (request {requestId}). Reconnect the account, or resend the complete conversation. The session went cold — reconnect or resend 🔌",
         {
           providerId: affinity.providerId,
           accountId: affinity.providerAccountId,
@@ -641,6 +748,11 @@ export class RoutingEngine {
     const pinnedDecisions = pinned.map((candidate) => this.eligibility.evaluate(candidate));
     const blocked = pinnedDecisions.find((decision) => !decision.eligible);
     if (blocked !== undefined) {
+      // A rebaseable continuation (complete conversation replay) is not owed
+      // to this account: the recorded exchange may travel as history to a
+      // fresh Run on an eligible account. Cooling/blocked pinned account must
+      // not turn that into a hard refusal — fall through to normal routing.
+      if (affinity.rebaseable) return null;
       const reason = blocked.reason;
       if (
         reason === "cooldown_hard" ||
@@ -652,7 +764,7 @@ export class RoutingEngine {
       throw new GatewayError(
         "invalid_request",
         400,
-        "This tool result belongs to an account that is no longer routable. Reconnect the account, or resend the complete conversation.",
+        "This tool result belongs to an account that is no longer routable (request {requestId}). Reconnect the account, or resend the complete conversation. The session went cold — reconnect or resend 🔌",
         {
           providerId: affinity.providerId,
           accountId: affinity.providerAccountId,
@@ -810,11 +922,14 @@ export class RoutingEngine {
       );
     }
 
-    // Single sort by rank (fresh → slow → cooling → saturated), stable.
+    // Single sort by rank (fresh → slow → cooling → saturated), stable. Within
+    // the same rank, accounts with remaining credit come first unless the model
+    // is free tier, which routes to any account.
     eligible = [...eligible].sort((left, right) => {
       const leftRank = decisions.get(admissionKey(left))?.rank ?? ROUTING_RANK.FRESH;
       const rightRank = decisions.get(admissionKey(right))?.rank ?? ROUTING_RANK.FRESH;
-      return leftRank - rightRank;
+      if (leftRank !== rightRank) return leftRank - rightRank;
+      return creditPriority(right) - creditPriority(left);
     });
 
     // Provider routing rotates accounts within the same rank group only; it can