@indigoai-us/hq-cli 5.345.109 → 5.345.111

package/dist/lib/capacity/collectors/claude-oauth.js

@@ -5,10 +5,26 @@
  * `Claude Code-credentials`, plus `Claude Code-credentials-<hash>` seats,
  * or the credentials JSON under ~/.claude/ on Linux). GETs
  * https://api.anthropic.com/api/oauth/usage with the oauth-2025-04-20 beta
- * header. This module does not refresh the token, write the Keychain or
- * ~/.claude, call an OAuth token endpoint, or invoke the claude CLI except
+ * header. This module does not invoke the claude CLI except
  * `claude --version` when the caller does not pass cliVersion.
  *
+ * US-014 wires in a token-refresh gate. The gate uses two seams,
+ * `defaultListLiveLanes` and `defaultListProcesses`, to decide whether a
+ * refresh is safe (no running Claude Code holds the home). Both seams
+ * FAIL CLOSED: an error, a timeout, or an unexpected JSON shape returns an
+ * error-signalling throw and the caller records `skipped-live` /
+ * `skipped-process` and does NOT rotate the refresh token.
+ *
+ * Residual blind spot on darwin: `ps -axo pid=,command=` cannot read a
+ * child process's environment, so on darwin a running `claude` process is
+ * conservatively treated as holding the DEFAULT home AND blocking any
+ * non-default home refresh. A sibling that sets `CLAUDE_CONFIG_DIR` to a
+ * different home still blocks the gate; this is the safe side of the
+ * precision/safety tradeoff. On linux `/proc/<pid>/environ` lets the gate
+ * read the per-process `CLAUDE_CONFIG_DIR`, so it only blocks the matching
+ * home. Windows and other platforms get no process gate; the lane gate is
+ * authoritative there.
+ *
  * The legacy shape (seven_day_opus populated, no limits[]) is drift.
  * observedAt is the response time. One collect appends every account's
  * readings and failures in one rebuild.
@@ -18,7 +34,7 @@ import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { DIR_MODE, FILE_MODE, appendReadings, capacityRoot, EXPIRED_REASON, readCollectorMark, } from "../ledger.js";
+import { DIR_MODE, FILE_MODE, appendReadings, capacityRoot, EXPIRED_REASON, SIGN_IN_REVOKED_REASON, readCollectorMark, redactProviderTokens, } from "../ledger.js";
 import { hashClaudeAccountId } from "./claude-statusline.js";
 export const CLAUDE_OAUTH_PARSER_VERSION = "claude-oauth-usage.1";
 export const CLAUDE_OAUTH_PROVIDER = "claude";
@@ -36,6 +52,17 @@ export const CLAUDE_OAUTH_FETCH_TIMEOUT_MS = 10_000;
 export const CLAUDE_OAUTH_SECURITY_TIMEOUT_MS = 5_000;
 export const CLAUDE_OAUTH_POLL_FILE = "claude-oauth-last-call.json";
 export const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+/** Claude Code's refresh endpoint. The URL and the client_id are the ones Claude Code itself posts. */
