@timo972/cc-router 0.12.3 → 0.12.4-rc.0

package/CHANGELOG.md

@@ -8,6 +8,47 @@ This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- Accounts whose refresh token the provider rejected permanently are now
+  reported as `re-auth required` in `cc-router accounts list` — in both the
+  live and the stored view — and named once with the command that recovers
+  them. Previously they were indistinguishable from an account holding a
+  merely stale access token, which the next refresh tick replaces on its own.
+  `authExpired` is exposed through the health endpoint and in
+  `cc-router accounts list --json` — with and without a running proxy — for
+  the same reason: both states otherwise read as nothing but a past
+  `expiresAt`.
+
+### Changed
+
+- A permanently rejected OpenAI account is no longer retried on the same
+  credentials. `authExpired` now persists for OpenAI as it already did for
+  Claude, so the rejection survives a restart, and such an account loads
+  quarantined rather than being handed live traffic. Recovery is by
+  re-authentication rather than by a retry that can only fail again.
+
+### Fixed
+
+- Re-authenticating an existing account id while the proxy is running no
+  longer discards the new credentials. `cc-router accounts add` already
+  replaced by id on disk, but the live pool refused the id and the CLI
+  aborted before writing anything — so the OAuth login that had just
+  completed, and the refresh token it minted, were lost. This was the
+  documented recovery for an account needing re-authentication.
+  `POST /cc-router/accounts` accepts an opt-in `replace` flag; without it the
+  endpoint still answers 409, and replacement is refused across providers.
+- A dead OpenAI refresh token no longer generates an OAuth request every five
+  minutes indefinitely. One account produced 1754 identical 401 diagnostics
+  over four days and dominated the proxy log.
+- `cc-router start --accounts <path>` now writes Claude accounts back to that
+  file. Every Anthropic write — token rotation, re-authentication, add, patch,
+  rename, delete, and the shutdown save — targeted the default
+  `~/.cc-router/accounts.json` regardless of the file the pool was loaded from.
+  Rotated refresh tokens therefore never reached the selected file and were
+  lost on the next restart, while the default file was overwritten with a pool
+  it does not describe. OpenAI accounts were already persisted correctly.
+
 ---
 
 ## [0.12.3] — 2026-09-17

package/dist/cli/cmd-accounts.js

@@ -10,6 +10,7 @@ import { loginXaiWithDeviceCode } from "../providers/xai/device-oauth.js";
 import { isValidAccountId } from "../proxy/account-rename.js";
 import { createSetupAttempt, failAttemptFromError, withSetupTelemetryFlush, } from "../telemetry/setup-diagnostics.js";
 import { sanitizeAccountInfo, formatAccountInfo } from "../providers/account-info.js";
+import { needsReauthentication } from "../providers/auth-state.js";
 export function registerAccounts(program) {
     const accounts = program
         .command("accounts")
@@ -43,6 +44,13 @@ export function registerAccounts(program) {
         console.log(chalk.bold(liveStats
             ? `\n  Accounts (${liveStats.length} in the running proxy)\n`
             : `\n  Accounts (${stored.length + openAIStored.length + xaiStored.length} configured)\n`));
+        /**
+         * Accounts only re-authentication can restore, tagged with the provider
+         * whose sign-in command actually recovers them — `accounts add` runs the
+         * Claude Max flow, so pointing an OpenAI or Grok operator at it would
+         * re-add the id under the wrong provider.
+         */
+        const reauthNeeded = [];
         if (liveStats) {
             console.log(chalk.green("  ● Proxy is running — showing live stats\n"));
             for (const s of liveStats) {
@@ -51,9 +59,16 @@ export function registerAccounts(program) {
                     : s.provider === "xai_subscription"
                         ? chalk.magenta("grok".padEnd(9))
                         : chalk.gray("claude".padEnd(9));
-                const status = s.healthy
-                    ? chalk.green("✓ healthy")
-                    : chalk.red("✗ unhealthy");
+                // "unhealthy" covers everything from a five-minute network blip to a
+                // permanently rejected refresh token. Only the latter needs the
+                // operator, so it gets its own label rather than hiding in the crowd.
+                if (needsReauthentication(s))
+                    reauthNeeded.push({ id: s.id, provider: s.provider });
+                const status = needsReauthentication(s)
+                    ? chalk.red("✗ re-auth required")
+                    : s.healthy
+                        ? chalk.green("✓ healthy")
+                        : chalk.red("✗ unhealthy");
                 const busy = s.busy ? chalk.yellow(" [busy]") : "";
                 const exp = s.expiresInMs > 0
                     ? chalk.yellow(formatMs(s.expiresInMs))
@@ -92,19 +107,27 @@ export function registerAccounts(program) {
                 const expColor = a.tokens.expiresAt > Date.now()
                     ? chalk.yellow(exp)
                     : chalk.red(exp);
+                // `authExpired` is persisted, so the dead state is knowable without
+                // the proxy running — and this is exactly when an operator looks.
+                if (needsReauthentication(a))
+                    reauthNeeded.push({ id: a.id, provider: "anthropic_subscription" });
                 console.log(`  ${chalk.bold(a.id.padEnd(24))}` +
                     `  ${redactToken(a.tokens.accessToken).padEnd(26)}` +
                     `  expires: ${expColor}` +
-                    `  scopes: ${chalk.gray(a.tokens.scopes.join(" "))}`);
+                    `  scopes: ${chalk.gray(a.tokens.scopes.join(" "))}` +
+                    (needsReauthentication(a) ? `  ${chalk.red("✗ re-auth required")}` : ""));
             }
             for (const a of openAIStored) {
                 const exp = a.expiresAt > Date.now()
                     ? chalk.yellow(formatExpiry(a.expiresAt))
                     : chalk.red("EXPIRED");
+                if (needsReauthentication(a))
+                    reauthNeeded.push({ id: a.id, provider: "openai_subscription" });
                 console.log(`  ${chalk.bold(a.id.padEnd(24))}` +
                     `  ${chalk.magenta("openai".padEnd(10))}` +
                     `  ${redactToken(a.accessToken).padEnd(26)}` +
-                    `  expires: ${exp}`);
+                    `  expires: ${exp}` +
+                    (needsReauthentication(a) ? `  ${chalk.red("✗ re-auth required")}` : ""));
             }
             for (const a of xaiStored) {
                 const exp = a.expiresAt > Date.now()
@@ -116,6 +139,19 @@ export function registerAccounts(program) {
                     `  expires: ${exp}`);
             }
         }
+        // A dead refresh token is the one failure the router cannot work its way
+        // out of: the refresh loop has deliberately stopped retrying, so nothing
+        // changes until someone re-authenticates. Say so, and say how.
+        if (reauthNeeded.length > 0) {
+            console.log(chalk.red(`\n  ⚠ Needs re-authentication: ${reauthNeeded.map(a => a.id).join(", ")}`));
+            console.log(chalk.gray("    The provider rejected these refresh tokens permanently; they cannot\n"
+                + "    be recovered and the refresh loop has stopped retrying them. Sign in\n"
+                + "    again under the same account id to resume routing — the existing\n"
+                + "    account is replaced, so there is nothing to remove first:"));
+            for (const { id, provider } of reauthNeeded) {
+                console.log(chalk.gray(`      ${reauthCommand(provider)}   (for ${id})`));
+            }
+        }
         console.log();
     });
     // ── accounts add ─────────────────────────────────────────────────────────
