tokenmaxxing 1.17.0 → 1.18.1

package/DESIGN.md

@@ -58,7 +58,7 @@ The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed
 
 ### 3.4 Swap sequence (under the lock)
 1. **Harvest the live credential into its TRUE owner's backup** - read the current `Claude Code-credentials` blob and resolve which account it actually belongs to via the profile endpoint (`GET /api/oauth/profile`, matched on `account.uuid`), NOT the `accounts.json` active label and NOT the organization (team seats share one). The label drifts from the live blob (a kill mid-swap, a manual `/login`), and harvesting by label once overwrote another account's backup and destroyed its only credential. Mandatory anyway: Claude rotates the refresh token in place, so older backups are dead. Refuse the swap if the live credential belongs to no pooled account.
-2. **Refresh B** - OAuth refresh-grant with B's parked refresh token → fresh access token; persist the rotated refresh token. On `invalid_grant`, mark B `needs_reauth`, notify, try the next account.
+2. **Refresh B** - a blob Claude Code dead-cleared (empty tokens) is dead without a request. Resolve the owner of B's parked token through the profile endpoint first; a token that belongs to another account is never refreshed, because a refresh rotation revokes that account's live sessions, and B is marked `needs_reauth` instead. Then OAuth refresh-grant with B's parked refresh token → fresh access token; persist the rotated refresh token. On `invalid_grant`, mark B `needs_reauth`, notify, try the next account. On any other 4xx, skip B for this evaluation without marking it and try the next account.
 3. **Install B** - `security add-generic-password -U ... 'Claude Code-credentials' ...` with B's fresh (non-expired) `claudeAiOauth` JSON.
 4. **Swap identity + mark B active** - atomically rewrite only the `oauthAccount` object in `~/.claude.json` (temp+rename) to B's, and write `activeAccountUuid = B` in the SAME critical section, so a crash can't leave the installed credential and the active label pointing at different accounts.
 5. Do steps 1, 3, 4 inside Claude's own refresh locks - the primary `<credDir>/.oauth_refresh.lock` plus the legacy sibling `<realpath(credDir)>.lock` (`~/.claude.lock` by default), both mkdir-based proper-lockfile locks, binary-verified against 2.1.214 - so the writes can't collide with a token refresh. Contention fails the swap fast (claude itself gives up with `lock_timeout` rather than refreshing unlocked); the next check retries.

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tokenmaxxing",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "Pool Claude Code and Codex logins, switch on pace pressure, and expose safe ops tools to agent clients.",
   "author": {
     "name": "anaclumos",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.17.0",
+  "version": "1.18.1",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",

package/src/cli/init.ts

@@ -1,7 +1,7 @@
 import { mkdirSync } from "node:fs";
 import { isApiKeyMode, readOAuthAccount } from "../lib/claudejson.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "../lib/credstore.ts";
-import { refreshCredential, isAccessTokenExpiring, fetchTokenIdentity, describeIdentity } from "../lib/oauth.ts";
+import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity } from "../lib/oauth.ts";
 import { withClaudeRefreshLock } from "../lib/claudelock.ts";
 import { loadAccounts, saveAccounts, loadConfig, pinBinOverride } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
@@ -83,6 +83,11 @@ export async function cmdInit(): Promise<number> {
   }
 
   let creds = blob.claudeAiOauth;
