@bitkyc08/opencodex 2.7.30 → 2.7.33-preview.20260722

package/src/codex/routing.ts

@@ -25,14 +25,31 @@ export type CodexThreadResolution =
 const threadAccountMap = new Map<string, ThreadAffinityEntry>();
 type CodexUpstreamHealth = {
   consecutiveFailures: number;
+  /** Consecutive healthy terminals observed while recovering from escalation level 2+. */
+  consecutiveSuccesses?: number;
   lastFailureStatus?: number;
   lastFailureAt?: number;
+  /** Hard cooldown (quota 429). Survives a later 2xx; blocks auth + selection. */
   cooldownUntil?: number;
+  /**
+   * Soft avoid after connect_error / timeout / transient 5xx. Cleared on 2xx.
+   * Blocks pool selection + thread affinity reuse so a sticky session can leave a
+   * flaky account without throwing CodexAccountCooldownError (hard-only).
+   */
+  softAvoidUntil?: number;
 };
 
 const CODEX_DEFAULT_QUOTA_COOLDOWN_MS = 60_000;
 const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
 export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
+/** How long a transient failure keeps the account out of pool selection. */
+export const CODEX_TRANSIENT_SOFT_AVOID_MS = 30_000;
+const CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS = [
+  CODEX_TRANSIENT_SOFT_AVOID_MS,
+  2 * 60_000,
+  10 * 60_000,
+  30 * 60_000,
+] as const;
 export const CODEX_THREAD_AFFINITY_IDLE_TTL_MS = 24 * 60 * 60_000;
 export const CODEX_THREAD_AFFINITY_MAX_ENTRIES = 2048;
 // Min interval between quota threshold re-evaluations for a single bound thread.
@@ -47,6 +64,8 @@ export type CodexUpstreamOutcomeMeta = {
   retryAfter?: string | null;
   resetAt?: unknown | unknown[];
   now?: number;
+  /** When set, clears affinity for this thread immediately on transient failure. */
+  threadId?: string | null;
 };
 
 function hasConfiguredPoolAccount(config: OcxConfig, accountId: string): boolean {
@@ -162,8 +181,21 @@ export function isCodexAccountInCooldown(accountId: string, now = Date.now()): b
   return getCodexAccountCooldownUntil(accountId, now) !== null;
 }
 
