tokenmaxxing 0.6.2 → 0.7.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 (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).
+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, furthest behind its own weekly pace first: highest remaining% / time-to-weekly-reset, since unused allowance is forfeited at the fixed per-account reset; tiebreak soonest expiry then lowest 7-day usage), 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.6.2",
+  "version": "0.7.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/cli/switch.ts

@@ -1,6 +1,7 @@
 // `tokenmaxxing switch [selector]`.
-// No selector → greedy: rank EVERY account (current included) by soonest weekly
-// expiry among those with session/week under threshold, off the cached windows.
+// No selector → greedy: rank EVERY account (current included) by pace pressure
+// (furthest behind its own weekly pace first, see picker.ts) among those with
+// session/week under threshold, off the cached windows.
 // When the current account already wins (or ties - swapping between equals buys
 // nothing), do nothing: the command is idempotent, so running it periodically
 // converges on the right account. With a selector → switch to that one. Runs

package/src/lib/picker.ts

@@ -1,11 +1,14 @@
 // Choose the account to switch TO. Greedy policy: among usable accounts (no
-// reauth, no window >= threshold that hasn't reset yet), take the one 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. Runs entirely off each
-// account's cached windows (absolute UTC epochs, so a stale snapshot still
-// resolves to the correct upcoming reset), which makes the pick deterministic
-// and idempotent: re-running lands on the same account.
+// reauth, no window >= threshold that hasn't reset yet), take the one furthest
+// behind its own weekly pace - highest pacePressure, the burn rate its
+// remaining weekly quota demands to be consumed at before the fixed
+// per-account reset forfeits it (weekly allowance is use-it-or-lose-it).
+// This refines the older soonest-expiry policy in both directions: equal
+// remaining reduces to soonest expiry first, equal expiry to most remaining
+// first. Runs entirely off each account's cached windows (absolute UTC
+// epochs, so a stale snapshot still resolves to the correct upcoming reset),
+// which makes the pick deterministic and idempotent: re-running lands on the
+// same account.
 
 import { minBy, sortBy } from "es-toolkit";
 import { z } from "zod";
@@ -75,10 +78,28 @@ export function weeklyExpiry(a: Account, now: number): number {
   return nextWeeklyReset(a.lastUsage?.sevenDay.resetsAt ?? null, now) ?? Number.POSITIVE_INFINITY;
 }
 
-/** The switch preference: soonest weekly expiry first, tiebreak lowest 7-day
- *  usage. Shared with the statusLine pool ordering so the display order IS the
+/** How far behind its own weekly pace the account is, measured forward: the
+ *  burn rate (percent per ms) its remaining weekly quota must be consumed at
+ *  to beat the reset that forfeits it. A backward-looking used/expected ratio
+ *  blows up right after a reset (expected ~0) and ignores how much quota is
+ *  at risk; the required forward rate has neither problem. A window past its
+ *  cached reset counts as empty (the account is fresh again); an account with
+ *  no sampled reset anchor has nothing to forfeit on any known clock and
+ *  ranks last (0). */
+export function pacePressure(a: Account, now: number): number {
+  const cached = a.lastUsage?.sevenDay;
+  const reset = nextWeeklyReset(cached?.resetsAt ?? null, now);
+  if (cached == null || reset == null) return 0;
+  const used = cached.resetsAt != null && cached.resetsAt <= now ? 0 : cached.usedPercentage;
+  return Math.max(0, 100 - used) / Math.max(1, reset - now);
+}
+
+/** The switch preference: furthest behind its own weekly pace first (highest
+ *  pacePressure), tiebreak soonest weekly expiry then lowest 7-day usage.
+ *  Shared with the statusLine pool ordering so the display order IS the
  *  swap order. */
 export const swapPreference = (now: number) => [
+  (a: Account) => -pacePressure(a, now),
   (a: Account) => weeklyExpiry(a, now),
   (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
 ];