@@ -137,8 +173,10 @@ export function registerAccounts(program) {
         ];
         let mode;
         try {
+            // Only `addStored` is overridden: this flow merges by id across the
+            // whole Claude pool. `tryAddLive` must stay the default so the live
+            // pool is asked to replace an existing id rather than reject it.
             ({ mode } = await addAccountRuntimeAware(serialize([account])[0], {
-                tryAddLive: tryAddAccountToRunningProxy,
                 addStored: () => saveAccounts(merged),
             }));
         }
@@ -455,12 +493,14 @@ export function buildStoredAccountsJson(anthropicAccounts, openAIAccounts, xaiAc
             enabled: a.enabled,
             expiresAt: a.tokens.expiresAt,
             scopes: a.tokens.scopes,
+            ...(needsReauthentication(a) ? { authExpired: true } : {}),
         })),
         ...openAIAccounts.map(a => ({
             id: a.id,
             provider: "openai_subscription",
             enabled: a.enabled !== false,
             expiresAt: a.expiresAt,
+            ...(needsReauthentication(a) ? { authExpired: true } : {}),
         })),
         ...xaiAccounts.map(a => ({
             id: a.id,
@@ -587,7 +627,7 @@ export async function tryAddAccountToRunningProxy(record, options = {}) {
                 "content-type": "application/json",
                 ...(authToken ? { authorization: `Bearer ${authToken}` } : {}),
             },
-            body: JSON.stringify(record),
+            body: JSON.stringify(options.replace ? { ...record, replace: true } : record),
             signal: AbortSignal.timeout(3_000),
         });
     }