+export function getCodexAccountSoftAvoidUntil(accountId: string, now = Date.now()): number | null {
+  const softAvoidUntil = upstreamHealth.get(accountId)?.softAvoidUntil;
+  return typeof softAvoidUntil === "number" && Number.isFinite(softAvoidUntil) && softAvoidUntil > now
+    ? softAvoidUntil
+    : null;
+}
+
+export function isCodexAccountSoftAvoided(accountId: string, now = Date.now()): boolean {
+  return getCodexAccountSoftAvoidUntil(accountId, now) !== null;
+}
+
 function isCodexAccountSelectable(config: OcxConfig, accountId: string, now: number): boolean {
-  return !isCodexAccountInCooldown(accountId, now) && isCodexAccountUsable(config, accountId);
+  return !isCodexAccountInCooldown(accountId, now)
+    && !isCodexAccountSoftAvoided(accountId, now)
+    && isCodexAccountUsable(config, accountId);
 }
 
 function isThreadAffinityExpired(entry: ThreadAffinityEntry, now: number): boolean {
@@ -215,6 +247,7 @@ function getEligiblePoolAccounts(config: OcxConfig, excludeId?: string, now = Da
   const ids = (config.codexAccounts ?? [])
     .filter(account => !account.isMain && account.id !== excludeId && !isAccountNeedsReauth(account.id))
     .filter(account => !isCodexAccountInCooldown(account.id, now))
+    .filter(account => !isCodexAccountSoftAvoided(account.id, now))
     .filter(account => isCodexAccountUsable(config, account.id))
     .map(account => account.id);
   // The main Codex account is not stored in config.codexAccounts; include it as a
@@ -223,6 +256,7 @@ function getEligiblePoolAccounts(config: OcxConfig, excludeId?: string, now = Da
     excludeId !== MAIN_CODEX_ACCOUNT_ID
     && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)
     && !isCodexAccountInCooldown(MAIN_CODEX_ACCOUNT_ID, now)
+    && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
     && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID)
   ) {
     ids.unshift(MAIN_CODEX_ACCOUNT_ID);
@@ -352,6 +386,9 @@ export function resolveCodexAccountForThreadDetailed(
     if (
       isThreadAffinityGenerationLive(entry)
       && isCodexAccountSelectable(config, entry.accountId, now)
+      // Affined threads must leave a failing account once the streak trips failover
+      // (soft-avoid covers the first-hit case; this catches post-avoid residual streaks).
+      && !shouldFailover(config, entry.accountId, now)
     ) {
       entry.lastUsedAt = now;
       // Periodic quota re-eval: a long-lived bound thread must still switch when
@@ -420,7 +457,22 @@ export function recordCodexUpstreamOutcome(
   const now = meta.now ?? Date.now();
   const outcomeClass = classifyCodexUpstreamOutcome(outcome);
   if (outcomeClass === "success") {
+    const current = upstreamHealth.get(accountId);
     const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
+    const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
+    if (failoverEnabled && current && current.consecutiveFailures >= 2) {
+      const consecutiveSuccesses = (current.consecutiveSuccesses ?? 0) + 1;
+      if (consecutiveSuccesses < 2) {
+        upstreamHealth.set(accountId, {
+          ...current,
+          consecutiveSuccesses,
+          ...(cooldownUntil ? { cooldownUntil } : {}),
+        });
+        return;
+      }
+    }
+    // Level 1 clears immediately; escalated accounts need two consecutive healthy terminals.
+    // Hard quota cooldown intentionally survives either recovery path.
     if (cooldownUntil) upstreamHealth.set(accountId, { consecutiveFailures: 0, cooldownUntil });
     else upstreamHealth.delete(accountId);
     return;
@@ -454,15 +506,44 @@ export function recordCodexUpstreamOutcome(
     return;
   }
 
+  // transient (connect_error / timeout / 5xx)
   const current = upstreamHealth.get(accountId);
   const stale = current?.lastFailureAt ? now - current.lastFailureAt > CODEX_FAILURE_WINDOW_MS : false;
-  const cooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
+  const hardCooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
+  // Soft avoid + affinity clears are part of failover. When threshold is 0, leave
+  // sticky sessions alone (same as shouldFailover / applyFailureFailover no-ops).
+  const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
+  const consecutiveFailures = stale ? 1 : (current?.consecutiveFailures ?? 0) + 1;
+  const escalationMs = CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS[
+    Math.min(consecutiveFailures, CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS.length) - 1
+  ]!;
+  const softAvoidUntil = failoverEnabled
+    ? Math.max(
+      getCodexAccountSoftAvoidUntil(accountId, now) ?? 0,
+      now + escalationMs,
+    )
+    : undefined;
   upstreamHealth.set(accountId, {
-    consecutiveFailures: stale ? 1 : (current?.consecutiveFailures ?? 0) + 1,
+    consecutiveFailures,
     lastFailureStatus,
     lastFailureAt: now,
-    ...(cooldownUntil ? { cooldownUntil } : {}),
+    ...(hardCooldownUntil ? { cooldownUntil: hardCooldownUntil } : {}),
+    ...(softAvoidUntil !== undefined ? { softAvoidUntil } : {}),
   });
+  // Drop this thread's pin immediately so the next continue can rebind without
+  // waiting for the soft-avoid selectable check. Guard: only delete when the
+  // thread is still pinned to the FAILING account — a late failure from account A
+  // must not delete a newer healthy binding to account B (race: T→A, A fails,
+  // T→B, late A failure must not delete B's mapping).
+  if (failoverEnabled && meta.threadId) {
+    const bound = threadAccountMap.get(meta.threadId);
+    if (bound?.accountId === accountId) threadAccountMap.delete(meta.threadId);
+  }
+  // Once the account is past the failover streak, clear every thread still pinned
+  // to it — matching 429 affinity behavior so "continue" cannot stay on a bad peer.
+  if (shouldFailover(config, accountId, now)) {
+    clearThreadAccountMapForAccount(accountId);
+  }
   if (config.activeCodexAccountId === accountId) applyFailureFailover(config, accountId, now);
 }
 

package/src/combos/index.ts

@@ -1,5 +1,4 @@
 export {
-  COMBO_DEFAULT_EFFORT,
   COMBO_NAMESPACE,
   comboConfigError,
   comboConfigIssues,
@@ -34,4 +33,5 @@ export {
 export {
   comboIdFromRawBody,
   concreteComboRequestBody,
+  resetComboEffortWarningStateForTests,
 } from "./request";

package/src/combos/request.ts

@@ -1,6 +1,12 @@
 import type { OcxComboDefaultEffort, OcxComboTarget } from "../types";
 import { parseComboModelId } from "./types";
 
+const warnedUnsupportedDefaults = new Set<string>();
+
+export function resetComboEffortWarningStateForTests(): void {
+  warnedUnsupportedDefaults.clear();
+}
+
 export function comboIdFromRawBody(body: unknown): string | null {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const model = (body as { model?: unknown }).model;
@@ -12,19 +18,35 @@ export function concreteComboRequestBody(
   body: unknown,
   target: Pick<OcxComboTarget, "provider" | "model">,
   defaultEffort: OcxComboDefaultEffort | null,
+  targetReasoningEfforts: readonly string[] | undefined,
 ): Record<string, unknown> {
   const clone = structuredClone(body) as Record<string, unknown>;
   clone.model = `${target.provider}/${target.model}`;
   if (!defaultEffort) return clone;
   const reasoning = clone.reasoning;
-  if (reasoning === undefined) {
-    clone.reasoning = { effort: defaultEffort };
-  } else if (
+  const needsDefault = reasoning === undefined || (
     reasoning
     && typeof reasoning === "object"
     && !Array.isArray(reasoning)
     && !Object.prototype.hasOwnProperty.call(reasoning, "effort")
-  ) {
+  );
+  if (!needsDefault) return clone;
+  if (!targetReasoningEfforts?.includes(defaultEffort)) {
+    const key = `${target.provider}/${target.model}:${defaultEffort}`;
+    if (!warnedUnsupportedDefaults.has(key)) {
+      warnedUnsupportedDefaults.add(key);
+      console.debug("[opencodex] combo default effort omitted", {
+        provider: target.provider,
+        model: target.model,
+        requestedEffort: defaultEffort,
+        capability: targetReasoningEfforts === undefined ? "unknown" : "unsupported",
+      });
+    }
+    return clone;
+  }
+  if (reasoning === undefined) {
+    clone.reasoning = { effort: defaultEffort };
+  } else {
     clone.reasoning = { ...(reasoning as Record<string, unknown>), effort: defaultEffort };
   }
   return clone;

package/src/combos/types.ts

@@ -8,7 +8,6 @@ import type {
 } from "../types";
 
 export const COMBO_NAMESPACE = "combo";
-export const COMBO_DEFAULT_EFFORT: OcxComboDefaultEffort = "medium";
 const COMBO_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 
 export interface ComboValidationIssue {
@@ -19,7 +18,7 @@ export interface ComboValidationIssue {
 export interface NormalizedComboConfig {
   strategy: OcxComboStrategy;
   stickyLimit: number;
-  defaultEffort: OcxComboDefaultEffort;
+  defaultEffort: OcxComboDefaultEffort | null;
   targets: Array<Required<OcxComboTarget>>;
 }
 
@@ -81,6 +80,7 @@ export function comboConfigIssues(
     issues.push({ path: ["stickyLimit"], message: "stickyLimit must be an integer from 1 to 100" });
   }
   if (body.defaultEffort !== undefined
+    && body.defaultEffort !== null
     && (typeof body.defaultEffort !== "string" || !isCodexReasoningEffort(body.defaultEffort))) {
     issues.push({
       path: ["defaultEffort"],
@@ -164,7 +164,7 @@ export function normalizeComboConfig(raw: OcxComboConfig): NormalizedComboConfig
   return {
     strategy: raw.strategy ?? "failover",
     stickyLimit: raw.stickyLimit ?? 1,
-    defaultEffort: raw.defaultEffort ?? COMBO_DEFAULT_EFFORT,
+    defaultEffort: raw.defaultEffort ?? null,
     targets: raw.targets.map(target => ({
       provider: target.provider.trim(),
       model: target.model.trim(),
@@ -179,7 +179,7 @@ export function comboDefaultEffort(
 ): OcxComboDefaultEffort | null {
   const combos = config.combos;
   if (!combos || !Object.hasOwn(combos, id)) return null;
-  const value: unknown = combos[id]!.defaultEffort ?? COMBO_DEFAULT_EFFORT;
+  const value: unknown = combos[id]!.defaultEffort ?? null;
   return typeof value === "string" && isCodexReasoningEffort(value)
     ? value as OcxComboDefaultEffort
     : null;

package/src/config.ts

@@ -6,7 +6,8 @@ import * as z from "zod/v4";
 import { comboConfigIssues } from "./combos/types";
 import { hardenSecretDir, hardenSecretPath } from "./lib/windows-secret-acl";
 import { providerDestinationConfigError } from "./lib/destination-policy";
-import type { OcxConfig } from "./types";
+import { openRouterRoutingConfigError } from "./providers/openrouter-routing";
+import { OPENAI_PROVIDER_TIER_VERSION, type OcxConfig } from "./types";
 
 let _atomicSeq = 0;
 
@@ -155,6 +156,28 @@ function isAlreadyExistsError(error: unknown): boolean {
   return (error as NodeJS.ErrnoException | undefined)?.code === "EEXIST";
 }
 
+/**
+ * Classify an existing `.pre-openai-tiers-v2.bak` snapshot.
+ *
+ * - `"stale"`: unparseable JSON (not written by us / truncated) or already a
+ *   post-migration (tier v2) snapshot — safe to delete or replace.
+ * - `"rollback"`: parses as a valid pre-migration (v1) config — a
+ *   user-intentional rollback point that must never be silently destroyed.
+ *
+ * Shared by the startup migration backup path and `ocx init` cleanup so both
+ * apply the same preservation policy (issue #257 / sol review 260722).
+ */
+export function classifyOpenAiTierBackup(backupBytes: Uint8Array): "stale" | "rollback" {
+  try {
+    // Use Buffer.from to ensure proper UTF-8 decoding from Uint8Array/Buffer.
+    const parsed = JSON.parse(Buffer.from(backupBytes).toString("utf8")) as Record<string, unknown>;
+    return parsed.openaiProviderTierVersion === 2 ? "stale" : "rollback";
+  } catch {
+    // Unparseable: not a config file we created, treat as stale.
+    return "stale";
+  }
+}
+
 export function backupConfigBeforeOpenAiTierMigration(
   configPath = getConfigPath(),
   io: OpenAiTierBackupIO = {
@@ -178,8 +201,24 @@ export function backupConfigBeforeOpenAiTierMigration(
   // docs/fixtures and is never reused or overwritten as the v2 snapshot.
   const backup = `${source}.pre-openai-tiers-v2.bak`;
   if (io.exists(backup)) {
-    if (!sameBytes(original, io.read(backup))) throw new OpenAiTierBackupCollisionError();
-    return "reused";
+    if (!sameBytes(original, io.read(backup))) {
+      // The backup differs from the current config. Only treat it as stale when it is
+      // clearly not a user-intentional rollback point:
+      //   - unparseable JSON: written by a different tool or truncated
+      //   - already at tier version 2: the backup is from a post-migration config (e.g.
+      //     ocx init wrote a fresh v2 config, making the old backup obsolete)
+      // A backup that parses as a valid pre-migration (v1) config is kept as-is and
+      // we throw a collision error, because silently replacing a user-created rollback
+      // point would be surprising and potentially destructive.
+      const backupBytes = io.read(backup);
+      if (classifyOpenAiTierBackup(backupBytes) === "rollback") {
+        throw new OpenAiTierBackupCollisionError();
+      }
+      console.warn("[openai-provider-migration] Replacing stale pre-migration backup (post-migration config was rewritten since last migration).");
+      io.unlink(backup);
+    } else {
+      return "reused";
+    }
   }
   const temp = `${backup}.ocx.${process.pid}.${++_atomicSeq}.tmp`;
   let published = false;
@@ -374,6 +413,20 @@ const configSchema = z.object({
       });
     }
     const provider = config.providers[name];
+    const openRouterRoutingError = openRouterRoutingConfigError(provider);
+    if (openRouterRoutingError) {
+      ctx.addIssue({
+        code: "custom",
+        path: [
+          "providers",
+          name,
+          openRouterRoutingError.startsWith("modelOpenRouterRouting")
+            ? "modelOpenRouterRouting"
+            : "openRouterRouting",
+        ],
+        message: openRouterRoutingError,
+      });
+    }
     if (Object.hasOwn(provider, "virtualModels")) {
       ctx.addIssue({
         code: "custom",
@@ -641,6 +694,10 @@ export function getDefaultConfig(): OcxConfig {
   // Adding extra providers (e.g. opencode-go) and switching defaultProvider is a user/runtime choice.
   return {
     port: 10100,
+    // Fresh/re-initialized configs are already written in the current three-tier
+    // OpenAI shape. Mark them as such so startup does not mistake them for a
+    // legacy config and collide with an immutable backup from an earlier setup.
+    openaiProviderTierVersion: OPENAI_PROVIDER_TIER_VERSION,
     providers: {
       openai: {
         adapter: "openai-responses",

package/src/lib/upstream-retry.ts

@@ -148,6 +148,27 @@ export interface TransientRetryOptions extends ResetRetryOptions {
 export type UpstreamSendRecovery = "connection-reset" | "transient-5xx";
 type ReplayableFetch = (recovery?: UpstreamSendRecovery) => Promise<Response>;
 
+/**
+ * Opt out of Bun's keep-alive pool after a connection-reset retry.
+ *
+ * Prefer the Bun fetch extension `keepalive: false` (transport-level) over
+ * relying on the hop-by-hop `Connection: close` header alone — Bun has ignored
+ * that header in past releases (oven-sh/bun#20492), so a header-only retry can
+ * still reuse the same half-closed pooled socket. Still set Connection: close
+ * as a belt-and-suspenders signal for intermediaries that honor it.
+ */
+export function applyUpstreamRecoveryInit<T extends RequestInit>(
+  init: T,
+  recovery?: UpstreamSendRecovery,
+): T & { headers: Headers } {
+  const headers = new Headers(init.headers);
+  if (recovery !== "connection-reset") {
+    return { ...init, headers };
+  }
+  headers.set("connection", "close");
+  return { ...init, headers, keepalive: false };
+}
+
 /**
  * Run `doFetch`, retrying only connection-reset-shaped rejections (see
  * isConnectionResetError) with jittered backoff. The caller's thunk must be replay-safe

package/src/lib/winsw.ts

@@ -223,7 +223,13 @@ export function probeScmRegistration(run: () => string = queryScmForService): bo
     const text = [e.stderr, e.stdout, e.message]
       .map(v => (typeof v === "string" ? v : ""))
       .join("\n");
-    if (e.status === 1060 || /FAILED 1060/i.test(text)) return false;
+    // ERROR_SERVICE_DOES_NOT_EXIST: the numeric identifier 1060 is locale-invariant
+    // (FALHA 1060 pt-BR, localized ko output, English FAILED 1060). The query is a
+    // fixed `sc.exe query <service>` so a standalone 1060 in its output is proof of
+    // absence. Bun may deliver e.status as 36 (1060 & 0xff) — status 36 ALONE is
+    // NOT accepted (collides with any status ≡ 36 mod 256); the textual 1060 is
+    // required corroboration and covers those hosts.
+    if (e.status === 1060 || /\b1060\b/.test(text)) return false;
     return "error";
   }
 }

package/src/oauth/anthropic.ts

@@ -34,6 +34,17 @@ interface AnthropicTokenResponse {
   account?: { uuid?: string; email_address?: string };
 }
 
+export class AnthropicTokenError extends Error {
+  constructor(
+    message: string,
+    readonly httpStatus: number | undefined,
+    readonly oauthError: string | undefined,
+  ) {
+    super(message);
+    this.name = "AnthropicTokenError";
+  }
+}
+
 async function postJson(url: string, body: Record<string, string | number>): Promise<string> {
   const response = await fetch(url, {
     method: "POST",
@@ -43,7 +54,18 @@ async function postJson(url: string, body: Record<string, string | number>): Pro
   });
   const responseBody = await response.text();
   if (!response.ok) {
-    throw new Error(`Anthropic OAuth HTTP ${response.status}: ${responseBody}`);
+    let oauthError: string | undefined;
+    try {
+      const parsed = JSON.parse(responseBody) as { error?: unknown };
+      if (typeof parsed.error === "string") oauthError = parsed.error;
+    } catch {
+      // Best-effort only: malformed error bodies remain structured by HTTP status.
+    }
+    throw new AnthropicTokenError(
+      `Anthropic OAuth HTTP ${response.status}: ${responseBody}`,
+      response.status,
+      oauthError,
+    );
   }
   return responseBody;
 }

package/src/oauth/github-copilot.ts

@@ -395,6 +395,7 @@ export async function loginGithubCopilot(ctrl: OAuthController): Promise<OAuthCr
   ctrl.onAuth?.({
     url: device.verifyUrl,
     instructions: `Enter code: ${device.userCode}`,
+    deviceCode: device.userCode,
   });
   ctrl.onProgress?.("Waiting for GitHub device authorization…");
   const github = await pollGithubDeviceToken(

package/src/oauth/index.ts

@@ -3,9 +3,9 @@ import { parseCallbackInput } from "./callback-server";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { loadConfig, resolveEnvValue, saveConfig } from "../config";
 import { maskEmail } from "../lib/privacy";
-import { getAccountCredential, getAccountSet, saveAccountCredential, saveCredential, markAccountNeedsReauth, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration } from "./store";
+import { getAccountCredential, getAccountSet, saveAccountCredential, saveCredential, markAccountNeedsReauth, getCredential, credentialGeneration, createOAuthRefreshIntentLock, mergeAccountCredential, markAccountNeedsReauthIfGeneration, readOAuthRefreshIntent, writeOAuthRefreshIntent, clearOAuthRefreshIntent } from "./store";
 import { loginXai, refreshXaiToken, XAI_LOCAL_CLI_DETACH_WARNING, XaiTokenRequestError } from "./xai";
-import { ANTHROPIC_OAUTH_BETA, loginAnthropic, refreshAnthropicToken } from "./anthropic";
+import { ANTHROPIC_OAUTH_BETA, AnthropicTokenError, loginAnthropic, refreshAnthropicToken } from "./anthropic";
 import { loginKimi, refreshKimiToken } from "./kimi";
 import { loginKiro, readKiroCliSqlite, refreshKiroToken } from "./kiro";
 import { loginChatGPT, refreshChatGPTToken } from "./chatgpt";
@@ -15,7 +15,7 @@ import { loginGithubCopilot, refreshGithubCopilotToken, validateCopilotApiBaseUr
 import { deriveOAuthDefaultModel, deriveOAuthProviderConfig } from "../providers/derive";
 import { effectiveGoogleMode } from "../providers/registry";
 import { resolveProviderTransport } from "../providers/xai-transport";
-import { detectGrokCliToken, hasComparableGrokIdentity, isSameGrokIdentity, shouldAdoptGrokGeneration } from "./local-token-detect";
+import { detectClaudeCodeToken, detectGrokCliToken, hasComparableGrokIdentity, isSameGrokIdentity, shouldAdoptGrokGeneration } from "./local-token-detect";
 
 const REFRESH_SKEW_MS = 60_000;
 export interface OAuthAccessSnapshot {
@@ -29,6 +29,7 @@ const tokenRefreshes = new Map<string, Promise<OAuthAccessSnapshot>>();
 const XAI_PERMANENT_FAILURE_TTL_MS=30_000;
 const permanentRefreshFailures=new Map<string,number>();
 interface XaiRefreshDeps { intentLock?:ReturnType<typeof createOAuthRefreshIntentLock>; now?:()=>number; afterPrePersistRead?:()=>void|Promise<void> }
+interface AnthropicRefreshDeps { intentLock?:ReturnType<typeof createOAuthRefreshIntentLock>; now?:()=>number; afterPrePersistRead?:()=>void|Promise<void> }
 function verdictKey(p:string,a:string,c:OAuthCredentials){return `${p}\0${a}\0${credentialGeneration(c)}`;}
 function cached(p:string,a:string,c:OAuthCredentials,now:()=>number){const k=verdictKey(p,a,c),u=permanentRefreshFailures.get(k);if(u===undefined)return false;if(u<=now()){permanentRefreshFailures.delete(k);return false;}return true;}
 
@@ -257,7 +258,11 @@ function isTerminalRefreshError(err: unknown): boolean {
     || msg.includes("access_denied")
     || msg.includes("expired_token");
 }
-function terminal(error:unknown):boolean{return error instanceof XaiTokenRequestError?["invalid_grant","refresh_token_reused","revoked_token"].includes(error.oauthError??""):isTerminalRefreshError(error);}
+function terminal(error:unknown):boolean{
+  if(error instanceof XaiTokenRequestError)return ["invalid_grant","refresh_token_reused","revoked_token"].includes(error.oauthError??"");
+  if(error instanceof AnthropicTokenError)return (error.httpStatus===400||error.httpStatus===401)&&["invalid_grant","refresh_token_reused","revoked","revoked_token","refresh_token_revoked"].includes(error.oauthError??"");
+  return isTerminalRefreshError(error);
+}
 function authoritative(stored:OAuthCredentials,active:boolean,now:()=>number):OAuthCredentials{if(stored.source!=="local-cli")return stored;const disk=detectGrokCliToken();if(!disk)return stored;const allowed=isSameGrokIdentity(stored,disk)||(active&&!hasComparableGrokIdentity(stored,disk));return allowed&&shouldAdoptGrokGeneration(stored,disk,now(),REFRESH_SKEW_MS)?disk:stored;}
 function merged(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCredentials {
   return {
@@ -271,6 +276,79 @@ function merged(fresh: OAuthCredentials, previous: OAuthCredentials): OAuthCrede
 }
 export async function refreshXaiAccountWithLock(provider:string,accountId:string,def:OAuthProviderDef,callerCredential:OAuthCredentials,deps:XaiRefreshDeps={}):Promise<string>{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),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(!terminal(error))throw error;permanentRefreshFailures.set(verdictKey(provider,accountId,candidate),now()+XAI_PERMANENT_FAILURE_TTL_MS);await markAccountNeedsReauthIfGeneration(provider,accountId,generation);throw new OAuthLoginRequiredError(provider);}}finally{guard.release();}}
 
+function newerClaudeCredential(stored: OAuthCredentials, now: number): OAuthCredentials | undefined {
+  if (stored.source !== "local-cli") return undefined;
+  const disk = detectClaudeCodeToken();
+  if (!disk || disk.expires <= now + REFRESH_SKEW_MS) return undefined;
+  return credentialGeneration(disk) !== credentialGeneration(stored) ? disk : undefined;
+}
+
+export async function refreshAnthropicAccountWithLock(
+  provider: string,
+  accountId: string,
+  def: OAuthProviderDef,
+  callerCredential: OAuthCredentials,
+  deps: AnthropicRefreshDeps = {},
+): Promise<string> {
+  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 account = getAccountSet(provider)?.accounts.find(candidate => candidate.id === accountId);
+    const generation = credentialGeneration(stored);
+    const pendingIntent = readOAuthRefreshIntent(provider, accountId);
+    const disk = newerClaudeCredential(stored, now());
+    if (disk) {
+      const outcome = await mergeAccountCredential(provider, accountId, disk, {
+        expectedGeneration: credentialGeneration(stored),
+        afterPrePersistRead: deps.afterPrePersistRead,
+      });
+      if (outcome.superseded) {
+        if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+        if (outcome.stored.expires > now() + REFRESH_SKEW_MS) return outcome.stored.access;
+        throw new OAuthLoginRequiredError(provider);
+      }
+      if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+      return disk.access;
+    }
+    if (pendingIntent?.uncertain || pendingIntent?.generation === generation) {
+      await markAccountNeedsReauthIfGeneration(provider, accountId, generation);
+      throw new OAuthLoginRequiredError(provider);
+    }
+    if (pendingIntent) clearOAuthRefreshIntent(provider, accountId, pendingIntent.generation);
+    if (account?.needsReauth) {
+      throw new OAuthLoginRequiredError(provider);
+    }
+    if (credentialGeneration(stored) !== credentialGeneration(callerCredential) && stored.expires > now() + REFRESH_SKEW_MS) {
+      return stored.access;
+    }
+
+    try {
+      writeOAuthRefreshIntent(provider, accountId, generation, now());
+      const fresh = merged(await def.refresh(stored.refresh), stored);
+      const outcome = await mergeAccountCredential(provider, accountId, fresh, {
+        expectedGeneration: generation,
+        afterPrePersistRead: deps.afterPrePersistRead,
+      });
+      if (outcome.superseded) {
+        clearOAuthRefreshIntent(provider, accountId, generation);
+        if (outcome.stored.expires > now() + REFRESH_SKEW_MS) return outcome.stored.access;
+        throw new OAuthLoginRequiredError(provider);
+      }
+      clearOAuthRefreshIntent(provider, accountId, generation);
+      return fresh.access;
+    } catch (error) {
+      if (!terminal(error)) throw error;
+      await markAccountNeedsReauthIfGeneration(provider, accountId, generation);
+      clearOAuthRefreshIntent(provider, accountId, generation);
+      throw new OAuthLoginRequiredError(provider);
+    }
+  } finally {
+    guard.release();
+  }
+}
+
 async function refreshAndPersistAccessToken(
   provider: string,
   accountId: string,
@@ -288,6 +366,7 @@ async function refreshAndPersistAccessToken(
     }
   }
   if (provider === "xai") return refreshXaiAccountWithLock(provider, accountId, def, cred);
+  if (provider === "anthropic") return refreshAnthropicAccountWithLock(provider, accountId, def, cred);
   try {
     const fresh = await def.refresh(cred.refresh);
     const detachedLocalCli = provider === "xai" && cred.source === "local-cli";
@@ -567,7 +646,7 @@ export function submitManualLoginCode(provider: string, input: string): { ok: tr
   return { ok: true };
 }
 
-export interface OAuthAccountSummary { id: string; email?: string; active: boolean; needsReauth?: boolean; expiresAt?: number }
+export interface OAuthAccountSummary { id: string; alias?: 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);
@@ -575,6 +654,7 @@ export function getLoginStatus(provider: string): { loggedIn: boolean; email?: s
   const set = getAccountSet(provider);
   const accounts: OAuthAccountSummary[] | undefined = set?.accounts.map(a => ({
     id: a.id,
+    ...(a.alias ? { alias: a.alias } : {}),
     email: maskEmail(a.credential.email) ?? undefined,
     active: a.id === set.activeAccountId,
     ...(a.needsReauth ? { needsReauth: true } : {}),
@@ -616,7 +696,7 @@ export function cancelLoginFlow(provider: string): boolean {
   return true;
 }
 
-export async function startLoginFlow(provider: string, opts?: LoginOpts): Promise<{ url: string; instructions?: string }> {
+export async function startLoginFlow(provider: string, opts?: LoginOpts): Promise<{ url: string; instructions?: string; deviceCode?: string }> {
   const def = OAUTH_PROVIDERS[provider];
   if (!def) throw new UnsupportedOAuthProviderError(provider);
   const existing = loginState.get(provider);
@@ -630,9 +710,9 @@ export async function startLoginFlow(provider: string, opts?: LoginOpts): Promis
   return new Promise((resolve, reject) => {
     let urlResolved = false;
     const ctrl: OAuthController = {
-      onAuth: ({ url, instructions }) => {
+      onAuth: ({ url, instructions, deviceCode }) => {
         urlResolved = true;
-        resolve({ url, instructions });
+        resolve({ url, instructions, deviceCode });
       },
       onProgress: () => {},
       // GUI fallback when the browser cannot hit the loopback callback server.

package/src/oauth/kiro.ts

@@ -50,7 +50,9 @@ export function readKiroCliSqlite(): ImportedKiroToken | null {
 
 /**
  * Import-first login: kiro-cli SQLite → KIRO_ACCESS_TOKEN env → manual paste (CLI only).
- * In GUI (no onManualCodeInput) with no SQLite token and no env, throws a clear error — never hangs.
+ * When no local token is available, resolves the login flow via onAuth with instructions
+ * so the GUI renders the paste-input field, then blocks on onManualCodeInput for the token.
+ * If neither onAuth nor onManualCodeInput is available, throws a clear error.
  */
 export async function loginKiro(ctrl: OAuthController): Promise<OAuthCredentials> {
   const imported = readImportedKiroCredential();
@@ -71,6 +73,15 @@ export async function loginKiro(ctrl: OAuthController): Promise<OAuthCredentials
   }
 
   if (ctrl.onManualCodeInput) {
+    // Resolve the login flow immediately so the GUI receives instructions and
+    // shows the paste-input field. Without this, onManualCodeInput blocks
+    // forever and the HTTP response never reaches the dashboard.
+    ctrl.onAuth?.({
+      url: "",
+      instructions:
+        "No kiro-cli token found. Paste a Kiro access token below (starts with 'aoa'). " +
+        "Run `kiro-cli login` first, or set KIRO_ACCESS_TOKEN.",
+    });
     ctrl.onProgress?.("No kiro-cli token found. Paste a Kiro access token (starts with 'aoa').");
     const raw = (await ctrl.onManualCodeInput()).trim();
     if (raw) return { access: raw, refresh: "", expires: Date.now() + 3600_000, source: "manual" };

package/src/oauth/local-token-detect.ts

@@ -97,6 +97,9 @@ export function readClaudeCredentialsFile(): string | null {
 
 /** Keychain first on macOS, then the cross-platform credentials file. */
 function readClaudeSecureStorage(): string | null {
+  // An explicit config-dir override identifies a separate Claude installation/profile.
+  // Do not let the default macOS Keychain entry shadow that requested credential file.
+  if (process.env.CLAUDE_CONFIG_DIR?.trim()) return readClaudeCredentialsFile() ?? readClaudeKeychain();
   return readClaudeKeychain() ?? readClaudeCredentialsFile();
 }