tokenmaxxing 1.123.0 → 1.125.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.123.0",
+  "version": "1.125.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",
@@ -33,7 +33,6 @@
   },
   "devDependencies": {
     "@types/bun": "1.3.14",
-    "lefthook": "^2.1.14",
     "typescript": "^5.6.0"
   },
   "dependencies": {

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/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 };
 }