tokenmaxxing 1.87.0 → 1.89.0

package/DESIGN.md

@@ -36,8 +36,8 @@ 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.
-  - `wait-queue.json` - the depleted-pool wait claims (`{sessionId, accountId, at, waitUntil}`), so at most four sessions wait on one account; a session that arrives when every account already has four waiters takes the soonest reset anyway.
+  - `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)).
   - `sessions/<sid>.json`, `onboard/`, `hub-key`, `update.json`, `spawnrate.json`, `tokenmaxxing.log`, the codex `codex-onboard/`, `codex-respawn/`, and `codex-live/`, and the `grok-*` and `opencode-go-*` state of the status-only pools: the full table is in [State directory layout](docs/content/docs/state-directory.mdx).

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.87.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/pisupervisor.ts

@@ -386,6 +386,13 @@ export async function runPiSupervisor(argv: string[]): Promise<number> {
             savedTermios,
           });
         }
+        if (pool === "claude") {
+          try {
+            releaseWaitClaim(id);
+          } catch (e) {
+            log("pisupervisor.claim_release_failed", { err: errorMessage(e) });
+          }
+        }
         return { proc: spawned, seat: picked };
       });
       if (launched == null) {
@@ -422,7 +429,6 @@ export async function runPiSupervisor(argv: string[]): Promise<number> {
         if (waitUntil > Date.now()) {
           if (await countdownWait(target.label, waitUntil, { stream: false, say })) overriddenUntil = waitUntil;
         } else say(`\n\x1b[36m↻ tokenmaxxing: moving pi to ${target.label} - resuming...\x1b[0m\n`);
-        await releaseClaim();
         wanted = target.id;
         launchArgs = sessionExists(dirs, sid) ? ["--session-id", sid, ...args.flags, "--", RESUME_PROMPT] : firstArgs;
         continue;

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

@@ -180,7 +180,24 @@ type MarkerGate = {
   overriddenUntil: number;
 };
 
-function consumableMarker(marker: string, gate: MarkerGate): z.infer<typeof RespawnMarkerSchema> | null {
+function releaseClaimLocked(sid: string): void {
+  try {
+    releaseWaitClaim(sid);
+  } catch (e) {
+    log("supervisor.claim_release_failed", { err: errorMessage(e) });
+  }
+}
+
+async function discardMarker(marker: string, event: string, fields: Record<string, unknown>): Promise<null> {
+  await withLock(claudePool.lockFile, () => {
+    rmSync(marker, { force: true });
+    releaseClaimLocked(basename(marker));
+  });
+  log(event, fields);
+  return null;
+}
+
+async function consumableMarker(marker: string, gate: MarkerGate): Promise<z.infer<typeof RespawnMarkerSchema> | null> {
   let m: z.infer<typeof RespawnMarkerSchema>;
   try {
     m = readJsonFile(marker, RespawnMarkerSchema);
@@ -191,14 +208,10 @@ function consumableMarker(marker: string, gate: MarkerGate): z.infer<typeof Resp
     );
   }
   if (m.launchedAt !== undefined && m.launchedAt !== gate.launchedAt) {
-    rmSync(marker, { force: true });
-    log("supervisor.marker_stale", { markerLaunch: m.launchedAt, childLaunch: gate.launchedAt });
-    return null;
+    return discardMarker(marker, "supervisor.marker_stale", { markerLaunch: m.launchedAt, childLaunch: gate.launchedAt });
   }
   if (m.waitUntil > Date.now() && m.waitUntil <= gate.overriddenUntil) {
-    rmSync(marker, { force: true });
-    log("supervisor.marker_overridden", { waitUntil: m.waitUntil });
-    return null;
+    return discardMarker(marker, "supervisor.marker_overridden", { waitUntil: m.waitUntil });
   }
   return m;
 }
@@ -365,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; } });
   }
 
@@ -414,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 });
@@ -433,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) } : {}),
         },
       });
@@ -450,6 +466,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
           savedTermios,
         });
       }
+      releaseClaimLocked(sid);
       return { child: spawned, seat: picked };
     });
     if (launched == null) {
@@ -462,7 +479,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     await raceMarkerOrExit({
       child: proc,
       tick: async () => {
-        if (existsSync(marker) && consumableMarker(marker, gate) != null) return true;
+        if (existsSync(marker) && (await consumableMarker(marker, gate)) != null) return true;
         if (seat && !terminating && Date.now() >= seatCheckAt) {
           const decided = await moveExhaustedSeat(seat, sid, gate, model);
           seatCheckAt = Date.now() + (decided ? SEAT_RETRY_MS : SEAT_POLL_MS);
@@ -478,7 +495,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       },
     });
 
-    const m = !terminating && existsSync(marker) ? consumableMarker(marker, gate) : null;
+    const m = !terminating && existsSync(marker) ? await consumableMarker(marker, gate) : null;
     if (m) {
       rmSync(marker, { force: true });
       respawns++;
@@ -498,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) {
@@ -511,8 +529,8 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       if (m.waitUntil > Date.now()) {
         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.`);
-      await releaseClaim();
       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/claude.ts

@@ -1,5 +1,6 @@
 import { mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { countBy } from "es-toolkit";
 import { z } from "zod";
 import { readItem, writeItem, deleteItem, isolatedTarget, readStore, storeTarget, claudeAiOauthOnly } from "./credstore.ts";
 import { CLAUDE_BIN, resolveRealBin, resolveVerifiedClaude } from "./claudebin.ts";
@@ -10,10 +11,10 @@ import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isDeadCredential
 import { claudePool, env, paths, seatFromEnv, storeDirFor } from "./paths.ts";
 import { landWindows, pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
 import { deletePiStore } from "./piauth.ts";
-import { seatCounts } from "./presence.ts";
+import { livingPresences } from "./presence.ts";
 import { StoreUnusableError, type Observation, type Provider, type SampleReport } from "./provider.ts";
 import { foldTee, sampleAccountUsage, teeObservation, usageBlockedUntil } from "./sample.ts";
-import { clearUsageSnapshot, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
+import { clearUsageSnapshot, liveWaitClaims, loadAccounts, loadConfig, loadUsageSnapshot, pinBinOverride, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { saveTermios, restoreTermios } from "./tty.ts";
 import { fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredentialEnv, windowsOf } from "./usage.ts";
 import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config, type ModelInfo } from "./types.ts";
@@ -24,7 +25,9 @@ function liveId(): string | null {
 }
 
 function presence(): Map<string, number> {
-  return seatCounts(paths.presenceDir);
+  const seats = new Map(livingPresences(paths.presenceDir).map((s) => [s.id, s.accountId]));
+  for (const claim of liveWaitClaims(Date.now())) seats.set(claim.sessionId, claim.accountId);
+  return new Map(Object.entries(countBy([...seats.values()], (id) => id)));
 }
 
 const PROBE_BACKOFF_CAP_MS = 30 * 60 * 1000;

package/src/lib/decide.ts

@@ -1,4 +1,5 @@
 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, liveUsed, nextWeeklyReset, pickBest, pickWaitTarget, sessionWindow, thresholdBars, weeklyWindow, type PickCtx } from "./picker.ts";
@@ -13,9 +14,11 @@ export type EvalOpts = {
   seatId?: string | null;
   sessionFamilies?: string[];
   waiterId?: string;
+  exclude?: string[];
 };
 
 const MAX_WAITERS_PER_ACCOUNT = 4;
+const MOVE_CLAIM_MS = 2 * CLAUDE_COMPACT_KILL_MS;
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
@@ -80,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));
@@ -90,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" };
@@ -123,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;
@@ -143,6 +147,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
         continue;
       }
       log("decide.swap", { account: best.id.slice(0, 8), enforced: enforced2 != null });
+      if (waiterId != null && p.seats === "shared") replaceWaitClaim({ sessionId: waiterId, accountId: best.id, at: now, waitUntil: now + MOVE_CLAIM_MS });
       return { swapped: true, account: best, reason: "swapped" };
     }
 

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;