tokenmaxxing 1.52.0 → 1.54.0

package/DESIGN.md

@@ -41,7 +41,7 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
   - `sessions/<sid>.json`, `sample/`, `onboard/`, `setup-tokens.json`, `setup-token/`, `cloud/`, `update.json`, `spawnrate.json`, `tokenmaxxing.log`, the codex `codex-onboard/`, `codex-respawn/`, and `codex-live/`, and the `grok-*` and `opencode-go-*` state of the status-only pools: the full table is in [State directory layout](docs/content/docs/state-directory.mdx).
 - 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 runs the decision with no seat (nothing moves), folds fresh tees into the index, samples up to three accounts whose last `/usage` attempt is oldest (the direct no-spend usage GET for an idle account with a fresh token, the `/usage` probe under the store otherwise), and on a Bun global install checks npm for a newer version once a day, 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 runs the decision with no seat (nothing moves), folds fresh tees into the index, samples up to three accounts whose last sample attempt is oldest (the direct no-spend usage GET first, the `/usage` probe under the store for a near-expiry token or a failed read), and on a Bun global install checks npm for a newer version once a day, 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.json`, and Claude Code's default credential store are untouched; inside `~/.claude` only `settings.json` gets the five entries.
 
@@ -84,7 +84,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 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 `/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.
+- 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, or the `/usage` child under its store when the token is near expiry or the read fails, 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 read or 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.
 
@@ -124,7 +124,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 ---
 
 ## 8. Stack
-TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` and `codex` supervisors, the statusLine and subagent statusLine shims, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry (a longer `/bin/sh` shim under Nix that drops its own directory from PATH; the Stop path runs every turn, and bun's start-up stays low-millisecond). A Bun global install refreshes itself from npm on the check tick, once a day. Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). Shipping is PR-based since 2026-07-18: work reaches main only through a pull request (branch, PR, CI green, a 10-minute review wait, every review handled, merge, teardown), and a release is a PR-landed version bump followed by `gh release create` (details in AGENTS.md "Release and CI"). The supervisor spawns claude with inherited stdio (a relay pipe on stdin for a stream-json session) and restores saved `stty -g` termios between runs - no PTY layer; resize and signals flow through the shared foreground process group.
+TypeScript on Bun, shipped as source: one multi-call entry (`src/main.ts`, `#!/usr/bin/env bun`) serves the CLI, the `claude` and `codex` supervisors, the statusLine and subagent statusLine shims, and the hooks; `init` installs a 2-line shim that `exec`s bun on the installed package's entry (a longer `/bin/sh` shim under Nix that drops its own directory from PATH; the Stop path runs every turn, and bun's start-up stays low-millisecond). A Bun global install refreshes itself from npm on the check tick, once a day. Published to npm as `tokenmaxxing` (source, platform-independent - a compiled binary was tried and shipped one architecture's Mach-O to every platform). Shipping is PR-based since 2026-07-18: work reaches main only through a pull request (branch, PR, CI green, a 10-minute review wait, every review handled, merge, teardown), and a merge that changes a packed file releases itself: CI assigns the next minor version on main, publishes, and tags it (details in AGENTS.md "Release and CI"). The supervisor spawns claude with inherited stdio (a relay pipe on stdin for a stream-json session) and restores saved `stty -g` termios between runs - no PTY layer; resize and signals flow through the shared foreground process group.
 
 ---
 

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 `/usage` attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`: an idle account with a fresh token through the direct no-spend usage read, the rest through `claude -p '/usage'` under the account's store; a move reads the cached figures, which are as fresh as each account's last successful attempt or its sessions' latest push.
+- 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`: the direct no-spend usage read first, and `claude -p '/usage'` under the account's store only for a near-expiry token or a failed read; a move reads the cached figures, which are as fresh as each account's last successful attempt or its sessions' latest push.
 - When no account is usable, the session pauses until the soonest reset if that 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.52.0",
+  "version": "1.54.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

@@ -12,11 +12,11 @@ import { claudePool, paths, sampleDirFor, seatFromEnv, storeDirFor } from "./pat
 import { pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import { seatCounts } from "./presence.ts";
 import type { Observation, Provider, SampleReport } from "./provider.ts";
-import { foldTee, probeAccountUsage, teeObservation } from "./sample.ts";
+import { foldTee, sampleAccountUsage, teeObservation } from "./sample.ts";
 import { clearUsageSnapshot, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, saveAccounts, type Harvest } from "./state.ts";
 import { loadSetupTokens, saveSetupTokens } from "./setuptokens.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
-import { CRED_ENV_OVERRIDES, gatedFamilies, mergeWindows, probeUsage, windowsOf } from "./usage.ts";
+import { CRED_ENV_OVERRIDES, fetchUsageDirect, gatedFamilies, mergeWindows, windowsOf } from "./usage.ts";
 import { CredentialBlobSchema, OAuthAccountSchema, type Account, type Config } from "./types.ts";
 import { c } from "../cli/render.ts";
 
@@ -46,7 +46,7 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
   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, { retries: 0 });