+export const CLAUDE_OAUTH_REFRESH_URL = "https://console.anthropic.com/v1/oauth/token";
+export const CLAUDE_OAUTH_REFRESH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+/** Minimum gap between refresh attempts for one home when the previous attempt did not revoke. */
+export const CLAUDE_OAUTH_REFRESH_BACKOFF_MS = 10 * 60 * 1000;
+/** Minimum gap between refresh attempts for one home after an invalid_grant. */
+export const CLAUDE_OAUTH_REFRESH_REVOKED_BACKOFF_MS = 60 * 60 * 1000;
+/** Try a refresh when the token is this close to expiry, so one tick does not land on a stale token. */
+export const CLAUDE_OAUTH_REFRESH_PREFLIGHT_MS = 10 * 60 * 1000;
+export const CLAUDE_OAUTH_REFRESH_TIMEOUT_MS = 10_000;
+export const CLAUDE_OAUTH_REFRESH_LAST_FILE = "claude-oauth-refresh-last.json";
 const SESSION_MINUTES = 5 * 60;
 const WEEKLY_MINUTES = 7 * 24 * 60;
 const ACCOUNT_ID_KEYS = [
@@ -190,19 +217,59 @@ export async function collectClaudeOAuth(options = {}) {
         if (pollIsFresh(root, account.accountId, nowMs))
             continue;
         writeAccountPoll(root, account.accountId, new Date(nowMs).toISOString());
-        if (account.blocked) {
-            failures.push(failure(mapContext, credentialBlockReason(account.blocked)));
+        const meta = account.metadata;
+        let currentToken = account.token;
+        let currentBlocked = account.blocked;
+        // Honour the persisted revoked marker, but only when its fingerprint
+        // matches the refresh token we are about to use. A stale marker means the
+        // human signed in again and the token rotated; clear it and proceed. A
+        // match means the account is still signed out from the perspective of
+        // the token we hold.
+        const revokedMarker = revokedMarkerForCurrentCredential(root, account.accountId, meta.refreshToken);
+        if (revokedMarker === "match") {
+            currentBlocked = SIGN_IN_REVOKED_REASON;
+        }
+        else if (revokedMarker === "stale") {
+            clearAccountRevoked(root, account.accountId);
+        }
+        const needsRefresh = (currentBlocked === EXPIRED_REASON
+            || currentBlocked === "unavailable: token_expired"
+            || shouldAttemptRefresh(meta.expiresAt, nowMs))
+            && !!meta.refreshToken
+            && currentBlocked !== SIGN_IN_REVOKED_REASON;
+        if (needsRefresh) {
+            const refreshResult = await maybeRefreshAccount({
+                options,
+                root,
+                home: meta.home,
+                service: meta.service,
+                platform: meta.platform,
+                refreshToken: meta.refreshToken,
+                expiresAt: meta.expiresAt,
+                previousDocument: meta.credentialDocument,
+                nowMs,
+            });
+            if (refreshResult?.outcome === "refreshed" && refreshResult.newAccessToken) {
+                currentToken = refreshResult.newAccessToken;
+                currentBlocked = undefined;
+            }
+            else if (refreshResult?.outcome === "revoked" || refreshResult?.outcome === "skipped-revoked") {
+                currentBlocked = SIGN_IN_REVOKED_REASON;
+                markAccountRevoked(root, account.accountId, nowMs, meta.refreshToken);
+            }
+        }
+        if (currentBlocked) {
+            failures.push(failure(mapContext, credentialBlockReason(currentBlocked)));
             continue;
         }
-        const token = account.token;
-        if (!token)
+        if (!currentToken)
             continue;
         fetched = true;
         let status;
         let text;
         let retryAfter;
         try {
-            const response = await fetchImpl(endpoint, usageInit(token));
+            const response = await fetchImpl(endpoint, usageInit(currentToken));
             status = response.status;
             retryAfter = response.headers?.get("retry-after") ?? null;
             text = status === 200 ? await response.text() : "";
@@ -214,9 +281,13 @@ export async function collectClaudeOAuth(options = {}) {
         if (httpStatus === null)
             httpStatus = status;
         if (status === 401 || status === 403) {
-            failures.push(failure(mapContext, "signed out: auth rejected"));
+            failures.push(failure(mapContext, SIGN_IN_REVOKED_REASON));
+            markAccountRevoked(root, account.accountId, nowMs, meta.refreshToken);
             continue;
         }
+        if (status === 200) {
+            clearAccountRevoked(root, account.accountId);
+        }
         if (status === 429 || status >= 500) {
             failures.push(failure(mapContext, `unavailable: http ${status}`));
             noteHttpBackoff(root, account.accountId, nowMs, retryAfter);
@@ -303,6 +374,57 @@ async function collectEnumeratedClaude(options, scoped, root, clock, cliVersion)
             accountHome: home,
             organization: null,
         };
+        // Honour the persisted revoked marker. A matching fingerprint means the
+        // same refresh token is still in play; block before we spend a refresh or
+        // usage round trip. A stale fingerprint means the human signed in again
+        // (the token rotated); clear the marker and proceed. Without this check
+        // the usage-401 writer below would be dead on this path once a marker
+        // was set, because every subsequent collect would still land on 401.
+        const enumRevokedMarker = revokedMarkerForCurrentCredential(root, account.accountId, account.refreshToken);
+        if (enumRevokedMarker === "match") {
+            account.blocked = SIGN_IN_REVOKED_REASON;
+        }
+        else if (enumRevokedMarker === "stale") {
+            clearAccountRevoked(root, account.accountId);
+        }
+        // Refresh gate: fire before the usage fetch when the stored token is
+        // expired or close to expiry. Successful refresh clears the block and
+        // lets the usage fetch proceed with the new token.
+        const needsRefresh = (account.blocked === EXPIRED_REASON
+            || account.blocked === "unavailable: token_expired"
+            || shouldAttemptRefresh(account.expiresAt, nowMs))
+            && account.refreshToken
+            && account.blocked !== SIGN_IN_REVOKED_REASON;
+        if (needsRefresh) {
+            const refreshResult = await maybeRefreshAccount({
+                options,
+                root,
+                home,
+                service: account.service,
+                platform: account.platform,
+                refreshToken: account.refreshToken,
+                expiresAt: account.expiresAt,
+                previousDocument: account.credentialDocument,
+                nowMs,
+            });
+            if (refreshResult) {
+                if (refreshResult.outcome === "refreshed" && refreshResult.newAccessToken) {
+                    account.token = refreshResult.newAccessToken;
+                    account.blocked = null;
+                    if (refreshResult.newExpiresAt !== undefined)
+                        account.expiresAt = refreshResult.newExpiresAt;
+                    if (refreshResult.newRefreshToken)
+                        account.refreshToken = refreshResult.newRefreshToken;
+                    if (refreshResult.newScopes && refreshResult.newScopes.length > 0)
+                        account.scopes = refreshResult.newScopes;
+                }
+                else if (refreshResult.outcome === "revoked" || refreshResult.outcome === "skipped-revoked") {
+                    account.blocked = SIGN_IN_REVOKED_REASON;
+                    markAccountRevoked(root, account.accountId, nowMs, account.refreshToken);
+                }
+                // Other outcomes (skipped-live/process/race/backoff, error) keep whatever block the parser set.
+            }
+        }
         if (account.blocked) {
             failures.push(failure(mapContext, account.blocked));
             continue;
@@ -331,9 +453,13 @@ async function collectEnumeratedClaude(options, scoped, root, clock, cliVersion)
         if (httpStatus === null)
             httpStatus = status;
         if (status === 401 || status === 403) {
-            failures.push(failure(mapContext, "signed out: auth rejected"));
+            failures.push(failure(mapContext, SIGN_IN_REVOKED_REASON));
+            markAccountRevoked(root, account.accountId, nowMs, account.refreshToken);
             continue;
         }
+        if (status === 200) {
+            clearAccountRevoked(root, account.accountId);
+        }
         if (status === 429 || status >= 500) {
             failures.push(failure(mapContext, `unavailable: http ${status}`));
             noteHttpBackoff(root, account.accountId, nowMs, retryAfter);
@@ -389,8 +515,9 @@ function primaryLabel(labels) {
 async function readEnumeratedHome(group, options, nowMs, root) {
     const labels = [...group.labels];
     const platform = options.platform ?? process.platform;
+    const service = platform === "darwin" ? claudeKeychainServiceName(group.home) : null;
     const seat = platform === "darwin"
-        ? `keychain:${claudeKeychainServiceName(group.home)}`
+        ? `keychain:${service}`
         : `file:${path.resolve(group.home)}`;
     const accountId = hashClaudeAccountId(seat);
     if (homeKeychainBlocked(root, group.home, nowMs)) {
@@ -402,6 +529,12 @@ async function readEnumeratedHome(group, options, nowMs, root) {
             planType: null,
             blocked: "unavailable: keychain",
             keychain: "timeout",
+            refreshToken: null,
+            expiresAt: null,
+            credentialDocument: null,
+            scopes: null,
+            service,
+            platform,
         };
     }
     if (pollIsFresh(root, accountId, nowMs)) {
@@ -413,55 +546,61 @@ async function readEnumeratedHome(group, options, nowMs, root) {
             planType: null,
             blocked: null,
             keychain: "no-prompt",
+            refreshToken: null,
+            expiresAt: null,
+            credentialDocument: null,
+            scopes: null,
+            service,
+            platform,
         };
     }
     if (platform === "darwin")
-        return readEnumeratedKeychain(group, labels, options, nowMs, root);
-    return readEnumeratedFile(group, labels, nowMs);
+        return readEnumeratedKeychain(group, labels, options, nowMs, root, service, platform);
+    return readEnumeratedFile(group, labels, nowMs, platform);
 }
-function readEnumeratedFile(group, labels, nowMs) {
+function readEnumeratedFile(group, labels, nowMs, platform) {
     const file = path.join(group.home, ".credentials.json");
     let text;
     try {
         text = fs.readFileSync(file, "utf8");
     }
     catch {
-        return blockedCredential(group, labels, "signed out: credential missing", "error");
+        return blockedCredential(group, labels, "signed out: credential missing", "error", null, platform);
     }
     const parsed = parseCredentialDocument(text, `file:${path.resolve(group.home)}`, nowMs, "underlying");
     if (!parsed || parsed.length === 0) {
-        return blockedCredential(group, labels, "signed out: credential unreadable", "error");
+        return blockedCredential(group, labels, "signed out: credential unreadable", "error", null, platform);
     }
-    return outcomeCredential(group, labels, parsed[0], "no-prompt");
+    return outcomeCredential(group, labels, parsed[0], "no-prompt", null, platform);
 }
-async function readEnumeratedKeychain(group, labels, options, nowMs, root) {
-    const service = claudeKeychainServiceName(group.home);
+async function readEnumeratedKeychain(group, labels, options, nowMs, root, service, platform) {
+    const keychainService = service ?? claudeKeychainServiceName(group.home);
     const username = os.userInfo().username;
-    let read = await callSecurity(options, ["find-generic-password", "-s", service, "-a", username, "-w"], CLAUDE_OAUTH_SECURITY_TIMEOUT_MS);
+    let read = await callSecurity(options, ["find-generic-password", "-s", keychainService, "-a", username, "-w"], CLAUDE_OAUTH_SECURITY_TIMEOUT_MS);
     let status = classifySecurity(read);
     if (status === "prompt" || status === "timeout") {
         noteKeychainBackoff(root, group.home, nowMs);
-        return blockedCredential(group, labels, "unavailable: keychain", status);
+        return blockedCredential(group, labels, "unavailable: keychain", status, keychainService, platform);
     }
     if (isKeychainMiss(read)) {
-        read = await callSecurity(options, ["find-generic-password", "-s", service, "-w"], CLAUDE_OAUTH_SECURITY_TIMEOUT_MS);
+        read = await callSecurity(options, ["find-generic-password", "-s", keychainService, "-w"], CLAUDE_OAUTH_SECURITY_TIMEOUT_MS);
         status = classifySecurity(read);
         if (status === "prompt" || status === "timeout") {
             noteKeychainBackoff(root, group.home, nowMs);
-            return blockedCredential(group, labels, "unavailable: keychain", status);
+            return blockedCredential(group, labels, "unavailable: keychain", status, keychainService, platform);
         }
     }
     if (status !== "no-prompt") {
         const reason = isKeychainMiss(read) ? "signed out: credential missing" : "signed out: credential unreadable";
-        return blockedCredential(group, labels, reason, "error");
+        return blockedCredential(group, labels, reason, "error", keychainService, platform);
     }
-    const parsed = parseCredentialDocument(read.stdout.replace(/\n$/, ""), `keychain:${service}`, nowMs, "underlying");
+    const parsed = parseCredentialDocument(read.stdout.replace(/\n$/, ""), `keychain:${keychainService}`, nowMs, "underlying");
     if (!parsed || parsed.length === 0) {
-        return blockedCredential(group, labels, "signed out: credential unreadable", "error");
+        return blockedCredential(group, labels, "signed out: credential unreadable", "error", keychainService, platform);
     }
-    return outcomeCredential(group, labels, parsed[0], "no-prompt");
+    return outcomeCredential(group, labels, parsed[0], "no-prompt", keychainService, platform);
 }
-function blockedCredential(group, labels, reason, keychain) {
+function blockedCredential(group, labels, reason, keychain, service, platform) {
     return {
         accountId: hashClaudeAccountId(`missing:${path.resolve(group.home)}`),
         labels,
@@ -470,11 +609,18 @@ function blockedCredential(group, labels, reason, keychain) {
         planType: null,
         blocked: reason,
         keychain,
+        refreshToken: null,
+        expiresAt: null,
+        credentialDocument: null,
+        scopes: null,
+        service,
+        platform,
     };
 }
-function outcomeCredential(group, labels, outcome, keychain) {
-    if (!outcome)
-        return blockedCredential(group, labels, "signed out: credential unreadable", "error");
+function outcomeCredential(group, labels, outcome, keychain, service, platform) {
+    if (!outcome) {
+        return blockedCredential(group, labels, "signed out: credential unreadable", "error", service, platform);
+    }
     const blocked = outcome.blocked ? credentialBlockReason(outcome.blocked) : null;
     return {
         accountId: outcome.accountId,
@@ -484,6 +630,12 @@ function outcomeCredential(group, labels, outcome, keychain) {
         planType: outcome.planType,
         blocked,
         keychain,
+        refreshToken: outcome.metadata.refreshToken,
+        expiresAt: outcome.metadata.expiresAt,
+        credentialDocument: outcome.metadata.credentialDocument,
+        scopes: outcome.metadata.scopes,
+        service,
+        platform,
     };
 }
 function credentialBlockReason(blocked) {
@@ -518,6 +670,21 @@ function mergeEnumerated(loaded) {
             existing.blocked = account.blocked;
             existing.planType = account.planType;
         }
+        if (!existing.refreshToken && account.refreshToken) {
+            existing.refreshToken = account.refreshToken;
+        }
+        if (existing.expiresAt === null && account.expiresAt !== null) {
+            existing.expiresAt = account.expiresAt;
+        }
+        if (!existing.credentialDocument && account.credentialDocument) {
+            existing.credentialDocument = account.credentialDocument;
+        }
+        if (!existing.scopes && account.scopes) {
+            existing.scopes = account.scopes;
+        }
+        if (!existing.service && account.service) {
+            existing.service = account.service;
+        }
     }
     return merged;
 }
@@ -719,6 +886,7 @@ export function claudeSeatAccountId(seat, orgId) {
     return hashClaudeAccountId(material);
 }
 function loadAccounts(options, nowMs) {
+    const platform = options.platform ?? process.platform;
     if (options.readCredentials) {
         const read = options.readCredentials();
         return {
@@ -726,13 +894,19 @@ function loadAccounts(options, nowMs) {
             store: "injected",
             seat: "injected",
             failures: [],
-            accounts: read.accounts.map((account) => classifyAccount(account, nowMs)),
+            accounts: read.accounts.map((account) => {
+                const home = account.home ?? null;
+                const service = platform === "darwin" && home ? claudeKeychainServiceName(home) : "";
+                return classifyAccount(account, nowMs, home, service, platform);
+            }),
         };
     }
-    if (options.credentialsPath || (options.platform ?? process.platform) !== "darwin") {
+    if (options.credentialsPath || platform !== "darwin") {
         const file = options.credentialsPath ?? defaultClaudeCredentialsPath(options.ledger?.home);
         const seat = `file:${path.basename(file)}`;
-        const read = readCredentialFile(file, seat, nowMs);
+        const home = path.dirname(file);
+        const service = platform === "darwin" ? claudeKeychainServiceName(home) : "";
+        const read = readCredentialFile(file, seat, nowMs, home, service, platform);
         if ("error" in read) {
             return { keychain: "error", accounts: [], failures: [], store: "file", seat };
         }
@@ -740,23 +914,34 @@ function loadAccounts(options, nowMs) {
     }
     const file = defaultClaudeCredentialsPath(options.ledger?.home);
     const seat = `file:${path.basename(file)}`;
-    const read = readCredentialFile(file, seat, nowMs);
+    const home = path.dirname(file);
+    const service = platform === "darwin" ? claudeKeychainServiceName(home) : "";
+    const read = readCredentialFile(file, seat, nowMs, home, service, platform);
     if ("error" in read) {
         return { keychain: "error", accounts: [], failures: [], store: "file", seat };
     }
     return { keychain: "no-prompt", accounts: read.accounts, failures: [], store: "file", seat };
 }
-function classifyAccount(account, nowMs) {
+function classifyAccount(account, nowMs, home = account.home ?? null, service = "", platform = process.platform) {
     const planType = account.planType ?? null;
+    const metadata = {
+        refreshToken: account.refreshToken ?? null,
+        expiresAt: account.expiresAt ?? null,
+        credentialDocument: account.credentialDocument ?? null,
+        scopes: account.scopes ?? null,
+        home,
+        service,
+        platform,
+    };
     if (isExpired(account.expiresAt ?? null, nowMs)) {
-        return { blocked: "unavailable: token_expired", accountId: account.accountId, planType };
+        return { blocked: "unavailable: token_expired", accountId: account.accountId, planType, metadata };
     }
     if (!hasProfileScope(account.scopes)) {
-        return { blocked: "unavailable: missing_scope", accountId: account.accountId, planType };
+        return { blocked: "unavailable: missing_scope", accountId: account.accountId, planType, metadata };
     }
-    return { token: account.token, accountId: account.accountId, planType };
+    return { token: account.token, accountId: account.accountId, planType, metadata };
 }
-function readCredentialFile(file, seat, nowMs) {
+function readCredentialFile(file, seat, nowMs, home, service, platform) {
     let text;
     try {
         text = fs.readFileSync(file, "utf8");
@@ -764,12 +949,12 @@ function readCredentialFile(file, seat, nowMs) {
     catch {
         return { error: "missing" };
     }
-    const accounts = parseCredentialDocument(text, seat, nowMs);
+    const accounts = parseCredentialDocument(text, seat, nowMs, "seat", home, service, platform);
     if (!accounts || accounts.length === 0)
         return { error: "invalid" };
     return { accounts };
 }
-function parseCredentialDocument(text, seat, nowMs, identity = "seat") {
+function parseCredentialDocument(text, seat, nowMs, identity = "seat", home = null, service = "", platform = process.platform) {
     let parsed;
     try {
         parsed = JSON.parse(text);
@@ -790,6 +975,9 @@ function parseCredentialDocument(text, seat, nowMs, identity = "seat") {
         : (typeof oauth.access_token === "string" ? oauth.access_token : "");
     if (!token)
         return [];
+    const refreshToken = typeof oauth.refreshToken === "string" && oauth.refreshToken.trim()
+        ? oauth.refreshToken
+        : (typeof oauth.refresh_token === "string" && oauth.refresh_token.trim() ? oauth.refresh_token : null);
     const orgId = findAccountId(oauth);
     // A profile or credential account id is the seat. An organization id is
     // not: two people in one org must stay two accounts. With no account id,
@@ -804,7 +992,16 @@ function parseCredentialDocument(text, seat, nowMs, identity = "seat") {
         ? oauth.subscriptionType.trim()
         : (typeof oauth.rateLimitTier === "string" && oauth.rateLimitTier.trim() ? oauth.rateLimitTier.trim() : null);
     const expiresAt = typeof oauth.expiresAt === "number" && Number.isFinite(oauth.expiresAt) ? oauth.expiresAt : null;
-    return [classifyAccount({ token, accountId, expiresAt, scopes, planType }, nowMs)];
+    return [classifyAccount({
+            token,
+            accountId,
+            expiresAt,
+            scopes,
+            planType,
+            refreshToken,
+            credentialDocument: root,
+            home,
+        }, nowMs, home, service, platform)];
 }
 function underlyingAccountRaw(oauth) {
     for (const key of ["accountUuid", "accountId", "account_id", "uuid"]) {
@@ -1208,4 +1405,817 @@ function writePoll(root, state) {
 function isFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value);
 }
+const REFRESH_ERROR_CLASS_VALUES = new Set([
+    "invalid_grant",
+    "revoked",
+    "server_error",
+    "timeout",
+    "network",
+    "shape",
+]);
+const REFRESH_FINGERPRINT_RE = /^[0-9a-f]{16}$/;
+export function claudeOAuthRefreshLastPath(root) {
+    return path.join(root, CLAUDE_OAUTH_REFRESH_LAST_FILE);
+}
+function refreshLastKey(home) {
+    return path.resolve(home);
+}
+/** Not the token: a 16 char sha256 prefix. */
+export function tokenFingerprint(token) {
+    return crypto.createHash("sha256").update(token, "utf8").digest("hex").slice(0, 16);
+}
+function emptyRefreshLast() {
+    return { homes: {}, revokedTokens: {}, revokedAccounts: {} };
+}
+function readRefreshLast(root) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(claudeOAuthRefreshLastPath(root), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return emptyRefreshLast();
+        const record = parsed;
+        const homes = {};
+        if (record.homes && typeof record.homes === "object" && !Array.isArray(record.homes)) {
+            for (const [key, value] of Object.entries(record.homes)) {
+                if (!value || typeof value !== "object" || Array.isArray(value))
+                    continue;
+                const row = value;
+                if (typeof row.attemptedAt !== "string" || typeof row.outcome !== "string")
+                    continue;
+                const entry = {
+                    attemptedAt: row.attemptedAt,
+                    outcome: row.outcome,
+                };
+                if (typeof row.revokedRefreshTokenFingerprint === "string" && REFRESH_FINGERPRINT_RE.test(row.revokedRefreshTokenFingerprint)) {
+                    entry.revokedRefreshTokenFingerprint = row.revokedRefreshTokenFingerprint;
+                }
+                if (typeof row.errorMessage === "string")
+                    entry.errorMessage = row.errorMessage;
+                if (typeof row.errorClass === "string" && REFRESH_ERROR_CLASS_VALUES.has(row.errorClass)) {
+                    entry.errorClass = row.errorClass;
+                }
+                if (typeof row.httpStatus === "number")
+                    entry.httpStatus = row.httpStatus;
+                if (typeof row.backoffUntil === "string")
+                    entry.backoffUntil = row.backoffUntil;
+                if (typeof row.tokenExpiresAt === "string")
+                    entry.tokenExpiresAt = row.tokenExpiresAt;
+                homes[key] = entry;
+            }
+        }
+        const revokedTokens = {};
+        if (record.revokedTokens && typeof record.revokedTokens === "object" && !Array.isArray(record.revokedTokens)) {
+            for (const [key, value] of Object.entries(record.revokedTokens)) {
+                if (typeof value === "string" && REFRESH_FINGERPRINT_RE.test(key))
+                    revokedTokens[key] = value;
+            }
+        }
+        const revokedAccounts = {};
+        if (record.revokedAccounts && typeof record.revokedAccounts === "object" && !Array.isArray(record.revokedAccounts)) {
+            for (const [key, value] of Object.entries(record.revokedAccounts)) {
+                if (typeof value === "string") {
+                    revokedAccounts[key] = { at: value };
+                }
+                else if (value && typeof value === "object" && !Array.isArray(value)) {
+                    const row = value;
+                    if (typeof row.at !== "string")
+                        continue;
+                    const entry = { at: row.at };
+                    if (typeof row.fingerprint === "string" && REFRESH_FINGERPRINT_RE.test(row.fingerprint)) {
+                        entry.fingerprint = row.fingerprint;
+                    }
+                    revokedAccounts[key] = entry;
+                }
+            }
+        }
+        return { homes, revokedTokens, revokedAccounts };
+    }
+    catch {
+        return emptyRefreshLast();
+    }
+}
+function writeRefreshLast(root, data) {
+    fs.mkdirSync(root, { recursive: true, mode: DIR_MODE });
+    try {
+        fs.chmodSync(root, DIR_MODE);
+    }
+    catch {
+        // best-effort on an existing dir
+    }
+    const dest = claudeOAuthRefreshLastPath(root);
+    const body = `${JSON.stringify(data, null, 2)}\n`;
+    const tmp = path.join(root, `.${CLAUDE_OAUTH_REFRESH_LAST_FILE}.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, body, { mode: FILE_MODE });
+    fs.renameSync(tmp, dest);
+    fs.chmodSync(dest, FILE_MODE);
+}
+/** Reads the last refresh outcome for a home. Exposed for the doctor command. */
+export function readClaudeRefreshLast(root, home) {
+    const file = readRefreshLast(root);
+    return file.homes[refreshLastKey(home)] ?? null;
+}
+function refreshInBackoff(entry, nowMs) {
+    if (!entry || !entry.backoffUntil)
+        return false;
+    const at = Date.parse(entry.backoffUntil);
+    return !Number.isNaN(at) && nowMs < at;
+}
+function refreshTokenPersistentlyRevoked(file, token) {
+    if (!token)
+        return false;
+    return Object.prototype.hasOwnProperty.call(file.revokedTokens, tokenFingerprint(token));
+}
+function markAccountRevoked(root, accountId, nowMs, refreshToken) {
+    const file = readRefreshLast(root);
+    const entry = { at: new Date(nowMs).toISOString() };
+    if (refreshToken)
+        entry.fingerprint = tokenFingerprint(refreshToken);
+    file.revokedAccounts[accountId] = entry;
+    writeRefreshLast(root, file);
+}
+function clearAccountRevoked(root, accountId) {
+    const file = readRefreshLast(root);
+    if (!(accountId in file.revokedAccounts))
+        return;
+    delete file.revokedAccounts[accountId];
+    writeRefreshLast(root, file);
+}
+/** @deprecated prefer {@link revokedMarkerForCurrentCredential}; this is the pre-fingerprint shim. */
+export function isAccountRevokedPersisted(root, accountId) {
+    const file = readRefreshLast(root);
+    return Object.prototype.hasOwnProperty.call(file.revokedAccounts, accountId);
+}
+/**
+ * Compare the persisted revoked marker (if any) against the refresh token the
+ * caller is about to use.
+ *
+ * - `"match"`: the marker was written for this exact refresh token. The caller
+ *   must still block (nothing has changed since the account was marked signed
+ *   out).
+ * - `"stale"`: a marker exists but the stored fingerprint does not match the
+ *   current refresh token, meaning the human signed in again and the token
+ *   rotated. The caller should clear the marker and proceed; a fresh 401 will
+ *   re-mark it.
+ * - `"none"`: no marker is persisted.
+ *
+ * A marker written by an older version carries no fingerprint. We treat that
+ * as `"stale"` so a current sign-in can recover; if the token really is still
+ * revoked the usage fetch will set a fingerprinted marker on the next 401.
+ */
+export function revokedMarkerForCurrentCredential(root, accountId, refreshToken) {
+    const file = readRefreshLast(root);
+    const entry = file.revokedAccounts[accountId];
+    if (!entry)
+        return "none";
+    if (!entry.fingerprint)
+        return "stale";
+    if (!refreshToken)
+        return "match";
+    return entry.fingerprint === tokenFingerprint(refreshToken) ? "match" : "stale";
+}
+const defaultRefreshFetch = async (url, init) => {
+    const response = await fetch(url, init);
+    return {
+        status: response.status,
+        text: () => response.text(),
+        headers: { get: (name) => response.headers.get(name) },
+    };
+};
+const defaultWriteClaudeCredentials = async (request) => {
+    if (request.platform === "darwin") {
+        const username = os.userInfo().username;
+        const spawnOpts = {
+            encoding: "utf8",
+            timeout: CLAUDE_OAUTH_SECURITY_TIMEOUT_MS,
+            windowsHide: true,
+        };
+        // Try the strict selector first; fall back to -s only. Record which selector found
+        // the item so the write uses the SAME selector and does not create a second entry.
+        let selector = null;
+        let preRead = spawnSync("security", ["find-generic-password", "-s", request.service, "-a", username, "-w"], spawnOpts);
+        if (preRead.status === 0) {
+            selector = "sa";
+        }
+        else {
+            preRead = spawnSync("security", ["find-generic-password", "-s", request.service, "-w"], spawnOpts);
+            if (preRead.status === 0)
+                selector = "s";
+        }
+        if (selector !== null && typeof preRead.stdout === "string") {
+            try {
+                const parsed = JSON.parse(preRead.stdout.replace(/\n$/, ""));
+                const oauth = parsed.claudeAiOauth && typeof parsed.claudeAiOauth === "object" && !Array.isArray(parsed.claudeAiOauth)
+                    ? parsed.claudeAiOauth
+                    : null;
+                const current = oauth
+                    ? (typeof oauth.refreshToken === "string" ? oauth.refreshToken : (typeof oauth.refresh_token === "string" ? oauth.refresh_token : null))
+                    : null;
+                if (request.previousRefreshToken && current && current !== request.previousRefreshToken) {
+                    return { ok: false, raceDetected: true };
+                }
+            }
+            catch {
+                if (request.previousRefreshToken)
+                    return { ok: false, raceDetected: true };
+            }
+        }
+        else if (request.previousRefreshToken) {
+            // Fail closed: a refresh race check needs a readable prior item.
+            return { ok: false, raceDetected: true };
+        }
+        const body = JSON.stringify(request.document);
+        const writeArgs = selector === "s"
+            ? ["add-generic-password", "-U", "-s", request.service, "-w", body]
+            : ["add-generic-password", "-U", "-s", request.service, "-a", username, "-w", body];
+        const wrote = spawnSync("security", writeArgs, spawnOpts);
+        if (wrote.status !== 0) {
+            const message = redactProviderTokens(`security add-generic-password exit ${wrote.status}: ${wrote.stderr ?? ""}`);
+            return { ok: false, error: message };
+        }
+        return { ok: true };
+    }
+    const file = path.join(request.home, ".credentials.json");
+    let current = null;
+    try {
+        const text = fs.readFileSync(file, "utf8");
+        const parsed = JSON.parse(text);
+        const oauth = parsed.claudeAiOauth && typeof parsed.claudeAiOauth === "object" && !Array.isArray(parsed.claudeAiOauth)
+            ? parsed.claudeAiOauth
+            : null;
+        current = oauth
+            ? (typeof oauth.refreshToken === "string" ? oauth.refreshToken : (typeof oauth.refresh_token === "string" ? oauth.refresh_token : null))
+            : null;
+    }
+    catch {
+        // no prior file is fine, we are writing anew
+    }
+    if (request.previousRefreshToken && current && current !== request.previousRefreshToken) {
+        return { ok: false, raceDetected: true };
+    }
+    try {
+        fs.mkdirSync(request.home, { recursive: true, mode: 0o700 });
+        const body = `${JSON.stringify(request.document, null, 2)}\n`;
+        const tmp = path.join(request.home, `.credentials.json.${process.pid}.tmp`);
+        fs.writeFileSync(tmp, body, { mode: 0o600 });
+        fs.renameSync(tmp, file);
+        try {
+            fs.chmodSync(file, 0o600);
+        }
+        catch {
+            // best-effort on a filesystem that does not honour chmod
+        }
+        return { ok: true };
+    }
+    catch (error) {
+        const message = redactProviderTokens(error instanceof Error ? error.message : "write credentials failed");
+        return { ok: false, error: message };
+    }
+};
+function execHqJson(args) {
+    const result = spawnSync("hq", [...args], {
+        encoding: "utf8",
+        timeout: 5_000,
+        windowsHide: true,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ETIMEDOUT")
+            throw new Error(`hq ${args.join(" ")} timed out`);
+        throw new Error(`hq ${args.join(" ")} failed to spawn: ${result.error.message}`);
+    }
+    if (result.signal)
+        throw new Error(`hq ${args.join(" ")} killed by ${result.signal}`);
+    if (typeof result.status !== "number")
+        throw new Error(`hq ${args.join(" ")} no exit status`);
+    if (result.status !== 0)
+        throw new Error(`hq ${args.join(" ")} exit ${result.status}`);
+    if (!result.stdout)
+        throw new Error(`hq ${args.join(" ")} empty stdout`);
+    try {
+        return JSON.parse(result.stdout);
+    }
+    catch (error) {
+        throw new Error(`hq ${args.join(" ")} invalid JSON: ${error.message}`);
+    }
+}
+/**
+ * Parse `hq lanes list --json` payload into typed rows.
+ * Exported for tests; fail-closed semantics live in defaultListLiveLanes.
+ */
+export function parseLanesListPayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new Error("lanes list: payload is not an object");
+    }
+    const lanes = payload.lanes;
+    if (!Array.isArray(lanes))
+        throw new Error("lanes list: missing lanes array");
+    const out = [];
+    for (const item of lanes) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error("lanes list: row is not an object");
+        }
+        out.push(item);
+    }
+    return out;
+}
+/**
+ * Parse `hq lanes accounts list --json` payload into typed rows.
+ * Exported for tests; fail-closed semantics live in defaultListLiveLanes.
+ */
+export function parseAccountsListPayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        throw new Error("lanes accounts list: payload is not an object");
+    }
+    const accounts = payload.accounts;
+    if (!Array.isArray(accounts))
+        throw new Error("lanes accounts list: missing accounts array");
+    const out = [];
+    for (const item of accounts) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            throw new Error("lanes accounts list: row is not an object");
+        }
+        out.push(item);
+    }
+    return out;
+}
+/**
+ * Join lanes rows against accounts rows to produce LiveLane records.
+ * Exported for tests.
+ */
+export function buildLiveLanesFromPayloads(lanes, accounts) {
+    const homeByAccount = new Map();
+    for (const acct of accounts) {
+        const id = typeof acct.id === "string" ? acct.id : null;
+        if (!id)
+            continue;
+        const effective = typeof acct.effective_home === "string" && acct.effective_home.trim()
+            ? acct.effective_home.trim()
+            : (typeof acct.home === "string" && acct.home.trim() ? acct.home.trim() : null);
+        if (effective)
+            homeByAccount.set(id, effective);
+    }
+    const out = [];
+    for (const row of lanes) {
+        const state = typeof row.state === "string" ? row.state : "";
+        const terminalReason = typeof row.terminal_reason === "string" ? row.terminal_reason : null;
+        const detailsObj = row.terminal_details && typeof row.terminal_details === "object" && !Array.isArray(row.terminal_details)
+            ? row.terminal_details
+            : null;
+        const detailAccount = detailsObj && typeof detailsObj.account === "string" ? detailsObj.account : null;
+        const detailProvider = detailsObj && typeof detailsObj.provider === "string" ? detailsObj.provider : null;
+        const laneAccount = typeof row.account === "string" ? row.account : null;
+        const laneProvider = typeof row.provider === "string" ? row.provider : "";
+        const isLive = state === "running" || state === "queued" || state === "awaiting_input";
+        const isAuthFailed = terminalReason === "provider_auth_failed";
+        if (!isLive && !isAuthFailed)
+            continue;
+        const account = isAuthFailed ? (detailAccount ?? laneAccount) : laneAccount;
+        const provider = (isAuthFailed ? (detailProvider ?? laneProvider) : laneProvider) || "claude";
+        if (provider !== "claude")
+            continue;
+        const home = account ? homeByAccount.get(account) ?? null : null;
+        out.push({ home, account, provider, state, reason: terminalReason, isLive, isAuthFailed });
+    }
+    return out;
+}
+/**
+ * Fail-closed enumeration of live Claude lanes and auth-failed lanes.
+ * Throws on hq call failure or unexpected JSON shape; callers skip the refresh.
+ */
+const defaultListLiveLanes = async () => {
+    const lanesPayload = execHqJson(["lanes", "list", "--json"]);
+    const accountsPayload = execHqJson(["lanes", "accounts", "list", "--json"]);
+    const lanes = parseLanesListPayload(lanesPayload);
+    const accounts = parseAccountsListPayload(accountsPayload);
+    return buildLiveLanesFromPayloads(lanes, accounts);
+};
+/**
+ * Parse `ps -axo pid=,command=` into rows that mention the `claude` executable.
+ * Exported for tests. Returned rows carry `probe: "command-only"` so the gate
+ * knows it cannot read per-process CLAUDE_CONFIG_DIR on darwin.
+ */
+export function parsePsClaudeOutput(stdout) {
+    const out = [];
+    const self = process.pid;
+    for (const rawLine of stdout.split("\n")) {
+        const line = rawLine.replace(/\s+$/, "");
+        if (!line)
+            continue;
+        const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const pid = Number(match[1]);
+        if (!Number.isFinite(pid) || pid === self)
+            continue;
+        const command = match[2];
+        // Match the executable segment only. Avoid "/claude-code/other", "my-claude-wrapper", etc.
+        // Accepts: "claude ...", "/usr/local/bin/claude ...", "node .../claude ..."
+        const exec = /(?:^|\/|\s)claude(?:$|\s)/.test(command) ? "claude" : null;
+        if (!exec)
+            continue;
+        // Skip our own hq subcommands if any ever shell out to `claude ...`
+        if (/\bhq\s+/.test(command))
+            continue;
+        out.push({ pid, env: {}, probe: "command-only" });
+    }
+    return out;
+}
+/**
+ * Fail-closed enumeration of running Claude Code processes.
+ *
+ * linux: /proc/<pid>/environ gives us per-process CLAUDE_CONFIG_DIR; absent
+ *   value means the process holds the default home.
+ * darwin: ps cannot read a child process environment, so we return
+ *   `probe: "command-only"` rows. The gate treats such a row as holding the
+ *   default home AND blocking every non-default home.
+ * other platforms: return []. The lane gate is authoritative there.
+ *
+ * Throws on ps/readdir failure so the caller skips refresh.
+ */
+const defaultListProcesses = async () => {
+    if (process.platform === "linux") {
+        const procDir = "/proc";
+        let entries;
+        try {
+            entries = fs.readdirSync(procDir);
+        }
+        catch (error) {
+            throw new Error(`readdir /proc failed: ${error.message}`);
+        }
+        const out = [];
+        for (const entry of entries) {
+            if (!/^\d+$/.test(entry))
+                continue;
+            const pid = Number(entry);
+            if (pid === process.pid)
+                continue;
+            let cmdline;
+            try {
+                cmdline = fs.readFileSync(path.join(procDir, entry, "cmdline"), "utf8");
+            }
+            catch {
+                continue;
+            }
+            const argv0 = cmdline.split("\0")[0] ?? "";
+            const base = argv0.split("/").pop() ?? "";
+            if (base !== "claude")
+                continue;
+            let envText;
+            try {
+                envText = fs.readFileSync(path.join(procDir, entry, "environ"), "utf8");
+            }
+            catch {
+                // Running process we cannot inspect: fail closed by raising.
+                throw new Error(`read /proc/${entry}/environ failed`);
+            }
+            const match = /(?:^|\0)CLAUDE_CONFIG_DIR=([^\0]+)/.exec(envText);
+            out.push({
+                pid,
+                env: match && match[1] ? { CLAUDE_CONFIG_DIR: match[1] } : {},
+                probe: "env",
+            });
+        }
+        return out;
+    }
+    if (process.platform === "darwin") {
+        const result = spawnSync("ps", ["-axo", "pid=,command="], {
+            encoding: "utf8",
+            timeout: 5_000,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        if (result.error)
+            throw new Error(`ps failed to spawn: ${result.error.message}`);
+        if (result.signal)
+            throw new Error(`ps killed by ${result.signal}`);
+        if (typeof result.status !== "number")
+            throw new Error("ps no exit status");
+        if (result.status !== 0)
+            throw new Error(`ps exit ${result.status}`);
+        return parsePsClaudeOutput(result.stdout ?? "");
+    }
+    return [];
+};
+async function attemptClaudeTokenRefresh(ctx) {
+    const preFile = readRefreshLast(ctx.root);
+    const key = refreshLastKey(ctx.home);
+    const entry = preFile.homes[key];
+    if (refreshInBackoff(entry, ctx.nowMs))
+        return { outcome: "skipped-backoff" };
+    if (refreshTokenPersistentlyRevoked(preFile, ctx.refreshToken))
+        return { outcome: "skipped-revoked" };
+    let liveLanes;
+    try {
+        liveLanes = await ctx.listLiveLanes();
+    }
+    catch (error) {
+        const message = redactProviderTokens(error instanceof Error ? error.message : "listLiveLanes failed");
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "skipped-live-check-failed",
+            errorMessage: message,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "skipped-live-check-failed", errorMessage: message };
+    }
+    const resolvedHome = path.resolve(ctx.home);
+    const sameHome = (candidate) => typeof candidate === "string" && candidate.length > 0 && path.resolve(candidate) === resolvedHome;
+    // Addendum 1: if the lane watcher classified a 401/403 on this home as
+    // provider_auth_failed, treat the account as already signed out and record
+    // revoked immediately. No token endpoint call, no response body stored.
+    const authFailedHere = liveLanes.find((lane) => lane.isAuthFailed && sameHome(lane.home));
+    if (authFailedHere) {
+        const fingerprint = tokenFingerprint(ctx.refreshToken);
+        const now = new Date(ctx.nowMs).toISOString();
+        recordRefresh(ctx.root, key, {
+            attemptedAt: now,
+            outcome: "revoked",
+            errorClass: "revoked",
+            revokedRefreshTokenFingerprint: fingerprint,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_REVOKED_BACKOFF_MS).toISOString(),
+        }, (file) => {
+            file.revokedTokens[fingerprint] = now;
+        });
+        return { outcome: "revoked", errorClass: "revoked" };
+    }
+    if (liveLanes.some((lane) => lane.isLive && sameHome(lane.home))) {
+        recordRefresh(ctx.root, key, { attemptedAt: new Date(ctx.nowMs).toISOString(), outcome: "skipped-live" });
+        return { outcome: "skipped-live" };
+    }
+    let procs;
+    try {
+        procs = await ctx.listProcesses();
+    }
+    catch (error) {
+        const message = redactProviderTokens(error instanceof Error ? error.message : "listProcesses failed");
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "skipped-process-check-failed",
+            errorMessage: message,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "skipped-process-check-failed", errorMessage: message };
+    }
+    const defaultHome = path.join(os.homedir(), ".claude");
+    const isDefaultHome = resolvedHome === path.resolve(defaultHome);
+    const procBlocks = procs.some((proc) => {
+        if (proc.probe === "env") {
+            const dir = typeof proc.env.CLAUDE_CONFIG_DIR === "string" ? proc.env.CLAUDE_CONFIG_DIR : "";
+            // On linux we have a real env read. Default home is held when
+            // CLAUDE_CONFIG_DIR is empty; non-default home only when it points here.
+            if (!dir)
+                return isDefaultHome;
+            return path.resolve(dir) === resolvedHome;
+        }
+        // command-only (darwin): we cannot read the per-process env. Conservatively
+        // treat the row as holding the default home AND blocking non-default homes.
+        return true;
+    });
+    if (procBlocks) {
+        recordRefresh(ctx.root, key, { attemptedAt: new Date(ctx.nowMs).toISOString(), outcome: "skipped-process" });
+        return { outcome: "skipped-process" };
+    }
+    let status;
+    let text;
+    try {
+        const response = await ctx.refreshFetch(ctx.tokenEndpoint, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                Accept: "application/json",
+            },
+            body: JSON.stringify({
+                grant_type: "refresh_token",
+                refresh_token: ctx.refreshToken,
+                client_id: CLAUDE_OAUTH_REFRESH_CLIENT_ID,
+            }),
+            redirect: "manual",
+            signal: AbortSignal.timeout(CLAUDE_OAUTH_REFRESH_TIMEOUT_MS),
+        });
+        status = response.status;
+        try {
+            text = await response.text();
+        }
+        catch {
+            text = "";
+        }
+    }
+    catch (error) {
+        const isTimeout = error instanceof Error
+            && (error.name === "TimeoutError" || error.name === "AbortError" || /timeout/i.test(error.message));
+        const errorClass = isTimeout ? "timeout" : "network";
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "error",
+            errorClass,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "error", errorClass };
+    }
+    // Parse the response body ONLY to classify. The parsed error/error_description
+    // is NEVER persisted; only a fixed classification string and the HTTP status.
+    let parsedErrorField = null;
+    let parsedErrorDescription = null;
+    let bodyIsJson = false;
+    let parsedBody = null;
+    if (text) {
+        try {
+            const maybe = JSON.parse(text);
+            if (maybe && typeof maybe === "object" && !Array.isArray(maybe)) {
+                parsedBody = maybe;
+                bodyIsJson = true;
+                if (typeof parsedBody.error === "string")
+                    parsedErrorField = parsedBody.error;
+                if (typeof parsedBody.error_description === "string")
+                    parsedErrorDescription = parsedBody.error_description;
+            }
+        }
+        catch {
+            // non-JSON body is not stored; we only know we got a status back
+        }
+    }
+    if (status === 400 || status === 401) {
+        const errField = (parsedErrorField ?? "").toLowerCase();
+        const descField = (parsedErrorDescription ?? "").toLowerCase();
+        const revokedHit = errField === "invalid_grant"
+            || /\b(revoked|invalid)\b/.test(errField)
+            || /\b(revoked|invalid)\b/.test(descField);
+        if (revokedHit) {
+            const fingerprint = tokenFingerprint(ctx.refreshToken);
+            const now = new Date(ctx.nowMs).toISOString();
+            const errorClass = errField === "invalid_grant" ? "invalid_grant" : "revoked";
+            recordRefresh(ctx.root, key, {
+                attemptedAt: now,
+                outcome: "revoked",
+                errorClass,
+                revokedRefreshTokenFingerprint: fingerprint,
+                httpStatus: status,
+                backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_REVOKED_BACKOFF_MS).toISOString(),
+            }, (file) => {
+                file.revokedTokens[fingerprint] = now;
+            });
+            return { outcome: "revoked", errorClass, httpStatus: status };
+        }
+    }
+    if (status !== 200) {
+        const errorClass = "server_error";
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "error",
+            errorClass,
+            httpStatus: status,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "error", errorClass, httpStatus: status };
+    }
+    if (!bodyIsJson || !parsedBody) {
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "error",
+            errorClass: "shape",
+            httpStatus: status,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "error", errorClass: "shape", httpStatus: status };
+    }
+    const body = parsedBody;
+    const accessToken = typeof body.access_token === "string" && body.access_token.trim() ? body.access_token : "";
+    if (!accessToken) {
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "error",
+            errorClass: "shape",
+            httpStatus: status,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "error", errorClass: "shape", httpStatus: status };
+    }
+    const newRefresh = typeof body.refresh_token === "string" && body.refresh_token.trim() ? body.refresh_token : ctx.refreshToken;
+    const expiresIn = typeof body.expires_in === "number" && Number.isFinite(body.expires_in) ? body.expires_in : null;
+    if (expiresIn === null) {
+        // Missing expires_in used to fall back to the previous (expired) expiresAt,
+        // which lets a bogus response rotate the stored refresh token forever.
+        // Treat as a failed refresh instead.
+        recordRefresh(ctx.root, key, {
+            attemptedAt: new Date(ctx.nowMs).toISOString(),
+            outcome: "error",
+            errorClass: "shape",
+            httpStatus: status,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "error", errorClass: "shape", httpStatus: status };
+    }
+    const newExpiresAt = ctx.nowMs + expiresIn * 1000;
+    let scopesOut = null;
+    if (Array.isArray(body.scopes)) {
+        scopesOut = body.scopes.filter((s) => typeof s === "string");
+    }
+    else if (typeof body.scope === "string") {
+        scopesOut = body.scope.split(/\s+/).filter((s) => s.length > 0);
+    }
+    const document = buildRefreshedDocument(ctx.previousDocument, {
+        accessToken,
+        refreshToken: newRefresh,
+        expiresAt: newExpiresAt,
+        scopes: scopesOut,
+    });
+    const writeResult = await ctx.writeCredentials({
+        home: ctx.home,
+        service: ctx.service ?? "",
+        platform: ctx.platform,
+        document,
+        previousRefreshToken: ctx.refreshToken,
+    });
+    const now = new Date(ctx.nowMs).toISOString();
+    if (!writeResult.ok && writeResult.raceDetected) {
+        recordRefresh(ctx.root, key, { attemptedAt: now, outcome: "skipped-race" });
+        return { outcome: "skipped-race" };
+    }
+    if (!writeResult.ok) {
+        const message = writeResult.error ?? "writeCredentials failed";
+        recordRefresh(ctx.root, key, {
+            attemptedAt: now,
+            outcome: "error",
+            errorMessage: message,
+            backoffUntil: new Date(ctx.nowMs + CLAUDE_OAUTH_REFRESH_BACKOFF_MS).toISOString(),
+        });
+        return { outcome: "error", errorMessage: message };
+    }
+    const tokenExpiresAt = newExpiresAt !== null && Number.isFinite(newExpiresAt)
+        ? new Date(newExpiresAt < 1e12 ? newExpiresAt * 1000 : newExpiresAt).toISOString()
+        : undefined;
+    recordRefresh(ctx.root, key, { attemptedAt: now, outcome: "refreshed", tokenExpiresAt });
+    return {
+        outcome: "refreshed",
+        newAccessToken: accessToken,
+        newExpiresAt: newExpiresAt ?? undefined,
+        newRefreshToken: newRefresh,
+        newScopes: scopesOut,
+    };
+}
+function recordRefresh(root, key, entry, mutate) {
+    const file = readRefreshLast(root);
+    file.homes[key] = entry;
+    if (mutate)
+        mutate(file);
+    writeRefreshLast(root, file);
+}
+function buildRefreshedDocument(previous, update) {
+    const base = previous ? { ...previous } : {};
+    const existing = base.claudeAiOauth && typeof base.claudeAiOauth === "object" && !Array.isArray(base.claudeAiOauth)
+        ? { ...base.claudeAiOauth }
+        : {};
+    existing.accessToken = update.accessToken;
+    existing.refreshToken = update.refreshToken;
+    if (update.expiresAt !== null)
+        existing.expiresAt = update.expiresAt;
+    if (update.scopes && update.scopes.length > 0)
+        existing.scopes = [...update.scopes];
+    base.claudeAiOauth = existing;
+    return base;
+}
+function expiresAtFromDocument(document) {
+    const oauth = document.claudeAiOauth;
+    if (!oauth || typeof oauth !== "object" || Array.isArray(oauth))
+        return null;
+    const value = oauth.expiresAt;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function shouldAttemptRefresh(expiresAt, nowMs) {
+    if (expiresAt === null)
+        return false;
+    const ms = expiresAt < 1e12 ? expiresAt * 1000 : expiresAt;
+    return ms <= nowMs + CLAUDE_OAUTH_REFRESH_PREFLIGHT_MS;
+}
+/**
+ * Gate wrapper used by both the direct and enumerated collect paths.
+ * Returns null when the gate did not trip (no refresh token, not near expiry,
+ * no home info). Otherwise returns the refresh result.
+ */
+async function maybeRefreshAccount(params) {
+    const { options, root, home, service, platform, refreshToken, expiresAt, previousDocument, nowMs } = params;
+    if (!refreshToken || !home)
+        return null;
+    if (!shouldAttemptRefresh(expiresAt, nowMs))
+        return null;
+    const writeCredentials = options.writeCredentials ?? defaultWriteClaudeCredentials;
+    const refreshFetch = options.refreshFetch ?? defaultRefreshFetch;
+    const tokenEndpoint = options.tokenEndpoint ?? CLAUDE_OAUTH_REFRESH_URL;
+    const listLiveLanes = options.listLiveLanes ?? defaultListLiveLanes;
+    const listProcesses = options.listProcesses ?? defaultListProcesses;
+    return attemptClaudeTokenRefresh({
+        root,
+        home,
+        service,
+        platform,
+        refreshToken,
+        previousDocument,
+        writeCredentials,
+        refreshFetch,
+        tokenEndpoint,
+        listLiveLanes,
+        listProcesses,
+        nowMs,
+    });
+}
 //# sourceMappingURL=claude-oauth.js.map