@bitkyc08/opencodex 2.35.0 → 2.36.0-preview.20260830

package/src/providers/kiro-usage.ts

@@ -0,0 +1,272 @@
+/**
+ * Kiro usage limits — the account-scoped quota read behind the Kiro pool.
+ *
+ * Kiro's generation traffic goes to `runtime.<region>.kiro.dev`, but the usage numbers
+ * live behind a different subdomain and a different AWS JSON-RPC operation:
+ * `AmazonCodeWhispererService.GetUsageLimits` on `management.<region>.kiro.dev`. The
+ * operation is undocumented, so every field here is best-effort: a shape we do not
+ * recognise resolves to `null` ("unknown"), never to a fabricated zero.
+ *
+ * This module also owns the small amount of state that quota percentages cannot express —
+ * whether an account is actually out of allowance, and when its window rolls over — because
+ * the pool needs those two answers to decide how long to cool a 429'd account.
+ */
+import { getValidAccessSnapshotForAccount } from "../oauth";
+import type { ProviderQuota, ProviderQuotaWindow } from "./quota-types";
+import {
+  ACCOUNT_QUOTA_TTL_MS,
+  asRecord,
+  normalizePercent,
+  normalizeResetAt,
+  QUOTA_JSON_READ_FAILURE,
+  readQuotaJson,
+  REQUEST_TIMEOUT_MS,
+  toFiniteNumber,
+} from "./quota-wire";
+
+const AMZ_USAGE_TARGET = "AmazonCodeWhispererService.GetUsageLimits";
+
+/**
+ * Regions are interpolated into a hostname, and two of the three candidates below are read
+ * out of credential files this process did not write. An allowlist keeps a crafted region
+ * from redirecting the request somewhere else entirely.
+ */
+const REGION_PATTERN = /^[a-z0-9-]{1,32}$/;
+
+/**
+ * Which usage bucket represents the plan allowance, in preference order.
+ *
+ * Selecting by position instead would mean an upstream reordering silently reweights the
+ * pool against an unrelated resource, so an unrecognised list resolves to unknown.
+ */
+const RESOURCE_PRIORITY = ["AGENTIC_REQUEST", "CREDIT"] as const;
+
+export interface KiroUsageContext {
+  /** Keys the usage-state row; always the stored account id, never the active account. */
+  accountId: string;
+  access: string;
+  profileArn?: string;
+  apiRegion?: string;
+  ssoRegion?: string;
+}
+
+export interface KiroUsageSnapshot {
+  quota: ProviderQuota;
+  /** Allowance is spent AND overage is not enabled — not merely "percent hit 100". */
+  exhausted: boolean;
+  /** Epoch ms when the plan window rolls over, when upstream reports it. */
+  nextResetAt?: number;
+}
+
+interface KiroUsageStateEntry {
+  exhausted: boolean;
+  nextResetAt?: number;
+  ts: number;
+}
+
+/**
+ * Exhaustion state, keyed exactly like the per-account quota cache in `quota.ts`.
+ *
+ * It is written only inside that cache's commit guard and cleared through the same
+ * logout/reconcile paths, so a removed account cannot leave a verdict behind for whatever
+ * account replaces it.
+ */
+const usageState = new Map<string, KiroUsageStateEntry>();
+
+function safeRegion(value: string | undefined): string | undefined {
+  return value && REGION_PATTERN.test(value) ? value : undefined;
+}
+
+/**
+ * The profile ARN wins because an enterprise profile can live in a different region from
+ * the SSO session that minted the token.
+ */
+function usageRegion(ctx: KiroUsageContext): string {
+  return safeRegion(ctx.profileArn?.split(":")[3])
+    ?? safeRegion(ctx.apiRegion)
+    ?? safeRegion(ctx.ssoRegion)
+    ?? "us-east-1";
+}
+
+export function kiroUsageManagementUrl(region: string): string {
+  return `https://management.${region}.kiro.dev/`;
+}
+
+/** Credit balances are fractional; the integer fields round 695.17 down to 695. */
+function preciseNumber(row: Record<string, unknown>, precise: string, whole: string): number | undefined {
+  return toFiniteNumber(row[precise]) ?? toFiniteNumber(row[whole]);
+}
+
+function selectBreakdown(list: unknown): Record<string, unknown> | null {
+  if (!Array.isArray(list)) return null;
+  const rows = list.map(asRecord).filter((row): row is Record<string, unknown> => row !== null);
+  for (const wanted of RESOURCE_PRIORITY) {
+    const match = rows.find(row => String(row.resourceType ?? "").trim().toUpperCase() === wanted);
+    if (match) return match;
+  }
+  return null;
+}
+
+function parseKiroUsage(body: unknown): KiroUsageSnapshot | null {
+  const payload = asRecord(body);
+  if (!payload) return null;
+  const breakdown = selectBreakdown(payload.usageBreakdownList);
+  if (!breakdown) return null;
+
+  const used = preciseNumber(breakdown, "currentUsageWithPrecision", "currentUsage");
+  const limit = preciseNumber(breakdown, "usageLimitWithPrecision", "usageLimit");
+  if (used === undefined || limit === undefined || limit <= 0) return null;
+
+  const percent = normalizePercent((used / limit) * 100);
+  if (percent === undefined) return null;
+
+  const nextResetAt = normalizeResetAt(payload.nextDateReset);
+  const customWindows: ProviderQuotaWindow[] = [];
+
+  // A trial allowance is a separate pool: folding it into the plan window would understate
+  // what the account can actually spend.
+  const trial = asRecord(breakdown.freeTrialInfo);
+  if (trial) {
+    const trialUsed = preciseNumber(trial, "currentUsageWithPrecision", "currentUsage");
+    const trialLimit = preciseNumber(trial, "usageLimitWithPrecision", "usageLimit");
+    if (trialUsed !== undefined && trialLimit !== undefined && trialLimit > 0) {
+      const trialPercent = normalizePercent((trialUsed / trialLimit) * 100);
+      if (trialPercent !== undefined) customWindows.push({ label: "Free trial", percent: trialPercent });
+    }
+  }
+
+  const quota: ProviderQuota = {
+    monthlyPercent: percent,
+    ...(nextResetAt !== undefined ? { monthlyResetAt: nextResetAt } : {}),
+    ...(customWindows.length > 0 ? { customWindows } : {}),
+    updatedAt: Date.now(),
+  };
+
+  // Enterprise accounts with overage enabled keep serving past the included limit, so
+  // "used >= limit" is not by itself a reason to stop routing to the account.
+  const overageEnabled = String(asRecord(payload.overageConfiguration)?.overageStatus ?? "")
+    .trim()
+    .toUpperCase() === "ENABLED";
+
+  return {
+    quota,
+    exhausted: used >= limit && !overageEnabled,
+    ...(nextResetAt !== undefined ? { nextResetAt } : {}),
+  };
+}
+
+/**
+ * Read one account's usage. Resolves `null` for any transport, status, or schema failure —
+ * the caller renders that as "unavailable" and keeps whatever it knew before.
+ *
+ * `userInfo` in the response carries an email and a user id. Both are read past and
+ * discarded here: nothing identifying an operator's person reaches the cache, the API, or
+ * a log line.
+ */
+export async function fetchKiroUsageSnapshot(ctx: KiroUsageContext): Promise<KiroUsageSnapshot | null> {
+  const region = usageRegion(ctx);
+  const url = new URL(kiroUsageManagementUrl(region));
+  url.searchParams.set("origin", "AI_EDITOR");
+  url.searchParams.set("isEmailRequired", "true");
+  if (ctx.profileArn) url.searchParams.set("profileArn", ctx.profileArn);
+
+  // The modeled arguments appear in BOTH the query string and the body. That duplication is
+  // the observed Kiro CLI contract, not an oversight; we have no way to test which side the
+  // service actually reads, so we reproduce both.
+  const body: Record<string, unknown> = { origin: "AI_EDITOR", isEmailRequired: true };
+  if (ctx.profileArn) body.profileArn = ctx.profileArn;
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${ctx.access}`,
+        "content-type": "application/x-amz-json-1.0",
+        accept: "application/json",
+        "x-amz-target": AMZ_USAGE_TARGET,
+        "x-amzn-codewhisperer-optout": "true",
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    if (!response.ok) return null;
+    const json = await readQuotaJson(response);
+    if (json === QUOTA_JSON_READ_FAILURE) return null;
+    return parseKiroUsage(json);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Assemble the probe context from ONE account-scoped snapshot.
+ *
+ * Reading the bearer and the routing metadata from a single snapshot is what keeps account
+ * A's token from being sent with account B's profile ARN — the same pairing class of defect
+ * #2841 fixed for Copilot origins.
+ */
+export async function kiroUsageContextForAccount(accountId: string): Promise<KiroUsageContext> {
+  const snapshot = await getValidAccessSnapshotForAccount("kiro", accountId);
+  return {
+    accountId,
+    access: snapshot.accessToken,
+    ...(snapshot.kiro?.profileArn ? { profileArn: snapshot.kiro.profileArn } : {}),
+    ...(snapshot.kiro?.apiRegion ? { apiRegion: snapshot.kiro.apiRegion } : {}),
+    ...(snapshot.kiro?.ssoRegion ? { ssoRegion: snapshot.kiro.ssoRegion } : {}),
+  };
+}
+
+/** Record exhaustion for a probed account. Called from the quota cache's commit guard. */
+export function commitKiroAccountUsageState(key: string, snapshot: KiroUsageSnapshot | null): void {
+  if (!snapshot) {
+    usageState.delete(key);
+    return;
+  }
+  usageState.set(key, {
+    exhausted: snapshot.exhausted,
+    ...(snapshot.nextResetAt !== undefined ? { nextResetAt: snapshot.nextResetAt } : {}),
+    ts: Date.now(),
+  });
+}
+
+/**
+ * Is this account known to be out of allowance right now?
+ *
+ * Returns `null` (unknown) rather than a stale `true`: an expired reading, or one whose
+ * reset time has already passed, must degrade to "try it again", never to "keep it parked".
+ */
+export function getKiroAccountExhaustion(
+  key: string,
+  now = Date.now(),
+): { exhausted: boolean; nextResetAt?: number } | null {
+  const entry = usageState.get(key);
+  if (!entry) return null;
+  if (now - entry.ts >= ACCOUNT_QUOTA_TTL_MS) return null;
+  if (entry.nextResetAt !== undefined && entry.nextResetAt <= now) return null;
+  return {
+    exhausted: entry.exhausted,
+    ...(entry.nextResetAt !== undefined ? { nextResetAt: entry.nextResetAt } : {}),
+  };
+}
+
+/** Drop rows for one provider prefix, or all of them. Mirrors clearAccountQuotaCache. */
+export function clearKiroAccountUsageState(prefix?: string): void {
+  if (!prefix) {
+    usageState.clear();
+    return;
+  }
+  for (const key of [...usageState.keys()]) {
+    if (key.startsWith(prefix)) usageState.delete(key);
+  }
+}
+
+/** Drop rows whose account no longer exists. Mirrors reconcileProviderAccountQuotaRows. */
+export function reconcileKiroAccountUsageState(liveKeys: ReadonlySet<string>): number {
+  let removed = 0;
+  for (const key of [...usageState.keys()]) {
+    if (liveKeys.has(key)) continue;
+    usageState.delete(key);
+    removed += 1;
+  }
+  return removed;
+}

package/src/providers/ollama-show.ts

@@ -0,0 +1,311 @@
+/**
+ * Bounded Ollama Cloud `/api/show` metadata enrichment.
+ *
+ * `/v1/models` is the authoritative live ID roster, but it carries no per-model context or
+ * capability metadata, so a newly announced Ollama model (e.g. glm-5.3 during its rollout)
+ * would otherwise be advertised to Codex with generic defaults — a 1M-context model published
+ * at 128K, and native vision unknown. `/api/show` fills that gap for canonical Ollama Cloud
+ * destinations only.
+ *
+ * The show request reuses the discovery request's already-materialized captured headers
+ * (credential + configured-header precedence resolved by `buildModelsRequest`, not re-derived
+ * here) and executes through the same outbound-policy transport as discovery
+ * (`providerOutboundPost`: destination policy, DNS pinning, manual redirects, caller-owned
+ * executor).
+ *
+ * Failure is per model and fail-soft: any transport, status, redirect, size, parse, or timeout
+ * failure drops the enrichment for that one model and never touches other rows or the ID roster
+ * itself. Only evidence-backed fields are extracted; templates, licenses, and tokenizer
+ * payloads exist only inside the bounded body and are never projected into CatalogModel
+ * metadata.
+ */
+import { readBoundedResponseBytes } from "../lib/bounded-body";
+import { isCanonicalOllamaCloudUrl } from "../adapters/ollama-native-url";
+import { providerOutboundPost, providerRedirectError } from "../lib/provider-outbound";
+
+/** Hard per-response bound: cloud /api/show metadata is small; anything larger is discarded. */
+const SHOW_MAX_RESPONSE_BYTES = 256 * 1024;
+/**
+ * Aggregate deadline for the ENTIRE show-enrichment phase, independent of roster size and of
+ * the generic discovery row limit. A stalled endpoint must never turn a successful /v1/models
+ * discovery into a multi-minute catalog stall.
+ */
+const SHOW_AGGREGATE_DEADLINE_MS = 12_000;
+/** Per-request timeout: a single show request never outlives this, deadline or not. */
+const SHOW_REQUEST_TIMEOUT_MS = 8_000;
+/**
+ * Show-specific request cap, independent of the generic 2000-row discovery hard limit.
+ * Conservative for the current Ollama Cloud roster (~19 ids) while leaving room for growth;
+ * ids beyond the cap simply stay on the existing safe fallback metadata.
+ */
+const SHOW_REQUEST_CAP = 48;
+/** Concurrent /api/show requests never exceed this, regardless of roster size. */
+const SHOW_MAX_CONCURRENCY = 4;
+/** A discovered context window must be a plausible positive integer, not arbitrary data. */
+const SHOW_MAX_CONTEXT_LENGTH = 16 * 1024 * 1024;
+
+export interface OllamaShowMetadata {
+  /** Trained context length reported by the model's own architecture metadata. */
+  contextWindow?: number;
+  /** Native vision capability reported by Ollama (`capabilities` includes "vision"). */
+  nativeVision?: boolean;
+}
+
+export interface OllamaShowEnrichmentResult {
+  metadata: Map<string, OllamaShowMetadata>;
+  /** /api/show requests issued (bounded by the request cap and the roster). */
+  showRequests: number;
+  /** True when the aggregate deadline stopped the enrichment early. */
+  deadlineHit: boolean;
+}
+
+export interface OllamaShowEnrichmentOptions {
+  /** The already-materialized captured discovery headers (credential + configured precedence). */
+  headers: Record<string, string>;
+  /** The discovery request URL actually captured for this provider (same origin is used). */
+  discoveryUrl: string;
+  modelIds: readonly string[];
+  /** Show-specific request cap, independent of the generic discovery row limit. */
+  showRequestCap?: number;
+  /** Aggregate wall-clock deadline for the whole enrichment phase (injectable for tests). */
+  deadlineMs?: number;
+  /** Per-request timeout (injectable for deterministic tests). */
+  requestTimeoutMs?: number;
+  /** Outbound config for the policy-checked transport (must carry the test executor). */
+  provider: {
+    baseUrl: string;
+    adapter?: string;
+    fetch?: typeof fetch;
+  };
+}
+
+/**
+ * Scope gate: enrichment runs ONLY for the canonical Ollama Cloud destination. Custom
+ * ollama-native providers (self-hosted or renamed rows) and every unrelated provider are
+ * untouched, so `/api/show` behavior can never widen into a generic provider surface.
+ */
+export function ollamaShowEnrichable(
+  providerName: string,
+  provider: { adapter?: string; baseUrl?: string },
+): boolean {
+  if (providerName !== "ollama-cloud") return false;
+  if (provider.adapter !== "ollama-native") return false;
+  const baseUrl = provider.baseUrl;
+  if (typeof baseUrl !== "string" || !baseUrl) return false;
+  return isCanonicalOllamaCloudUrl(baseUrl);
+}
+
+/**
+ * Extract only evidence-backed catalog metadata from an `/api/show` payload. The input is not
+ * mutated; templates, licenses, and tokenizer payloads exist only inside the bounded parse and
+ * are never projected into CatalogModel metadata.
+ */
+export function ollamaShowMetadataFromPayload(payload: unknown): OllamaShowMetadata | undefined {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const raw = payload as Record<string, unknown>;
+  const modelInfo = raw.model_info;
+  let contextWindow: number | undefined;
+  const info = modelInfo !== null && typeof modelInfo === "object" && !Array.isArray(modelInfo)
+    ? modelInfo as Record<string, unknown>
+    : undefined;
+  if (info !== undefined) {
+    // Prefer the context length named by the model's own architecture, then fall back to a
+    // unique `*.context_length` key only when the architecture spelling is absent or ambiguous.
+    // The architecture key is FILTERED while collecting fallback candidates — the parsed input is
+    // never mutated.
+    const architecture = typeof info["general.architecture"] === "string"
+      ? (info["general.architecture"] as string)
+      : undefined;
+    const architectureKey = architecture !== undefined ? `${architecture}.context_length` : undefined;
+    if (architectureKey !== undefined) {
+      const value = info[architectureKey];
+      if (isPlausibleContextLength(value)) contextWindow = value;
+    }
+    if (contextWindow === undefined) {
+      const candidates = Object.entries(info)
+        .filter(([key, value]) =>
+          key.endsWith(".context_length")
+          && key !== architectureKey
+          && isPlausibleContextLength(value))
+        .map(([, value]) => value as number);
+      if (candidates.length === 1) contextWindow = candidates[0];
+    }
+  }
+
+  const capabilities = Array.isArray(raw.capabilities)
+    ? raw.capabilities.filter((c): c is string => typeof c === "string")
+    : undefined;
+  const nativeVision = capabilities?.includes("vision") === true;
+
+  if (contextWindow === undefined && capabilities === undefined) return undefined;
+  return {
+    ...(contextWindow !== undefined ? { contextWindow } : {}),
+    ...(capabilities !== undefined ? { nativeVision } : {}),
+  };
+}
+
+function isPlausibleContextLength(value: unknown): value is number {
+  return typeof value === "number"
+    && Number.isSafeInteger(value)
+    && value > 0
+    && value <= SHOW_MAX_CONTEXT_LENGTH;
+}
+
+/**
+ * Reapply the configured provider headers LAST over an already-materialized header map,
+ * case-insensitively: a configured Authorization/authorization replaces the generated Bearer
+ * (exactly one effective credential spelling survives), matching the native /api/chat adapter's
+ * precedence (generated Bearer first, provider.headers last). Non-credential configured headers
+ * are likewise reapplied so an explicit operator spelling wins.
+ */
+export function applyConfiguredHeadersLast(
+  headers: Record<string, string>,
+  providerHeaders: Record<string, string> | undefined,
+): Record<string, string> {
+  const out: Record<string, string> = { ...headers };
+  for (const [key, value] of Object.entries(providerHeaders ?? {})) {
+    const lower = key.toLowerCase();
+    for (const existing of Object.keys(out)) {
+      if (existing.toLowerCase() === lower && existing !== key) delete out[existing];
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Show headers for the JSON POST: force Content-Type case-insensitively (the endpoint has a
+ * JSON body), leave every other captured header — including configured Authorization/auth
+ * spellings — exactly as the materialized discovery request produced them.
+ */
+export function showHeadersFromCaptured(
+  capturedHeaders: Record<string, string>,
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(capturedHeaders)) {
+    if (key.toLowerCase() === "content-type") continue;
+    out[key] = value;
+  }
+  out["Content-Type"] = "application/json";
+  return out;
+}
+
+/**
+ * Enrich discovered Ollama Cloud ids through `POST /api/show`, executed through the same
+ * outbound-policy transport as discovery (`providerOutboundPost`) with the already-materialized
+ * captured headers — the show request never manufactures its own auth contract.
+ *
+ * Fail-soft per model: transport errors, non-2xx responses, redirects (never followed, so the
+ * credential can never reach another origin), oversized payloads, malformed data, and deadline
+ * aborts each skip that model's enrichment without affecting other rows or the success of
+ * discovery itself. The aggregate deadline stops new launches and aborts active work; partial
+ * results are returned and unenriched ids stay on the existing safe fallback metadata.
+ */
+export async function fetchOllamaShowEnrichment(
+  options: OllamaShowEnrichmentOptions,
+): Promise<OllamaShowEnrichmentResult> {
+  const {
+    headers: capturedHeaders,
+    discoveryUrl,
+    modelIds,
+    showRequestCap = SHOW_REQUEST_CAP,
+    deadlineMs = SHOW_AGGREGATE_DEADLINE_MS,
+    requestTimeoutMs = SHOW_REQUEST_TIMEOUT_MS,
+    provider,
+  } = options;
+  // Late-worker isolation: workers that complete or throw after the phase returns mutate ONLY
+  // the internal map; the returned metadata is the EXACT snapshot the phase promise resolved
+  // with — never a re-snapshot of the mutable map after resolution.
+  const metadata = new Map<string, OllamaShowMetadata>();
+
+  // Same origin as the materialized discovery request, so /api/show can never point at another
+  // destination than the one the credential was already materialized for.
+  const showUrl = new URL("/api/show", new URL(discoveryUrl).origin).toString();
+  const showHeaders = showHeadersFromCaptured(capturedHeaders);
+
+  const deadlineAbort = new AbortController();
+  const requestSignal = () => AbortSignal.any([
+    AbortSignal.timeout(requestTimeoutMs),
+    deadlineAbort.signal,
+  ]);
+
+  const ids = modelIds.slice(0, Math.min(modelIds.length, showRequestCap));
+  let cursor = 0;
+  let active = 0;
+  let showRequests = 0;
+  let deadlineHit = false;
+  let settled = false;
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  let resolvePhase: ((snapshot: Map<string, OllamaShowMetadata>) => void) | undefined;
+
+  // The phase-finishing path: stops launches (settled guard), takes the metadata snapshot at
+  // this exact moment, and resolves the phase promise with it. The caller returns THAT resolved
+  // snapshot, so late worker settlement can never change the returned metadata.
+  const finish = (deadline: boolean): void => {
+    if (settled) return;
+    settled = true;
+    deadlineHit = deadline;
+    if (deadlineTimer !== undefined) clearTimeout(deadlineTimer);
+    const snapshot = new Map(metadata);
+    resolvePhase?.(snapshot);
+  };
+
+  const result = await new Promise<OllamaShowEnrichmentResult>((resolve) => {
+    resolvePhase = (snapshot) => resolve({
+      metadata: snapshot,
+      showRequests,
+      deadlineHit,
+    });
+
+    // The aggregate deadline TIMER ITSELF is the return bound: it prevents further launches
+    // (settled guard in pump), aborts active workers, and resolves the phase IMMEDIATELY. It
+    // never relies on a worker settling, its finally block, the per-request timeout, or another
+    // pump() call. Declared after finish so the callback has no TDZ reference.
+    deadlineTimer = setTimeout(() => {
+      if (settled) return;
+      deadlineAbort.abort(new DOMException("ollama /api/show aggregate deadline", "TimeoutError"));
+      finish(true);
+    }, deadlineMs);
+
+    const pump = () => {
+      if (settled) return;
+      while (active < SHOW_MAX_CONCURRENCY && cursor < ids.length) {
+        const id = ids[cursor++];
+        active += 1;
+        showRequests += 1;
+        void (async () => {
+          try {
+            const res = await providerOutboundPost("ollama-cloud", provider, showUrl, {
+              headers: showHeaders,
+              body: JSON.stringify({ model: id }),
+              signal: requestSignal(),
+            });
+            const redirectError = await providerRedirectError(res, showUrl);
+            // Redirect handling: never follow — the credential must never reach another origin.
+            // A redirected or non-2xx show response is a per-model failure, not a retry.
+            if (redirectError || !res.ok || ![200, 201].includes(res.status)) return;
+            const bounded = await readBoundedResponseBytes(res, { maxBytes: SHOW_MAX_RESPONSE_BYTES });
+            if (bounded.oversized) return;
+            let payload: unknown;
+            try {
+              payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bounded.bytes));
+            } catch {
+              return;
+            }
+            const parsed = ollamaShowMetadataFromPayload(payload);
+            if (parsed) metadata.set(id, parsed);
+          } catch {
+            // Fail-soft: this model simply stays unenriched. Late settlement after the phase has
+            // returned only touches the internal map — the caller holds the exact snapshot.
+          } finally {
+            active -= 1;
+            pump();
+          }
+        })();
+      }
+      if (cursor >= ids.length && active === 0) finish(false);
+    };
+    pump();
+  });
+  return result;
+}

package/src/providers/openai-sidecar.ts

@@ -140,6 +140,9 @@ export async function resolveFirstUsableOpenAiSidecar(
             probeLeaseId: authContext.probeLeaseId,
             probeQuotaScope: authContext.probeQuotaScope,
             writerGeneration: authContext.writerGeneration,
+            // 401/403 here is evidence about this exact stored credential; without the generation a
+            // replacement inherits the quarantine (#2892 gap 4).
+            ...(authContext.kind === "pool" ? { credentialGeneration: authContext.generation } : {}),
           },
         ),
       };
@@ -172,6 +175,8 @@ export async function resolveFirstUsableOpenAiSidecar(
               threadId: authContext.affinityKey,
               probeLeaseId: authContext.probeLeaseId,
               writerGeneration: authContext.writerGeneration,
+              // Same fence as the exact-account recorder above (#2892 gap 4).
+              ...(authContext.kind === "pool" ? { credentialGeneration: authContext.generation } : {}),
             },
           ),
         }

package/src/providers/quota-routing-cache.ts

@@ -0,0 +1,32 @@
+import type { ProviderQuota, ProviderQuotaReport } from "./quota";
+
+const quotaCache = new Map<string, ProviderQuota>();
+
+export function clearCachedProviderQuotas(): void {
+  quotaCache.clear();
+}
+
+export function replaceCachedProviderQuotas(reports: ProviderQuotaReport[]): void {
+  quotaCache.clear();
+  for (const report of reports) {
+    quotaCache.set(report.provider, report.quota);
+  }
+}
+
+export function getCachedProviderQuota(
+  provider: string,
+  now: number,
+  maxAgeMs = 30 * 60_000,
+): ProviderQuota | null {
+  const quota = quotaCache.get(provider);
+  if (!quota) return null;
+  if (now - quota.updatedAt > maxAgeMs) return null;
+  return quota;
+}
+
+export function setCachedProviderQuotaForTests(
+  provider: string,
+  quota: ProviderQuota,
+): void {
+  quotaCache.set(provider, quota);
+}

package/src/providers/quota-types.ts

@@ -0,0 +1,36 @@
+/**
+ * Provider quota shapes, split out of `quota.ts` so a provider-specific quota module can
+ * describe its result without importing the aggregator that will consume it.
+ *
+ * `quota.ts` imports the Kiro usage module for its fetcher; if that module reached back
+ * into `quota.ts` for these types the two would depend on each other. Types have no
+ * runtime edge, but a cycle that exists only in the type graph is still a cycle, and it
+ * blocks any later attempt to load one side without the other.
+ */
+
+export interface ProviderQuotaWindow {
+  label: string;
+  percent: number;
+  resetAt?: number;
+}
+
+export interface ProviderQuotaCreditsUsd {
+  used: number;
+  limit: number;
+  remaining: number;
+  percent: number;
+  expiresAt?: number;
+  unlimited?: boolean;
+}
+
+export interface ProviderQuota {
+  fiveHourPercent?: number;
+  fiveHourResetAt?: number;
+  weeklyPercent?: number;
+  weeklyResetAt?: number;
+  monthlyPercent?: number;
+  monthlyResetAt?: number;
+  customWindows?: ProviderQuotaWindow[];
+  creditsUsd?: ProviderQuotaCreditsUsd;
+  updatedAt: number;
+}