tokenmaxxing 1.114.0 → 1.116.0

package/DESIGN.md

@@ -66,7 +66,7 @@ The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed
 
 ### 3.4 Placement (supervisor, under the pool lock)
 1. Fold every account's tee into the index.
-2. Rank the usable accounts (§5) with the live session counts from `live/`, or the soonest-recovering account when none is usable; with no pooled account or every account needing re-auth, launch without a store (still supervised, on whatever login the environment names). Print mode, every subcommand, the bare resume picker, an invalid `--session-id`, and `--fork-session` with a resume are passed through unmanaged.
+2. Rank the usable accounts (§5) with the live session counts from `live/`, or the soonest-recovering account when none is usable; with no pooled account or every account needing re-auth, launch without a store (still supervised, on whatever login the environment names). Print mode, every subcommand, the bare resume picker, an invalid `--session-id`, `--fork-session` with a resume, and `--no-session-persistence` (no transcript, so a move could not resume the run) are passed through unmanaged.
 3. Spawn claude with the store env set, then write `live/<sid>` with the child's pid and start time. The lock covers the pick and the presence write, so concurrent launches see each other.
 
 ### 3.5 Multiple concurrent sessions

package/README.md

@@ -112,7 +112,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 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; `thresholds.accounts` gives one account its own pair, keyed by label (`{"shared-seat": {"session": 75, "weekly": 75}}`), and `policy.accountReleaseMs` (30 minutes for the session window, 5 hours for a weekly window by default) lifts each of its windows to the higher of its own and the global bar that close to the window's reset; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is the shortest sample interval, the one an account near a bar gets, for a seat's own sample, for `status`, and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a 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. `claudeBin`, `codexBin`, `grokBin`, `opencodeBin`, and `piBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, `TOKENMAXXING_OPENCODE_BIN`, and `TOKENMAXXING_PI_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
+`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; `thresholds.accounts` gives one account its own pair, keyed by label (`{"shared-seat": {"session": 75, "weekly": 75}}`), and `"credits": true` in an entry keeps an account with purchased usage credits usable past its windows, ranked after every account with plan headroom left; `policy.accountReleaseMs` (30 minutes for the session window, 5 hours for a weekly window by default) lifts each of its windows to the higher of its own and the global bar that close to the window's reset; `switchModels` names the models whose per-model cap triggers a move; `usagePollTtlMs` is the shortest sample interval, the one an account near a bar gets, for a seat's own sample, for `status`, and for the accounts each check tick samples; `maxWaitMs` bounds the depleted-pool countdown - a 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. `claudeBin`, `codexBin`, `grokBin`, `opencodeBin`, and `piBin` pin the real binaries; `init` writes them, and `TOKENMAXXING_CLAUDE_BIN`, `TOKENMAXXING_CODEX_BIN`, `TOKENMAXXING_GROK_BIN`, `TOKENMAXXING_OPENCODE_BIN`, and `TOKENMAXXING_PI_BIN` override them for one process, except that `init` pins the binary it resolved into `config.json`.
 
 State lives in `~/.config/tokenmaxxing/`; outside it the install touches Claude Code's `settings.json`, codex's `hooks.json`, the timer and usage hub units, and your shell rc. 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.114.0",
+  "version": "1.116.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/render.ts

@@ -46,7 +46,7 @@ export function bar(pct: number, width = 16): string {
   const clamped = clamp(pct, 0, 100);
   const filled = Math.round((clamped / 100) * width);
   const body = "█".repeat(filled) + "░".repeat(width - filled);
-  const label = `${clamped.toFixed(0).padStart(3)}%`;
+  const label = `${Math.max(0, pct).toFixed(0).padStart(3)}%`;
   const paint = clamped >= 95 ? c.red : clamped >= 75 ? c.yellow : c.green;
   return `${paint(body)} ${label}`;
 }

package/src/cli/status.ts

@@ -9,7 +9,7 @@ import { codexPool, grokPool, opencodeGoPool } from "../lib/paths.ts";
 import { barFor, earliestReset, gatedWindows, landWindows, isExhausted, isSessionWindow, limitWindows, liveUsed, nextWeeklyReset, sessionWindow, thresholdBars, weeklyWindow } from "../lib/picker.ts";
 import type { Provider, SampleReport } from "../lib/provider.ts";
 import { bar, c, count, emitJson, fmtAgo } from "./render.ts";
-import type { Account, Bars, Config, Thresholds, Window } from "../lib/types.ts";
+import type { Account, AccountThresholds, Bars, Config, Thresholds, Window } from "../lib/types.ts";
 
 export type WindowReport = { usedPercentage: number; resetsAt: number | null; windowSeconds: number | null };
 
@@ -24,7 +24,7 @@ type StatusAccount = {
   sessions: number;
   needsReauth: boolean;
   exhausted: boolean;
-  thresholds: Thresholds | null;
+  thresholds: AccountThresholds | null;
   usage: UsageReport | null;
   usageAt: number | null;
   limitsAt: number | null;
@@ -116,6 +116,7 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
           }
           if (a.lastUsageAt != null && (stored.lastUsageAt == null || a.lastUsageAt > stored.lastUsageAt)) {
             landWindows(stored, p.mergeWindows(a.windows, stored.windows), a.lastUsageAt, bars);
+            stored.hasCredits = a.hasCredits;
             if (a.email != null) stored.email = a.email;
             if (a.tier != null) stored.tier = a.tier;
             dirty = true;
@@ -221,7 +222,7 @@ function card(p: Provider, a: StatusAccount, now: number, staleAfterMs: number):
     for (const w of a.usage.limits) lines.push(usageRow(p.windowLabel(w.name), w));
   }
   const notes: Note[] = [];
-  if (a.thresholds) notes.push({ paint: c.dim, text: `thresholds 5h ${a.thresholds.session}% weekly ${a.thresholds.weekly}%` });
+  if (a.thresholds) notes.push({ paint: c.dim, text: `thresholds 5h ${a.thresholds.session}% weekly ${a.thresholds.weekly}%${a.thresholds.credits ? ", usable past them on credits" : ""}` });
   if (a.sample.ok && a.sample.source === "statusline") {
     const stale = a.usageAt == null || now - a.usageAt > staleAfterMs;
     const age = a.usageAt != null ? fmtAgo(a.usageAt, now) : "age unknown";

package/src/entries/supervisor.ts

@@ -81,6 +81,7 @@ export function analyzeArgs(argv: string[]): Analysis {
     if (a === "--") break;
     else if (a === "-p" || a === "--print") printMode = true;
     else if (a === "--version" || a === "-v" || a === "--help" || a === "-h") printMode = true;
+    else if (a === "--no-session-persistence") printMode = true;
     else if (a === "--session-id") {
       const next = argv[++i] ?? null;
       if (next && isUuid(next)) sessionId = next;

package/src/lib/codex.ts

@@ -13,7 +13,7 @@ import { codexSupervisorLink, ensurePathInRc, installCodexSupervisor, managedShe
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { codexPaths, codexPool, codexSeatFromEnv, optionalEnv } from "./paths.ts";
-import { isExhausted, pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
+import { isExhausted, onCredits, pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import { StoreUnusableError, type Observation, type Provider, type SampleReport, type SeatBorrow } from "./provider.ts";
 import { loadAccounts, loadConfig, pinBinOverride, saveAccounts, type Harvest } from "./state.ts";
 import { restoreTermios, saveTermios } from "./tty.ts";
@@ -33,6 +33,7 @@ function presence(): Map<string, number> {
 function applyUsage(account: Account, usage: CodexUsage, at: number): void {
   account.windows = usage.windows;
   account.lastUsageAt = at;
+  account.hasCredits = usage.hasCredits ?? undefined;
   if (usage.email != null) account.email = usage.email;
   if (usage.planType != null) account.tier = usage.planType;
 }
@@ -272,8 +273,10 @@ export async function borrowCodexSeat(pid: number): Promise<SeatBorrow> {
     const usable = idx.accounts.filter(
       (a) => !closed.has(a.id) && a.needsReauth !== true && !isExhausted(a, ctx) && codexStoreUsable(a.id)
     );
-    const fewest = Math.min(...usable.map((a) => lent[a.id] ?? 0));
-    const picked = pickBest(usable.filter((a) => (lent[a.id] ?? 0) === fewest), ctx);
+    const plan = usable.filter((a) => !onCredits(a, ctx));
+    const open = plan.length > 0 ? plan : usable;
+    const fewest = Math.min(...open.map((a) => lent[a.id] ?? 0));
+    const picked = pickBest(open.filter((a) => (lent[a.id] ?? 0) === fewest), ctx);
     if (!picked) return null;
     const store = ensureCodexStoreHome(picked.id);
     writePresence({ dir: codexPaths.presenceDir, id: seatId, accountId: picked.id, pid });

package/src/lib/codexusage.ts

@@ -32,6 +32,7 @@ const WireUsageSchema = z.looseObject({
   email: z.string().nullish(),
   plan_type: z.string().nullish(),
   rate_limit: WireRateLimitSchema.nullish(),
+  credits: z.looseObject({ has_credits: z.boolean().nullish() }).nullish(),
   additional_rate_limits: z
     .array(z.looseObject({ limit_name: z.string(), rate_limit: WireRateLimitSchema.nullish() }))
     .nullish(),
@@ -81,6 +82,7 @@ export async function fetchCodexUsage(input: { auth: CodexAuthJson; at: number }
     accountId: wire.account_id,
     email: wire.email ?? null,
     planType: wire.plan_type ?? null,
+    hasCredits: wire.credits?.has_credits ?? null,
     windows: [
       ...toWindows(wire.rate_limit, null, at),
       ...(wire.additional_rate_limits ?? []).flatMap((row) => toWindows(row.rate_limit, row.limit_name, at)),

package/src/lib/decide.ts

@@ -2,7 +2,7 @@ import { countBy } from "es-toolkit";
 import { CLAUDE_COMPACT_KILL_MS } from "./compact.ts";
 import { withLock } from "./lock.ts";
 import { loadAccounts, loadConfig, liveWaitClaims, releaseWaitClaim, replaceWaitClaim, saveAccounts } from "./state.ts";
-import { isExhausted, landWindows, limitWindows, nextWeeklyReset, pickBest, pickWaitTarget, screensUntilReset, sessionWindow, thresholdBars, weeklyWindow, type PickCtx } from "./picker.ts";
+import { isExhausted, landWindows, limitWindows, liveUsed, nextWeeklyReset, pickBest, pickWaitTarget, screensUntilReset, sessionWindow, thresholdBars, weeklyWindow, type PickCtx } from "./picker.ts";
 import { familyTokens } from "./usage.ts";
 import { errorMessage, log } from "./log.ts";
 import type { Observation, Provider } from "./provider.ts";
@@ -48,11 +48,13 @@ function enforcedWall(limit: EnforcedLimit, account: Account, now: number): numb
           .map((w) => w.resetsAt)
           .find((r): r is number => r != null) ?? null;
   const session = sessionWindow(account)?.resetsAt ?? null;
+  const weekly = weeklyWindow(account);
+  const span = limit.kind !== "overage" ? limit.kind : weekly != null && liveUsed(weekly, now) >= 100 ? "weekly" : "session";
   const cachedReset =
-    limit.kind === "session"
+    span === "session"
       ? session != null && session > now ? session : null
-      : nextWeeklyReset(familyReset ?? weeklyWindow(account)?.resetsAt ?? null, now);
-  return limit.resetsAt ?? cachedReset ?? now + (limit.kind === "session" ? FIVE_HOURS_MS : WEEK_MS);
+      : nextWeeklyReset(familyReset ?? weekly?.resetsAt ?? null, now);
+  return limit.resetsAt ?? cachedReset ?? now + (span === "session" ? FIVE_HOURS_MS : WEEK_MS);
 }
 
 export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, opts: EvalOpts = {}): Promise<SwapDecision> {

package/src/lib/picker.ts

@@ -6,7 +6,7 @@ export function thresholdBars(cfg: Config): Bars {
   const bars = (t: Thresholds): Thresholds => ({ session: t.session - cfg.policy.projectionMargin, weekly: t.weekly });
   return {
     ...bars(cfg.thresholds),
-    accounts: new Map(Object.entries(cfg.thresholds.accounts).map(([label, t]) => [label, bars(t)])),
+    accounts: new Map(Object.entries(cfg.thresholds.accounts).map(([label, t]) => [label, { ...bars(t), credits: t.credits }])),
     accountReleaseMs: cfg.policy.accountReleaseMs,
   };
 }
@@ -68,9 +68,13 @@ function windowEnd(w: Window): number {
   return w.resetsAt ?? w.sampledAt + (w.windowSeconds ?? 0) * 1000;
 }
 
+function spendsCredits(a: Account, bars: Bars): boolean {
+  return bars.accounts.get(a.label)?.credits === true && a.hasCredits !== false;
+}
+
 function blockedUntil(a: Account, w: Window, bars: Bars, now: number): number {
   const used = liveUsed(w, now);
-  if (used < barFor(a, w, bars, now)) return 0;
+  if (used < barFor(a, w, bars, now) || spendsCredits(a, bars)) return 0;
   const reset = windowEnd(w);
   const release = reset - releaseMs(w, bars);
   return release > now && used < barFor(a, w, bars, release) ? release : reset;
@@ -95,10 +99,10 @@ export function isExhausted(a: Account, ctx: PickCtx): boolean {
 
 export function landWindows(a: Account, windows: Window[], at: number, thresholds: Bars): void {
   const ctx: PickCtx = { now: at, thresholds, currentId: null, families: [], seats: null };
-  const blocked = a.enforcedUntil != null && isExhausted({ ...a, enforcedUntil: undefined }, ctx);
+  const blocked = a.enforcedUntil != null && isExhausted({ ...a, enforcedUntil: undefined, hasCredits: false }, ctx);
   a.windows = windows;
   a.lastUsageAt = at;
-  if (blocked && !isExhausted({ ...a, enforcedUntil: undefined }, ctx)) a.enforcedUntil = undefined;
+  if (blocked && !isExhausted({ ...a, enforcedUntil: undefined, hasCredits: false }, ctx)) a.enforcedUntil = undefined;
 }
 
 export function nextWeeklyReset(resetsAt: number | null, now: number): number | null {
@@ -139,7 +143,12 @@ export function seatHeadroom(a: Account, ctx: PickCtx): number {
   return (barFor(a, session, ctx.thresholds, ctx.now) - liveUsed(session, ctx.now)) / ((ctx.seats?.get(a.id) ?? 0) + 1);
 }
 
+export function onCredits(a: Account, ctx: PickCtx): boolean {
+  return spendsCredits(a, ctx.thresholds) && isExhausted({ ...a, hasCredits: false }, ctx);
+}
+
 const swapPreference = (ctx: PickCtx) => [
+  (a: Account) => (onCredits(a, ctx) ? 1 : 0),
   ...(ctx.seats == null ? [] : [(a: Account) => -seatHeadroom(a, ctx)]),
   (a: Account) => -pacePressure(a, ctx),
   (a: Account) => weeklyExpiry(a, ctx.now),

package/src/lib/types.ts

@@ -72,6 +72,7 @@ export const AccountSchema = z.object({
   usageRetryAt: z.number().optional(),
   enforcedUntil: z.number().optional(),
   needsReauth: z.boolean().optional(),
+  hasCredits: z.boolean().optional(),
   oauthAccount: OAuthAccountSchema.optional(),
 });
 export type Account = z.infer<typeof AccountSchema>;
@@ -84,7 +85,7 @@ export type AccountsIndex = z.infer<typeof AccountsIndexSchema>;
 
 export type EnforcedLimit = {
   account: string;
-  kind: "session" | "weekly" | "model" | "credits" | "org";
+  kind: "session" | "weekly" | "model" | "credits" | "org" | "overage";
   family: string | null;
   resetsAt: number | null;
   blind: boolean;
@@ -92,7 +93,9 @@ export type EnforcedLimit = {
 
 export type Thresholds = { session: number; weekly: number };
 
-export type Bars = Thresholds & { accounts: Map<string, Thresholds>; accountReleaseMs: Thresholds };
+export type AccountThresholds = Thresholds & { credits: boolean };
+
+export type Bars = Thresholds & { accounts: Map<string, AccountThresholds>; accountReleaseMs: Thresholds };
 
 const PercentSchema = z.number().min(0).max(100);
 
@@ -102,7 +105,7 @@ export const ConfigSchema = z
       .object({
         session: PercentSchema.default(90),
         weekly: PercentSchema.default(98),
-        accounts: z.record(z.string(), z.object({ session: PercentSchema, weekly: PercentSchema })).default({}),
+        accounts: z.record(z.string(), z.object({ session: PercentSchema, weekly: PercentSchema, credits: z.boolean().default(false) })).default({}),
       })
       .prefault({}),
     claudeBin: z.string().default(""),
@@ -248,6 +251,7 @@ export type CodexUsage = {
   accountId: string;
   email: string | null;
   planType: string | null;
+  hasCredits: boolean | null;
   windows: Window[];
 };
 

package/src/lib/usage.ts

@@ -115,7 +115,8 @@ export type EnforcedClass =
   | { kind: "weekly"; resetsAt: number | null }
   | { kind: "model"; family: string; resetsAt: number | null }
   | { kind: "credits"; family: string; resetsAt: null }
-  | { kind: "org"; resetsAt: null };
+  | { kind: "org"; resetsAt: null }
+  | { kind: "overage"; resetsAt: null };
 
 const ErrorBodySchema = z.looseObject({
   error: z.looseObject({ type: z.string().optional(), details: z.looseObject({ error_code: z.string().optional() }).optional() }).optional(),
@@ -140,6 +141,7 @@ export function classifyEnforcedLimit(row: TranscriptRow, switchModels: string[]
   const type = q.rateLimitType ?? "";
   if (type === "five_hour") return { kind: "session", resetsAt };
   if (type === "seven_day") return { kind: "weekly", resetsAt };
+  if (type === "overage") return { kind: "overage", resetsAt: null };
   const family = switchModels.find((f) => type.includes(f));
   return family ? { kind: "model", family, resetsAt } : null;
 }