tokenmaxxing 1.58.0 → 1.60.0

package/DESIGN.md

@@ -90,7 +90,7 @@ The [switching policy](docs/content/docs/switching.mdx) is one rule: under both
 
 The [profile](docs/content/docs/switching-profile.mdx) records observed cache rewrites across swaps and does not infer subscription quota savings.
 
-**Model-aware trigger.** Claude subscriptions also enforce **per-model weekly caps** - currently only for Sonnet and Fable (there is no Opus-only quota), and Fable's tighter limit binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the active model is in `policy.switchModels`, or the seat's tee is older than the TTL, we read it from the `limits[]` rows of the direct no-spend usage read for the seat (free, 0 tokens, one attempt with backoff, with the `/usage` probe under the seat's store refreshing the token when the read needs it) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session moves on the Fable cap; a Sonnet session rides the aggregate. Candidate screening applies the same per-model gate: a burnt Fable cap screens an account out of a move, and a launch, whose model is unknown, gates every configured family.
+**Model-aware trigger.** Claude subscriptions also enforce **per-model weekly caps** - currently only for Sonnet and Fable (there is no Opus-only quota), and Fable's tighter limit binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the session's model is in `policy.switchModels`, or the seat's tee is older than the TTL, we read it from the `limits[]` rows of the direct no-spend usage read for the seat (free, 0 tokens, one attempt with backoff, with the `/usage` probe under the seat's store refreshing the token when the read needs it) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session moves on the Fable cap; a Sonnet session rides the aggregate. Candidate screening applies the same per-model gate: a burnt Fable cap screens an account out of a move. A session's model is the `--model` value it was launched with: the supervisor reads it from the launch flags, uses it for launch placement and the seat watch, and hands it to the session's hooks in `TOKENMAXXING_MODEL`, which the hooks read ahead of the per-account tee. With the default `policy.switchModels`, a session launched as Opus, Sonnet, or Haiku gates no per-model cap, so it runs on an account whose Fable cap is spent while the session and weekly windows have headroom. A launch without `--model`, or with a value that names no model family (`best`, `opusplan`), is unknown: launch placement and the seat watch gate every configured family for it, and its hooks fall back to the model in the account's tee. A move off a walled seat, or one that follows a subagent's five-hour or weekly refusal, screens candidates on every configured family whatever the launch model.
 
 ---
 
