tokenmaxxing 0.3.1 → 0.5.0

package/src/entries/supervisor.ts

@@ -106,7 +106,7 @@ async function countdownWait(acct: string, until: number): Promise<void> {
     await Bun.sleep(1000);
   }
   process.removeListener("SIGINT", onInt);
-  process.stdout.write(`\n\x1b[36m↻ resuming on ${acct}…\x1b[0m\n`);
+  process.stdout.write(`\n\x1b[36m↻ resuming on ${acct}...\x1b[0m\n`);
 }
 
 /** Entry point: `claude ...args`. */
@@ -193,10 +193,13 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       rmSync(marker, { force: true });
       respawns++;
       if (m.waitUntil && m.waitUntil > Date.now()) await countdownWait(m.account, m.waitUntil);
-      else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming…\x1b[0m\n`);
+      else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming...\x1b[0m\n`);
       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,15 +11,16 @@
 // 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 { familyTokens, matchedFamily, probeUsage } from "./usage.ts";
 import { log } from "./log.ts";
 import { AccountSchema, type Account, type Config, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
 
@@ -45,25 +46,34 @@ 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;
+/** 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 +81,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 +90,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

@@ -1,9 +1,10 @@
 // Install/uninstall the on-PATH `claude` supervisor wrapper + settings entries.
-// The wrapper is a 2-line `exec … __supervise "$@"` shim so dispatch never
+// The wrapper is a 2-line `exec ... __supervise "$@"` shim so dispatch never
 // depends on argv0 semantics.
 
 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";
@@ -13,8 +14,8 @@ import { resolveRealClaude } from "./claudebin.ts";
 const InstallOutcomeSchema = z.object({
   claudeWrapper: z.string(),
   installedBin: z.string(),
-  priorStatusLine: z.string().nullable(),
   pathAhead: z.boolean(),
+  timerLoaded: z.boolean(),
 });
 export type InstallOutcome = z.infer<typeof InstallOutcomeSchema>;
 
@@ -46,15 +47,139 @@ export function installSupervisor(): InstallOutcome {
   // the `xx` short alias → tokenmaxxing
   writeFileAtomic(join(paths.binDir, "xx"), `#!/bin/sh\nexec ${JSON.stringify(target)} "$@"\n`, 0o755);
 
-  const { priorStatusLine } = installSettings();
+  installSettings();
   return {
     claudeWrapper: paths.supervisorLink,
     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 +206,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/keychain.ts

@@ -1,7 +1,7 @@
 // macOS login-keychain generic-password I/O, ps-safe. The darwin backend of
 // credstore.ts - construct targets there, not here.
 //   READ  : `security find-generic-password -w`  → secret only ever in stdout.
-//   WRITE : pipe an `add-generic-password -U … -w <secret>` line into `security -i`
+//   WRITE : pipe an `add-generic-password -U ... -w <secret>` line into `security -i`
 //           over STDIN - the secret never appears in any process's argv (verified).
 // The service/account are non-secret and may sit in argv.
 

package/src/lib/log.ts

@@ -11,7 +11,7 @@ export function redact(s: string): string {
   return s
     // JWT-ish / long opaque tokens
     .replace(/\b(sk-ant-[A-Za-z0-9._-]{6,})/g, "sk-ant-***")
-    .replace(/\b([A-Za-z0-9_-]{40,})\b/g, (m) => `${m.slice(0, 4)}…(${m.length})`);
+    .replace(/\b([A-Za-z0-9_-]{40,})\b/g, (m) => `${m.slice(0, 4)}...(${m.length})`);
 }
 
 export function log(event: string, fields: Record<string, unknown> = {}): void {

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/picker.ts

@@ -38,6 +38,15 @@ export function weeklyExpiry(a: Account, now: number): number {
   return r + (Math.floor((now - r) / WEEK_MS) + 1) * WEEK_MS;
 }
 
+/** The switch preference: soonest weekly expiry first; tiebreak lowest 7-day
+ *  usage, then soonest 5h reset. Shared with the statusLine pool ordering so
+ *  the display order IS the swap order. */
+export const swapPreference = (now: number) => [
+  (a: Account) => weeklyExpiry(a, now),
+  (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
+  (a: Account) => a.lastUsage?.fiveHour.resetsAt ?? Number.POSITIVE_INFINITY,
+];
+
 export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   const candidates = accounts.filter(
     (a) =>
@@ -46,13 +55,7 @@ export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
       !isExhausted(a, ctx),
   );
   if (candidates.length === 0) return null;
-
-  // soonest weekly expiry first; tiebreak lowest 7-day usage, then soonest 5h reset.
-  return sortBy(candidates, [
-    (a) => weeklyExpiry(a, ctx.now),
-    (a) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
-    (a) => a.lastUsage?.fiveHour.resetsAt ?? Number.POSITIVE_INFINITY,
-  ])[0]!;
+  return sortBy(candidates, swapPreference(ctx.now))[0]!;
 }
 
 /** When an account becomes usable again: the latest reset among its over-threshold

package/src/lib/settings.ts

@@ -1,6 +1,7 @@
 // Idempotent merge of tokenmaxxing's three entries into the user-owned
-// ~/.claude/settings.json: a statusLine shim, a Stop hook, a SessionStart hook.
-// We APPEND to existing hook arrays and WRAP the existing statusLine - never clobber.
+// ~/.claude/settings.json: our statusLine, a Stop hook, a SessionStart hook.
+// Hooks APPEND to existing arrays; the statusLine slot is ours outright -
+// tokenmaxxing renders it natively, so any other statusLine command is replaced.
 
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -23,8 +24,6 @@ const SettingsSchema = z.looseObject({
 type Settings = z.infer<typeof SettingsSchema>;
 type HookGroup = z.infer<typeof HookGroupSchema>;
 
-const PRIOR_STATUSLINE_FILE = join(paths.home, "prior-statusline.json");
-
 const SUBCMD = {
   statusline: "__statusline",
   stop: "__stop-hook",
@@ -71,57 +70,27 @@ function removeHook(s: Settings, event: string, sub: string): void {
   if (s.hooks![event]!.length === 0) delete s.hooks![event];
 }
 
-const InstallResultSchema = z.object({ priorStatusLine: z.string().nullable() });
-export type InstallResult = z.infer<typeof InstallResultSchema>;
-
-/**
- * Install the three entries. Returns the prior statusLine command that was
- * wrapped (stored to disk so the shim can chain to it and uninstall can restore).
- */
-export function installSettings(): InstallResult {
+/** Install the three entries: take the statusLine slot, append our hooks. */
+export function installSettings(): void {
   const s = readSettings();
-
-  // ---- statusLine: capture prior (unless it's already ours), then wrap.
-  let prior: string | null;
-  if (s.statusLine && !isOurCommand(s.statusLine.command)) {
-    prior = s.statusLine.command;
-    writeFileAtomic(PRIOR_STATUSLINE_FILE, JSON.stringify({ command: prior }) + "\n", 0o644);
-  } else {
-    prior = readPriorStatusLine();
-  }
   s.statusLine = {
     type: "command",
     command: `${JSON.stringify(installedBin())} ${SUBCMD.statusline}`,
   };
-
-  // ---- hooks: append ours if absent.
   appendHook(s, "Stop", SUBCMD.stop);
   appendHook(s, "SessionStart", SUBCMD.sessionStart);
-
   writeSettings(s);
-  return { priorStatusLine: prior };
 }
 
-/** Remove our three entries and restore the prior statusLine if we have it. */
+/** Remove our three entries. The statusLine slot is deleted only if it is ours. */
 export function uninstallSettings(): void {
   const s = readSettings();
   removeHook(s, "Stop", SUBCMD.stop);
   removeHook(s, "SessionStart", SUBCMD.sessionStart);
-  if (s.statusLine && isOurCommand(s.statusLine.command)) {
-    const prior = readPriorStatusLine();
-    if (prior) s.statusLine = { type: "command", command: prior };
-    else delete s.statusLine;
-  }
+  if (s.statusLine && isOurCommand(s.statusLine.command)) delete s.statusLine;
   writeSettings(s);
 }
 
-const PriorStatusLineSchema = z.object({ command: z.string() });
-
-export function readPriorStatusLine(): string | null {
-  if (!existsSync(PRIOR_STATUSLINE_FILE)) return null;
-  return PriorStatusLineSchema.parse(JSON.parse(readFileSync(PRIOR_STATUSLINE_FILE, "utf8"))).command;
-}
-
 const SettingsCheckSchema = z.object({
   statusLineOk: z.boolean(),
   stopOk: z.boolean(),

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({
@@ -132,6 +137,32 @@ export const RateLimitsStdinSchema = z.looseObject({
   organizationUuid: z.string().optional(),
 });
 
+/** The statusLine stdin fields the native renderer consumes, on top of the
+ *  rate-limit tee's needs. Loose + optional throughout: fields are null before
+ *  the first API response and claude adds new ones freely. Each sub-object also
+ *  `.catch(undefined)`es so a field that drifts to a wrong shape degrades to
+ *  absent instead of failing the whole parse and erasing the info block. */
+export const StatusLineStdinSchema = RateLimitsStdinSchema.extend({
+  workspace: z
+    .looseObject({
+      current_dir: z.string().nullable().optional(),
+      project_dir: z.string().nullable().optional(),
+    })
+    .nullable()
+    .optional()
+    .catch(undefined),
+  context_window: z.looseObject({ used_percentage: z.number().nullable().optional() }).nullable().optional().catch(undefined),
+  cost: z
+    .looseObject({
+      total_lines_added: z.number().nullable().optional(),
+      total_lines_removed: z.number().nullable().optional(),
+    })
+    .nullable()
+    .optional()
+    .catch(undefined),
+  effort: z.looseObject({ level: z.string().optional() }).nullable().optional().catch(undefined),
+});
+
 /** Success body of the OAuth refresh grant. */
 export const RefreshResponseSchema = z.looseObject({
   access_token: z.string(),

package/src/lib/usage.ts

@@ -49,6 +49,24 @@ export function parseStatusLineModel(obj: unknown): ModelInfo | null {
   return { id: m?.id ?? m?.display_name ?? "", display: m?.display_name ?? m?.id ?? "" };
 }
 
+/** 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;
+}
+
 export const FullUsageSchema = z.object({
   session: UsageWindowSchema,
   weekAll: UsageWindowSchema,
@@ -122,8 +140,8 @@ export function parseResetClock(clock: string, now = Date.now()): number | null
 /**
  * Parse `claude -p '/usage'` .result text into all three limit kinds:
  *   Current session: N% used · resets <clock>      → session (5h)
- *   Current week (all models): N% used · resets …   → weekAll (7d aggregate)
- *   Current week (<Model>): N% used · resets …      → perModel[<Model>]
+ *   Current week (all models): N% used · resets ...   → weekAll (7d aggregate)
+ *   Current week (<Model>): N% used · resets ...      → perModel[<Model>]
  */
 export function parseUsageTextFull(text: string, now = Date.now()): FullUsage | null {
   if (!text) return null;
@@ -213,13 +231,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 +252,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/lib/worktree.ts

@@ -0,0 +1,22 @@
+// Linked-worktree detection for the statusLine. A linked worktree's root holds
+// a .git FILE (a gitdir pointer) where the main checkout has a .git directory.
+// Read the filesystem directly - never a git subprocess.
+
+import { statSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+/** The worktree root's basename when `dir` is inside a LINKED git worktree;
+ *  null in a main checkout or outside any repository. Any fs error while
+ *  walking (EACCES, ENOTDIR, stale mounts) is also null: the status line must
+ *  never break over an unreadable path. */
+export function worktreeName(dir: string): string | null {
+  try {
+    for (let cur = dir; ; cur = dirname(cur)) {
+      const st = statSync(join(cur, ".git"), { throwIfNoEntry: false });
+      if (st) return st.isFile() ? basename(cur) : null;
+      if (dirname(cur) === cur) return null;
+    }
+  } catch {
+    return null;
+  }
+}

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();