@bitkyc08/opencodex 2.84.0 → 2.87.0

package/src/protocols/plan-snapshot.ts

@@ -23,6 +23,7 @@ import { getRoutingProfile, POLICY_NAMESPACE, resolvePolicyProfileId } from "../
 import { resolveWireProtocolOverride } from "../server/adapter-resolve";
 import { nativeChatDeclineReason } from "../server/chat-native-eligibility";
 import { nativeMessagesDeclineReason } from "../server/messages-native-eligibility";
+import { antigravityDirectDeclineReason, antigravityMessagesDeclineReason } from "../server/antigravity-direct-eligibility";
 import { messagesSelectorTargetsSecondaryInstance, messagesSecondaryInstanceUnavailable } from "../server/messages-native-selector";
 import { parseSyntheticRowId } from "../server/fast-row";
 import type { OcxConfig } from "../types";
@@ -125,6 +126,7 @@ function candidateFor(
   const adapter = provider.adapter ?? "openai-responses";
   let declineReasons: ProtocolReasonCode[] = [];
   let nativeEligible = false;
+  let directEligible = false;
   // With `nativeChatCombos` on, the combo loop judges each Chat candidate as the concrete route it
   // is (PF-07), so the preview must too; a policy still resolves one candidate on the bridge.
   const comboChildNative = inbound === "chat" && routeKind === "combo"
@@ -136,25 +138,46 @@ function candidateFor(
     ...(routeKind === "direct" || comboChildNative ? {} : { routeKind }),
   };
   if (inbound === "chat") {
-    const reason = rows.effortRow ? "effort-row" : nativeChatDeclineReason(settled, chatBodyForFeatures(features), config);
-    nativeEligible = reason === undefined;
-    if (reason) declineReasons = [reason];
-  } else if (inbound === "messages" && resolveProtocolSettings(config, settled.providerName).rollout.managedMessagesNative) {
-    // The runtime rule itself. With the switch off nothing is judged, so the default preview
-    // is exactly what it was before the managed native lane existed.
-    // Pinned effort is judged from config and the route; blocked-skill elision and the web-search
-    // sidecar depend on body content no feature describes, so a preview cannot predict them.
-    // Anthropic OAuth (PF-10) is judged from config alone: the rollout switch, the provider, its
-    // host and `anthropicAccountPool.enabled`. The stored-account quorum a sender supplies is
-    // never read here, so a preview selects, resolves and refreshes no account.
-    const reason = nativeMessagesDeclineReason(settled, messagesBodyForFeatures(features), config, {
-      ...rows,
-      claudeCode: config.claudeCode,
-    });
+    const body = chatBodyForFeatures(features);
+    const reason = rows.effortRow ? "effort-row" : nativeChatDeclineReason(settled, body, config);
     nativeEligible = reason === undefined;
     if (reason) declineReasons = [reason];
+    // The Antigravity direct lane, judged by the ingress's own rule, for a standalone route only:
+    // a combo child is dispatched from the full Responses body even when `nativeChatCombos`
+    // judges it as a concrete route above. A hosted web-search tool and the other body-content
+    // declines are not described by any Chat feature, so a preview cannot predict them.
+    directEligible = !nativeEligible && routeKind === "direct"
+      && antigravityDirectDeclineReason(settled, { ...body, model: rows.routeSelector }, config) === undefined;
+  } else if (inbound === "messages") {
+    const body = messagesBodyForFeatures(features);
+    if (resolveProtocolSettings(config, settled.providerName).rollout.managedMessagesNative) {
+      // The runtime rule itself. With the switch off nothing is judged, so the default preview
+      // is exactly what it was before the managed native lane existed.
+      // Pinned effort is judged from config and the route; blocked-skill elision and the web-search
+      // sidecar depend on body content no feature describes, so a preview cannot predict them.
+      // Anthropic OAuth (PF-10) is judged from config alone: the rollout switch, the provider, its
+      // host and `anthropicAccountPool.enabled`. The stored-account quorum a sender supplies is
+      // never read here, so a preview selects, resolves and refreshes no account.
+      const reason = nativeMessagesDeclineReason(settled, body, config, {
+        ...rows,
+        claudeCode: config.claudeCode,
+      });
+      nativeEligible = reason === undefined;
+      if (reason) declineReasons = [reason];
+    }
+    // The Antigravity direct lane for a standalone route, as for Chat. The ingress plans it on the
+    // resolved selector, which is `rows.routeSelector`.
+    directEligible = !nativeEligible && routeKind === "direct"
+      && antigravityMessagesDeclineReason(settled, body, rows.routeSelector, config) === undefined;
   }
-  return { provider: route.providerName, model: route.modelId, adapter, nativeEligible, declineReasons };
+  return {
+    provider: route.providerName,
+    model: route.modelId,
+    adapter,
+    nativeEligible,
+    ...(directEligible ? { directEligible } : {}),
+    declineReasons,
+  };
 }
 
 /** Whether the Messages ingress could forward this selector with a caller's own credential. */

