tokenmaxxing 1.18.0 → 1.19.0

package/src/lib/oauth.ts

@@ -29,11 +29,19 @@ export class RefreshRejectedError extends Error {
   }
 }
 
+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",
@@ -93,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/paths.ts

@@ -19,6 +19,7 @@ export const paths = {
   usageJson: join(TM_HOME, "usage.json"),
   modelUsageJson: join(TM_HOME, "model-usage.json"),
   lastSwapJson: join(TM_HOME, "lastswap.json"),
+  lastResetJson: join(TM_HOME, "lastreset.json"),
   depletedJson: join(TM_HOME, "depleted.json"),
   nextCheckJson: join(TM_HOME, "nextcheck.json"),
   respawnDir: join(TM_HOME, "respawn"),

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, isDeadCredential, 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 {
@@ -54,6 +61,8 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
   }
 
   const liveRaw = await readItem(liveTarget());
+  let liveAccount: string | null = null;
+  let liveToken: string | null = null;
   if (liveRaw != null) {
     let liveCreds: OAuthCreds;
     try {
@@ -62,7 +71,7 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
       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 (!isDeadCredential(liveCreds)) {
-      let liveAccount: string;
+      liveToken = liveCreds.accessToken;
       try {
         liveAccount = (await fetchTokenIdentity(liveCreds.accessToken)).accountUuid;
       } catch (e) {
@@ -74,28 +83,64 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     }
   }
 
+  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)) {
     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; re-auth with \`tokenmaxxing auth\`` };
+      return { ok: false, reason: `${owner.reason} - refusing to spend another account's grant; the pair ${kept}; re-auth with \`tokenmaxxing auth\`` };
     }