@@ -115,7 +115,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 
 **Removed (1.37.0, issue #79):** the shared live credential and everything that served it: the swap-time harvest, park, and install, tokenmaxxing's own OAuth refresh grant and its interlock with Claude Code's refresh lock, the `~/.claude.json` `oauthAccount` rewrite, the 45-second post-swap cooldown, the pool-wide depleted-wait record, the parked-credential slots (`creds/`, `tokenmaxxing-cred-*`), the ambient `CLAUDE_CONFIG_DIR` refusal, and manual `switch` for the Claude pool.
 
-**Shipped since (0.13.0):** Codex as a second pool with its own state (`codex-accounts.json`, per-account `codex-stores/`, own flock). Since 1.35.0 the engine is one: a generic account record (`id`, `label`, `email`, `tier`, `windows`), one picker, one decision, and one set of account commands run against a `Provider` (`src/lib/provider.ts`); `src/lib/claude.ts` and `src/lib/codex.ts` hold only what differs per product (credential store, identity, usage source, presence, login and install flows), and the provider's `seats` capability (`shared` for Claude, `live` for Codex) is how the engine knows whether present accounts stay candidates and whether a move needs the caller's respawn. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), one store per pooled account with `CODEX_HOME` set per session (everything but `auth.json` symlinked to the shared home, so resume works across stores), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (persisted into the account's own store the instant it returns, never refreshed for an account running in another session), and the codex Stop hook drives the auto-switch through a codex supervisor shim that respawns `codex resume <session-id>` under the target's store (hooks must be trusted once via `/hooks`). Since 1.44.0 two status-only pools, grok and opencode-go, share the engine's account commands and state layout with `statusOnly: true` and no supervisor, hooks, or usage source ([Status-only pools](docs/content/docs/status-only-pools.mdx)).
+**Shipped since (0.13.0):** Codex as a second pool with its own state (`codex-accounts.json`, per-account `codex-stores/`, own flock). Since 1.35.0 the engine is one: a generic account record (`id`, `label`, `email`, `tier`, `windows`), one picker, one decision, and one set of account commands run against a `Provider` (`src/lib/provider.ts`); `src/lib/claude.ts` and `src/lib/codex.ts` hold only what differs per product (credential store, identity, usage source, presence, login and install flows), and the provider's `seats` capability (`shared` for Claude, `live` for Codex) is how the engine knows whether present accounts stay candidates and whether a move needs the caller's respawn. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), one store per pooled account with `CODEX_HOME` set per session (everything but `auth.json` symlinked to the shared home, so resume works across stores), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (persisted into the account's own store the instant it returns, never refreshed for an account running in another session), and the codex Stop hook drives the auto-switch through a codex supervisor shim that respawns `codex resume <session-id>` under the target's store (hooks must be trusted once via `/hooks`). Since 1.44.0 two status-only pools, grok and opencode-go, share the engine's account commands and state layout with `statusOnly: true` and no supervisor or hooks ([Status-only pools](docs/content/docs/status-only-pools.mdx)). grok `status` reads the weekly subscription credit window from the credits billing GET; opencode-go has no usage source.
 
 **Shipped since (1.29.0):** a Cursor Cloud relay. A cloud VM has no keychain, no pool state, and no supervisor, so the path uses what it does have (environment variables, a shell, repo files) and a different credential primitive, one-year inference-only setup tokens, minted once per pooled account by `tokenmaxxing setup-token` on the owner's machine and carried to the VM as one user-scoped Runtime Secret (`TOKENMAXXING_TOKENS`). `tokenmaxxing cursor init` writes `.cursor/environment.json` and a `claude` project subagent (`.cursor/agents/claude.md`) that forwards each task to `tokenmaxxing cloud run`, which spawns `claude -p --dangerously-skip-permissions --output-format json` under `CLAUDE_CODE_OAUTH_TOKEN` and pins the thread to that token (the API caches by exact prefix, so a rotation busts one thread, not all). A setup token carries no usage signal, so rotation is reactive. A run whose transcript gained a non-transient rate-limit row during that run (the structured row the StopFailure hook reads) walls the label until the reset the row names (five hours without one) and resumes the same session on the next token; the result's `api_error_status` alone never walls, so a transient 429 or an older row from a previous token does not cascade across the pool. The local switching engine never reads a setup token; `/usage` prints no percentages under one. Details in [Cursor Cloud](docs/content/docs/cursor-cloud.mdx).
 

package/README.md

@@ -84,7 +84,7 @@ claude                  # use claude as always; each session gets its own accoun
 Each session runs on its own seat. One rule: while the seat is under its bars, nothing happens; once it is at or over a bar, the session moves to the usable account that ranks first. The session bar is `thresholds.session` (90) minus `policy.projectionMargin` (3), so **87%** of the 5-hour window by default, and the weekly bar is **98%**. The bars also screen candidates on any of:
 
 - **Session** (5-hour) or **week (all models)** - the aggregate windows, fed free/push-based by the statusLine into one tee per account.
-- **Per-model weekly cap** - the most capable model (Fable) has its own tighter weekly limit that binds *before* the aggregate (per-model caps currently exist only for Sonnet and Fable, and Sonnet's is generous). tokenmaxxing reads it from the direct no-spend usage read for the seat (free, 0 tokens, one attempt per interval) whenever the seat's tee is older than `policy.usagePollTtlMs` or the active model is one of `policy.switchModels`, backing off after a failed sample, so a Fable session moves on the Fable cap while a Sonnet session rides the aggregate.
+- **Per-model weekly cap** - the most capable model (Fable) has its own tighter weekly limit that binds *before* the aggregate (per-model caps currently exist only for Sonnet and Fable, and Sonnet's is generous). tokenmaxxing reads it from the direct no-spend usage read for the seat (free, 0 tokens, one attempt per interval) whenever the seat's tee is older than `policy.usagePollTtlMs` or the session's model is one of `policy.switchModels`, backing off after a failed sample, so a Fable session moves on the Fable cap while a Sonnet session rides the aggregate. A session launched with `--model` on another family (`claude --model opus`) ignores the Fable cap from launch on: it is placed on, and moves to, an account whose Fable cap is spent as long as that account's session and weekly windows have headroom. The exception is a move off an account the server already refused (an enforced-limit wall), which screens every configured family.
 
 The bars' headroom is deliberate: it's the budget to reach a clean turn boundary before the account's real limit. The session bar sits lower (90, minus the margin) because a 5-hour reset is cheap to sit out; weekly quota is use-it-or-lose-it, so it drains closer to the limit (98).
 
@@ -142,7 +142,7 @@ A Cursor Cloud Agent can hand substantial work to Claude Code running on your ow
 - **One shared identity file.** `~/.claude.json` holds one `oauthAccount` that Claude Code rewrites after whichever session refreshed last, so `/status` can show another session's email; the statusline's `◆` marks the account a session actually uses.
 - **Keychain (macOS).** The first keychain access for a new store happens inside the interactive `init`, `add`, or `auth` run, where a prompt can be answered, not inside a headless hook.
 - **Plaintext credentials (Linux).** Claude Code itself stores Linux credentials as a 0600 plaintext file; a store follows the same model.
-- **Status-only pools carry no usage.** grok and opencode-go accounts render with no bars and never move.
+- **Status-only pools do not switch.** grok `status` shows the weekly subscription credit window; opencode-go accounts still render with no bars. Neither pool moves.
 
 ## How it's built
 

package/package.json

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

@@ -88,9 +88,14 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
   if (!cached && idx.accounts.length > 0) {
     await withLock(p.pool.lockFile, async () => {
       idx = loadAccounts(p.pool);
-      console.error(c.dim(`sampling ${p.name} usage...`));
-      liveId = p.liveId();
-      reports = await p.samplePool(idx.accounts, liveId, now);
+      const notice = process.stderr.isTTY;
+      if (notice) process.stderr.write(c.dim(`sampling ${p.name} usage...`));
+      try {
+        liveId = p.liveId();
+        reports = await p.samplePool(idx.accounts, liveId, now);
+      } finally {
+        if (notice) process.stderr.write("\r\x1b[2K");
+      }
       saveAccounts(p.pool, idx);
     });
   }

package/src/entries/codexstophook.ts

@@ -21,7 +21,7 @@ async function compactBeforeMove(input: { sessionId: string | null; now: number
   const liveId = codex.liveId();
   const live = liveId == null ? undefined : loadAccounts(codex.pool).accounts.find((a) => a.id === liveId);
   if (!live || live.needsReauth === true || (live.enforcedUntil != null && live.enforcedUntil > now)) return;
-  const observed = await codex.observeLive(live, loadConfig(), now, { probe: true });
+  const observed = await codex.observeLive(live, loadConfig(), now, { probe: true, perModel: false });
   if (!observed || !isExhausted({ ...live, windows: observed.windows }, codexPickCtx(now, live.id))) return;
   const env: Record<string, string | undefined> = { ...process.env, TOKENMAXXING_PROBE: "1", [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) };
   delete env[CODEX_SUPERVISOR_ID_ENV];

package/src/entries/supervisor.ts

@@ -17,7 +17,8 @@ import { exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, r
 import { saveTermios } from "../lib/tty.ts";
 import { loadSessionFlags, pruneStaleSessions, saveSessionFlags, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
-import { RespawnMarkerSchema, type Account } from "../lib/types.ts";
+import { gatedFamilies, modelFromFlag } from "../lib/usage.ts";
+import { RespawnMarkerSchema, type Account, type Config, type ModelInfo } from "../lib/types.ts";
 import { errorMessage, log } from "../lib/log.ts";
 
 const NONINTERACTIVE_SUBCMDS = new Set([
@@ -53,6 +54,7 @@ type Analysis = {
   continueLatest: boolean;
   streamInput: boolean;
   streamOutput: boolean;
+  model: string | null;
 };
 
 export function analyzeArgs(argv: string[]): Analysis {
@@ -61,6 +63,7 @@ export function analyzeArgs(argv: string[]): Analysis {
   let continueLatest = false;
   let streamInput = false;
   let streamOutput = false;
+  let model: string | null = null;
   let printMode = false;
   let invalidSessionArg = false;
   let pickerResume = false;
@@ -98,6 +101,8 @@ export function analyzeArgs(argv: string[]): Analysis {
     else if (a.startsWith("--input-format=")) streamInput = a.slice("--input-format=".length) === "stream-json";
     else if (a === "--output-format") streamOutput = argv[++i] === "stream-json";
     else if (a.startsWith("--output-format=")) streamOutput = a.slice("--output-format=".length) === "stream-json";
+    else if (a === "--model") model = argv[++i] ?? null;
+    else if (a.startsWith("--model=")) model = a.slice("--model=".length);
     else if (VALUE_TAKING_ROOT_FLAGS.has(a)) i++;
     else if (VARIADIC_ROOT_FLAGS.has(a)) {
       while (i + 1 < argv.length && !argv[i + 1]!.startsWith("-")) i++;
@@ -113,7 +118,7 @@ export function analyzeArgs(argv: string[]): Analysis {
   const isSubcmd = firstPositional !== null && NONINTERACTIVE_SUBCMDS.has(firstPositional);
   const forkResume = forkSession && (resumeId !== null || continueLatest);
   const manage = !printMode && !isSubcmd && !invalidSessionArg && !pickerResume && !forkResume && !process.env.TOKENMAXXING_PROBE;
-  return { manage, sessionId, resumeId, continueLatest, streamInput, streamOutput };
+  return { manage, sessionId, resumeId, continueLatest, streamInput, streamOutput, model };
 }
 
 export function stripSessionFlags(argv: string[]): string[] {
@@ -201,22 +206,23 @@ function consumableMarker(marker: string, gate: MarkerGate): z.infer<typeof Resp
 const SEAT_POLL_MS = 10_000;
 const SEAT_RETRY_MS = 60_000;
 
-function seatBlockedUntil(seatId: string, now: number): number | null {
+function seatBlockedUntil(seatId: string, now: number, families: string[], cfg: Config): number | null {
   const account = loadAccounts(claudePool).accounts.find((a) => a.id === seatId);
   if (!account) return null;
-  const cfg = loadConfig();
   const observed = teeObservation(account);
   const current = observed ? { ...account, windows: observed.windows } : account;
-  const until = usableAt(current, { now, thresholds: thresholdBars(cfg), currentId: seatId, families: cfg.policy.switchModels, seats: null });
+  const until = usableAt(current, { now, thresholds: thresholdBars(cfg), currentId: seatId, families, seats: null });
   return until > now ? until : null;
 }
 
-async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate): Promise<boolean> {
+async function moveExhaustedSeat(seat: Account, sid: string, gate: MarkerGate, model: ModelInfo | null): Promise<boolean> {
   try {
     const now = Date.now();
-    const until = seatBlockedUntil(seat.id, now);
+    const cfg = loadConfig();
+    const families = gatedFamilies(model, cfg.policy.switchModels);
+    const until = seatBlockedUntil(seat.id, now, families, cfg);
     if (until == null || until <= gate.overriddenUntil) return false;
-    const decision = await evaluateAndMaybeSwap(claude, now, true, null, seat.id);
+    const decision = await evaluateAndMaybeSwap(claude, now, true, null, seat.id, families);
     log("supervisor.seat_exhausted", { seat: seat.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
     if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       writeRespawnMarker({ session: { sid, launchedAt: gate.launchedAt }, sessionId: sid, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: true });
@@ -342,6 +348,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     const passthroughEnv: Record<string, string | undefined> = { ...childEnv };
     delete passthroughEnv.TOKENMAXXING_SUPERVISED;
     delete passthroughEnv.TOKENMAXXING_SESSION_ID;
+    delete passthroughEnv.TOKENMAXXING_MODEL;
     return runPassthrough({ real, argv, env: passthroughEnv, onSpawn: (p) => { child = p; } });
   }
 
@@ -380,6 +387,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   const effective = analyzeArgs(base);
   const relay = effective.streamInput ? new StdinRelay() : null;
   const stream = effective.streamOutput;
+  const model = modelFromFlag(effective.model);
   let noticeSid = sid;
   const say: Say = (terminal, text) => {
     if (stream) process.stdout.write(systemLine(noticeSid, text));
@@ -394,7 +402,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
 
     const gate: MarkerGate = { launchedAt: Date.now(), overriddenUntil };
     const { child: proc, seat } = await withLock(claudePool.lockFile, async () => {
-      const picked = (wanted == null ? null : (loadAccounts(claudePool).accounts.find((a) => a.id === wanted) ?? null)) ?? pickSeat(gate.launchedAt);
+      const picked = (wanted == null ? null : (loadAccounts(claudePool).accounts.find((a) => a.id === wanted) ?? null)) ?? pickSeat(gate.launchedAt, model);
       log("supervisor.launch", { sid, respawns, seat: picked?.id.slice(0, 8) ?? null, args: launchArgs.join(" "), injected: firstLine !== null });
       const spawned = Bun.spawn([real, ...launchArgs], {
         stdin: relay === null ? "inherit" : "pipe",
@@ -405,6 +413,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
           TOKENMAXXING_SUPERVISED: "1",
           TOKENMAXXING_SESSION_ID: sid,
           TOKENMAXXING_LAUNCHED_AT: String(gate.launchedAt),
+          TOKENMAXXING_MODEL: effective.model ?? "",
           ...(picked ? { CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : {}),
         },
       });
@@ -431,7 +440,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       tick: async () => {
         if (existsSync(marker) && consumableMarker(marker, gate) != null) return true;
         if (seat && !terminating && Date.now() >= seatCheckAt) {
-          const decided = await moveExhaustedSeat(seat, sid, gate);
+          const decided = await moveExhaustedSeat(seat, sid, gate, model);
           seatCheckAt = Date.now() + (decided ? SEAT_RETRY_MS : SEAT_POLL_MS);
         }
         return false;
@@ -459,6 +468,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         delete compactEnv.TOKENMAXXING_SUPERVISED;
         delete compactEnv.TOKENMAXXING_SESSION_ID;
         delete compactEnv.TOKENMAXXING_LAUNCHED_AT;
+        delete compactEnv.TOKENMAXXING_MODEL;
         const outcome = await compactClaudeSession({ real, sid: m.sessionId, env: compactEnv });
         log("supervisor.compact", { sid: m.sessionId.slice(0, 8), seat: seat.id.slice(0, 8), ok: outcome.ok, reason: outcome.ok ? undefined : outcome.reason });
         if (!outcome.ok) say(`\x1b[33m   compaction did not land (${outcome.reason}) - resuming with the full context\x1b[0m\n`, `tokenmaxxing: compaction did not land; resuming with the full context. (${outcome.reason})`);

package/src/lib/claude.ts

@@ -8,7 +8,7 @@ import { ensurePathInRc, installSupervisor, managedShellRcSkipLines, shellRcPath
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isDeadCredential, InvalidGrantError } from "./oauth.ts";
-import { claudePool, paths, sampleDirFor, seatFromEnv, storeDirFor } from "./paths.ts";
+import { claudePool, env, paths, sampleDirFor, seatFromEnv, storeDirFor } from "./paths.ts";
 import { pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import { seatCounts } from "./presence.ts";
 import type { Observation, Provider, SampleReport } from "./provider.ts";
@@ -16,8 +16,8 @@ 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 { fetchUsageDirect, gatedFamilies, mergeWindows, scrubCredentialEnv, windowsOf } from "./usage.ts";
-import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config } from "./types.ts";
+import { fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredentialEnv, windowsOf } from "./usage.ts";
+import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config, type ModelInfo } from "./types.ts";
 import { c } from "../cli/render.ts";
 
 class StoreUnusableError extends Error {
@@ -37,14 +37,13 @@ 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 }): Promise<Observation | null> {
+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 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)) {
+  if (opts.probe && !probeAttempted && (!fresh || opts.perModel)) {
     const startedAt = Date.now();
     const outcome = await sampleAccountUsage(account);
     await withLock(claudePool.lockFile, () => {
@@ -125,13 +124,13 @@ async function storeUsable(a: Account): Promise<boolean> {
   }
 }
 
-export function pickSeat(now: number): Account | null {
+export function pickSeat(now: number, model: ModelInfo | null): Account | null {
   const cfg = loadConfig();
   const idx = loadAccounts(claudePool);
   let dirty = false;
   for (const a of idx.accounts) dirty = foldTee(a) || dirty;
   if (dirty) saveAccounts(claudePool, idx);
-  const ctx: PickCtx = { now, thresholds: thresholdBars(cfg), currentId: null, families: cfg.policy.switchModels, seats: presence() };
+  const ctx: PickCtx = { now, thresholds: thresholdBars(cfg), currentId: null, families: gatedFamilies(model, cfg.policy.switchModels), seats: presence() };
   return pickBest(idx.accounts, ctx) ?? pickEarliestReset(idx.accounts, ctx)?.account ?? null;
 }
 
@@ -286,7 +285,8 @@ export const claude: Provider = {
   presence,
   gatedFamilies: (cfg) => {
     const seat = liveId();
-    return gatedFamilies(seat == null ? null : (loadUsageSnapshot(seat)?.state.model ?? null), cfg.policy.switchModels);
+    const model = modelFromFlag(env("TOKENMAXXING_MODEL", "")) ?? (seat == null ? null : (loadUsageSnapshot(seat)?.state.model ?? null));
+    return gatedFamilies(model, cfg.policy.switchModels);
   },
   observeLive,
   samplePool,

package/src/lib/decide.ts

@@ -36,16 +36,17 @@ function enforcedWall(limit: EnforcedLimit, account: Account, now: number): numb
   return limit.resetsAt ?? cachedReset ?? now + (limit.kind === "session" ? FIVE_HOURS_MS : WEEK_MS);
 }
 
-export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, seatId: string | null = p.liveId()): Promise<SwapDecision> {
+export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, seatId: string | null = p.liveId(), sessionFamilies?: string[]): Promise<SwapDecision> {
   const activeId = seatId;
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
   const stored0 = loadAccounts(p.pool).accounts.find((a) => a.id === activeId);
   const walled0 = stored0?.enforcedUntil != null && stored0.enforcedUntil > now;
-  const observed = stored0 ? await p.observeLive(stored0, cfg, now, { probe: enforced == null && !walled0 }) : null;
+  const gated = sessionFamilies ?? p.gatedFamilies(cfg);
+  const observed = stored0 ? await p.observeLive(stored0, cfg, now, { probe: enforced == null && !walled0, perModel: gated == null || gated.length > 0 }) : null;
   const stored = loadAccounts(p.pool).accounts.find((a) => a.id === activeId);
 
-  if (!enforced && !isOver(stored, observed, { now, thresholds: bars, currentId: activeId, families: p.gatedFamilies(cfg), seats: null })) {
+  if (!enforced && !isOver(stored, observed, { now, thresholds: bars, currentId: activeId, families: gated, seats: null })) {
     return { swapped: false, account: null, reason: "under-threshold-or-stale" };
   }
 
@@ -70,7 +71,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
 
     let obs2: Observation | null = null;
     for (const a of idx.accounts) {
-      const obs = await p.observeLive(a, cfg, now, { probe: false });
+      const obs = await p.observeLive(a, cfg, now, { probe: false, perModel: false });
       if (a === active) obs2 = obs;
       if (obs && (a.lastUsageAt == null || obs.at > a.lastUsageAt)) {
         a.windows = p.mergeWindows(obs.windows, a.windows);
@@ -79,7 +80,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     }
     saveAccounts(p.pool, idx);
 
-    const families = p.gatedFamilies(cfg);
+    const families = sessionFamilies ?? p.gatedFamilies(cfg);
     const walled = active?.enforcedUntil != null && active.enforcedUntil > now;
     const blindScreen = (enforced != null && (prior || enforced.blind)) || (walled && !enforced2);
     const screened = blindScreen && families != null ? cfg.policy.switchModels : families;

package/src/lib/grok.ts

@@ -2,10 +2,13 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
+import { fetchGrokUsage, GrokUsageReadError } from "./grokusage.ts";
+import { errorMessage } from "./log.ts";
 import { grokAuthJsonFor, grokPaths, grokPool, grokSeatFromEnv, grokStoreDirFor } from "./paths.ts";
-import type { Provider } from "./provider.ts";
+import type { Provider, SampleReport } from "./provider.ts";
 import { loadAccounts, type Harvest } from "./state.ts";
 import { statusOnlyProvider, type AuthEntry } from "./statusonly.ts";
+import type { Account } from "./types.ts";
 import { c } from "../cli/render.ts";
 
 const GrokAuthEntrySchema = z.looseObject({
@@ -13,11 +16,14 @@ const GrokAuthEntrySchema = z.looseObject({
   principal_id: z.string().optional(),
   email: z.string().nullish(),
   first_name: z.string().nullish(),
+  key: z.string().optional(),
   refresh_token: z.string().optional(),
   expires_at: z.string().nullish(),
 });
 type GrokAuthEntry = z.infer<typeof GrokAuthEntrySchema>;
 
+type GrokCred = { id: string; token: string; expiresAt: number | null };
+
 function harvestOf(id: string, key: string, entry: GrokAuthEntry): Harvest {
   return {
     id,
@@ -31,7 +37,7 @@ function harvestOf(id: string, key: string, entry: GrokAuthEntry): Harvest {
   };
 }
 
-function readAuth(path: string): AuthEntry[] {
+function readMap(path: string): [string, GrokAuthEntry][] {
   let raw: unknown;
   try {
     raw = JSON.parse(readFileSync(path, "utf8"));
@@ -40,18 +46,87 @@ function readAuth(path: string): AuthEntry[] {
   }
   const map = z.record(z.string(), z.unknown()).safeParse(raw);
   if (!map.success) return [];
-  const out: AuthEntry[] = [];
+  const out: [string, GrokAuthEntry][] = [];
   for (const [key, value] of Object.entries(map.data)) {
     const parsed = GrokAuthEntrySchema.safeParse(value);
     if (!parsed.success) continue;
-    const entry = parsed.data;
+    out.push([key, parsed.data]);
+  }
+  return out;
+}
+
+function readAuth(path: string): AuthEntry[] {
+  const out: AuthEntry[] = [];
+  for (const [key, entry] of readMap(path)) {
     const id = entry.user_id ?? entry.principal_id ?? key;
     out.push({ id, usable: (entry.refresh_token ?? "") !== "", harvest: id === "" ? null : harvestOf(id, key, entry) });
   }
   return out;
 }
 
-export const grok: Provider = statusOnlyProvider({
+function credsIn(path: string): GrokCred[] {
+  const out: GrokCred[] = [];
+  for (const [key, entry] of readMap(path)) {
+    const id = entry.user_id ?? entry.principal_id ?? key;
+    const token = entry.key ?? "";
+    if (id === "" || token === "") continue;
+    const expiresAt = entry.expires_at != null ? Date.parse(entry.expires_at) : null;
+    out.push({ id, token, expiresAt: expiresAt != null && Number.isFinite(expiresAt) ? expiresAt : null });
+  }
+  return out;
+}
+
+function liveCred(accountId: string): GrokCred | null {
+  return credsIn(join(grokPaths.home, "auth.json")).find((c) => c.id === accountId) ?? null;
+}
+
+function bearerFor(accountId: string, now: number): { token: string; from: "store" | "live" } | null {
+  const store = credsIn(grokAuthJsonFor(accountId)).find((c) => c.id === accountId) ?? null;
+  const live = liveCred(accountId);
+  if (store != null && (store.expiresAt == null || store.expiresAt > now + 60_000)) return { token: store.token, from: "store" };
+  if (live != null) return { token: live.token, from: "live" };
+  if (store != null) return { token: store.token, from: "store" };
+  return null;
+}
+
+async function readGrokUsage(account: Account, now: number): Promise<{ ok: true; at: number } | { ok: false; reason: string }> {
+  const first = bearerFor(account.id, now);
+  if (first == null) return { ok: false, reason: "no usable credential in this account's store - run `tokenmaxxing auth --grok`" };
+  try {
+    const usage = await fetchGrokUsage({ token: first.token, at: now });
+    account.windows = usage.windows;
+    account.lastUsageAt = usage.at;
+    return { ok: true, at: usage.at };
+  } catch (e) {
+    if (e instanceof GrokUsageReadError && e.status === 401 && first.from === "store") {
+      const live = liveCred(account.id);
+      if (live != null && live.token !== first.token) {
+        try {
+          const usage = await fetchGrokUsage({ token: live.token, at: now });
+          account.windows = usage.windows;
+          account.lastUsageAt = usage.at;
+          return { ok: true, at: usage.at };
+        } catch (retry) {
+          return { ok: false, reason: retry instanceof GrokUsageReadError ? retry.message : errorMessage(retry) };
+        }
+      }
+    }
+    return { ok: false, reason: e instanceof GrokUsageReadError ? e.message : errorMessage(e) };
+  }
+}
+
+async function samplePool(accounts: Account[], _liveId: string | null, now: number): Promise<Map<string, SampleReport>> {
+  const reports = new Map<string, SampleReport>();
+  await Promise.all(
+    accounts.map(async (account) => {
+      const outcome = await readGrokUsage(account, now);
+      reports.set(account.id, outcome.ok ? { ok: true, source: "probe" } : { ok: false, reason: outcome.reason });
+    }),
+  );
+  return reports;
+}
+
+const base = statusOnlyProvider({
   name: "grok",
   flag: " --grok",
   pool: grokPool,
@@ -72,3 +147,8 @@ export const grok: Provider = statusOnlyProvider({
   installNotice: "grok pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled grok accounts.",
   loginStep: () => `Sign in in the browser session that opens (or run ${c.bold("grok login --device-auth")} on headless hosts first).`,
 });
+
+export const grok: Provider = {
+  ...base,
+  samplePool,
+};

package/src/lib/grokusage.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { http, safeErrorDetail } from "./http.ts";
+import { errorMessage } from "./log.ts";
+import { env } from "./paths.ts";
+import { JsonTextSchema, type Window } from "./types.ts";
+
+export class GrokUsageReadError extends Error {
+  status: number | null;
+  constructor(detail: string, status: number | null = null) {
+    super(`grok usage read failed: ${detail}`);
+    this.name = "GrokUsageReadError";
+    this.status = status;
+  }
+}
+
+const InstantSchema = z.iso.datetime({ offset: true });
+
+const CreditsPeriodSchema = z.looseObject({
+  start: InstantSchema,
+  end: InstantSchema,
+});
+
+const CreditsConfigSchema = z.looseObject({
+  currentPeriod: CreditsPeriodSchema,
+  creditUsagePercent: z.number(),
+});
+
+const CreditsBillingSchema = z.looseObject({
+  config: CreditsConfigSchema,
+});
+
+export type GrokUsage = { windows: Window[]; at: number };
+
+function usageUrl(): string {
+  return env("TOKENMAXXING_GROK_USAGE_URL", "https://cli-chat-proxy.grok.com/v1/billing?format=credits");
+}
+
+export async function fetchGrokUsage(input: { token: string; at: number }): Promise<GrokUsage> {
+  const { token, at } = input;
+  let res: Response;
+  try {
+    res = await http.get(usageUrl(), {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        "User-Agent": "grok",
+      },
+    });
+  } catch (e) {
+    throw new GrokUsageReadError(`endpoint unreachable: ${errorMessage(e)}`);
+  }
+  const text = await res.text();
+  if (!res.ok) {
+    throw new GrokUsageReadError(`HTTP ${res.status}: ${safeErrorDetail({ text })}`, res.status);
+  }
+  const parsed = CreditsBillingSchema.safeParse(JsonTextSchema.safeParse(text).data);
+  if (!parsed.success) {
+    throw new GrokUsageReadError("endpoint returned an unexpected body shape (withheld)");
+  }
+  const period = parsed.data.config.currentPeriod;
+  const start = Date.parse(period.start);
+  const end = Date.parse(period.end);
+  return {
+    at,
+    windows: [
+      {
+        name: null,
+        usedPercentage: parsed.data.config.creditUsagePercent,
+        resetsAt: Number.isFinite(end) ? end : null,
+        windowSeconds: Number.isFinite(start) && Number.isFinite(end) && end > start ? Math.round((end - start) / 1000) : null,
+        sampledAt: at,
+      },
+    ],
+  };
+}

package/src/lib/provider.ts

@@ -18,7 +18,7 @@ export type Provider = {
   liveId(): string | null;
   presence(): Map<string, number>;
   gatedFamilies(cfg: Config): string[] | null;
-  observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null>;
+  observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean; perModel: boolean }): Promise<Observation | null>;
   samplePool(accounts: Account[], liveId: string | null, now: number): Promise<Map<string, SampleReport>>;
   mergeWindows(next: Window[], prev: Window[]): Window[];
   swap(target: Account): Promise<void>;

package/src/lib/usage.ts

@@ -44,6 +44,14 @@ export function gatedFamilies(model: ModelInfo | null, families: string[]): stri
   return family ? [family] : [];
 }
 
+const MODEL_FAMILIES = ["sonnet", "opus", "haiku", "fable"];
+
+export function modelFromFlag(value: string | null): ModelInfo | null {
+  const name = value?.split("[")[0]?.trim() ?? "";
+  const tokens = familyTokens(name);
+  return MODEL_FAMILIES.some((f) => tokens.includes(f)) ? { id: name, display: name } : null;
+}
+
 const TranscriptBlockSchema = z.looseObject({ type: z.string().optional(), text: z.string().optional() });
 export const TranscriptRowSchema = z.looseObject({
   type: z.string().optional(),