tokenmaxxing 1.17.0 → 1.18.0

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.0",
   "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.0",
   "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/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 ctxAll = { now, thresholds: barsOf(cur.accounts), currentAccountUuid: null, switchFamilies, holdMargin };
-        if (currentWins(active, cur.accounts, ctxAll)) {
+        const pool = usable(cur.accounts);
+        const ctxAll = { now, thresholds: barsOf(pool), currentAccountUuid: null, switchFamilies, holdMargin };
+        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 thresholds = barsOf(cur.accounts);
+      const pool = usable(cur.accounts);
+      const thresholds = barsOf(pool);
       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,6 +22,17 @@ 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 function isDeadCredential(creds: OAuthCreds): boolean {
+  return creds.refreshToken === "" || creds.accessToken === "";
+}
+
 export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Promise<OAuthCreds> {
   const scope = (creds.scopes?.length ? creds.scopes : DEFAULT_SCOPES).join(" ");
   const body = {
@@ -43,10 +54,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((() => {

package/src/lib/sample.ts

@@ -4,7 +4,7 @@ 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, InvalidGrantError } from "./oauth.ts";
 import { FullUsageSchema, pingSession, probeUsage } from "./usage.ts";
 import { CredentialBlobSchema, type Account, type OAuthCreds, type TokenIdentity } from "./types.ts";
 
@@ -48,22 +48,38 @@ 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());
   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)) {
+      let liveAccount: string;
+      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" };
+      }
     }
   }
 
   if (isAccessTokenExpiring(creds, 300_000)) {
+    const owner = await checkIdentity(creds, account);
+    if (owner.status === "mismatch") {
+      account.needsReauth = true;
+      return { ok: false, reason: `${owner.reason} - refusing to spend another account's grant; re-auth with \`tokenmaxxing auth\`` };
+    }
     try {
       creds = await refreshCredential(creds);
       await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
@@ -122,11 +138,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,6 +1,6 @@
 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, InvalidGrantError, RefreshRejectedError } from "./oauth.ts";
 import { swapOAuthAccount } from "./claudejson.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
 import { log } from "./log.ts";
@@ -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());
@@ -62,14 +65,23 @@ 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`");
+    const parkedOwner = await fetchTokenIdentity(parked.accessToken).catch(() => null);
+    if (parkedOwner != null && parkedOwner.accountUuid !== target.accountUuid) {
+      throw markDead(`parked credential belongs to ${describeIdentity(parkedOwner)} - refusing to spend another account's grant; re-auth with \`tokenmaxxing auth ${target.label}\``);
+    }
     try {
-      fresh = await refreshCredential(parseBlob(parkedRaw).claudeAiOauth);
+      fresh = await refreshCredential(parked);
     } 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 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;
     }
     await writeItem(parkedTarget(target.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
@@ -105,8 +117,12 @@ 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 function isSkippableSwapError(e: unknown): boolean {
+  return e instanceof InvalidGrantError || e instanceof RefreshRejectedError;
+}
+
+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 +133,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;
     }
   }