tokenmaxxing 1.124.0 → 1.126.0

package/DESIGN.md

@@ -62,7 +62,7 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 4. Write `respawn/<session-id>` (atomic temp+rename) naming the target, with `waitUntil` now for a plain move or the assigned reset when the pool is depleted. No credential is written.
 
 ### 3.3 Move and depleted-pool pause (supervisor)
-The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed turn boundary, deletes the marker, resets the terminal, compacts the conversation when the marker asks for it and the old seat's record carries no live `enforcedUntil` (`compact: true` from the Stop and SessionStart hooks and from the supervisor's own seat watch, `false` from StopFailure: it runs `claude -p --resume <live-id> /compact` under the old seat's store, bounded at five minutes; the compaction counts only when a `compact_boundary` row lands in the transcript, because a refused compaction still exits 0, and a failure only prints why), and (when `waitUntil` is in the future) shows an interruptible countdown to the reset; then it relaunches `claude --resume <live-id>` (`--session-id <live-id>` when that id has no transcript yet, because `--resume` exits with `No conversation found` for it) with `CLAUDE_SECURESTORAGE_CONFIG_DIR` set to the target's store and rewrites the session's presence. The marker file is keyed by the launch id `<sid>`; the live id inside it is the session id the supervised process runs now, which `/clear` and an in-session `/resume` change. A hook adopts a differing stdin id as the live id (`current` in `sessions/<sid>.json`) only when its own process descends, through shell processes alone, from the presence record's pid; any other differing id is a nested session and writes nothing. The resumed process reads that store cold → runs on the target account, same conversation. The `--session-id` path is the exception: the conversation has no prior turn (a `/clear` with no turn since, or a move before the first turn), so it starts with no compaction and no first prompt, and in a stream-json session the relay replays the harness lines the killed child received: `user` lines and the `initialize` and session-state control requests in `REPLAYED_REQUESTS`; every other control request gets an error `control_response` on stdout, because a repeat could run its effect twice, and the `control_response` answers to the killed child's own requests are dropped. A first launch with `--resume <id>` takes the same path when the supervisor holds `sessions/<id>.json` for that id and no project directory holds its transcript. On the `--resume` path the relaunch submits a first prompt that names the move (and the compaction, when it landed). After a Stop move the previous turn had finished, so the prompt asks Claude to end the turn without restating it, and to relaunch any background Bash task, Monitor, or Workflow run that turn waited on, because the move ended it. After any other move the prompt asks Claude to continue the task, says the restart ended every background Bash task, Monitor, and Workflow run the session started, and asks Claude to relaunch what the task still needs; a SessionStart move is in that group because a prompt sent inside the marker poll window can already have started on the old seat. The conversation goes on without a keystroke: in a terminal session it is the positional prompt after the session id; in a stream-json session (`--input-format stream-json`, where the binary ignores a positional prompt) the supervisor owns stdin, relays the harness's lines to the child through a pipe, and writes the prompt as the first `user` line of the new process. In a terminal session the supervisor's own notices go to stderr. In a stream-json session (`--output-format stream-json`, read from the effective flags like the relay) there is no terminal and no statusline, so the supervisor writes each notice (the compaction and its failure, the move, the depleted-pool wait with its resume time, the resume) to stdout as a `system` line of subtype `informational` and level `warning`, the shape Claude Code emits for its own print-mode notices, which the harness renders in the conversation while the stream stays parseable; the per-second countdown ticks stay terminal-only, and the supervisor writes only while no child is running. The `SessionStart` hook (every source) re-runs the decision before the first turn and writes the same marker if the seat is already over its bar or the pool is depleted. The supervisor also watches its own seat every ten seconds while the child runs (account record plus tee, the same bars) and writes the marker itself when the seat is at or over a bar, so a move never depends on a hook firing: a harness session between turns whose background workflow burns the window, or a subagent refusal that stamped the wall, is moved within seconds. SIGTERM to the supervisor is forwarded to the child and the supervisor exits after it, so a harness that stops the wrapper (the Agent SDK does) never leaves an orphaned claude on the old seat. A marker whose `launchedAt` does not match the running child is discarded, and after a Ctrl-C on the countdown a later marker whose `waitUntil` falls inside the skipped wait is ignored. A marker that fails to parse is never deleted and never treated as absent: the supervisor stops the child, restores the terminal, and exits naming the marker path. In a stream-json session that fatal, the wrap-depth abort, the wrapper-chain abort, and a failed presence write also go to stdout as the same `informational`/`warning` line.
+The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed turn boundary, deletes the marker, resets the terminal, compacts the conversation when the marker asks for it and the old seat's record carries no live `enforcedUntil` (`compact: true` from the Stop and SessionStart hooks and from the supervisor's own seat watch, `false` from StopFailure: it runs `claude -p --resume <live-id> /compact` under the old seat's store, bounded at five minutes; the compaction counts only when a `compact_boundary` row lands in the transcript, because a refused compaction still exits 0, and a failure only prints why), and (when `waitUntil` is in the future) shows an interruptible countdown to the reset; then it relaunches `claude --resume <live-id>` (`--session-id <live-id>` when that id has no transcript yet, because `--resume` exits with `No conversation found` for it) with `CLAUDE_SECURESTORAGE_CONFIG_DIR` set to the target's store and rewrites the session's presence. The marker file is keyed by the launch id `<sid>`; the live id inside it is the session id the supervised process runs now, which `/clear` and an in-session `/resume` change. A hook adopts a differing stdin id as the live id (`current` in `sessions/<sid>.json`) only when its own process descends, through shell processes alone, from the presence record's pid; any other differing id is a nested session and writes nothing. The resumed process reads that store cold → runs on the target account, same conversation. The `--session-id` path is the exception: the conversation has no prior turn (a `/clear` with no turn since, or a move before the first turn), so it starts with no compaction and no first prompt, and in a stream-json session the relay replays the harness lines the killed child received: `user` lines and the `initialize` and session-state control requests in `REPLAYED_REQUESTS`; every other control request gets an error `control_response` on stdout, because a repeat could run its effect twice, and the `control_response` answers to the killed child's own requests are dropped. A first launch with `--resume <id>` takes the same path when the supervisor holds `sessions/<id>.json` for that id and no project directory holds its transcript. On the `--resume` path the relaunch submits a first prompt that names the move (and the compaction, when it landed). After a Stop move the previous turn had finished, so the prompt asks Claude to end the turn without restating it, and to relaunch any background Bash task, Monitor, or Workflow run that turn waited on, because the move ended it. After any other move the prompt asks Claude to continue the task, says the restart ended every background Bash task, Monitor, and Workflow run the session started, and asks Claude to relaunch what the task still needs; a SessionStart move is in that group because a prompt sent inside the marker poll window can already have started on the old seat. The conversation goes on without a keystroke: in a terminal session it is the positional prompt after the session id; in a stream-json session (`--input-format stream-json`, where the binary ignores a positional prompt) the supervisor owns stdin, relays the harness's lines to the child through a pipe, sends the new process the latest `initialize` and session-state control requests the harness sent, because the Agent SDK sends `initialize` once per query and it carries the appended system prompt, the hooks, and the SDK MCP servers, and then writes the prompt as the first `user` line. In a terminal session the supervisor's own notices go to stderr. In a stream-json session (`--output-format stream-json`, read from the effective flags like the relay) there is no terminal and no statusline, so the supervisor writes each notice (the compaction and its failure, the move, the depleted-pool wait with its resume time, the resume) to stdout as a `system` line of subtype `informational` and level `warning`, the shape Claude Code emits for its own print-mode notices, which the harness renders in the conversation while the stream stays parseable; the per-second countdown ticks stay terminal-only, and the supervisor writes only while no child is running. The `SessionStart` hook (every source) re-runs the decision before the first turn and writes the same marker if the seat is already over its bar or the pool is depleted. The supervisor also watches its own seat every ten seconds while the child runs (account record plus tee, the same bars) and writes the marker itself when the seat is at or over a bar, so a move never depends on a hook firing: a harness session between turns whose background workflow burns the window, or a subagent refusal that stamped the wall, is moved within seconds. SIGTERM to the supervisor is forwarded to the child and the supervisor exits after it, so a harness that stops the wrapper (the Agent SDK does) never leaves an orphaned claude on the old seat. A marker whose `launchedAt` does not match the running child is discarded, and after a Ctrl-C on the countdown a later marker whose `waitUntil` falls inside the skipped wait is ignored. A marker that fails to parse is never deleted and never treated as absent: the supervisor stops the child, restores the terminal, and exits naming the marker path. In a stream-json session that fatal, the wrap-depth abort, the wrapper-chain abort, and a failed presence write also go to stdout as the same `informational`/`warning` line.
 
 ### 3.4 Placement (supervisor, under the pool lock)
 1. Fold every account's tee into the index.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.124.0",
