tokenmaxxing 1.45.0 → 1.47.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.
 
@@ -95,7 +95,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 
 ## 6. Honest papercuts
 - **A move restarts the process.** Every move is a `claude` stop and `--resume`; anything typed in the split second before the SIGTERM is lost, the supervisor resets terminal mode so nothing is left garbled, and the first turn on the new account re-uploads context once (prompt cache is org-scoped). A bar-triggered move compacts on the old account first so that upload is the summary, not the transcript; a move after a refusal cannot, and re-uploads the full context.
-- **Single-turn overshoot.** If one turn jumps from under the threshold straight past the wall, that turn ends rate-limited; the StopFailure hook walls the seat and moves the session, and the next prompt continues the conversation on the fresh account. Projected threshold reduces this.
+- **Single-turn overshoot.** If one turn jumps from under the threshold straight past the wall, that turn ends rate-limited; the StopFailure hook walls the seat and moves the session, and the next prompt continues the conversation on the fresh account. The static session-bar margin (`policy.projectionMargin`, default 3) reduces this.
 - **Unsupervised sessions are not moved.** A claude started outside the supervisor runs on whatever login its environment names, by default Claude Code's default store, which tokenmaxxing never writes.
 - **One shared identity file.** `~/.claude.json` keeps a single `oauthAccount`, which Claude Code rewrites after whichever session refreshed last, so `/status` can show another session's email. The store decides which credential a session uses.
 - **Dead stores.** A refresh Claude Code cannot complete dead-clears the store; the sampler and the decision recognize the empty tokens without a request, flag the account, and `auth` repairs it in place.

package/README.md

@@ -101,7 +101,7 @@ See [How switching decides](docs/content/docs/switching.mdx) for the policy and
 {
   "thresholds": { "session": 90, "weekly": 98 },
   "policy": {
-    "projectionMargin": 0,
+    "projectionMargin": 3,
     "switchModels": ["fable"],
     "usagePollTtlMs": 90000,
     "checkIntervalMs": 60000
@@ -109,7 +109,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 each threshold bar (effective bar = threshold - margin), so a large turn is less likely to blow past a bar between checks; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is how long a `/usage` attempt stays fresh, for a seat's per-model poll and for the account each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a soonest 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.
+`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` attempt stays fresh, for a seat's per-model poll and for the account each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a soonest 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.
 
 State lives entirely in `~/.config/tokenmaxxing/`. 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.45.0",
+  "version": "1.47.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/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/picker.ts

@@ -6,7 +6,7 @@ import { AccountSchema, ThresholdsSchema, type Account, type Config, type Thresh
 export function thresholdBars(cfg: Config): Thresholds {
   return {
     session: cfg.thresholds.session - cfg.policy.projectionMargin,
-    weekly: cfg.thresholds.weekly - cfg.policy.projectionMargin,
+    weekly: cfg.thresholds.weekly,
   };
 }
 
@@ -87,11 +87,22 @@ export function earliestReset(a: Account, now: number): number {
   return Math.min(session != null && session > now ? session : Number.POSITIVE_INFINITY, weeklyExpiry(a, now));
 }
 
-export function pacePressure(a: Account, now: number): number {
+function windowResetAt(w: Window, now: number): number | null {
+  if (w.resetsAt != null) return nextWeeklyReset(w.resetsAt, now);
+  if (w.windowSeconds != null) return w.sampledAt + w.windowSeconds * 1000;
+  return null;
+}
+
+export function pacePressure(a: Account, ctx: PickCtx): number {
+  const binding = minBy(gatedWindows(a, ctx.families), (w) => Math.max(0, 100 - liveUsed(w, ctx.now)));
+  if (binding != null) {
+    const reset = windowResetAt(binding, ctx.now);
+    if (reset != null) return Math.max(0, 100 - liveUsed(binding, ctx.now)) / Math.max(1, reset - ctx.now);
+  }
   const weekly = weeklyWindow(a);
-  const reset = nextWeeklyReset(weekly?.resetsAt ?? null, now);
+  const reset = nextWeeklyReset(weekly?.resetsAt ?? null, ctx.now);
   if (weekly == null || reset == null) return 0;
-  return Math.max(0, 100 - liveUsed(weekly, now)) / Math.max(1, reset - now);
+  return Math.max(0, 100 - liveUsed(weekly, ctx.now)) / Math.max(1, reset - ctx.now);
 }
 
 export function seatHeadroom(a: Account, ctx: PickCtx): number {
@@ -102,7 +113,7 @@ export function seatHeadroom(a: Account, ctx: PickCtx): number {
 
 const swapPreference = (ctx: PickCtx) => [
   ...(ctx.seats == null ? [] : [(a: Account) => -seatHeadroom(a, ctx)]),
-  (a: Account) => -pacePressure(a, ctx.now),
+  (a: Account) => -pacePressure(a, ctx),
   (a: Account) => weeklyExpiry(a, ctx.now),
   (a: Account) => weeklyWindow(a)?.usedPercentage ?? 101,
 ];
@@ -116,7 +127,7 @@ export function currentWins(active: Account | null, accounts: Account[], ctx: Pi
   if (!active || active.needsReauth || isExhausted(active, ctx)) return false;
   const best = pickBest(accounts, { ...ctx, currentId: null });
   if (best == null || best.id === active.id) return true;
-  if (margin > 1) return pacePressure(best, ctx.now) <= pacePressure(active, ctx.now) * margin;
+  if (margin > 1) return pacePressure(best, ctx) <= pacePressure(active, ctx) * margin;
   return swapPreference(ctx).every((k) => k(active) === k(best));
 }
 

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(),
@@ -114,7 +116,7 @@ export const ConfigSchema = z
     opencodeBin: z.string().default(""),
     policy: z
       .object({
-        projectionMargin: z.number().min(0).max(100).default(0),
+        projectionMargin: z.number().min(0).max(100).default(3),
         switchModels: z
           .array(z.string())
           .default(["fable"])
@@ -125,9 +127,9 @@ export const ConfigSchema = z
       })
       .prefault({}),
   })
-  .refine((cfg) => cfg.policy.projectionMargin < Math.min(cfg.thresholds.session, cfg.thresholds.weekly), {
+  .refine((cfg) => cfg.policy.projectionMargin < cfg.thresholds.session, {
     path: ["policy", "projectionMargin"],
-    message: "must be strictly below both thresholds (the bars would hit zero and every account would read as exhausted)",
+    message: "must be strictly below the session threshold (the session bar would hit zero and every account would read as exhausted)",
   });
 export type Config = z.infer<typeof ConfigSchema>;