tokenmaxxing 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.3.1",
+  "version": "0.4.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/add.ts

@@ -11,6 +11,7 @@ import { readItem, writeItem, deleteItem, parkedTarget, isolatedTarget, claudeAi
 import { resolveRealClaude } from "../lib/claudebin.ts";
 import { probeUsage } from "../lib/usage.ts";
 import { saveTermios, restoreTermios } from "../lib/tty.ts";
+import { withLock } from "../lib/lock.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, OAuthAccountSchema, type Account } from "../lib/types.ts";
@@ -101,29 +102,33 @@ export async function cmdAdd(): Promise<number> {
   const keychainItem = credItemFor(uuid);
   await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw)); // park a small backup
 
-  const idx = loadAccounts();
-  const existing = idx.accounts.find((a) => a.accountUuid === uuid);
-  const account: Account = {
-    accountUuid: uuid,
-    email: oauthAccount.emailAddress,
-    organizationUuid: oauthAccount.organizationUuid,
-    label: existing?.label ?? oauthAccount.emailAddress,
-    keychainItem,
-    oauthAccount,
-    addedAt: existing?.addedAt ?? new Date().toISOString(),
-    subscriptionType: blob.claudeAiOauth.subscriptionType,
-    needsReauth: false,
-    lastUsage: sampled ? { fiveHour: sampled.session, sevenDay: sampled.weekAll } : existing?.lastUsage,
-    lastPerModel: sampled && Object.keys(sampled.perModel).length > 0 ? sampled.perModel : existing?.lastPerModel,
-  };
-  if (existing) Object.assign(existing, account);
-  else idx.accounts.push(account);
-  saveAccounts(idx);
+  // under the flock: a concurrent swap's index write must not be clobbered.
+  const { account, poolSize } = await withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+    const existing = idx.accounts.find((a) => a.accountUuid === uuid);
+    const fresh: Account = {
+      accountUuid: uuid,
+      email: oauthAccount.emailAddress,
+      organizationUuid: oauthAccount.organizationUuid,
+      label: existing?.label ?? oauthAccount.emailAddress,
+      keychainItem,
+      oauthAccount,
+      addedAt: existing?.addedAt ?? new Date().toISOString(),
+      subscriptionType: blob.claudeAiOauth.subscriptionType,
+      needsReauth: false,
+      lastUsage: sampled ? { fiveHour: sampled.session, sevenDay: sampled.weekAll } : existing?.lastUsage,
+      lastPerModel: sampled && Object.keys(sampled.perModel).length > 0 ? sampled.perModel : existing?.lastPerModel,
+    };
+    if (existing) Object.assign(existing, fresh);
+    else idx.accounts.push(fresh);
+    saveAccounts(idx);
+    return { account: fresh, poolSize: idx.accounts.length };
+  });
 
   await cleanup();
 
   console.log();
   const usageNote = sampled ? ` · session ${sampled.session.usedPercentage}% / week ${sampled.weekAll.usedPercentage}%` : "";
-  console.log(`${c.green("✓")} added ${c.bold(account.email)} (${account.subscriptionType ?? "?"})${usageNote} → pool now has ${idx.accounts.length} account(s)`);
+  console.log(`${c.green("✓")} added ${c.bold(account.email)} (${account.subscriptionType ?? "?"})${usageNote} → pool now has ${poolSize} account(s)`);
   return 0;
 }

package/src/cli/check.ts

@@ -0,0 +1,29 @@
+// `tokenmaxxing check` - one auto-switch evaluation, the same decision the
+// Stop/SessionStart hooks make (flocked, idempotent). Installed as a periodic
+// launchd/systemd job so a limit crossed mid-turn, or with no session running,
+// still switches within minutes; the hooks only ever see turn boundaries.
+// Running claude sessions adopt the swapped credential in place (<=30s).
+
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { log } from "../lib/log.ts";
+import { c, fmtReset } from "./render.ts";
+
+export async function cmdCheck(): Promise<number> {
+  let d;
+  try {
+    d = await evaluateAndMaybeSwap();
+  } catch (e) {
+    // unattended under the timer: the log is the only place anyone will look.
+    log("check.error", { err: String((e as Error).message ?? e) });
+    console.error(c.red(`check failed: ${String((e as Error).message ?? e)}`));
+    return 1;
+  }
+  if (d.swapped && d.account) {
+    console.log(`${c.green("↻")} switched to ${c.bold(d.account.label)}`);
+  } else if (d.waitUntil !== undefined && d.account) {
+    console.log(c.yellow(`all accounts at limit - staying on ${c.bold(d.account.label)} (${fmtReset(d.waitUntil)})`));
+  } else {
+    console.log(c.dim(`no switch (${d.reason})`));
+  }
+  return 0;
+}

