@bitkyc08/opencodex 2.68.0 → 2.69.0

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

@@ -42,6 +42,7 @@ import { kiroEvidenceIdentity } from "../providers/kiro-account-state-disk";
 import { kiroAccountSupportsModel } from "../providers/kiro-model-catalog";
 import { ACCOUNT_QUOTA_TTL_MS } from "../providers/quota-wire";
 import { sweepExpiredOnWrite } from "../lib/state-store-sweeper";
+import { subscribeOAuthAccountPauseChanges } from "../lib/account-selection-events";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 
 /** Cap same-request rotations so a short Retry-After cannot spin. Mirrors the Anthropic bound. */
@@ -83,7 +84,7 @@ const EXCLUDED_PROVIDERS = new Set(["openai", "anthropic"]);
 
 interface AccountHealth {
   cooldownUntil: number;
-  cooldownSource: "retry-after" | "default" | "kiro-suspension";
+  cooldownSource: "retry-after" | "default" | "kiro-suspension" | "auth";
   identity?: string;
 }
 
@@ -98,6 +99,8 @@ const health = new Map<string, AccountHealth>();
 /** Provider -> recent eligible-account count. TTL-bounded; never holds credential material. */
 const presence = new Map<string, PresenceEntry>();
 
+subscribeOAuthAccountPauseChanges(provider => presence.delete(provider));
+
 const healthKey = (provider: string, accountId: string, family?: QuotaModelFamily) =>
   family ? `${provider}\u0000${accountId}\u0000${family}` : `${provider}\u0000${accountId}`;
 
