@bitkyc08/opencodex 2.6.26-preview.20260705 → 2.6.28-preview.20260707

package/src/oauth/index.ts

@@ -1,8 +1,8 @@
 import type { OAuthController, OAuthCredentials } from "./types";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { loadConfig, resolveEnvValue, saveConfig } from "../config";
-import { maskEmail } from "../privacy";
-import { getCredential, saveCredential } from "./store";
+import { maskEmail } from "../lib/privacy";
+import { getAccountCredential, getAccountSet, saveAccountCredential, saveCredential, markAccountNeedsReauth, getCredential } from "./store";
 import { loginXai, refreshXaiToken } from "./xai";
 import { ANTHROPIC_OAUTH_BETA, loginAnthropic, refreshAnthropicToken } from "./anthropic";
 import { loginKimi, refreshKimiToken } from "./kimi";
@@ -46,13 +46,14 @@ function oauthDefaultModel(id: string): string {
 
 export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
   xai: {
-    login: (ctrl) => loginXai(ctrl, { importLocal: "fallback" }),
+    // forceLogin skips the local grok-cli import so a SECOND account can be chosen in the browser.
+    login: (ctrl, opts) => loginXai(ctrl, { importLocal: opts?.forceLogin ? "off" : "fallback" }),
     refresh: refreshXaiToken,
     providerConfig: oauthConfig("xai"),
     defaultModel: oauthDefaultModel("xai"),
   },
   anthropic: {
-    login: (ctrl) => loginAnthropic(ctrl, { importLocal: "fallback" }),
+    login: (ctrl, opts) => loginAnthropic(ctrl, { importLocal: opts?.forceLogin ? "off" : "fallback" }),
     refresh: refreshAnthropicToken,
     providerConfig: oauthConfig("anthropic"),
     defaultModel: oauthDefaultModel("anthropic"),
@@ -73,7 +74,7 @@ export const OAUTH_PROVIDERS: Record<string, OAuthProviderDef> = {
     defaultModel: oauthDefaultModel("kiro"),
   },
   "google-antigravity": {
-    login: (ctrl) => loginAntigravity(ctrl),
+    login: (ctrl, opts) => loginAntigravity(ctrl, { forceAccountSelect: opts?.forceLogin === true }),
     refresh: refreshAntigravityToken,
     providerConfig: oauthConfig("google-antigravity"),
     defaultModel: oauthDefaultModel("google-antigravity"),
@@ -136,19 +137,33 @@ export class OAuthLoginRequiredError extends Error {
   }
 }
 
-/** Return a valid access token, refreshing + persisting if expired. Throws if not logged in. */
+/** Return a valid access token for the ACTIVE account, refreshing + persisting if expired. */
 export async function getValidAccessToken(provider: string): Promise<string> {
   const def = OAUTH_PROVIDERS[provider];
   if (!def) throw new UnsupportedOAuthProviderError(provider);
-  const cred = getCredential(provider);
+  const set = getAccountSet(provider);
+  if (!set) throw new OAuthLoginRequiredError(provider);
+  return getValidAccessTokenForAccount(provider, set.activeAccountId);
+}
+
+/**
+ * Account-scoped token resolver (multiauth): refresh is single-flighted per
+ * (provider, account), and the rotated credential is persisted for THAT account only —
+ * a guardian refresh of a background account never switches the active account.
+ */
+export async function getValidAccessTokenForAccount(provider: string, accountId: string): Promise<string> {
+  const def = OAUTH_PROVIDERS[provider];
+  if (!def) throw new UnsupportedOAuthProviderError(provider);
+  const cred = getAccountCredential(provider, accountId);
   if (!cred) throw new OAuthLoginRequiredError(provider);
   if (cred.expires > Date.now() + REFRESH_SKEW_MS) return cred.access;
-  const existing = tokenRefreshes.get(provider);
+  const key = `${provider}\u0000${accountId}`;
+  const existing = tokenRefreshes.get(key);
   if (existing) return existing;
-  const refresh = refreshAndPersistAccessToken(provider, def, cred).finally(() => {
-    if (tokenRefreshes.get(provider) === refresh) tokenRefreshes.delete(provider);
+  const refresh = refreshAndPersistAccessToken(provider, accountId, def, cred).finally(() => {
+    if (tokenRefreshes.get(key) === refresh) tokenRefreshes.delete(key);
   });
-  tokenRefreshes.set(provider, refresh);
+  tokenRefreshes.set(key, refresh);
   return refresh;
 }
 
@@ -158,12 +173,22 @@ function readFreshKiroCliCredential(): OAuthCredentials | undefined {
   return { access: imported.access, refresh: imported.refresh, expires: imported.expires, source: "local-cli" };
 }
 
+/** Terminal refresh failures (revoked/rotated-away grants) — retrying cannot succeed. */
+function isTerminalRefreshError(err: unknown): boolean {
+  const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+  return msg.includes("invalid_grant") || msg.includes("refresh_token_reused") || msg.includes("revoked");
+}
+
 async function refreshAndPersistAccessToken(
   provider: string,
+  accountId: string,
   def: OAuthProviderDef,
   cred: OAuthCredentials,
 ): Promise<string> {
-  if (provider === "kiro") {
+  // Local-CLI import fallback only for the ACTIVE account: importing another identity's
+  // token under a background account id would silently contaminate that account.
+  const isActive = getAccountSet(provider)?.activeAccountId === accountId;
+  if (provider === "kiro" && isActive) {
     const imported = readFreshKiroCliCredential();
     if (imported) {
       saveCredential(provider, imported);
@@ -172,22 +197,31 @@ async function refreshAndPersistAccessToken(
   }
   try {
     const fresh = await def.refresh(cred.refresh);
-    saveCredential(provider, {
+    // Persist to THIS account (rotation-safe: new refresh token hits disk before use) without
+    // touching activeAccountId.
+    saveAccountCredential(provider, accountId, {
       ...fresh,
       source: fresh.source ?? cred.source ?? "oauth",
       // Preserve a previously-discovered project id when a refresh-time re-discovery comes back empty
       // (e.g. a transient network blip), so Antigravity does not lose its CCA project across refresh.
       ...(fresh.projectId === undefined && cred.projectId ? { projectId: cred.projectId } : {}),
+      // Preserve identity fields the refresh response may omit, so identity matching stays stable.
+      ...(fresh.email === undefined && cred.email ? { email: cred.email } : {}),
+      ...(fresh.accountId === undefined && cred.accountId ? { accountId: cred.accountId } : {}),
     });
     return fresh.access;
   } catch (err) {
-    if (provider === "kiro") {
+    if (provider === "kiro" && isActive) {
       const imported = readFreshKiroCliCredential();
       if (imported) {
         saveCredential(provider, imported);
         return imported.access;
       }
     }
+    if (isTerminalRefreshError(err)) {
+      markAccountNeedsReauth(provider, accountId, true);
+      throw new OAuthLoginRequiredError(provider);
+    }
     throw err;
   }
 }
@@ -329,10 +363,27 @@ export async function runLogin(provider: string, ctrl: OAuthController, opts?: L
 const loginState = new Map<string, { error?: string; done: boolean }>();
 const loginAbort = new Map<string, AbortController>();
 
-export function getLoginStatus(provider: string): { loggedIn: boolean; email?: string; source?: OAuthCredentials["source"]; error?: string; done: boolean } {
+export interface OAuthAccountSummary { id: string; email?: string; active: boolean; needsReauth?: boolean; expiresAt?: number }
+
+export function getLoginStatus(provider: string): { loggedIn: boolean; email?: string; source?: OAuthCredentials["source"]; error?: string; done: boolean; activeAccountId?: string; accounts?: OAuthAccountSummary[] } {
   const cred = getCredential(provider);
   const st = loginState.get(provider);
-  return { loggedIn: !!cred, email: maskEmail(cred?.email) ?? undefined, source: cred?.source, error: st?.error, done: st?.done ?? false };
+  const set = getAccountSet(provider);
+  const accounts: OAuthAccountSummary[] | undefined = set?.accounts.map(a => ({
+    id: a.id,
+    email: maskEmail(a.credential.email) ?? undefined,
+    active: a.id === set.activeAccountId,
+    ...(a.needsReauth ? { needsReauth: true } : {}),
+    expiresAt: a.credential.expires,
+  }));
+  return {
+    loggedIn: !!cred,
+    email: maskEmail(cred?.email) ?? undefined,
+    source: cred?.source,
+    error: st?.error,
+    done: st?.done ?? false,
+    ...(set ? { activeAccountId: set.activeAccountId, accounts } : {}),
+  };
 }
 
 /** Token-safe per-provider login state for the CLI `ocx status` logins section (no tokens, masked email). */

package/src/oauth/login-cli.ts

@@ -1,7 +1,7 @@
 import * as readline from "node:readline";
-import { openUrl } from "../open-url";
+import { openUrl } from "../lib/open-url";
 import { loadConfig, saveConfig } from "../config";
-import { findLiveProxy, probeHostname } from "../proxy-liveness";
+import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
 import { OAUTH_PROVIDERS, runLogin } from "./index";
 import { KEY_LOGIN_PROVIDERS, isKeyLoginProvider, validateApiKey, type KeyLoginProvider } from "./key-providers";
 import type { OcxProviderConfig } from "../types";

package/src/oauth/store.ts

@@ -1,28 +1,51 @@
-/** OAuth token store at ~/.opencodex/auth.json, keyed by provider name. */
-import { existsSync, mkdirSync, readFileSync, chmodSync } from "node:fs";
+/**
+ * OAuth token store at ~/.opencodex/auth.json, keyed by provider name.
+ *
+ * Multiauth shape (260706): each provider value is a ProviderAccountSet
+ * `{ activeAccountId, accounts: [{ id, credential, needsReauth?, addedAt? }] }`.
+ * Legacy single-credential values (`{ access, refresh, expires, ... }`) normalize on load,
+ * and the first new-shape persist writes a one-time `auth.json.pre-multiauth` backup so a
+ * downgraded loader (which silently drops unknown shapes) cannot destroy refresh tokens.
+ *
+ * Exceptions:
+ * - `chatgpt` stays single-slot (always replaced): codex-auth-api uses it as a scratch slot
+ *   for Codex pool logins, which have their own ledger (codex-accounts.json).
+ * - Credentials without identity (no accountId/email — kimi, kiro, cursor) replace the
+ *   active slot instead of appending: their refresh tokens rotate, so a derived id would
+ *   duplicate the same human on every re-login.
+ */
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, chmodSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir, atomicWriteFile, backupInvalidConfig, hardenConfigDir, hardenExistingSecret } from "../config";
-import type { OAuthCredentialSource, OAuthCredentials } from "./types";
+import type { OAuthCredentialSource, OAuthCredentials, ProviderAccount, ProviderAccountSet } from "./types";
 
-type AuthStore = Record<string, OAuthCredentials>;
+type AuthStore = Record<string, ProviderAccountSet>;
+
+/** Providers whose account set is pinned to a single slot (see module doc). */
+const SINGLE_SLOT_PROVIDERS = new Set(["chatgpt"]);
 
 function authPath(): string {
   return join(getConfigDir(), "auth.json");
 }
 
-export function loadAuthStore(): AuthStore {
+function loadAuthStoreInternal(): { store: AuthStore; hadLegacy: boolean } {
   const path = authPath();
   hardenConfigDir();
   hardenExistingSecret(path);
-  if (!existsSync(path)) return {};
+  if (!existsSync(path)) return { store: {}, hadLegacy: false };
   try {
     return normalizeAuthStore(JSON.parse(readFileSync(path, "utf-8")));
   } catch {
     backupInvalidConfig(path);
-    return {};
+    return { store: {}, hadLegacy: false };
   }
 }
 
+export function loadAuthStore(): AuthStore {
+  return loadAuthStoreInternal().store;
+}
+
 function persist(store: AuthStore): void {
   const dir = getConfigDir();
   if (!existsSync(dir)) {
@@ -33,6 +56,22 @@ function persist(store: AuthStore): void {
   atomicWriteFile(authPath(), JSON.stringify(store, null, 2) + "\n");
 }
 
+/**
+ * One-time downgrade safety net: the first time we persist the NEW shape over a file that
+ * still contains legacy single-credential entries, keep a pristine copy. An older opencodex
+ * would silently drop the new shape (normalizeCredential -> null) and then persist an empty
+ * store, destroying refresh tokens; the backup makes that recoverable.
+ */
+function backupLegacyOnce(): void {
+  const path = authPath();
+  const backup = `${path}.pre-multiauth`;
+  if (!existsSync(path) || existsSync(backup)) return;
+  try {
+    copyFileSync(path, backup);
+    try { chmodSync(backup, 0o600); } catch { /* best-effort */ }
+  } catch { /* best-effort */ }
+}
+
 function isCredentialSource(value: unknown): value is OAuthCredentialSource {
   return value === "oauth" || value === "local-cli" || value === "credential-file" || value === "environment" || value === "manual";
 }
@@ -55,30 +94,207 @@ function normalizeCredential(cred: unknown): OAuthCredentials | null {
   return normalized;
 }
 
-function normalizeAuthStore(raw: unknown): AuthStore {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return {};
+/**
+ * Stable short account id. MUST be deterministic for a given credential: legacy
+ * single-credential stores are re-normalized on EVERY load without being persisted,
+ * so a time-salted id would differ between two loads (getAccountSet vs
+ * getAccountCredential), surfacing as a spurious OAuthLoginRequiredError and making
+ * refresh persists silently miss the account (rotated refresh token lost).
+ */
+function newAccountId(cred: OAuthCredentials): string {
+  const identity = cred.accountId ?? cred.email ?? cred.refresh;
+  return createHash("sha256").update(identity).digest("hex").slice(0, 8);
+}
+
+function normalizeAccount(value: unknown): ProviderAccount | null {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value as Partial<ProviderAccount>;
+  if (typeof candidate.id !== "string" || candidate.id.length === 0) return null;
+  const credential = normalizeCredential(candidate.credential);
+  if (!credential) return null;
+  const account: ProviderAccount = { id: candidate.id, credential };
+  if (candidate.needsReauth === true) account.needsReauth = true;
+  if (typeof candidate.addedAt === "number") account.addedAt = candidate.addedAt;
+  return account;
+}
+
+function normalizeAccountSet(raw: unknown): { set: ProviderAccountSet | null; wasLegacy: boolean } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { set: null, wasLegacy: false };
+  const candidate = raw as Partial<ProviderAccountSet>;
+  if (Array.isArray(candidate.accounts)) {
+    const accounts = candidate.accounts.map(normalizeAccount).filter((a): a is ProviderAccount => a !== null);
+    if (accounts.length === 0) return { set: null, wasLegacy: false };
+    const active = typeof candidate.activeAccountId === "string" && accounts.some(a => a.id === candidate.activeAccountId)
+      ? candidate.activeAccountId
+      : accounts[0]!.id;
+    return { set: { activeAccountId: active, accounts }, wasLegacy: false };
+  }
+  // Legacy single-credential value.
+  const cred = normalizeCredential(raw);
+  if (!cred) return { set: null, wasLegacy: false };
+  const id = newAccountId(cred);
+  return { set: { activeAccountId: id, accounts: [{ id, credential: cred }] }, wasLegacy: true };
+}
+
+function normalizeAuthStore(raw: unknown): { store: AuthStore; hadLegacy: boolean } {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return { store: {}, hadLegacy: false };
   const normalized: AuthStore = {};
-  for (const [provider, cred] of Object.entries(raw)) {
-    const safe = normalizeCredential(cred);
-    if (safe) normalized[provider] = safe;
+  let hadLegacy = false;
+  for (const [provider, value] of Object.entries(raw)) {
+    const { set, wasLegacy } = normalizeAccountSet(value);
+    if (set) normalized[provider] = set;
+    if (wasLegacy) hadLegacy = true;
   }
-  return normalized;
+  return { store: normalized, hadLegacy };
+}
+
+/**
+ * In-process write serialization: every mutation runs load-modify-persist under this queue so
+ * a guardian refresh persisting a non-active account cannot roll back a concurrent
+ * active-account switch (lost update). Cross-process races are accepted (single proxy).
+ */
+let writeQueue: Promise<unknown> = Promise.resolve();
+function enqueueWrite<T>(fn: () => T): T {
+  // Synchronous mutations: chain onto the queue for ordering, but run eagerly since all
+  // current callers are sync. The queue exists so future async mutators serialize too.
+  const result = fn();
+  writeQueue = writeQueue.then(() => result);
+  return result;
+}
+
+function mutateStore<T>(fn: (store: AuthStore) => T): T {
+  return enqueueWrite(() => {
+    const { store, hadLegacy } = loadAuthStoreInternal();
+    if (hadLegacy) backupLegacyOnce();
+    const result = fn(store);
+    persist(store);
+    return result;
+  });
 }
 
+/** The ACTIVE account's credential for a provider (what requests should use). */
 export function getCredential(provider: string): OAuthCredentials | null {
-  return loadAuthStore()[provider] ?? null;
+  const set = loadAuthStore()[provider];
+  if (!set) return null;
+  return set.accounts.find(a => a.id === set.activeAccountId)?.credential ?? null;
 }
 
+/**
+ * Persist a credential as the ACTIVE account. Identity-matching (accountId ?? email) upserts
+ * the same human's slot; a new identity appends a new account. Credentials without identity
+ * (rotating refresh tokens would fabricate duplicates) and single-slot providers replace the
+ * active slot / whole set instead.
+ */
 export function saveCredential(provider: string, cred: OAuthCredentials): void {
-  const store = loadAuthStore();
   const safe = normalizeCredential(cred);
   if (!safe) return;
-  store[provider] = safe;
-  persist(store);
+  mutateStore(store => {
+    const set = store[provider];
+    const identity = safe.accountId ?? safe.email;
+    if (!set || SINGLE_SLOT_PROVIDERS.has(provider)) {
+      const id = newAccountId(safe);
+      store[provider] = { activeAccountId: id, accounts: [{ id, credential: safe, addedAt: Date.now() }] };
+      return;
+    }
+    if (identity) {
+      const existing = set.accounts.find(a => (a.credential.accountId ?? a.credential.email) === identity);
+      if (existing) {
+        existing.credential = safe;
+        delete existing.needsReauth;
+        set.activeAccountId = existing.id;
+        return;
+      }
+      const id = newAccountId(safe);
+      set.accounts.push({ id, credential: safe, addedAt: Date.now() });
+      set.activeAccountId = id;
+      return;
+    }
+    // No identity: replace the active slot in place (single-account semantics).
+    const active = set.accounts.find(a => a.id === set.activeAccountId);
+    if (active) {
+      active.credential = safe;
+      delete active.needsReauth;
+    } else {
+      const id = newAccountId(safe);
+      set.accounts.push({ id, credential: safe, addedAt: Date.now() });
+      set.activeAccountId = id;
+    }
+  });
 }
 
+/** Remove the ACTIVE account; remaining accounts promote the first one. */
 export function removeCredential(provider: string): void {
-  const store = loadAuthStore();
-  delete store[provider];
-  persist(store);
+  mutateStore(store => {
+    const set = store[provider];
+    if (!set) return;
+    set.accounts = set.accounts.filter(a => a.id !== set.activeAccountId);
+    if (set.accounts.length === 0) {
+      delete store[provider];
+      return;
+    }
+    set.activeAccountId = set.accounts[0]!.id;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Multi-account API
+// ---------------------------------------------------------------------------
+
+export function getAccountSet(provider: string): ProviderAccountSet | null {
+  return loadAuthStore()[provider] ?? null;
+}
+
+export function listAccounts(provider: string): ProviderAccount[] {
+  return loadAuthStore()[provider]?.accounts ?? [];
+}
+
+export function getAccountCredential(provider: string, accountId: string): OAuthCredentials | null {
+  return loadAuthStore()[provider]?.accounts.find(a => a.id === accountId)?.credential ?? null;
+}
+
+/** Persist a refreshed credential for a SPECIFIC account without touching activeAccountId. */
+export function saveAccountCredential(provider: string, accountId: string, cred: OAuthCredentials): void {
+  const safe = normalizeCredential(cred);
+  if (!safe) return;
+  mutateStore(store => {
+    const account = store[provider]?.accounts.find(a => a.id === accountId);
+    if (!account) return;
+    account.credential = safe;
+    delete account.needsReauth;
+  });
+}
+
+export function setActiveAccount(provider: string, accountId: string): boolean {
+  return mutateStore(store => {
+    const set = store[provider];
+    if (!set || !set.accounts.some(a => a.id === accountId)) return false;
+    set.activeAccountId = accountId;
+    return true;
+  });
+}
+
+/** Remove one account by id; active removal promotes the first remaining account. */
+export function removeAccount(provider: string, accountId: string): boolean {
+  return mutateStore(store => {
+    const set = store[provider];
+    if (!set) return false;
+    const before = set.accounts.length;
+    set.accounts = set.accounts.filter(a => a.id !== accountId);
+    if (set.accounts.length === before) return false;
+    if (set.accounts.length === 0) {
+      delete store[provider];
+      return true;
+    }
+    if (set.activeAccountId === accountId) set.activeAccountId = set.accounts[0]!.id;
+    return true;
+  });
+}
+
+export function markAccountNeedsReauth(provider: string, accountId: string, needsReauth: boolean): void {
+  mutateStore(store => {
+    const account = store[provider]?.accounts.find(a => a.id === accountId);
+    if (!account) return;
+    if (needsReauth) account.needsReauth = true;
+    else delete account.needsReauth;
+  });
 }

package/src/oauth/token-guardian.ts

@@ -13,14 +13,14 @@
  */
 import { loadConfig } from "../config";
 import type { OcxConfig, OcxTokenGuardianConfig } from "../types";
-import { getCredential } from "./store";
-import { getValidAccessToken, listOAuthProviders, resolveRefreshPolicy } from "./index";
+import { listAccounts } from "./store";
+import { getValidAccessTokenForAccount, listOAuthProviders, OAuthLoginRequiredError, resolveRefreshPolicy } from "./index";
 import {
   getValidCodexToken,
   listCodexAccountIds,
   readCodexAccountRecord,
   TokenRefreshError,
-} from "../codex-account-store";
+} from "../codex/account-store";
 
 export interface TokenGuardianHandle {
   stop(): void;
@@ -113,25 +113,29 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
   const horizonMs = (opts.tickSeconds + opts.leadSeconds) * 1000;
   const tasks: Array<() => Promise<void>> = [];
 
-  // A) single-account OAuth providers
+  // A) OAuth providers — every account in each provider's set (multiauth keep-alive),
+  // skipping accounts already marked needsReauth (terminal; only a re-login fixes them).
   for (const provider of listOAuthProviders()) {
     if (resolveRefreshPolicy(provider, config) !== "proactive") continue;
-    const cred = getCredential(provider);
-    if (!cred) continue;
-    if (cred.expires > nowMs + horizonMs) continue;
-    const key = `oauth:${provider}`;
-    if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
-    tasks.push(async () => {
-      try {
-        await getValidAccessToken(provider);
-        backoff.delete(key);
-        result.refreshed.push(key);
-      } catch {
-        // Single-account refresh throws generic errors; treat as transient (exponential backoff).
-        recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, false);
-        result.failed.push(key);
-      }
-    });
+    for (const account of listAccounts(provider)) {
+      if (account.needsReauth) continue;
+      if (account.credential.expires > nowMs + horizonMs) continue;
+      const key = `oauth:${provider}:${account.id}`;
+      if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
+      tasks.push(async () => {
+        try {
+          await getValidAccessTokenForAccount(provider, account.id);
+          backoff.delete(key);
+          result.refreshed.push(key);
+        } catch (err) {
+          // Terminal grant failures surface as OAuthLoginRequiredError (account marked
+          // needsReauth by the resolver) — back off at the ceiling; transient errors backoff exponentially.
+          const permanent = err instanceof OAuthLoginRequiredError;
+          recordFailure(key, nowMs, opts.backoffBaseSeconds, opts.backoffMaxSeconds, permanent);
+          result.failed.push(key);
+        }
+      });
+    }
   }
 
   // B) multi-account Codex pool (gated on the chatgpt provider's policy)

package/src/oauth/types.ts

@@ -12,6 +12,22 @@ export type OAuthCredentials = {
   projectId?: string;
 };
 
+/** One logged-in account inside a provider's account set (multiauth). */
+export interface ProviderAccount {
+  /** Stable short id, generated once at append time; never re-derived after rotation. */
+  id: string;
+  credential: OAuthCredentials;
+  /** Terminal refresh failure (invalid_grant / reused / revoked) — re-login required. */
+  needsReauth?: boolean;
+  addedAt?: number;
+}
+
+/** auth.json value per provider: N accounts + which one requests use. */
+export interface ProviderAccountSet {
+  activeAccountId: string;
+  accounts: ProviderAccount[];
+}
+
 export interface OAuthController {
   onAuth?(info: { url: string; instructions?: string }): void;
   onProgress?(message: string): void;