tokenmaxxing 1.89.0 → 1.90.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: 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. An expired stored access token stays unmeasured until a session on that store refreshes it.
 
 ### 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 `policy.usagePollTtlMs`, over the direct no-spend usage read with the account's stored token, so every account is attempted about once per three ticks per pooled account, or once per `policy.usagePollTtlMs` 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.
+- 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.
 - 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.
 

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 `policy.usagePollTtlMs`, 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. An expired stored access token stays unmeasured until a session on that store refreshes it.
 - 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.
@@ -112,7 +112,7 @@ See [How switching decides](docs/content/docs/switching.mdx) for the policy and
 }
 ```
 
-`thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `projectionMargin` is a fixed safety margin subtracted from the session bar only (default 3), so a large turn is less likely to blow past the 5-hour bar between checks; the weekly bar takes no margin because one turn cannot overshoot a week; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is how long a usage sample stays fresh, for a seat's own sample and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers); `checkIntervalMs` is the periodic check tick (default 60s), which `init` writes into the timer - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick. `claudeBin`, `codexBin`, `grokBin`, `opencodeBin`, and `piBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, `TOKENMAXXING_OPENCODE_BIN`, and `TOKENMAXXING_PI_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
+`thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `projectionMargin` is a fixed safety margin subtracted from the session bar only (default 3), so a large turn is less likely to blow past the 5-hour bar between checks; the weekly bar takes no margin because one turn cannot overshoot a week; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is the shortest sample interval, the one an account near a bar gets, for a seat's own sample, for `status`, and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers); `checkIntervalMs` is the periodic check tick (default 60s), which `init` writes into the timer - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick. `claudeBin`, `codexBin`, `grokBin`, `opencodeBin`, and `piBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, `TOKENMAXXING_OPENCODE_BIN`, and `TOKENMAXXING_PI_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
 
 State lives in `~/.config/tokenmaxxing/`; outside it the install touches Claude Code's `settings.json`, codex's `hooks.json`, the timer and usage hub units, and your shell rc. Each account's credential store is `stores/<uuid8>/`, which Claude Code reads and refreshes as its own: on macOS the credential is a login-keychain item keyed by the store path (never plaintext on disk), on Linux a 0600 `.credentials.json` inside the store (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.89.0",
+  "version": "1.90.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/status.ts

@@ -27,7 +27,7 @@ type StatusAccount = {
   usage: UsageReport | null;
   usageAt: number | null;
   limitsAt: number | null;
-  sample: SampleReport | { ok: true; source: "cached" };
+  sample: SampleReport;
 };
 
 type PoolReport = {
@@ -109,6 +109,10 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
             stored.usageRetryAt = a.usageRetryAt;
             dirty = true;
           }
+          if ((a.lastProbeAt ?? 0) > (stored.lastProbeAt ?? 0)) {
+            stored.lastProbeAt = a.lastProbeAt;
+            dirty = true;
+          }
           if (a.lastUsageAt != null && (stored.lastUsageAt == null || a.lastUsageAt > stored.lastUsageAt)) {
             landWindows(stored, p.mergeWindows(a.windows, stored.windows), a.lastUsageAt, bars);
             if (a.email != null) stored.email = a.email;

package/src/lib/claude.ts

@@ -13,7 +13,7 @@ import { landWindows, pickBest, pickEarliestReset, thresholdBars, type PickCtx }
 import { deletePiStore } from "./piauth.ts";
 import { livingPresences } from "./presence.ts";
 import { StoreUnusableError, type Observation, type Provider, type SampleReport } from "./provider.ts";
-import { foldTee, sampleAccountUsage, teeObservation, usageBlockedUntil } from "./sample.ts";
+import { foldTee, readyToSample, runSample, sampleAccountUsage, sampleDue, sampleIntervalMs, teeObservation, usageBlockedUntil } from "./sample.ts";
 import { clearUsageSnapshot, liveWaitClaims, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
 import { fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredentialEnv, windowsOf } from "./usage.ts";
@@ -33,11 +33,10 @@ function presence(): Map<string, number> {
 const PROBE_BACKOFF_CAP_MS = 30 * 60 * 1000;
 
 async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean; perModel: boolean }): Promise<Observation | null> {
-  const ttl = cfg.policy.usagePollTtlMs;
-  const interval = Math.min(ttl * 2 ** (account.probeFails ?? 0), PROBE_BACKOFF_CAP_MS);
+  const interval = Math.min(sampleIntervalMs(account, cfg, now) * 2 ** (account.probeFails ?? 0), PROBE_BACKOFF_CAP_MS);
   const probeAttempted = account.lastProbeAt != null && now - account.lastProbeAt <= interval;
   const snap = loadUsageSnapshot(account.id);
-  const fresh = snap != null && now - snap.at <= ttl;
+  const fresh = snap != null && now - snap.at <= cfg.policy.usagePollTtlMs;
   if (opts.probe && !probeAttempted && usageBlockedUntil(account, now) == null && (!fresh || opts.perModel)) {
     const startedAt = Date.now();
     const outcome = await sampleAccountUsage(account);
@@ -64,9 +63,10 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
   return teeObservation(current);
 }
 
-async function samplePool(accounts: Account[]): Promise<Map<string, SampleReport>> {
+async function samplePool(accounts: Account[], _liveId: string | null, now: number): Promise<Map<string, SampleReport>> {
   const reports = new Map<string, SampleReport>();
-  const bars = thresholdBars(loadConfig());
+  const cfg = loadConfig();
+  const bars = thresholdBars(cfg);
   await Promise.all(
     accounts.map(async (a) => {
       const tee = loadUsageSnapshot(a.id);
@@ -76,7 +76,17 @@ async function samplePool(accounts: Account[]): Promise<Map<string, SampleReport
         reports.set(a.id, { ok: true, source: "statusline" });
         return;
       }
-      const outcome = await sampleAccountUsage(a);
+      const ready = await readyToSample(a, now);
+      if (!ready.ok) {
+        reports.set(a.id, { ok: false, reason: ready.reason });
+        return;
+      }
+      if (!sampleDue(a, cfg, now)) {
+        reports.set(a.id, { ok: true, source: "cached" });
+        return;
+      }
+      a.lastProbeAt = now;
+      const outcome = await runSample(a, ready);
       if (!outcome.ok) {
         if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
         reports.set(a.id, { ok: false, reason: outcome.reason });

package/src/lib/picker.ts

@@ -49,7 +49,7 @@ export function liveUsed(w: Window, now: number): number {
   return w.usedPercentage;
 }
 
-function barFor(w: Window, thresholds: Thresholds): number {
+export function barFor(w: Window, thresholds: Thresholds): number {
   return isSessionWindow(w) ? thresholds.session : thresholds.weekly;
 }
 

package/src/lib/provider.ts

@@ -4,7 +4,7 @@ import type { Account, Config, Window } from "./types.ts";
 
 export type Observation = { windows: Window[]; at: number };
 
-export type SampleReport = { ok: true; source: "statusline" | "probe" } | { ok: false; reason: string };
+export type SampleReport = { ok: true; source: "statusline" | "probe" | "cached" } | { ok: false; reason: string };
 
 export type SwapFailure = "dead-grant" | "skip" | "fatal";
 

package/src/lib/sample.ts

@@ -3,16 +3,36 @@ import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, isDeadCredential } from "./oauth.ts";
 import { claudePool, paths } from "./paths.ts";
-import { landWindows, thresholdBars } from "./picker.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 type { Account, Config, Thresholds, UsageWindows } from "./types.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 };
 
-type PreparedSample = { ok: true; token: string } | { ok: false; reason: string };
+type PreparedSample = { ok: true; token: string; expiresAt: number } | { ok: false; reason: string };
+
+const SAMPLE_INTERVAL_MAX_MS = 15 * 60 * 1000;
+
+export function sampleIntervalMs(account: Account, cfg: Config, now: number): number {
+  const floor = cfg.policy.usagePollTtlMs;
+  const bars = thresholdBars(cfg);
+  const aggregates = account.windows.filter((w) => w.name == null);
+  if (aggregates.length === 0) return floor;
+  const blocked = (w: Window) => liveUsed(w, now) >= barFor(w, bars);
+  if (aggregates.some(blocked)) return Math.max(floor, SAMPLE_INTERVAL_MAX_MS);
+  const open = [...aggregates, ...gatedWindows(account, cfg.policy.switchModels).filter((w) => !blocked(w))];
+  const spare = Math.min(...open.map((w) => 1 - liveUsed(w, now) / barFor(w, bars)));
+  return Math.max(floor, SAMPLE_INTERVAL_MAX_MS * spare);
+}
+
+const sampledAt = (a: Account) => Math.max(a.lastUsageAt ?? 0, a.lastProbeAt ?? 0);
+
+export function sampleDue(account: Account, cfg: Config, now: number): boolean {
+  return now - sampledAt(account) > sampleIntervalMs(account, cfg, now);
+}
 
 export function teeObservation(account: Account): Observation | null {
   const stored = account.lastUsageAt != null ? { windows: account.windows, at: account.lastUsageAt } : null;
@@ -45,7 +65,7 @@ export async function prepareSample(account: Account): Promise<PreparedSample> {
   }
   if (!account.oauthAccount) return { ok: false, reason: "account record has no oauthAccount - run `tokenmaxxing auth`" };
   account.tier = claudeTierLabel(creds) ?? account.tier;
-  return { ok: true, token: creds.accessToken };
+  return { ok: true, token: creds.accessToken, expiresAt: creds.expiresAt };
 }
 
 export function usageBlockedUntil(account: Account, now: number): number | null {
@@ -56,19 +76,27 @@ 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`;
 }
 
