tokenmaxxing 1.88.0 → 1.89.0

package/DESIGN.md

@@ -36,7 +36,7 @@ It is a process manager only - spawn with inherited stdio (stdin through a relay
   - `codex-stores/<uuid8>/` - one Codex credential store per pooled account: its `auth.json`, with everything else symlinked to the shared `~/.codex` so sessions, history, and config stay shared and `codex resume` works across stores.
   - `usage/<uuid8>.json` - the statusline tee per account, written by the sessions running on it.
   - `live/<session-id>` - PID-validated presence per supervised session, naming its account; placement counts them.
-  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal): the target account, the session to resume, a `waitUntil`, a `compact` flag, the `origin` (the hook or the seat watch that wrote it), and the launch time the marker was written for.
+  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal): the target account, the session to resume, a `waitUntil`, a `compact` flag, the `origin` (the hook or the seat watch that wrote it), the launch time the marker was written for, and after a usage-credits refusal the accounts that have refused the session.
   - `wait-queue.json` - the claims of supervised sessions that are moving or waiting (`{sessionId, accountId, at, waitUntil}`), naming the account each relaunches on: placement counts a claimed session there, and at most four sessions wait on one account; a session that arrives when every account already has four waiters takes the soonest reset anyway.
   - `bin/claude` and `bin/codex` - the supervisors, beside the `tokenmaxxing` and `xx` entry points; `bin/pi` after `init --pi`.
   - `pi-stores/claude/<uuid8>/` and `pi-stores/codex/<uuid8>/` - one pi store per pooled account that has a pi login: the account's own pi grant in `auth.json`, everything else symlinked to the shared `~/.pi/agent` ([pi support](docs/content/docs/pi.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 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.
+- **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. A refusal for usage credits, which the usage read cannot predict, walls nothing: the refused session moves with the Fable cap screened, and a later credits move never returns it to an account that already refused it.
 
 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.88.0",
+  "version": "1.89.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/entries/stopfailurehook.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { claude } from "../lib/claude.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { readStdin } from "../lib/proc.ts";
-import { adoptLiveSession, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
+import { adoptLiveSession, refusedAccounts, supervisedSession, writeRespawnMarker } from "../lib/sessions.ts";
 import { loadConfig } from "../lib/state.ts";
 import { classifyEnforcedLimit, findEnforcedRow, parseErrorBody, readTranscriptTail, type TranscriptRow } from "../lib/usage.ts";
 import { paths } from "../lib/paths.ts";
@@ -57,7 +57,7 @@ export async function runStopFailureHook(): Promise<number> {
 
     let enforced: EnforcedLimit | null = null;
     if (limit && account) {
-      enforced = { account, kind: limit.kind, family: limit.kind === "model" ? limit.family : null, resetsAt: limit.resetsAt, blind: !mainLoop && limit.kind !== "model" };
+      enforced = { account, kind: limit.kind, family: limit.kind === "model" || limit.kind === "credits" ? limit.family : null, resetsAt: limit.resetsAt, blind: !mainLoop && limit.kind !== "model" };
       log("stopfailure.enforced", { kind: limit.kind, family: enforced.family ?? undefined, resetsAt: limit.resetsAt, subagent: !mainLoop });
     } else {
       log("stopfailure.unclassified", {
@@ -80,9 +80,10 @@ export async function runStopFailureHook(): Promise<number> {
       );
     }
 
-    const decision = await evaluateAndMaybeSwap(claude, now, canRespawn, enforced, { waiterId: canRespawn ? session?.sid : undefined });
+    const refused = enforced?.kind === "credits" ? [...new Set([...refusedAccounts(), enforced.account])] : undefined;
+    const decision = await evaluateAndMaybeSwap(claude, now, canRespawn, enforced, { waiterId: canRespawn ? session?.sid : undefined, exclude: refused });
     if (session && canRespawn && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false, origin: "stopfailure" });
+      writeRespawnMarker({ session, accountId: decision.account.id, waitUntil: decision.waitUntil ?? now, compact: false, origin: "stopfailure", refused });
       log("stopfailure.marker", { session: session.sid.slice(0, 8), live: session.live.slice(0, 8), account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil ?? now });
     } else {
       log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });

package/src/entries/supervisor.ts

@@ -378,6 +378,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     delete passthroughEnv.TOKENMAXXING_SUPERVISED;
     delete passthroughEnv.TOKENMAXXING_SESSION_ID;
     delete passthroughEnv.TOKENMAXXING_MODEL;
+    delete passthroughEnv.TOKENMAXXING_REFUSED;
     return runPassthrough({ real, argv, env: passthroughEnv, onSpawn: (p) => { child = p; } });
   }
 
@@ -427,6 +428,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   let respawns = 0;
   let overriddenUntil = 0;
   let wanted: string | null = null;