package/src/protocols/plan.ts

@@ -28,6 +28,12 @@ export interface ProtocolPlanCandidateInput {
   adapter: string;
   /** True when the ingress would send its own wire to this candidate. */
   nativeEligible: boolean;
+  /**
+   * True when the ingress would decode its own wire straight into the IR for this candidate (the
+   * Antigravity direct lane). Only meaningful toward an `other` upstream; `path.ts` ignores it
+   * anywhere else.
+   */
+  directEligible?: boolean;
   /** Why the ingress declined its native lane, when it did. */
   declineReasons: readonly ProtocolReasonCode[];
 }
@@ -80,7 +86,9 @@ function planCandidate(
   const upstream = upstreamWireForAdapter(candidate.adapter);
   // A native lane only exists toward the ingress's own wire; an inconsistent snapshot must
   // not produce a path that claims the source body reached a different wire untouched.
-  const lane: ProtocolLane = candidate.nativeEligible && upstream === input.inbound ? "native" : "bridge";
+  const lane: ProtocolLane = candidate.nativeEligible && upstream === input.inbound
+    ? "native"
+    : candidate.directEligible === true ? "direct" : "bridge";
   const requestPath = requestPathForLane(input.inbound, lane, upstream);
   const responsePath = responsePathForLane(input.inbound, lane, upstream);
   const mode = deliveryModeForLane(input.inbound, lane, upstream);

package/src/protocols/provider-summary.ts

@@ -55,12 +55,13 @@ function usableModelId(model: unknown): model is string {
 function candidateModelIds(name: string, provider: Readonly<OcxProviderConfig>): string[] {
   const registry = PROVIDER_REGISTRY.find(entry => entry.id === name);
   const ids = new Set<string>();
+  /** Collect valid candidate IDs without exceeding the protocol-summary scan limit. */
   const add = (model: unknown) => {
     if (ids.size < MODEL_SCAN_LIMIT && usableModelId(model)) ids.add(model);
   };
   for (const model of Object.keys(provider.modelAdapters ?? {})) add(model);
   for (const model of Object.keys(registry?.modelWireDefaults ?? {})) add(model);
-  for (const model of Object.keys(captureWireAdapterHardPins(name))) add(model);
+  for (const model of Object.keys(captureWireAdapterHardPins(name, provider))) add(model);
   add(provider.defaultModel);
   for (const model of provider.models ?? []) add(model);
   return [...ids].sort((left, right) => left.localeCompare(right));

package/src/protocols/settings.ts

@@ -64,6 +64,7 @@ export interface ProtocolRolloutSettings {
   managedMessagesNative: boolean;
   managedMessagesNativeOAuth: boolean;
   directEncoders: boolean;
+  antigravityDirect: boolean;
   shadowPlan: boolean;
 }
 
@@ -101,6 +102,12 @@ export function resolveProtocolSettings(config: ProtocolConfig, providerName?: s
       // OAuth extension is meaningless without the key-auth path it extends.
       managedMessagesNativeOAuth: managedMessagesNative && nativeOn("managedMessagesNativeOAuth"),
       directEncoders: on("directEncoders"),
+      // Default on: an absent switch takes the Antigravity direct lane, which falls back to the
+      // bridge per request whenever its eligibility rule declines. Only an explicit `false` turns
+      // it off; a non-boolean value or a malformed container fails closed like every other switch.
+      antigravityDirect: validContainers && (Object.hasOwn(rollout, "antigravityDirect")
+        ? rollout.antigravityDirect === true
+        : true),
       shadowPlan: on("shadowPlan"),
     }),
   });
@@ -145,6 +152,7 @@ export function protocolPolicyRevision(config: ProtocolConfig & Pick<OcxConfig,
       secondarySettings.rollout.managedMessagesNative,
       secondarySettings.rollout.managedMessagesNativeOAuth,
       settings.rollout.directEncoders,
+      settings.rollout.antigravityDirect,
       settings.rollout.shadowPlan,
     ],
   });

package/src/providers/antigravity-account-roster.ts

