tokenmaxxing 0.2.1 → 0.3.0

package/DESIGN.md

@@ -48,7 +48,7 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
 1. Read `usage.json`; `exit 0` fast if both windows `< 95%` (metered per `organizationUuid`).
-2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (lowest 7-day, not rate-limited, soonest `resets_at` tiebreak), and **swap the credential** (§3.4).
+2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (not rate-limited, soonest-expiring weekly window first since unused allowance is forfeited at the fixed per-account reset, lowest 7-day usage tiebreak), and **swap the credential** (§3.4).
 3. Write `respawn/<session_id>` (atomic temp+rename) and `SIGTERM` the parent `claude` (`kill -TERM $PPID`). The turn is already committed, so this is a clean stop.
 
 ### 3.3 Respawn (supervisor)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",

package/src/lib/picker.ts

@@ -1,7 +1,10 @@
 // Choose the best account to switch TO when the active one crosses threshold.
 // Policy: exclude the current account and any that need reauth or are still
 // rate-limited (usage >= threshold and not yet past resets_at). Among the rest,
-// prefer lowest 7-day usage; tiebreak on soonest resets_at.
+// prefer the account whose weekly window expires soonest: weekly limits reset
+// at a fixed per-account time and unused allowance is forfeited at reset, so
+// quota nearest its reset is use-it-or-lose-it and should be drained first.
+// Tiebreak on lowest 7-day usage, then soonest 5h reset.
 
 import { minBy, sortBy } from "es-toolkit";
 import { z } from "zod";
@@ -23,6 +26,18 @@ export function isExhausted(a: Account, ctx: PickCtx): boolean {
   return blocked(u.fiveHour) || blocked(u.sevenDay);
 }
 
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Epoch ms when the account's weekly quota is next forfeited. The weekly reset
+ *  is a fixed per-account anchor, so a stale (past) resetsAt extrapolates
+ *  forward in 7-day steps; an account with no sampled reset sorts last. */
+export function weeklyExpiry(a: Account, now: number): number {
+  const r = a.lastUsage?.sevenDay.resetsAt;
+  if (r == null) return Number.POSITIVE_INFINITY;
+  if (r > now) return r;
+  return r + (Math.floor((now - r) / WEEK_MS) + 1) * WEEK_MS;
+}
+
 export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   const candidates = accounts.filter(
     (a) =>
@@ -32,8 +47,9 @@ export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   );
   if (candidates.length === 0) return null;
 
-  // lowest 7-day usage first; tiebreak on soonest 5h reset.
+  // soonest weekly expiry first; tiebreak lowest 7-day usage, then soonest 5h reset.
   return sortBy(candidates, [
+    (a) => weeklyExpiry(a, ctx.now),
     (a) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
     (a) => a.lastUsage?.fiveHour.resetsAt ?? Number.POSITIVE_INFINITY,
   ])[0]!;