-export async function runSample(account: Account, token: string): Promise<SampleOutcome> {
-  const read = await fetchUsageDirect(token);
+const EXPIRED_REASON = "the stored access token expired, next read after a session on this account refreshes it";
+
+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);
   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 };
 }
 
-export async function sampleAccountUsage(account: Account): Promise<SampleOutcome> {
-  const now = Date.now();
+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);
-  return prepared.ok ? runSample(account, prepared.token) : prepared;
+  if (prepared.ok && prepared.expiresAt <= now) return { ok: false, reason: EXPIRED_REASON };
+  return prepared;
+}
+
+export async function sampleAccountUsage(account: Account): Promise<SampleOutcome> {
+  const ready = await readyToSample(account, Date.now());
+  return ready.ok ? runSample(account, ready) : ready;
 }
 
 const SAMPLE_BATCH = 3;
@@ -80,17 +108,16 @@ export async function sampleOldest(cfg: Config): Promise<void> {
     const idx = loadAccounts(claudePool);
     let dirty = false;
     for (const a of idx.accounts) dirty = foldTee(a, thresholdBars(cfg)) || dirty;
-    const sampledAt = (a: Account) => Math.max(a.lastUsageAt ?? 0, a.lastProbeAt ?? 0);
     const seats = seatCounts(paths.presenceDir);
     const stale = idx.accounts
-      .filter((a) => a.needsReauth !== true && now - sampledAt(a) > cfg.policy.usagePollTtlMs)
+      .filter((a) => a.needsReauth !== true && sampleDue(a, cfg, now))
       .sort((a, b) => Number(seats.has(b.id)) - Number(seats.has(a.id)) || sampledAt(a) - sampledAt(b))
       .slice(0, SAMPLE_BATCH);
     if (stale.length === 0) {
       if (dirty) saveAccounts(claudePool, idx);
       return [];
     }
-    const batch: { account: Account; token: string }[] = [];
+    const batch: { account: Account; prepared: { token: string; expiresAt: number } }[] = [];
     for (const target of stale) {
       target.lastProbeAt = now;
       const prepared = await prepareSample(target);
@@ -101,15 +128,15 @@ export async function sampleOldest(cfg: Config): Promise<void> {
         continue;
       }
       target.storeFails = 0;
-      if (usageBlockedUntil(target, now) == null) batch.push({ account: target, token: prepared.token });
+      if (usageBlockedUntil(target, now) == null) batch.push({ account: target, prepared });
     }
     saveAccounts(claudePool, idx);
     return batch;
   });
   await Promise.all(
-    reserved.map(async ({ account, token }) => {
+    reserved.map(async ({ account, prepared }) => {
       const startedAt = Date.now();
-      const outcome = await runSample(account, token);
+      const outcome = await runSample(account, prepared);
       await withLock(claudePool.lockFile, () => {
         const idx = loadAccounts(claudePool);
         const stored = idx.accounts.find((a) => a.id === account.id);