@@ -0,0 +1,102 @@
+import { getConfigDir } from "../config/paths";
+import { ANTIGRAVITY_MODEL_ALIASES, canonicalAntigravityUsageModel, type AntigravityAvailableModel } from "./antigravity-models";
+
+/**
+ * Per-account Antigravity model rosters, taken from each account's own live
+ * `:fetchAvailableModels` discovery.
+ *
+ * Google gates models per account, not per client. Measured 2026-10-14: one account lists
+ * `claude-sonnet-4-6` / `claude-opus-4-6-thinking` and answers 404 "Requested entity was not
+ * found" for every `claude-{opus,sonnet}-5-5-*` id, while other accounts list only the 5.5
+ * families. Gemini 4 Argon is likewise Ultra / Enterprise only. Google documents Claude 5.5 as
+ * needing a directly billed, non-trial Pro or Ultra plan and rolls it out gradually, so the static
+ * lineup is a superset and only discovery says what one account can actually call.
+ *
+ * The catalog already exposes only the ACTIVE account's discovered rows (an authoritative live
+ * roster drops static rows it did not return). This store keeps every account's last roster so
+ * that account selection can prefer an account that lists the requested model, instead of
+ * landing a 5.5 request on a 4.6-only account. Absence of a roster is "unknown", never "no":
+ * an account that was never active during discovery stays fully usable.
+ */
+
+/** A roster older than this is treated as unknown; entitlements change with plan and rollout. */
+export const ANTIGRAVITY_ACCOUNT_ROSTER_TTL_MS = 6 * 60 * 60 * 1000;
+
+interface AccountRoster {
+  readonly ids: ReadonlySet<string>;
+  readonly modelIds: readonly string[];
+  readonly observedAt: number;
+}
+
+const rosters = new Map<string, AccountRoster>();
+
+function rosterKey(providerName: string, accountId: string): string {
+  return `${getConfigDir()}\0${providerName}\0${accountId}`;
+}
+
+/** Record one account's discovered roster: picker ids, representative wire ids, and tier wire ids. */
+export function recordAntigravityAccountRoster(
+  providerName: string,
+  accountId: string,
+  models: readonly AntigravityAvailableModel[],
+  now = Date.now(),
+): void {
+  if (!providerName || !accountId) return;
+  const ids = new Set<string>();
+  for (const model of models) {
+    ids.add(model.id);
+    ids.add(model.wireModelId);
+    for (const wire of Object.values(model.effortWireModelIds ?? {})) if (wire) ids.add(wire);
+  }
+  rosters.set(rosterKey(providerName, accountId), {
+    ids,
+    modelIds: models.map(model => model.id),
+    observedAt: now,
+  });
+}
+
+function freshRoster(providerName: string, accountId: string, now: number): AccountRoster | undefined {
+  const roster = rosters.get(rosterKey(providerName, accountId));
+  if (!roster || now - roster.observedAt > ANTIGRAVITY_ACCOUNT_ROSTER_TTL_MS) return undefined;
+  return roster;
+}
+
+/** The picker ids one account's last discovery returned, or `undefined` when unknown. */
+export function antigravityAccountRosterModelIds(
+  providerName: string,
+  accountId: string,
+  now = Date.now(),
+): readonly string[] | undefined {
+  return freshRoster(providerName, accountId, now)?.modelIds;
+}
+
+/**
+ * Whether one account's roster lists `modelId`: `true` / `false` from its last discovery,
+ * `undefined` when that account has no fresh roster. A picker id, one of its tier wire ids, or a
+ * compatibility alias of either all count as listed.
+ */
+export function antigravityAccountSupportsModel(
+  providerName: string,
+  accountId: string,
+  modelId: string,
+  now = Date.now(),
+): boolean | undefined {
+  const roster = freshRoster(providerName, accountId, now);
+  if (!roster) return undefined;
+  const id = modelId.trim();
+  if (!id) return undefined;
+  if (roster.ids.has(id)) return true;
+  const canonical = canonicalAntigravityUsageModel(id);
+  if (roster.ids.has(canonical)) return true;
+  const alias = Object.hasOwn(ANTIGRAVITY_MODEL_ALIASES, id) ? ANTIGRAVITY_MODEL_ALIASES[id] : undefined;
+  return alias !== undefined && roster.ids.has(alias);
+}
+
+/** Forget rosters (one account, or all). For account removal and tests. */
+export function clearAntigravityAccountRosters(providerName?: string, accountId?: string): void {
+  if (providerName && accountId) {
+    rosters.delete(rosterKey(providerName, accountId));
+    return;
+  }
+  rosters.clear();
+}

package/src/providers/antigravity-models.ts

