tokenmaxxing 0.2.1 → 0.3.1

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.1",
   "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]!;

package/src/lib/usage.ts

@@ -86,12 +86,16 @@ function zonedWallToEpoch(y: number, mon: number, day: number, hour: number, min
 
 /**
  * Parse a `/usage` reset clock like `Jul 11 at 12pm (Asia/Seoul)` or
- * `Jul 9 at 11:20pm (Asia/Seoul)` to epoch ms. The text carries no year, so we
- * pick the year whose resulting instant is nearest `now` (resets are always days
- * away, so the correct year wins by ~360 days). Returns null if unparseable.
+ * `Jul 10, 3:30pm (Asia/Seoul)` to epoch ms. The day-time glue is not stable
+ * across claude installs (observed on 2.1.206: ` at ` on macOS, `, ` on Linux);
+ * exactly those two glues are accepted, same-line only, so a third drift shows
+ * up as an unparsed clock (and the usage.reset_clock_unparsed log) instead of a
+ * guessed instant. The text carries no year, so we pick the year whose resulting
+ * instant is nearest `now` (resets are always days away, so the correct year
+ * wins by ~360 days). Returns null if unparseable.
  */
 export function parseResetClock(clock: string, now = Date.now()): number | null {
-  const m = clock.match(/\b([A-Za-z]{3,9})\s+(\d{1,2})\s+at\s+(\d{1,2})(?::(\d{2}))?\s*([ap])m\s*\(([^)]+)\)/i);
+  const m = clock.match(/\b([A-Za-z]{3,9})\s+(\d{1,2})(?:[^\S\n]+at[^\S\n]+|,[^\S\n]*)(\d{1,2})(?::(\d{2}))?\s*([ap])m\s*\(([^)]+)\)/i);
   if (!m) return null;
   const mon = MONTHS[m[1]!.slice(0, 3).toLowerCase()];
   if (mon === undefined) return null;
@@ -123,11 +127,15 @@ export function parseResetClock(clock: string, now = Date.now()): number | null
  */
 export function parseUsageTextFull(text: string, now = Date.now()): FullUsage | null {
   if (!text) return null;
-  // The reset clock is required in full (month day at h[:mm]am/pm (tz)) inside its
-  // optional group, so the lazy bridge is forced to find it when present yet the
-  // group cleanly skips a line that has no clock - and it never swallows a
-  // following "Current …" entry on a single line.
-  const re = /current (session|week \(([^)]+)\)):\s*(\d+)\s*%(?:[^\n]*?\bresets\s+([A-Z][a-z]{2,8}\s+\d{1,2}\s+at\s+\d{1,2}(?::\d{2})?\s*[ap]m\s*\([^)]+\)))?/gi;
+  // The reset clock is required in full (month day[, | at ]h[:mm]am/pm (tz))
+  // inside its optional group, so the lazy bridge is forced to find it when
+  // present yet the group cleanly skips a line that has no clock. The bridge
+  // refuses to cross another "Current" so a dateless clock ("resets Jul 8.")
+  // can never steal the NEXT entry's clock or swallow that entry. The day-time
+  // glue is not stable across installs (observed on 2.1.206: ` at ` on macOS,
+  // `, ` on Linux); exactly those two are accepted, same-line only, so a third
+  // drift surfaces in the usage.reset_clock_unparsed log instead of misparsing.
+  const re = /current (session|week \(([^)]+)\)):\s*(\d+)\s*%(?:(?:(?!current)[^\n])*?\bresets\s+([A-Z][a-z]{2,8}\s+\d{1,2}(?:[^\S\n]+at[^\S\n]+|,[^\S\n]*)\d{1,2}(?::\d{2})?\s*[ap]m\s*\([^)]+\)))?/gi;
   let session: UsageWindow | null = null;
   let weekAll: UsageWindow | null = null;
   const perModel: Record<string, UsageWindow> = {};
@@ -190,8 +198,18 @@ async function probeUsageOnce(env: Record<string, string>, now: number): Promise
   }
 
   const j = z.object({ result: z.string() }).safeParse((() => { try { return JSON.parse(out); } catch { return null; } })());
-  const full = parseUsageTextFull(j.success ? j.data.result : out, now);
-  if (!full) log("usage.probe_unparsed", { sample: out.trim().slice(0, 120) });
+  const text = j.success ? j.data.result : out;
+  const full = parseUsageTextFull(text, now);
+  if (!full) {
+    log("usage.probe_unparsed", { sample: text.trim().slice(0, 200) });
+  } else {
+    const clockLine = text.split("\n").find((l) => /^current /i.test(l) && /\bresets\b/i.test(l));
+    if (clockLine && [full.session, full.weekAll, ...Object.values(full.perModel)].every((w) => w.resetsAt === null)) {
+      // Percentages parsed but every reset clock was dropped: the clock format
+      // drifted again. Log the line so the next drift is visible in the log.
+      log("usage.reset_clock_unparsed", { sample: clockLine.slice(0, 120) });
+    }
+  }
   return full;
 }