-    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`" };
+    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 };

package/src/lib/state.ts

@@ -1,10 +1,11 @@
 import { closeSync, existsSync, fstatSync, openSync, readFileSync, rmSync, utimesSync } from "node:fs";
-import { isEqual } from "es-toolkit";
+import { isEqual, uniq } from "es-toolkit";
 import { z } from "zod";
 import { paths, realClaudeBinFromEnv, realCodexBinFromEnv } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
 import {
   AccountsIndexSchema,
+  BankedResetProvidersSchema,
   ConfigSchema,
   LastSwapSchema,
   ModelUsageStateSchema,
@@ -13,8 +14,11 @@ import {
   UsageStateSchema,
   type AccountsIndex,
   type Config,
+  type FamilyAnchor,
   type ModelUsageState,
   type UsageState,
+  type UsageWindow,
+  type WindowAnchor,
 } from "./types.ts";
 
 const DEFAULT_CONFIG: Config = {
@@ -30,6 +34,7 @@ const DEFAULT_CONFIG: Config = {
     usagePollTtlMs: 90_000,
     maxWaitMs: 3_600_000,
     checkIntervalMs: 60_000,
+    preferToUseBankedReset: [],
   },
 };
 
@@ -50,6 +55,7 @@ export const ConfigFileSchema = z
         usagePollTtlMs: z.number().int().positive(),
         maxWaitMs: z.number().int().positive(),
         checkIntervalMs: z.number().int().min(10_000),
+        preferToUseBankedReset: BankedResetProvidersSchema,
       })
       .partial(),
   })
@@ -83,6 +89,9 @@ export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutco
   if (p.policy?.switchModels) {
     cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
   }
+  if (p.policy?.preferToUseBankedReset) {
+    cfg.policy.preferToUseBankedReset = uniq(p.policy.preferToUseBankedReset);
+  }
   const envBin = realClaudeBinFromEnv();
   if (envBin) cfg.claudeBin = envBin;
   const envCodexBin = realCodexBinFromEnv();
@@ -187,6 +196,29 @@ export function saveLastSwapAt(ts: number): void {
   writeFileAtomic(paths.lastSwapJson, JSON.stringify(LastSwapSchema.parse({ ts })));
 }
 
+export function loadLastResetAt(): number | null {
+  if (!existsSync(paths.lastResetJson)) return null;
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(paths.lastResetJson, "utf8"));
+  } catch {
+    throw new Error(`${paths.lastResetJson} is corrupt (unparsable JSON) - refusing to treat a damaged reset clock as never-reset; repair or remove the file`);
+  }
+  return LastSwapSchema.parse(json).ts;
+}
+
+export function saveLastResetAt(ts: number): void {
+  writeFileAtomic(paths.lastResetJson, JSON.stringify(LastSwapSchema.parse({ ts })));
+}
+
+export function loadLastSeatChangeAt(): number | null {
+  const swapAt = loadLastSwapAt();
+  const resetAt = loadLastResetAt();
+  if (swapAt == null) return resetAt;
+  if (resetAt == null) return swapAt;
+  return Math.max(swapAt, resetAt);
+}
+
 const DepletedWaitSchema = z.object({ waitUntil: z.number(), accountUuid: z.string(), ts: z.number() });
 export type DepletedWait = z.infer<typeof DepletedWaitSchema>;
 
@@ -237,10 +269,68 @@ export function clearNextCheck(): void {
 }
 
 const USAGE_TS_REFRESH_MS = 10 * 60_000;
+const SAMPLED_AT_REFRESH_MS = 30_000;
+const SESSION_COST_MIN_DELTA = 25;
+
+function anchorHolds(anchor: WindowAnchor, next: UsageState): boolean {
+  return (
+    anchor.fiveHourResetsAt === next.fiveHour.resetsAt &&
+    anchor.sevenDayResetsAt === next.sevenDay.resetsAt &&
+    next.fiveHour.usedPercentage >= anchor.session &&
+    next.sevenDay.usedPercentage >= anchor.weekly
+  );
+}
+
+export function measureSessionWindow(prev: UsageState | null, next: UsageState, stamp: boolean): Pick<UsageState, "anchor" | "sessionWindowWeeklyCost"> {
+  const same = prev != null && prev.account === next.account;
+  const carried = same ? prev.sessionWindowWeeklyCost : undefined;
+  if (stamp) return { ...(same && prev.anchor ? { anchor: prev.anchor } : {}), ...(carried != null ? { sessionWindowWeeklyCost: carried } : {}) };
+  const anchor: WindowAnchor =
+    same && prev.anchor && anchorHolds(prev.anchor, next)
+      ? prev.anchor
+      : { fiveHourResetsAt: next.fiveHour.resetsAt, sevenDayResetsAt: next.sevenDay.resetsAt, session: next.fiveHour.usedPercentage, weekly: next.sevenDay.usedPercentage };
+  const sessionDelta = next.fiveHour.usedPercentage - anchor.session;
+  const weeklyDelta = next.sevenDay.usedPercentage - anchor.weekly;
+  const measured = sessionDelta >= SESSION_COST_MIN_DELTA && weeklyDelta > 0 ? (100 * weeklyDelta) / sessionDelta : undefined;
+  const cost = measured ?? carried;
+  return { anchor, ...(cost != null ? { sessionWindowWeeklyCost: cost } : {}) };
+}
+
+function familyAnchorHolds(anchor: FamilyAnchor, session: UsageWindow, caps: Record<string, number>): boolean {
+  return (
+    anchor.fiveHourResetsAt === session.resetsAt &&
+    session.usedPercentage >= anchor.session &&
+    Object.entries(caps).every(([family, used]) => anchor.caps[family] == null || used >= anchor.caps[family])
+  );
+}
+
+export function measureFamilyWindow(prev: ModelUsageState | null, account: string | null, session: UsageWindow | null, caps: Record<string, number>): Pick<ModelUsageState, "anchor" | "familyCosts"> {
+  const same = prev != null && prev.account === account;
+  const carried = same ? prev.familyCosts : undefined;
+  if (session == null) return { ...(same && prev.anchor ? { anchor: prev.anchor } : {}), ...(carried != null ? { familyCosts: carried } : {}) };
+  const held = same && prev.anchor && familyAnchorHolds(prev.anchor, session, caps) ? prev.anchor : null;
+  const anchor: FamilyAnchor = held ? { ...held, caps: { ...caps, ...held.caps } } : { fiveHourResetsAt: session.resetsAt, session: session.usedPercentage, caps };
+  const sessionDelta = session.usedPercentage - anchor.session;
+  const measured = Object.entries(caps).flatMap(([family, used]) => {
+    const capDelta = used - (anchor.caps[family] ?? used);
+    return sessionDelta >= SESSION_COST_MIN_DELTA && capDelta > 0 ? [[family, (100 * capDelta) / sessionDelta] as const] : [];
+  });
+  const familyCosts = { ...carried, ...Object.fromEntries(measured) };
+  return { anchor, ...(Object.keys(familyCosts).length > 0 ? { familyCosts } : {}) };
+}
 
-export function writeUsage(next: UsageState): boolean {
+export function writeUsage(input: UsageState, opts: { stamp?: boolean } = {}): boolean {
   const prev = loadUsage();
-  if (prev && isEqual({ ...prev, ts: 0 }, { ...next, ts: 0 }) && next.ts - prev.ts < USAGE_TS_REFRESH_MS) {
+  const stamp = opts.stamp === true;
+  const carriedSampleAt = prev != null && prev.account === input.account ? (prev.sampledAt ?? prev.ts) : undefined;
+  const sampledAt = stamp ? (carriedSampleAt ?? input.sampledAt) : input.ts;
+  const next: UsageState = { ...input, ...measureSessionWindow(prev, input, stamp), ...(sampledAt != null ? { sampledAt } : {}) };
+  if (
+    prev &&
+    isEqual({ ...prev, ts: 0, sampledAt: 0 }, { ...next, ts: 0, sampledAt: 0 }) &&
+    next.ts - prev.ts < USAGE_TS_REFRESH_MS &&
+    (stamp || next.ts - (prev.sampledAt ?? prev.ts) < SAMPLED_AT_REFRESH_MS)
+  ) {
     try {
       utimesSync(paths.usageJson, new Date(next.ts), new Date(next.ts));
     } catch (e) {

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, isDeadCredential, fetchTokenIdentity, describeIdentity, InvalidGrantError, RefreshRejectedError } 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));
@@ -44,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(
@@ -73,16 +78,51 @@ export async function performSwap(target: Account): Promise<void> {
       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}\``);