@@ -17,6 +17,21 @@ import { readAntigravityWireSnapshot, writeAntigravityWireSnapshot, type Antigra
 /** Current Antigravity Flash generation. */
 const GEMINI_FLASH_CURRENT = "gemini-3.8-flash";
 
+/**
+ * Gemini 4 Argon. Like 3.8 it publishes one wire id per tier (`-low/-medium/-high`) and no
+ * `-tiered` row, verified 2026-10-14 against live CCA. CCA serves these ids only to the CLI
+ * User-Agent (see antigravityUserAgentForWireModel), and only to AI Ultra / Enterprise accounts.
+ */
+const GEMINI_ARGON = "gemini-4-argon";
+
+/**
+ * Claude 5.5 on Antigravity: one wire id per tier (`-low/-medium/-high`), each 1,000,000 tokens
+ * with image input, observed in live CCA discovery on 2026-10-03
+ * (devlog/_fin/261003_release_lane_c). They ride the IDE User-Agent like every non-Argon model.
+ */
+const CLAUDE_OPUS_55 = "claude-opus-5-5";
+const CLAUDE_SONNET_55 = "claude-sonnet-5-5";
+
 /**
  * Previous Flash generation — still served, still picker-visible.
  *
@@ -75,6 +90,15 @@ const ANTIGRAVITY_WIRE_MODELS = [
 ];
 
 const ANTIGRAVITY_PICKER_MODEL_BY_WIRE_ID: Record<string, string> = {
+  "claude-opus-5-5-low": CLAUDE_OPUS_55,
+  "claude-opus-5-5-medium": CLAUDE_OPUS_55,
+  "claude-opus-5-5-high": CLAUDE_OPUS_55,
+  "claude-sonnet-5-5-low": CLAUDE_SONNET_55,
+  "claude-sonnet-5-5-medium": CLAUDE_SONNET_55,
+  "claude-sonnet-5-5-high": CLAUDE_SONNET_55,
+  "gemini-4-argon-low": GEMINI_ARGON,
+  "gemini-4-argon-medium": GEMINI_ARGON,
+  "gemini-4-argon-high": GEMINI_ARGON,
   "gemini-3.8-flash-low": "gemini-3.8-flash",
   "gemini-3.8-flash-medium": "gemini-3.8-flash",
   "gemini-3.8-flash-high": "gemini-3.8-flash",
@@ -164,8 +188,11 @@ function collapsesIntoKnownPickerModel(candidateId: string): boolean {
 // Claude Opus: effort → thinkingConfig.thinkingLevel (CLIProxyAPI proven pattern).
 export const ANTIGRAVITY_MODEL_EFFORTS: Record<string, string[]> = {
   // No `minimal`: Google documents it as an error for this generation, and CCA exposes only
-  // the three tiers.
+  // the three tiers. Argon documents the same ladder (`minimal` is an HTTP 400).
+  [GEMINI_ARGON]: ["low", "medium", "high"],
   "gemini-3.8-flash": ["low", "medium", "high"],
+  [CLAUDE_OPUS_55]: ["low", "medium", "high"],
+  [CLAUDE_SONNET_55]: ["low", "medium", "high"],
   "gemini-3.7-flash": ["low", "medium", "high"],
   "gemini-3.1-pro": ["low", "high"],
   "claude-sonnet-4-6": ["low", "medium", "high", "max"],
@@ -175,7 +202,23 @@ export const ANTIGRAVITY_MODEL_EFFORTS: Record<string, string[]> = {
 // ── Effort → wire model map for Gemini base models ──
 const ANTIGRAVITY_EFFORT_WIRE_MAP: Record<string, Record<string, string>> = {
   // 3.8 publishes one wire id per tier and no `-tiered` row, so its efforts ride the suffix.
-  // This is the 3.6 shape, not the 3.7 one.
+  // This is the 3.6 shape, not the 3.7 one. Argon has the same shape.
+  [GEMINI_ARGON]: {
+    low: "gemini-4-argon-low",
+    medium: "gemini-4-argon-medium",
+    high: "gemini-4-argon-high",
+  },
+  // Claude 5.5 publishes the same per-tier suffix family.
+  [CLAUDE_OPUS_55]: {
+    low: "claude-opus-5-5-low",
+    medium: "claude-opus-5-5-medium",
+    high: "claude-opus-5-5-high",
+  },
+  [CLAUDE_SONNET_55]: {
+    low: "claude-sonnet-5-5-low",
+    medium: "claude-sonnet-5-5-medium",
+    high: "claude-sonnet-5-5-high",
+  },
   "gemini-3.8-flash": {
     low: "gemini-3.8-flash-low",
     medium: "gemini-3.8-flash-medium",
@@ -198,7 +241,7 @@ const ANTIGRAVITY_EFFORT_WIRE_MAP: Record<string, Record<string, string>> = {
  * `gemini-3.1-pro` is deliberately absent: its `high` rung is `gemini-pro-agent`, which carries
  * no tier suffix, so there the level is the only thing naming the effort.
  */
-const ANTIGRAVITY_SUFFIX_TIER_MODELS = new Set(["gemini-3.8-flash"]);
+const ANTIGRAVITY_SUFFIX_TIER_MODELS = new Set([GEMINI_ARGON, "gemini-3.8-flash", CLAUDE_OPUS_55, CLAUDE_SONNET_55]);
 
 function completeDiscoveredEffortWireModelIds(
   pickerId: string,
@@ -223,7 +266,11 @@ function completeDiscoveredEffortWireModelIds(
 // ── Default effort per Gemini base model ──
 const ANTIGRAVITY_DEFAULT_EFFORT: Record<string, string> = {
   // Google's documented thinking_level default, and the tier CCA marks `recommended`.
+  [GEMINI_ARGON]: "medium",
   "gemini-3.8-flash": "medium",
+  // Matches the discovered-family default (medium), so static and live resolution agree.
+  [CLAUDE_OPUS_55]: "medium",
+  [CLAUDE_SONNET_55]: "medium",
   "gemini-3.1-pro": "high",
 };
 
@@ -285,9 +332,25 @@ export const ANTIGRAVITY_MODEL_ALIASES: Record<string, string> = {
   ...ANTIGRAVITY_COMPATIBILITY_MODEL_ALIASES,
 };
 
-// Picker-visible: collapsed base models only.
+// Static picker lineup: collapsed base models only, exactly "3.8 / 4 / 5.5 / 5.5" (2026-10-14).
+// Anything else reaches the picker only when live discovery returns it.
 export const ANTIGRAVITY_MODELS = [
   GEMINI_FLASH_CURRENT,
+  GEMINI_ARGON,
+  CLAUDE_OPUS_55,
+  CLAUDE_SONNET_55,
+];
+
+/**
+ * Every base id the routing and discovery rules recognise: the static lineup plus models that
+ * left it. Removing a model from the picker must not change how a saved selection routes or how
+ * a discovered row collapses, so these legacy bases stay known here. Live discovery on
+ * 2026-10-14 no longer returns gemini-3.7-flash(-tiered) or the gemini-3.1-pro wire ids (both
+ * 404), but still returns the Claude 4.6 rows and gpt-oss-120b-medium, which therefore keep
+ * appearing through discovery.
+ */
+export const ANTIGRAVITY_KNOWN_PICKER_MODELS: readonly string[] = [
+  ...ANTIGRAVITY_MODELS,
   GEMINI_FLASH_PREVIOUS,
   "gemini-3.1-pro",
   "gemini-3.1-flash-image",
@@ -297,11 +360,20 @@ export const ANTIGRAVITY_MODELS = [
 ];
 
 function isKnownAntigravityPickerModelId(value: string): boolean {
-  return isValidModelDiscoveryModelId(value) && ANTIGRAVITY_MODELS.includes(value);
+  return isValidModelDiscoveryModelId(value) && ANTIGRAVITY_KNOWN_PICKER_MODELS.includes(value);
 }
 
 // Context windows from the upstream `:fetchAvailableModels` maxTokens per model.
 const ANTIGRAVITY_WIRE_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
+  "claude-opus-5-5-low": 1_000_000,
+  "claude-opus-5-5-medium": 1_000_000,
+  "claude-opus-5-5-high": 1_000_000,
+  "claude-sonnet-5-5-low": 1_000_000,
+  "claude-sonnet-5-5-medium": 1_000_000,
+  "claude-sonnet-5-5-high": 1_000_000,
+  "gemini-4-argon-low": 1_048_576,
+  "gemini-4-argon-medium": 1_048_576,
+  "gemini-4-argon-high": 1_048_576,
   "gemini-3.8-flash-low": 1_048_576,
   "gemini-3.8-flash-medium": 1_048_576,
   "gemini-3.8-flash-high": 1_048_576,
@@ -316,7 +388,10 @@ const ANTIGRAVITY_WIRE_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
 
 export const ANTIGRAVITY_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
   // Collapsed base IDs — explicit entries for the picker.
+  [GEMINI_ARGON]: 1_048_576,
   "gemini-3.8-flash": 1_048_576,
+  [CLAUDE_OPUS_55]: 1_000_000,
+  [CLAUDE_SONNET_55]: 1_000_000,
   "gemini-3.7-flash": 1_048_576,
   "gemini-3.1-pro": 1_048_576,
   // Wire IDs and aliases via derivation.
@@ -330,6 +405,9 @@ export const ANTIGRAVITY_MODEL_CONTEXT_WINDOWS: Record<string, number> = {
 };
 
 export const ANTIGRAVITY_MODEL_INPUT_MODALITIES: Record<string, string[]> = {
+  [GEMINI_ARGON]: ["text", "image"],
+  [CLAUDE_OPUS_55]: ["text", "image"],
+  [CLAUDE_SONNET_55]: ["text", "image"],
   // Google documents 3.7 Flash as also accepting video, audio and PDF, but this proxy
   // carries only text and image parts (`OcxImageContent`, src/types.ts) and the Codex
   // catalog normalizes `input_modalities` against a closed enum. Advertising a modality
@@ -641,7 +719,7 @@ export function resolveAntigravityWireModelId(modelId: string, baseUrl?: string)
  * IS the effort, and sending both creates a contradictory request.
  */
 export function isAntigravitySuffixModelId(modelId: string): boolean {
-  return !(ANTIGRAVITY_MODELS as string[]).includes(modelId);
+  return !ANTIGRAVITY_KNOWN_PICKER_MODELS.includes(modelId);
 }
 
 /** The reasoning tier a retired Flash id used to encode, if it is one. */
@@ -753,7 +831,7 @@ export function resolveAntigravityEffortWireModel(
 // summary aggregation consults this reverse map so one call model = one usage row.
 const ANTIGRAVITY_USAGE_BASE_BY_ID: Record<string, string> = (() => {
   const rev: Record<string, string> = {};
-  for (const base of ANTIGRAVITY_MODELS) rev[base] = base;
+  for (const base of ANTIGRAVITY_KNOWN_PICKER_MODELS) rev[base] = base;
   for (const [base, effortMap] of Object.entries(ANTIGRAVITY_EFFORT_WIRE_MAP)) {
     rev[base] = base;
     for (const wire of Object.values(effortMap)) rev[wire] = base;

package/src/providers/api-key-cooldowns.ts

@@ -0,0 +1,49 @@
+/** Process-local cooldown state shared by selection validation and key failover. */
+const keyCooldowns = new Map<string, { cooldownUntil: number }>();
+
+function cooldownKey(providerName: string, keyId: string): string {
+  return `${providerName}\0${keyId}`;
+}
+
+export function setKeyCooldown(providerName: string, keyId: string, cooldownUntil: number): void {
+  const key = cooldownKey(providerName, keyId);
+  keyCooldowns.set(key, { cooldownUntil: Math.max(keyCooldowns.get(key)?.cooldownUntil ?? 0, cooldownUntil) });
+}
+
+export function isKeyInCooldown(providerName: string, keyId: string, now = Date.now()): boolean {
+  const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    keyCooldowns.delete(cooldownKey(providerName, keyId));
+    return false;
+  }
+  return true;
+}
+
+export function getKeyCooldownUntil(providerName: string, keyId: string, now = Date.now()): number | null {
+  const entry = keyCooldowns.get(cooldownKey(providerName, keyId));
+  if (!entry) return null;
+  return entry.cooldownUntil > now ? entry.cooldownUntil : null;
+}
+
+export function sweepExpiredApiKeyCooldowns(now = Date.now()): number {
+  let removed = 0;
+  for (const [key, cooldown] of keyCooldowns) {
+    if (cooldown.cooldownUntil > now) continue;
+    keyCooldowns.delete(key);
+    removed += 1;
+  }
+  return removed;
+}
+
+/** Manual key management clears this provider's cooldowns. */
+export function clearKeyCooldowns(providerName?: string): void {
+  if (!providerName) {
+    keyCooldowns.clear();
+    return;
+  }
+  const prefix = `${providerName}\0`;
+  for (const key of keyCooldowns.keys()) {
+    if (key.startsWith(prefix)) keyCooldowns.delete(key);
+  }
+}

package/src/providers/api-key-resolve.ts

@@ -18,9 +18,12 @@
  */
 import { resolveEnvValue } from "../config/proxy-env";
 import { loadKeyringBinding } from "../lib/keyring-native";
+import { isGcpCredentialMaterial } from "../lib/gcp-credential-input";
 import type { OcxProviderConfig } from "../types";
 
 export const KEYCHAIN_REFERENCE_PREFIX = "keychain:";
+/** Stored GCP JSON uses the same OS service, but must never be restored as a literal API key. */
+export const GCP_CREDENTIAL_MARKER_PREFIX = "gcp-sa:";
 export const PROVIDER_KEYCHAIN_SERVICE = "opencodex.provider-api-key.v1";
 
 export interface ProviderKeychainEntry {
@@ -87,15 +90,17 @@ export function providerKeychainEntry(account: string): ProviderKeychainEntry {
 function readKeychain(account: string, quiet = false): string | undefined {
   const cached = resolvedCache.get(account);
   if (cached !== undefined) return cached;
+  let value: string | null = null;
   try {
-    const value = providerKeychainEntry(account).getPassword();
-    if (typeof value === "string" && value.trim()) {
-      resolvedCache.set(account, value);
-      return value;
-    }
+    value = providerKeychainEntry(account).getPassword();
   } catch {
     // fall through to the single warning below
   }
+  if (typeof value === "string" && value.trim()) {
+    if (isGcpCredentialMaterial(value)) throw new Error("GCP credential JSON cannot be used as a literal API key; select a gcp-sa reference");
+    resolvedCache.set(account, value);
+    return value;
+  }
   if (!quiet && !warnedAccounts.has(account)) {
     warnedAccounts.add(account);
     console.warn(`[opencodex] provider key reference keychain:${account} could not be read from the OS keychain; requests for this provider have no credential until the keychain is available (no plaintext fallback)`);
@@ -125,7 +130,7 @@ export type ProviderKeyStoreKind = "keychain" | "env" | "file" | "none";
 export function providerKeyStoreKind(provider: Pick<OcxProviderConfig, "apiKey"> | undefined): ProviderKeyStoreKind {
   const key = provider?.apiKey;
   if (!key) return "none";
-  if (isKeychainReference(key)) return "keychain";
+  if (key.startsWith(GCP_CREDENTIAL_MARKER_PREFIX) || isKeychainReference(key)) return "keychain";
   if (/^\$\{?\w+\}?$/.test(key)) return "env";
   return "file";
 }

package/src/providers/api-key-response-ownership.ts

@@ -0,0 +1,57 @@
+import type { OcxConfig, OcxProviderConfig } from "../types";
+import { isEgressTransparentExecutor, markEgressTransparentExecutor } from "../lib/provider-egress";
+import { isNonReplayableResponse } from "../lib/upstream-retry";
+import { providerApiKeySelectionOwnsFailure } from "./api-key-selection";
+import { recordDistributedKeyFailure } from "./key-failover";
+import { registerProviderResponseProvenance } from "./request-pacing";
+
+interface KeyResponseOwner {
+  readonly providerName: string;
+  readonly provider: OcxProviderConfig;
+}
+const owners = new WeakMap<Response, KeyResponseOwner | null>();
+registerProviderResponseProvenance(owners);
+
+/** Capture the credential after connection-policy rewrites, immediately before fetch. */
+export function distributedKeyPhysicalFetch(
+  physicalFetch: typeof globalThis.fetch, providerName: string, provider: OcxProviderConfig, target: string,
+  authHeader: "authorization" | "x-api-key" = "authorization",
+): typeof globalThis.fetch {
+  if (!provider._apiKeyAttempt?.distributed) return physicalFetch;
+  const wrapped = (async (input, init) => {
+    const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+    const destination = input instanceof Request ? input.url : String(input);
+    const ownsCredential = destination === target && !headers.has("api-key")
+      && (authHeader === "authorization"
+        ? headers.get("authorization") === `Bearer ${provider.apiKey}` && !headers.has("x-api-key")
+        : headers.get("x-api-key") === provider.apiKey && !headers.has("authorization"));
+    const owner: KeyResponseOwner | null = provider._apiKeyAttempt?.distributed && ownsCredential
+      ? Object.freeze({ providerName, provider: Object.freeze({ ...provider,
+        _apiKeyAttempt: Object.freeze({ ...provider._apiKeyAttempt }) }) }) : null;
+    const response = await physicalFetch(input, init);
+    // Reused response identities cannot safely describe two physical sends.
+    owners.set(response, owners.has(response) ? null : owner);
+    return response;
+  }) as typeof globalThis.fetch;
+  return isEgressTransparentExecutor(physicalFetch) ? markEgressTransparentExecutor(wrapped) : wrapped;
+}
+
+/** Return only a still-configured credential captured at the physical send. */
+export function distributedKeyResponseOwner(
+  response: Response, config: OcxConfig, providerName: string,
+): OcxProviderConfig | null {
+  const owner = owners.get(response);
+  return owner?.providerName === providerName
+    && providerApiKeySelectionOwnsFailure(config, providerName, owner.provider) ? owner.provider : null;
+}
+
+/** Settle only the terminal refusal; configured same-key 429 retries retain their key. */
+export function recordDistributedResponseFailure(
+  response: Response, config: OcxConfig, providerName: string, signal?: AbortSignal,
+): void {
+  if (signal?.aborted || isNonReplayableResponse(response) || (response.status !== 401 && response.status !== 429)) return;
+  const owner = distributedKeyResponseOwner(response, config, providerName);
+  if (!owner) return;
+  recordDistributedKeyFailure(config, providerName, owner._apiKeyAttempt,
+    response.status, Date.now(), response.headers.get("retry-after"));
+}

package/src/providers/api-key-selection.ts

@@ -1,10 +1,11 @@
+import { isKeyInCooldown } from "./api-key-cooldowns";
 import { randomUUID } from "node:crypto";
 import { mutatePersistedConfig } from "../config";
 import { publishAccountSelection } from "../lib/account-selection-events";
 import { clearModelCache } from "../codex/model-cache";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import type { ProviderApiKeySelection } from "../types/provider";
-import { routedProviderConfig } from "../router";
+import { routedProviderConfig } from "./routed-config";
 import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, XAI_GROK_COMPATIBILITY, type OcxProviderTransport } from "./xai-transport";
 import { captureProviderApiKeySelection } from "./api-key-selection-capture";
@@ -17,10 +18,17 @@ function matchesSelection(provider: OcxProviderConfig, expected: ProviderApiKeyS
     && current.revision === expected.revision;
 }
 
-function currentKeyProvider(config: OcxConfig, name: string): OcxProviderConfig | null {
+function currentKeyProvider(config: OcxConfig, name: string, selection?: ProviderApiKeySelection, allowCooling = false): OcxProviderConfig | null {
   const configured = config.providers[name];
   if (!configured || configured.disabled) return null;
-  const current = routedProviderConfig(name, { ...configured, _apiKeyAttempt: undefined });
+  let row = configured;
+  if (selection?.distributed) {
+    const entry = configured.apiKeyPool?.find(key => key.id === selection.entryId && key.key === selection.reference);
+    if (!entry || (!allowCooling && isKeyInCooldown(name, entry.id)) || configured.apiKeySelectionRevision !== selection.revision
+      || !configured.requestPacing?.enabled || configured.requestPacing.keySelection !== "round-robin") return null;
+    row = { ...configured, apiKey: entry.key, _apiKeyAttempt: selection };
+  }
+  const current = routedProviderConfig(name, { ...row, _apiKeyAttempt: selection?.distributed ? selection : undefined });
   if (current.authMode === "oauth" || current.authMode === "forward") return null;
   if (current.authMode === "key" && !current.keyOptional && !current.apiKey?.trim()) return null;
   return current;
@@ -32,10 +40,23 @@ export function providerApiKeySelectionIsCurrent(
   name: string,
   routedProvider: OcxProviderConfig,
 ): boolean {
-  const current = currentKeyProvider(config, name);
+  return matchesConfiguredSelection(config, name, routedProvider, false);
+}
+
+/** An already sent failure can extend cooldown, but cannot authorize another dispatch. */
+export function providerApiKeySelectionOwnsFailure(
+  config: OcxConfig, name: string, routedProvider: OcxProviderConfig,
+): boolean {
+  return matchesConfiguredSelection(config, name, routedProvider, true);
+}
+
+function matchesConfiguredSelection(
+  config: OcxConfig, name: string, routedProvider: OcxProviderConfig, allowCooling: boolean,
+): boolean {
   const expected = routedProvider._apiKeyAttempt;
+  const current = currentKeyProvider(config, name, expected, allowCooling);
   return current !== null && expected !== undefined
-    && matchesSelection(config.providers[name]!, expected)
+    && (expected.distributed === true || matchesSelection(config.providers[name]!, expected))
     && current.apiKey === routedProvider.apiKey
     && current.authMode === routedProvider.authMode
     && current.baseUrl === routedProvider.baseUrl;
@@ -47,7 +68,11 @@ export function resolveCurrentProviderApiKeyTransport(
   name: string,
   routedProvider: OcxProviderConfig,
 ): OcxProviderConfig | null {
-  const current = currentKeyProvider(config, name);
+  // A permit acquired for one key cannot authorize a different key after a manual edit.
+  if (routedProvider.requestPacing?.enabled && routedProvider.requestPacing.keys
+    && routedProvider._apiKeyAttempt && config.providers[name]
+    && !routedProvider._apiKeyAttempt.distributed && !matchesSelection(config.providers[name]!, routedProvider._apiKeyAttempt)) return null;
+  const current = currentKeyProvider(config, name, routedProvider._apiKeyAttempt);
   if (!current) return null;
   const runtime = routedProvider as OcxProviderTransport;
   const headers = { ...current.headers };