@yansigit/opencodex 2.33.1 → 2.35.0

package/src/images/loop.ts

@@ -274,10 +274,11 @@ export interface ImageBridgeDeps {
   /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
   onUsage?: (usage: OcxUsage | undefined) => void;
   /**
-   * Optional 429 key-failover for the routed (non-xAI) model. Return a rebuilt adapter for the
-   * rotated key, or null when the pool is exhausted.
+   * Optional 429 failover for the routed (non-xAI) model. Return a rebuilt adapter for the
+   * rotated credential, or null when the pool is exhausted. Async hooks support OAuth refresh;
+   * existing synchronous key-pool hooks remain valid.
    */
-  on429?: (retryAfterHeader: string | null) => ProviderAdapter | null;
+  on429?: (retryAfterHeader: string | null) => ProviderAdapter | null | Promise<ProviderAdapter | null>;
   /** Opt-in same-target 429 policy (key-auth providers). When present, 429 replays on the SAME key before on429 rotation. */
   retryOn429Policy?: Required<RateLimitRetryPolicy> | null;
   /** Called when the bridged Responses stream completes (parity with runTurn / routed paths). */
@@ -592,7 +593,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       }
       // 429 key-failover parity with web-search / normal routed path.
       while (prepared.response.status === 429 && deps.on429) {
-        const rotated = deps.on429(prepared.response.headers.get("retry-after"));
+        const rotated = await deps.on429(prepared.response.headers.get("retry-after"));
         if (!rotated) break;
         try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
         adapter = rotated;

package/src/lab/conformance/fixtures/protocol-v1-cases.json

@@ -274,7 +274,7 @@
       "assertions": [
         { "id": "text", "operator": "normalized_text_equals", "selector": "/client/response/normalizedText", "expected": "OK", "required": true },
         { "id": "terminal", "operator": "terminal_signal_equals", "selector": "/client/response/terminal", "expected": "completed", "required": true },
-        { "id": "phase", "operator": "json_path_equals", "selector": "/client/response/events/6/data/item/phase", "expected": "final_answer", "required": true }
+        { "id": "phase", "operator": "json_path_equals", "selector": "/client/response/events/7/data/item/phase", "expected": "final_answer", "required": true }
       ]
     },
     {

package/src/lab/fabric/producer-child.ts

@@ -128,7 +128,7 @@ async function main(): Promise<void> {
   writeLine({ type: "result", patch });
 }
 
-main().catch((error: unknown) => {
+await main().catch((error: unknown) => {
   writeLine({
     type: "error",
     code: "harness_failure",

package/src/lib/config-ownership.ts

@@ -40,6 +40,7 @@ const INITIAL_OWNED_PATHS = [
   "artifacts",
   "auth.json",
   "auth.store.lock",
+  "admin-api-token",
   "catalog-backup.json",
   "claude-env.sh",
   "codex-accounts.json",
@@ -333,6 +334,25 @@ export function removeOwnedConfigState(configDir: string): ConfigRemovalResult {
     }
   }
 
+  // Per-catalog backups are named `catalog-backup-<16 hex>.json` (catalogBackupPathFor), one per
+  // CODEX_HOME, so they cannot be enumerated as literal manifest entries the way every other
+  // owned file can. Without this, `ocx uninstall` always reported "unowned files remain" and
+  // refused to remove a home OpenCodex created itself — the file is unambiguously ours, produced
+  // by our own writer, and the strict hex shape keeps the match from widening.
+  for (const name of readdirSync(configDir)) {
+    if (!/^catalog-backup-[0-9a-f]{16}\.json$/.test(name)) continue;
+    const path = join(configDir, name);
+    try {
+      removeOwnedEntry(rootPath, path);
+    } catch (error) {
+      return {
+        status: "partial",
+        reason: `could not remove owned path ${name}: ${error instanceof Error ? error.message : String(error)}`,
+        residualPaths: [path],
+      };
+    }
+  }
+
   try {
     unlinkSync(join(configDir, CONFIG_UNINSTALL_MANIFEST));
     unlinkSync(join(configDir, CONFIG_OWNER_FILE));

package/src/lib/errors.ts

@@ -16,11 +16,18 @@ export class OcxRequestValidationError extends Error {
 
 /** OpenAI / Codex hard block for high-risk cybersecurity activity (HTTP 400 or mid-stream). */
 export const CYBER_POLICY_ERROR_CODE = "cyber_policy";
+export const CYBER_POLICY_FALLBACK_MESSAGE = "Request blocked by the upstream cybersecurity policy.";
 
 export function isCyberPolicyCode(code: string | null | undefined): boolean {
   return code === CYBER_POLICY_ERROR_CODE;
 }
 
+/** Preserve a structured upstream error type; otherwise use the dedicated policy identity. */
+export function cyberPolicyErrorType(type: string | null | undefined): string {
+  const trimmed = typeof type === "string" ? type.trim() : "";
+  return trimmed || CYBER_POLICY_ERROR_CODE;
+}
+
 /**
  * Detect OpenAI cyber-policy refusals from message text when structured `code` was stripped.
  * Matches Codex fallback copy and Cursor/API agent wording (session evidence 2026-07-24).
@@ -149,9 +156,11 @@ export function classifyError(status: number, type: string, message: string): Oc
     return { message, type: "invalid_request_error", code: "client_closed_request" };
   }
   // Codex only shows the dedicated cyber UI when error.code === "cyber_policy".
-  // Prefer that code (and invalid_request_error) over generic remaps / 502 upstream_server_error.
+  // The public wire does not establish invalid_request_error as the canonical type, so
+  // message-only classification keeps the dedicated identity instead of inventing one.
+  // Structured callers re-apply their real upstream type with cyberPolicyErrorType().
   if (type === CYBER_POLICY_ERROR_CODE || isCyberPolicyMessage(text)) {
-    return { message, type: "invalid_request_error", code: CYBER_POLICY_ERROR_CODE };
+    return { message, type: CYBER_POLICY_ERROR_CODE, code: CYBER_POLICY_ERROR_CODE };
   }
   // A LOCAL preflight refusal keeps its own code (#1524). The message necessarily says
   // "context window" -- that is what it is refusing on -- so the generic remap below would

package/src/lib/package-tree-integrity.ts

@@ -0,0 +1,101 @@
+import { statSync } from "node:fs";
+
+export interface PackageTreeObservation {
+  readonly device: bigint;
+  readonly inode: bigint;
+  readonly contentTimeNs: bigint;
+  readonly size: bigint;
+}
+
+export type PackageTreeIntegrityStatus =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly reason: "package_tree_replaced" | "package_tree_unreadable" };
+
+export interface PackageTreeIntegrityGuard {
+  status(): PackageTreeIntegrityStatus;
+}
+
+type ObservePackageTree = () => PackageTreeObservation | null;
+type PackageTreeRuntimeInstall = "bun" | "npm" | "source";
+
+const packageManifestUrl = new URL("../../package.json", import.meta.url);
+
+function observePackageManifest(): PackageTreeObservation | null {
+  try {
+    const stat = statSync(packageManifestUrl, { bigint: true });
+    return {
+      device: stat.dev,
+      inode: stat.ino,
+      // mtimeNs, NOT ctimeNs. An inode-change time moves for METADATA writes that
+      // replace nothing: chmod, chown, touch, an editor normalizing permissions, a
+      // backup tool restoring modes. Each of those left device, inode and size
+      // identical, so the comparison below called the manifest "replaced" and every
+      // /v1/* request answered 503 until the process was restarted. Measured on
+      // macOS: chmod alone moved ctimeNs and left mtimeNs untouched.
+      //
+      // mtimeNs still catches every real replacement. An in-place rewrite of the
+      // same byte length moves mtimeNs while inode and size hold; an atomic
+      // install (write-then-rename, which is what a package manager does) changes
+      // the inode as well. Both were measured before this change was made.
+      contentTimeNs: stat.mtimeNs,
+      size: stat.size,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function sameObservation(left: PackageTreeObservation, right: PackageTreeObservation): boolean {
+  return left.device === right.device
+    && left.inode === right.inode
+    && left.contentTimeNs === right.contentTimeNs
+    && left.size === right.size;
+}
+
+/**
+ * How long an `ok` observation is reused before the manifest is stat'd again.
+ *
+ * `status()` runs on `/healthz`, `/readyz` and every `/v1/*` request, so an unthrottled guard
+ * adds a filesystem syscall to the proxy's hot path to detect an event that happens at most
+ * once per install. A replaced tree is not time-critical either: the process is already
+ * serving broken imports, and one more second of that is not worse than a syscall per turn
+ * forever.
+ *
+ * A NEGATIVE result is never cached — once the tree looks wrong, every later request re-checks,
+ * so a repaired install recovers on its own instead of staying refused for a window.
+ */
+const PACKAGE_TREE_RECHECK_MS = 1_000;
+
+export function createPackageTreeIntegrityGuard(
+  observe: ObservePackageTree = observePackageManifest,
+  now: () => number = Date.now,
+): PackageTreeIntegrityGuard {
+  const boot = observe();
+  let lastOkAt: number | null = null;
+  return {
+    status(): PackageTreeIntegrityStatus {
+      const at = now();
+      if (lastOkAt !== null && at - lastOkAt < PACKAGE_TREE_RECHECK_MS) return { ok: true };
+      const current = observe();
+      if (boot === null || current === null) return { ok: false, reason: "package_tree_unreadable" };
+      if (!sameObservation(boot, current)) return { ok: false, reason: "package_tree_replaced" };
+      lastOkAt = at;
+      return { ok: true };
+    },
+  };
+}
+
+/**
+ * Installed packages fail closed when their manifest is replaced under a live process.
+ * A source checkout is different: editing package.json is ordinary development work, and
+ * Bun keeps serving the module snapshot already loaded by this process until the operator
+ * chooses to restart. Fencing every request there makes running dev directly impossible.
+ */
+export function createRuntimePackageTreeIntegrityGuard(
+  installer: PackageTreeRuntimeInstall,
+  observe: ObservePackageTree = observePackageManifest,
+  now: () => number = Date.now,
+): PackageTreeIntegrityGuard {
+  if (installer === "source") return { status: () => ({ ok: true }) };
+  return createPackageTreeIntegrityGuard(observe, now);
+}

package/src/oauth/aistudio-credentials.ts

@@ -0,0 +1,65 @@
+import { createHash } from "node:crypto";
+import type { OcxProviderConfig } from "../types";
+import {
+  parseGoogleCookieJar,
+  validateAiStudioCookies,
+} from "./google-aistudio-auth";
+import {
+  cookieHeaderFromSession,
+  loadAiStudioSession,
+  type AiStudioSessionData,
+} from "./aistudio-session-sync";
+
+export type AiStudioCredentialResolution =
+  | { kind: "ready"; cookieHeader: string; source: "provider-api-key" | "provider-header" | "session"; fingerprint: string }
+  | { kind: "missing"; reason: string }
+  | { kind: "invalid"; reason: string };
+
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+
+function validCookieHeader(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const cookieHeader = value.trim();
+  if (!cookieHeader || CONTROL_CHARACTERS.test(cookieHeader)) return undefined;
+  const jar = parseGoogleCookieJar(cookieHeader);
+  return validateAiStudioCookies(jar).valid ? jar.cookieHeader : undefined;
+}
+
+function ready(cookieHeader: string, source: "provider-api-key" | "provider-header" | "session"): AiStudioCredentialResolution {
+  return {
+    kind: "ready",
+    cookieHeader,
+    source,
+    fingerprint: createHash("sha256").update(cookieHeader).digest("hex"),
+  };
+}
+
+export function resolveAiStudioCredentials(
+  provider: OcxProviderConfig,
+  session?: AiStudioSessionData | null,
+): AiStudioCredentialResolution {
+  const invalidSources: string[] = [];
+  const apiKey = validCookieHeader(provider.apiKey);
+  if (apiKey) return ready(apiKey, "provider-api-key");
+  if ((typeof provider.apiKey === "string" && provider.apiKey.trim())
+    || (provider.apiKey !== undefined && provider.apiKey !== null && typeof provider.apiKey !== "string")) {
+    invalidSources.push("provider apiKey");
+  }
+
+  const cookieEntry = Object.entries(provider.headers ?? {}).find(([name]) => name.toLowerCase() === "cookie");
+  const headerCookie = validCookieHeader(cookieEntry?.[1]);
+  if (headerCookie) return ready(headerCookie, "provider-header");
+  if ((typeof cookieEntry?.[1] === "string" && cookieEntry[1].trim())
+    || (cookieEntry !== undefined && typeof cookieEntry[1] !== "string")) {
+    invalidSources.push("provider Cookie header");
+  }
+
+  const savedSession = session === undefined ? loadAiStudioSession() : session;
+  const sessionCookie = validCookieHeader(cookieHeaderFromSession(savedSession));
+  if (sessionCookie) return ready(sessionCookie, "session");
+  if (savedSession) invalidSources.push("saved session");
+
+  return invalidSources.length > 0
+    ? { kind: "invalid", reason: "AI Studio credentials are malformed or missing SAPISID." }
+    : { kind: "missing", reason: "AI Studio credentials are missing." };
+}

package/src/oauth/aistudio-native-daemon.ts

@@ -1,6 +1,9 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { spawn, type ChildProcess } from "node:child_process";
+import { loadAiStudioSession, getAiStudioSessionPath } from "./aistudio-session-sync";
+import { resolveAiStudioCredentials } from "./aistudio-credentials";
+import type { OcxProviderConfig } from "../types";
 
 export function isNativeWebKitSupported(): boolean {
   return process.platform === "darwin";
@@ -30,6 +33,57 @@ export async function buildAiStudioNativeDaemon(outputPath?: string): Promise<st
   return dest;
 }
 
+type NativeLoginChild = { exited: Promise<number>; kill: () => void };
+type NativeLoginSpawn = (command: string[], options: { stdout: "pipe"; stderr: "pipe" }) => NativeLoginChild;
+
+export type AiStudioNativeLoginResult =
+  | { kind: "authenticated"; sessionPath: string }
+  | { kind: "cancelled" }
+  | { kind: "unsupported" }
+  | { kind: "failed"; error: string };
+
+export interface AiStudioNativeLoginOptions {
+  platform?: NodeJS.Platform;
+  sessionPath?: string;
+  signal?: AbortSignal;
+  /** Test-only process seam. Production always uses Bun.spawn. */
+  spawn?: NativeLoginSpawn;
+}
+
+/** Spawn one visible native login and report only after its session is durable and valid. */
+export async function runAiStudioNativeLogin(options: AiStudioNativeLoginOptions = {}): Promise<AiStudioNativeLoginResult> {
+  if ((options.platform ?? process.platform) !== "darwin") return { kind: "unsupported" };
+  const sessionPath = options.sessionPath ?? getAiStudioSessionPath();
+  const spawnLogin = options.spawn ?? ((command, spawnOptions) => Bun.spawn(command, spawnOptions) as unknown as NativeLoginChild);
+  let child: NativeLoginChild;
+  try {
+    child = spawnLogin(["swift", getAiStudioNativeDaemonSourcePath(), "--login"], { stdout: "pipe", stderr: "pipe" });
+  } catch (error) {
+    return { kind: "failed", error: `Could not start native AI Studio login: ${error instanceof Error ? error.message : String(error)}` };
+  }
+  let aborted = options.signal?.aborted === true;
+  const terminate = () => {
+    aborted = true;
+    try { child.kill(); } catch { /* already exited */ }
+  };
+  options.signal?.addEventListener("abort", terminate, { once: true });
+  try {
+    const exitCode = await child.exited;
+    if (aborted || options.signal?.aborted) return { kind: "cancelled" };
+    if (exitCode === 2) return { kind: "cancelled" };
+    if (exitCode !== 0) return { kind: "failed", error: `Native AI Studio login failed (exit code ${exitCode})` };
+    const session = loadAiStudioSession(sessionPath);
+    const credentials = resolveAiStudioCredentials({} as OcxProviderConfig, session);
+    return credentials.kind === "ready"
+      ? { kind: "authenticated", sessionPath }
+      : { kind: "failed", error: "Native login completed without a valid AI Studio session" };
+  } catch (error) {
+    return { kind: "failed", error: error instanceof Error ? error.message : String(error) };
+  } finally {
+    options.signal?.removeEventListener("abort", terminate);
+  }
+}
+
 export interface NativeDaemonHandle {
   process: ChildProcess;
   stop: () => void;

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);
+  }
+}