tokenmaxxing 1.58.0 → 1.59.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.
 
 ---
 

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).
 

package/package.json

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