@@ -611,15 +651,38 @@ export async function tryAddAccountToRunningProxy(record, options = {}) {
  * running the record is handed to it (live pool + disk in one step); otherwise
  * it is written to disk via `addStored` and picked up on the next start.
  */
-export async function addAccountRuntimeAware(record, dependencies = {
-    tryAddLive: tryAddAccountToRunningProxy,
-    addStored: upsertAccountRecord,
-}) {
-    if (await dependencies.tryAddLive(record))
+export async function addAccountRuntimeAware(record, dependencies = {}) {
+    // Each dependency defaults independently. Taking the whole object as one
+    // default meant a caller that only needed its own `addStored` — the Claude
+    // `accounts add` flow does, to merge by id — had to restate `tryAddLive`
+    // too, and that restatement silently dropped the replacement request. The
+    // path that most needs replacement was the one path not asking for it.
+    const tryAddLive = dependencies.tryAddLive
+        // `upsertAccountRecord` already replaces by id on disk; asking the live
+        // pool for the same thing is what keeps the two halves of an `accounts
+        // add` in agreement instead of failing on the account that most needs it.
+        ?? (live => tryAddAccountToRunningProxy(live, { replace: true }));
+    const addStored = dependencies.addStored ?? upsertAccountRecord;
+    if (await tryAddLive(record))
         return { mode: "live" };
-    dependencies.addStored(record);
+    addStored(record);
     return { mode: "stored" };
 }
+/**
+ * The sign-in command that recovers an account of this provider.
+ *
+ * `accounts add` is the Claude Max flow specifically; the other providers have
+ * their own. Each re-registers under the id the operator types, and the live
+ * pool now replaces rather than rejects it, so no deletion step is needed —
+ * which also avoids the running proxy refusing to delete a lone Claude account.
+ */
+function reauthCommand(provider) {
+    if (provider === "openai_subscription")
+        return "cc-router accounts login-openai";
+    if (provider === "xai_subscription")
+        return "cc-router accounts login-grok";
+    return "cc-router accounts add";
+}
 async function fetchLiveStats() {
     try {
         const { proxySecret } = readConfig();

package/dist/config/manager.js

@@ -66,11 +66,23 @@ function writeAccountsAtomicToPath(path, data) {
     // accounts.json holds plaintext OAuth access + refresh tokens — owner-only.
     writeFileSecureSync(path, JSON.stringify(data, null, 2));
 }
-export function writeAnthropicAccountsPreservingOtherProviders(data) {
+/**
+ * Replace the Anthropic records in an accounts file, leaving every other
+ * provider's records in it untouched.
+ *
+ * `path` defaults to `ACCOUNTS_PATH`, but a server started with
+ * `--accounts <path>` must write back to the file it read: sending rotated
+ * refresh tokens to the default file instead loses them on the next restart
+ * *and* overwrites a file describing a different pool. Mirrors
+ * `saveOpenAIAccountsToPath`, which has always taken the path.
+ */
+export function writeAnthropicAccountsPreservingOtherProviders(data, path = ACCOUNTS_PATH) {
     ensureConfigDir();
-    const existing = readAccountsRaw();
+    // Read from the same file being written, or the merge would carry another
+    // file's non-Anthropic records into this one.
+    const existing = readRawFromPath(path);
     const nonAnthropic = existing.filter(a => a.provider !== undefined && a.provider !== "anthropic_subscription");
-    writeAccountsAtomicToPath(ACCOUNTS_PATH, [...data, ...nonAnthropic]);
+    writeAccountsAtomicToPath(path, [...data, ...nonAnthropic]);
 }
 export function upsertAccountRecord(record) {
     ensureConfigDir();
@@ -158,6 +170,9 @@ export function loadOpenAIAccounts(path) {
         refreshToken: a.refreshToken,
         expiresAt: a.expiresAt,
         enabled: a.enabled !== false,
+        // Without this the flag is lost on restart and the dead refresh token is
+        // POSTed again from scratch — the whole point of persisting it.
+        ...(a.authExpired === true ? { authExpired: true } : {}),
         ...(Array.isArray(a.scopes) ? { scopes: a.scopes } : {}),
         ...(a.sessionLimitPercent !== undefined ? { sessionLimitPercent: a.sessionLimitPercent } : {}),
         ...(a.weeklyLimitPercent !== undefined ? { weeklyLimitPercent: a.weeklyLimitPercent } : {}),
@@ -178,6 +193,7 @@ export function saveOpenAIAccountsToPath(accounts, path) {
         expiresAt: a.expiresAt,
         scopes: a.scopes ?? ["openid", "profile", "email", "offline_access"],
         enabled: a.enabled,
+        ...(a.authExpired ? { authExpired: true } : {}),
         ...(a.sessionLimitPercent !== undefined ? { sessionLimitPercent: a.sessionLimitPercent } : {}),
         ...(a.weeklyLimitPercent !== undefined ? { weeklyLimitPercent: a.weeklyLimitPercent } : {}),
     }));

package/dist/providers/auth-state.js

@@ -0,0 +1,9 @@
+/**
+ * True when an account can only be restored by re-authenticating it.
+ *
+ * A bare quarantine is deliberately not enough: a transient rejection also
+ * quarantines, and the next refresh tick can clear it on its own.
+ */
+export function needsReauthentication(account) {
+    return account.authExpired === true || account.authFailure === "permanent";
+}

package/dist/providers/openai/account-state.js

@@ -45,7 +45,11 @@ export function createOpenAIAccount(record) {
         weeklyLimitPercent: record.weeklyLimitPercent !== undefined
             ? clampPercent(record.weeklyLimitPercent)
             : ACCOUNT_USER_DEFAULTS.weeklyLimitPercent,
-        healthy: true,
+        // A record persisted as authExpired must come back out of rotation. The
+        // refresh path deliberately never retries it, so defaulting to healthy
+        // would route live traffic at a token already known to be dead and spend
+        // a request discovering it. Mirrors `deserialize()` on the Anthropic side.
+        healthy: record.authExpired !== true,
         requestCount: 0,
         errorCount: 0,
         consecutiveErrors: 0,
@@ -53,7 +57,9 @@ export function createOpenAIAccount(record) {
         lastRefresh: 0,
         rateLimits,
         modelBuckets: new Map(),
-        authState: "ok",
+        ...(record.authExpired === true
+            ? { authState: "quarantined", authFailure: "permanent" }
+            : { authState: "ok" }),
     };
 }
 /**

package/dist/providers/openai/token-refresher.js

@@ -65,6 +65,13 @@ function persistCredentials(account, allAccounts, saveAccounts) {
         return false;
     }
 }
+/**
+ * True when this account's refresh token was terminally rejected. A refresh
+ * must never be attempted for it — see `authExpired` above.
+ */
+export function isOpenAIAuthExpired(account) {
+    return account.authExpired === true;
+}
 export function needsOpenAIRefresh(account) {
     return account.expiresAt - Date.now() < REFRESH_BUFFER_MS;
 }
@@ -88,6 +95,19 @@ export async function refreshOpenAISubscriptionToken(account) {
 }
 export async function prepareOpenAIAccountForRequest(account, allAccounts, saveAccounts) {
     const runtime = account;
+    // A terminally rejected refresh token can only fail again, and the
+    // quarantine branch below would otherwise retry it on every request and
+    // every scheduled tick — thousands of dead POSTs on one client_id. The way
+    // back is replacement credentials (re-add the account), not another retry.
+    if (isOpenAIAuthExpired(account)) {
+        // The flag itself still has to reach disk. If the write that recorded it
+        // failed, returning here without retrying would strand `authExpired` in
+        // memory, and the next start would POST the dead token all over again —
+        // exactly what persisting it prevents. Cheap: no request goes out.
+        if (hasPendingCredentialWrite(account))
+            persistCredentials(account, allAccounts, saveAccounts);
+        return false;
+    }
     // A revoked but unexpired access token must not bypass the refresh gate.
     if (!needsOpenAIRefresh(account) && runtime.authState !== "quarantined") {
         // No refresh due, but a previous rotation from this account never made it
@@ -112,9 +132,16 @@ export async function prepareOpenAIAccountForRequest(account, allAccounts, saveA
  * turns a successful refresh into a `false` result.
  */
 export async function refreshAndPersistOpenAIAccount(account, allAccounts, saveAccounts) {
+    const wasAuthExpired = isOpenAIAuthExpired(account);
     const ok = await refreshOpenAISubscriptionToken(account);
-    if (ok)
+    // Persist on a rotated credential, and also on a newly terminal rejection:
+    // an `authExpired` that never reaches disk is re-tried from scratch after
+    // every restart, which is how a dead token keeps generating OAuth traffic
+    // for days. A failed write here is best-effort — the flag is still live in
+    // memory for this process, and the next start re-derives it from one POST.
+    if (ok || (!wasAuthExpired && isOpenAIAuthExpired(account))) {
         persistCredentials(account, allAccounts, saveAccounts);
+    }
     return ok;
 }
 /**
@@ -173,6 +200,13 @@ function markRefreshFailure(account, permanent) {
     if (permanent) {
         runtime.authFailure = "permanent";
         runtime.authState = "quarantined";
+        // Tell the operator exactly once. Before this, a dead token produced one
+        // indistinguishable 401 diagnostic line per tick and nothing that said
+        // the account would never recover on its own.
+        if (account.authExpired !== true) {
+            account.authExpired = true;
+            console.error(`  Account ${account.id} needs re-authentication: its refresh token was rejected permanently. Re-add the account to resume routing.`);
+        }
     }
     else if (runtime.authState !== "quarantined") {
         runtime.authFailure = "transient";
@@ -282,6 +316,10 @@ async function doRefresh(account, span) {
         runtime.lastRefresh = Date.now();
     runtime.authState = "ok";
     runtime.authFailure = undefined;
+    // Replacement credentials proved themselves, so the account is no longer
+    // stranded. Written rather than deleted so the cleared state is persisted
+    // over a previously stored `authExpired: true`.
+    account.authExpired = false;
     // The rotated access token can carry a different plan than the one decoded
     // at account creation (e.g. a Plus->Pro upgrade). Mirrors createOpenAIAccount's
     // semantics: only overwrite when the new token actually decodes a plan claim —

package/dist/proxy/account-replace.js

@@ -0,0 +1,108 @@
+import { reserveAccountForDeletion } from "./token-refresher.js";
+import { createOpenAIAccount } from "../providers/openai/account-state.js";
+/**
+ * Replacing an account's credentials in the live pool — what re-authenticating
+ * an existing account id does.
+ *
+ * This exists because a terminally rejected refresh token has exactly one
+ * recovery: install new credentials under the same id. Adding was previously
+ * the only live write, and it refused an id already in the pool, so the OAuth
+ * login the operator had just completed was discarded and its brand-new
+ * refresh token lost. Replacement closes that path.
+ *
+ * Both transactions mutate the live array and persist, rolling the mutation
+ * back if the write throws — the same shape as `addOpenAIAccountTransaction`.
+ * Leaving the pool ahead of disk would let a later whole-pool write persist
+ * credentials the operator never installed.
+ */
+export class AccountReplacementConflictError extends Error {
+    constructor(id) {
+        super(`Account "${id}" changed during replacement`);
+        this.name = "AccountReplacementConflictError";
+    }
+}
+export function accountReplacementStatusCode(error) {
+    return error instanceof AccountReplacementConflictError ? 409 : 500;
+}
+/**
+ * Swap new credentials in under an existing id.
+ *
+ * The reservation is the load-bearing part. A refresh already in flight holds
+ * the *old* refresh token, and on success it writes the rotated result onto
+ * its account object and persists the whole pool. Replacing without waiting
+ * would let that completion land after the swap and put dead credentials back
+ * over the ones just installed. `reserveAccountForDeletion` both waits for
+ * that work and blocks new refreshes for the old object, so the window closes.
+ */
+export async function replaceAnthropicAccountTransaction(options) {
+    const { id } = options.record;
+    const previous = options.pool.findById(id);
+    if (!previous)
+        throw new Error(`Account "${id}" not found`);
+    const release = await (options.reserve ?? reserveAccountForDeletion)(previous);
+    try {
+        // Re-check after the await: a concurrent delete or replace may have landed
+        // while this one waited for the in-flight refresh to settle.
+        if (options.pool.findById(id) !== previous) {
+            throw new AccountReplacementConflictError(id);
+        }
+        // One pool operation rather than remove-then-add: the swap discards the
+        // old incarnation's in-flight count and cooldowns (the replacement must
+        // not inherit a bench it never earned) and hands back a rollback that
+        // restores every bit of it if the write below fails.
+        const { added, rollback } = options.pool.replaceAccount(options.record);
+        try {
+            options.persist(options.pool.getAll());
+        }
+        catch (error) {
+            rollback();
+            throw error;
+        }
+        // Only after the swap is durable: sticky sessions pinned to the dead
+        // incarnation would otherwise keep routing at an object out of the pool.
+        options.sessionRouter.invalidateAccount(id);
+        return added;
+    }
+    finally {
+        release();
+    }
+}
+/**
+ * OpenAI counterpart. No reservation is needed: refresh locks are keyed by
+ * object identity, so a refresh still running against the replaced object
+ * mutates an object no longer in the array — it cannot overwrite the new
+ * credentials, and the whole-pool write it may trigger sees the new ones.
+ */
+export function replaceOpenAIAccountTransaction(options) {
+    const index = options.accounts.findIndex(candidate => candidate.id === options.record.id);
+    if (index < 0)
+        throw new Error(`Account "${options.record.id}" not found`);
+    const previous = options.accounts[index];
+    const account = createOpenAIAccount({
+        id: options.record.id,
+        provider: "openai_subscription",
+        accessToken: options.record.accessToken,
+        refreshToken: options.record.refreshToken,
+        expiresAt: options.record.expiresAt,
+        enabled: options.record.enabled !== false,
+        ...(options.record.sessionLimitPercent !== undefined
+            ? { sessionLimitPercent: options.record.sessionLimitPercent }
+            : {}),
+        ...(options.record.weeklyLimitPercent !== undefined
+            ? { weeklyLimitPercent: options.record.weeklyLimitPercent }
+            : {}),
+    });
+    // Splice in place so the replacement keeps the old account's position; the
+    // array reference is the one the pool, router, and refresh loop all hold.
+    options.accounts.splice(index, 1, account);
+    try {
+        options.persist(options.accounts);
+    }
+    catch (error) {
+        options.accounts.splice(index, 1, previous);
+        throw error;
+    }
+    options.forgetAccount?.(previous);
+    options.invalidateAccount?.(options.record.id);
+    return account;
+}

package/dist/proxy/server.js

@@ -38,6 +38,7 @@ import { applyUpstreamFailureRoutingDetailed, reconcileAmbiguousRateLimitCooldow
 import { persistProviderEnabledState } from "./provider-routing.js";
 import { accountDeletionStatusCode, deleteAnthropicAccountTransaction, deleteOpenAIAccountTransaction, } from "./account-deletion.js";
 import { addOpenAIAccountTransaction } from "./account-add.js";
+import { accountReplacementStatusCode, replaceAnthropicAccountTransaction, replaceOpenAIAccountTransaction, } from "./account-replace.js";
 import { createAnthropicRefreshMiddleware, createAnthropicRoutingMiddleware, } from "./anthropic-routing.js";
 import { createAllowanceView } from "./allowance.js";
 import { AccountInfoCache } from "./account-info-cache.js";
@@ -119,7 +120,12 @@ function publicAnthropicAccountView(a, metrics) {
         enabled: a.enabled,
         sessionLimitPercent: a.sessionLimitPercent,
         weeklyLimitPercent: a.weeklyLimitPercent,
-        healthy: a.enabled !== false && a.healthy,
+        // `authExpired` is checked here rather than relying on `healthy` alone:
+        // a dead refresh token must never read as healthy regardless of which
+        // code path last touched the flag. Mirrors the OpenAI view's treatment
+        // of `authState === "quarantined"`.
+        healthy: a.enabled !== false && a.healthy && a.authExpired !== true,
+        ...(a.authExpired ? { authExpired: true } : {}),
         busy: a.busy || metrics.coolingDown,
         cooldownUntilMs: metrics.cooldownUntilMs ?? 0,
         globalCooldownUntilMs: metrics.globalCooldownUntilMs ?? 0,
@@ -243,6 +249,7 @@ function publicOpenAIAccountView(a, routing) {
         lastRefreshMs: a.lastRefresh,
         codexRateLimits: publicCodexRateLimits(a, routing.cooldowns),
         ...(hasPendingCredentialWrite(a) ? { credentialsPendingWrite: true } : {}),
+        ...(a.authExpired ? { authExpired: true } : {}),
         ...(a.authState === "quarantined" ? { authState: "quarantined" } : {}),
         ...(a.authFailure ? { authFailure: a.authFailure } : {}),
     };
@@ -331,6 +338,18 @@ export { applyRateLimitHeaders } from "../providers/anthropic/rate-limit-headers
  * a rotation that failed to persist earlier on disk even though no refresh was
  * involved, and the pending-write bookkeeping has to clear with it.
  */
+/**
+ * Bind Anthropic persistence to the accounts file this server was started
+ * with. Every Anthropic write has to go through it: a server running on
+ * `--accounts <path>` that writes to the default file loses each rotated
+ * refresh token on restart and clobbers a file describing a different pool.
+ * The OpenAI side has always done this — see `createOpenAIPersister`.
+ */
+export function createAnthropicPersister(accountsPath) {
+    return (accountsToSave) => {
+        saveAccounts(accountsToSave, accountsPath ?? ACCOUNTS_PATH);
+    };
+}
 export function createOpenAIPersister(accountsPath) {
     return (accountsToSave) => {
         saveOpenAIAccountsToPath(accountsToSave, accountsPath ?? ACCOUNTS_PATH);
@@ -349,6 +368,9 @@ export async function startServer(opts = {}) {
     const mode = litellmUrl ? "litellm" : "standalone";
     const accountsPath = opts.accountsPath;
     const persistOpenAIAccounts = createOpenAIPersister(accountsPath);
+    // Every Anthropic write goes through this, never `saveAccounts` directly, so
+    // a server started with `--accounts <path>` writes back to the file it read.
+    const persistAnthropicAccounts = createAnthropicPersister(accountsPath);
     if (!accountsFileExists(accountsPath)) {
         console.error(chalk.red("\n✗ accounts.json not found."));
         console.error(chalk.yellow("  Run: cc-router setup\n"));
@@ -422,7 +444,10 @@ export async function startServer(opts = {}) {
     openAIPool.onCooldownExpired = (a) => {
         stats.addLog({ ts: Date.now(), accountId: a.id, model: "-", type: "route", details: `${a.id} cooldown expired — rate limit cleared` });
     };
-    startRefreshLoop(accounts);
+    // The loop rotates refresh tokens, so it is the write that matters most for
+    // a custom accounts file: without the bound persister every rotation lands
+    // in the default file and the selected one goes stale within hours.
+    startRefreshLoop(accounts, { persist: persistAnthropicAccounts });
     startOpenAIRefreshLoop(openAIAccounts, persistOpenAIAccounts);
     const usageRefresher = new AnthropicUsageRefresher(pool);
     usageRefresher.start();
@@ -578,7 +603,10 @@ export async function startServer(opts = {}) {
                 getAll: () => pool.getAll(),
                 refreshTokens: async () => {
                     let failed = 0;
-                    await refreshAccountsOnce(pool.getAll(), { onError: error => { failed++; onError("anthropic", error); } });
+                    await refreshAccountsOnce(pool.getAll(), {
+                        persist: persistAnthropicAccounts,
+                        onError: error => { failed++; onError("anthropic", error); },
+                    });
                     return { failed };
                 },
                 refreshUsage: account => usageRefresher.refreshNow(account),
@@ -747,7 +775,7 @@ export async function startServer(opts = {}) {
      */
     const tryPersist = (rollback) => {
         try {
-            saveAccounts(pool.getAll());
+            persistAnthropicAccounts(pool.getAll());
             return { ok: true };
         }
         catch (err) {
@@ -789,7 +817,7 @@ export async function startServer(opts = {}) {
                     ? {
                         rename: (oldId, nextId) => pool.renameAccount(oldId, nextId) !== null,
                         renameSessions: (oldId, nextId) => { sessionRouter.renameAccount(oldId, nextId); },
-                        persist: () => saveAccounts(pool.getAll()),
+                        persist: () => persistAnthropicAccounts(pool.getAll()),
                     }
                     : {
                         rename: (oldId, nextId) => openAIPool.renameAccount(oldId, nextId) !== null,
@@ -876,8 +904,13 @@ export async function startServer(opts = {}) {
             account: publicOpenAIAccountView(updatedOpenAI, resolveOpenAIRouting(updatedOpenAI.id)),
         });
     });
-    accountsRouter.post("/", (req, res) => {
+    accountsRouter.post("/", async (req, res) => {
         const body = (req.body ?? {});
+        // Opt-in upsert. Re-authenticating an existing id is the only recovery for
+        // a terminally rejected refresh token, and refusing it here discarded the
+        // OAuth login the operator had just completed. It stays opt-in so an
+        // accidental id collision from any other API client still gets its 409.
+        const wantsReplace = req.body?.replace === true;
         const required = ["id", "accessToken", "refreshToken", "expiresAt"];
         for (const k of required) {
             if (body[k] === undefined || body[k] === null || body[k] === "") {
@@ -902,9 +935,68 @@ export async function startServer(opts = {}) {
         }
         // IDs are unique across providers, so a new account may not collide with an
         // existing account in either the Claude pool or the OpenAI pool.
-        if (pool.findById(body.id) || openAIAccounts.some(a => a.id === body.id)) {
-            res.status(409).json({ error: `Account "${body.id}" already exists` });
-            return;
+        const existingAnthropic = pool.findById(body.id);
+        const existingOpenAI = openAIAccounts.find(a => a.id === body.id);
+        if (existingAnthropic || existingOpenAI) {
+            // Replacement is within a provider only: swapping a Claude account for
+            // an OpenAI one under the same id is an id collision, not a re-auth.
+            const sameProvider = body.provider === "openai_subscription"
+                ? existingOpenAI !== undefined
+                : body.provider !== "xai_subscription" && existingAnthropic !== null;
+            if (!wantsReplace || !sameProvider) {
+                res.status(409).json({ error: `Account "${body.id}" already exists` });
+                return;
+            }
+            try {
+                if (existingOpenAI) {
+                    const replaced = replaceOpenAIAccountTransaction({
+                        record: {
+                            id: body.id,
+                            accessToken: body.accessToken,
+                            refreshToken: body.refreshToken,
+                            expiresAt: body.expiresAt,
+                            enabled: body.enabled,
+                            sessionLimitPercent: body.sessionLimitPercent,
+                            weeklyLimitPercent: body.weeklyLimitPercent,
+                        },
+                        accounts: openAIAccounts,
+                        persist: persistOpenAIAccounts,
+                        forgetAccount: account => openAIPool.forgetAccount(account),
+                        invalidateAccount: accountId => { openAIRouter.invalidateAccount(accountId); },
+                    });
+                    res.json({ account: publicOpenAIAccountView(replaced, resolveOpenAIRouting(replaced.id)) });
+                    return;
+                }
+                const replaced = await replaceAnthropicAccountTransaction({
+                    record: {
+                        id: body.id,
+                        provider: "anthropic_subscription",
+                        accessToken: body.accessToken,
+                        refreshToken: body.refreshToken,
+                        expiresAt: body.expiresAt,
+                        scopes: Array.isArray(body.scopes) ? body.scopes : ["user:inference", "user:profile"],
+                        enabled: body.enabled,
+                        sessionLimitPercent: body.sessionLimitPercent,
+                        weeklyLimitPercent: body.weeklyLimitPercent,
+                    },
+                    pool,
+                    sessionRouter,
+                    persist: persistAnthropicAccounts,
+                });
+                res.json({ account: publicAnthropicAccountView(replaced, createRoutingMetricsResolver()(replaced.id)) });
+                return;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                const status = accountReplacementStatusCode(err);
+                if (status === 409) {
+                    res.status(409).json({ error: message });
+                    return;
+                }
+                logError("accounts", 0, `Failed to replace account: ${message}`);
+                res.status(500).json({ error: `Failed to replace account: ${message}` });
+                return;
+            }
         }
         if (body.provider === "xai_subscription") {
             try {
@@ -1046,7 +1138,7 @@ export async function startServer(opts = {}) {
                 id,
                 pool,
                 sessionRouter,
-                persist: saveAccounts,
+                persist: persistAnthropicAccounts,
             });
         }
         catch (err) {
@@ -1134,14 +1226,14 @@ export async function startServer(opts = {}) {
         sessionRouter,
         ...upstreamAttempts,
         needsRefresh,
-        refresh: account => refreshAccountIfCurrent(account, pool),
+        refresh: account => refreshAccountIfCurrent(account, pool, { persist: persistAnthropicAccounts }),
         onRefreshFailure: onAnthropicRefreshFailure,
         onEmptyPool: onAnthropicEmptyPool,
         onNoEligibleAccount: onAnthropicNoEligibleAccount,
         // A relayed 401 means the token is stale — refresh in the background so
         // the next request succeeds without making this client wait on it.
         onUpstream401: account => {
-            void refreshAccountIfCurrent(account, pool).catch(console.error);
+            void refreshAccountIfCurrent(account, pool, { persist: persistAnthropicAccounts }).catch(console.error);
         },
         // Refresh in the background to narrow only ambiguity-owned global state
         // when fresh usage proves a requested-model exhaustion.
@@ -1227,7 +1319,7 @@ export async function startServer(opts = {}) {
                         ? routeFailureDetails(route, "token-invalid")
                         : "token-invalid";
                     logError(account.id, 401, "Token invalid — scheduling background refresh");
-                    void refreshAccountIfCurrent(account, pool).catch(console.error);
+                    void refreshAccountIfCurrent(account, pool, { persist: persistAnthropicAccounts }).catch(console.error);
                 }
                 else if (status === 429) {
                     // Rate limited — put account on cooldown for Retry-After seconds.
@@ -1327,7 +1419,7 @@ export async function startServer(opts = {}) {
         onNoEligibleAccount: onAnthropicNoEligibleAccount,
     }), createAnthropicRefreshMiddleware({
         needsRefresh,
-        refresh: account => refreshAccountIfCurrent(account, pool),
+        refresh: account => refreshAccountIfCurrent(account, pool, { persist: persistAnthropicAccounts }),
         onRefreshFailure: onAnthropicRefreshFailure,
     }), (req, _res, next) => {
         const route = req._ccRoute;
@@ -1377,7 +1469,7 @@ export async function startServer(opts = {}) {
         usageRefresher.stop();
         openAIUsageRefresher.stop();
         accountInfoCache.stop();
-        saveAccounts(pool.getAll());
+        persistAnthropicAccounts(pool.getAll());
         if (managesPidFile()) {
             removePid();
         }
@@ -1406,7 +1498,7 @@ export async function startServer(opts = {}) {
                 const ok = await performUpdate(check.latest);
                 if (ok) {
                     console.log(chalk.green("[auto-update] Restarting with new version..."));
-                    saveAccounts(pool.getAll());
+                    persistAnthropicAccounts(pool.getAll());
                     restartSelf();
                 }
             }

package/dist/proxy/token-pool.js

@@ -229,6 +229,38 @@ function clearExpiredRateLimitWindows(a, nowMs) {
         }
     }
 }
+/**
+ * Build a runtime account from a stored record. Shared by `addAccount` and
+ * `replaceAccount` so a replaced account is constructed exactly like a newly
+ * added one — including starting healthy, which is what clears a previous
+ * incarnation's terminal auth state.
+ */
+function buildAccount(record) {
+    return {
+        id: record.id,
+        tokens: {
+            accessToken: record.accessToken,
+            refreshToken: record.refreshToken,
+            expiresAt: record.expiresAt,
+            scopes: record.scopes ?? ["user:inference", "user:profile"],
+        },
+        healthy: true,
+        busy: false,
+        requestCount: 0,
+        errorCount: 0,
+        lastUsed: 0,
+        lastRefresh: 0,
+        consecutiveErrors: 0,
+        rateLimits: { ...DEFAULT_RATE_LIMITS },
+        enabled: record.enabled !== false,
+        sessionLimitPercent: record.sessionLimitPercent !== undefined
+            ? clampPercent(record.sessionLimitPercent)
+            : ACCOUNT_USER_DEFAULTS.sessionLimitPercent,
+        weeklyLimitPercent: record.weeklyLimitPercent !== undefined
+            ? clampPercent(record.weeklyLimitPercent)
+            : ACCOUNT_USER_DEFAULTS.weeklyLimitPercent,
+    };
+}
 export class TokenPool {
     accounts;
     inFlight = new Map();
@@ -836,6 +868,10 @@ export class TokenPool {
             lastRefreshMs: a.lastRefresh,
             rateLimits: a.rateLimits,
             enabled: a.enabled,
+            // Without this, a terminally rejected refresh token is indistinguishable
+            // from a token that is merely stale: both read as unhealthy with an
+            // expired timestamp, but only this one needs the operator to re-auth.
+            authExpired: a.authExpired === true,
             sessionLimitPercent: a.sessionLimitPercent,
             weeklyLimitPercent: a.weeklyLimitPercent,
         }));
@@ -894,33 +930,51 @@ export class TokenPool {
         if (this.findById(record.id)) {
             throw new Error(`Account "${record.id}" already exists`);
         }
-        const account = {
-            id: record.id,
-            tokens: {
-                accessToken: record.accessToken,
-                refreshToken: record.refreshToken,
-                expiresAt: record.expiresAt,
-                scopes: record.scopes ?? ["user:inference", "user:profile"],
-            },
-            healthy: true,
-            busy: false,
-            requestCount: 0,
-            errorCount: 0,
-            lastUsed: 0,
-            lastRefresh: 0,
-            consecutiveErrors: 0,
-            rateLimits: { ...DEFAULT_RATE_LIMITS },
-            enabled: record.enabled !== false,
-            sessionLimitPercent: record.sessionLimitPercent !== undefined
-                ? clampPercent(record.sessionLimitPercent)
-                : ACCOUNT_USER_DEFAULTS.sessionLimitPercent,
-            weeklyLimitPercent: record.weeklyLimitPercent !== undefined
-                ? clampPercent(record.weeklyLimitPercent)
-                : ACCOUNT_USER_DEFAULTS.weeklyLimitPercent,
-        };
+        const account = buildAccount(record);
         this.accounts.push(account);
         return account;
     }
+    /**
+     * Swap `record` in for the account currently holding its id, returning the
+     * replacement and a rollback that undoes the whole swap.
+     *
+     * `removeAccount` deliberately discards the departing account's in-flight
+     * count and cooldowns — for a real removal that state is garbage. A
+     * replacement whose persistence then fails has to put all of it back, or a
+     * rate-limited account returns to the pool looking idle and takes traffic it
+     * is still benched for. Capturing that state is only possible in here, which
+     * is why the swap is one pool operation rather than remove-then-add.
+     *
+     * The account keeps its position, so `currentIndex` stays valid and the
+     * rotation order is undisturbed.
+     */
+    replaceAccount(record) {
+        const index = this.accounts.findIndex(a => a.id === record.id);
+        if (index === -1)
+            throw new Error(`Account "${record.id}" not found`);
+        const previous = this.accounts[index];
+        const previousInFlight = this.inFlight.get(record.id);
+        const previousCooldowns = this.cooldowns.get(previous);
+        const added = buildAccount(record);
+        this.accounts.splice(index, 1, added);
+        // The replacement starts clean: cooldowns and in-flight counts belonged to
+        // credentials that no longer exist.
+        this.inFlight.delete(record.id);
+        this.cooldowns.delete(previous);
+        return {
+            added,
+            rollback: () => {
+                this.accounts.splice(index, 1, previous);
+                this.cooldowns.delete(added);
+                if (previousInFlight === undefined)
+                    this.inFlight.delete(record.id);
+                else
+                    this.inFlight.set(record.id, previousInFlight);
+                if (previousCooldowns !== undefined)
+                    this.cooldowns.set(previous, previousCooldowns);
+            },
+        };
+    }
     /**
      * Remove an account by id. Returns true if something was removed.
      *

package/dist/proxy/token-refresher.js

@@ -221,8 +221,8 @@ async function _doRefresh(account, span) {
  * Uses atomic write (tmp + rename) to prevent corruption if process dies mid-write.
  * Must be called after every successful refresh since refresh_token ROTATES.
  */
-export function saveAccounts(accounts) {
-    writeAnthropicAccountsPreservingOtherProviders(serialize(accounts));
+export function saveAccounts(accounts, path) {
+    writeAnthropicAccountsPreservingOtherProviders(serialize(accounts), path);
 }
 /** Run one ownership-aware scheduled refresh pass. */
 export async function refreshAccountsOnce(accounts, options = {}) {
@@ -247,8 +247,8 @@ export async function refreshAccountsOnce(accounts, options = {}) {
  * Background refresh loop: checks every 5 minutes and refreshes any
  * token expiring within the REFRESH_BUFFER_MS window.
  */
-export function startRefreshLoop(accounts) {
-    const check = () => refreshAccountsOnce(accounts);
+export function startRefreshLoop(accounts, options = {}) {
+    const check = () => refreshAccountsOnce(accounts, options);
     // Run immediately on startup (catches already-expired tokens)
     check().catch(console.error);
     setInterval(() => { check().catch(console.error); }, CHECK_INTERVAL_MS);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timo972/cc-router",
-  "version": "0.12.3",
+  "version": "0.12.4-rc.0",
   "description": "Cache-aware session router for Claude Max OAuth tokens — use multiple Claude Max accounts with Claude Code",
   "type": "module",
   "bin": {