opencode-claude-auth 2.1.5 → 2.2.0

package/README.md

@@ -55,11 +55,12 @@ Just run OpenCode. The plugin handles auth automatically — it reads your Claud
 
 ## Supported models
 
-13 supported models. Run `pnpm run test:models` to verify against your account.
+14 supported models. Run `pnpm run test:models` to verify against your account.
 
 | Model                      |
 | -------------------------- |
 | claude-fable-5             |
+| claude-fable-5-1           |
 | claude-haiku-4-5           |
 | claude-haiku-4-5-20251001  |
 | claude-opus-4-5            |
@@ -151,14 +152,19 @@ This reads your stored credentials, calls Anthropic's OAuth token endpoint, and
 
 All configurable parameters can be overridden via environment variables. If Anthropic changes something before we publish an update, set an env var and keep working:
 
-| Variable                            | Description                                                                                                                                                                            | Default                                                            |
-| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| `ANTHROPIC_CLI_VERSION`             | Claude CLI version for user-agent and billing headers                                                                                                                                  | `config.ccVersion` in [`src/model-config.ts`](src/model-config.ts) |
-| `ANTHROPIC_USER_AGENT`              | Full User-Agent string (overrides CLI version)                                                                                                                                         | `claude-cli/{version} (external, sdk-cli)`                         |
-| `ANTHROPIC_BETA_FLAGS`              | Comma-separated beta feature flags                                                                                                                                                     | `baseBetas` list in [`src/model-config.ts`](src/model-config.ts)   |
-| `CLAUDE_AUTH_DEBUG`                 | Enable diagnostic logging (`1` for default path, or a custom file path)                                                                                                                | disabled                                                           |
-| `CLAUDE_CONFIG_DIR`                 | Claude Code config directory used for the credentials-file fallback (reads `$CLAUDE_CONFIG_DIR/.credentials.json`). macOS still checks the Keychain first.                             | `~/.claude`                                                        |
-| `OPENCODE_CLAUDE_AUTH_MAX_RETRY_MS` | Max ms the plugin waits when honouring a 429/529 `retry-after` header. Beyond this cap the response surfaces immediately so OpenCode doesn't appear to hang on hour-long quota resets. | `30000`                                                            |
+| Variable                                   | Description                                                                                                                                                                                                                                                                       | Default                                                            |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `ANTHROPIC_CLI_VERSION`                    | Claude CLI version for user-agent and billing headers                                                                                                                                                                                                                             | `config.ccVersion` in [`src/model-config.ts`](src/model-config.ts) |
+| `ANTHROPIC_USER_AGENT`                     | Full User-Agent string (overrides CLI version)                                                                                                                                                                                                                                    | `claude-cli/{version} (external, sdk-cli)`                         |
+| `ANTHROPIC_BETA_FLAGS`                     | Comma-separated beta feature flags                                                                                                                                                                                                                                                | `baseBetas` list in [`src/model-config.ts`](src/model-config.ts)   |
+| `CLAUDE_AUTH_DEBUG`                        | Enable diagnostic logging (`1` for default path, or a custom file path)                                                                                                                                                                                                           | disabled                                                           |
+| `CLAUDE_CONFIG_DIR`                        | Claude Code config directory used for the credentials-file fallback (reads `$CLAUDE_CONFIG_DIR/.credentials.json`). macOS still checks the Keychain first.                                                                                                                        | `~/.claude`                                                        |
+| `OPENCODE_CLAUDE_AUTH_MAX_RETRY_MS`        | Max ms the plugin waits when honouring a 429/529 `retry-after` header. Beyond this cap the response surfaces immediately so OpenCode doesn't appear to hang on hour-long quota resets.                                                                                            | `30000`                                                            |
+| `OPENCODE_CLAUDE_AUTH_TOOL_REPAIR`         | Strategy for reconciling `tool_use`/`tool_result` adjacency broken by OpenCode auto-compaction. `placeholder` synthesizes a paired result for orphaned `tool_use` blocks (lossless, preserves `thinking` blocks); `drop` removes orphaned blocks (omitting whole thinking turns). | `placeholder`                                                      |
+| `OPENCODE_CLAUDE_AUTH_REFRESH_WAIT_MS`     | Max ms a single request waits through a transient token-refresh rate-limit (429) before returning a retryable error instead of a hard "run `claude`".                                                                                                                             | `45000`                                                            |
+| `OPENCODE_CLAUDE_AUTH_REFRESH_COOLDOWN_MS` | Base per-account cooldown after a rate-limited refresh, before the plugin retries the token endpoint. Escalates with consecutive failures and is jittered; capped at 60s.                                                                                                         | `15000`                                                            |
+| `OPENCODE_CLAUDE_AUTH_REFRESH_LOCK_TTL_MS` | TTL for the cross-process refresh lock. A held lock older than this is treated as stale (crashed holder) and taken over.                                                                                                                                                          | `20000`                                                            |
+| `OPENCODE_CLAUDE_AUTH_REFRESH_LOCK_DIR`    | Directory for the advisory cross-process refresh lock files.                                                                                                                                                                                                                      | OpenCode data dir (`~/.local/share/opencode`)                      |
 
 Example:
 