-    }
+    let parkedOwner: TokenIdentity | null = null;
     try {
-      fresh = await refreshCredential(parked);
+      parkedOwner = await fetchTokenIdentity(parked.accessToken);
     } 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 (!(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 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 }));
   }
@@ -117,8 +157,43 @@ export async function performSwap(target: Account): Promise<void> {
   log("swap.done", { account: target.accountUuid.slice(0, 8), email: target.email });
 }
 
+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;
+  return e instanceof InvalidGrantError || e instanceof RefreshRejectedError || e instanceof IdentityUnavailableError;
 }
 
 export async function chooseAndSwap(ctx: PickCtx, exclude: ReadonlySet<string> = new Set()): Promise<Account | null> {

package/src/lib/types.ts

@@ -41,21 +41,51 @@ export type UsageWindows = z.infer<typeof UsageWindowsSchema>;
 const ModelInfoSchema = z.object({ id: z.string(), display: z.string() });
 export type ModelInfo = z.infer<typeof ModelInfoSchema>;
 
+const WindowAnchorSchema = z.object({
+  fiveHourResetsAt: z.number().nullable(),
+  sevenDayResetsAt: z.number().nullable(),
+  session: z.number(),
+  weekly: z.number(),
+});
+export type WindowAnchor = z.infer<typeof WindowAnchorSchema>;
+
 export const UsageStateSchema = UsageWindowsSchema.extend({
   account: z.string().nullable(),
   ts: z.number(),
   model: ModelInfoSchema.nullable().default(null),
+  anchor: WindowAnchorSchema.optional(),
+  sessionWindowWeeklyCost: z.number().positive().optional(),
+  sampledAt: z.number().optional(),
 });
 export type UsageState = z.infer<typeof UsageStateSchema>;
 
+const FamilyAnchorSchema = z.object({
+  fiveHourResetsAt: z.number().nullable(),
+  session: z.number(),
+  caps: z.record(z.string(), z.number()),
+});
+export type FamilyAnchor = z.infer<typeof FamilyAnchorSchema>;
+
 export const ModelUsageStateSchema = z.object({
   perModel: z.record(z.string(), UsageWindowSchema).default({}),
   account: z.string().nullable(),
   ts: z.number(),
   sampledAt: z.number().optional(),
+  anchor: FamilyAnchorSchema.optional(),
+  familyCosts: z.record(z.string(), z.number()).optional(),
 });
 export type ModelUsageState = z.infer<typeof ModelUsageStateSchema>;
 
+export const BankedResetOutcomeSchema = z.enum(["reset", "already_used", "not_limited", "ineligible", "unavailable", "rate_limited", "auth_error", "error"]);
+export type BankedResetOutcome = z.infer<typeof BankedResetOutcomeSchema>;
+
+export const BankedResetRecordSchema = z.object({
+  outcome: BankedResetOutcomeSchema,
+  at: z.number(),
+  nextAvailableAt: z.number().nullable(),
+});
+export type BankedResetRecord = z.infer<typeof BankedResetRecordSchema>;
+
 export const AccountSchema = z.object({
   accountUuid: z.string(),
   email: z.string(),
@@ -72,6 +102,8 @@ export const AccountSchema = z.object({
   needsReauth: z.boolean().optional(),
   subscriptionType: z.string().optional(),
   rateLimitTier: z.string().optional(),
+  sessionWindowWeeklyCost: z.number().positive().optional(),
+  bankedReset: BankedResetRecordSchema.optional(),
 });
 export type Account = z.infer<typeof AccountSchema>;
 
@@ -88,6 +120,7 @@ export const NextCheckSchema = z.object({ dueAt: z.number(), ts: z.number() });
 
 export const EnforcedLimitSchema = z.object({
   account: z.string(),
+  kind: z.enum(["session", "weekly", "model"]),
   family: z.string().nullable(),
   resetsAt: z.number().nullable(),
   windowMs: z.number(),
@@ -112,6 +145,10 @@ export const ScreeningThresholdsSchema = z.object({
   weekly: z.number().min(0).max(100),
 });
 
+export const BankedResetProviderSchema = z.enum(["claude", "codex"]);
+export type BankedResetProvider = z.infer<typeof BankedResetProviderSchema>;
+export const BankedResetProvidersSchema = z.array(BankedResetProviderSchema);
+
 export const ConfigSchema = z
   .object({
     thresholds: ScreeningThresholdsSchema,
@@ -126,6 +163,7 @@ export const ConfigSchema = z
       usagePollTtlMs: z.number().int().positive(),
       maxWaitMs: z.number().int().positive(),
       checkIntervalMs: z.number().int().min(10_000),
+      preferToUseBankedReset: BankedResetProvidersSchema,
     }),
   })
   .refine((cfg) => cfg.policy.projectionMargin < Math.min(...cfg.thresholds.session, cfg.thresholds.weekly), {
@@ -143,6 +181,7 @@ export const RespawnMarkerSchema = z.object({
   sessionId: z.string(),
   prompt: z.string().optional(),
   launchedAt: z.number().optional(),
+  reset: z.boolean().optional(),
 });
 
 export const RateLimitsStdinSchema = z.looseObject({
@@ -242,9 +281,21 @@ export const CodexUsageSchema = z.object({
   planType: z.string().nullable(),
   aggregate: z.array(CodexWindowSchema),
   perLimit: z.record(z.string(), z.array(CodexWindowSchema)),
+  resetCredits: z.number().int().nullable(),
+  reachedType: z.string().nullable(),
 });
 export type CodexUsage = z.infer<typeof CodexUsageSchema>;
 
+export const CodexBankedResetOutcomeSchema = z.enum(["reset", "nothing_to_reset", "no_credit", "already_redeemed", "auth_error", "error"]);
+export type CodexBankedResetOutcome = z.infer<typeof CodexBankedResetOutcomeSchema>;
+
+export const CodexBankedResetRecordSchema = z.object({
+  outcome: CodexBankedResetOutcomeSchema,
+  at: z.number(),
+  key: z.string().optional(),
+});
+export type CodexBankedResetRecord = z.infer<typeof CodexBankedResetRecordSchema>;
+
 const BareFileNameSchema = z
   .string()
   .refine((s) => s.length > 0 && s !== "." && s !== ".." && !s.includes("/") && !s.includes("\\"), {
@@ -263,9 +314,12 @@ export const CodexAccountSchema = z.object({
     .object({
       aggregate: z.array(CodexWindowSchema),
       perLimit: z.record(z.string(), z.array(CodexWindowSchema)),
+      resetCredits: z.number().int().nullable().optional(),
+      reachedType: z.string().nullable().optional(),
     })
     .optional(),
   lastUsageAt: z.number().optional(),
+  bankedReset: CodexBankedResetRecordSchema.optional(),
 });
 export type CodexAccount = z.infer<typeof CodexAccountSchema>;