+  "version": "1.126.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/check.ts

@@ -1,5 +1,6 @@
 import { claude } from "../lib/claude.ts";
-import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { codex } from "../lib/codex.ts";
+import { evaluateAndMaybeSwap, useBankedResets } from "../lib/decide.ts";
 import { sampleOldest } from "../lib/sample.ts";
 import { pruneStaleSessions } from "../lib/sessions.ts";
 import { loadConfig } from "../lib/state.ts";
@@ -13,6 +14,7 @@ export async function cmdCheck(json = false): Promise<number> {
   try {
     pruneStaleSessions(now);
     d = await evaluateAndMaybeSwap(claude, now);
+    await useBankedResets(codex, loadConfig(), now);
     await sampleOldest(loadConfig());
     await maybeAutoUpdate();
   } catch (e) {

package/src/cli/status.ts

@@ -6,7 +6,7 @@ import { opencodeGo } from "../lib/opencodego.ts";
 import { loadAccounts, loadConfig, saveAccounts } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
 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 { barFor, earliestReset, gatedWindows, landGrant, 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, AccountThresholds, Bars, Config, Thresholds, Window } from "../lib/types.ts";
@@ -121,6 +121,11 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
             if (a.tier != null) stored.tier = a.tier;
             dirty = true;
           }
+          const report = reports.get(a.id);
+          if (report?.ok === true && report.source === "probe" && a.bankedResetAt != null) {
+            landGrant(stored, a.bankedReset, a.bankedResetAt);
+            dirty = true;
+          }
         }
         if (dirty) saveAccounts(p.pool, fresh);
         idx = fresh;

package/src/entries/supervisor.ts

