opencode-claude-auth 2.1.3 → 2.1.5

package/README.md

@@ -176,10 +176,15 @@ export ANTHROPIC_CLI_VERSION=2.2.0
 - Sets required API headers (beta flags, billing, user-agent) with model-aware selection
 - On macOS, enumerates all `Claude Code-credentials*` Keychain entries and labels them by subscription tier
 - Provides an account switcher via `opencode auth login` when multiple accounts are found; persists selection to `~/.local/share/opencode/claude-account-source.txt`
-- Syncs credentials to `auth.json` on startup and every 5 minutes as a fallback (sync never triggers refresh; refresh is lazy, only on API requests)
+- Syncs credentials to `auth.json` on startup and every 5 minutes as a fallback; that same tick proactively refreshes once the token is within an hour of expiry
 - On Windows, writes to both `%USERPROFILE%\.local\share\opencode\auth.json` and `%LOCALAPPDATA%\opencode\auth.json`
+- Re-reads the credential source on every cache miss, so an account rotated by something other than this plugin — the `claude` CLI in another terminal, a second OpenCode instance, or a switcher like [claude-swap](https://github.com/realiti4/claude-swap) — gets picked up mid-session without a restart. Bounded by the same 30s cache, so it adds at most about two source reads a minute under load. A stored token is adopted whenever it is usable, and when it isn't only if the one already held is also unusable — otherwise a failed write-back would resurrect the pre-refresh token it left behind
+- Guards credential write-back with the access token the refresh started from, so a switch landing mid-refresh can't write one account's rotated tokens into another account's slot
 - Retries API requests on 429 (rate limit) and 529 (overloaded) with exponential backoff, respecting `retry-after` headers
-- When a token is within 60 seconds of expiry, refreshes directly via `POST https://claude.ai/v1/oauth/token` (no LLM tokens consumed). Falls back to `claude` CLI if the direct refresh fails. New tokens are written back to Keychain (macOS) or credentials file (Linux/Windows) to keep stored credentials in sync with rotated refresh tokens
+- On a 429 that outlives those backoff retries, re-reads the source once and retries only if the access token changed, so a rate limit another process has already resolved by switching accounts isn't surfaced. A changed token isn't proof of a switch — a routine refresh of the same account changes it too — so this costs at most one extra request
+- On a 401, recovers in place rather than surfacing it: adopts an externally rotated token if the source now holds one, otherwise forces an OAuth refresh, then retries the request. Bounded at two attempts, so a rejected token costs at most three API calls. A 401 that survives recovery is returned unmodified, without SSE stream transformation, since it carries an error body rather than a stream
+- Refreshes directly via `POST https://claude.ai/v1/oauth/token` using the runtime's own `fetch` (no LLM tokens consumed, no subprocess). Requests are triggered within 60 seconds of expiry on the API request path and within an hour on the background tick; concurrent refreshes of one account share a single request, since each rotation invalidates the previous refresh token
+- Falls back to the `claude` CLI only within the 60-second window, the point at which Claude Code will actually rotate the token — running it earlier costs a real API request and returns the same token. New tokens are written back to Keychain (macOS) or credentials file (Linux/Windows) to keep stored credentials in sync with rotated refresh tokens
 - If credentials aren't OAuth-based, the auth loader returns `{}` and falls through to API key auth
 - If credentials are unavailable or unreadable, the plugin disables itself and OpenCode continues without Claude auth
 

package/dist/credentials.d.ts

@@ -4,20 +4,48 @@ export type { ClaudeCredentials } from "./keychain.ts";
 export declare function initAccounts(accounts: ClaudeAccount[]): void;
 export declare function setActiveAccountSource(source: string): void;
 export declare function refreshAccountsList(): ClaudeAccount[];
+export declare function getActiveAccount(): ClaudeAccount | null;
 export declare function loadPersistedAccountSource(): string | null;
 export declare function saveAccountSource(source: string): void;
 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;
-export declare function refreshViaOAuth(refreshToken: string): ClaudeCredentials | null;
-export declare function refreshIfNeeded(account?: ClaudeAccount): ClaudeCredentials | null;
+/**
+ * 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.
+ */
+export declare function refreshViaOAuth(refreshToken: string, timeoutMs?: number): Promise<ClaudeCredentials | null>;
+/**
+ * Refreshes the given (or active) account's credentials if they are within
+ * `thresholdMs` of expiry. Defaults to 60s, matching the reactive
+ * per-request refresh path. Callers that want a proactive refresh further
+ * ahead of expiry (e.g. a background timer) should pass a larger threshold —
+ * the account resolution (via getActiveAccount()) stays correct regardless
+ * of threshold, so this always operates on the currently active account
+ * unless one is explicitly passed in.
+ */
+export declare function refreshIfNeeded(account?: ClaudeAccount, thresholdMs?: number): Promise<ClaudeCredentials | null>;
 export declare function getCredentialsForSync(): ClaudeCredentials | null;
 /**
  * Re-read only the active account's credentials from its source (single
- * keychain service read or credentials file) and update them in place.
- * Used on 401 so an externally refreshed token is picked up without a
- * full multi-account keychain rescan.
+ * keychain service read or credentials file) and update them in place,
+ * so an externally refreshed token is picked up without a full
+ * multi-account keychain rescan.
+ *
+ * Currently has no call sites: the 401 path uses
+ * reloadCredentialsFromSource, which additionally validates the result
+ * and refreshes the cache. Wiring this up or deleting it is tracked as a
+ * follow-up; until then it must stay consistent with the read paths that
+ * are live, hence the configDir below.
  */
 export declare function reloadActiveAccount(): void;
 /**
@@ -27,7 +55,7 @@ export declare function reloadActiveAccount(): void;
  * On success the account, its source, and the cache are all updated.
  * The refresh function is injectable for tests.
  */
-export declare function forceRefreshActiveAccount(refresh?: (refreshToken: string) => ClaudeCredentials | null): ClaudeCredentials | null;
+export declare function forceRefreshActiveAccount(refresh?: (refreshToken: string) => Promise<ClaudeCredentials | null>): Promise<ClaudeCredentials | null>;
 /**
  * Drop the active account's cached credentials so the next
  * getCachedCredentials() call re-reads from the source, bypassing the
@@ -35,6 +63,6 @@ export declare function forceRefreshActiveAccount(refresh?: (refreshToken: strin
  * valid locally.
  */
 export declare function invalidateCredentialCache(): void;
-export declare function getCachedCredentials(): ClaudeCredentials | null;
+export declare function getCachedCredentials(): Promise<ClaudeCredentials | 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;AAItB,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAClD,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAWtD,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;AAqBD,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;AAED,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,GACnB,iBAAiB,GAAG,IAAI,CAiD1B;AA0CD,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,aAAa,GACtB,iBAAiB,GAAG,IAAI,CA0E1B;AAyCD,wBAAgB,qBAAqB,IAAI,iBAAiB,GAAG,IAAI,CAUhE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAY1C;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE,CAAC,YAAY,EAAE,MAAM,KAAK,iBAAiB,GAAG,IAAsB,GAC5E,iBAAiB,GAAG,IAAI,CAqB1B;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,IAAI,IAAI,CAMhD;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAgC/D;AAED,wBAAgB,2BAA2B,IAAI,iBAAiB,GAAG,IAAI,CA0CtE"}
+{"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"}

package/dist/credentials.js

@@ -1,12 +1,21 @@
-import { execFileSync, execSync } from "node:child_process";
+import { execSync } from "node:child_process";
 import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { PRIMARY_SERVICE, readAllClaudeAccounts, refreshAccount, writeBackCredentials, } from "./keychain.js";
 import { resetExcludedBetas } from "./betas.js";
+import { fetchWithRetry } from "./http.js";
 import { log } from "./logger.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.
+const CLI_FALLBACK_THRESHOLD_MS = 60_000;
 const accountCacheMap = new Map();
+const inFlightRefreshes = new Map();
+// Accounts currently running on credentials borrowed from another account.
+// Those tokens belong to the lender: they must never be used as this
+// account's refresh source, and never written back to its store.
+const borrowedCredentialAccounts = new WeakSet();
 let activeAccountSource = null;
 let allAccounts = [];
 export function initAccounts(accounts) {
@@ -32,7 +41,7 @@ export function refreshAccountsList() {
     allAccounts = fresh;
     return allAccounts;
 }
-function getActiveAccount() {
+export function getActiveAccount() {
     if (allAccounts.length === 0)
         return null;
     if (activeAccountSource) {
@@ -143,36 +152,47 @@ export function parseOAuthResponse(raw, currentRefreshToken, now = Date.now()) {
         expiresAt: Math.trunc(now + (data.expires_in ?? 36_000) * 1000),
     };
 }
-export function refreshViaOAuth(refreshToken) {
-    const script = `
-    process.stdin.resume();
-    let input = '';
-    process.stdin.on('data', c => input += c);
-    process.stdin.on('end', () => {
-      const body = new URLSearchParams({
-        grant_type: 'refresh_token',
-        client_id: '${OAUTH_CLIENT_ID}',
-        refresh_token: input.trim()
-      });
-      fetch('${OAUTH_TOKEN_URL}', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: body.toString()
-      })
-      .then(r => { if (!r.ok) throw new Error(String(r.status)); return r.json(); })
-      .then(d => { process.stdout.write(JSON.stringify(d)); })
-      .catch(e => { process.stdout.write(JSON.stringify({ error: String(e) })); process.exit(1); });
+const OAUTH_TIMEOUT_MS = 15_000;
+/**
+ * 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.
+ */
+export async function refreshViaOAuth(refreshToken, timeoutMs = OAUTH_TIMEOUT_MS) {
+    const body = new URLSearchParams({
+        grant_type: "refresh_token",
+        client_id: OAUTH_CLIENT_ID,
+        refresh_token: refreshToken,
     });
-  `;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
         log("refresh_started", { source: "oauth" });
-        const result = execFileSync(process.execPath, ["-e", script], {
-            input: refreshToken,
-            timeout: 15_000,
-            encoding: "utf-8",
-            stdio: ["pipe", "pipe", "ignore"],
+        // 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" },
+            body: body.toString(),
+            signal: controller.signal,
         });
-        const creds = parseOAuthResponse(result, refreshToken);
+        if (!response.ok) {
+            log("refresh_failed", {
+                source: "oauth",
+                error: `HTTP ${response.status}`,
+            });
+            return null;
+        }
+        const creds = parseOAuthResponse(await response.text(), refreshToken);
         if (!creds) {
             log("refresh_failed", {
                 source: "oauth",
@@ -190,6 +210,9 @@ export function refreshViaOAuth(refreshToken) {
         });
         return null;
     }
+    finally {
+        clearTimeout(timer);
+    }
 }
 function refreshViaCli(configDir, requireConfigDir = false) {
     if (requireConfigDir && !configDir) {
@@ -229,36 +252,155 @@ function refreshViaCli(configDir, requireConfigDir = false) {
     log("refresh_cli_exhausted", { source: "cli", configDir });
     return false;
 }
-export function refreshIfNeeded(account) {
+/**
+ * Refreshes the given (or active) account's credentials if they are within
+ * `thresholdMs` of expiry. Defaults to 60s, matching the reactive
+ * per-request refresh path. Callers that want a proactive refresh further
+ * ahead of expiry (e.g. a background timer) should pass a larger threshold —
+ * the account resolution (via getActiveAccount()) stays correct regardless
+ * of threshold, so this always operates on the currently active account
+ * unless one is explicitly passed in.
+ */
+export async function refreshIfNeeded(account, thresholdMs = 60_000) {
     const target = account ?? getActiveAccount();
     if (!target)
         return null;
-    // Pick up external updates to .credentials.json (e.g. switch_claude_account
-    // on Windows). Bounded by getCachedCredentials's 30s TTL: fires at most
-    // ~2x/min under load. macOS keychain sources stay on the in-memory path;
-    // their state is mutated only by our own writeBackCredentials, so no
-    // external-update vector exists for them.
-    if (target.source === "file") {
-        const onDisk = refreshAccount(target.source);
-        if (onDisk)
-            target.credentials = onDisk;
+    // Pick up credentials replaced externally — cswap switching accounts, the
+    // claude CLI in another terminal, or a second OpenCode instance. This was
+    // once limited to file sources, on the false assumption that a keychain
+    // entry is only ever mutated by our own writeBackCredentials. Bounded by
+    // getCachedCredentials's 30s TTL, so it fires at most ~2x/min under load.
+    //
+    // A keychain read shells out to `security`, which throws when the keychain
+    // is locked, access is denied, or the call times out. Degrade to the
+    // in-memory credentials rather than take down the request path.
+    //
+    // Adopt a usable stored blob always; an unusable one only when what we
+    // already hold is unusable too. Do not simplify this to an unconditional
+    // adopt: performRefresh ignores writeBackCredentials's return value, and
+    // that write can fail while the read before it succeeded (malformed blob,
+    // or an ACL allowing read but not add-generic-password), leaving memory
+    // freshly refreshed and the store holding the orphaned pre-refresh blob.
+    // On the reactive path that blob has under 60s left — that window is the
+    // only reason we refreshed — so adopting it re-enters performRefresh with
+    // a refresh token our own refresh just rotated dead: OAuth fails and we
+    // fall through to two 60s claude spawns, on every cache miss, forever.
+    //
+    // Two accepted residuals. An external switch installing an already-expired
+    // token while ours is usable is ignored until ours expires; cswap freshens
+    // a target before activating it, so that is rare. And the proactive timer
+    // refreshes an hour ahead (index.ts), where a failed write-back orphans a
+    // blob that is still usable — so it IS adopted, costing wasted background
+    // refreshes rather than failed requests until it drops under 60s and the
+    // CLI fallback recovers. No guard here closes that one: the re-read cannot
+    // tell "stale because our write failed" from "changed because cswap
+    // switched", as both present as store-disagrees-with-memory-and-usable.
+    // Only the return value performRefresh discards carries the distinction.
+    try {
+        const stored = refreshAccount(target.source, target.configDir);
+        const now = Date.now();
+        if (stored &&
+            (stored.expiresAt > now + 60_000 ||
+                target.credentials.expiresAt <= now + 60_000)) {
+            target.credentials = stored;
+            // Read from this account's own source, so what it returned is this
+            // account's own credentials — it is no longer running on a lender's.
+            borrowedCredentialAccounts.delete(target);
+        }
+    }
+    catch (err) {
+        log("source_reread_failed", {
+            source: target.source,
+            error: err instanceof Error ? err.message : String(err),
+        });
     }
     const creds = target.credentials;
-    if (creds.expiresAt > Date.now() + 60_000)
+    if (creds.expiresAt > Date.now() + thresholdMs)
         return creds;
+    // 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
+    // one caller holding an already-dead token. Share one attempt instead.
+    const inFlight = inFlightRefreshes.get(target.source);
+    if (inFlight) {
+        log("refresh_joined", { source: target.source });
+        return inFlight;
+    }
+    const pending = performRefresh(target, creds);
+    inFlightRefreshes.set(target.source, pending);
+    try {
+        return await pending;
+    }
+    finally {
+        inFlightRefreshes.delete(target.source);
+    }
+}
+async function performRefresh(target, creds) {
+    if (borrowedCredentialAccounts.has(target)) {
+        return refreshBorrowedAccount(target);
+    }
     log("refresh_needed", {
         source: target.source,
         expiresAt: creds.expiresAt,
         expiresIn: creds.expiresAt - Date.now(),
     });
     if (creds.refreshToken) {
-        const oauthCreds = refreshViaOAuth(creds.refreshToken);
+        const oauthCreds = await refreshViaOAuth(creds.refreshToken);
         if (oauthCreds && oauthCreds.expiresAt > Date.now() + 60_000) {
             target.credentials = oauthCreds;
-            writeBackCredentials(target.source, oauthCreds, target.configDir);
+            if (!writeBackCredentials(target.source, oauthCreds, 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
+                // (I/O failure vs. CAS mismatch) differs, and the proactive-path
+                // consequence — a still-usable orphaned blob being re-adopted by
+                // the validated re-read — is tracked as a follow-up.
+                log("refresh_writeback_failed", { source: target.source });
+            }
             return oauthCreds;
         }
     }
+    // The claude CLI only rotates a token that is itself close to expiry, so
+    // running it while the current one is still usable spawns a real API
+    // request that hands back the same token. Callers using a proactive
+    // threshold (the sync timer passes an hour) would otherwise pay for that
+    // request on every tick. Keep the fallback scoped to the reactive window
+    // and let the caller try again later.
+    if (creds.expiresAt > Date.now() + CLI_FALLBACK_THRESHOLD_MS) {
+        log("refresh_cli_skipped", {
+            source: target.source,
+            reason: "credentials still usable",
+            expiresIn: creds.expiresAt - Date.now(),
+        });
+        return creds;
+    }
+    // Every OpenCode instance refreshes independently, and a rotation
+    // invalidates the refresh token the others are holding. When ours is
+    // rejected, the instance that won may already have written usable
+    // credentials to the shared store during the OAuth round trip — far
+    // cheaper to re-read than to spawn the CLI.
+    //
+    // The file-source exclusion below is a leftover from when refreshIfNeeded
+    // re-read file sources only. That rationale is gone and the exclusion now
+    // has none: a sibling process can write a file source mid-round-trip
+    // exactly as it can a keychain entry. Left in place only to keep this
+    // change off the file path; removing it is tracked as a follow-up.
+    if (target.source !== "file") {
+        let stored = null;
+        try {
+            stored = refreshAccount(target.source, target.configDir);
+        }
+        catch {
+            stored = null;
+        }
+        if (stored &&
+            stored.accessToken !== creds.accessToken &&
+            stored.expiresAt > Date.now() + 60_000) {
+            target.credentials = stored;
+            log("refresh_adopted_external", { source: target.source });
+            return stored;
+        }
+    }
     log("refresh_fallback_cli", { source: target.source });
     const isSuffixedAccount = target.source !== PRIMARY_SERVICE &&
         target.source.startsWith(PRIMARY_SERVICE + "-");
@@ -267,6 +409,7 @@ export function refreshIfNeeded(account) {
         const fallback = tryFallbackAccount(target.source);
         if (fallback) {
             target.credentials = fallback;
+            borrowedCredentialAccounts.add(target);
             return fallback;
         }
         log("refresh_exhausted", {
@@ -295,6 +438,62 @@ export function refreshIfNeeded(account) {
     });
     return null;
 }
+/**
+ * Refresh path for an account running on borrowed credentials. The tokens it
+ * currently holds belong to another account, so they cannot be exchanged at
+ * the OAuth endpoint on this account's behalf, and the result must never be
+ * written to this account's store. Re-read our own source first — the claude
+ * CLI or another process may have repaired it — and otherwise borrow again.
+ */
+async function refreshBorrowedAccount(target) {
+    log("refresh_borrowed", { source: target.source });
+    let own = null;
+    try {
+        own = refreshAccount(target.source, target.configDir);
+    }
+    catch {
+        own = null;
+    }
+    if (own && own.expiresAt > Date.now() + 60_000) {
+        borrowedCredentialAccounts.delete(target);
+        target.credentials = own;
+        log("refresh_borrowed_recovered", { source: target.source, via: "source" });
+        return own;
+    }
+    // A refresh token outlives its access token by weeks, so this account's
+    // own stored token is likely still exchangeable even though the access
+    // token it came with has expired. This is the only token we may present
+    // on its behalf, and the only result we may write to its store.
+    if (own?.refreshToken) {
+        const oauthCreds = await refreshViaOAuth(own.refreshToken);
+        if (oauthCreds && oauthCreds.expiresAt > Date.now() + 60_000) {
+            borrowedCredentialAccounts.delete(target);
+            target.credentials = oauthCreds;
+            writeBackCredentials(target.source, oauthCreds, target.configDir, own.accessToken);
+            log("refresh_borrowed_recovered", { source: target.source, via: "oauth" });
+            return oauthCreds;
+        }
+    }
+    const again = tryFallbackAccount(target.source);
+    if (again) {
+        target.credentials = again;
+        return again;
+    }
+    // Recovery failed. The account must not be left holding the lender's
+    // tokens, or the next cycle would take the normal path and exchange them.
+    // Restore its own credentials if we managed to read them — expired, but
+    // ours to refresh — and otherwise keep the guard in place.
+    if (own) {
+        borrowedCredentialAccounts.delete(target);
+        target.credentials = own;
+    }
+    log("refresh_exhausted", {
+        source: target.source,
+        hadCredentials: !!own,
+        expiresAt: own?.expiresAt,
+    });
+    return null;
+}
 function tryFallbackAccount(excludeSource) {
     const now = Date.now();
     const candidates = allAccounts.filter((a) => a.source !== excludeSource);
@@ -344,16 +543,22 @@ export function getCredentialsForSync() {
 }
 /**
  * Re-read only the active account's credentials from its source (single
- * keychain service read or credentials file) and update them in place.
- * Used on 401 so an externally refreshed token is picked up without a
- * full multi-account keychain rescan.
+ * keychain service read or credentials file) and update them in place,
+ * so an externally refreshed token is picked up without a full
+ * multi-account keychain rescan.
+ *
+ * Currently has no call sites: the 401 path uses
+ * reloadCredentialsFromSource, which additionally validates the result
+ * and refreshes the cache. Wiring this up or deleting it is tracked as a
+ * follow-up; until then it must stay consistent with the read paths that
+ * are live, hence the configDir below.
  */
 export function reloadActiveAccount() {
     const account = getActiveAccount();
     if (!account)
         return;
     try {
-        const fresh = refreshAccount(account.source);
+        const fresh = refreshAccount(account.source, account.configDir);
         if (fresh)
             account.credentials = fresh;
     }
@@ -371,16 +576,28 @@ export function reloadActiveAccount() {
  * On success the account, its source, and the cache are all updated.
  * The refresh function is injectable for tests.
  */
-export function forceRefreshActiveAccount(refresh = refreshViaOAuth) {
+export async function forceRefreshActiveAccount(refresh = refreshViaOAuth) {
     const account = getActiveAccount();
     if (!account?.credentials.refreshToken)
         return null;
-    const oauthCreds = refresh(account.credentials.refreshToken);
+    // These tokens belong to another account: exchanging them here would
+    // rotate the lender's refresh token and persist the result to this
+    // account's store. Borrowed-account recovery belongs to refreshIfNeeded.
+    if (borrowedCredentialAccounts.has(account)) {
+        log("force_refresh_skipped_borrowed", { source: account.source });
+        return null;
+    }
+    const priorAccessToken = account.credentials.accessToken;
+    const oauthCreds = await refresh(account.credentials.refreshToken);
     if (oauthCreds && oauthCreds.expiresAt > Date.now() + 60_000) {
         account.credentials = oauthCreds;
-        if (!writeBackCredentials(account.source, oauthCreds)) {
-            // Session continues from memory/cache; a later source re-read may
-            // resurrect the rejected token and trigger another refresh.
+        if (!writeBackCredentials(account.source, oauthCreds, account.configDir, priorAccessToken)) {
+            // Session continues from memory/cache either way, but the two causes
+            // diverge on a later source re-read. An I/O failure leaves our own
+            // rejected token in the store, so the re-read resurrects it and
+            // triggers another refresh. A CAS mismatch means the store now holds
+            // another account's token, so the re-read adopts that instead and this
+            // account stops using the credentials it just refreshed.
             log("force_refresh_writeback_failed", { source: account.source });
         }
         accountCacheMap.set(account.source, {
@@ -405,7 +622,7 @@ export function invalidateCredentialCache() {
         log("cache_invalidated", { source: account.source });
     }
 }
-export function getCachedCredentials() {
+export async function getCachedCredentials() {
     const account = getActiveAccount();
     if (!account)
         return null;
@@ -424,13 +641,13 @@ export function getCachedCredentials() {
         source: account.source,
         reason: cached ? "stale or expiring" : "empty",
     });
-    const fresh = refreshIfNeeded(account);
+    const fresh = await refreshIfNeeded(account);
     if (!fresh) {
         log("credentials_unavailable", { source: account.source });
         accountCacheMap.delete(account.source);
         return null;
     }
-    accountCacheMap.set(account.source, { creds: fresh, cachedAt: now });
+    accountCacheMap.set(account.source, { creds: fresh, cachedAt: Date.now() });
     return fresh;
 }
 export function reloadCredentialsFromSource() {
@@ -439,7 +656,9 @@ export function reloadCredentialsFromSource() {
         return null;
     let reloaded;
     try {
-        reloaded = refreshAccount(account.source);
+        // Same configDir the write path resolves, so the compare-and-swap in
+        // writeBackCredentials compares against the file this read came from.
+        reloaded = refreshAccount(account.source, account.configDir);
     }
     catch {
         accountCacheMap.delete(account.source);
@@ -467,6 +686,13 @@ export function reloadCredentialsFromSource() {
         return null;
     }
     account.credentials = reloaded;
+    // Read from this account's own source, so what it returned is this
+    // account's own credentials — it is no longer running on a lender's.
+    // Same invariant as refreshIfNeeded's up-front re-read: leaving the flag
+    // set here makes forceRefreshActiveAccount decline to exchange a token
+    // that is legitimately this account's, which strands the 401 recovery
+    // loop's second attempt on a credential it could have refreshed.
+    borrowedCredentialAccounts.delete(account);
     accountCacheMap.set(account.source, { creds: reloaded, cachedAt: now });
     log("credentials_source_reload", {
         source: account.source,