+  if (isDeadCredential(creds)) {
+    console.error(c.red("the live credential was cleared after a failed refresh."));
+    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} first, then re-run ${c.cyan("tokenmaxxing init")}.`);
+    return 1;
+  }
   if (isAccessTokenExpiring(creds)) {
     await withClaudeRefreshLock(async (lock) => {
       const raw2 = await readItem(liveTarget());

package/src/cli/switch.ts

@@ -2,7 +2,7 @@ import { withLock } from "../lib/lock.ts";
 import { paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig, loadUsage } from "../lib/state.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
-import { performSwap } from "../lib/swap.ts";
+import { isSkippableSwapError, performSwap } from "../lib/swap.ts";
 import { currentWins, effectiveBars, pickBest, pickEarliestReset, weeklyExpiry, type PickCtx } from "../lib/picker.ts";
 import { InvalidGrantError } from "../lib/oauth.ts";
 import { gatedFamilies } from "../lib/usage.ts";
@@ -66,14 +66,16 @@ export async function cmdSwitch(selector?: string, json = false): Promise<number
       currentAccountUuid: null,
       switchFamilies,
     });
+    const rejected = new Set<string>();
     while (true) {
       const cur = loadAccounts();
       const everyone = everyoneIn(cur.accounts);
+      const pool = cur.accounts.filter((a) => !rejected.has(a.accountUuid));
       const active =
         (claimed != null ? cur.accounts.find((a) => a.accountUuid === claimed) : null) ??
         cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ??
         null;
-      if (active != null && currentWins(active, cur.accounts, everyone)) {
+      if (active != null && currentWins(active, pool, everyone)) {
         if (drifted) return swapTo(active, "drift-reconciled");
         const expiry = weeklyExpiry(active, now);
         const why = Number.isFinite(expiry) ? ` (weekly ${fmtReset(expiry, now)})` : "";
@@ -85,60 +87,83 @@ export async function cmdSwitch(selector?: string, json = false): Promise<number
         });
         return 0;
       }
-      const best = pickBest(cur.accounts, { ...everyone, currentAccountUuid: active?.accountUuid ?? null });
+      const best = pickBest(pool, { ...everyone, currentAccountUuid: active?.accountUuid ?? null });
       if (!best) break;
       try {
         await performSwap(best);
       } catch (e) {
+        rejected.add(best.accountUuid);
         if (e instanceof InvalidGrantError) {
           deadGrants.push(best.label);
           if (!json) console.error(c.red(deadGrantMessage(best)));
           continue;
         }
+        if (isSkippableSwapError(e)) {
+          if (!json) console.error(c.yellow(`${best.label}: ${e instanceof Error ? e.message : String(e)} - skipped for this run`));
+          continue;
+        }
         throw e;
       }
       emit(`${c.green("↻")} switched to ${c.bold(best.label)}`, { switched: true, account: best.label, reason: "best" });
       return 0;
     }
 
-    const fresh = loadAccounts();
-    const earliest = pickEarliestReset(fresh.accounts, everyoneIn(fresh.accounts));
-    const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
-    if (!earliest) {
-      if (reauth.length > 0) {
-        return fail(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`, {
-          paint: c.yellow,
-          extra: { reauthNeeded: reauth },
+    while (true) {
+      const fresh = loadAccounts();
+      const pool = fresh.accounts.filter((a) => !rejected.has(a.accountUuid));
+      const earliest = pickEarliestReset(pool, everyoneIn(fresh.accounts));
+      const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
+      if (!earliest) {
+        if (reauth.length > 0) {
+          return fail(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`, {
+            paint: c.yellow,
+            extra: { reauthNeeded: reauth },
+          });
+        }
+        const freshActive = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid) ?? null;
+        if (drifted && freshActive) return swapTo(freshActive, "drift-reconciled");
+        emit(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"), {
+          switched: false,
+          account: freshActive?.label ?? null,
+          reason: "unknown-resets",
+        });
+        return 0;
+      }
+      const reauthNote = reauth.length ? ` - re-auth needed: ${reauth.join(", ")}` : "";
+      const availableAt = earliest.availableAt > now ? earliest.availableAt : null;
+      if (earliest.account.accountUuid === fresh.activeAccountUuid && !drifted) {
+        const msg = availableAt == null
+          ? `staying on ${c.bold(earliest.account.label)} - no usable switch target${reauthNote}`
+          : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(availableAt, now)})${reauthNote}`;
+        emit(c.yellow(msg), {
+          switched: false,
+          account: earliest.account.label,
+          reason: availableAt == null ? "no-target" : "all-at-limit",
+          availableAt,
+          reauthNeeded: reauth,
         });
+        return 0;
+      }
+      try {
+        await performSwap(earliest.account);
+      } catch (e) {
+        rejected.add(earliest.account.accountUuid);
+        if (e instanceof InvalidGrantError) {
+          deadGrants.push(earliest.account.label);
+          if (!json) console.error(c.red(deadGrantMessage(earliest.account)));
+          continue;
+        }
+        if (isSkippableSwapError(e)) {
+          if (!json) console.error(c.yellow(`${earliest.account.label}: ${e instanceof Error ? e.message : String(e)} - skipped for this run`));
+          continue;
+        }
+        throw e;
+      }
+      emit(`${c.green("↻")} switched to ${c.bold(earliest.account.label)}`, { switched: true, account: earliest.account.label, reason: "earliest-reset", availableAt, reauthNeeded: reauth });
+      if (availableAt != null && !json) {
+        console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(availableAt, now)})${reauthNote}`));
       }
-      const freshActive = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid) ?? null;
-      if (drifted && freshActive) return swapTo(freshActive, "drift-reconciled");
-      emit(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"), {
-        switched: false,
-        account: freshActive?.label ?? null,
-        reason: "unknown-resets",
-      });
-      return 0;
-    }
-    const reauthNote = reauth.length ? ` - re-auth needed: ${reauth.join(", ")}` : "";
-    const availableAt = earliest.availableAt > now ? earliest.availableAt : null;
-    if (earliest.account.accountUuid === fresh.activeAccountUuid && !drifted) {
-      const msg = availableAt == null
-        ? `staying on ${c.bold(earliest.account.label)} - no usable switch target${reauthNote}`
-        : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(availableAt, now)})${reauthNote}`;
-      emit(c.yellow(msg), {
-        switched: false,
-        account: earliest.account.label,
-        reason: availableAt == null ? "no-target" : "all-at-limit",
-        availableAt,
-        reauthNeeded: reauth,
-      });
       return 0;
     }
-    const code = await swapTo(earliest.account, "earliest-reset", { availableAt, reauthNeeded: reauth });
-    if (code === 0 && availableAt != null && !json) {
-      console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(availableAt, now)})${reauthNote}`));
-    }
-    return code;
   });
 }

package/src/lib/decide.ts

@@ -4,9 +4,8 @@ import { withLock } from "./lock.ts";
 import { paths } from "./paths.ts";
 import { MAX_CHECK_DELAY_TICKS, POST_SWAP_COOLDOWN_MS, maxCheckDelayMs, loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadUsageSnapshot, loadModelUsage, saveAccounts, saveDepletedWait, saveModelUsage, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
-import { chooseAndSwap, performSwap } from "./swap.ts";
+import { chooseAndSwap, isSkippableSwapError, performSwap } from "./swap.ts";
 import { currentWins, effectiveBars, hardBars, isExhausted, nextWeeklyReset, pickBest, pickEarliestReset, sessionLadder, usableAt } from "./picker.ts";
-import { InvalidGrantError } from "./oauth.ts";
 import { familyTokens, gatedFamilies, probeUsage, type EnforcedClass } from "./usage.ts";
 import { log } from "./log.ts";
 import { AccountSchema, ModelUsageStateSchema, UsageStateSchema, type Account, type Config, type EnforcedLimit, type ModelUsageState, type Thresholds, type UsageState, type UsageWindow } from "./types.ts";
@@ -197,21 +196,30 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       idx2.accounts.find((a) => a.accountUuid === idx2.activeAccountUuid) ??
       null;
 
+    const rejected = new Set<string>();
+    const usable = (accounts: Account[]): Account[] => accounts.filter((a) => !rejected.has(a.accountUuid));
+    const skipOrThrow = (e: unknown, candidate: Account): void => {
+      if (!isSkippableSwapError(e)) throw e;
+      rejected.add(candidate.accountUuid);
+      log("decide.candidate_rejected", { account: candidate.accountUuid.slice(0, 8), error: e instanceof Error ? e.message : String(e) });
+    };
+
     const greedy = async (holdMargin: number): Promise<SwapDecision> => {
       while (true) {
         const cur = loadAccounts();
         const active = seatOf(cur);
+        const pool = usable(cur.accounts);
         const ctxAll = { now, thresholds: barsOf(cur.accounts), currentAccountUuid: null, switchFamilies, holdMargin };
-        if (currentWins(active, cur.accounts, ctxAll)) {
+        if (currentWins(active, pool, ctxAll)) {
           return { swapped: false, account: null, reason: "current-best" };
         }
-        const best = pickBest(cur.accounts, { ...ctxAll, currentAccountUuid: active?.accountUuid ?? null });
+        const best = pickBest(pool, { ...ctxAll, currentAccountUuid: active?.accountUuid ?? null });
         if (!best) return { swapped: false, account: null, reason: "no-usable-target" };
         try {
           await performSwap(best);
         } catch (e) {
-          if (e instanceof InvalidGrantError) continue;
-          throw e;
+          skipOrThrow(e, best);
+          continue;
         }
         log("decide.greedy_swap", { account: best.accountUuid.slice(0, 8) });
         return { swapped: true, account: best, reason: "swapped" };
@@ -222,15 +230,16 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
     while (true) {
       const cur = loadAccounts();
       const seat = seatOf(cur);
+      const pool = usable(cur.accounts);
       const thresholds = barsOf(cur.accounts);
       if (!enforced2 && seat && !seat.needsReauth && !isExhausted(seat, { now, thresholds, currentAccountUuid: null, switchFamilies })) return greedy(0);
-      const best = pickBest(cur.accounts, { now, thresholds, currentAccountUuid: seat?.accountUuid ?? null, switchFamilies });
+      const best = pickBest(pool, { now, thresholds, currentAccountUuid: seat?.accountUuid ?? null, switchFamilies });
       if (!best) break;
       try {
         await performSwap(best);
       } catch (e) {
-        if (e instanceof InvalidGrantError) continue;
-        throw e;
+        skipOrThrow(e, best);
+        continue;
       }
       return { swapped: true, account: best, reason: "swapped" };
     }
@@ -241,7 +250,7 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       log("decide.last_drop_hold", { account: seat.accountUuid.slice(0, 8) });
       return { swapped: false, account: null, reason: "last-drop-hold" };
     }
-    const squeezed = await chooseAndSwap({ ...hardCtx, currentAccountUuid: seat?.accountUuid ?? null });
+    const squeezed = await chooseAndSwap({ ...hardCtx, currentAccountUuid: seat?.accountUuid ?? null }, rejected);
     if (squeezed) {
       log("decide.last_drop_swap", { account: squeezed.accountUuid.slice(0, 8) });
       return { swapped: true, account: squeezed, reason: "last-drop-swap" };
@@ -253,7 +262,7 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       const ctx = { now, thresholds: hardBars(cfg), currentAccountUuid: current?.accountUuid ?? null, switchFamilies };
       const enforcedUntil = enforced2 && current && current.accountUuid === enforced2.account ? (enforced2.resetsAt ?? now + enforced2.windowMs) : 0;
       const currentAt = current ? Math.max(usableAt(current, ctx), enforcedUntil) : Number.POSITIVE_INFINITY;
-      const other = pickEarliestReset(fresh.accounts, ctx);
+      const other = pickEarliestReset(usable(fresh.accounts), ctx);
 
       let target: Account | null = null;
       let waitUntil = Number.POSITIVE_INFINITY;
@@ -275,8 +284,8 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
         try {
           await performSwap(target);
         } catch (e) {
-          if (e instanceof InvalidGrantError) continue;
-          throw e;
+          skipOrThrow(e, target);
+          continue;
         }
       }
       saveDepletedWait({ waitUntil, accountUuid: target.accountUuid, ts: now });

package/src/lib/http.ts

@@ -1,25 +1,52 @@
 import ky from "ky";
 import { z } from "zod";
 
-const ErrorBodySchema = z.looseObject({
-  error: z.string().optional(),
+const OAuthErrorBodySchema = z.looseObject({
+  error: z.string(),
   error_description: z.string().optional(),
+});
+
+const NestedErrorBodySchema = z.looseObject({
+  error: z.looseObject({ type: z.string().optional(), message: z.string().optional() }),
+  request_id: z.string().nullish(),
+});
+
+const PlainErrorBodySchema = z.looseObject({
   detail: z.string().optional(),
   message: z.string().optional(),
 });
 
+const ErrorDetailSchema = z.object({ code: z.string().nullable(), fields: z.array(z.string()) });
+type ErrorDetail = z.infer<typeof ErrorDetailSchema>;
+
+function parseErrorBody(text: string): ErrorDetail | null {
+  let json: unknown;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const oauth = OAuthErrorBodySchema.safeParse(json);
+  if (oauth.success) return { code: oauth.data.error, fields: [oauth.data.error, oauth.data.error_description ?? ""] };
+  const nested = NestedErrorBodySchema.safeParse(json);
+  if (nested.success) {
+    const requestId = nested.data.request_id ? ` (${nested.data.request_id})` : "";
+    return { code: nested.data.error.type ?? null, fields: [nested.data.error.type ?? "", (nested.data.error.message ?? "") + requestId] };
+  }
+  const plain = PlainErrorBodySchema.safeParse(json);
+  if (plain.success) return { code: null, fields: [plain.data.detail ?? "", plain.data.message ?? ""] };
+  return null;
+}
+
+export function oauthErrorCode(input: { text: string }): string | null {
+  return parseErrorBody(input.text)?.code ?? null;
+}
+
 export function safeErrorDetail(input: { text: string }): string {
-  const parsed = ErrorBodySchema.safeParse((() => {
-    try {
-      return JSON.parse(input.text);
-    } catch {
-      return null;
-    }
-  })());
-  if (!parsed.success) return "(unparsable error body withheld)";
-  const fields = [parsed.data.error, parsed.data.error_description, parsed.data.detail, parsed.data.message];
-  const detail = fields.filter((field): field is string => field != null && field.length > 0).join(": ");
-  return detail.length > 0 ? detail.slice(0, 200) : "(no error detail)";
+  const body = parseErrorBody(input.text);
+  if (!body) return `(unrecognized error body, ${input.text.length} bytes, content withheld)`;
+  const detail = body.fields.filter((field) => field.length > 0).join(": ");
+  return detail.length > 0 ? detail.slice(0, 240) : "(no error detail)";
 }
 
 export const http = ky.create({

package/src/lib/log.ts

@@ -21,6 +21,7 @@ export function log(event: string, fields: Record<string, unknown> = {}): void {
   let line = "";
   try {
     line = Object.entries(fields)
+      .filter(([, v]) => v !== undefined)
       .map(([k, v]) => {
         const str = z.string().safeParse(v);
         return `${k}=${redact(str.success ? str.data : JSON.stringify(v))}`;

package/src/lib/oauth.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { http, safeErrorDetail } from "./http.ts";
+import { http, oauthErrorCode, safeErrorDetail } from "./http.ts";
 import { ProfileResponseSchema, RefreshResponseSchema, TokenIdentitySchema, type OAuthCreds, type TokenIdentity } from "./types.ts";
 
 const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
@@ -22,7 +22,26 @@ export class InvalidGrantError extends Error {
   }
 }
 
+export class RefreshRejectedError extends Error {
+  constructor(public readonly status: number, public readonly detail: string) {
+    super(`token refresh rejected (HTTP ${status}): ${detail}`);
+    this.name = "RefreshRejectedError";
+  }
+}
+
+export class IdentityUnavailableError extends Error {
+  constructor(public readonly status: number | null, public readonly detail: string) {
+    super(status == null ? `profile endpoint unreachable: ${detail}` : `identity check failed (HTTP ${status}): ${detail}`);
+    this.name = "IdentityUnavailableError";
+  }
+}
+
+export function isDeadCredential(creds: OAuthCreds): boolean {
+  return creds.refreshToken === "" || creds.accessToken === "";
+}
+
 export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Promise<OAuthCreds> {
+  if (isDeadCredential(creds)) throw new InvalidGrantError("credential was cleared after a failed refresh");
   const scope = (creds.scopes?.length ? creds.scopes : DEFAULT_SCOPES).join(" ");
   const body = {
     grant_type: "refresh_token",
@@ -43,10 +62,10 @@ export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Pr
 
   const text = await res.text();
   if (!res.ok) {
-    if (res.status === 400 && /invalid_grant/.test(text)) {
-      throw new InvalidGrantError(safeErrorDetail({ text }));
-    }
-    throw new Error(`token refresh failed (HTTP ${res.status}): ${safeErrorDetail({ text })}`);
+    const detail = safeErrorDetail({ text });
+    if (res.status === 400 && oauthErrorCode({ text }) === "invalid_grant") throw new InvalidGrantError(detail);
+    if (res.status >= 400 && res.status < 500) throw new RefreshRejectedError(res.status, detail);
+    throw new Error(`token refresh failed (HTTP ${res.status}): ${detail}`);
   }
 
   const parsed = RefreshResponseSchema.safeParse((() => {
@@ -82,14 +101,19 @@ export async function fetchTokenIdentity(accessToken: string): Promise<TokenIden
       headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
     });
   } catch (e) {
-    throw new Error(`profile endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);
+    throw new IdentityUnavailableError(null, e instanceof Error ? e.message : String(e));
   }