+    const outcome = await sampleAccountUsage(account, { retries: 0 });
     await withLock(claudePool.lockFile, () => {
       const idx = loadAccounts(claudePool);
       const a = idx.accounts.find((x) => x.id === account.id);
@@ -81,7 +81,7 @@ async function samplePool(accounts: Account[]): Promise<Map<string, SampleReport
         reports.set(a.id, { ok: true, source: "statusline" });
         return;
       }
-      const outcome = await probeAccountUsage(a);
+      const outcome = await sampleAccountUsage(a);
       if (!outcome.ok) {
         reports.set(a.id, { ok: false, reason: outcome.reason });
         return;
@@ -217,7 +217,7 @@ async function login(): Promise<Harvest | null> {
     }
 
     console.log(c.dim("sampling usage..."));
-    const sampled = await probeUsage({ configDir: onboardDir });
+    const sampled = await fetchUsageDirect(blob.claudeAiOauth.accessToken);
     if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
     const at = Date.now();
     const id = oauthAccount.accountUuid;

package/src/lib/sample.ts

@@ -14,16 +14,16 @@ import { fetchUsageDirect, mergeWindows, probeUsage, windowsOf } from "./usage.t
 import { UsageWindowsSchema, type Account, type Config } from "./types.ts";
 
 const SampleOutcomeSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), usage: UsageWindowsSchema }),
+  z.object({ ok: z.literal(true), usage: UsageWindowsSchema, via: z.enum(["get", "probe"]) }),
   z.object({ ok: z.literal(false), reason: z.string() }),
 ]);
 export type SampleOutcome = z.infer<typeof SampleOutcomeSchema>;
 
-const PreparedProbeSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), dir: z.string() }),
+const PreparedSampleSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), token: z.string().nullable() }),
   z.object({ ok: z.literal(false), reason: z.string() }),
 ]);