package/dist/credentials.d.ts

@@ -1,4 +1,5 @@
 import { type ClaudeAccount, type ClaudeCredentials } from "./keychain.ts";
+import { type RefreshFailureKind } from "./refresh-backoff.ts";
 export type { ClaudeAccount } from "./keychain.ts";
 export type { ClaudeCredentials } from "./keychain.ts";
 export declare function initAccounts(accounts: ClaudeAccount[]): void;
@@ -11,6 +12,17 @@ export declare function syncAuthJson(creds: ClaudeCredentials): void;
 export declare const OAUTH_TOKEN_URL = "https://claude.ai/v1/oauth/token";
 export declare const OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
 export declare function parseOAuthResponse(raw: string, currentRefreshToken: string, now?: number): ClaudeCredentials | null;
+/**
+ * Extract the non-secret failure reason from an OAuth token-endpoint error
+ * body so a refresh failure is diagnosable from the debug log. Handles both the
+ * OAuth shape (`{ error, error_description }`) and Anthropic's API error
+ * envelope (`{ error: { type, message } }`). Values are truncated and never
+ * include tokens; the logger additionally redacts anything JWT-shaped.
+ */
+export declare function extractOAuthError(raw: string): {
+    oauthError?: string;
+    oauthErrorDescription?: string;
+};
 /**
  * Exchanges a refresh token for fresh credentials using the runtime's own
  * fetch.
@@ -23,6 +35,35 @@ export declare function parseOAuthResponse(raw: string, currentRefreshToken: str
  * non-zero with empty stdout and silently fell through to the claude CLI.
  * Node 18+ and Bun both expose a global fetch, so no subprocess is needed.
  */
+/**
+ * Classified result of an OAuth refresh. A `transient` outcome (429/5xx/network
+ * /`rate_limit_error`) means the refresh token is still good and the caller
+ * should back off and retry rather than surface a hard error; a `terminal`
+ * outcome (`invalid_grant`, ...) means the refresh token is dead.
+ */
+export type RefreshOutcome = {
+    kind: "ok";
+    creds: ClaudeCredentials;
+} | {
+    kind: "transient";
+    status: number;
+    oauthError?: string;
+    retryAfterMs?: number;
+} | {
+    kind: "terminal";
+    status: number;
+    oauthError?: string;
+};
+/**
+ * Exchange a refresh token for fresh credentials and classify the result.
+ * See {@link RefreshOutcome}. Uses the runtime's own fetch (no subprocess).
+ */
+export declare function refreshViaOAuthDetailed(refreshToken: string, timeoutMs?: number): Promise<RefreshOutcome>;
+/**
+ * Backward-compatible wrapper: returns credentials on success, else null.
+ * Prefer {@link refreshViaOAuthDetailed} when the transient/terminal
+ * distinction matters (cooldown, CLI-fallback gating).
+ */
 export declare function refreshViaOAuth(refreshToken: string, timeoutMs?: number): Promise<ClaudeCredentials | null>;
 /**
  * Refreshes the given (or active) account's credentials if they are within
@@ -64,5 +105,29 @@ export declare function forceRefreshActiveAccount(refresh?: (refreshToken: strin
  */
 export declare function invalidateCredentialCache(): void;
 export declare function getCachedCredentials(): Promise<ClaudeCredentials | null>;
