cartethyia 2.7.9 → 2.8.0

package/src/transport/failure-policy.ts

@@ -2,7 +2,6 @@ import { GatewayError, type GatewayErrorCode, type GatewayErrorOrigin } from "..
 import { isRecord } from "../protocol/codecs";
 import { resolveFallbackRetryBaseMs, resolveFallbackRetryCapMs } from "../config/timeouts";
 import { parseUpstreamBackoff } from "../protocol/upstream-parsing";
-import { resolveAccountQuotaCooldownMs } from "../config/cooldowns";
 
 /**
  * How much of the upstream's error body is kept and surfaced.
@@ -260,31 +259,6 @@ export function classifyUpstreamFailure(error: unknown): UpstreamFailurePolicy {
   // DNS failure. Failing the client request instead of failing over is the wrong
   // outcome for a whole class the table already names as platform-wide.
   const statusCode = error.status;
-  // Qoder answers an exhausted quota by closing the stream with an upstream 499
-  // (nginx client-close style). That is a refusal from the upstream — the
-  // gateway's own aborts are `transport_closed`, produced locally, and never
-  // carry a qoder providerId — so a 499 scoped to qoder is quota, not a
-  // malformed request. Without this it fell through to `invalid_request`
-  // (non-retryable, no cooldown) and the account was re-dialled on every
-  // request inside the exhausted window until a late 429 finally classified it.
-  if (
-    error.origin === "upstream" &&
-    statusCode === 499 &&
-    (providerId === "qoder" || providerId === "qodercn")
-  ) {
-    const cooldownMs = resolveAccountQuotaCooldownMs();
-    return {
-      retryable: true,
-      mutatesAccount: true,
-      category: "quota_exceeded",
-      scope: "account",
-      origin: error.origin,
-      ...(providerCode ? { providerCode } : {}),
-      ...(providerId ? { providerId } : {}),
-      cooldownMs,
-      statusCode,
-    };
-  }
   const retryableByStatus =
     statusCode === 401 ||
     statusCode === 403 ||
@@ -684,10 +658,8 @@ const QUOTA_ERROR_IDENTIFIERS: ReadonlySet<string> = new Set([
   // quota (a cooldown) instead of `auth_invalidated`.
   "110",
   // Qoder also reports quota exhaustion as `{"code":116,"error":"quota
-  // exceeded"}` (seen on the IDE model-server surface with a 499/stream
-  // close). The 499 special-case below already treats qoder 499 as quota;
-  // naming the code here makes any status that carries it classify as quota
-  // instead of `invalid_request`/`authentication_failed`.
+  // exceeded"}`. Naming the code here makes any status that carries it classify
+  // as quota instead of `invalid_request`/`authentication_failed`.
   "116",
   // InferHub publishes its own vocabulary in `error.code`. The two 403s below
   // are deliberate absences: `account_blocked` means the account was blocked
@@ -846,6 +818,20 @@ export function classifyUpstreamError(
     return { code: "proxy_auth_required", status: 407, origin: "network" };
   if (normalized === "11140")
     return { code: "policy_rejected", status: 403, origin: "upstream" };
+  // ZCode plan-lane envelope codes (verified live 2026-10-30 by the donor and
+  // mirrored by the zcode-start provider). `3009` is model concurrency
+  // (transient, retried in place), `3008` user concurrency (the desktop client
+  // is busy on that account — switchable), `3012` is the identity/prompt-shape
+  // gate, `1113` the paid-lane "insufficient balance or no resource package"
+  // (a request that was not recognized as start-plan traffic).
+  if (normalized === "3009")
+    return { code: "rate_limited", status: 429, origin: "upstream" };
+  if (normalized === "3008")
+    return { code: "accounts_rate_limited", status: 429, origin: "upstream" };
+  if (normalized === "3012")
+    return { code: "policy_rejected", status: 405, origin: "upstream" };
+  if (normalized === "1113")
+    return { code: "quota_exceeded", status: 429, origin: "upstream", rateLimitScope: "provider" };
   if (normalized !== undefined && CONTEXT_LENGTH_CODES.has(normalized))
     return { code: "context_length_exceeded", status: 413, origin: "upstream" };
   if (normalized !== undefined && QUOTA_ERROR_IDENTIFIERS.has(normalized))

package/src/transport/guards/body-policy.ts

@@ -58,8 +58,14 @@ export function isProxyDispatchRoute(path: string | undefined): path is string {
   return path !== undefined && isJsonProxyRoute(path);
 }
 
+/**
+ * The same canonical JSON-route membership as `isProxyDispatchRoute`, kept as
+ * a non-narrowing alias for callers that already hold a string path. One
+ * predicate, two spellings, so a route-table change cannot diverge between
+ * the body-read policy and the canonical-parse gate.
+ */
 export function isJsonProxyRoutePath(path: string): boolean {
-  return isJsonProxyRoute(path);
+  return isProxyDispatchRoute(path);
 }
 
 interface IngressPolicyOptions {

package/src/transport/guards/error-lifecycle.ts

@@ -77,8 +77,20 @@ export function createErrorNormalizationMiddleware(deps: {
     .error(({ request, error, set }) => {
       const state = deps.stateStore.get(request as Request);
       const gateway = error instanceof GatewayError ? error : undefined;
+      // Elysia's built-in errors (NotFound, ValidationError, ParseError,
+      // InternalServerError) always carry a numeric `status` **and** a code.
+      // A raw runtime error can carry a `.code` on its own — Bun's fetch
+      // surfaces `TypeError` with `code: "ECONNRESET"` when an upstream socket
+      // dies mid-response — so a `code` alone is not evidence of an Elysia
+      // built-in. Requiring the numeric status keeps that raw error from
+      // leaking into the public envelope as a fake code/400; the dispatch loop
+      // already normalizes socket drops to `transport_unavailable`/502 before
+      // they reach here.
       const builtin =
-        !gateway && typeof error === "object" && error !== null
+        !gateway &&
+        typeof error === "object" &&
+        error !== null &&
+        typeof (error as ElysiaBuiltinError).status === "number"
           ? (error as ElysiaBuiltinError)
           : undefined;
       const builtinStatus = typeof builtin?.status === "number" ? builtin.status : undefined;

package/src/transport/guards/request-context.ts

@@ -12,7 +12,7 @@ import { resolveClientIdentity } from "../../security/ip-boundary";
 import { GATEWAY_SECURITY_HEADERS } from "../../security/outbound-headers";
 import { pushStructuredConsoleLog } from "../../observability/log-ring";
 import { log } from "../../observability/logger";
-import { isJsonProxyRoutePath, isProxyDispatchRoute } from "./body-policy";
+import { isProxyDispatchRoute } from "./body-policy";
 import { isOpaqueBodyRoute } from "../contracts";
 import { peerAddressUnavailableError } from "./guard-errors";
 
@@ -24,6 +24,24 @@ interface RequestApp {
   ): RequestApp;
 }
 
+/**
+ * Whether this request falls outside the canonical JSON-proxy pipeline the
+ * canonical-parse and route-preparation stages serve.
+ *
+ * Shared gate, applied in the exact order both middlewares historically
+ * checked: non-`/v1/` paths, GET/HEAD (which carry no body to parse), then
+ * the JSON route table with opaque-body routes excluded — `/v1/completions`
+ * needs no separate arm because it is already in the JSON routes table, and
+ * native routes (compact, System One, token count) read a body but are never
+ * parsed into a canonical request, their bodies being opaque by contract.
+ */
+function skipNonCanonicalProxyRequest(request: Request): boolean {
+  const path = fastPathname(request.url);
+  if (!path.startsWith("/v1/")) return true;
+  if (request.method === "GET" || request.method === "HEAD") return true;
+  return !isProxyDispatchRoute(path) || isOpaqueBodyRoute(path);
+}
+
 interface RequestContextDeps {
   readonly stateStore: ProxyRequestStateStore;
   readonly clock?: () => number;
@@ -141,15 +159,9 @@ export function createCanonicalRequestMiddleware(deps: {
 }): Elysia {
   return new Elysia()
     .beforeHandle(async ({ request }) => {
-      const path = fastPathname(request.url);
-      if (!path.startsWith("/v1/")) return;
-      if (request.method === "GET" || request.method === "HEAD") return;
-      // `/v1/completions` needs no separate arm: it is already in
-      // the JSON routes table, so the body-policy predicate covers it.
-      // Native routes (compact, System One) read a body but are never parsed
-      // into a canonical request — their bodies are opaque by contract.
-      if (!isJsonProxyRoutePath(path) || isOpaqueBodyRoute(path)) return;
       // Model discovery and other GET/multimodal routes must not go through canonical parsing.
+      if (skipNonCanonicalProxyRequest(request)) return;
+      const path = fastPathname(request.url);
       const state = deps.stateStore.require(request);
       // Single-read invariant: the ingress policy middleware already decoded the
       // body once into `state.ingressBody`. Never re-read `request.body` here —
@@ -216,11 +228,7 @@ export function createProxyRoutePreparationMiddleware(deps: {
 }): Elysia {
   return new Elysia()
     .beforeHandle(async ({ request }) => {
-      const path = fastPathname(request.url);
-      if (!path.startsWith("/v1/")) return;
-      if (request.method === "GET" || request.method === "HEAD") return;
-      const isJsonRoute = isJsonProxyRoutePath(path);
-      if (!isJsonRoute || isOpaqueBodyRoute(path)) return;
+      if (skipNonCanonicalProxyRequest(request)) return;
       const state = deps.stateStore.require(request);
       if (!state.authorization || !state.canonicalRequest)
         throw new GatewayError("route_unavailable", 503, "The request was not authenticated and parsed, so this route cannot be served (request {requestId}). Resend the request. The bouncer stepped out — resend shortly 🚪");

package/src/transport/request/preparer.ts

@@ -5,7 +5,7 @@ import type { ApiKeyAdmissionService } from "../../security/admission/service";
 import type { VisionHandoffCall, VisionHandoffResult } from "../vision-handoff";
 import { isImageOrPlaceholderPart, lastImageCarryingUserTurnIndex } from "../vision-handoff";
 import type { CallerIdentity } from "../../security/access-control";
-import type { RouteCandidate as RouteCandidate, InMemoryRouteSnapshotService, RoutePlan } from "../routing/route-model";
+import type { RouteCandidate as RouteCandidate, InMemoryRouteSnapshotService, RoutePlan, RouteSnapshot } from "../routing/route-model";
 import type { RouteContinuationAffinity } from "../routing/route-model";
 import { resolveAliasTarget, type RoutingEngine } from "../routing/router";
 import { projectForRoute, routeCapabilitiesFor, deriveRequiredCapabilities } from "../../protocol/translation/capabilities";
@@ -80,7 +80,17 @@ function replaceImagePartsWithText(
     }
     const hasImage = message.content.some(isImageOrPlaceholderPart);
     if (!hasImage) return message;
-    return { ...message, content: message.content.filter((part) => !isImageOrPlaceholderPart(part)) };
+    // Never delete images silently (proposal Option E): replace a dropped
+    // older image with a marker so the main model at least knows something
+    // was there, instead of the loss being invisible.
+    return {
+      ...message,
+      content: message.content.flatMap((part) =>
+        isImageOrPlaceholderPart(part)
+          ? [{ kind: "text" as const, text: "[image omitted]" }]
+          : [part],
+      ),
+    };
   });
   const unchangedMessages = nextMessages.every(
     (message, i) => message === request.messages[i],
@@ -350,6 +360,61 @@ export class ProxyRequestPreparer {
 
   constructor(private readonly deps: ProxyRequestPreparerDeps) {}
 
+  /**
+   * The key's model-admission gate, shared by the canonical and native
+   * preparation paths: CLI-mapping eligibility → alias resolution → the
+   * model allowlist → the model-prefix gate, in that exact order. Rejects
+   * with the same `model_not_allowed` 403s (same code, status, message, and
+   * detail fields) on both paths, so a policy change here cannot silently
+   * split admission between the chat and native surfaces. Returns the state
+   * the gate computed that the caller still needs for routing: the resolved
+   * alias target and whether CLI mappings were eligible.
+   */
+  #resolveAliasAndGateModel(
+    model: string,
+    authorization: ResolvedApiKey,
+    clientUserAgent: string | undefined,
+    snapshot: RouteSnapshot,
+  ): { readonly resolvedTarget: string; readonly allowCliMappings: boolean } {
+    // Scope opts the key into the mapping table; the User-Agent decides whether
+    // *this* request may consume it. Without the UA gate, a Claude→DeepSeek
+    // remap would also rewrite a non-Claude caller that named `opus`.
+    const allowCliMappings = allowsCliToolMappings(authorization.scopes, {
+      ...(clientUserAgent === undefined ? {} : { userAgent: clientUserAgent }),
+    });
+    // CLI source→target mappings are an explicit API-key capability. Ordinary
+    // tenant aliases remain available to every key; only selected keys may
+    // consume the CLI mapping table.
+    const resolvedTarget = resolveAliasTarget(
+      snapshot,
+      authorization.tenantId,
+      model,
+      allowCliMappings,
+      authorization.cliMappingOwnerId ?? authorization.id,
+    );
+    // Pass `model` as the requested name so an allowlisted alias / a CLI
+    // remapping can authorize the resolved target (see modelRejectionReason).
+    const allowedForKey = isModelAllowed(authorization.snapshot, resolvedTarget, undefined, model);
+    if (
+      authorization.modelPrefix &&
+      !model.startsWith(authorization.modelPrefix) &&
+      !resolvedTarget.startsWith(authorization.modelPrefix) &&
+      !allowedForKey
+    )
+      throw new GatewayError(
+        "model_not_allowed",
+        403,
+        `This key may only use models starting with '${authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
+        { model, required_prefix: authorization.modelPrefix },
+      );
+    if (!allowedForKey) {
+      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
+        model,
+      });
+    }
+    return { resolvedTarget, allowCliMappings };
+  }
+
   /** Injects the vision-handoff runner (called once from boot wiring). */
   bindVisionHandoff(
     runner: (input: VisionHandoffCall) => Promise<readonly VisionHandoffResult[]>,
@@ -391,47 +456,12 @@ export class ProxyRequestPreparer {
         ? initialRequest
         : withThinkingSuffixIntent({ ...initialRequest, model: bareModel }, thinkingIntent);
     const snapshot = await this.deps.snapshotService.getSnapshot();
-    // Scope opts the key into the mapping table; the User-Agent decides whether
-    // *this* request may consume it. Without the UA gate, a Claude→DeepSeek
-    // remap would also rewrite a non-Claude caller that named `opus`.
-    const allowCliMappings = allowsCliToolMappings(authorization.scopes, {
-      ...(input.clientUserAgent === undefined ? {} : { userAgent: input.clientUserAgent }),
-    });
-    // CLI source→target mappings are an explicit API-key capability. Ordinary
-    // tenant aliases remain available to every key; only selected keys may
-    // consume the CLI mapping table.
-    const resolvedTarget = resolveAliasTarget(
-      snapshot,
-      authorization.tenantId,
-      request.model,
-      allowCliMappings,
-      authorization.cliMappingOwnerId ?? authorization.id,
-    );
-    // Pass `request.model` as the requested name so an allowlisted alias / a
-    // CLI remapping can authorize the resolved target (see modelRejectionReason).
-    const allowedForKey = isModelAllowed(
-      authorization.snapshot,
-      resolvedTarget,
-      undefined,
+    const { allowCliMappings } = this.#resolveAliasAndGateModel(
       request.model,
+      authorization,
+      input.clientUserAgent,
+      snapshot,
     );
-    if (
-      authorization.modelPrefix &&
-      !request.model.startsWith(authorization.modelPrefix) &&
-      !resolvedTarget.startsWith(authorization.modelPrefix) &&
-      !allowedForKey
-    )
-      throw new GatewayError(
-        "model_not_allowed",
-        403,
-        `This key may only use models starting with '${authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
-        { model: request.model, required_prefix: authorization.modelPrefix },
-      );
-    if (!allowedForKey) {
-      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
-        model: request.model,
-      });
-    }
     // An inline image that cannot survive the upstream is dropped here rather
     // than dispatched: a provider rejects the whole request for one corrupt
     // attachment, and the buddy family reports it with no field named, so the
@@ -474,6 +504,7 @@ export class ProxyRequestPreparer {
           allowCliMappings,
           authorization.cliMappingOwnerId ?? authorization.id,
           continuationAffinity,
+          request.conversation_id ?? request.conversation?.conversation_id,
         );
       } catch (error) {
         // `plan()` collapses "no candidate supports this capability" into
@@ -541,6 +572,7 @@ export class ProxyRequestPreparer {
                   allowCliMappings,
                   authorization.cliMappingOwnerId ?? authorization.id,
                   continuationAffinity,
+                  request.conversation_id ?? request.conversation?.conversation_id,
                 );
                 plan = handoffPlan;
                 variantRequest = replaced;
@@ -725,42 +757,18 @@ export class ProxyRequestPreparer {
     readonly clientUserAgent?: string;
     readonly eligible: (candidate: RouteCandidate) => boolean;
     readonly emptyMessage: string;
+    /** Session identity for sticky routing (conversation id when present). */
+    readonly conversationId?: string;
   }): Promise<PreparedNativeRequest> {
     if (input.signal?.aborted)
       throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");
     const snapshot = await this.deps.snapshotService.getSnapshot();
-    const allowCliMappings = allowsCliToolMappings(input.authorization.scopes, {
-      ...(input.clientUserAgent === undefined ? {} : { userAgent: input.clientUserAgent }),
-    });
-    const resolvedTarget = resolveAliasTarget(
-      snapshot,
-      input.authorization.tenantId,
-      input.model,
-      allowCliMappings,
-      input.authorization.cliMappingOwnerId ?? input.authorization.id,
-    );
-    const allowedForKey = isModelAllowed(
-      input.authorization.snapshot,
-      resolvedTarget,
-      undefined,
+    const { allowCliMappings } = this.#resolveAliasAndGateModel(
       input.model,
+      input.authorization,
+      input.clientUserAgent,
+      snapshot,
     );
-    if (
-      input.authorization.modelPrefix &&
-      !input.model.startsWith(input.authorization.modelPrefix) &&
-      !resolvedTarget.startsWith(input.authorization.modelPrefix) &&
-      !allowedForKey
-    )
-      throw new GatewayError(
-        "model_not_allowed",
-        403,
-        `This key may only use models starting with '${input.authorization.modelPrefix}' (request {requestId}). Ask for one inside that prefix, or have an operator widen the key. The door's locked for this one — check the allowlist 🔒`,
-        { model: input.model, required_prefix: input.authorization.modelPrefix },
-      );
-    if (!allowedForKey)
-      throw new GatewayError("model_not_allowed", 403, "model is not allowed for this API key (request {requestId}). The door's locked for this one — check the allowlist 🔒", {
-        model: input.model,
-      });
     const plan = await this.deps.routingEngine.plan(
       input.model,
       snapshot,
@@ -768,6 +776,8 @@ export class ProxyRequestPreparer {
       undefined,
       allowCliMappings,
       input.authorization.cliMappingOwnerId ?? input.authorization.id,
+      undefined,
+      input.conversationId,
     );
     if (input.signal?.aborted)
       throw new GatewayError("transport_closed", 499, "The request was cancelled (request {requestId}). Send it again whenever ready 🙃");

package/src/transport/routing/bounded-lru.ts

@@ -1,5 +1,19 @@
 // Bounded LRU map: the one shared implementation for routing-layer caches.
 
+/**
+ * Evicts the oldest-inserted entry while `map.size > cap`. The shared
+ * insertion-order bound for caches whose read path must not refresh recency
+ * (unlike `BoundedLruMap`, whose `get` does). Eviction is one `keys().next()`
+ * and no bookkeeping arrays.
+ */
+export function evictOldestEntry<K>(map: Map<K, unknown>, cap: number): void {
+  while (map.size > cap) {
+    const oldest = map.keys().next().value;
+    if (oldest === undefined) break;
+    map.delete(oldest);
+  }
+}
+
 /**
  * A capacity-bounded LRU `Map`.
  *

package/src/transport/routing/drain-reserve.ts

@@ -0,0 +1,129 @@
+// Drain urgency and reserve scoring for candidate ordering.
+//
+// Ported from oh-my-pi's `windowRequiredDrain` and reserve semantics
+// (`packages/ai/src/auth/usage-report.ts`, `policy.ts`): within the same rank
+// group, an account whose remaining quota is about to expire unused should be
+// burned first ("use it or lose it"), and an account parked in reserve (at or
+// below the reserve percent) should yield to non-reserve siblings.
+import {
+  totalRemainingPercent,
+  type ProviderQuotaWindow,
+} from "../../providers/quota/quota-contracts";
+
+/** Minimum time before reset that still counts as "some headroom" (1 minute). */
+const MIN_REMAINING_MS = 60_000;
+
+/** Usable fraction of a window: 0..1, with 0.5 neutral when unmeasured. */
+function usedFraction(window: ProviderQuotaWindow): number {
+  const used = window.usedPercent;
+  if (typeof used === "number" && Number.isFinite(used)) {
+    return Math.min(1, Math.max(0, used / 100));
+  }
+  const remaining = window.remainingPercent;
+  if (typeof remaining === "number" && Number.isFinite(remaining)) {
+    return Math.min(1, Math.max(0, 1 - remaining / 100));
+  }
+  if (typeof window.used === "number" && Number.isFinite(window.used)) {
+    if (typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0) {
+      return Math.min(1, Math.max(0, window.used / window.limit));
+    }
+  }
+  if (typeof window.remaining === "number" && Number.isFinite(window.remaining)) {
+    if (typeof window.limit === "number" && Number.isFinite(window.limit) && window.limit > 0) {
+      return Math.min(1, Math.max(0, 1 - window.remaining / window.limit));
+    }
+  }
+  return 0.5;
+}
+
+/** Reset instant (epoch ms) for a window, or undefined when it has no clock. */
+function resetAtMs(window: ProviderQuotaWindow): number | undefined {
+  if (window.resetsAt === null || window.resetsAt === undefined) return undefined;
+  const at = Date.parse(window.resetsAt);
+  return Number.isFinite(at) ? at : undefined;
+}
+
+/**
+ * Drain score for the most-urgent relevant window: headroom fraction divided by
+ * remaining hours until reset. Higher means quota that is about to expire
+ * unused and should be burned first. Returns 0 when no window carries usable
+ * evidence (the candidate is neutral, never penalized).
+ */
+export function drainScore(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+  nowMs = Date.now(),
+): number {
+  if (windows === undefined || windows.length === 0) return 0;
+  let best = 0;
+  for (const window of windows) {
+    const headroom = 1 - usedFraction(window);
+    if (headroom <= 0) continue;
+    const resetAt = resetAtMs(window);
+    const durationMs = windowAccountingDurationMs(window);
+    let remainingMs = resetAt === undefined ? (durationMs ?? MIN_REMAINING_MS) : resetAt - nowMs;
+    if (durationMs !== undefined && durationMs > 0) {
+      remainingMs = Math.min(remainingMs, durationMs);
+    }
+    const remainingHours = Math.max(remainingMs, MIN_REMAINING_MS) / (60 * 60 * 1000);
+    best = Math.max(best, headroom / remainingHours);
+  }
+  return best;
+}
+
+function windowAccountingDurationMs(window: ProviderQuotaWindow): number | undefined {
+  // Providers state window durations in the kind label (e.g. "5h", "7d") when
+  // they do not carry an explicit duration field. Parse the common spellings;
+  // an unparseable label contributes no clock.
+  const text = `${window.kind} ${window.label}`.toLowerCase();
+  const m = /(\d+(?:\.\d+)?)\s*(h|hour|hr|d|day|m|min|minute|s|sec|second)\b/.exec(text);
+  if (!m) return undefined;
+  const value = Number(m[1]);
+  if (!Number.isFinite(value)) return undefined;
+  const unit = m[2];
+  if (unit === "h" || unit === "hour" || unit === "hr") return value * 60 * 60 * 1000;
+  if (unit === "d" || unit === "day") return value * 24 * 60 * 60 * 1000;
+  if (unit === "m" || unit === "min" || unit === "minute") return value * 60 * 1000;
+  if (unit === "s" || unit === "sec" || unit === "second") return value * 1000;
+  return undefined;
+}
+
+/**
+ * The account's remaining fraction (0..1) across its pooled credit and
+ * independent windows, or undefined when nothing is measured. Mirrors
+ * `totalRemainingPercent` (the router's existing aggregate) but normalized to a
+ * 0..1 fraction.
+ */
+export function remainingFraction(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+): number | undefined {
+  if (windows === undefined || windows.length === 0) return undefined;
+  const percent = totalRemainingPercent(windows);
+  if (percent === null) return undefined;
+  return Math.min(1, Math.max(0, percent / 100));
+}
+
+/** True when the account's remaining fraction is at or below the reserve percent. */
+export function isInReserve(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+  reservePct: number,
+): boolean {
+  if (reservePct <= 0) return false;
+  const fraction = remainingFraction(windows);
+  if (fraction === undefined) return false;
+  return fraction * 100 <= reservePct;
+}
+
+/**
+ * True when a reserved account has healed above the reclaim threshold and may be
+ * reclaimed to full priority.
+ */
+export function isReclaimReady(
+  windows: readonly ProviderQuotaWindow[] | undefined,
+  reservePct: number,
+  reclaimAbovePct: number,
+): boolean {
+  if (reservePct <= 0 || reclaimAbovePct <= reservePct) return false;
+  const fraction = remainingFraction(windows);
+  if (fraction === undefined) return false;
+  return fraction * 100 >= reclaimAbovePct;
+}

package/src/transport/routing/plan-gate.ts

@@ -17,7 +17,13 @@
  * costs one refused request that the cooldown machinery already handles; a
  * wrong paid match silently blackholes a model.
  */
-const FREE_PLAN_MARKERS: readonly string[] = ["free"];
+/**
+ * The marker set that proves a plan string is free. Exported so every
+ * free-plan consumer — the routing plan gate here and the cooldown-tier
+ * derivation in `account-tier.ts` — reads the same list, so the two cannot
+ * drift apart about an account.
+ */
+export const FREE_PLAN_MARKERS: readonly string[] = ["free"];
 
 export function isFreePlanAccount(plan: string | null | undefined): boolean {
   if (plan === null || plan === undefined) return false;

package/src/transport/routing/round-robin.ts

@@ -36,3 +36,63 @@ const MAX_ROUND_ROBIN_ENTRIES = 1000;
 export function createRoundRobinMap(): BoundedLruMap<string, RoundRobinState> {
   return new BoundedLruMap<string, RoundRobinState>(MAX_ROUND_ROBIN_ENTRIES);
 }
+
+/** One session's sticky account: which provider account last served it, and when. */
+export interface StickySession {
+  readonly accountId: string;
+  readonly lastUsedAtMs: number;
+  /** Set only by an explicit operator pin; automatic warm stickiness leaves it absent. */
+  readonly explicit?: true;
+}
+
+/**
+ * Session → account stickiness per provider, bounded by an LRU. Used by the
+ * router to prefer the account that last served a session within the warm
+ * window — prompt-cache warmth is worth more than perfect load balance. A
+ * session id that is absent, evicted, or past the warm window simply carries
+ * no preference.
+ */
+export class StickySessionStore {
+  private readonly byProvider = new Map<string, BoundedLruMap<string, StickySession>>();
+
+  constructor(private readonly maxSessionsPerProvider: number) {}
+
+  private mapFor(providerId: string): BoundedLruMap<string, StickySession> {
+    let map = this.byProvider.get(providerId);
+    if (map === undefined) {
+      map = new BoundedLruMap<string, StickySession>(this.maxSessionsPerProvider);
+      this.byProvider.set(providerId, map);
+    }
+    return map;
+  }
+
+  /** The account last pinned to this session, or undefined. */
+  get(providerId: string, sessionId: string | undefined): StickySession | undefined {
+    if (sessionId === undefined) return undefined;
+    return this.mapFor(providerId).get(sessionId);
+  }
+
+  /** Record that `accountId` served `sessionId` now (or pin it explicitly). */
+  set(providerId: string, sessionId: string | undefined, accountId: string, explicit = false): void {
+    if (sessionId === undefined) return;
+    const now = Date.now();
+    this.mapFor(providerId).set(sessionId, {
+      accountId,
+      lastUsedAtMs: now,
+      ...(explicit ? { explicit: true as const } : {}),
+    });
+  }
+
+  /** Drop one session's stickiness (e.g. after the account is invalidated). */
+  clear(providerId: string, sessionId: string | undefined): void {
+    if (sessionId === undefined) return;
+    this.mapFor(providerId).delete(sessionId);
+  }
+
+  /** Total retained sticky entries across providers (for metrics/tests). */
+  size(): number {
+    let total = 0;
+    for (const map of this.byProvider.values()) total += map.size;
+    return total;
+  }
+}