@iislee/opencodex 2.11.0 → 2.35.0

package/src/oauth/command-code.ts

@@ -0,0 +1,239 @@
+import type { OAuthController, OAuthCredentials } from "./types";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { isAddrInUse } from "../server/ports";
+import { parseCallbackInput } from "./callback-server";
+
+const COMMAND_CODE_STUDIO_URL = "https://commandcode.ai";
+const COMMAND_CODE_CALLBACK_PORT = 5959;
+const LOGIN_TIMEOUT_MS = 120_000;
+const CALLBACK_PATH = "/callback";
+
+interface CommandCodeCallback {
+  apiKey: string;
+  state: string;
+  userId: string;
+  userName: string;
+  keyName: string;
+}
+
+interface CommandCodeLocalAuth {
+  apiKey?: unknown;
+  userId?: unknown;
+}
+
+export interface CommandCodeLoginOptions {
+  /** Add-account and reauthentication flows must select a fresh browser identity. */
+  importLocal?: "fallback" | "off";
+}
+
+export function shouldImportLocalCommandCodeAuth(options: CommandCodeLoginOptions = {}): boolean {
+  return options.importLocal !== "off";
+}
+
+async function importLocalCommandCodeAuth(signal?: AbortSignal): Promise<OAuthCredentials | undefined> {
+  if (signal?.aborted) {
+    throw signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+  }
+  let parsed: CommandCodeLocalAuth;
+  try {
+    parsed = JSON.parse(await Bun.file(join(homedir(), ".commandcode", "auth.json")).text()) as CommandCodeLocalAuth;
+  } catch {
+    return undefined;
+  }
+  if (typeof parsed.apiKey !== "string" || parsed.apiKey.length === 0) return undefined;
+  let accountId: string | undefined;
+  try {
+    const response = await fetch("https://api.commandcode.ai/alpha/whoami", {
+      headers: { Authorization: `Bearer ${parsed.apiKey}`, Accept: "application/json" },
+      signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(10_000)]) : AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return undefined;
+    // Carry the validated whoami identity so an imported credential keeps multi-account
+    // semantics even when the local auth.json omits userId.
+    const body = (await response.json()) as { user?: { id?: unknown } };
+    if (typeof body.user?.id === "string" && body.user.id.length > 0) accountId = body.user.id;
+  } catch (error) {
+    if (signal?.aborted) throw signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+    return undefined;
+  }
+  if (!accountId && typeof parsed.userId === "string" && parsed.userId.length > 0) accountId = parsed.userId;
+  return {
+    access: parsed.apiKey,
+    refresh: parsed.apiKey,
+    expires: Number.MAX_SAFE_INTEGER,
+    ...(accountId ? { accountId } : {}),
+    source: "local-cli",
+  };
+}
+
+function randomState(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Buffer.from(bytes).toString("base64url");
+}
+
+export function parseCommandCodeCallback(value: unknown, expectedState: string): CommandCodeCallback {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Command Code callback must be an object");
+  }
+  const body = value as Record<string, unknown>;
+  if (body.state !== expectedState) throw new Error("Command Code OAuth state mismatch");
+  for (const field of ["apiKey", "userId", "userName", "keyName"] as const) {
+    if (typeof body[field] !== "string" || body[field].length === 0) {
+      throw new Error(`Command Code callback missing ${field}`);
+    }
+  }
+  return body as unknown as CommandCodeCallback;
+}
+
+function createCallbackServer(state: string): {
+  servers: Array<ReturnType<typeof Bun.serve>>;
+  callback: Promise<CommandCodeCallback>;
+} {
+  let resolve!: (value: CommandCodeCallback) => void;
+  const callback = new Promise<CommandCodeCallback>((res) => { resolve = res; });
+  const fetch = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url);
+    const origin = request.headers.get("origin");
+    const headers = new Headers({
+      "Content-Type": "application/json",
+      "Access-Control-Allow-Origin": origin === COMMAND_CODE_STUDIO_URL ? origin : COMMAND_CODE_STUDIO_URL,
+      "Access-Control-Allow-Methods": "POST, OPTIONS",
+      "Access-Control-Allow-Headers": "Content-Type",
+    });
+    if (request.method === "OPTIONS") return new Response(null, { status: 204, headers });
+    if (url.pathname !== CALLBACK_PATH) return Response.json({ success: false, error: "Not found" }, { status: 404, headers });
+    if (request.method !== "POST") return Response.json({ success: false, error: "Method not allowed" }, { status: 405, headers });
+    try {
+      const body = await request.json();
+      const parsed = parseCommandCodeCallback(body, state);
+      queueMicrotask(() => resolve(parsed));
+      return Response.json({ success: true }, { headers });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return Response.json({ success: false, error: message }, { status: 400, headers });
+    }
+  };
+  const create = (port: number): Array<ReturnType<typeof Bun.serve>> => {
+    // The advertised callback host is `127.0.0.1`; on Windows `localhost` commonly resolves to `::1`
+    // first, so also bind the IPv6 loopback best-effort (mirrors the shared OAuthCallbackFlow).
+    const servers = [Bun.serve({ hostname: "127.0.0.1", port, fetch })];
+    try {
+      servers.push(Bun.serve({ hostname: "::1", port: servers[0].port, fetch }));
+    } catch (error) {
+      if (isAddrInUse(error)) {
+        for (const server of servers) server.stop(true);
+        throw error;
+      }
+      // IPv6 unsupported (EAFNOSUPPORT etc.) degrades to the IPv4-only listener.
+    }
+    return servers;
+  };
+  try {
+    return { servers: create(COMMAND_CODE_CALLBACK_PORT), callback };
+  } catch {
+    return { servers: create(0), callback };
+  }
+}
+
+/** Validate a raw pasted Command Code API key and return the validated identity. */
+async function validatePastedApiKey(apiKey: string): Promise<{ userId: string; userName: string } | undefined> {
+  try {
+    const response = await fetch("https://api.commandcode.ai/alpha/whoami", {
+      headers: { Authorization: `Bearer ${apiKey}`, Accept: "application/json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) return undefined;
+    const body = (await response.json()) as { user?: { id?: unknown; userName?: unknown } };
+    const userId = body.user?.id;
+    const userName = body.user?.userName;
+    if (typeof userId !== "string" || typeof userName !== "string") return undefined;
+    if (!userId.trim() || !userName.trim()) return undefined;
+    return { userId, userName };
+  } catch {
+    return undefined;
+  }
+}
+
+/** Manual-paste fallback: a raw API key, or a pasted callback JSON/URL that carries `apiKey`. */
+function parsePastedCommandCodeInput(input: string, expectedState: string): CommandCodeCallback | undefined {
+  const trimmed = input.trim();
+  if (!trimmed) return undefined;
+  if (trimmed.startsWith("{")) {
+    try {
+      return parseCommandCodeCallback(JSON.parse(trimmed) as unknown, expectedState);
+    } catch {
+      return undefined;
+    }
+  }
+  const parsed = parseCallbackInput(trimmed);
+  const apiKey = parsed.code?.trim();
+  if (!apiKey) return undefined;
+  // A URL/query-shaped paste is an authorization response and must carry a matching state,
+  // mirroring the shared OAuth callback flow; a stale or attacker-supplied URL from another
+  // session must not be accepted. Raw in-session keys are exempt (no state to compare).
+  if (parsed.kind !== "raw" && parsed.state !== expectedState) return undefined;
+  return { apiKey, state: expectedState, userId: "", userName: "", keyName: "manual" };
+}
+
+export async function loginCommandCode(ctrl: OAuthController, options: CommandCodeLoginOptions = {}): Promise<OAuthCredentials> {
+  if (ctrl.signal?.aborted) {
+    throw ctrl.signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+  }
+  if (shouldImportLocalCommandCodeAuth(options)) {
+    const local = await importLocalCommandCodeAuth(ctrl.signal);
+    if (local) {
+      ctrl.onProgress?.("Imported existing Command Code CLI authentication.");
+      return local;
+    }
+  }
+  const state = randomState();
+  let servers: Array<ReturnType<typeof Bun.serve>> = [];
+  let timeoutId: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const created = createCallbackServer(state);
+    servers = created.servers;
+    const callbackUrl = `http://127.0.0.1:${servers[0].port}${CALLBACK_PATH}`;
+    const authUrl = `${COMMAND_CODE_STUDIO_URL}/studio/auth/cli?callback=${encodeURIComponent(callbackUrl)}&state=${encodeURIComponent(state)}`;
+    ctrl.onAuth?.({ url: authUrl, instructions: "Sign in with Command Code in the browser." });
+    ctrl.onProgress?.("Waiting for Command Code authentication...");
+    const timeout = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error("Command Code OAuth callback timed out")), LOGIN_TIMEOUT_MS);
+      ctrl.signal?.addEventListener("abort", () => { if (timeoutId) clearTimeout(timeoutId); reject(ctrl.signal?.reason); }, { once: true });
+    });
+    const manual = ctrl.onManualCodeInput
+      ? (async (): Promise<CommandCodeCallback> => {
+          while (true) {
+            // The loop keeps waiting until a valid paste arrives; invalid pastes re-prompt.
+            // Yield between iterations so an abort signal can interrupt a fast re-prompt loop.
+            if (ctrl.signal?.aborted) throw ctrl.signal.reason ?? new DOMException("Command Code login aborted", "AbortError");
+            const input = await ctrl.onManualCodeInput?.(state);
+            if (input === undefined) continue;
+            const pasted = parsePastedCommandCodeInput(input, state);
+            if (!pasted) continue;
+            const identity = await validatePastedApiKey(pasted.apiKey);
+            if (identity) return { ...pasted, ...identity };
+            await new Promise(resolve => setTimeout(resolve, 0));
+          }
+        })()
+      : undefined;
+    const result = await Promise.race([created.callback, timeout, ...(manual ? [manual] : [])]);
+    if (result === undefined) throw new Error("Command Code OAuth callback cancelled");
+    return {
+      access: result.apiKey,
+      refresh: result.apiKey,
+      expires: Number.MAX_SAFE_INTEGER,
+      accountId: result.userId,
+      source: "oauth",
+    };
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+    for (const server of servers) server.stop(true);
+  }
+}
+
+export async function refreshCommandCodeToken(apiKey: string): Promise<OAuthCredentials> {
+  if (!apiKey) throw new Error("Command Code API key missing; run ocx login command-code");
+  return { access: apiKey, refresh: apiKey, expires: Number.MAX_SAFE_INTEGER, source: "oauth" };
+}