+  let refused: string[] = [];
   try {
   while (true) {
     if (existsSync(marker)) rmSync(marker, { force: true });
@@ -446,6 +448,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
           TOKENMAXXING_SESSION_ID: sid,
           TOKENMAXXING_LAUNCHED_AT: String(gate.launchedAt),
           TOKENMAXXING_MODEL: effective.model ?? "",
+          TOKENMAXXING_REFUSED: refused.join(","),
           ...(picked ? { CLAUDE_SECURESTORAGE_CONFIG_DIR: storeDirFor(picked.id) } : {}),
         },
       });
@@ -512,6 +515,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         delete compactEnv.TOKENMAXXING_SESSION_ID;
         delete compactEnv.TOKENMAXXING_LAUNCHED_AT;
         delete compactEnv.TOKENMAXXING_MODEL;
+        delete compactEnv.TOKENMAXXING_REFUSED;
         const outcome = await compactClaudeSession({ real, sid: m.sessionId, transcript, env: compactEnv, onSpawn: (p) => { child = p; } });
         child = null;
         if (terminating) {
@@ -526,6 +530,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
         if (await countdownWait(label, m.waitUntil, { stream, say })) overriddenUntil = m.waitUntil;
       } else say(`\n\x1b[36m↻ tokenmaxxing: moving to ${label} - resuming...\x1b[0m\n`, `tokenmaxxing: moving to ${label} and resuming.`);
       wanted = m.accountId;
+      refused = m.refused ?? refused;
       saveSessionFlags(m.sessionId, persistable, process.cwd());
       const prompt = resumable ? resumePrompt({ compacted, origin: m.origin }) : null;
       firstLine = relay !== null && prompt !== null ? userLine(prompt) : null;

package/src/lib/decide.ts

@@ -14,6 +14,7 @@ export type EvalOpts = {
   seatId?: string | null;
   sessionFamilies?: string[];
   waiterId?: string;
+  exclude?: string[];
 };
 
 const MAX_WAITERS_PER_ACCOUNT = 4;
@@ -82,7 +83,8 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     const origin = enforced ? idx.accounts.find((a) => a.id === enforced.account) : undefined;
     const prior = origin?.enforcedUntil != null && origin.enforcedUntil > now;
     let stamped = false;