package/src/cli/doctor.ts

@@ -3,7 +3,7 @@
 
 import { existsSync } from "node:fs";
 import { checkSettings, installedBin } from "../lib/settings.ts";
-import { isBinDirAhead } from "../lib/install.ts";
+import { checkTimerHealthy, isBinDirAhead, timerActivationHint } from "../lib/install.ts";
 import { paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { readItem, liveTarget, parkedTarget } from "../lib/credstore.ts";
@@ -34,6 +34,7 @@ export async function cmdDoctor(): Promise<number> {
   check(s.statusLineOk, "statusLine shim installed in settings.json", "run `tokenmaxxing init`");
   check(s.stopOk, "Stop hook installed in settings.json", "run `tokenmaxxing init`");
   check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
+  check(checkTimerHealthy(), "periodic check timer active", timerActivationHint());
 
   const idx = loadAccounts();
   check(idx.accounts.length > 0, "at least one account in the pool", "run `tokenmaxxing init`");

package/src/cli/init.ts

@@ -6,7 +6,7 @@ import { isApiKeyMode, readOAuthAccount } from "../lib/claudejson.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "../lib/credstore.ts";
 import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg } from "../lib/oauth.ts";
 import { loadAccounts, saveAccounts, loadConfig, saveConfig } from "../lib/state.ts";
-import { installSupervisor, shellRcPath, ensurePathInRc } from "../lib/install.ts";
+import { installSupervisor, shellRcPath, ensurePathInRc, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
 import { resolveRealClaude } from "../lib/claudebin.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, type Account } from "../lib/types.ts";
@@ -25,6 +25,11 @@ function ensurePathAhead(): void {
   else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
 }
 
+function reportTimer(out: InstallOutcome): void {
+  if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every 3m)`);
+  else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
+}
+
 export async function cmdInit(): Promise<number> {
   mkdirSync(paths.home, { recursive: true });
 
@@ -41,6 +46,7 @@ export async function cmdInit(): Promise<number> {
     saveConfig(cfg);
     const active = existingIdx.accounts.find((a) => a.accountUuid === existingIdx.activeAccountUuid);
     console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
+    reportTimer(out);
     if (!out.pathAhead) ensurePathAhead();
     console.log(`  active: ${c.bold(active?.label ?? "unknown")} · run ${c.cyan("tokenmaxxing add")} for more, ${c.cyan("tokenmaxxing status")} to check`);
     return 0;
@@ -113,6 +119,7 @@ export async function cmdInit(): Promise<number> {
 
   console.log(`${c.green("✓")} imported current account → ${c.bold(account.email)} (${account.subscriptionType ?? "?"})`);
   console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/SessionStart hooks`);
+  reportTimer(out);
   if (out.priorStatusLine) console.log(`${c.green("✓")} wrapped your existing statusLine (preserved)`);
   if (!out.pathAhead) {
     console.log();

package/src/cli/rename.ts

@@ -1,5 +1,7 @@
 // `tokenmaxxing rename <selector> <new-label>` - relabel a pooled account.
 
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
 import { c } from "./render.ts";
 import type { Account } from "../lib/types.ts";
@@ -14,20 +16,23 @@ export function findAccount(accounts: Account[], selector: string): Account | un
   );
 }
 
-export function cmdRename(selector?: string, newLabel?: string): number {
+export async function cmdRename(selector?: string, newLabel?: string): Promise<number> {
   if (!selector || !newLabel) {
     console.error("usage: tokenmaxxing rename <email|label|uuid> <new-label>");
     return 2;
   }
-  const idx = loadAccounts();
-  const a = findAccount(idx.accounts, selector);
-  if (!a) {
-    console.error(c.red(`no account matches "${selector}"`));
-    return 1;
-  }
-  const old = a.label;
-  a.label = newLabel;
-  saveAccounts(idx);
-  console.log(`renamed ${c.dim(old)} → ${c.bold(newLabel)}`);
-  return 0;
+  // under the flock: a concurrent swap's index write must not be clobbered.
+  return withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+    const a = findAccount(idx.accounts, selector);
+    if (!a) {
+      console.error(c.red(`no account matches "${selector}"`));
+      return 1;
+    }
+    const old = a.label;
+    a.label = newLabel;
+    saveAccounts(idx);
+    console.log(`renamed ${c.dim(old)} → ${c.bold(newLabel)}`);
+    return 0;
+  });
 }

