tokenmaxxing 1.46.0 → 1.48.0

package/DESIGN.md

@@ -40,7 +40,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
   - `bin/claude` - the supervisor.
 - Per-account **credential stores** follow the platform's Claude Code store: macOS = a login-keychain item keyed by the store path (never plaintext on disk); Linux = a 0600 `.credentials.json` inside the 0700 store directory (the same plaintext model claude itself uses - its Linux build has no keyring path at all, binary-verified 2.1.205). One `credstore` facade dispatches on a `{kind: keychain|file}` target; call sites never branch on platform. tokenmaxxing writes a store once, at onboarding; Claude Code's own refresh is the only writer afterwards.
 
-- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check` once per tick (`policy.checkIntervalMs`, 60s by default): it folds fresh tees into the index and samples the account whose `/usage` figure is oldest, so the cached figures every placement reads stay fresh.
+- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check` once per tick (`policy.checkIntervalMs`, 60s by default): it folds fresh tees into the index and samples the accounts whose `/usage` figures are oldest (up to three per tick), so the cached figures every placement reads stay fresh.
 
 The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. The `claude` binary, `~/.claude`, `~/.claude.json`, and Claude Code's default credential store are untouched.
 
@@ -83,7 +83,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, wait for the soonest 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 weekly pace pressure (remaining weekly percent over time to the weekly reset), then soonest weekly reset, then lowest weekly usage; unknown usage ranks last. Organization membership is not an input. Codex keeps the pure pace ordering 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 the account whose last `/usage` attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, under that account's store, so every account is attempted about once per tick 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` child.
+- Selection reads the cached figures only, after folding every account's tee. Each periodic check tick samples up to three accounts whose last `/usage` attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, under each account's store, 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` child.
 - 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.46.0",
+  "version": "1.48.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

@@ -7,7 +7,7 @@ import { opencodeGo } from "../lib/opencodego.ts";
 import { loadAccounts, loadConfig, saveAccounts } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
 import { codexPool, grokPool, opencodeGoPool } from "../lib/paths.ts";
-import { earliestReset, isExhausted, isSessionWindow, limitWindows, nextWeeklyReset, sessionWindow, thresholdBars, weeklyWindow } from "../lib/picker.ts";
+import { earliestReset, gatedWindows, isExhausted, isSessionWindow, limitWindows, liveUsed, nextWeeklyReset, sessionWindow, thresholdBars, weeklyWindow } from "../lib/picker.ts";
 import type { Provider, SampleReport } from "../lib/provider.ts";
 import { bar, c, count, emitJson, fmtAgo } from "./render.ts";
 import { ThresholdsSchema, type Account, type Config, type Window } from "../lib/types.ts";
@@ -50,6 +50,7 @@ const PoolReportSchema = z.object({
   thresholds: ThresholdsSchema,
   bars: ThresholdsSchema,
   projectionMargin: z.number(),
+  gatedNote: z.string().nullable(),
   accounts: z.array(StatusAccountSchema),
 });
 type PoolReport = z.infer<typeof PoolReportSchema>;
@@ -77,6 +78,29 @@ function usageReport(a: Account, now: number): StatusAccount["usage"] {
   };
 }
 
+function gatedNote(accounts: Account[], families: string[] | null, weeklyBar: number, now: number): string | null {
+  const groups = new Map<string, { carriers: number; capped: number }>();
+  for (const a of accounts) {
+    if (a.needsReauth === true) continue;
+    for (const w of gatedWindows(a, families)) {
+      const key = (w.name ?? "").toLowerCase();
+      const g = groups.get(key) ?? { carriers: 0, capped: 0 };
+      g.carriers++;
+      if (liveUsed(w, now) >= weeklyBar) g.capped++;
+      groups.set(key, g);
+    }
+  }
+  const capped = [...groups.entries()].filter(([, g]) => g.capped === g.carriers).map(([name]) => name);
+  if (capped.length === 0) return null;
+  const headroom = accounts.filter((a) => {
+    if (a.needsReauth === true) return false;
+    const w = weeklyWindow(a);
+    return w != null && liveUsed(w, now) < weeklyBar;
+  }).length;
+  if (headroom === 0) return null;
+  return `every ${capped.join(", ")} cap is at the weekly bar, but ${count({ n: headroom, noun: "account" })} still ha${headroom === 1 ? "s" : "ve"} weekly aggregate headroom for other models`;
+}
+
 async function collect(p: Provider, cfg: Config, now: number, cached: boolean): Promise<PoolReport> {
   let idx = loadAccounts(p.pool);
   let reports = new Map<string, SampleReport>();
@@ -119,6 +143,7 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
     thresholds: { session: cfg.thresholds.session, weekly: cfg.thresholds.weekly },
     bars,
     projectionMargin: cfg.policy.projectionMargin,
+    gatedNote: gatedNote(idx.accounts, ctx.families, bars.weekly, now),
     accounts,
   };
 }
@@ -232,6 +257,10 @@ function renderPool(p: Provider, pool: PoolReport, header: string, now: number,
   console.log(c.dim(header));
   console.log();
   renderGrid(pool.accounts.map((a) => card(p, a, now, staleAfterMs)));
+  if (pool.gatedNote) {
+    console.log(c.yellow(pool.gatedNote));
+    console.log();
+  }
 }
 
 export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {}): Promise<number> {

package/src/lib/claude.ts

@@ -35,15 +35,18 @@ function presence(): Map<string, number> {
   return seatCounts(paths.presenceDir);
 }
 
+const PROBE_BACKOFF_CAP_MS = 30 * 60 * 1000;
+
 async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null> {
   const ttl = cfg.policy.usagePollTtlMs;
-  const probeAttempted = account.lastProbeAt != null && now - account.lastProbeAt <= ttl;
+  const interval = Math.min(ttl * 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 needsPerModel = snap != null && gatedFamilies(snap.state.model, cfg.policy.switchModels).length > 0;
   if (opts.probe && !probeAttempted && (!fresh || needsPerModel)) {
     const startedAt = Date.now();
-    const outcome = await probeAccountUsage(account);
+    const outcome = await probeAccountUsage(account, { retries: 0 });
     await withLock(claudePool.lockFile, () => {
       const idx = loadAccounts(claudePool);
       const a = idx.accounts.find((x) => x.id === account.id);
@@ -51,9 +54,14 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
       a.lastProbeAt = startedAt;
       a.tier = account.tier;
       if (account.needsReauth) a.needsReauth = true;
-      if (outcome.ok && (a.lastUsageAt == null || startedAt > a.lastUsageAt)) {
-        a.windows = mergeWindows(windowsOf(outcome.usage, startedAt), a.windows);
-        a.lastUsageAt = startedAt;
+      if (outcome.ok) {
+        a.probeFails = 0;
+        if (a.lastUsageAt == null || startedAt > a.lastUsageAt) {
+          a.windows = mergeWindows(windowsOf(outcome.usage, startedAt), a.windows);
+          a.lastUsageAt = startedAt;
+        }
+      } else {
+        a.probeFails = (a.probeFails ?? 0) + 1;
       }
       saveAccounts(claudePool, idx);
     });

package/src/lib/sample.ts

@@ -1,6 +1,5 @@
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
-import { minBy } from "es-toolkit";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
 import { readStore } from "./credstore.ts";
@@ -69,11 +68,14 @@ export async function runProbe(account: Account, dir: string, opts: { retries?:
   return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
 }
 
-export async function probeAccountUsage(account: Account): Promise<SampleOutcome> {
+export async function probeAccountUsage(account: Account, opts: { retries?: number } = {}): Promise<SampleOutcome> {
   const prepared = await prepareProbe(account);
-  return prepared.ok ? runProbe(account, prepared.dir, {}) : prepared;
+  return prepared.ok ? runProbe(account, prepared.dir, opts) : prepared;
 }
 
+const SAMPLE_BATCH = 3;
+const STORE_FAILS_REAUTH = 5;
+
 export async function sampleOldest(cfg: Config): Promise<void> {
   const reserved = await withLock(claudePool.lockFile, async () => {
     const now = Date.now();
@@ -81,52 +83,64 @@ export async function sampleOldest(cfg: Config): Promise<void> {
     let dirty = false;
     for (const a of idx.accounts) dirty = foldTee(a) || dirty;
     const sampledAt = (a: Account) => Math.max(a.lastUsageAt ?? 0, a.lastProbeAt ?? 0);
-    const stale = idx.accounts.filter((a) => a.needsReauth !== true && now - sampledAt(a) > cfg.policy.usagePollTtlMs);
-    const target = minBy(stale, sampledAt);
-    if (!target) {
+    const stale = idx.accounts
+      .filter((a) => a.needsReauth !== true && now - sampledAt(a) > cfg.policy.usagePollTtlMs)
+      .sort((a, b) => sampledAt(a) - sampledAt(b))
+      .slice(0, SAMPLE_BATCH);
+    if (stale.length === 0) {
       if (dirty) saveAccounts(claudePool, idx);
-      return null;
-    }
-    target.lastProbeAt = now;
-    const prepared = await prepareProbe(target, "-tick");
-    saveAccounts(claudePool, idx);
-    if (!prepared.ok) {
-      log("sample.failed", { account: target.id.slice(0, 8), reason: prepared.reason.slice(0, 200) });
-      return null;
+      return [];
     }
-    let token: string | null = null;
-    if (!seatCounts(paths.presenceDir).has(target.id)) {
-      const creds = await readStore(target.id).catch(() => null);
-      if (creds && !isDeadCredential(creds) && !isAccessTokenExpiring(creds)) token = creds.accessToken;
-    }
-    return { account: target, dir: prepared.dir, token };
-  });
-  if (!reserved) return;
-  const startedAt = Date.now();
-  let via = "probe";
-  let outcome: SampleOutcome;
-  if (reserved.token) {
-    const usage = await fetchUsageDirect(reserved.token);
-    if (usage) {
-      via = "get";
-      outcome = { ok: true, usage };
-    } else {
-      outcome = await runProbe(reserved.account, reserved.dir, { retries: 0 });
+    const batch: { account: Account; dir: string; token: string | null }[] = [];
+    for (const target of stale) {
+      target.lastProbeAt = now;
+      const prepared = await prepareProbe(target, "-tick");
+      if (!prepared.ok) {
+        target.storeFails = (target.storeFails ?? 0) + 1;
+        if (target.storeFails >= STORE_FAILS_REAUTH) target.needsReauth = true;
+        log("sample.failed", { account: target.id.slice(0, 8), reason: prepared.reason.slice(0, 200) });
+        continue;
+      }
+      target.storeFails = 0;
+      let token: string | null = null;
+      if (!seatCounts(paths.presenceDir).has(target.id)) {
+        const creds = await readStore(target.id).catch(() => null);
+        if (creds && !isDeadCredential(creds) && !isAccessTokenExpiring(creds)) token = creds.accessToken;
+      }
+      batch.push({ account: target, dir: prepared.dir, token });
     }
-  } else {
-    outcome = await runProbe(reserved.account, reserved.dir, { retries: 0 });
-  }
-  await withLock(claudePool.lockFile, () => {
-    const idx = loadAccounts(claudePool);
-    const stored = idx.accounts.find((a) => a.id === reserved.account.id);
-    if (stored && outcome.ok && (stored.lastUsageAt == null || startedAt > stored.lastUsageAt)) {
-      stored.windows = mergeWindows(windowsOf(outcome.usage, startedAt), stored.windows);
-      stored.lastUsageAt = startedAt;
-      saveAccounts(claudePool, idx);
-    }
-    log(outcome.ok ? "sample.ok" : "sample.failed", {
-      account: reserved.account.id.slice(0, 8),
-      ...(outcome.ok ? { via } : { reason: outcome.reason.slice(0, 200) }),
-    });
+    saveAccounts(claudePool, idx);
+    return batch;
   });
+  await Promise.all(
+    reserved.map(async ({ account, dir, token }) => {
+      const startedAt = Date.now();
+      let via = "probe";
+      let outcome: SampleOutcome;
+      if (token) {
+        const usage = await fetchUsageDirect(token);
+        if (usage) {
+          via = "get";
+          outcome = { ok: true, usage };
+        } else {
+          outcome = await runProbe(account, dir, { retries: 0 });
+        }
+      } else {
+        outcome = await runProbe(account, dir, { retries: 0 });
+      }
+      await withLock(claudePool.lockFile, () => {
+        const idx = loadAccounts(claudePool);
+        const stored = idx.accounts.find((a) => a.id === account.id);
+        if (stored && outcome.ok && (stored.lastUsageAt == null || startedAt > stored.lastUsageAt)) {
+          stored.windows = mergeWindows(windowsOf(outcome.usage, startedAt), stored.windows);
+          stored.lastUsageAt = startedAt;
+          saveAccounts(claudePool, idx);
+        }
+        log(outcome.ok ? "sample.ok" : "sample.failed", {
+          account: account.id.slice(0, 8),
+          ...(outcome.ok ? { via } : { reason: outcome.reason.slice(0, 200) }),
+        });
+      });
+    }),
+  );
 }

package/src/lib/types.ts

@@ -70,6 +70,8 @@ export const AccountSchema = z.object({
   windows: z.array(WindowSchema).default([]),
   lastUsageAt: z.number().optional(),
   lastProbeAt: z.number().optional(),
+  probeFails: z.number().optional(),
+  storeFails: z.number().optional(),
   enforcedUntil: z.number().optional(),
   needsReauth: z.boolean().optional(),
   oauthAccount: OAuthAccountSchema.optional(),