-  const text = await res.text();
-  if (!res.ok) throw new Error(`identity check failed (HTTP ${res.status}): ${safeErrorDetail({ text })}`);
+  let text: string;
+  try {
+    text = await res.text();
+  } catch (e) {
+    throw new IdentityUnavailableError(res.status, `profile response body unreadable: ${e instanceof Error ? e.message : String(e)}`);
+  }
+  if (!res.ok) throw new IdentityUnavailableError(res.status, safeErrorDetail({ text }));
   const parsed = ProfileResponseSchema.safeParse((() => {
     try { return JSON.parse(text); } catch { return null; }
   })());
-  if (!parsed.success) throw new Error(`profile endpoint returned an unrecognized body (${text.length} bytes, withheld)`);
+  if (!parsed.success) throw new IdentityUnavailableError(res.status, `profile endpoint returned an unrecognized body (${text.length} bytes, withheld)`);
   return TokenIdentitySchema.parse({
     accountUuid: parsed.data.account.uuid,
     email: parsed.data.account.email ?? null,

package/src/lib/sample.ts

@@ -4,9 +4,12 @@ import { z } from "zod";
 import { readItem, writeItem, deleteItem, liveTarget, parkedTarget, isolatedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
 import { credItemFor, paths } from "./paths.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
-import { refreshCredential, isAccessTokenExpiring, fetchTokenIdentity, describeIdentity, InvalidGrantError } from "./oauth.ts";
+import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity, IdentityUnavailableError, InvalidGrantError } from "./oauth.ts";
 import { FullUsageSchema, pingSession, probeUsage } from "./usage.ts";
-import { CredentialBlobSchema, type Account, type OAuthCreds, type TokenIdentity } from "./types.ts";
+import { loadAccounts } from "./state.ts";
+import { keepRotatedPair } from "./swap.ts";
+import { log } from "./log.ts";
+import { CredentialBlobSchema, TokenIdentitySchema, type Account, type OAuthCreds, type TokenIdentity } from "./types.ts";
 
 const SampleOutcomeSchema = z.discriminatedUnion("ok", [
   z.object({ ok: z.literal(true), usage: FullUsageSchema, pingError: z.string().optional(), pingRejected: z.boolean().optional() }),
@@ -16,8 +19,8 @@ export type SampleOutcome = z.infer<typeof SampleOutcomeSchema>;
 
 const IdentityCheckSchema = z.discriminatedUnion("status", [
   z.object({ status: z.literal("match") }),
-  z.object({ status: z.literal("mismatch"), reason: z.string() }),
-  z.object({ status: z.literal("unavailable"), reason: z.string() }),
+  z.object({ status: z.literal("mismatch"), reason: z.string(), owner: TokenIdentitySchema }),
+  z.object({ status: z.literal("unavailable"), reason: z.string(), stale: z.boolean() }),
 ]);
 type IdentityCheck = z.infer<typeof IdentityCheckSchema>;
 
@@ -26,10 +29,14 @@ async function checkIdentity(creds: OAuthCreds, account: Account): Promise<Ident
   try {
     identity = await fetchTokenIdentity(creds.accessToken);
   } catch (e) {
-    return { status: "unavailable", reason: `credential identity check failed: ${e instanceof Error ? e.message : String(e)}` };
+    return {
+      status: "unavailable",
+      reason: `credential identity check failed: ${e instanceof Error ? e.message : String(e)}`,
+      stale: e instanceof IdentityUnavailableError && e.status === 401,
+    };
   }
   if (identity.accountUuid === account.accountUuid) return { status: "match" };
-  return { status: "mismatch", reason: `credential actually belongs to ${describeIdentity(identity)}` };
+  return { status: "mismatch", reason: `credential actually belongs to ${describeIdentity(identity)}`, owner: identity };
 }
 
 function refreshPlanFields(account: Account, creds: OAuthCreds): void {
@@ -48,38 +55,92 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
   } catch (e) {
     return { ok: false, reason: `parked credential unreadable (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - run \`tokenmaxxing auth\`` };
   }
+  if (isDeadCredential(creds)) {
+    account.needsReauth = true;
+    return { ok: false, reason: "parked credential was cleared after a failed refresh - re-auth with `tokenmaxxing auth`" };
+  }
 
   const liveRaw = await readItem(liveTarget());
+  let liveAccount: string | null = null;
+  let liveToken: string | null = null;
   if (liveRaw != null) {
-    let liveAccount: string;
+    let liveCreds: OAuthCreds;
     try {
-      const liveCreds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
-      liveAccount = (await fetchTokenIdentity(liveCreds.accessToken)).accountUuid;
+      liveCreds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
     } catch (e) {
-      return { ok: false, reason: `cannot verify the live credential's owner (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - refusing to sample a possibly-live account` };
+      return { ok: false, reason: `cannot read the live credential (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - refusing to sample a possibly-live account` };
     }
-    if (liveAccount === account.accountUuid) {
-      return { ok: false, reason: "this account holds the LIVE login (active label drifted) - run `tokenmaxxing switch` to reconcile" };
+    if (!isDeadCredential(liveCreds)) {
+      liveToken = liveCreds.accessToken;
+      try {
+        liveAccount = (await fetchTokenIdentity(liveCreds.accessToken)).accountUuid;
+      } catch (e) {
+        return { ok: false, reason: `cannot verify the live credential's owner (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - refusing to sample a possibly-live account` };
+      }
+      if (liveAccount === account.accountUuid) {
+        return { ok: false, reason: "this account holds the LIVE login (active label drifted) - run `tokenmaxxing switch` to reconcile" };
+      }
     }
   }
 
+  const relocate = async (owner: TokenIdentity): Promise<string> => {
+    const pooled = loadAccounts().accounts.find((a) => a.accountUuid === owner.accountUuid) ?? null;
+    if (pooled == null || pooled.accountUuid === liveAccount) return "was left in place";
+    await writeItem(parkedTarget(pooled.keychainItem), JSON.stringify({ claudeAiOauth: creds }));
+    log("swap.parked_relocated", { account: pooled.accountUuid.slice(0, 8) });
+    return "was copied to that account's slot";
+  };
+
   if (isAccessTokenExpiring(creds, 300_000)) {
-    try {
-      creds = await refreshCredential(creds);
-      await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
-    } catch (e) {
-      if (e instanceof InvalidGrantError) {
-        account.needsReauth = true;
-        return { ok: false, reason: "refresh token dead - re-auth with `tokenmaxxing auth`" };
+    const owner = await checkIdentity(creds, account);
+    if (owner.status === "mismatch") {
+      const kept = await relocate(owner.owner);
+      account.needsReauth = true;
+      return { ok: false, reason: `${owner.reason} - refusing to spend another account's grant; the pair ${kept}; re-auth with \`tokenmaxxing auth\`` };
+    }
+    if (owner.status === "unavailable" && !owner.stale) {
+      return { ok: false, reason: `${owner.reason} - refusing to refresh a parked credential whose owner cannot be verified` };
+    }
+    const rotate = async (): Promise<{ fresh: OAuthCreds } | { failed: SampleOutcome }> => {
+      try {
+        return { fresh: await refreshCredential(creds) };
+      } catch (e) {
+        if (e instanceof InvalidGrantError) {
+          account.needsReauth = true;
+          return { failed: { ok: false, reason: "refresh token dead - re-auth with `tokenmaxxing auth`" } };
+        }
+        return { failed: { ok: false, reason: `token refresh failed: ${e instanceof Error ? e.message : String(e)}` } };
+      }
+    };
+    let result: { fresh: OAuthCreds } | { failed: SampleOutcome };
+    if (owner.status === "match") {
+      result = await rotate();
+    } else {
+      try {
+        result = await withClaudeRefreshLock(async (lock) => {
+          const rotated = await rotate();
+          if ("failed" in rotated) return rotated;
+          const verified = await checkIdentity(rotated.fresh, account);
+          if (verified.status !== "mismatch") return rotated;
+          const trueOwner = loadAccounts().accounts.find((a) => a.accountUuid === verified.owner.accountUuid) ?? null;
+          const kept = await keepRotatedPair({ fresh: rotated.fresh, owner: trueOwner, fallback: account, liveOwnerUuid: liveAccount, expectedLiveToken: liveToken, lock });
+          account.needsReauth = true;
+          return { failed: { ok: false, reason: `${verified.reason}, whose grant this refresh rotated - the rotated token ${kept}; re-auth with \`tokenmaxxing auth\`` } };
+        });
+      } catch (e) {
+        return { ok: false, reason: `cannot arbitrate a stale parked credential: ${e instanceof Error ? e.message : String(e)}` };
       }
-      return { ok: false, reason: `token refresh failed: ${e instanceof Error ? e.message : String(e)}` };
     }
+    if ("failed" in result) return result.failed;
+    creds = result.fresh;
+    await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
   }
 
   const identity = await checkIdentity(creds, account);
   if (identity.status === "mismatch") {
+    const kept = await relocate(identity.owner);
     account.needsReauth = true;
-    return { ok: false, reason: `${identity.reason} - this account's own credential is gone; re-auth with \`tokenmaxxing auth\`` };
+    return { ok: false, reason: `${identity.reason} - this account's own credential is gone; the pair ${kept}; re-auth with \`tokenmaxxing auth\`` };
   }
   if (identity.status === "unavailable") {
     return { ok: false, reason: identity.reason };
@@ -122,11 +183,13 @@ export async function ensureLiveTokenFresh(): Promise<void> {
   } catch {
     return;
   }
+  if (isDeadCredential(creds)) throw new InvalidGrantError("live credential was cleared after a failed refresh");
   if (!isAccessTokenExpiring(creds, 300_000)) return;
   await withClaudeRefreshLock(async (lock) => {
     const raw2 = await readItem(liveTarget());
     if (raw2 == null) throw new Error("live credential vanished while waiting for the refresh lock");
     const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
+    if (isDeadCredential(current)) throw new InvalidGrantError("live credential was cleared after a failed refresh");
     const next = isAccessTokenExpiring(current, 300_000) ? await refreshCredential(current) : current;
     if (next === current) return;
     if (lock.compromised()) throw new Error("refresh lock compromised mid-refresh - discarding the live rewrite");

package/src/lib/swap.ts

@@ -1,11 +1,11 @@
 import { clearDepletedWait, clearNextCheck, clearUsageSnapshots, loadAccounts, saveAccounts, saveLastSwapAt } from "./state.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
-import { refreshCredential, isAccessTokenExpiring, fetchTokenIdentity, describeIdentity, InvalidGrantError } from "./oauth.ts";
+import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity, IdentityUnavailableError, InvalidGrantError, RefreshRejectedError } from "./oauth.ts";
 import { swapOAuthAccount } from "./claudejson.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
 import { log } from "./log.ts";
 import { pickBest, type PickCtx } from "./picker.ts";
-import { CredentialBlobSchema, type Account, type OAuthCreds } from "./types.ts";
+import { CredentialBlobSchema, type Account, type OAuthCreds, type TokenIdentity } from "./types.ts";
 
 function parseBlob(raw: string) {
   return CredentialBlobSchema.parse(JSON.parse(raw));
@@ -21,7 +21,10 @@ export async function performSwap(target: Account): Promise<void> {
   if (preLive) {
     liveCreds = parseBlob(preLive).claudeAiOauth;
     expectedLiveToken = liveCreds.accessToken;
-    if (isAccessTokenExpiring(liveCreds, 60_000)) {
+    if (isDeadCredential(liveCreds)) {
+      liveCreds = null;
+      log("swap.live_dead", {});
+    } else if (isAccessTokenExpiring(liveCreds, 60_000)) {
       try {
         await withClaudeRefreshLock(async (lock) => {
           const raw2 = await readItem(liveTarget());
@@ -41,7 +44,12 @@ export async function performSwap(target: Account): Promise<void> {
       }
     }
     if (liveCreds != null) {
-      const identity = await fetchTokenIdentity(liveCreds.accessToken);
+      let identity: TokenIdentity;
+      try {
+        identity = await fetchTokenIdentity(liveCreds.accessToken);
+      } catch (e) {
+        throw new Error(`cannot resolve the live credential's owner (${e instanceof Error ? e.message : String(e)}) - refusing to swap over it; the next check retries`);
+      }
       liveOwner = idx.accounts.find((a) => a.accountUuid === identity.accountUuid) ?? null;
       if (!liveOwner) {
         throw new Error(
@@ -62,15 +70,59 @@ export async function performSwap(target: Account): Promise<void> {
   if (!selfSwap) {
     const parkedRaw = await readItem(parkedTarget(target.keychainItem));
     if (!parkedRaw) throw new Error(`no parked credential for ${target.email}`);
+    const parked = parseBlob(parkedRaw).claudeAiOauth;
+    const markDead = (detail: string): InvalidGrantError => {
+      const t = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
+      if (t) { t.needsReauth = true; saveAccounts(idx); }
+      log("swap.invalid_grant", { account: target.accountUuid.slice(0, 8), detail });
+      return new InvalidGrantError(detail);
+    };
+    if (isDeadCredential(parked)) throw markDead("parked credential was cleared after a failed refresh - re-auth with `tokenmaxxing auth`");
+    let parkedOwner: TokenIdentity | null = null;
     try {
-      fresh = await refreshCredential(parseBlob(parkedRaw).claudeAiOauth);
+      parkedOwner = await fetchTokenIdentity(parked.accessToken);
     } catch (e) {
-      if (e instanceof InvalidGrantError) {
-        const t = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
-        if (t) { t.needsReauth = true; saveAccounts(idx); }
-        log("swap.invalid_grant", { account: target.accountUuid.slice(0, 8) });
+      if (!(e instanceof IdentityUnavailableError && e.status === 401)) throw e;
+      log("swap.parked_token_stale", { account: target.accountUuid.slice(0, 8) });
+    }
+    if (parkedOwner != null && parkedOwner.accountUuid !== target.accountUuid) {
+      const owner = idx.accounts.find((a) => a.accountUuid === parkedOwner.accountUuid) ?? null;
+      let kept = "was left in place";
+      if (owner != null && owner.accountUuid !== liveOwner?.accountUuid) {
+        await writeItem(parkedTarget(owner.keychainItem), JSON.stringify({ claudeAiOauth: parked }));
+        log("swap.parked_relocated", { account: owner.accountUuid.slice(0, 8) });
+        kept = "was copied to that account's slot";
       }
-      throw e;
+      throw markDead(`parked credential belongs to ${describeIdentity(parkedOwner)} - refusing to spend another account's grant; the pair ${kept}; re-auth with \`tokenmaxxing auth ${target.label}\``);
+    }
+    const refreshParked = async (): Promise<OAuthCreds> => {
+      try {
+        return await refreshCredential(parked);
+      } catch (e) {
+        if (e instanceof InvalidGrantError) throw markDead(e.detail);
+        if (e instanceof RefreshRejectedError) log("swap.refresh_rejected", { account: target.accountUuid.slice(0, 8), status: e.status, detail: e.detail });
+        throw e;
+      }
+    };
+    if (parkedOwner != null) {
+      fresh = await refreshParked();
+    } else {
+      fresh = await withClaudeRefreshLock(async (lock) => {
+        const rotated = await refreshParked();
+        let freshOwner: TokenIdentity;
+        try {
+          freshOwner = await fetchTokenIdentity(rotated.accessToken);
+        } catch (e) {
+          await writeItem(parkedTarget(target.keychainItem), JSON.stringify({ claudeAiOauth: rotated }));
+          throw new Error(`refreshed the parked credential but cannot verify its owner (${e instanceof Error ? e.message : String(e)}) - kept the rotated token parked; the next check retries`);
+        }
+        if (freshOwner.accountUuid !== target.accountUuid) {
+          const owner = idx.accounts.find((a) => a.accountUuid === freshOwner.accountUuid) ?? null;
+          const kept = await keepRotatedPair({ fresh: rotated, owner, fallback: target, liveOwnerUuid: liveOwner?.accountUuid ?? null, expectedLiveToken, lock });
+          throw markDead(`parked credential belongs to ${describeIdentity(freshOwner)}, whose grant this refresh rotated - the rotated token ${kept}; re-auth with \`tokenmaxxing auth ${target.label}\``);
+        }
+        return rotated;
+      });
     }
     await writeItem(parkedTarget(target.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
   }
@@ -105,8 +157,47 @@ export async function performSwap(target: Account): Promise<void> {
   log("swap.done", { account: target.accountUuid.slice(0, 8), email: target.email });
 }
 
-export async function chooseAndSwap(ctx: PickCtx): Promise<Account | null> {
-  const tried = new Set<string>();
+export async function keepRotatedPair(input: {
+  fresh: OAuthCreds;
+  owner: Account | null;
+  fallback: Account;
+  liveOwnerUuid: string | null;
+  expectedLiveToken: string | null;
+  lock: { compromised: () => boolean };
+}): Promise<string> {
+  const { fresh, owner } = input;
+  if (owner == null) {
+    await writeItem(parkedTarget(input.fallback.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
+    log("swap.rotated_kept_in_stamped_slot", { account: input.fallback.accountUuid.slice(0, 8) });
+    return "was kept in this account's stamped slot because its owner is not in the pool";
+  }
+  const park = async (): Promise<void> => {
+    await writeItem(parkedTarget(owner.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
+    log("swap.rotated_parked_rescued", { account: owner.accountUuid.slice(0, 8) });
+  };
+  if (input.liveOwnerUuid !== owner.accountUuid) {
+    await park();
+    return "was parked under that account";
+  }
+  try {
+    const currentLive = await readItem(liveTarget());
+    if (input.lock.compromised()) throw new Error("refresh lock compromised");
+    if (currentLive == null || parseBlob(currentLive).claudeAiOauth.accessToken !== input.expectedLiveToken) throw new Error("live credential changed while unlocked");
+    await writeItem(liveTarget(), mergeIntoLive(currentLive, fresh));
+    log("swap.rotated_live_rescued", { account: owner.accountUuid.slice(0, 8) });
+    return "was installed into the live store so that account's sessions continue";
+  } catch (e) {
+    await park();
+    return `was parked under that account (${e instanceof Error ? e.message : String(e)})`;
+  }
+}
+
+export function isSkippableSwapError(e: unknown): boolean {
+  return e instanceof InvalidGrantError || e instanceof RefreshRejectedError || e instanceof IdentityUnavailableError;
+}
+
+export async function chooseAndSwap(ctx: PickCtx, exclude: ReadonlySet<string> = new Set()): Promise<Account | null> {
+  const tried = new Set<string>(exclude);
   while (true) {
     const idx = loadAccounts();
     const candidates = idx.accounts.filter((a) => !tried.has(a.accountUuid));
@@ -117,7 +208,7 @@ export async function chooseAndSwap(ctx: PickCtx): Promise<Account | null> {
       await performSwap(best);
       return best;
     } catch (e) {
-      if (e instanceof InvalidGrantError) continue;
+      if (isSkippableSwapError(e)) continue;
       throw e;
     }
   }