@@ -114,6 +117,13 @@ export function quarantineKiroSuspendedAccount(accountId: string, generation?: s
 function isCooled(provider: string, accountId: string, now: number, family?: QuotaModelFamily): boolean {
   const entry = health.get(healthKey(provider, accountId, family));
   if (!entry) return false;
+  if (provider === "google-antigravity" && entry.cooldownSource === "auth") {
+    const live = getAccountSet(provider)?.accounts.find(row => row.id === accountId);
+    if (!live || entry.identity !== credentialGeneration(live.credential)) {
+      health.delete(healthKey(provider, accountId, family));
+      return false;
+    }
+  }
   if (provider === "kiro" && entry.cooldownSource === "kiro-suspension") {
     const live = getAccountSet("kiro")?.accounts.find(row => row.id === accountId);
     if (!live || entry.identity !== kiroEvidenceIdentity(live)) {
@@ -128,12 +138,13 @@ function isCooled(provider: string, accountId: string, now: number, family?: Quo
   return true;
 }
 
-export type KiroSkipReason = "needs_reauth" | "suspended" | "cooldown" | "quota_exhausted";
+export type KiroSkipReason = "paused" | "needs_reauth" | "suspended" | "cooldown" | "quota_exhausted";
 
 /** Eligibility for automatic alternatives; an active singleton can still send. */
 export function kiroAutoSelection(
   account: ProviderAccount, now = Date.now(),
 ): { autoSelectable: boolean; skipReason?: KiroSkipReason } {
+  if (account.paused === true) return { autoSelectable: false, skipReason: "paused" };
   if (account.needsReauth === true) return { autoSelectable: false, skipReason: "needs_reauth" };
   const cooled = isCooled("kiro", account.id, now);
   if (cooled && health.get(healthKey("kiro", account.id))?.cooldownSource === "kiro-suspension")
@@ -163,8 +174,10 @@ function eligibleAccountCount(providerName: string, now: number): number {
   const set = getAccountSet(providerName);
   // Kiro terminal refresh marks the just-refused account needsReauth before the alternate
   // selector runs. Both stored logins still express consent to recover through the survivor.
-  const eligible = set ? (providerName === "kiro" ? set.accounts.length
-    : set.accounts.filter(account => account.needsReauth !== true).length) : 0;
+  const eligible = set
+    ? set.accounts.filter(account => account.paused !== true
+      && (providerName === "kiro" || account.needsReauth !== true)).length
+    : 0;
   presence.set(providerName, { eligible, readAt: now });
   return eligible;
 }
@@ -260,8 +273,9 @@ function eligibleIdsIn(
 ): string[] {
   if (!set) return [];
   return set.accounts
-    .filter(account => providerName === "kiro" ? kiroAutoSelection(account, now).autoSelectable
-      : account.needsReauth !== true && !isCooled(providerName, account.id, now, family))
+    .filter(account => account.paused !== true
+      && (providerName === "kiro" ? kiroAutoSelection(account, now).autoSelectable
+        : account.needsReauth !== true && !isCooled(providerName, account.id, now, family)))
     .map(account => account.id);
 }
 
@@ -285,6 +299,34 @@ export function hasEligibleGenericOAuthFailoverTarget(
   return eligibleIdsIn(set, providerName, now, family).some(id => id !== failedAccountId);
 }
 
+/** Select a live Antigravity sibling using activation captured before the refused send. */
+export function rotateAntigravityAccountOnAuthRefusal(
+  poolActivated: boolean,
+  failedAccountId: string,
+  sentGeneration: string,
+  requestedModelId: string | null | undefined,
+  now = Date.now(),
+): string | null {
+  if (!poolActivated) return null;
+  const set = getAccountSet("google-antigravity");
+  if (!set || set.accounts.length < 2) return null;
+  const family = classifyModelFamilyForQuota("google-antigravity", requestedModelId);
+  const failed = set.accounts.find(row => row.id === failedAccountId);
+  if (failed && credentialGeneration(failed.credential) === sentGeneration) {
+    health.set(healthKey("google-antigravity", failedAccountId, family), {
+      cooldownUntil: now + DEFAULT_COOLDOWN_MS,
+      cooldownSource: "auth",
+      identity: sentGeneration,
+    });
+    sweepExpiredOnWrite(now);
+  }
+  const eligible = new Set(eligibleIdsIn(set, "google-antigravity", now, family));
+  const order = set.accounts.map(row => row.id);
+  const start = order.indexOf(failedAccountId);
+  const ring = start >= 0 ? [...order.slice(start + 1), ...order.slice(0, start)] : order;
+  return ring.find(id => id !== failedAccountId && eligible.has(id)) ?? null;
+}
+
 /** Generic pool strategies the kernel can actually run. `quota` IS the pre-kernel path. */
 type ActiveGenericStrategy = "round-robin" | "fill-first" | "least-loaded";
 
@@ -579,7 +621,9 @@ export function preferredInitialAccount(
   if (!selected) return null;
   const active = selected.activeAccountId;
   const accountRows = new Map(selected.accounts.map(account => [account.id, account]));
-  const order = selected.accounts.filter(account => account.needsReauth !== true).map(account => account.id);
+  const order = selected.accounts
+    .filter(account => account.paused !== true && account.needsReauth !== true)
+    .map(account => account.id);
   if (order.length < 2) return null;
 
   const modelEligible = preferKiroModelSupport(providerName,
@@ -629,7 +673,7 @@ export function preferredInitialAccount(
   }
 
   const activeRow = selected.accounts.find(account => account.id === active);
-  if (activeRow && activeRow.needsReauth !== true
+  if (activeRow && activeRow.paused !== true && activeRow.needsReauth !== true
     && !isCooled(providerName, activeRow.id, now, classifyModelFamilyForQuota(providerName, requestedModelId))
     && !isAccountQuotaExhausted(providerName, activeRow.id, requestedModelId, activeRow)) return null;
 

package/src/oauth/index.ts

@@ -108,6 +108,7 @@ export interface ObservedOAuthAccessSnapshot extends OAuthAccessSnapshot {
 
 export type OAuthActiveTokenObservation =
   | { readonly kind: "available"; readonly snapshot: ObservedOAuthAccessSnapshot }
+  | { readonly kind: "paused" }
   | { readonly kind: "missing" }
   | { readonly kind: "malformed" }
   | { readonly kind: "needs-reauth" }
@@ -418,6 +419,14 @@ export class OAuthLoginRequiredError extends Error {
   }
 }
 
+/** An operator-paused account is temporarily unavailable, not an invalid login. */
+export class OAuthAccountPausedError extends Error {
+  constructor() {
+    super("OAuth account is paused. Resume it in account settings and retry.");
+    this.name = "OAuthAccountPausedError";
+  }
+}
+
 export class OAuthProviderPublicationError extends Error {
   constructor() {
     super("OAuth credential was saved, but the provider entry was not written. Resolve the account namespace collision, then retry login.");
@@ -455,6 +464,7 @@ export function publicOAuthAuthenticationErrorMessage(error: unknown): string {
   }
   if (
     (error instanceof OAuthLoginRequiredError && isOAuthProvider(error.provider))
+    || error instanceof OAuthAccountPausedError
     || error instanceof OAuthProviderPublicationError
     // Reauth identity outcomes carry fixed, account-free remediation text. Dropping them to the
     // generic message hides WHICH failure the user must fix (sign in with the selected account).
@@ -466,7 +476,7 @@ export function publicOAuthAuthenticationErrorMessage(error: unknown): string {
   return "OAuth authentication failed. Check the OpenCodex account status and retry.";
 }
 
-function accessSnapshot(provider: string, accountId: string, cred: OAuthCredentials): OAuthAccessSnapshot {
+function accessSnapshot(provider: string, accountId: string, cred: OAuthCredentials, oauthProvider = provider): OAuthAccessSnapshot {
   // Derived, not read back: a stored `authType` is trusted when present, but a credential imported
   // before the field existed still routes correctly because the client pair implies SSO OIDC.
   const kiroAuthType = cred.kiro?.authType
@@ -484,9 +494,11 @@ function accessSnapshot(provider: string, accountId: string, cred: OAuthCredenti
   // Validated here, not at the call site: an unvalidated origin from a legacy or crafted
   // credential must never travel with a bearer, and dropping it makes the transport fall back to
   // the canonical host rather than to whatever the previous account was using.
-  const accountApiBaseUrl = provider === "github-copilot"
+  // The host rides on the OAuth definition the snapshot was resolved through, not the routed
+  // slot name: a custom provider reusing the Devin definition keeps its stored tenant URL.
+  const accountApiBaseUrl = oauthProvider === "github-copilot"
     ? validateCopilotApiBaseUrl(cred.apiBaseUrl)
-    : provider === "devin" || provider === "devin-cli"
+    : oauthProvider === "devin" || oauthProvider === "devin-cli"
       ? validateDevinApiBaseUrl(cred.apiBaseUrl)
       : undefined;
   return {
@@ -529,6 +541,7 @@ export function observeActiveOAuthAccessToken(
   const accountSet = authStore.store[provider];
   const account = accountSet?.accounts.find(candidate => candidate.id === accountSet.activeAccountId);
   if (!account) return { kind: "missing" };
+  if (account.paused === true) return { kind: "paused" };
   if (account.needsReauth) return { kind: "needs-reauth" };
   if (account.credential.expires <= now) return { kind: "expired" };
   if (account.credential.expires <= now + REFRESH_SKEW_MS) return { kind: "near-expiry" };
@@ -550,18 +563,20 @@ async function resolveAccessSnapshotForAccount(
   accountId: string,
   rejectedGeneration?: string,
   requireUsableAccount = false,
+  oauthProvider = provider,
 ): Promise<OAuthAccessSnapshot> {
-  const def = OAUTH_PROVIDERS[provider];
-  if (!def) throw new UnsupportedOAuthProviderError(provider);
+  const def = OAUTH_PROVIDERS[oauthProvider];
+  if (!def) throw new UnsupportedOAuthProviderError(oauthProvider);
   // One store read answers both questions. A caller that opts in gets the account REJECTED
   // when it needs reauthentication, which a bare credential read cannot detect: a revoked
   // account keeps a readable credential, so resolution would otherwise succeed and the
   // request would dispatch on an account already known to need a fresh login.
   const row = getAccountCredentialWithStatus(provider, accountId);
   if (!row) throw new OAuthLoginRequiredError(provider);
+  if (row.paused === true) throw new OAuthAccountPausedError();
   if (requireUsableAccount && row.needsReauth) throw new OAuthLoginRequiredError(provider);
   const cred = row.credential;
-  const current = accessSnapshot(provider, accountId, cred);
+  const current = accessSnapshot(provider, accountId, cred, oauthProvider);
   if (rejectedGeneration !== undefined && current.generation !== rejectedGeneration) return current;
   if (rejectedGeneration === undefined && cred.expires > Date.now() + REFRESH_SKEW_MS) return current;
 
@@ -590,12 +605,14 @@ async function resolveAccessSnapshotForAccount(
   };
   const refresh = (async (): Promise<OAuthAccessSnapshot> => {
     const accessToken = await refreshAndPersistAccessToken(provider, accountId, def, cred, abort.signal, flight, replacedStaleFlight);
-    const persisted = getAccountCredential(provider, accountId);
-    if (!persisted) throw new OAuthLoginRequiredError(provider);
+    const persistedRow = getAccountCredentialWithStatus(provider, accountId);
+    if (!persistedRow) throw new OAuthLoginRequiredError(provider);
+    if (persistedRow.paused === true) throw new OAuthAccountPausedError();
+    const persisted = persistedRow.credential;
     if (persisted.access !== accessToken) {
       throw new Error(`OAuth refresh persisted an unexpected access token for ${provider}`);
     }
-    return accessSnapshot(provider, accountId, persisted);
+    return accessSnapshot(provider, accountId, persisted, oauthProvider);
   })().catch(error => {
     if (abort.signal.reason instanceof OAuthTokenRefreshStaleError) throw abort.signal.reason;
     throw error;
@@ -607,10 +624,13 @@ async function resolveAccessSnapshotForAccount(
   return refresh;
 }
 
-export async function getValidAccessTokenSnapshot(provider: string): Promise<OAuthAccessSnapshot> {
+export async function getValidAccessTokenSnapshot(
+  provider: string,
+  options: { oauthProvider?: string } = {},
+): Promise<OAuthAccessSnapshot> {
   const set = getAccountSet(provider);
   if (!set) throw new OAuthLoginRequiredError(provider);
-  return resolveAccessSnapshotForAccount(provider, set.activeAccountId);
+  return resolveAccessSnapshotForAccount(provider, set.activeAccountId, undefined, false, options.oauthProvider);
 }
 
 /** Providers whose upstream-401 replay path may force a snapshot refresh. */
@@ -836,7 +856,7 @@ function merged(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCrede
     ...(fresh.kiro === undefined && previous.kiro ? { kiro: previous.kiro } : {}),
   };
 }
-export async function refreshXaiAccountWithLock(provider:string,accountId:string,def:OAuthProviderDef,callerCredential:OAuthCredentials,deps:XaiRefreshDeps={}):Promise<string>{const writerGeneration=captureConfigGeneration();const now=deps.now??Date.now;const guard=await(deps.intentLock??createOAuthRefreshIntentLock(provider,accountId)).acquire();try{const stored=getAccountCredential(provider,accountId);if(!stored)throw new OAuthLoginRequiredError(provider);const active=getAccountSet(provider)?.activeAccountId===accountId,candidate=authoritative(stored,active,now);if(credentialGeneration(candidate)!==credentialGeneration(callerCredential)&&candidate.expires>now()+REFRESH_SKEW_MS){if(credentialGeneration(candidate)!==credentialGeneration(stored)){const o=await mergeAccountCredential(provider,accountId,candidate,{expectedGeneration:credentialGeneration(stored),afterPrePersistRead:deps.afterPrePersistRead});if(o.superseded){if(o.stored.expires>now()+REFRESH_SKEW_MS)return o.stored.access;throw new OAuthLoginRequiredError(provider);}}return candidate.access;}if(cached(provider,accountId,candidate,now))throw new OAuthLoginRequiredError(provider);const generation=credentialGeneration(candidate);try{const fresh=merged(await def.refresh(candidate.refresh,deps.signal),candidate);const o=await mergeAccountCredential(provider,accountId,fresh,{expectedGeneration:generation,afterPrePersistRead:deps.afterPrePersistRead});if(o.superseded){if(o.stored.expires>now()+REFRESH_SKEW_MS)return o.stored.access;throw new OAuthLoginRequiredError(provider);}permanentRefreshFailures.delete(verdictKey(provider,accountId,candidate));if(candidate.source==="local-cli")console.warn(XAI_LOCAL_CLI_DETACH_WARNING);return fresh.access;}catch(error){if(error instanceof OAuthMutationBusyError){permanentRefreshFailures.delete(verdictKey(provider,accountId,candidate));throw error;}if(!terminal(error))throw error;const failedAt=now();permanentRefreshFailures.set(verdictKey(provider,accountId,candidate),failedAt+XAI_PERMANENT_FAILURE_TTL_MS);sweepExpiredOnWrite(failedAt);await markAccountNeedsReauthIfGeneration(provider,accountId,generation,writerGeneration);throw new OAuthLoginRequiredError(provider);}}finally{guard.release();}}
+export async function refreshXaiAccountWithLock(provider:string,accountId:string,def:OAuthProviderDef,callerCredential:OAuthCredentials,deps:XaiRefreshDeps={}):Promise<string>{const writerGeneration=captureConfigGeneration();const now=deps.now??Date.now;const guard=await(deps.intentLock??createOAuthRefreshIntentLock(provider,accountId)).acquire();try{const row=getAccountCredentialWithStatus(provider,accountId);if(!row)throw new OAuthLoginRequiredError(provider);if(row.paused)throw new OAuthAccountPausedError();const stored=row.credential;const active=getAccountSet(provider)?.activeAccountId===accountId,candidate=authoritative(stored,active,now);if(credentialGeneration(candidate)!==credentialGeneration(callerCredential)&&candidate.expires>now()+REFRESH_SKEW_MS){if(credentialGeneration(candidate)!==credentialGeneration(stored)){const o=await mergeAccountCredential(provider,accountId,candidate,{expectedGeneration:credentialGeneration(stored),afterPrePersistRead:deps.afterPrePersistRead});if(o.superseded){if(o.stored.expires>now()+REFRESH_SKEW_MS)return o.stored.access;throw new OAuthLoginRequiredError(provider);}}return candidate.access;}if(cached(provider,accountId,candidate,now))throw new OAuthLoginRequiredError(provider);const generation=credentialGeneration(candidate);try{const fresh=merged(await def.refresh(candidate.refresh,deps.signal),candidate);const o=await mergeAccountCredential(provider,accountId,fresh,{expectedGeneration:generation,afterPrePersistRead:deps.afterPrePersistRead});if(o.superseded){if(o.stored.expires>now()+REFRESH_SKEW_MS)return o.stored.access;throw new OAuthLoginRequiredError(provider);}permanentRefreshFailures.delete(verdictKey(provider,accountId,candidate));if(candidate.source==="local-cli")console.warn(XAI_LOCAL_CLI_DETACH_WARNING);return fresh.access;}catch(error){if(error instanceof OAuthMutationBusyError){permanentRefreshFailures.delete(verdictKey(provider,accountId,candidate));throw error;}if(!terminal(error))throw error;const failedAt=now();permanentRefreshFailures.set(verdictKey(provider,accountId,candidate),failedAt+XAI_PERMANENT_FAILURE_TTL_MS);sweepExpiredOnWrite(failedAt);await markAccountNeedsReauthIfGeneration(provider,accountId,generation,writerGeneration);throw new OAuthLoginRequiredError(provider);}}finally{guard.release();}}
 
 function newerClaudeCredential(stored: OAuthCredentials, now: number): OAuthCredentials | undefined {
   if (stored.source !== "local-cli") return undefined;
@@ -1018,8 +1038,11 @@ export async function refreshGenericAccountWithLock(
   logOAuthEvent("OAuth refresh started", { provider, accountId });
   const guard = await (deps.intentLock ?? createOAuthRefreshIntentLock(provider, accountId)).acquire();
   try {
-    const stored = getAccountCredential(provider, accountId);
-    if (!stored) throw new OAuthLoginRequiredError(provider);
+    // Re-read under the lock: a pause committed while this caller waited must stop the refresh.
+    const row = getAccountCredentialWithStatus(provider, accountId);
+    if (!row) throw new OAuthLoginRequiredError(provider);
+    if (row.paused) throw new OAuthAccountPausedError();
+    const stored = row.credential;
     if (
       credentialGeneration(stored) !== credentialGeneration(callerCredential)
       && stored.expires > Date.now() + REFRESH_SKEW_MS

package/src/oauth/store.ts

@@ -27,7 +27,7 @@ import { atomicWriteFileNoFollowUnclaimed } from "../config/atomic-write";
 import { assertNotRealHomeUnderTest } from "../lib/test-home-guard";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 import { MAX_PENDING_OAUTH_MUTATIONS } from "../lib/translator-budget";
-import { publishAccountSelection } from "../lib/account-selection-events";
+import { publishAccountSelection, publishOAuthAccountPauseChange } from "../lib/account-selection-events";
 import {
   captureConfigGeneration,
   type GenerationContext,
@@ -625,6 +625,7 @@ function normalizeAccount(value: unknown): ProviderAccount | null {
   const account: ProviderAccount = { id: candidate.id, credential };
   if (typeof candidate.alias === "string" && candidate.alias.trim()) account.alias = candidate.alias.trim();
   if (candidate.needsReauth === true) account.needsReauth = true;
+  if (candidate.paused === true) account.paused = true;
   if (typeof candidate.addedAt === "number") account.addedAt = candidate.addedAt;
   if (typeof candidate.loginId === "string"
     && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(candidate.loginId)) {
@@ -874,7 +875,7 @@ export async function saveCredentialWithReceipt(
       if (existing) {
         existing.credential = safe;
         delete existing.needsReauth;
-        set.activeAccountId = existing.id;
+        if (existing.paused !== true) set.activeAccountId = existing.id;
         accountId = existing.id;
       } else {
         // Legacy migration: a pre-identity row (no accountId/email) for this provider is the
@@ -912,6 +913,15 @@ export async function saveCredentialWithReceipt(
         accountId = id;
       }
     }
+    const updatedSet = store[provider];
+    const savedAccount = updatedSet?.accounts.find(account => account.id === accountId);
+    const activeAccount = updatedSet?.accounts.find(account => account.id === updatedSet.activeAccountId);
+    if (savedAccount?.paused === true
+      && (!activeAccount || activeAccount.paused === true || activeAccount.needsReauth === true)) {
+      const fallback = updatedSet.accounts.find(account => account.id !== accountId
+        && account.paused !== true && account.needsReauth !== true);
+      if (fallback) updatedSet.activeAccountId = fallback.id;
+    }
     // Every explicit login, including an in-place legacy slot upgrade, starts new evidence.
     store[provider]!.accounts.find(account => account.id === accountId)!.loginId = randomUUID();
     return {
@@ -1047,7 +1057,7 @@ export async function upsertCredentialByIdentity(
 }
 
 /**
- * Remove the ACTIVE account; remaining accounts promote the first one.
+ * Remove the ACTIVE account; promote the first usable survivor when available.
  *
  * Returns what actually happened, which a caller cannot otherwise know. A read-then-remove
  * preflight is not equivalent: `mutateStore` serializes mutations, so between a caller's
@@ -1064,7 +1074,8 @@ export async function removeCredential(provider: string): Promise<"removed" | "n
       delete store[provider];
       return "removed" as const;
     }
-    set.activeAccountId = set.accounts[0]!.id;
+    set.activeAccountId = set.accounts.find(account => account.paused !== true && account.needsReauth !== true)?.id
+      ?? set.accounts[0]!.id;
     return "removed" as const;
   }, [provider], { scrubLegacyBackup: result => result === "removed" ? [provider] : [] });
 }
@@ -1106,10 +1117,14 @@ export function getAccountCredential(provider: string, accountId: string): OAuth
 export function getAccountCredentialWithStatus(
   provider: string,
   accountId: string,
-): { credential: OAuthCredentials; needsReauth: boolean } | null {
+): { credential: OAuthCredentials; needsReauth: boolean; paused: boolean } | null {
   const account = loadAuthStore()[provider]?.accounts.find(a => a.id === accountId);
   if (!account?.credential) return null;
-  return { credential: account.credential, needsReauth: account.needsReauth === true };
+  return {
+    credential: account.credential,
+    needsReauth: account.needsReauth === true,
+    paused: account.paused === true,
+  };
 }
 
 /** Persist a refreshed credential for a SPECIFIC account without touching activeAccountId. */
@@ -1122,11 +1137,19 @@ export async function saveAccountCredential(
   const safe = normalizeCredential(cred);
   if (!safe) return;
   await mutateStore(store => {
-    const account = store[provider]?.accounts.find(a => a.id === accountId);
-    if (!account) return;
+    const set = store[provider];
+    const account = set?.accounts.find(a => a.id === accountId);
+    if (!set || !account) return;
     account.credential = safe;
     if (opts.rotateLoginId) account.loginId = randomUUID();
     delete account.needsReauth;
+    // A pause that found no usable fallback leaves the active id on a paused row. Once this
+    // reauthentication makes an unpaused account usable, hand the selection to it.
+    const active = set.accounts.find(a => a.id === set.activeAccountId);
+    if (active?.paused === true && account.paused !== true && account.id !== active.id) {
+      set.activeAccountId = account.id;
+      set.selectionRevision = randomUUID();
+    }
   }, [provider, accountId, safe], { assertBeforePersist: opts.assertBeforePersist });
 }
 
@@ -1162,7 +1185,7 @@ export async function commitOAuthAccountSelection(
   const valid = (set: ProviderAccountSet): boolean => {
     if (expected && (set.activeAccountId !== expected.accountId || set.selectionRevision !== expected.revision)) return false;
     const account = set.accounts.find(account => account.id === accountId);
-    if (!account || (requireUsableAccount && account.needsReauth === true)) return false;
+    if (!account || account.paused === true || (requireUsableAccount && account.needsReauth === true)) return false;
     return expectedCredentialGeneration === undefined || credentialGeneration(account.credential) === expectedCredentialGeneration;
   };
   if (expected?.accountId === accountId) {
@@ -1196,7 +1219,64 @@ export async function setAccountAlias(provider: string, accountId: string, alias
   }, [provider, accountId, alias]);
 }
 
-/** Remove one account by id; active removal promotes the first remaining account. */
+export type SetAccountPausedResult =
+  | { status: "updated"; activeAccountId: string; activeAccountChanged: boolean }
+  | { status: "unchanged"; activeAccountId: string; activeAccountChanged: boolean }
+  | { status: "not-found" };
+
+/** Persist an operator pause and move an active account to the next usable unpaused slot when available. */
+export async function setAccountPaused(
+  provider: string,
+  accountId: string,
+  paused: boolean,
+): Promise<SetAccountPausedResult> {
+  const result = await mutateStore(store => {
+    const set = store[provider];
+    const account = set?.accounts.find(candidate => candidate.id === accountId);
+    if (!set || !account) return { status: "not-found" } as const;
+    if ((account.paused === true) === paused) {
+      return { status: "unchanged", activeAccountId: set.activeAccountId, activeAccountChanged: false } as const;
+    }
+
+    if (paused) account.paused = true;
+    else delete account.paused;
+    // Pause is part of selection eligibility even when the operator changes a non-active
+    // account. Bump the provider selection revision so observers receive the existing
+    // post-persistence roster invalidation and stale automatic proposals cannot commit.
+    set.selectionRevision = randomUUID();
+
+    let activeAccountChanged = false;
+    if (paused && set.activeAccountId === accountId) {
+      const start = set.accounts.findIndex(candidate => candidate.id === accountId);
+      const ring = [...set.accounts.slice(start + 1), ...set.accounts.slice(0, start)];
+      const fallback = ring.find(candidate => candidate.paused !== true && candidate.needsReauth !== true);
+      if (fallback) {
+        set.activeAccountId = fallback.id;
+        set.selectionRevision = randomUUID();
+        activeAccountChanged = true;
+      }
+    } else if (!paused) {
+      // If all accounts had been paused, the active id still points at a paused
+      // slot. Resuming the first usable account must restore a usable selection.
+      const active = set.accounts.find(candidate => candidate.id === set.activeAccountId);
+      if ((!active || active.paused === true || active.needsReauth === true) && account.needsReauth !== true) {
+        set.activeAccountId = accountId;
+        set.selectionRevision = randomUUID();
+        activeAccountChanged = true;
+      }
+    }
+
+    return {
+      status: "updated",
+      activeAccountId: set.activeAccountId,
+      activeAccountChanged,
+    } as const;
+  }, [provider, accountId, paused]);
+  if (result.status === "updated") publishOAuthAccountPauseChange(provider);
+  return result;
+}
+
+/** Remove one account by id; active removal promotes the first usable survivor when available. */
 export async function removeAccount(provider: string, accountId: string): Promise<boolean> {
   const removed = await mutateStore(store => {
     const set = store[provider];
@@ -1208,7 +1288,11 @@ export async function removeAccount(provider: string, accountId: string): Promis
       delete store[provider];
       return true;
     }
-    if (set.activeAccountId === accountId) set.activeAccountId = set.accounts[0]!.id;
+    if (set.activeAccountId === accountId) {
+      const next = set.accounts.find(account => account.paused !== true && account.needsReauth !== true)
+        ?? set.accounts[0]!;
+      set.activeAccountId = next.id;
+    }
     return true;
   }, [provider, accountId], { scrubLegacyBackup: removed => removed ? [provider] : [] });
   return removed;
@@ -1238,6 +1322,7 @@ export async function replaceProviderAccountSet(
         credential: { ...account.credential, ...(account.credential.kiro ? { kiro: { ...account.credential.kiro } } : {}) },
         ...(account.alias ? { alias: account.alias } : {}),
         ...(account.needsReauth ? { needsReauth: true } : {}),
+        ...(account.paused ? { paused: true } : {}),
         ...(account.addedAt !== undefined ? { addedAt: account.addedAt } : {}),
         ...(account.loginId ? { loginId: account.loginId } : {}),
       })),

package/src/oauth/token-guardian.ts

@@ -14,7 +14,7 @@
 import { loadConfig } from "../config";
 import type { OcxConfig, OcxTokenGuardianConfig } from "../types";
 import { listAccounts } from "./store";
-import { getValidAccessTokenForAccount, listOAuthProviders, OAuthLoginRequiredError, resolveRefreshPolicy } from "./index";
+import { getValidAccessTokenForAccount, listOAuthProviders, OAuthAccountPausedError, OAuthLoginRequiredError, resolveRefreshPolicy } from "./index";
 import {
   getValidCodexToken,
   listCodexAccountIds,
@@ -141,11 +141,12 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
   const tasks: Array<() => Promise<void>> = [];
 
   // 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).
+  // skipping accounts already marked needsReauth (terminal; only a re-login fixes them) or
+  // paused by the operator (manual exclusion from all automatic account use).
   for (const provider of listOAuthProviders()) {
     if (resolveRefreshPolicy(provider, config) !== "proactive") continue;
     for (const account of listAccounts(provider)) {
-      if (account.needsReauth) continue;
+      if (account.needsReauth || account.paused) continue;
       if (account.credential.expires > nowMs + horizonMs) continue;
       const key = `oauth:${provider}:${account.id}`;
       if (inBackoff(key, nowMs)) { result.skippedBackoff.push(key); continue; }
@@ -155,6 +156,9 @@ export async function guardianSweep(nowMs: number = Date.now()): Promise<Guardia
           backoff.delete(key);
           result.refreshed.push(key);
         } catch (err) {
+          // The account may have been paused after this task was queued. It is no longer an
+          // automatic refresh failure and must not acquire retry backoff.
+          if (err instanceof OAuthAccountPausedError) return;
           // 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;

package/src/oauth/types.ts

@@ -88,6 +88,8 @@ export interface ProviderAccount {
   credential: OAuthCredentials;
   /** Terminal refresh failure (invalid_grant / reused / revoked) — re-login required. */
   needsReauth?: boolean;
+  /** Operator exclusion from generic OAuth account selection until explicitly resumed. */
+  paused?: boolean;
   addedAt?: number;
 }
 

package/src/plugins/loader.ts

@@ -81,10 +81,12 @@ export function macAclListingTrustError(listing: string, currentUser = userInfo(
     if (!entry) { unparseable = true; continue; }
     if (entry[2] === "deny") continue;
     const principal = entry[1]!;
-    // The file owner, this process's user, and root already control the path without an ACE.
-    // Require the `user:` prefix: a bare or group principal might include other users.
+    // The file owner and this process's user already control the path without an ACE. Require the
+    // `user:` prefix: a bare or group principal might include other users. macOS `ls` prints a
+    // resolved directory-record NAME here, so neither `0` nor `root` proves that the ACE is UID 0.
+    // On a genuinely root-owned path, `root` is still admitted by the owner comparison.
     if (principal.startsWith("user:")
-      && [owner, currentUser, "root", "0"].includes(principal.slice(5))) continue;
+      && [owner, currentUser].includes(principal.slice(5))) continue;
     const rights = entry[3]!.split(",");
     if (rights.includes("only_inherit")) continue;
     if (rights.some(right => !MAC_ACL_BENIGN_TOKENS.has(right))) return "has an access control list";

package/src/providers/fastwire.ts

@@ -340,6 +340,9 @@ export function createAdapterTierMetadata(
   const loggedWireValue = wireValue === null ? null : sanitizeLogMetadataString(wireValue);
   const outcome: AttemptTierOutcome = {
     wireKind,
+    ...(context.responseTierAuthoritative !== undefined
+      ? { responseTierAuthoritative: context.responseTierAuthoritative }
+      : {}),
     ...(wireValue === null
       ? { wireValue: null }
       : loggedWireValue ? { wireValue: loggedWireValue } : {}),

package/src/providers/key-failover.ts

@@ -12,7 +12,7 @@ import { commitProviderApiKeySelection } from "./api-key-selection";
 import type { ProviderApiKeySelection } from "../types/provider";
 import { routedProviderConfig } from "../router";
 import { getProviderRegistryEntry } from "./registry";
-import { normalizedBaseUrl } from "./quota/vendor-probes-key";
+import { isCanonicalCommandCodeBaseUrl, normalizedBaseUrl } from "./quota/vendor-probes-key";
 import type { OcxConfig, OcxProviderConfig, RateLimitRetryPolicy, ResetReplayPolicy, TransientRetryPolicy } from "../types";
 import { OPENCODE_GO_SESSION_HEADER } from "./opencode-go-transport";
 import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
@@ -566,7 +566,8 @@ export function selectProactiveApiKeyTransport(
  * `enabled: false` to opt out). When the knob is absent, the OpenCode Go destination
  * (subscription traffic such as Muse Spark) falls back to a patient same-key policy so a
  * burst 429 waits and replays instead of surfacing to the client and aborting a long
- * session; every other provider without the knob keeps today's fail-fast behavior.
+ * session; key-auth Command Code at its canonical endpoints gets the same fallback (#5180), and
+ * every other provider without the knob keeps today's fail-fast behavior.
  * OAuth/forward/local credentials are never replayed on the same token. The returned
  * policy is fully defaulted so callers never re-check fields.
  */
@@ -590,10 +591,17 @@ export function rateLimitRetryPolicyFor(
       respectRetryAfter: policy.respectRetryAfter ?? DEFAULT_RATE_LIMIT_RETRY.respectRetryAfter,
     };
   }
-  // No explicit knob: patient fallback for the OpenCode Go destination only.
+  // No explicit knob: patient fallback for OpenCode Go and canonical Command Code only.
   if (provider.authMode !== undefined && provider.authMode !== "key") return null;
-  if (!isOpenCodeGoDestination(provider)) return null;
-  return { ...OPENCODE_GO_RATE_LIMIT_RETRY };
+  if (isOpenCodeGoDestination(provider)) return { ...OPENCODE_GO_RATE_LIMIT_RETRY };
+  // Command Code's Provider API rate-limits long muse-spark turns the same way (#5180): a single
+  // key cannot fail over, and the Codex client does not retry a 429, so the turn aborts. The key
+  // endpoint gets the same patient same-key policy. A row repointed at a custom relay is not the
+  // canonical endpoint and keeps fail-fast unless it sets `retryOn429`.
+  if (typeof provider.baseUrl === "string" && isCanonicalCommandCodeBaseUrl(provider.baseUrl.trim())) {
+    return { ...OPENCODE_GO_RATE_LIMIT_RETRY };
+  }
+  return null;
 }
 
 /**

package/src/providers/kiro-model-catalog.ts

@@ -27,7 +27,8 @@ export function kiroModelDiscoveryEnabled(): boolean {
 }
 
 function liveAccount(accountId: string): ProviderAccount | undefined {
-  return getAccountSet("kiro")?.accounts.find(account => account.id === accountId && account.needsReauth !== true);
+  return getAccountSet("kiro")?.accounts.find(account => account.id === accountId
+    && account.needsReauth !== true && account.paused !== true);
 }
 
 function currentIdentity(accountId: string): string | undefined {
@@ -74,7 +75,7 @@ export function refreshKiroAccountModelsDetached(
   providerConfig: OcxProviderConfig,
   dependencies: ProviderOutboundDependencies = {},
 ): void {
-  if (!kiroModelDiscoveryEnabled() || account.needsReauth === true) return;
+  if (!kiroModelDiscoveryEnabled() || account.needsReauth === true || account.paused === true) return;
   const identity = kiroEvidenceIdentity(account);
   if (currentIdentity(account.id) !== identity) return;
   const old = validRow(account);
@@ -138,7 +139,7 @@ export function kiroAccountSupportsModel(accountId: string, model: string): bool
 export function kiroObservedContextWindow(model: string): number | undefined {
   const normalized = normalizeKiroModelId(model);
   if (normalized === "auto") return undefined;
-  const accounts = getAccountSet("kiro")?.accounts.filter(account => account.needsReauth !== true) ?? [];
+  const accounts = getAccountSet("kiro")?.accounts.filter(account => account.needsReauth !== true && account.paused !== true) ?? [];
   const limits: number[] = [];
   let unknown = accounts.length === 0;
   for (const account of accounts) {

package/src/providers/model-rename-fields.ts

@@ -16,6 +16,7 @@ export const PROVIDER_MODEL_RENAME_ROLES = {
   mcpMaxResultBytes: "none",
   modelAdapters: "record",
   fastWire: "none",
+  responseTierAuthoritative: "none",
   baseUrl: "none",
   responsesPath: "none",
   chatCompletionsPath: "none",

package/src/providers/openai-tiers-destination.ts

@@ -25,6 +25,15 @@ export function isCanonicalOpenAiForwardProvider(provider: OcxProviderConfig): b
     && normalizedBaseUrl(provider.baseUrl) === CODEX_FORWARD_BASE_URL;
 }
 
+/**
+ * Response evidence is separate from Fast capability and request serialization. Preserve the
+ * known Codex exception (#2558); other destinations may declare their response contract without
+ * a gateway-name or URL heuristic. Absence retains the authoritative legacy default.
+ */
+export function responseTierAuthorityForProvider(provider: OcxProviderConfig): boolean | undefined {
+  return isCanonicalOpenAiForwardProvider(provider) ? false : provider.responseTierAuthoritative;
+}
+
 const OPENAI_API_ORIGIN = "https://api.openai.com";
 const OPENAI_API_BASE_URL = `${OPENAI_API_ORIGIN}/v1`;
 const OPENAI_API_RESPONSES_URL = `${OPENAI_API_BASE_URL}/responses`;