package/src/oauth/cursor.ts

@@ -52,8 +52,8 @@ function decodeCursorJwtPayload(token: string): CursorJwtPayload | undefined {
 /** Build OAuthCredentials from Cursor tokens, extracting stable identity from JWT `sub` for multiauth. */
 export function credentialsFromCursorTokens(accessToken: string, refreshToken: string): OAuthCredentials {
   const payload = decodeCursorJwtPayload(accessToken) ?? decodeCursorJwtPayload(refreshToken);
-  const accountId = typeof payload?.sub === "string" && payload.sub.length > 0 ? payload.sub : undefined;
-  const email = typeof payload?.email === "string" && payload.email.length > 0 ? payload.email.toLowerCase() : undefined;
+  const accountId = cursorJwtIdentity(payload?.sub);
+  const email = cursorJwtEmail(payload?.email);
   return {
     access: accessToken,
     refresh: refreshToken,
@@ -63,10 +63,24 @@ export function credentialsFromCursorTokens(accessToken: string, refreshToken: s
   };
 }
 
+/** Coerce JWT `sub` (string or safe integer) into a stable multiauth account id. */
+function cursorJwtIdentity(value: unknown): string | undefined {
+  if (typeof value === "string" && value.length > 0) return value;
+  if (typeof value === "number" && Number.isSafeInteger(value)) return String(value);
+  return undefined;
+}
+
+function cursorJwtEmail(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length === 0) return undefined;
+  return value.toLowerCase();
+}
+
 /** Generate PKCE params + the cursor.com deep-link login URL (challenge only — never the verifier). */
-export async function generateCursorAuthParams(): Promise<CursorAuthParams> {
+export async function generateCursorAuthParams(_opts?: { forceLogin?: boolean }): Promise<CursorAuthParams> {
   const { verifier, challenge } = await generatePKCE();
   const uuid = crypto.randomUUID();
+  // Cursor's deep-control page has no documented account-picker query; only the stable
+  // PKCE params are sent. forceLogin is honored only in loginCursor instructions.
   const params = new URLSearchParams({ challenge, uuid, mode: "login", redirectTarget: "cli" });
   return { verifier, challenge, uuid, loginUrl: `${CURSOR_LOGIN_URL}?${params.toString()}` };
 }
@@ -87,6 +101,19 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+/** Terminal poll statuses (T07, senpi PR #905): the login is denied/expired — retrying cannot succeed. */
+const POLL_TERMINAL_STATUSES = new Set([400, 401, 403, 410]);
+
+export class CursorAuthTerminalError extends Error {
+  readonly status: number;
+
+  constructor(status: number) {
+    super(`Cursor login rejected by the auth server (HTTP ${status}); start a new login`);
+    this.name = "CursorAuthTerminalError";
+    this.status = status;
+  }
+}
+
 /**
  * Poll cursor.com for login completion. 404 = still pending (back off), 200 = tokens.
  * `baseDelayMs` is injectable so tests can avoid the real 1s cadence; production uses the default.
@@ -121,9 +148,17 @@ export async function pollCursorAuth(
         return { accessToken: data.accessToken, refreshToken: data.refreshToken };
       }
 
+      // T07: a terminal auth status means the login attempt itself is dead (denied,
+      // expired, revoked). Fail on the FIRST such response instead of burning the
+      // 3-strike retry budget and masking the reason behind a generic error.
+      if (POLL_TERMINAL_STATUSES.has(response.status)) {
+        throw new CursorAuthTerminalError(response.status);
+      }
+
       throw new Error(`Cursor auth poll failed: ${response.status}`);
     } catch (err) {
       if (signal?.aborted) throw err instanceof Error ? err : new Error("Cursor login cancelled");
+      if (err instanceof CursorAuthTerminalError) throw err;
       consecutiveErrors++;
       if (consecutiveErrors >= 3) {
         throw new Error("Too many consecutive errors during Cursor auth polling");
@@ -139,9 +174,15 @@ export async function pollCursorAuth(
 export async function loginCursor(
   ctrl: OAuthController,
   pollBaseDelayMs: number = POLL_BASE_DELAY_MS,
+  opts?: { forceLogin?: boolean },
 ): Promise<OAuthCredentials> {
-  const { verifier, uuid, loginUrl } = await generateCursorAuthParams();
-  ctrl.onAuth?.({ url: loginUrl, instructions: "Approve the Cursor login in your browser, then return here." });
+  const { verifier, uuid, loginUrl } = await generateCursorAuthParams({ forceLogin: opts?.forceLogin === true });
+  ctrl.onAuth?.({
+    url: loginUrl,
+    instructions: opts?.forceLogin
+      ? "Log out of Cursor in the browser (or use a private window), sign in as the account you want to add, then approve and return here."
+      : "Approve the Cursor login in your browser, then return here.",
+  });
   ctrl.onProgress?.("Waiting for Cursor login approval…");
   const { accessToken, refreshToken } = await pollCursorAuth(uuid, verifier, ctrl.signal, pollBaseDelayMs);
   return credentialsFromCursorTokens(accessToken, refreshToken);

package/src/oauth/generic-account-failover.ts

@@ -0,0 +1,231 @@
+/**
+ * Generic OAuth multi-account 429 failover (#2568).
+ *
+ * The API-key twin (`providers/key-failover.ts`) rotates by default for any key provider with a
+ * 2+ pool, but it returns false for `authMode === "oauth"`, and the only OAuth rotator that
+ * exists is Anthropic's — behind its own opt-in. So xAI, Cursor, Kimi, GitHub Copilot,
+ * Antigravity and Nous have no recovery path on a 429 even with several accounts logged in.
+ *
+ * Deliberately narrower than the Anthropic pool: no session affinity, no quota-ranked selection,
+ * no probe leases. Those carry provider-specific meaning; this module only answers "the account
+ * that just 429'd is cooled, is there another one we may use".
+ *
+ * NOT a home for Codex (`codex/routing.ts` owns quota scopes and probe leases) or Anthropic
+ * (`oauth/anthropic-routing.ts` owns affinity and a fail-closed local-cli credential rule).
+ * Both are excluded by `isGenericFailoverProvider`.
+ */
+import { getAccountSet } from "./store";
+import { getValidAccessSnapshotForAccount, type OAuthAccessSnapshot } from "./index";
+import { parseRetryAfterMs } from "../combos/failover";
+import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
+import type { OcxConfig, OcxProviderConfig } from "../types";
+
+/** Cap same-request rotations so a short Retry-After cannot spin. Mirrors the Anthropic bound. */
+export const GENERIC_OAUTH_MAX_FAILOVERS_PER_REQUEST = 3;
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 15 * 60_000;
+
+/**
+ * How long a presence answer may be reused before the store is consulted again.
+ *
+ * `loadAuthStore` has no cache: every call chmods the config dir and the secret, reads the whole
+ * file, parses it and normalizes the store (store.ts:136-151). Since presence now decides
+ * activation, this predicate runs on paths that have not seen a 429 at all — the streaming and
+ * non-streaming runTurn entry points evaluate it once per request — so an uncached check would put
+ * a synchronous file read in front of every request for every OAuth provider.
+ *
+ * Two seconds is short enough that a login in another window is picked up before the operator can
+ * switch back and send a prompt, and long enough that a burst of requests shares one read. The
+ * cache holds a COUNT, never a credential.
+ */
+const PRESENCE_CACHE_TTL_MS = 2_000;
+
+/**
+ * Providers whose rotation is owned elsewhere and must not be handled here.
+ *
+ * `openai` is the Codex pool: quota scopes, probe leases and affinity semantics that this
+ * module deliberately does not reimplement. `anthropic` has its own pool with a fail-closed
+ * rule about background local-cli credential slots.
+ */
+const EXCLUDED_PROVIDERS = new Set(["openai", "anthropic"]);
+
+interface AccountHealth {
+  cooldownUntil: number;
+  cooldownSource: "retry-after" | "default";
+}
+
+interface PresenceEntry {
+  eligible: number;
+  readAt: number;
+}
+
+/** Process-local, like the Anthropic pool's: a restart is allowed to forget a cooldown. */
+const health = new Map<string, AccountHealth>();
+
+/** Provider -> recent eligible-account count. TTL-bounded; never holds credential material. */
+const presence = new Map<string, PresenceEntry>();
+
+const healthKey = (provider: string, accountId: string) => `${provider}\u0000${accountId}`;
+
+function isCooled(provider: string, accountId: string, now: number): boolean {
+  const entry = health.get(healthKey(provider, accountId));
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    health.delete(healthKey(provider, accountId));
+    return false;
+  }
+  return true;
+}
+
+/** True when this provider participates in generic rotation at all. */
+export function isGenericFailoverProvider(providerName: string, provider: OcxProviderConfig): boolean {
+  return provider.authMode === "oauth" && !EXCLUDED_PROVIDERS.has(providerName);
+}
+
+/**
+ * Stored accounts that could serve traffic if asked, ignoring cooldowns.
+ *
+ * Cooldowns are excluded on purpose: they are transient and per-request, while this answers the
+ * durable question "did the operator log in more than one account". Treating a cooled account as
+ * absent would switch the feature off for the rest of the cooldown, which is exactly when it is
+ * needed.
+ */
+function eligibleAccountCount(providerName: string, now: number): number {
+  const cached = presence.get(providerName);
+  if (cached && now >= cached.readAt && now - cached.readAt < PRESENCE_CACHE_TTL_MS) return cached.eligible;
+  const set = getAccountSet(providerName);
+  const eligible = set ? set.accounts.filter(account => account.needsReauth !== true).length : 0;
+  presence.set(providerName, { eligible, readAt: now });
+  return eligible;
+}
+
+/**
+ * Presence IS consent (#2568d).
+ *
+ * `hasKeyPoolFailover` already reads a 2+ key pool as the operator asking for rotation, and a
+ * second OAuth login is the same statement. One account stays a strict no-op either way, so this
+ * only changes behaviour for someone who deliberately logged in twice.
+ */
+export function hasFailoverAccountQuorum(providerName: string, now = Date.now()): boolean {
+  return eligibleAccountCount(providerName, now) >= 2;
+}
+
+/**
+ * Whether generic rotation is active for this provider.
+ *
+ * Precedence, most specific first:
+ *
+ *   1. `providers.<name>.oauthAccountFailover.enabled` — an operator may accept rotation on one
+ *      provider and refuse it on another, because provider terms differ.
+ *   2. `oauthAccountFailover.enabled` — the global switch. Anyone who already wrote `false` keeps
+ *      strict single-account behaviour across this change.
+ *   3. Presence: 2 or more eligible stored accounts (#2568d, owner decision).
+ *
+ * Only an explicit boolean overrides presence. A malformed value falls through instead of
+ * throwing, because a typo in a knob must not take a provider out of service.
+ */
+export function isGenericOAuthFailoverEnabled(
+  config: OcxConfig,
+  providerName: string,
+  now = Date.now(),
+): boolean {
+  const provider = config.providers?.[providerName];
+  if (!provider || !isGenericFailoverProvider(providerName, provider)) return false;
+  const perProvider = provider.oauthAccountFailover?.enabled;
+  if (typeof perProvider === "boolean") return perProvider;
+  const global = config.oauthAccountFailover?.enabled;
+  if (typeof global === "boolean") return global;
+  return hasFailoverAccountQuorum(providerName, now);
+}
+
+/** Accounts that may serve traffic right now: not cooled, not flagged for reauth. */
+export function eligibleFailoverAccounts(providerName: string, now = Date.now()): string[] {
+  const set = getAccountSet(providerName);
+  if (!set) return [];
+  return set.accounts
+    .filter(account => account.needsReauth !== true && !isCooled(providerName, account.id, now))
+    .map(account => account.id);
+}
+
+/**
+ * Cool the account that actually 429'd and name the next eligible one, or null.
+ *
+ * Returns the id only; the caller mints the credential so a failed refresh does not leave the
+ * cooldown applied to an account we then could not use.
+ */
+export function rotateGenericOAuthAccountOn429(
+  config: OcxConfig,
+  providerName: string,
+  failedAccountId: string,
+  retryAfterHeader: string | null | undefined,
+  now = Date.now(),
+): string | null {
+  if (!isGenericOAuthFailoverEnabled(config, providerName)) return null;
+  const set = getAccountSet(providerName);
+  // A single stored account has nowhere to go; rotating to itself would just replay the 429.
+  if (!set || set.accounts.length < 2) return null;
+
+  const parsed = parseRetryAfterMs(retryAfterHeader, now);
+  const cooldownMs = Math.min(parsed ?? DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS);
+  health.set(healthKey(providerName, failedAccountId), {
+    cooldownUntil: now + cooldownMs,
+    cooldownSource: parsed ? "retry-after" : "default",
+  });
+  sweepExpiredOnWrite(now);
+
+  const eligible = eligibleFailoverAccounts(providerName, now).filter(id => id !== failedAccountId);
+  if (eligible.length === 0) return null;
+  // A rotation means the roster in use just changed; do not answer the next activation question
+  // from a count read before the failure.
+  presence.delete(providerName);
+  // Deterministic: start after the failed account so repeated 429s walk the roster instead of
+  // hammering whichever id happens to sort first.
+  const order = set.accounts.map(account => account.id);
+  const start = order.indexOf(failedAccountId);
+  for (let i = 1; i <= order.length; i++) {
+    const candidate = order[(start + i) % order.length]!;
+    if (candidate !== failedAccountId && eligible.includes(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Full credential snapshot for a rotated account.
+ *
+ * Returns the snapshot rather than a bare bearer: Antigravity pairs an account-matched
+ * `projectId` with its token and Kiro carries routing metadata, so a token-only swap would mix
+ * one account's bearer with another's routing data.
+ */
+export async function failoverAccountSnapshot(
+  providerName: string,
+  accountId: string,
+): Promise<OAuthAccessSnapshot> {
+  return getValidAccessSnapshotForAccount(providerName, accountId);
+}
+
+/** Earliest remaining cooldown, for a client-facing Retry-After when every account is cooled. */
+export function genericFailoverRetryAfterSeconds(providerName: string, now = Date.now()): number | null {
+  const set = getAccountSet(providerName);
+  if (!set) return null;
+  let earliest: number | null = null;
+  for (const account of set.accounts) {
+    const entry = health.get(healthKey(providerName, account.id));
+    if (!entry || entry.cooldownUntil <= now) continue;
+    if (earliest === null || entry.cooldownUntil < earliest) earliest = entry.cooldownUntil;
+  }
+  return earliest === null ? null : Math.max(1, Math.ceil((earliest - now) / 1000));
+}
+
+/** Test seam and manual-recovery hook. */
+export function clearGenericFailoverHealth(providerName?: string): void {
+  if (!providerName) {
+    health.clear();
+    presence.clear();
+    return;
+  }
+  presence.delete(providerName);
+  for (const key of [...health.keys()]) {
+    if (key.startsWith(`${providerName}\u0000`)) health.delete(key);
+  }
+}

package/src/oauth/google-antigravity.ts

@@ -12,7 +12,7 @@
 import { OAuthCallbackFlow, type OAuthCallbackFlowOptions } from "./callback-server";
 import { generatePKCE } from "./pkce";
 import type { OAuthController, OAuthCredentials } from "./types";
-import { antigravityUserAgent, ANTIGRAVITY_GOOG_API_CLIENT_UA } from "../adapters/client-fingerprint";
+import { antigravityUserAgent, ANTIGRAVITY_IDE_VERSION } from "../adapters/client-fingerprint";
 
 const CLIENT_ID = process.env.GOOGLE_ANTIGRAVITY_CLIENT_ID
   || "1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com";
@@ -20,6 +20,7 @@ const CLIENT_SECRET = process.env.GOOGLE_ANTIGRAVITY_CLIENT_SECRET
   || "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";
 const AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
 const TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+const USERINFO_ENDPOINT = "https://www.googleapis.com/oauth2/v2/userinfo";
 const PROD_API = "https://cloudcode-pa.googleapis.com";
 const DAILY_API = "https://daily-cloudcode-pa.googleapis.com";
 const API_VERSION = "v1internal";
@@ -109,8 +110,13 @@ async function onboardProject(accessToken: string, signal?: AbortSignal): Promis
     if (signal?.aborted) throw signal.reason ?? new Error("Antigravity onboarding aborted");
     const response = await fetch(`${DAILY_API}/${API_VERSION}:onboardUser`, {
       method: "POST",
-      headers: { Authorization: `Bearer ${accessToken}`, Accept: "*/*", "Content-Type": "application/json", "User-Agent": antigravityUserAgent(), "x-goog-api-client": ANTIGRAVITY_GOOG_API_CLIENT_UA },
-      body: JSON.stringify({ tier_id: "free-tier", metadata: { ide_type: "ANTIGRAVITY", ide_name: "antigravity", ide_version: antigravityUserAgent() } }),
+      headers: { Authorization: `Bearer ${accessToken}`, Accept: "*/*", "Content-Type": "application/json", "User-Agent": antigravityUserAgent() },
+      // `ide_version` is a version, not a User-Agent. `antigravityUserAgent()` returns the whole
+      // header — `antigravity/ide/2.5.5 (aidev_client; os_type=...; arch=...)` — so onboarding was
+      // sending a parenthesized UA string in a field the real client fills with `2.5.5`. It is a
+      // fingerprint mismatch rather than a crash, which is why nothing failed: the request still
+      // succeeds, it just does not look like Antigravity.
+      body: JSON.stringify({ tier_id: "free-tier", metadata: { ide_type: "ANTIGRAVITY", ide_name: "antigravity", ide_version: ANTIGRAVITY_IDE_VERSION } }),
       signal: requestSignal(signal),
     });
     if (!response.ok) {
@@ -228,3 +234,29 @@ export async function refreshAntigravityToken(refreshToken: string, signal?: Abo
   const projectId = await discoverAntigravityProject(creds.access, signal).catch(() => undefined);
   return projectId ? { ...creds, projectId } : creds;
 }
+
+/**
+ * Refresh and derive import identity from Google's pinned userinfo endpoint. Imports may not
+ * borrow the email written in a local file: that would let one valid token overwrite another
+ * account's slot when a refresh response has no id_token.
+ */
+export async function validateAntigravityImportCredential(
+  refreshToken: string,
+  signal?: AbortSignal,
+): Promise<OAuthCredentials> {
+  const credential = await refreshAntigravityToken(refreshToken, signal);
+  const response = await fetch(USERINFO_ENDPOINT, {
+    method: "GET",
+    headers: { Accept: "application/json", Authorization: `Bearer ${credential.access}` },
+    signal: requestSignal(signal),
+  });
+  if (!response.ok) throw new Error(`Antigravity identity request failed: ${response.status}`);
+  const body = (await response.json().catch(() => undefined)) as { email?: unknown; id?: unknown } | undefined;
+  if (typeof body?.email !== "string" || body.email.length === 0) {
+    throw new Error("Antigravity identity response did not include an email");
+  }
+  if (typeof body.id !== "string" || body.id.length === 0) {
+    throw new Error("Antigravity identity response did not include an account id");
+  }
+  return { ...credential, accountId: body.id, email: body.email.toLowerCase() };
+}