package/src/cli/rm.ts

@@ -1,6 +1,8 @@
 // `tokenmaxxing rm <selector>` - remove a pooled account (not the active one).
 
 import { deleteItem, parkedTarget } from "../lib/credstore.ts";
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
 import { findAccount } from "./rename.ts";
 import { c } from "./render.ts";
@@ -10,19 +12,22 @@ export async function cmdRm(selector?: string): Promise<number> {
     console.error("usage: tokenmaxxing rm <email|label|uuid>");
     return 2;
   }
-  const idx = loadAccounts();
-  const a = findAccount(idx.accounts, selector);
-  if (!a) {
-    console.error(c.red(`no account matches "${selector}"`));
-    return 1;
-  }
-  if (a.accountUuid === idx.activeAccountUuid) {
-    console.error(c.red(`${a.email} is the ACTIVE account - switch away before removing it.`));
-    return 1;
-  }
-  await deleteItem(parkedTarget(a.keychainItem));
-  idx.accounts = idx.accounts.filter((x) => x.accountUuid !== a.accountUuid);
-  saveAccounts(idx);
-  console.log(`removed ${c.bold(a.label)} from the pool (${idx.accounts.length} left)`);
-  return 0;
+  // under the flock: a concurrent swap's index write must not be clobbered.
+  return withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+    const a = findAccount(idx.accounts, selector);
+    if (!a) {
+      console.error(c.red(`no account matches "${selector}"`));
+      return 1;
+    }
+    if (a.accountUuid === idx.activeAccountUuid) {
+      console.error(c.red(`${a.email} is the ACTIVE account - switch away before removing it.`));
+      return 1;
+    }
+    await deleteItem(parkedTarget(a.keychainItem));
+    idx.accounts = idx.accounts.filter((x) => x.accountUuid !== a.accountUuid);
+    saveAccounts(idx);
+    console.log(`removed ${c.bold(a.label)} from the pool (${idx.accounts.length} left)`);
+    return 0;
+  });
 }

package/src/cli/status.ts

