tokenmaxxing 1.90.0 → 1.92.0

package/DESIGN.md

@@ -53,7 +53,7 @@ The switching path runs no long-lived daemon. The statusline pushes usage. Hooks
 ## 3. How a move happens
 
 ### 3.1 Usage feed (free, push-based)
-The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine tees that to `usage/<uuid8>.json` for the session's seat, read from the inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` (write-on-change, O(ms)), and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). A session with no pooled seat writes no tee. The seat is sampled when its tee is older than `policy.usagePollTtlMs`, and for the per-model rows when the active model is a gated family, at most once per the account's sample interval (§5): the direct no-spend usage read with the seat's stored token. The compact child still sets `TOKENMAXXING_PROBE=1` so the hook entries return at once. The sample takes one attempt per interval; a failed sample doubles the interval up to 30 minutes, and a success resets it. An expired stored access token stays unmeasured until a session on that store refreshes it.
+The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine tees that to `usage/<uuid8>.json` for the session's seat, read from the inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` (write-on-change, O(ms)), and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). A session with no pooled seat writes no tee. The seat is sampled when its tee is older than `policy.usagePollTtlMs`, and for the per-model rows when the active model is a gated family, at most once per the account's sample interval (§5): the direct no-spend usage read with the seat's stored token. The compact child still sets `TOKENMAXXING_PROBE=1` so the hook entries return at once. The sample takes one attempt per interval; a failed sample doubles the interval up to 30 minutes, and a success resets it. A sample that finds the stored access token expired has Claude Code refresh it first (§5).
 
 ### 3.2 Detect + decide + signal (Stop hook, per turn)
 1. Resolve the seat: the pooled account whose store the inherited `CLAUDE_SECURESTORAGE_CONFIG_DIR` names. No seat (a session started outside the supervisor) means nothing to move.
