@bitkyc08/opencodex 2.6.27-preview.20260705 → 2.6.30-preview.20260707

package/src/{service-secrets.ts → lib/service-secrets.ts}

@@ -1,5 +1,5 @@
 import { join } from "node:path";
-import { getConfigDir } from "./config";
+import { getConfigDir } from "../config";
 
 export function serviceApiTokenFilePath(): string {
   return join(getConfigDir(), "service-api-token");

package/src/oauth/anthropic.ts

@@ -137,8 +137,8 @@ export async function loginAnthropic(
     } else if (importLocal === "only") {
       throw new Error(
         process.platform === "darwin"
-          ? "No Claude Code token found in the keychain. Run 'ocx login anthropic' for browser OAuth."
-          : "Claude Code auto-import is macOS-only. Run 'ocx login anthropic' for browser OAuth.",
+          ? "No Claude Code token found (Keychain or ~/.claude/.credentials.json). Run 'ocx login anthropic' for browser OAuth."
+          : "No Claude Code token found (~/.claude/.credentials.json). Run 'ocx login anthropic' for browser OAuth.",
       );
     }
   }

package/src/oauth/callback-server.ts

@@ -8,7 +8,7 @@
  * Handles: port allocation (preferred → random fallback), callback server, CSRF state,
  * manual-input race, 300s timeout. Providers implement generateAuthUrl() + exchangeToken().
  */
-import { isAddrInUse } from "../ports";
+import { isAddrInUse } from "../server/ports";
 import type { OAuthController, OAuthCredentials } from "./types";
 
 const DEFAULT_TIMEOUT = 300_000;

package/src/oauth/google-antigravity.ts

@@ -154,8 +154,9 @@ function credentialsFromPayload(payload: GoogleTokenPayload, refreshFallback = "
 
 class AntigravityOAuthFlow extends OAuthCallbackFlow {
   #verifier = "";
+  #forceAccountSelect: boolean;
 
-  constructor(ctrl: OAuthController) {
+  constructor(ctrl: OAuthController, opts?: { forceAccountSelect?: boolean }) {
     super(ctrl, {
       preferredPort: CALLBACK_PORT,
       callbackPath: CALLBACK_PATH,
@@ -163,6 +164,7 @@ class AntigravityOAuthFlow extends OAuthCallbackFlow {
       callbackBindHostname: "127.0.0.1",
       redirectUri: `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`,
     } satisfies OAuthCallbackFlowOptions);
+    this.#forceAccountSelect = opts?.forceAccountSelect === true;
   }
 
   async generateAuthUrl(state: string, redirectUri: string): Promise<{ url: string; instructions?: string }> {
@@ -176,7 +178,8 @@ class AntigravityOAuthFlow extends OAuthCallbackFlow {
       code_challenge: pkce.challenge,
       code_challenge_method: "S256",
       access_type: "offline",
-      prompt: "consent",
+      // select_account lets the user pick a DIFFERENT Google account when adding a second one.
+      prompt: this.#forceAccountSelect ? "consent select_account" : "consent",
       state,
     });
     return {
@@ -207,8 +210,8 @@ class AntigravityOAuthFlow extends OAuthCallbackFlow {
   }
 }
 
-export async function loginAntigravity(ctrl: OAuthController): Promise<OAuthCredentials> {
-  return new AntigravityOAuthFlow(ctrl).login();
+export async function loginAntigravity(ctrl: OAuthController, opts?: { forceAccountSelect?: boolean }): Promise<OAuthCredentials> {
+  return new AntigravityOAuthFlow(ctrl, opts).login();
 }
 
 export async function refreshAntigravityToken(refreshToken: string, signal?: AbortSignal): Promise<OAuthCredentials> {

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/local-token-detect.ts

@@ -39,8 +39,14 @@ export function detectGrokCliToken(): OAuthCredentials | null {
   }
 }
 
-/** Read the Claude Code OAuth credential from macOS Keychain. Windows/Linux: use `ocx login`. */
-function readClaudeSecureStorage(): string | null {
+/** Claude Code config dir: `CLAUDE_CONFIG_DIR` override, else `~/.claude`. */
+function claudeConfigDir(): string {
+  const explicit = process.env.CLAUDE_CONFIG_DIR?.trim();
+  return explicit ? explicit : join(homedir(), ".claude");
+}
+
+/** Read the Claude Code OAuth credential from the macOS Keychain (darwin only). */
+function readClaudeKeychain(): string | null {
   if (process.platform !== "darwin") return null;
   try {
     return execSync(`security find-generic-password -s "${CLAUDE_KEYCHAIN_SERVICE}" -w`, {
@@ -51,9 +57,28 @@ function readClaudeSecureStorage(): string | null {
   }
 }
 
-export function detectClaudeCodeToken(): OAuthCredentials | null {
-  const raw = readClaudeSecureStorage();
-  if (!raw) return null;
+/**
+ * Read the Claude Code credential file (`<config-dir>/.credentials.json`).
+ * Claude Code writes this on Linux/Windows (and on macOS when the Keychain is
+ * unavailable); it carries the same `claudeAiOauth` payload as the Keychain item.
+ * Exported for tests.
+ */
+export function readClaudeCredentialsFile(): string | null {
+  const path = join(claudeConfigDir(), ".credentials.json");
+  try {
+    if (!existsSync(path)) return null;
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+/** Keychain first on macOS, then the cross-platform credentials file. */
+function readClaudeSecureStorage(): string | null {
+  return readClaudeKeychain() ?? readClaudeCredentialsFile();
+}
+
+export function parseClaudeOauthPayload(raw: string): OAuthCredentials | null {
   try {
     const data = JSON.parse(raw) as { claudeAiOauth?: { accessToken?: string; refreshToken?: string; expiresAt?: number } };
     const o = data.claudeAiOauth;
@@ -63,3 +88,9 @@ export function detectClaudeCodeToken(): OAuthCredentials | null {
     return null;
   }
 }
+
+export function detectClaudeCodeToken(): OAuthCredentials | null {
+  const raw = readClaudeSecureStorage();
+  if (!raw) return null;
+  return parseClaudeOauthPayload(raw);
+}

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