-type PreparedProbe = z.infer<typeof PreparedProbeSchema>;
+type PreparedSample = z.infer<typeof PreparedSampleSchema>;
 
 export function teeObservation(account: Account): Observation | null {
   const stored = account.lastUsageAt != null ? { windows: account.windows, at: account.lastUsageAt } : null;
@@ -43,7 +43,7 @@ export function foldTee(account: Account): boolean {
   return true;
 }
 
-export async function prepareProbe(account: Account, suffix = ""): Promise<PreparedProbe> {
+export async function prepareSample(account: Account): Promise<PreparedSample> {
   let creds;
   try {
     creds = await readStore(account.id);
@@ -57,20 +57,28 @@ export async function prepareProbe(account: Account, suffix = ""): Promise<Prepa
   }
   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: isAccessTokenExpiring(creds) ? null : creds.accessToken };
+}
+
+async function runProbe(account: Account, suffix: string, retries: number | undefined): Promise<SampleOutcome> {
   const dir = sampleDirFor(account.id, suffix);
   mkdirSync(dir, { recursive: true });
   writeFileAtomic(join(dir, ".claude.json"), JSON.stringify({ oauthAccount: account.oauthAccount, hasCompletedOnboarding: true }));
-  return { ok: true, dir };
+  const usage = await probeUsage({ configDir: dir, store: storeDirFor(account.id) }, Date.now(), { retries });
+  return usage ? { ok: true, usage, via: "probe" } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
 }
 
-export async function runProbe(account: Account, dir: string, opts: { retries?: number }): Promise<SampleOutcome> {
-  const usage = await probeUsage({ configDir: dir, store: storeDirFor(account.id) }, Date.now(), { retries: opts.retries });
-  return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+export async function runSample(account: Account, token: string | null, opts: { retries?: number; suffix?: string }): Promise<SampleOutcome> {
+  if (token) {
+    const usage = await fetchUsageDirect(token);
+    if (usage) return { ok: true, usage, via: "get" };
+  }
+  return runProbe(account, opts.suffix ?? "", opts.retries);
 }
 
-export async function probeAccountUsage(account: Account, opts: { retries?: number } = {}): Promise<SampleOutcome> {
-  const prepared = await prepareProbe(account);
-  return prepared.ok ? runProbe(account, prepared.dir, opts) : prepared;
+export async function sampleAccountUsage(account: Account, opts: { retries?: number } = {}): Promise<SampleOutcome> {
+  const prepared = await prepareSample(account);
+  return prepared.ok ? runSample(account, prepared.token, opts) : prepared;
 }
 
 const SAMPLE_BATCH = 3;
@@ -92,10 +100,10 @@ export async function sampleOldest(cfg: Config): Promise<void> {
       if (dirty) saveAccounts(claudePool, idx);
       return [];
     }
-    const batch: { account: Account; dir: string; token: string | null }[] = [];
+    const batch: { account: Account; token: string | null }[] = [];
     for (const target of stale) {
       target.lastProbeAt = now;
-      const prepared = await prepareProbe(target, "-tick");
+      const prepared = await prepareSample(target);
       if (!prepared.ok) {
         target.storeFails = (target.storeFails ?? 0) + 1;
         if (target.storeFails >= STORE_FAILS_REAUTH) target.needsReauth = true;
@@ -103,32 +111,15 @@ export async function sampleOldest(cfg: Config): Promise<void> {
         continue;
       }
       target.storeFails = 0;
-      let token: string | null = null;
-      if (!seats.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 });
+      batch.push({ account: target, token: prepared.token });
     }
     saveAccounts(claudePool, idx);
     return batch;
   });
   await Promise.all(
-    reserved.map(async ({ account, dir, token }) => {
+    reserved.map(async ({ account, 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 });
-      }
+      const outcome = await runSample(account, token, { retries: 0, suffix: "-tick" });
       await withLock(claudePool.lockFile, () => {
         const idx = loadAccounts(claudePool);
         const stored = idx.accounts.find((a) => a.id === account.id);
@@ -139,7 +130,7 @@ export async function sampleOldest(cfg: Config): Promise<void> {
         }
         log(outcome.ok ? "sample.ok" : "sample.failed", {
           account: account.id.slice(0, 8),
-          ...(outcome.ok ? { via } : { reason: outcome.reason.slice(0, 200) }),
+          ...(outcome.ok ? { via: outcome.via } : { reason: outcome.reason.slice(0, 200) }),
         });
       });
     }),

package/src/lib/usage.ts

@@ -359,12 +359,28 @@ export async function probeUsage(target: ProbeTarget, now = Date.now(), opts: {
 const USAGE_URL = env("TOKENMAXXING_OAUTH_USAGE_URL", "https://api.anthropic.com/api/oauth/usage");
 const USAGE_DEADLINE_MS = 10_000;
 
-const UsageWindowResponseSchema = z.object({ utilization: z.number(), resets_at: z.number().nullable().optional() });
-const UsageResponseSchema = z.object({
-  rate_limits: z
-    .object({ five_hour: UsageWindowResponseSchema.nullish(), seven_day: UsageWindowResponseSchema.nullish() })
-    .nullish(),
+const UsageLimitSchema = z.looseObject({ utilization: z.number(), resets_at: z.unknown() });
+const UsageScopedLimitSchema = z.looseObject({
+  kind: z.string(),
+  percent: z.number(),
+  resets_at: z.unknown(),
+  scope: z.looseObject({ model: z.looseObject({ display_name: z.string() }) }),
 });
+const UsageResponseSchema = z.looseObject({
+  five_hour: UsageLimitSchema.nullish(),
+  seven_day: UsageLimitSchema.nullish(),
+  limits: z.array(z.unknown()).nullish(),
+});
+
+function scopedRows(limits: unknown[]): Record<string, UsageWindow> {
+  const perModel: Record<string, UsageWindow> = {};
+  for (const raw of limits) {
+    const row = UsageScopedLimitSchema.safeParse(raw);
+    if (!row.success || row.data.kind !== "weekly_scoped") continue;
+    perModel[row.data.scope.model.display_name] = { usedPercentage: row.data.percent, resetsAt: normalizeResetsAt(row.data.resets_at) };
+  }
+  return perModel;
+}
 
 export async function fetchUsageDirect(accessToken: string): Promise<UsageWindows | null> {
   let res: Response;
@@ -382,15 +398,10 @@ export async function fetchUsageDirect(accessToken: string): Promise<UsageWindow
     return null;
   }
   const parsed = UsageResponseSchema.safeParse(JsonTextSchema.safeParse(await res.text()).data);
-  const five = parsed.success ? parsed.data.rate_limits?.five_hour : null;
-  const seven = parsed.success ? parsed.data.rate_limits?.seven_day : null;
-  if (!five || !seven) {
+  if (!parsed.success || !parsed.data.five_hour || !parsed.data.seven_day) {
     log("usage.get_incomplete", { ok: parsed.success });
     return null;
   }
-  const win = (w: z.infer<typeof UsageWindowResponseSchema>): UsageWindow => ({
-    usedPercentage: w.utilization * 100,
-    resetsAt: w.resets_at != null ? w.resets_at * 1000 : null,
-  });
-  return { fiveHour: win(five), sevenDay: win(seven), perModel: {} };
+  const win = (w: z.infer<typeof UsageLimitSchema>): UsageWindow => ({ usedPercentage: w.utilization, resetsAt: normalizeResetsAt(w.resets_at) });
+  return { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []) };
 }