+export interface CredentialWaitOptions {
+    maxWaitMs?: number;
+    pollMs?: number;
+    signal?: AbortSignal;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    rng?: () => number;
+}
+/**
+ * Resolve credentials, waiting through a transient refresh rate-limit rather
+ * than failing hard. Returns as soon as a token is available — ours refreshed
+ * once the cooldown clears, or a sibling OpenCode instance / the `claude` CLI
+ * wrote a fresh one to the shared store. Returns null promptly on a terminal
+ * failure (dead refresh token) or when the wait budget is exhausted, so the
+ * caller can decide between a retryable response and a hard error.
+ */
+export declare function getCredentialsWithBackoff(opts?: CredentialWaitOptions): Promise<ClaudeCredentials | null>;
+/**
+ * Whether the active account's most recent refresh failure was transient
+ * (rate-limited/retryable) or terminal (dead refresh token), for callers
+ * deciding between a retryable response and a hard "re-authenticate" error.
+ * An active cooldown implies a transient failure.
+ */
+export declare function getActiveRefreshFailureKind(): RefreshFailureKind | null;
 export declare function reloadCredentialsFromSource(): ClaudeCredentials | null;
 //# sourceMappingURL=credentials.d.ts.map

package/dist/credentials.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAA;AAKtB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAqBtD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAE5D;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAQ3D;AAED,wBAAgB,mBAAmB,IAAI,aAAa,EAAE,CAUrD;AAED,wBAAgB,gBAAgB,IAAI,aAAa,GAAG,IAAI,CAOvD;AAYD,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,IAAI,CAU1D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAStD;AA4CD,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAc3D;AAED,eAAO,MAAM,eAAe,qCAAqC,CAAA;AACjE,eAAO,MAAM,eAAe,yCAAyC,CAAA;AAErE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,mBAAmB,EAAE,MAAM,EAC3B,GAAG,GAAE,MAAmB,GACvB,iBAAiB,GAAG,IAAI,CAoB1B;AAID;;;;;;;;;;;GAWG;AACH,wBAAsB,eAAe,CACnC,YAAY,EAAE,MAAM,EACpB,SAAS,SAAmB,GAC3B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAmDnC;AA0CD;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CACnC,OAAO,CAAC,EAAE,aAAa,EACvB,WAAW,SAAS,GACnB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA2EnC;AA6OD,wBAAgB,qBAAqB,IAAI,iBAAiB,GAAG,IAAI,CAUhE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAY1C;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,OAAO,GAAE,CACP,YAAY,EAAE,MAAM,KACjB,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAmB,GACvD,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAyCnC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAED,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAgC9E;AAED,wBAAgB,2BAA2B,IAAI,iBAAiB,GAAG,IAAI,CAmDtE"}
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"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"}

package/dist/credentials.js

@@ -6,6 +6,8 @@ import { PRIMARY_SERVICE, readAllClaudeAccounts, refreshAccount, writeBackCreden
 import { resetExcludedBetas } from "./betas.js";
 import { fetchWithRetry } from "./http.js";
 import { log } from "./logger.js";
+import { classifyRefreshFailure, clearRefreshOutcome, getRefreshCooldownUntil, getRefreshFailureKind, isRefreshCooldownActive, noteRefreshTerminal, noteRefreshTransient, } from "./refresh-backoff.js";
+import { acquireRefreshLock } from "./refresh-lock.js";
 const CREDENTIAL_CACHE_TTL_MS = 30_000;
 // Only inside this window will the claude CLI actually rotate a token, so
 // it is also the only window where spawning it is worth a real API request.
@@ -146,26 +148,72 @@ export function parseOAuthResponse(raw, currentRefreshToken, now = Date.now()) {
     }
     if (!data.access_token)
         return null;
+    // Prefer an absolute `expires_at` (ms) when the endpoint provides one, but
+    // only if it is a future millisecond timestamp — a seconds-precision value
+    // would land in 1970 and read as already-expired, so fall back to the
+    // relative `expires_in` (or a conservative default) in that case.
+    const expiresAt = typeof data.expires_at === "number" && data.expires_at > now
+        ? Math.trunc(data.expires_at)
+        : Math.trunc(now + (data.expires_in ?? 36_000) * 1000);
     return {
         accessToken: data.access_token,
         refreshToken: data.refresh_token ?? currentRefreshToken,
-        expiresAt: Math.trunc(now + (data.expires_in ?? 36_000) * 1000),
+        expiresAt,
     };
 }