@@ -345,6 +345,7 @@ function controlErrorLine(requestId: string): string {
 class StdinRelay {
   private sink: FileSink | null = null;
   private queue: string[] = [];
+  private state = new Map<string, string>();
   private replayable: string[] = [];
   private dropped: string[] = [];
   private pendingTranscript: string | null = null;
@@ -364,7 +365,7 @@ class StdinRelay {
     this.replayable = [];
     this.dropped = [];
     this.pendingTranscript = pendingTranscript;
-    const lines = first === null ? this.queue : [first, ...this.queue];
+    const lines = [...this.state.values(), ...(first === null ? [] : [first]), ...this.queue];
     this.queue = [];
     for (const line of lines) this.forward(line);
     if (this.ended) this.close();
@@ -382,7 +383,7 @@ class StdinRelay {
     return dropped;
   }
 
-  private keep(line: string): void {
+  private keep(line: string, control: boolean, request: { request_id: string } | null): void {
     if (this.pendingTranscript === null) return;
     if (existsSync(this.pendingTranscript)) {
       this.pendingTranscript = null;
@@ -390,10 +391,8 @@ class StdinRelay {
       this.dropped = [];
       return;
     }
-    const parsed = RelayLineSchema.safeParse(JsonTextSchema.safeParse(line).data);
-    if (!parsed.success) this.replayable.push(line);
-    else if (parsed.data.type === "control_request" && REPLAYED_REQUESTS.has(parsed.data.request.subtype)) this.replayable.push(line);
-    else if (parsed.data.type === "control_request") this.dropped.push(parsed.data.request_id);
+    if (request !== null) this.dropped.push(request.request_id);
+    else if (!control) this.replayable.push(line);
   }
 
   private async pump(): Promise<void> {
@@ -401,18 +400,22 @@ class StdinRelay {
   }
 
   private forward(line: string): void {
+    const parsed = RelayLineSchema.safeParse(JsonTextSchema.safeParse(line).data);
+    const request = parsed.success && parsed.data.type === "control_request" ? parsed.data : null;
+    const setup = request !== null && REPLAYED_REQUESTS.has(request.request.subtype);
+    if (setup) this.state.set(request.request.subtype, line);
     if (this.sink !== null) {
       try {
         this.sink.write(line);
         this.sink.flush();
-        this.keep(line);
+        if (!setup) this.keep(line, parsed.success, request);
         return;
       } catch (e) {
         log("supervisor.relay_write_failed", { err: errorMessage(e) });
         this.sink = null;
       }
     }
-    this.queue.push(line);
+    if (!setup) this.queue.push(line);
   }
 
   private close(): void {

package/src/lib/claude.ts

@@ -9,14 +9,14 @@ import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isDeadCredential, InvalidGrantError } from "./oauth.ts";
 import { claudePool, env, paths, seatFromEnv, storeDirFor } from "./paths.ts";
-import { MAX_WAITERS_PER_ACCOUNT, landWindows, pickBest, pickEarliestReset, pickWaitTarget, thresholdBars, type PickCtx } from "./picker.ts";
+import { MAX_WAITERS_PER_ACCOUNT, pickBest, pickEarliestReset, pickWaitTarget, thresholdBars, type PickCtx } from "./picker.ts";
 import { deletePiStore } from "./piauth.ts";
 import { livingPresences, writePresence } from "./presence.ts";
-import { StoreUnusableError, type Observation, type Provider, type SampleReport, type SeatBorrow } from "./provider.ts";
-import { claimSample, foldTee, readyToSample, runSample, sampleAccountUsage, sampleDue, sampleIntervalMs, teeObservation, usageBlockedUntil } from "./sample.ts";
+import { StoreUnusableError, type Observation, type Provider, type ResetClaim, type SampleReport, type SeatBorrow } from "./provider.ts";
+import { claimSample, foldTee, landRead, readyToSample, runSample, sampleAccountUsage, sampleDue, sampleIntervalMs, teeObservation, usageBlockedUntil } from "./sample.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, scrubCredEnv, windowsOf } from "./usage.ts";
+import { claimResetGrant, fetchUsageDirect, gatedFamilies, mergeWindows, modelFromFlag, scrubCredEnv, windowsOf } from "./usage.ts";
 import { CredentialBlobSchema, JsonTextSchema, OAuthAccountSchema, type Account, type Config, type ModelInfo } from "./types.ts";
 import { c } from "../cli/render.ts";
 
@@ -48,9 +48,7 @@ async function observeLive(account: Account, cfg: Config, now: number, opts: { p
       if (account.needsReauth) a.needsReauth = true;
       if (outcome.ok) {
         a.probeFails = 0;
-        if (a.lastUsageAt == null || startedAt > a.lastUsageAt) {
-          landWindows(a, mergeWindows(windowsOf(outcome.usage, startedAt), a.windows), startedAt, thresholdBars(cfg));
-        }
+        landRead(a, outcome.usage, startedAt, thresholdBars(cfg));
       } else {
         a.probeFails = (a.probeFails ?? 0) + 1;
         if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
@@ -87,14 +85,14 @@ async function samplePool(accounts: Account[], _liveId: string | null, now: numb
         return;
       }
       a.lastProbeAt = now;
+      const startedAt = Date.now();
       const outcome = await runSample(a, ready);
       if (!outcome.ok) {
         if (outcome.retryAt != null) a.usageRetryAt = outcome.retryAt;
         reports.set(a.id, { ok: false, reason: outcome.reason });
         return;
       }
-      const at = Date.now();
-      landWindows(a, mergeWindows(windowsOf(outcome.usage, at), a.windows), at, bars);
+      landRead(a, outcome.usage, startedAt, bars);
       reports.set(a.id, { ok: true, source: "probe" });
     }),
   );
@@ -122,6 +120,15 @@ async function prepareMove(target: Account): Promise<void> {
   log("move.prepared", { account: target.id.slice(0, 8), label: target.label });
 }
 
+async function useBankedReset(a: Account, signal: AbortSignal): Promise<ResetClaim> {
+  const grant = a.bankedReset?.grant;
+  const organizationUuid = a.oauthAccount?.organizationUuid;
+  if (grant == null || organizationUuid == null) return { reset: false, detail: "no grant id or organization on the record" };
+  const creds = await readStore(a.id);
+  if (creds == null || isDeadCredential(creds) || creds.expiresAt <= Date.now()) return { reset: false, detail: "no unexpired access token in the store" };
+  return claimResetGrant({ accessToken: creds.accessToken, organizationUuid, grant }, signal);
+}
+
 async function storeUsable(a: Account): Promise<boolean> {
   try {
     const creds = await readStore(a.id);
@@ -339,6 +346,7 @@ export const claude: Provider = {
   samplePool,
   mergeWindows,
   swap: prepareMove,
+  useBankedReset,
   classifySwapError: (e) => (e instanceof InvalidGrantError ? "dead-grant" : e instanceof StoreUnusableError ? "skip" : "fatal"),
   removeCredentials,
   storeUsable,

package/src/lib/claudebin.ts

@@ -85,11 +85,15 @@ export function resolveRealBin(input: { name: string; key: BinKey }): string {
   throw new Error(`could not locate the real \`${input.name}\` binary (set ${input.key} in config.json)`);
 }
 
-export function verifyRealBin(input: { bin: string; name: string; versionOk: (versionOutput: string) => boolean }): string | null {
+function spawnVersion(bin: string) {
   const env = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH), TOKENMAXXING_PROBE: "1" };
+  return Bun.spawnSync([bin, "--version"], { env, stdout: "pipe", stderr: "pipe", timeout: 15_000, killSignal: "SIGKILL" });
+}
+
+export function verifyRealBin(input: { bin: string; name: string; versionOk: (versionOutput: string) => boolean }): string | null {
   let p;
   try {
-    p = Bun.spawnSync([input.bin, "--version"], { env, stdout: "pipe", stderr: "pipe", timeout: 15_000, killSignal: "SIGKILL" });
+    p = spawnVersion(input.bin);
   } catch (e) {
     return errorMessage(e);
   }
@@ -115,6 +119,17 @@ function isBareVersion(out: string): boolean {
 
 export const PI_BIN = { name: "pi", key: "piBin", versionOk: isBareVersion } as const;
 
+let userAgent: string | undefined;
+
+export function claudeUserAgent(): string {
+  if (userAgent != null) return userAgent;
+  const bin = resolveRealBin(CLAUDE_BIN);
+  const version = spawnVersion(bin).stdout.toString().trim().split(" ")[0] ?? "";
+  if (!isBareVersion(version)) throw new Error(`\`${bin} --version\` printed no version`);
+  userAgent = `claude-cli/${version} (external, cli)`;
+  return userAgent;
+}
+
 export function resolveVerifiedClaude(): string {
   const candidates: string[] = [];
   try {

package/src/lib/codex.ts

@@ -8,12 +8,12 @@ import { codexIdentityOf, codexStoreUsable, deleteCodexStoreAuth, ensureCodexSto
 import { CodexInvalidGrantError, CodexRefreshFailedError, refreshCodexAuth } from "./codexoauth.ts";
 import { deletePiStore } from "./piauth.ts";
 import { PI_PRESENCE_PREFIX, livingPresences, seatCounts, writePresence } from "./presence.ts";
-import { CodexUsageReadError, codexLimitLabel, fetchCodexUsage } from "./codexusage.ts";
+import { CodexUsageReadError, codexLimitLabel, consumeCodexReset, fetchCodexUsage } from "./codexusage.ts";
 import { codexSupervisorLink, ensurePathInRc, installCodexSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
 import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { codexPaths, codexPool, codexSeatFromEnv, optionalEnv } from "./paths.ts";
-import { isExhausted, onCredits, pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
+import { isExhausted, landGrant, 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";
@@ -34,6 +34,7 @@ function applyUsage(account: Account, usage: CodexUsage, at: number): void {
   account.windows = usage.windows;
   account.lastUsageAt = at;
   account.hasCredits = usage.hasCredits ?? undefined;
+  landGrant(account, usage.bankedReset, at);
   if (usage.email != null) account.email = usage.email;
   if (usage.planType != null) account.tier = usage.planType;
 }
@@ -300,6 +301,10 @@ export const codex: Provider = {
   samplePool,
   mergeWindows: (next) => next,
   swap: prepareMove,
+  useBankedReset: async (a, signal) => {
+    const fresh = await freshCodexAuth(a, Date.now(), false);
+    return fresh.ok ? consumeCodexReset(fresh.auth, signal) : { reset: false, detail: fresh.reason };
+  },
   classifySwapError: (e) => (e instanceof CodexInvalidGrantError ? "dead-grant" : e instanceof StoreUnusableError ? "skip" : "fatal"),
   removeCredentials: async (a) => {
     deleteCodexStoreAuth(a.id);

package/src/lib/codexusage.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { http, safeErrorDetail } from "./http.ts";
-import { errorMessage } from "./log.ts";
+import { errorMessage, log } from "./log.ts";
 import { env } from "./paths.ts";
-import { EpochSecondsSchema, JsonTextSchema, type CodexAuthJson, type CodexUsage, type Window } from "./types.ts";
+import { EpochSecondsSchema, JsonTextSchema, type BankedReset, type CodexAuthJson, type CodexUsage, type Window } from "./types.ts";
 import { codexIdentityOf } from "./codexauth.ts";
+import type { ResetClaim } from "./provider.ts";
 import { familyTokens } from "./usage.ts";
 
 export const CODEX_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
@@ -33,6 +34,7 @@ const WireUsageSchema = z.looseObject({
   plan_type: z.string().nullish(),
   rate_limit: WireRateLimitSchema.nullish(),
   credits: z.looseObject({ has_credits: z.boolean().nullish() }).nullish(),
+  rate_limit_reset_credits: z.unknown().optional(),
   additional_rate_limits: z
     .array(z.looseObject({ limit_name: z.string(), rate_limit: WireRateLimitSchema.nullish() }))
     .nullish(),
@@ -53,18 +55,19 @@ function toWindows(rateLimit: z.infer<typeof WireRateLimitSchema> | null | undef
   return out;
 }
 
+function codexHeaders(auth: CodexAuthJson): Record<string, string> {
+  return {
+    Authorization: `Bearer ${auth.tokens.access_token}`,
+    "ChatGPT-Account-Id": codexIdentityOf({ auth }).accountId,
+    "User-Agent": "codex-cli",
+  };
+}
+
 export async function fetchCodexUsage(input: { auth: CodexAuthJson; at: number }): Promise<CodexUsage> {
   const { auth, at } = input;
-  const identity = codexIdentityOf({ auth });
   let res: Response;
   try {
-    res = await http.get(USAGE_URL, {
-      headers: {
-        Authorization: `Bearer ${auth.tokens.access_token}`,
-        "ChatGPT-Account-Id": identity.accountId,
-        "User-Agent": "codex-cli",
-      },
-    });
+    res = await http.get(USAGE_URL, { headers: codexHeaders(auth) });
   } catch (e) {
     throw new CodexUsageReadError(`endpoint unreachable: ${errorMessage(e)}`);
   }
@@ -83,6 +86,7 @@ export async function fetchCodexUsage(input: { auth: CodexAuthJson; at: number }
     email: wire.email ?? null,
     planType: wire.plan_type ?? null,
     hasCredits: wire.credits?.has_credits ?? null,
+    bankedReset: resetCredits(wire.rate_limit_reset_credits),
     windows: [
       ...toWindows(wire.rate_limit, null, at),
       ...(wire.additional_rate_limits ?? []).flatMap((row) => toWindows(row.rate_limit, row.limit_name, at)),
@@ -90,6 +94,33 @@ export async function fetchCodexUsage(input: { auth: CodexAuthJson; at: number }
   };
 }
 
+const ResetCreditsSchema = z.looseObject({ available_count: z.number() });
+
+function resetCredits(raw: unknown): BankedReset | undefined {
+  if (raw == null) return undefined;
+  const block = ResetCreditsSchema.safeParse(raw);
+  if (!block.success) {
+    log("codexusage.reset_credits_unreadable", { issue: z.prettifyError(block.error).slice(0, 200) });
+    return undefined;
+  }
+  return block.data.available_count > 0 ? { grant: null } : undefined;
+}
+
+const RESET_URL = env("TOKENMAXXING_CODEX_RESET_URL", "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume");
+const ConsumeResponseSchema = z.looseObject({ code: z.string() });
+
+export async function consumeCodexReset(auth: CodexAuthJson, signal: AbortSignal): Promise<ResetClaim> {
+  const res = await http.post(RESET_URL, {
+    headers: codexHeaders(auth),
+    json: { redeem_request_id: crypto.randomUUID() },
+    signal,
+  });
+  const text = await res.text();
+  if (!res.ok) return { reset: false, detail: `HTTP ${res.status}: ${safeErrorDetail({ text })}` };
+  const code = ConsumeResponseSchema.safeParse(JsonTextSchema.safeParse(text).data).data?.code;
+  return { reset: code === "reset", detail: code ?? "unreadable body" };
+}
+
 const LIMIT_LABEL_ABBREVIATIONS = new Map([["reserve", "rsrv"]]);
 
 export function codexLimitLabel(limitName: string): string {

package/src/lib/decide.ts

@@ -2,11 +2,11 @@ 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 { MAX_WAITERS_PER_ACCOUNT, isExhausted, landWindows, limitWindows, liveUsed, nextWeeklyReset, onCredits, pickBest, pickWaitTarget, screensUntilReset, sessionWindow, thresholdBars, weeklyWindow, type PickCtx } from "./picker.ts";
+import { MAX_WAITERS_PER_ACCOUNT, isExhausted, landWindows, limitWindows, liveUsed, nextWeeklyReset, onCredits, pickBest, pickWaitTarget, screensUntilReset, sessionWindow, thresholdBars, wantsBankedReset, weeklyWindow, type PickCtx } from "./picker.ts";
 import { familyTokens } from "./usage.ts";
 import { errorMessage, log } from "./log.ts";
-import type { Observation, Provider } from "./provider.ts";
-import type { Account, Bars, EnforcedLimit } from "./types.ts";
+import type { Observation, Provider, ResetClaim } from "./provider.ts";
+import type { Account, Bars, Config, EnforcedLimit } from "./types.ts";
 
 export type SwapDecision = { swapped: boolean; account: Account | null; reason: string; waitUntil?: number };
 
@@ -58,11 +58,58 @@ function enforcedWall(limit: EnforcedLimit, account: Account, now: number): numb
   return limit.resetsAt ?? cachedReset ?? now + (span === "session" ? FIVE_HOURS_MS : WEEK_MS);
 }
 
+async function foldLive(p: Provider, a: Account, cfg: Config, now: number, bars: Bars): Promise<Observation | null> {
+  const obs = await p.observeLive(a, cfg, now, { probe: false, perModel: false });
+  if (obs && (a.lastUsageAt == null || obs.at > a.lastUsageAt)) landWindows(a, p.mergeWindows(obs.windows, a.windows), obs.at, bars);
+  return obs;
+}
+
+const CLAIM_DEADLINE_MS = 25_000;
+const CLAIM_HOLD_MS = 60_000;
+
+export async function useBankedResets(p: Provider, cfg: Config, now: number): Promise<void> {
+  const bars = thresholdBars(cfg);
+  const wanted = async (accounts: Account[]): Promise<Account[]> => {
+    const held = accounts.filter((a) => a.bankedReset != null);
+    for (const a of held) await foldLive(p, a, cfg, now, bars);
+    return held.filter((a) => wantsBankedReset(a, bars, now));
+  };
+  if ((await wanted(loadAccounts(p.pool).accounts)).length === 0) return;
+  const due = await withLock(p.pool.lockFile, async () => {
+    const idx = loadAccounts(p.pool);
+    const picked = await wanted(idx.accounts);
+    const claims = picked.map((a) => ({ ...a }));
+    const until = Date.now() + CLAIM_HOLD_MS;
+    for (const a of picked) {
+      a.bankedReset = undefined;
+      a.bankedResetAt = until;
+    }
+    if (picked.length > 0) saveAccounts(p.pool, idx);
+    return claims;
+  });
+  const signal = AbortSignal.timeout(CLAIM_DEADLINE_MS);
+  await Promise.all(
+    due.map(async (a) => {
+      const claim = await p.useBankedReset(a, signal).catch((e: unknown): ResetClaim => ({ reset: false, detail: errorMessage(e) }));
+      log("decide.banked_reset", { account: a.id.slice(0, 8), reset: claim.reset, detail: claim.detail.slice(0, 200) });
+      if (!claim.reset) return;
+      await withLock(p.pool.lockFile, () => {
+        const idx = loadAccounts(p.pool);
+        const stored = idx.accounts.find((x) => x.id === a.id);
+        if (!stored) return;
+        landWindows(stored, p.mergeWindows([], stored.windows), Date.now(), bars);
+        saveAccounts(p.pool, idx);
+      });
+    }),
+  );
+}
+
 export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRespawn = false, enforced: EnforcedLimit | null = null, opts: EvalOpts = {}): Promise<SwapDecision> {
   const activeId = opts.seatId === undefined ? p.liveId() : opts.seatId;
   const waiterId = canRespawn ? opts.waiterId : undefined;
   const cfg = loadConfig();
   const bars = thresholdBars(cfg);
+  if (enforced == null) await useBankedResets(p, cfg, now);
   const stored0 = loadAccounts(p.pool).accounts.find((a) => a.id === activeId);
   const walled0 = stored0?.enforcedUntil != null && stored0.enforcedUntil > now;
   const gated = opts.sessionFamilies ?? p.gatedFamilies(cfg);
@@ -106,9 +153,8 @@ 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, perModel: false });
+      const obs = await foldLive(p, a, cfg, now, bars);
       if (a === active) obs2 = obs;
-      if (obs && (a.lastUsageAt == null || obs.at > a.lastUsageAt)) landWindows(a, p.mergeWindows(obs.windows, a.windows), obs.at, bars);
     }
     saveAccounts(p.pool, idx);
 

package/src/lib/picker.ts

@@ -1,6 +1,6 @@
 import { maxBy, minBy, sortBy } from "es-toolkit";
 import { familyTokens } from "./usage.ts";
-import type { Account, Bars, Config, Thresholds, Window } from "./types.ts";
+import type { Account, BankedReset, Bars, Config, Thresholds, Window } from "./types.ts";
 
 export function thresholdBars(cfg: Config): Bars {
   const bars = (t: Thresholds): Thresholds => ({ session: t.session - cfg.policy.projectionMargin, weekly: t.weekly });
@@ -114,6 +114,20 @@ export function weeklyExpiry(a: Account, now: number): number {
   return nextWeeklyReset(weeklyWindow(a)?.resetsAt ?? null, now) ?? Number.POSITIVE_INFINITY;
 }
 
+const BANKED_RESET_LEAD_MS = 3 * 24 * 60 * 60 * 1000;
+
+export function wantsBankedReset(a: Account, bars: Bars, now: number): boolean {
+  const weekly = weeklyWindow(a);
+  const left = weeklyExpiry(a, now) - now;
+  return a.bankedReset != null && weekly != null && liveUsed(weekly, now) >= barFor(a, weekly, bars, now) && Number.isFinite(left) && left > BANKED_RESET_LEAD_MS;
+}
+
+export function landGrant(a: Account, grant: BankedReset | undefined, sentAt: number): void {
+  if (sentAt <= (a.bankedResetAt ?? 0)) return;
+  a.bankedReset = grant;
+  a.bankedResetAt = sentAt;
+}
+
 export function earliestReset(a: Account, now: number): number {
   const session = sessionWindow(a)?.resetsAt;
   return Math.min(session != null && session > now ? session : Number.POSITIVE_INFINITY, weeklyExpiry(a, now));

package/src/lib/provider.ts

@@ -8,6 +8,8 @@ export type SampleReport = { ok: true; source: "statusline" | "probe" | "cached"
 
 export type SwapFailure = "dead-grant" | "skip" | "fatal";
 
+export type ResetClaim = { reset: boolean; detail: string };
+
 export type SeatBorrow = { store: string; id: string; reused: boolean } | { denied: string } | null;
 
 export class StoreUnusableError extends Error {
@@ -31,6 +33,7 @@ export type Provider = {
   samplePool(accounts: Account[], liveId: string | null, now: number): Promise<Map<string, SampleReport>>;
   mergeWindows(next: Window[], prev: Window[]): Window[];
   swap(target: Account): Promise<void>;
+  useBankedReset(account: Account, signal: AbortSignal): Promise<ResetClaim>;
   classifySwapError(e: unknown): SwapFailure;
   removeCredentials(account: Account): Promise<void>;
   storeUsable(account: Account): Promise<boolean>;

package/src/lib/sample.ts

@@ -7,7 +7,7 @@ import { withLock } from "./lock.ts";
 import { errorMessage, log } from "./log.ts";
 import { claudeTierLabel, isDeadCredential } from "./oauth.ts";
 import { claudePool, paths, storeDirFor } from "./paths.ts";
-import { barFor, gatedWindows, landWindows, liveUsed, thresholdBars } from "./picker.ts";
+import { barFor, gatedWindows, landGrant, landWindows, liveUsed, thresholdBars } from "./picker.ts";
 import { seatCounts } from "./presence.ts";
 import type { Observation } from "./provider.ts";
 import { loadAccounts, loadUsageSnapshot, saveAccounts } from "./state.ts";
@@ -60,6 +60,11 @@ export function teeObservation(account: Account): Observation | null {
   return { windows: mergeWindows(aggregate, account.windows), at };
 }
 
+export function landRead(account: Account, usage: UsageWindows, at: number, thresholds: Bars): void {
+  if (account.lastUsageAt == null || at > account.lastUsageAt) landWindows(account, mergeWindows(windowsOf(usage, at), account.windows), at, thresholds);
+  landGrant(account, usage.bankedReset, at);
+}
+
 export function foldTee(account: Account, thresholds: Bars): boolean {
   const observed = teeObservation(account);
   if (!observed || (account.lastUsageAt != null && observed.at <= account.lastUsageAt)) return false;
@@ -197,8 +202,8 @@ export async function sampleOldest(cfg: Config): Promise<void> {
           stored.usageRetryAt = outcome.retryAt;
           dirty = true;
         }
-        if (stored && outcome.ok && (stored.lastUsageAt == null || startedAt > stored.lastUsageAt)) {
-          landWindows(stored, mergeWindows(windowsOf(outcome.usage, startedAt), stored.windows), startedAt, thresholdBars(cfg));
+        if (stored && outcome.ok) {
+          landRead(stored, outcome.usage, startedAt, thresholdBars(cfg));
           dirty = true;
         }
         if (dirty) saveAccounts(claudePool, idx);

package/src/lib/statusonly.ts

@@ -110,6 +110,7 @@ export function statusOnlyProvider(spec: StatusOnlySpec): Provider {
     swap: async () => {
       throw new Error(`${spec.name} moves are not supported yet (status-only pool)`);
     },
+    useBankedReset: async () => ({ reset: false, detail: `${spec.name} has no banked reset` }),
     classifySwapError: () => "fatal",
     removeCredentials: async (a) => {
       rmSync(spec.storeDirFor(a.id), { recursive: true, force: true });

package/src/lib/types.ts

@@ -36,7 +36,10 @@ const AggregateWindowsSchema = z.object({
   sevenDay: UsageWindowSchema,
 });
 
-export type UsageWindows = z.infer<typeof AggregateWindowsSchema> & { perModel: Record<string, UsageWindow> };
+export const BankedResetSchema = z.object({ grant: z.string().nullable() });
+export type BankedReset = z.infer<typeof BankedResetSchema>;
+
+export type UsageWindows = z.infer<typeof AggregateWindowsSchema> & { perModel: Record<string, UsageWindow>; bankedReset?: BankedReset };
 
 export const WindowSchema = z.object({
   name: z.string().nullable(),
@@ -73,6 +76,8 @@ export const AccountSchema = z.object({
   enforcedUntil: z.number().optional(),
   needsReauth: z.boolean().optional(),
   hasCredits: z.boolean().optional(),
+  bankedReset: BankedResetSchema.optional(),
+  bankedResetAt: z.number().optional(),
   oauthAccount: OAuthAccountSchema.optional(),
 });
 export type Account = z.infer<typeof AccountSchema>;
@@ -252,6 +257,7 @@ export type CodexUsage = {
   email: string | null;
   planType: string | null;
   hasCredits: boolean | null;
+  bankedReset: BankedReset | undefined;
   windows: Window[];
 };
 

package/src/lib/usage.ts

@@ -1,9 +1,11 @@
 import { omit } from "es-toolkit";
 import { z } from "zod";
-import { http } from "./http.ts";
+import { claudeUserAgent } from "./claudebin.ts";
+import { http, safeErrorDetail } from "./http.ts";
 import { errorMessage, log } from "./log.ts";
 import { env } from "./paths.ts";
-import { EpochSecondsSchema, InstantSchema, JsonTextSchema, RateLimitsStdinSchema, type ModelInfo, type UsageWindow, type UsageWindows, type Window } from "./types.ts";
+import type { ResetClaim } from "./provider.ts";
+import { EpochSecondsSchema, InstantSchema, JsonTextSchema, RateLimitsStdinSchema, type BankedReset, type ModelInfo, type UsageWindow, type UsageWindows, type Window } from "./types.ts";
 
 const win = (w: { used_percentage: number; resets_at?: number | null }): UsageWindow => ({
   usedPercentage: w.used_percentage,
@@ -198,12 +200,32 @@ const UsageScopedLimitSchema = z.looseObject({
   resets_at: ResetsAtSchema,
   scope: z.looseObject({ model: z.looseObject({ display_name: z.string() }) }),
 });
+const ResetGrantSchema = z.looseObject({ id: z.string(), resets_left: z.number(), clears: z.array(z.string()), paused: z.boolean(), usable_now: z.boolean() });
+const CedarEmberSchema = z.looseObject({ next_grant_id: z.string().nullish(), grants: z.array(z.looseObject({ id: z.string() })) });
 const UsageResponseSchema = z.looseObject({
   five_hour: UsageLimitSchema.nullish(),
   seven_day: UsageLimitSchema.nullish(),
   limits: z.array(z.unknown()).nullish(),
+  cedar_ember: z.unknown().optional(),
 });
 
+function unreadableGrant(error: z.ZodError): undefined {
+  log("usage.cedar_ember_unreadable", { issue: z.prettifyError(error).slice(0, 200) });
+  return undefined;
+}
+
+function weeklyGrant(raw: unknown): BankedReset | undefined {
+  if (raw == null) return undefined;
+  const block = CedarEmberSchema.safeParse(raw);
+  if (!block.success) return unreadableGrant(block.error);
+  const named = block.data.grants.find((g) => g.id === block.data.next_grant_id);
+  if (named == null) return undefined;
+  const next = ResetGrantSchema.safeParse(named);
+  if (!next.success) return unreadableGrant(next.error);
+  const g = next.data;
+  return g.usable_now && !g.paused && g.resets_left > 0 && g.clears.includes("seven_day") ? { grant: g.id } : undefined;
+}
+
 function scopedRows(limits: unknown[]): Record<string, UsageWindow> {
   const perModel: Record<string, UsageWindow> = {};
   for (const raw of limits) {
@@ -223,7 +245,7 @@ export async function fetchUsageDirect(accessToken: string): Promise<UsageRead>
   try {
     res = await http.get(USAGE_URL, {
       searchParams: { at_wall: 1, skip_spend: 1 },
-      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+      headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json", "User-Agent": claudeUserAgent() },
       signal: AbortSignal.timeout(USAGE_DEADLINE_MS),
     });
   } catch (e) {
@@ -241,5 +263,23 @@ export async function fetchUsageDirect(accessToken: string): Promise<UsageRead>
     return { ok: false, retryAt: null };
   }
   const win = (w: z.infer<typeof UsageLimitSchema>): UsageWindow => ({ usedPercentage: w.utilization, resetsAt: w.resets_at ?? null });
-  return { ok: true, usage: { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []) } };
+  return {
+    ok: true,
+    usage: { fiveHour: win(parsed.data.five_hour), sevenDay: win(parsed.data.seven_day), perModel: scopedRows(parsed.data.limits ?? []), bankedReset: weeklyGrant(parsed.data.cedar_ember) },
+  };
+}
+
+const ClaimResponseSchema = z.looseObject({ result: z.string(), reason: z.string().nullish() });
+
+export async function claimResetGrant(input: { accessToken: string; organizationUuid: string; grant: string }, signal: AbortSignal): Promise<ResetClaim> {
+  const res = await http.post(new URL(`/api/organizations/${input.organizationUuid}/reset_rate_limits`, USAGE_URL), {
+    headers: { Authorization: `Bearer ${input.accessToken}`, "anthropic-beta": "oauth-2025-04-20", "User-Agent": claudeUserAgent() },
+    json: { program: "cedar_ember", grant_id: input.grant, request_id: crypto.randomUUID() },
+    signal,
+  });
+  const text = await res.text();
+  if (!res.ok) return { reset: false, detail: `HTTP ${res.status}: ${safeErrorDetail({ text })}` };
+  const claim = ClaimResponseSchema.safeParse(JsonTextSchema.safeParse(text).data).data;
+  if (claim == null) return { reset: false, detail: "unreadable body" };
+  return { reset: claim.result === "reset", detail: claim.reason != null ? `${claim.result}: ${claim.reason}` : claim.result };
 }