-    if (enforced && origin) {
+    const credits = enforced?.kind === "credits";
+    if (enforced && origin && !credits) {
       const covered = modelKindCovered(enforced, origin, now, bars.weekly);
       if (!covered || prior) {
         origin.enforcedUntil = Math.max(origin.enforcedUntil ?? 0, enforcedWall(enforced, origin, now));
@@ -92,7 +94,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
       saveAccounts(p.pool, idx);
       log("usage.enforced_limit", { kind: enforced.kind, family: enforced.family ?? undefined, resetsAt: origin.enforcedUntil, blind: prior || enforced.blind, live: origin === active, covered: covered && !prior });
     }
-    const enforced2 = stamped && origin === active ? enforced : null;
+    const enforced2 = (stamped || credits) && origin === active ? enforced : null;
 
     if (id2 != null && !active) {
       return { swapped: false, account: null, reason: "live-credential-not-in-pool" };
@@ -125,7 +127,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
 
     const seatOf = (cur: { accounts: Account[] }): Account | null => cur.accounts.find((a) => a.id === id2) ?? null;
 
-    const rejected = new Set<string>();
+    const rejected = new Set<string>(opts.exclude);
     const usable = (accounts: Account[]): Account[] => accounts.filter((a) => !rejected.has(a.id) && (p.seats === "shared" || a.id === id2 || !present.has(a.id)));
     const skipOrThrow = (e: unknown, candidate: Account): void => {
       if (p.classifySwapError(e) === "fatal") throw e;

package/src/lib/sessions.ts

@@ -104,6 +104,7 @@ export function pruneStaleSessions(now: number): void {
 export type SupervisedSession = { sid: string; launchedAt: number | null; live: string };
 
 const LaunchedAtSchema = z.coerce.number().finite().optional().catch(undefined);
+const RefusedSchema = z.string().optional().transform((ids) => (ids ?? "").split(",").filter((id) => id !== ""));
 
 export function supervisedSession(env: Record<string, string | undefined> = process.env): SupervisedSession | null {
   if (env.TOKENMAXXING_SUPERVISED !== "1") return null;
@@ -112,6 +113,10 @@ export function supervisedSession(env: Record<string, string | undefined> = proc
   return { sid, launchedAt: LaunchedAtSchema.parse(env.TOKENMAXXING_LAUNCHED_AT) ?? null, live: liveSessionId(sid) };
 }
 
+export function refusedAccounts(env: Record<string, string | undefined> = process.env): string[] {
+  return RefusedSchema.parse(env.TOKENMAXXING_REFUSED);
+}
+
 export function adoptLiveSession(session: SupervisedSession, stdinSid: string | undefined): SupervisedSession | null {
   if (stdinSid == null || stdinSid === session.live) return session;
   const child = presencePid({ dir: paths.presenceDir, id: session.sid });
@@ -124,7 +129,7 @@ export function adoptLiveSession(session: SupervisedSession, stdinSid: string |
   return { ...session, live: stdinSid };
 }
 
-export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"] }): void {
+export function writeRespawnMarker(input: { session: SupervisedSession; accountId: string; waitUntil: number; compact: boolean; origin: z.infer<typeof RespawnMarkerSchema>["origin"]; refused?: string[] }): void {
   const payload: z.infer<typeof RespawnMarkerSchema> = {
     accountId: input.accountId,
     ts: Date.now(),
@@ -133,6 +138,7 @@ export function writeRespawnMarker(input: { session: SupervisedSession; accountI
     compact: input.compact,
     origin: input.origin,
     ...(input.session.launchedAt != null ? { launchedAt: input.session.launchedAt } : {}),
+    ...(input.refused != null ? { refused: input.refused } : {}),
   };
   writeFileAtomic(join(paths.respawnDir, input.session.sid), JSON.stringify(payload));
 }

package/src/lib/types.ts

@@ -84,7 +84,7 @@ export type AccountsIndex = z.infer<typeof AccountsIndexSchema>;
 
 export type EnforcedLimit = {
   account: string;
-  kind: "session" | "weekly" | "model";
+  kind: "session" | "weekly" | "model" | "credits";
   family: string | null;
   resetsAt: number | null;
   blind: boolean;
@@ -150,6 +150,7 @@ export const RespawnMarkerSchema = z.object({
   compact: z.boolean(),
   origin: z.enum(["stop", "sessionstart", "stopfailure", "seatwatch"]),
   launchedAt: z.number().optional(),
+  refused: z.array(z.string()).optional(),
 });
 
 export const EpochSecondsSchema = z.number().transform((seconds) => seconds * 1000);

package/src/lib/usage.ts

@@ -56,6 +56,7 @@ export const TranscriptRowSchema = z.looseObject({
   timestamp: z.string().optional(),
   isApiErrorMessage: z.boolean().optional(),
   apiErrorIsTransient: z.boolean().optional(),
+  apiError: z.string().optional(),
   error: z.string().optional(),
   errorDetails: z.string().optional(),
   quotaLimits: z.looseObject({ rateLimitType: z.string().optional(), resetsAt: EpochSecondsSchema.optional() }).optional(),
@@ -114,13 +115,14 @@ export function findEnforcedRow(input: { rows: TranscriptRow[]; lastAssistantMes
 export type EnforcedClass =
   | { kind: "session"; resetsAt: number | null }
   | { kind: "weekly"; resetsAt: number | null }
-  | { kind: "model"; family: string; resetsAt: number | null };
+  | { kind: "model"; family: string; resetsAt: number | null }
+  | { kind: "credits"; family: string; resetsAt: null };
 
 const ErrorBodySchema = z.looseObject({
   error: z.looseObject({ type: z.string().optional(), details: z.looseObject({ error_code: z.string().optional() }).optional() }).optional(),
 });
 
-const CREDITS_GATED_FAMILIES = ["fable"];
+const CREDITS_FAMILY = "fable";
 
 export function parseErrorBody(errorDetails: string | undefined): z.infer<typeof ErrorBodySchema> | null {
   if (!errorDetails) return null;
@@ -131,19 +133,15 @@ export function parseErrorBody(errorDetails: string | undefined): z.infer<typeof
 }
 
 export function classifyEnforcedLimit(row: TranscriptRow, switchModels: string[]): EnforcedClass | null {
+  if (row.apiError === "model_requires_usage_credits") return { kind: "credits", family: CREDITS_FAMILY, resetsAt: null };
   const q = row.quotaLimits;
-  if (q) {
-    const resetsAt = q.resetsAt ?? null;
-    const type = q.rateLimitType ?? "";
-    if (type === "five_hour") return { kind: "session", resetsAt };
-    if (type === "seven_day") return { kind: "weekly", resetsAt };
-    const family = switchModels.find((f) => type.includes(f));
-    return family ? { kind: "model", family, resetsAt } : null;
-  }
-  if (row.apiErrorIsTransient === true) return null;
-  if (parseErrorBody(row.errorDetails)?.error?.type !== "rate_limit_error") return null;
-  const family = switchModels.find((f) => CREDITS_GATED_FAMILIES.includes(f));
-  return family ? { kind: "model", family, resetsAt: null } : null;
+  if (!q) return null;
+  const resetsAt = q.resetsAt ?? null;
+  const type = q.rateLimitType ?? "";
+  if (type === "five_hour") return { kind: "session", resetsAt };
+  if (type === "seven_day") return { kind: "weekly", resetsAt };
+  const family = switchModels.find((f) => type.includes(f));
+  return family ? { kind: "model", family, resetsAt } : null;
 }
 
 const FIVE_HOURS_S = 5 * 3600;