+/**
+ * Extract the non-secret failure reason from an OAuth token-endpoint error
+ * body so a refresh failure is diagnosable from the debug log. Handles both the
+ * OAuth shape (`{ error, error_description }`) and Anthropic's API error
+ * envelope (`{ error: { type, message } }`). Values are truncated and never
+ * include tokens; the logger additionally redacts anything JWT-shaped.
+ */
+export function extractOAuthError(raw) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+    // JSON.parse succeeds for primitives and arrays too (`null`, `123`, `"str"`,
+    // `[...]`); dereferencing `data.error` on those would throw and, worse,
+    // escape into refreshViaOAuthDetailed's outer catch — erasing the HTTP status
+    // this function exists to preserve. Only object bodies carry an error shape.
+    if (typeof data !== "object" || data === null || Array.isArray(data)) {
+        return {};
+    }
+    const out = {};
+    if (typeof data.error === "string") {
+        out.oauthError = data.error.slice(0, 200);
+    }
+    else if (data.error && typeof data.error === "object") {
+        const nested = data.error;
+        if (typeof nested.type === "string")
+            out.oauthError = nested.type.slice(0, 200);
+        if (typeof nested.message === "string") {
+            out.oauthErrorDescription = nested.message.slice(0, 500);
+        }
+    }
+    // The flat OAuth-standard `error_description` is canonical, so it deliberately
+    // wins over a nested-envelope `message` when a response carries both.
+    if (typeof data.error_description === "string") {
+        out.oauthErrorDescription = data.error_description.slice(0, 500);
+    }
+    return out;
+}
 const OAUTH_TIMEOUT_MS = 15_000;
+function parseRetryAfterMs(headerValue) {
+    if (!headerValue)
+        return undefined;
+    const seconds = Number.parseInt(headerValue, 10);
+    return Number.isFinite(seconds) && seconds > 0 ? seconds * 1000 : undefined;
+}
 /**
- * Exchanges a refresh token for fresh credentials using the runtime's own
- * fetch.
- *
- * This previously ran the request inside a child process spawned as
- * `process.execPath -e <script>`. That assumed process.execPath is a
- * JavaScript runtime, which does not hold inside OpenCode: the plugin runs
- * in a compiled single-file executable, so process.execPath is the OpenCode
- * binary itself and `-e` is not a script to evaluate. Every refresh exited
- * non-zero with empty stdout and silently fell through to the claude CLI.
- * Node 18+ and Bun both expose a global fetch, so no subprocess is needed.
+ * Exchange a refresh token for fresh credentials and classify the result.
+ * See {@link RefreshOutcome}. Uses the runtime's own fetch (no subprocess).
  */