@@ -87,7 +87,7 @@ Each terminal ran the supervisor, so each has its own child `claude`, its own `-
 The [switching policy](docs/content/docs/switching.mdx) is one rule: under both bars, hold; at or over a bar, move to the usable account that ranks first; nothing usable, queue first come first served onto a reset target (at most four waiters per account, overflow takes the soonest anyway) and wait for that reset. The same ranking places a session at launch.
 
 - Ranking (decided by consult for #79): greatest remaining headroom to the session bar divided by the number of sessions after placement, `(bar - used) / (sessions + 1)`, then highest pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, over time to its reset), then soonest weekly reset, then lowest weekly usage; unknown usage ranks last. Organization membership is not an input. Codex drops the headroom key, keeps the pace ordering and the weekly tie-breaks, and excludes accounts running in another codex session, because codex has no cross-process refresh lock and two sessions must never share a login.
-- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within the account's sample interval, over the direct no-spend usage read with the account's stored token. The interval is 15 minutes times the unused fraction of the bar closest to being reached, never under `policy.usagePollTtlMs`, and 15 minutes for an account at or over an aggregate bar. The windows are the session and weekly aggregates plus the `policy.switchModels` caps that are still under their bar, and an account with no stored aggregate gets `policy.usagePollTtlMs`. Every account is attempted about once per three ticks per pooled account, or once per its sample interval plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. The usage endpoint rate limits each account on its own and names the time to come back in the `retry-after` of its HTTP 429; that time is stored as `usageRetryAt`, and no sampler (the tick, `status`, the seat's in-decision sample) reads the account before it. An expired stored access token stays unmeasured until a session on that store refreshes it, and no sampler sends a read with it, because the endpoint answers it with 401 and, after a few, with the same 429.
+- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last sample attempt is oldest, skipping any attempted within the account's sample interval, over the direct no-spend usage read with the account's stored token. The interval is 15 minutes times the unused fraction of the bar closest to being reached, never under `policy.usagePollTtlMs`, and 15 minutes for an account at or over an aggregate bar. The windows are the session and weekly aggregates plus the `policy.switchModels` caps that are still under their bar, and an account with no stored aggregate gets `policy.usagePollTtlMs`. Every account is attempted about once per three ticks per pooled account, or once per its sample interval plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt or its sessions' latest push. The pool lock covers only the reservation and the result write, never the usage GET. The usage endpoint rate limits each account on its own and names the time to come back in the `retry-after` of its HTTP 429; that time is stored as `usageRetryAt`, and no sampler (the tick, `status`, the seat's in-decision sample) reads the account before it. No sampler sends a read with an expired stored access token, because the endpoint answers it with 401 and, after a few, with the same 429. A sample that finds the token expired first runs `claude -p /usage --no-session-persistence --safe-mode` with the account's store set and a throwaway `CLAUDE_CONFIG_DIR`, so Claude Code refreshes the token under its own lock, and then reads with the new token; the child's output is not read. A refresh that leaves the token expired fails the sample with no read, and one that clears the store flags the account `needsReauth`.
 - The depleted pause happens at the bar, not at 100; Codex has no pause and rides its account until the server refuses it, because a running sibling cannot adopt another account without restarting.
 - Neither pool has a post-swap cooldown or a manual `switch`: a move is a respawn of one session under a fixed store, so nothing another session reads is invalidated by it, and placement at launch replaces the manual pick.
 
@@ -135,7 +135,7 @@ TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/u
 
 ### 2026-09-12 (per-account stores, 1.37.0)
 
-Hermetic run on Linux under a throwaway `HOME` and `TOKENMAXXING_HOME`, a stub `claude` that records its environment, and a synthetic three-account version 2 pool with equal headroom on two accounts and the third over its session bar. Usage comes from a stub usage endpoint named by `TOKENMAXXING_OAUTH_USAGE_URL` that answers per access token. There is no `/usage` spawn.
+Hermetic run on Linux under a throwaway `HOME` and `TOKENMAXXING_HOME`, a stub `claude` that records its environment, and a synthetic three-account version 2 pool with equal headroom on two accounts and the third over its session bar. Usage comes from a stub usage endpoint named by `TOKENMAXXING_OAUTH_USAGE_URL` that answers per access token. No `/usage` output is parsed.
 
 1. **Placement - ✅.** The first supervised launch spawned the stub with `CLAUDE_SECURESTORAGE_CONFIG_DIR=stores/<first account>` and wrote its presence; the second launch, with equal headroom, landed on the other account.
 2. **Plain move - ✅.** A 95% session tee for the second session's account made its Stop hook write the marker; the supervisor relaunched `--resume <sid>` under the first account's store within a second and rewrote the presence file.

package/README.md

@@ -90,7 +90,7 @@ The bars' headroom is deliberate: it's the budget to reach a clean turn boundary
 
 Launches and moves rank usable accounts by session-window headroom per running session, `(bar - used) / (sessions + 1)`, so two fresh accounts alternate and a third session goes to whichever has more headroom left per session; ties break by pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, divided by time to its reset, highest first), then soonest weekly reset, then lowest weekly use. Organization membership is not an input.
 
-- Every periodic check tick folds fresh statusline tees into the index and samples up to three accounts whose last sample attempt is oldest, skipping any attempted within the account's sample interval (15 minutes for an empty account, shrinking to `policy.usagePollTtlMs` as it nears a bar, and 15 minutes again at or over an aggregate bar), with the direct no-spend usage read; a move reads the cached figures, which are as fresh as each account's last successful attempt or its sessions' latest push. An expired stored access token stays unmeasured until a session on that store refreshes it.
+- Every periodic check tick folds fresh statusline tees into the index and samples up to three accounts whose last sample attempt is oldest, skipping any attempted within the account's sample interval (15 minutes for an empty account, shrinking to `policy.usagePollTtlMs` as it nears a bar, and 15 minutes again at or over an aggregate bar), with the direct no-spend usage read; a move reads the cached figures, which are as fresh as each account's last successful attempt or its sessions' latest push. A sample that finds the stored access token expired has Claude Code refresh it first (`claude -p /usage` under that store) and reads with the new token.
 - When no account is usable, the session queues first come first served onto a reset target (at most four waiters per account) and pauses until that reset if it lands within `policy.maxWaitMs`, and otherwise stays put.
 
 See [How switching decides](docs/content/docs/switching.mdx) for the policy and the [cache-cost profile](docs/content/docs/switching-profile.mdx) for measurements and their limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.90.0",
+  "version": "1.92.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/cli/seat.ts

@@ -1,11 +1,4 @@
-import { codexPickCtx, observeCodex } from "../lib/codex.ts";
-import { codexStoreUsable, ensureCodexStoreHome } from "../lib/codexauth.ts";
-import { withLock } from "../lib/lock.ts";
-import { log } from "../lib/log.ts";
-import { codexPaths, codexPool } from "../lib/paths.ts";
-import { livingPresences, seatCounts, writePresence } from "../lib/presence.ts";
-import { isExhausted, pickBest } from "../lib/picker.ts";
-import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { borrowCodexSeat } from "../lib/codex.ts";
 import { emitError } from "./render.ts";
 
 export async function cmdSeat(pidRaw: string | undefined, extra: string[]): Promise<number> {
@@ -14,38 +7,7 @@ export async function cmdSeat(pidRaw: string | undefined, extra: string[]): Prom
     emitError({ message: "usage: tokenmaxxing seat --codex <pid> - print the CODEX_HOME of one pooled account, reserved until <pid> exits" });
     return 2;
   }
-  const now = Date.now();
-  const seatId = `seat-${pid}`;
-  const cfg = loadConfig();
-  await Promise.all(
-    loadAccounts(codexPool)
-      .accounts.filter((a) => a.needsReauth !== true && codexStoreUsable(a.id))
-      .map((a) => observeCodex(a, cfg, now, { probe: true, refresh: false })),
-  );
-  const granted = await withLock(codexPool.lockFile, (): { store: string; id: string; reused: boolean } | { denied: string } | null => {
-    const ctx = codexPickCtx(now, null);
-    const idx = loadAccounts(codexPool);
-    const held = livingPresences(codexPaths.presenceDir).find((p) => p.id === seatId);
-    const heldAccount = held ? (idx.accounts.find((x) => x.id === held.accountId) ?? null) : null;
-    if (heldAccount) {
-      if (heldAccount.needsReauth === true) {
-        return { denied: "the account this pid holds needs reauthentication - run `tokenmaxxing auth --codex` and borrow again" };
-      }
-      if (!codexStoreUsable(heldAccount.id)) {
-        return { denied: "the account this pid holds has no usable credential in its store - refusing to hand back a credential-less seat" };
-      }
-      return { store: ensureCodexStoreHome(heldAccount.id), id: heldAccount.id, reused: true };
-    }
-    const present = seatCounts(codexPaths.presenceDir);
-    const usable = idx.accounts.filter(
-      (a) => a.needsReauth !== true && !isExhausted(a, ctx) && !present.has(a.id) && codexStoreUsable(a.id)
-    );
-    const picked = pickBest(usable, ctx);
-    if (!picked) return null;
-    const store = ensureCodexStoreHome(picked.id);
-    writePresence({ dir: codexPaths.presenceDir, id: seatId, accountId: picked.id, pid });
-    return { store, id: picked.id, reused: false };
-  });
+  const granted = await borrowCodexSeat(pid);
   if (!granted) {
     emitError({ message: "no usable codex account (pool empty, every account live in another session, or every account at a limit) - use the ambient codex login" });
     return 1;
@@ -54,7 +16,6 @@ export async function cmdSeat(pidRaw: string | undefined, extra: string[]): Prom
     emitError({ message: granted.denied });
     return 1;
   }
-  log("seat.grant", { account: granted.id.slice(0, 8), pid, reused: granted.reused });
   console.log(granted.store);
   return 0;
 }

package/src/entries/codexsupervisor.ts

@@ -1,3 +1,4 @@
+import type { Subprocess } from "bun";
 import { existsSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -5,7 +6,7 @@ import { codexPaths, codexPool } from "../lib/paths.ts";
 import { withLock } from "../lib/lock.ts";
 import { CODEX_BIN, UNMANAGED_ENV, WRAP_DEPTH_ENV, resolveRealBin, wrapDepth } from "../lib/claudebin.ts";
 import { codexStoreUsable, ensureCodexStoreHome } from "../lib/codexauth.ts";
-import { codexPickCtx, pickCodexSeat } from "../lib/codex.ts";
+import { borrowCodexSeat, codexPickCtx, pickCodexSeat } from "../lib/codex.ts";
 import { clearPresence, livingPresences } from "../lib/presence.ts";
 import { isExhausted } from "../lib/picker.ts";
 import { exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, runPassthrough } from "../lib/supervise.ts";
@@ -17,11 +18,13 @@ import { errorMessage, log } from "../lib/log.ts";
 export const CODEX_SUPERVISOR_ID_ENV = "TOKENMAXXING_CODEX_SUPERVISOR_ID";
 
 const NONINTERACTIVE_SUBCMDS = new Set([
-  "exec", "review", "login", "logout", "mcp", "plugin", "mcp-server", "app-server",
+  "exec", "e", "review", "login", "logout", "mcp", "plugin", "mcp-server", "app-server",
   "remote-control", "app", "completion", "update", "doctor", "sandbox", "debug",
   "apply", "archive", "delete", "unarchive", "cloud", "exec-server", "features", "help",
 ]);
 
+const BORROWING_SUBCMDS = new Set(["exec", "e", "review", "app-server"]);
+
 const PASSTHROUGH_FLAGS = new Set(["--version", "-V", "--help", "-h"]);
 
 function readCodexMarker(marker: string): z.infer<typeof CodexRespawnMarkerSchema> {
@@ -40,19 +43,32 @@ const VALUE_TAKING_ROOT_FLAGS = new Set([
   "-s", "--sandbox", "-a", "--ask-for-approval", "-C", "--cd", "--add-dir", "--enable",
 ]);
 
-export function shouldManageCodex(input: { argv: string[] }): boolean {
-  if (process.env.TOKENMAXXING_PROBE) return false;
-  let firstPositional: string | null = null;
-  for (let i = 0; i < input.argv.length; i++) {
-    const arg = input.argv[i]!;
-    if (PASSTHROUGH_FLAGS.has(arg)) return false;
+function scanCodexArgs(argv: string[]): { help: boolean; positionals: string[] } {
+  const positionals: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]!;
+    if (arg === "--") break;
+    if (PASSTHROUGH_FLAGS.has(arg)) return { help: true, positionals };
     if (VALUE_TAKING_ROOT_FLAGS.has(arg)) {
       i++;
       continue;
     }
-    if (!arg.startsWith("-") && firstPositional === null) firstPositional = arg;
+    if (!arg.startsWith("-")) positionals.push(arg);
   }
-  return firstPositional === null || !NONINTERACTIVE_SUBCMDS.has(firstPositional);
+  return { help: false, positionals };
+}
+
+export function shouldManageCodex(input: { argv: string[] }): boolean {
+  if (process.env.TOKENMAXXING_PROBE) return false;
+  const { help, positionals: [sub] } = scanCodexArgs(input.argv);
+  return !help && (sub === undefined || !NONINTERACTIVE_SUBCMDS.has(sub));
+}
+
+function borrowsCodexSeat(input: { argv: string[] }): boolean {
+  if (process.env.TOKENMAXXING_PROBE || process.env[UNMANAGED_ENV] || process.env.CODEX_HOME) return false;
+  const { help, positionals: [sub, ...rest] } = scanCodexArgs(input.argv);
+  if (help || sub === undefined || !BORROWING_SUBCMDS.has(sub)) return false;
+  return sub !== "app-server" || rest.length === 0;
 }
 
 function validWanted(input: { wanted: string | null; now: number; supervisorId: string }): Account | null {
@@ -79,7 +95,34 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
   if (!shouldManageCodex({ argv }) || process.env[UNMANAGED_ENV]) {
     const passthroughEnv: Record<string, string | undefined> = { ...childEnv };
     delete passthroughEnv[CODEX_SUPERVISOR_ID_ENV];
-    return runPassthrough({ real, argv, env: passthroughEnv });
+    let child: Subprocess | null = null;
+    process.on("SIGTERM", () => {
+      if (child) child.kill("SIGTERM");
+      else process.exit(143);
+    });
+    const granted = borrowsCodexSeat({ argv }) ? await borrowCodexSeat(process.pid) : undefined;
+    const seat = granted && !("denied" in granted) ? granted : null;
+    if (seat) passthroughEnv.CODEX_HOME = seat.store;
+    else if (granted !== undefined) log("codexsupervisor.borrow_none", { reason: granted && "denied" in granted ? granted.denied : "no usable account" });
+    return runPassthrough({
+      real,
+      argv,
+      env: passthroughEnv,
+      onSpawn: (p) => {
+        child = p;
+        return seat
+          ? recordPresenceOrStop({
+              child: p,
+              dir: codexPaths.presenceDir,
+              id: `seat-${process.pid}`,
+              accountId: seat.id,
+              event: "codexsupervisor.borrow_presence_failed",
+              message: "could not key the borrowed codex seat to its child - refusing to run on an unreserved store",
+              savedTermios: null,
+            })
+          : undefined;
+      },
+    });
   }
 
   const supervisorId = crypto.randomUUID();

package/src/lib/codex.ts

@@ -2,10 +2,10 @@ import { existsSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { writeFileAtomic } from "./atomic.ts";
 import { CODEX_BIN, MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealBin, verifyRealBin } from "./claudebin.ts";
-import { codexIdentityOf, codexStoreUsable, deleteCodexStoreAuth, isCodexAccessExpiring, readCodexAuthAt, readCodexStoreAuth, writeCodexStoreAuth } from "./codexauth.ts";
+import { codexIdentityOf, codexStoreUsable, deleteCodexStoreAuth, ensureCodexStoreHome, isCodexAccessExpiring, readCodexAuthAt, readCodexStoreAuth, writeCodexStoreAuth } from "./codexauth.ts";
 import { CodexInvalidGrantError, CodexRefreshFailedError, refreshCodexAuth } from "./codexoauth.ts";
 import { deletePiStore } from "./piauth.ts";
-import { livingPresences, seatCounts } from "./presence.ts";
+import { livingPresences, seatCounts, writePresence } from "./presence.ts";
 import { CodexUsageReadError, codexLimitLabel, fetchCodexUsage } from "./codexusage.ts";
 import { codexSupervisorLink, ensurePathInRc, installCodexSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
 import { withLock } from "./lock.ts";
@@ -236,6 +236,45 @@ export function pickCodexSeat(now: number, eligible: (a: Account) => boolean = (
   return pickBest(open.filter((a) => !isExhausted(a, ctx)), ctx) ?? pickEarliestReset(open, ctx)?.account ?? null;
 }
 
+export type CodexBorrow = { store: string; id: string; reused: boolean } | { denied: string } | null;
+
+export async function borrowCodexSeat(pid: number): Promise<CodexBorrow> {
+  const now = Date.now();
+  const seatId = `seat-${pid}`;
+  const cfg = loadConfig();
+  await Promise.all(
+    loadAccounts(codexPool)
+      .accounts.filter((a) => a.needsReauth !== true && codexStoreUsable(a.id))
+      .map((a) => observeCodex(a, cfg, now, { probe: true, refresh: false })),
+  );
+  const granted = await withLock(codexPool.lockFile, (): CodexBorrow => {
+    const ctx = codexPickCtx(now, null);
+    const idx = loadAccounts(codexPool);
+    const held = livingPresences(codexPaths.presenceDir).find((p) => p.id === seatId);
+    const heldAccount = held ? (idx.accounts.find((x) => x.id === held.accountId) ?? null) : null;
+    if (heldAccount) {
+      if (heldAccount.needsReauth === true) {
+        return { denied: "the account this pid holds needs reauthentication - run `tokenmaxxing auth --codex` and borrow again" };
+      }
+      if (!codexStoreUsable(heldAccount.id)) {
+        return { denied: "the account this pid holds has no usable credential in its store - refusing to hand back a credential-less seat" };
+      }
+      return { store: ensureCodexStoreHome(heldAccount.id), id: heldAccount.id, reused: true };
+    }
+    const present = seatCounts(codexPaths.presenceDir);
+    const usable = idx.accounts.filter(
+      (a) => a.needsReauth !== true && !isExhausted(a, ctx) && !present.has(a.id) && codexStoreUsable(a.id)
+    );
+    const picked = pickBest(usable, ctx);
+    if (!picked) return null;
+    const store = ensureCodexStoreHome(picked.id);
+    writePresence({ dir: codexPaths.presenceDir, id: seatId, accountId: picked.id, pid });
+    return { store, id: picked.id, reused: false };
+  });
+  if (granted && !("denied" in granted)) log("seat.grant", { account: granted.id.slice(0, 8), pid, reused: granted.reused });
+  return granted;
+}
+
 export const codex: Provider = {
   name: "codex",
   flag: " --codex",

package/src/lib/grokusage.ts

@@ -20,7 +20,7 @@ const CreditsPeriodSchema = z.looseObject({
 
 const CreditsConfigSchema = z.looseObject({
   currentPeriod: CreditsPeriodSchema,
-  creditUsagePercent: z.number(),
+  creditUsagePercent: z.number().default(0),
 });
 
 const CreditsBillingSchema = z.looseObject({

package/src/lib/sample.ts

@@ -1,13 +1,17 @@
-import { readStore } from "./credstore.ts";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { CLAUDE_BIN, MAX_WRAP_DEPTH, resolveRealBin, WRAP_DEPTH_ENV } from "./claudebin.ts";
+import { deleteItem, readStore, storeTarget } from "./credstore.ts";
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, isDeadCredential } from "./oauth.ts";
-import { claudePool, paths } from "./paths.ts";
+import { claudePool, paths, storeDirFor } from "./paths.ts";
 import { barFor, gatedWindows, landWindows, liveUsed, thresholdBars } from "./picker.ts";
 import { seatCounts } from "./presence.ts";
 import type { Observation } from "./provider.ts";
 import { loadAccounts, loadUsageSnapshot, saveAccounts } from "./state.ts";
-import { fetchUsageDirect, mergeWindows, windowsOf } from "./usage.ts";
+import { fetchUsageDirect, mergeWindows, scrubCredentialEnv, windowsOf } from "./usage.ts";
 import type { Account, Config, Thresholds, UsageWindows, Window } from "./types.ts";
 
 export type SampleOutcome = { ok: true; usage: UsageWindows; via: "get" } | { ok: false; reason: string; retryAt?: number };
@@ -76,11 +80,46 @@ function rateLimitedReason(retryAt: number, now: number): string {
   return `the usage endpoint rate limited this account, next read in ${Math.ceil((retryAt - now) / 60_000)}m`;
 }
 
-const EXPIRED_REASON = "the stored access token expired, next read after a session on this account refreshes it";
+const REFRESH_KILL_MS = 60_000;
+
+async function refreshStore(account: Account): Promise<number | null> {
+  const home = mkdtempSync(join(tmpdir(), "tokenmaxxing-refresh-"));
+  const env = scrubCredentialEnv({ ...process.env, TOKENMAXXING_PROBE: "1", [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) });
+  env.CLAUDE_CONFIG_DIR = home;
+  env.CLAUDE_SECURESTORAGE_CONFIG_DIR = storeDirFor(account.id);
+  try {
+    const p = Bun.spawn([resolveRealBin(CLAUDE_BIN), "-p", "/usage", "--no-session-persistence", "--safe-mode"], {
+      env,
+      cwd: home,
+      stdin: "ignore",
+      stdout: "ignore",
+      stderr: "ignore",
+      timeout: REFRESH_KILL_MS,
+      killSignal: "SIGKILL",
+    });
+    await p.exited;
+    return p.exitCode;
+  } finally {
+    rmSync(home, { recursive: true, force: true });
+    await withLock(claudePool.lockFile, async () => {
+      if (loadAccounts(claudePool).accounts.some((a) => a.id === account.id)) return;
+      await deleteItem(storeTarget(account.id));
+      rmSync(storeDirFor(account.id), { recursive: true, force: true });
+      rmSync(`${storeDirFor(account.id)}.lock`, { recursive: true, force: true });
+    });
+  }
+}
 
 export async function runSample(account: Account, prepared: { token: string; expiresAt: number }): Promise<SampleOutcome> {
-  if (prepared.expiresAt <= Date.now()) return { ok: false, reason: EXPIRED_REASON };
-  const read = await fetchUsageDirect(prepared.token);
+  let token = prepared.token;
+  if (prepared.expiresAt <= Date.now()) {
+    const exit = await refreshStore(account);
+    const refreshed = await prepareSample(account);
+    if (!refreshed.ok) return refreshed;
+    if (refreshed.expiresAt <= Date.now()) return { ok: false, reason: `the stored access token expired and claude did not refresh it (exit ${exit ?? "killed"})` };
+    token = refreshed.token;
+  }
+  const read = await fetchUsageDirect(token);
   if (read.ok) return { ok: true, usage: read.usage, via: "get" };
   if (read.retryAt == null) return { ok: false, reason: "usage read failed (see log)" };
   return { ok: false, reason: rateLimitedReason(read.retryAt, Date.now()), retryAt: read.retryAt };
@@ -89,9 +128,7 @@ export async function runSample(account: Account, prepared: { token: string; exp
 export async function readyToSample(account: Account, now: number): Promise<PreparedSample> {
   const blockedUntil = usageBlockedUntil(account, now);
   if (blockedUntil != null) return { ok: false, reason: rateLimitedReason(blockedUntil, now) };
-  const prepared = await prepareSample(account);
-  if (prepared.ok && prepared.expiresAt <= now) return { ok: false, reason: EXPIRED_REASON };
-  return prepared;
+  return prepareSample(account);
 }
 
 export async function sampleAccountUsage(account: Account): Promise<SampleOutcome> {

package/src/lib/supervise.ts

@@ -75,9 +75,9 @@ export function loopGuardTripped(product: WrappedProduct): boolean {
   return false;
 }
 
-export async function runPassthrough(input: { real: string; argv: string[]; env: Record<string, string | undefined>; onSpawn?: (child: Subprocess) => void }): Promise<number> {
+export async function runPassthrough(input: { real: string; argv: string[]; env: Record<string, string | undefined>; onSpawn?: (child: Subprocess) => void | Promise<void> }): Promise<number> {
   const p = Bun.spawn([input.real, ...input.argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: input.env });
-  input.onSpawn?.(p);
+  await input.onSpawn?.(p);
   await p.exited;
   return exitStatus(p);
 }