@@ -16,10 +16,8 @@ import type { FullUsage } from "../lib/usage.ts";
 import type { UsageWindow } from "../lib/types.ts";
 
 export async function cmdStatus(): Promise<number> {
-  const idx = loadAccounts();
+  let idx = loadAccounts();
   const cfg = loadConfig();
-  const live = loadUsage();
-  const modelUsage = loadModelUsage();
   const now = Date.now();
 
   if (idx.accounts.length === 0) {
@@ -27,13 +25,17 @@ export async function cmdStatus(): Promise<number> {
     return 0;
   }
 
-  const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
-
-  // Sample under the flock so parked refreshes can't collide with an in-flight swap.
+  // Load, sample, and save entirely under the flock: parked refreshes must not
+  // collide with an in-flight swap, and a save of an index loaded before a
+  // concurrent swap would clobber the swap's activeAccountUuid.
   console.error(c.dim("sampling live usage…"));
   const outcomes = new Map<string, SampleOutcome>();
-  await withLock(paths.lockFile, () =>
-    Promise.all(
+  await withLock(paths.lockFile, async () => {
+    idx = loadAccounts();
+    const live = loadUsage();
+    const modelUsage = loadModelUsage();
+    const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+    await Promise.all(
       idx.accounts.map(async (a) => {
         const isActive = a.accountUuid === idx.activeAccountUuid && activeOrg === a.organizationUuid;
         // Active account: prefer the free statusLine push (usage.json) so we never
@@ -57,9 +59,9 @@ export async function cmdStatus(): Promise<number> {
         a.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
         if (Object.keys(outcome.usage.perModel).length > 0) a.lastPerModel = outcome.usage.perModel;
       }),
-    ),
-  );
-  saveAccounts(idx);
+    );
+    saveAccounts(idx);
+  });
 
   console.log(c.dim(`threshold ${cfg.threshold}%  ·  ${idx.accounts.length} account(s)`));
   console.log();

package/src/entries/statusline.ts

@@ -5,10 +5,15 @@
 
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { readPriorStatusLine } from "../lib/settings.ts";
-import { writeUsage } from "../lib/state.ts";
+import { loadLastSwapAt, writeUsage } from "../lib/state.ts";
 import { parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
 import type { UsageState } from "../lib/types.ts";
 
+/** A session that hasn't adopted a fresh swap yet (<=30s keychain cache) pushes
+ *  the OLD account's windows while ~/.claude.json already names the NEW org.
+ *  Suppress the tee for this long after a swap so that mislabel never lands. */
+const ADOPTION_GRACE_MS = 45_000;
+
 async function readStdin(): Promise<string> {
   const chunks: Uint8Array[] = [];
   for await (const c of Bun.stdin.stream()) chunks.push(c);
@@ -22,7 +27,8 @@ export async function runStatusline(): Promise<number> {
   try {
     const obj = JSON.parse(raw);
     const windows = parseStatusLineStdin(obj);
-    if (windows) {
+    const lastSwapAt = loadLastSwapAt();
+    if (windows && (lastSwapAt == null || Date.now() - lastSwapAt >= ADOPTION_GRACE_MS)) {
       const org = readOAuthAccount()?.organizationUuid ?? null;
       const state: UsageState = { ...windows, org, ts: Date.now(), model: parseStatusLineModel(obj) };
       writeUsage(state);

package/src/entries/supervisor.ts

@@ -197,6 +197,9 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       launchArgs = ["--resume", sid, ...base];
       continue;
     }
+    // No marker: claude exited on its own (quit, crash, resume refused). Log it -
+    // "the process just exited" is undiagnosable without the code/signal.
+    log("supervisor.exit", { sid, respawns, code: child.exitCode, signal: child.signalCode });
     return child.exitCode ?? (child.signalCode ? 1 : 0);
   }
 }

package/src/lib/decide.ts

@@ -11,17 +11,18 @@
 // the OLD account, so org != activeOrg → we correctly do nothing until fresh usage
 // for the new account arrives.
 
+import { maxBy } from "es-toolkit";
 import { z } from "zod";
 import { withLock } from "./lock.ts";
 import { paths } from "./paths.ts";
-import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts, saveModelUsage } from "./state.ts";
+import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts, saveModelUsage, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { chooseAndSwap, performSwap } from "./swap.ts";
 import { pickEarliestReset, usableAt } from "./picker.ts";
 import { InvalidGrantError } from "./oauth.ts";
 import { probeUsage } from "./usage.ts";
 import { log } from "./log.ts";
-import { AccountSchema, type Account, type Config, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
+import { AccountSchema, type Account, type Config, type ModelInfo, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
 
 const SwapDecisionSchema = z.object({
   swapped: z.boolean(),
@@ -45,25 +46,52 @@ async function ensurePerModel(cfg: Config, org: string | null): Promise<ModelUsa
   const fresh = cached && cached.org === org && Date.now() - cached.ts < cfg.policy.usagePollTtlMs;
   if (fresh) return cached;
   const full = await probeUsage();
-  if (!full) return cached; // keep stale on poll failure
+  if (!full) {
+    // Probing the live token fail-silently while it's busy is expected; stamp the
+    // cache so the next probe waits out the TTL instead of every turn re-paying
+    // the full backoff (the 2026-07-10 post-swap probe storm).
+    saveModelUsage({ perModel: cached?.org === org ? cached.perModel : {}, org, ts: Date.now() });
+    return cached;
+  }
   const state: ModelUsageState = { perModel: full.perModel, org, ts: Date.now() };
   saveModelUsage(state);
   return state;
 }
 
-function capForModel(mu: ModelUsageState | null, display: string): UsageWindow | undefined {
-  if (!mu) return undefined;
-  const key = Object.keys(mu.perModel).find((k) => k.toLowerCase() === display.toLowerCase());
-  return key ? mu.perModel[key] : undefined;
+/** Lowercased word tokens of a model id or display string: "claude-opus-4-8" /
+ *  "Opus 4.8" -> ["claude","opus","4","8"] / ["opus","4","8"]. Model naming
+ *  drifts per release ("Fable" became "Fable 5" in 2.1.206, and id grammar has
+ *  historically flipped between family-first and version-first), so gates match
+ *  a family token anywhere instead of an exact string - an exact-string gate
+ *  silently disabled the per-model check in the 2026-07-09/10 incidents. */
+export function familyTokens(s: string): string[] {
+  return s.trim().toLowerCase().split(/[\s.-]+/).filter((t) => t.length > 0);
+}
+
+/** The switchModels family the active model belongs to, from its id OR display
+ *  tokens; null when the model is not capacity-constrained. */
+export function matchedFamily(model: ModelInfo | null, families: string[]): string | null {
+  if (!model) return null;
+  const tokens = new Set([...familyTokens(model.id), ...familyTokens(model.display)]);
+  return families.find((f) => tokens.has(f)) ?? null;
+}
+
+/** The family's weekly cap among the `/usage` rows; when several rows match the
+ *  family, the most-used one wins (switching early beats metering a depleted cap). */
+function capForFamily(mu: ModelUsageState, family: string): UsageWindow | undefined {
+  const rows = Object.entries(mu.perModel)
+    .filter(([k]) => familyTokens(k).includes(family))
+    .map(([, w]) => w);
+  return maxBy(rows, (w) => w.usedPercentage);
 }
 
 /** True if the active account is over the floor on ANY applicable limit. */
 function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, floor: number): boolean {
   if (!u || !org || u.org !== org) return false;
   if (u.fiveHour.usedPercentage >= floor || u.sevenDay.usedPercentage >= floor) return true;
-  const display = u.model?.display;
-  if (display && cfg.policy.switchModels.includes(display.toLowerCase()) && mu && mu.org === org) {
-    const cap = capForModel(mu, display);
+  const family = matchedFamily(u.model, cfg.policy.switchModels);
+  if (family && mu && mu.org === org) {
+    const cap = capForFamily(mu, family);
     if (cap && cap.usedPercentage >= floor) return true;
   }
   return false;
@@ -71,8 +99,7 @@ function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string |
 
 /** Does the active model warrant a per-model `/usage` poll? */
 function needsPerModel(u: UsageState | null, cfg: Config): boolean {
-  const display = u?.model?.display;
-  return !!display && cfg.policy.switchModels.includes(display.toLowerCase());
+  return matchedFamily(u?.model ?? null, cfg.policy.switchModels) !== null;
 }
 
 export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecision> {
@@ -81,7 +108,12 @@ export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecisi
   const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
 
   let usage = loadUsage();
-  if (!usage && activeOrg) usage = await probeAggregate(activeOrg);
+  if (!usage && activeOrg) {
+    usage = await probeAggregate(activeOrg);
+    // Persist: post-swap the snapshots are cleared and the statusLine tee is in
+    // its grace window, so without this every turn boundary would re-probe.
+    if (usage) writeUsage(usage);
+  }
 
   // per-model poll (TTL-cached) only when on a capacity-constrained model
   const mu = needsPerModel(usage, cfg) ? await ensurePerModel(cfg, activeOrg) : null;

package/src/lib/install.ts

@@ -4,6 +4,7 @@
 
 import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
+import { escape } from "es-toolkit";
 import { z } from "zod";
 import { HOME, paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
@@ -15,6 +16,7 @@ const InstallOutcomeSchema = z.object({
   installedBin: z.string(),
   priorStatusLine: z.string().nullable(),
   pathAhead: z.boolean(),
+  timerLoaded: z.boolean(),
 });
 export type InstallOutcome = z.infer<typeof InstallOutcomeSchema>;
 
@@ -52,9 +54,134 @@ export function installSupervisor(): InstallOutcome {
     installedBin: target,
     priorStatusLine,
     pathAhead: isBinDirAhead(),
+    timerLoaded: installCheckTimer(),
   };
 }
 
+// ---- periodic `check` timer ------------------------------------------------
+// The hooks evaluate only at turn boundaries; one long agentic turn can burn a
+// window from healthy to depleted with zero boundaries (2026-07-10 incident).
+// A timer closes that gap: launchd on macOS, a systemd user timer on Linux.
+
+const CHECK_INTERVAL_S = 180;
+const LAUNCHD_LABEL = "com.tokenmaxxing.check";
+
+function launchdPlist(): string {
+  return join(paths.launchdAgentsDir, `${LAUNCHD_LABEL}.plist`);
+}
+
+/** `gui/<uid>` launchd domain, or null when the platform has no getuid. */
+function launchdDomain(): string | null {
+  const uid = process.getuid?.();
+  return uid == null ? null : `gui/${uid}`;
+}
+
+/** launchctl/systemctl may be absent (spawnSync throws ENOENT) or hang on a
+ *  dead session bus (ssh without lingering) - degrade, never crash or block. */
+function run(cmd: string[]): boolean {
+  try {
+    return Bun.spawnSync(cmd, { stdout: "ignore", stderr: "ignore", timeout: 10_000 }).exitCode === 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Install + activate the periodic check job. False means the unit files are in
+ *  place but activation failed (e.g. systemd user session absent over ssh) -
+ *  the caller prints the manual activation step. */
+export function installCheckTimer(): boolean {
+  if (process.platform === "darwin") {
+    const plist = launchdPlist();
+    writeFileAtomic(
+      plist,
+      `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${LAUNCHD_LABEL}</string>
+  <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string></array>
+  <key>StartInterval</key><integer>${CHECK_INTERVAL_S}</integer>
+  <key>StandardOutPath</key><string>/dev/null</string>
+  <key>StandardErrorPath</key><string>${escape(join(paths.home, "check.stderr.log"))}</string>
+</dict>
+</plist>
+`,
+      0o644,
+    );
+    const domain = launchdDomain();
+    if (domain == null) return false;
+    run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]); // reload a changed plist
+    // bootstrap can lose a benign race with an in-flight bootout; loaded is loaded.
+    return run(["launchctl", "bootstrap", domain, plist]) || checkTimerHealthy();
+  }
+
+  // systemd: quote the path and escape `%` (unit-file specifier character).
+  const exec = `"${installedBin().replaceAll("%", "%%")}" check`;
+  writeFileAtomic(
+    join(paths.systemdUserDir, "tokenmaxxing-check.service"),
+    `[Unit]
+Description=tokenmaxxing account-switch check
+
+[Service]
+Type=oneshot
+ExecStart=${exec}
+`,
+    0o644,
+  );
+  writeFileAtomic(
+    join(paths.systemdUserDir, "tokenmaxxing-check.timer"),
+    `[Unit]
+Description=tokenmaxxing periodic account-switch check
+
+[Timer]
+OnBootSec=60
+OnUnitActiveSec=${CHECK_INTERVAL_S}
+AccuracySec=30
+
+[Install]
+WantedBy=timers.target
+`,
+    0o644,
+  );
+  return (
+    run(["systemctl", "--user", "daemon-reload"]) &&
+    run(["systemctl", "--user", "enable", "--now", "tokenmaxxing-check.timer"])
+  );
+}
+
+/** The manual activation command for an unloaded timer, per platform. */
+export function timerActivationHint(): string {
+  if (process.platform === "darwin") {
+    return `launchctl bootstrap gui/$(id -u) ${launchdPlist()}`;
+  }
+  return "systemctl --user daemon-reload && systemctl --user enable --now tokenmaxxing-check.timer";
+}
+
+/** True when the timer unit exists AND the service manager reports it loaded. */
+export function checkTimerHealthy(): boolean {
+  if (process.platform === "darwin") {
+    const domain = launchdDomain();
+    return existsSync(launchdPlist()) && domain != null && run(["launchctl", "print", `${domain}/${LAUNCHD_LABEL}`]);
+  }
+  return (
+    existsSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer")) &&
+    run(["systemctl", "--user", "is-active", "--quiet", "tokenmaxxing-check.timer"])
+  );
+}
+
+export function uninstallCheckTimer(): void {
+  if (process.platform === "darwin") {
+    const domain = launchdDomain();
+    if (domain != null) run(["launchctl", "bootout", `${domain}/${LAUNCHD_LABEL}`]);
+    rmSync(launchdPlist(), { force: true });
+    return;
+  }
+  run(["systemctl", "--user", "disable", "--now", "tokenmaxxing-check.timer"]);
+  rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.timer"), { force: true });
+  rmSync(join(paths.systemdUserDir, "tokenmaxxing-check.service"), { force: true });
+  run(["systemctl", "--user", "daemon-reload"]);
+}
+
 /** The rc file of the user's login shell, or null when the shell is unknown.
  *  Overridable for hermetic tests. */
 export function shellRcPath(): string | null {
@@ -81,6 +208,7 @@ export function ensurePathInRc(rc: string): "added" | "present" {
 
 export function uninstallSupervisor(): void {
   uninstallSettings();
+  uninstallCheckTimer();
   for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
     if (existsSync(f)) rmSync(f, { force: true });
   }

package/src/lib/paths.ts

@@ -21,6 +21,7 @@ export const paths = {
   accountsJson: join(TM_HOME, "accounts.json"),
   usageJson: join(TM_HOME, "usage.json"),
   modelUsageJson: join(TM_HOME, "model-usage.json"),
+  lastSwapJson: join(TM_HOME, "lastswap.json"),
   respawnDir: join(TM_HOME, "respawn"),
   binDir: join(TM_HOME, "bin"),
   supervisorLink: join(TM_HOME, "bin", "claude"),
@@ -40,6 +41,10 @@ export const paths = {
   ),
   /** ~/.claude - for the credential-refresh lock and projects/ transcripts. */
   claudeDir: env("CLAUDE_CONFIG_DIR", join(HOME, ".claude")),
+
+  /** where the periodic-check timer units live (launchd / systemd user). */
+  launchdAgentsDir: env("TOKENMAXXING_LAUNCHD_DIR", join(HOME, "Library", "LaunchAgents")),
+  systemdUserDir: env("TOKENMAXXING_SYSTEMD_USER_DIR", join(HOME, ".config", "systemd", "user")),
 } as const;
 
 /** Claude's own credential-refresh lock (verified path filled from facts). */

package/src/lib/state.ts

@@ -1,6 +1,6 @@
 // Config + accounts index + usage snapshot persistence. All writes atomic.
 
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, rmSync } from "node:fs";
 import { isEqual } from "es-toolkit";
 import { z } from "zod";
 import { paths, realClaudeBinFromEnv } from "./paths.ts";
@@ -8,6 +8,7 @@ import { writeFileAtomic } from "./atomic.ts";
 import {
   AccountsIndexSchema,
   ConfigSchema,
+  LastSwapSchema,
   ModelUsageStateSchema,
   UsageStateSchema,
   type AccountsIndex,
@@ -100,6 +101,29 @@ export function loadUsage(): UsageState | null {
   }
 }
 
+/** Drop the statusLine-fed snapshots after a swap: their windows belong to the
+ *  pre-swap account and would otherwise be read under the new active org. */
+export function clearUsageSnapshots(): void {
+  rmSync(paths.usageJson, { force: true });
+  rmSync(paths.modelUsageJson, { force: true });
+}
+
+// ---- lastswap.json (epoch ms of the last swap; absent = never swapped) ----
+
+export function loadLastSwapAt(): number | null {
+  if (!existsSync(paths.lastSwapJson)) return null;
+  try {
+    const parsed = LastSwapSchema.safeParse(JSON.parse(readFileSync(paths.lastSwapJson, "utf8")));
+    return parsed.success ? parsed.data.ts : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveLastSwapAt(ts: number): void {
+  writeFileAtomic(paths.lastSwapJson, JSON.stringify(LastSwapSchema.parse({ ts })));
+}
+
 /** Write-on-change: skip the write (and its fsync) when only `ts` would differ. */
 export function writeUsage(next: UsageState): boolean {
   const prev = loadUsage();

package/src/lib/swap.ts

@@ -12,7 +12,7 @@
 //     mark B active (inside the lock: a crash before this write leaves a stale
 //     active label, which is exactly what once made a harvest destroy a backup)
 
-import { loadAccounts, saveAccounts } from "./state.ts";
+import { clearUsageSnapshots, loadAccounts, saveAccounts, saveLastSwapAt } from "./state.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
 import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
 import { swapOAuthAccount } from "./claudejson.ts";
@@ -110,6 +110,10 @@ export async function performSwap(target: Account): Promise<void> {
     const t2 = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
     if (t2) { t2.needsReauth = false; }
     saveAccounts(idx);
+    // the snapshots on disk still describe the pre-swap account; under the new
+    // org label they'd trigger a bogus switch off the account just installed.
+    clearUsageSnapshots();
+    saveLastSwapAt(Date.now());
   });
   log("swap.done", { account: target.accountUuid.slice(0, 8), email: target.email });
 }

package/src/lib/types.ts

@@ -94,6 +94,11 @@ export const AccountsIndexSchema = z.object({
   activeAccountUuid: z.string().nullable(),
   accounts: z.array(AccountSchema).default([]),
 });
+
+/** lastswap.json - epoch ms of the last credential swap. Its own tiny file (not
+ *  accounts.json) so the statusLine shim reads a few bytes per tick and no other
+ *  index writer can clobber it. Absent = no swap has ever run. */
+export const LastSwapSchema = z.object({ ts: z.number() });
 export type AccountsIndex = z.infer<typeof AccountsIndexSchema>;
 
 export const ConfigSchema = z.object({

package/src/lib/usage.ts

@@ -213,13 +213,19 @@ async function probeUsageOnce(env: Record<string, string>, now: number): Promise
   return full;
 }
 
+/** Escalating retry delays for the empty-footer case (usage endpoint throttled
+ *  or the sampled token busy). Capped at ~7s of sleep: probeUsage runs inside
+ *  Stop/SessionStart hooks and under the status flock, and the periodic `check`
+ *  timer re-runs every 3 minutes anyway, owning the long-tail retry. */
+const PROBE_RETRY_DELAYS_MS = [2000, 5000];
+
 /**
  * Run `claude -p '/usage'` (free, 0 tokens) and parse all three limit kinds.
  * Pass `configDir` to sample a specific account (its CLAUDE_CONFIG_DIR); omit to
  * sample the live account. All ambient credential overrides are scrubbed so the
  * probe meters exactly the OAuth credential in the (possibly namespaced)
  * keychain item. The empty-footer case (claude's own usage call throttled) is
- * transient, so retry it a couple of times. Returns null if it never yields data.
+ * transient, so retry with backoff. Returns null if it never yields data.
  */
 export async function probeUsage(configDir?: string, now = Date.now()): Promise<FullUsage | null> {
   const env: Record<string, string> = { ...process.env, TOKENMAXXING_PROBE: "1" };
@@ -228,7 +234,11 @@ export async function probeUsage(configDir?: string, now = Date.now()): Promise<
 
   for (let attempt = 0; ; attempt++) {
     const full = await probeUsageOnce(env, now);
-    if (full || attempt >= 2) return full;
-    await delay(1500);
+    if (full) return full;
+    if (attempt >= PROBE_RETRY_DELAYS_MS.length) {
+      log("usage.probe_gave_up", { attempts: attempt + 1 });
+      return null;
+    }
+    await delay(PROBE_RETRY_DELAYS_MS[attempt]!);
   }
 }

package/src/main.ts

@@ -16,6 +16,7 @@ import { cmdDoctor } from "./cli/doctor.ts";
 import { cmdRm } from "./cli/rm.ts";
 import { cmdRename } from "./cli/rename.ts";
 import { cmdSwitch } from "./cli/switch.ts";
+import { cmdCheck } from "./cli/check.ts";
 import { uninstallSupervisor } from "./lib/install.ts";
 import { c } from "./cli/render.ts";
 
@@ -24,6 +25,7 @@ function printHelp(): void {
 
   ${c.cyan("tokenmaxxing")}            show the pool with usage bars (alias of ${c.cyan("status")})
   ${c.cyan("tokenmaxxing switch")} [sel]  switch now to the best (or a specific) account
+  ${c.cyan("tokenmaxxing check")}      evaluate once, switch if over threshold (run by the periodic timer)
   ${c.cyan("tokenmaxxing init")}       import the current account + install supervisor & hooks
   ${c.cyan("tokenmaxxing add")}        register an additional account (isolated login)
   ${c.cyan("tokenmaxxing ls")}         list pooled accounts
@@ -56,6 +58,7 @@ async function main(): Promise<number> {
     case "__session-start": return runSessionStart();
     case undefined: return cmdStatus(); // bare `tokenmaxxing` / `xx` → status
     case "switch": return cmdSwitch(args[1]);
+    case "check": return cmdCheck();
     case "init": return cmdInit();
     case "add": return cmdAdd();
     case "ls": return cmdLs();