-export async function refreshViaOAuth(refreshToken, timeoutMs = OAUTH_TIMEOUT_MS) {
+export async function refreshViaOAuthDetailed(refreshToken, timeoutMs = OAUTH_TIMEOUT_MS) {
     const body = new URLSearchParams({
         grant_type: "refresh_token",
         client_id: OAUTH_CLIENT_ID,
@@ -175,10 +223,6 @@ export async function refreshViaOAuth(refreshToken, timeoutMs = OAUTH_TIMEOUT_MS
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         log("refresh_started", { source: "oauth" });
-        // The token endpoint rate-limits valid refresh requests, and several
-        // OpenCode instances refreshing near expiry cluster their calls, so a
-        // 429 here is transient rather than terminal. The shared helper caps
-        // its own backoff, and the abort signal bounds the whole sequence.
         const response = await fetchWithRetry(OAUTH_TOKEN_URL, {
             method: "POST",
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
@@ -186,34 +230,63 @@ export async function refreshViaOAuth(refreshToken, timeoutMs = OAUTH_TIMEOUT_MS
             signal: controller.signal,
         });
         if (!response.ok) {
+            // Capture the token endpoint's own failure reason (invalid_grant,
+            // invalid_client, rate_limit_error, ...) so a persistent 401 is
+            // diagnosable rather than an opaque "HTTP 400".
+            const detail = extractOAuthError(await response.text().catch(() => ""));
+            const kind = classifyRefreshFailure(response.status, detail.oauthError);
+            const retryAfterMs = parseRetryAfterMs(response.headers.get("retry-after"));
             log("refresh_failed", {
                 source: "oauth",
                 error: `HTTP ${response.status}`,
+                kind,
+                ...detail,
             });
-            return null;
+            return kind === "terminal"
+                ? { kind, status: response.status, oauthError: detail.oauthError }
+                : {
+                    kind,
+                    status: response.status,
+                    oauthError: detail.oauthError,
+                    retryAfterMs,
+                };
         }
         const creds = parseOAuthResponse(await response.text(), refreshToken);
         if (!creds) {
+            // A 200 we cannot parse is an endpoint hiccup, not a dead token — treat
+            // it as transient so a retry can recover.
             log("refresh_failed", {
                 source: "oauth",
                 error: "no access_token in response",
+                kind: "transient",
             });
-            return null;
+            return { kind: "transient", status: response.status };
         }
         log("refresh_success", { source: "oauth" });
-        return creds;
+        return { kind: "ok", creds };
     }
     catch (err) {
+        // Network error / abort: transient by nature.
         log("refresh_failed", {
             source: "oauth",
             error: err instanceof Error ? err.message : String(err),
+            kind: "transient",
         });
-        return null;
+        return { kind: "transient", status: 0 };
     }
     finally {
         clearTimeout(timer);
     }
 }
+/**
+ * Backward-compatible wrapper: returns credentials on success, else null.
+ * Prefer {@link refreshViaOAuthDetailed} when the transient/terminal
+ * distinction matters (cooldown, CLI-fallback gating).
+ */
+export async function refreshViaOAuth(refreshToken, timeoutMs = OAUTH_TIMEOUT_MS) {
+    const outcome = await refreshViaOAuthDetailed(refreshToken, timeoutMs);
+    return outcome.kind === "ok" ? outcome.creds : null;
+}
 function refreshViaCli(configDir, requireConfigDir = false) {
     if (requireConfigDir && !configDir) {
         log("refresh_cli_skipped", {
@@ -317,6 +390,22 @@ export async function refreshIfNeeded(account, thresholdMs = 60_000) {
     const creds = target.credentials;
     if (creds.expiresAt > Date.now() + thresholdMs)
         return creds;
+    // If a recent refresh was rate-limited, don't re-hit the endpoint until the
+    // cooldown clears — adopt a sibling instance's / the CLI's fresh token if one
+    // has appeared, else defer. This is what stops N OpenCode instances from
+    // turning a single transient 429 into a sustained storm. Borrowed accounts
+    // are exempt: their recovery (refreshBorrowedAccount) is a distinct path.
+    if (!borrowedCredentialAccounts.has(target) &&
+        isRefreshCooldownActive(target.source)) {
+        const adopted = adoptFreshFromSource(target, creds.accessToken);
+        if (adopted)
+            return adopted;
+        log("refresh_cooldown_skip", {
+            source: target.source,
+            until: getRefreshCooldownUntil(target.source),
+        });
+        return null;
+    }
     // The proactive sync timer calls this directly while the request path
     // arrives via getCachedCredentials(). A rotation invalidates the refresh
     // token it was issued against, so two concurrent refreshes would leave
@@ -326,7 +415,29 @@ export async function refreshIfNeeded(account, thresholdMs = 60_000) {
         log("refresh_joined", { source: target.source });
         return inFlight;
     }
-    const pending = performRefresh(target, creds);
+    // Cross-process single-flight: only one OpenCode instance / the CLI should
+    // hit the token endpoint at a time. If another holds the lock, wait briefly
+    // and adopt its result rather than piling onto an already-strained endpoint.
+    const lock = acquireRefreshLock(target.source);
+    if (!lock) {
+        log("refresh_lock_busy", { source: target.source });
+        const adopted = await waitForAdopt(target, creds.accessToken);
+        if (adopted)
+            return adopted;
+        // The holder produced nothing within the window (likely crashed; its lock
+        // ages out by TTL). Defer rather than refresh lock-free, so we don't
+        // recreate the burst the lock exists to prevent — the request-level wait
+        // loop and the lock TTL drive eventual progress.
+        return null;
+    }
+    const pending = (async () => {
+        try {
+            return await performRefresh(target, creds);
+        }
+        finally {
+            lock.release();
+        }
+    })();
     inFlightRefreshes.set(target.source, pending);
     try {
         return await pending;
@@ -335,6 +446,54 @@ export async function refreshIfNeeded(account, thresholdMs = 60_000) {
         inFlightRefreshes.delete(target.source);
     }
 }
+/**
+ * Re-read the account's own source and adopt a token another OpenCode instance
+ * or the `claude` CLI has just written. Returns the adopted credentials when
+ * the store now holds a distinct, still-valid token, else null.
+ */
+function adoptFreshFromSource(target, rejectedAccessToken) {
+    let stored = null;
+    try {
+        stored = refreshAccount(target.source, target.configDir);
+    }
+    catch {
+        return null;
+    }
+    if (stored &&
+        stored.accessToken !== rejectedAccessToken &&
+        stored.expiresAt > Date.now() + 60_000) {
+        target.credentials = stored;
+        borrowedCredentialAccounts.delete(target);
+        clearRefreshOutcome(target.source);
+        log("refresh_adopted_from_source", { source: target.source });
+        return stored;
+    }
+    return null;
+}
+const LOCK_ADOPT_WAIT_MS = 5_000;
+const LOCK_ADOPT_POLL_MS = 250;
+/**
+ * Another instance holds the refresh lock and is presumably refreshing. Poll
+ * the shared store for the token it is about to write, up to a short budget,
+ * before giving up.
+ */
+async function waitForAdopt(target, rejectedAccessToken, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? ((ms) => sleepAbortable(ms));
+    const maxMs = opts.maxMs ?? LOCK_ADOPT_WAIT_MS;
+    const pollMs = opts.pollMs ?? LOCK_ADOPT_POLL_MS;
+    const immediate = adoptFreshFromSource(target, rejectedAccessToken);
+    if (immediate)
+        return immediate;
+    const deadline = now() + maxMs;
+    while (now() < deadline) {
+        await sleep(pollMs);
+        const adopted = adoptFreshFromSource(target, rejectedAccessToken);
+        if (adopted)
+            return adopted;
+    }
+    return null;
+}
 async function performRefresh(target, creds) {
     if (borrowedCredentialAccounts.has(target)) {
         return refreshBorrowedAccount(target);
@@ -345,10 +504,12 @@ async function performRefresh(target, creds) {
         expiresIn: creds.expiresAt - Date.now(),
     });
     if (creds.refreshToken) {
-        const oauthCreds = await refreshViaOAuth(creds.refreshToken);
-        if (oauthCreds && oauthCreds.expiresAt > Date.now() + 60_000) {
-            target.credentials = oauthCreds;
-            if (!writeBackCredentials(target.source, oauthCreds, target.configDir, creds.accessToken)) {
+        const outcome = await refreshViaOAuthDetailed(creds.refreshToken);
+        if (outcome.kind === "ok" &&
+            outcome.creds.expiresAt > Date.now() + 60_000) {
+            clearRefreshOutcome(target.source);
+            target.credentials = outcome.creds;
+            if (!writeBackCredentials(target.source, outcome.creds, target.configDir, creds.accessToken)) {
                 // Mirrors force_refresh_writeback_failed on the forced path. The
                 // session continues from memory either way, so this stays a log
                 // rather than a control-flow change: acting on the two causes
@@ -357,7 +518,48 @@ async function performRefresh(target, creds) {
                 // the validated re-read — is tracked as a follow-up.
                 log("refresh_writeback_failed", { source: target.source });
             }
-            return oauthCreds;
+            return outcome.creds;
+        }
+        if (outcome.kind === "transient") {
+            // A rate-limit / 5xx / network blip: the refresh token is still valid.
+            // Back off so we (and our sibling OpenCode instances) stop hammering the
+            // endpoint, adopt a token another instance/CLI may have just written,
+            // and — crucially — do NOT spawn the claude CLI, which hits the same
+            // rate-limited endpoint and only deepens the limit.
+            const cooldownMs = noteRefreshTransient(target.source, {
+                retryAfterMs: outcome.retryAfterMs,
+            });
+            log("refresh_transient", {
+                source: target.source,
+                status: outcome.status,
+                oauthError: outcome.oauthError,
+                cooldownMs,
+            });
+            const adopted = adoptFreshFromSource(target, creds.accessToken);
+            if (adopted)
+                return adopted;
+            // Keep serving still-usable credentials on the proactive path.
+            if (creds.expiresAt > Date.now() + CLI_FALLBACK_THRESHOLD_MS)
+                return creds;
+            // Borrow a sibling account's still-valid token rather than spawning the
+            // claude CLI, which hits the same rate-limited endpoint.
+            const borrowed = tryFallbackAccount(target.source);
+            if (borrowed) {
+                target.credentials = borrowed;
+                borrowedCredentialAccounts.add(target);
+                return borrowed;
+            }
+            return null;
+        }
+        if (outcome.kind === "terminal") {
+            // The refresh token itself is dead (invalid_grant, ...). Fall through to
+            // the CLI fallback / borrowed-account recovery below.
+            noteRefreshTerminal(target.source);
+            log("refresh_terminal", {
+                source: target.source,
+                status: outcome.status,
+                oauthError: outcome.oauthError,
+            });
         }
     }
     // The claude CLI only rotates a token that is itself close to expiry, so
@@ -650,6 +852,85 @@ export async function getCachedCredentials() {
     accountCacheMap.set(account.source, { creds: fresh, cachedAt: Date.now() });
     return fresh;
 }
+/** Max time a single request will wait through a transient refresh rate-limit. */
+const REFRESH_WAIT_MS = (() => {
+    const raw = process.env.OPENCODE_CLAUDE_AUTH_REFRESH_WAIT_MS;
+    const parsed = raw ? Number.parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : 45_000;
+})();
+const REFRESH_POLL_MS = 2_500;
+function sleepAbortable(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const done = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", done);
+            resolve();
+        };
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", done, { once: true });
+    });
+}
+/**
+ * Resolve credentials, waiting through a transient refresh rate-limit rather
+ * than failing hard. Returns as soon as a token is available — ours refreshed
+ * once the cooldown clears, or a sibling OpenCode instance / the `claude` CLI
+ * wrote a fresh one to the shared store. Returns null promptly on a terminal
+ * failure (dead refresh token) or when the wait budget is exhausted, so the
+ * caller can decide between a retryable response and a hard error.
+ */
+export async function getCredentialsWithBackoff(opts = {}) {
+    const first = await getCachedCredentials();
+    if (first)
+        return first;
+    const source = getActiveAccount()?.source;
+    // No active account means no in-progress refresh could ever produce a token,
+    // so waiting is pointless — fail fast instead of spinning the wait budget.
+    if (!source)
+        return null;
+    // A dead refresh token will not fix itself by waiting.
+    if (getRefreshFailureKind(source) === "terminal")
+        return null;
+    const now = opts.now ?? Date.now;
+    const sleep = opts.sleep ?? sleepAbortable;
+    const rng = opts.rng ?? Math.random;
+    const maxWaitMs = opts.maxWaitMs ?? REFRESH_WAIT_MS;
+    const pollMs = opts.pollMs ?? REFRESH_POLL_MS;
+    const deadline = now() + maxWaitMs;
+    log("fetch_credentials_wait", { source: source ?? null, maxWaitMs });
+    while (now() < deadline) {
+        if (opts.signal?.aborted)
+            return null;
+        // Jittered poll so sibling instances desynchronize their re-reads.
+        await sleep(Math.round(pollMs * (0.5 + rng() * 0.5)), opts.signal);
+        if (opts.signal?.aborted)
+            return null;
+        const creds = await getCachedCredentials();
+        if (creds)
+            return creds;
+        if (source && getRefreshFailureKind(source) === "terminal")
+            return null;
+    }
+    return null;
+}
+/**
+ * Whether the active account's most recent refresh failure was transient
+ * (rate-limited/retryable) or terminal (dead refresh token), for callers
+ * deciding between a retryable response and a hard "re-authenticate" error.
+ * An active cooldown implies a transient failure.
+ */
+export function getActiveRefreshFailureKind() {
+    const source = getActiveAccount()?.source;
+    if (!source)
+        return null;
+    const kind = getRefreshFailureKind(source);
+    if (kind === "transient" || isRefreshCooldownActive(source))
+        return "transient";
+    return kind;
+}
 export function reloadCredentialsFromSource() {
     const account = getActiveAccount();
     if (!account)