tokenmaxxing 1.2.1 → 1.3.0

package/DESIGN.md

@@ -79,9 +79,11 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 ---
 
 ## 5. Rotation policy
-The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from there it greedily converges on the usable account furthest behind its weekly pace, staying put whenever the current account wins or ties. The hard bars - `five_hour >= 95%` OR `seven_day >= 98%`, per org - always force a switch and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - policy.projectionMargin`, a fixed configured margin) so a single large turn is less likely to blow past 100% before the next Stop hook.
+The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from there it greedily converges on the usable account furthest behind its weekly pace, staying put whenever the current account wins or ties. The **Layer 1 screening bars** - `five_hour >= 95%` OR `seven_day >= 98%`, per org (`thresholds`) - force a switch onto a fresher account and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - policy.projectionMargin`, a fixed configured margin) so a single large turn is less likely to blow past 100% before the next Stop hook.
 
-**Model-aware trigger.** Claude subscriptions also enforce **per-model weekly caps** - currently only for Sonnet and Fable (there is no Opus-only quota), and Fable's tighter limit binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the active model is in `policy.switchModels` we read it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session switches on the Fable cap; a Sonnet session rides the aggregate.
+**Two layers - pump the last drops.** The screening bars deliberately leave headroom, so when *every* account is over them Layer 1 alone would park the pool with 2-5% of each account's quota still unspent. **Layer 2 - the wall bars** (`hardThresholds`, default `100/100`, the server's own limit) - is the fallback reached only at that point: the session **holds its seat and squeezes** while it is under the wall, else swaps onto the best still-under-wall account (the same pace-pressure ranking as every other swap - squeeze the account whose weekly quota is most about to be forfeited first), and only parks (depleted-wait) once every account has truly walled. Recovery is then measured against the wall, not the screening bar, so an account whose 5h window drops below 100 is squeezable again even while its weekly window still sits above the Layer 1 bar. The wall reading is the statusLine's own `rate_limits` feed - the same server-side figure claude's `/rate-limit-options` renders - so when an account genuinely maxes out the tee shows 100 and Layer 2 moves on; a single-turn overshoot is caught one boundary later (the periodic `check` timer, or the next Stop hook) without needing to sniff assistant text. The serve/SDK path additionally stamps an account walled the instant an *errored* turn result reports a limit (`recordObservedLimit`, gated on `is_error`), because it has no statusLine tee. Set `hardThresholds` equal to `thresholds` to disable Layer 2. **Layer 2 is Claude-only:** a swap on Claude is a hot, in-place credential adoption every concurrent session follows automatically, whereas a running Codex refuses another account's credential (restart is the switch), so a last-drop-swap there would strand any sibling still on the walled account - Codex instead keeps riding its current account to the wall (its existing all-exhausted stay-put already squeezes it).
+
+**Model-aware trigger.** Claude subscriptions also enforce **per-model weekly caps** - currently only for Sonnet and Fable (there is no Opus-only quota), and Fable's tighter limit binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the active model is in `policy.switchModels` we read it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session switches on the Fable cap; a Sonnet session rides the aggregate. Both layers apply the per-model gate: a burnt Fable cap screens an account out of a Layer 1 switch, and a Fable cap at the wall screens it out of the Layer 2 squeeze too.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.2.1",
+  "version": "1.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/cli/config.ts

@@ -20,6 +20,8 @@ import { c } from "./render.ts";
 export const KNOWN_KEYS = [
   "thresholds.session",
   "thresholds.weekly",
+  "hardThresholds.session",
+  "hardThresholds.weekly",
   "claudeBin",
   "codexBin",
   "policy.projectionMargin",

package/src/cli/switch.ts

@@ -113,7 +113,9 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     // No usable target swapped in: everything is depleted, or the remaining
     // candidates' refresh tokens just died (performSwap persists needs-reauth
     // before throwing, hence the reload). Stay on / switch to whichever
-    // recovers soonest.
+    // recovers soonest. (Layer 2 - the wall squeeze - is deliberately confined
+    // to the automatic decision path in decide.ts, which decides off the live
+    // statusLine tee; bare `xx switch` stays cache-only and simply parks here.)
     const fresh = loadAccounts();
     const earliest = pickEarliestReset(fresh.accounts, everyone);
     if (!earliest) {

package/src/lib/codexdecide.ts

@@ -260,7 +260,13 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
 
     // Hard path: a bar is crossed. Land on the best usable candidate, walking
     // past dead grants; a fully depleted pool stays put (no pre-park: nothing
-    // can pause a codex session for a countdown yet).
+    // can pause a codex session for a countdown yet). Layer 2 (the wall) is
+    // deliberately claude-only: a running codex cannot hot-adopt a swapped
+    // credential (restart IS the switch), so a last-drop-swap onto a still-
+    // under-wall account would strand any concurrent sibling on the departed
+    // account (the reconcile can only signal siblings onto a Layer-1-usable
+    // seat), and a hold-only Layer 2 is identical to codex already staying put
+    // here - so codex just rides the current account to its wall.
     const tried = new Set<string>();
     while (true) {
       const current = loadCodexAccounts();

package/src/lib/decide.ts

@@ -30,7 +30,7 @@ import { paths } from "./paths.ts";
 import { loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadModelUsage, saveAccounts, saveDepletedWait, saveModelUsage, usageTeeAt, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { chooseAndSwap, performSwap } from "./swap.ts";
-import { currentWins, effectiveBars, pickBest, pickEarliestReset, usableAt } from "./picker.ts";
+import { currentWins, effectiveBars, hardBars, isExhausted, pickBest, pickEarliestReset, usableAt } from "./picker.ts";
 import { InvalidGrantError } from "./oauth.ts";
 import { familyTokens, gatedFamilies, probeUsage } from "./usage.ts";
 import { log } from "./log.ts";
@@ -307,15 +307,44 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
     const landed = await chooseAndSwap({ now, thresholds: effectiveBars(cfg), switchFamilies, currentAccountUuid: seatOf(loadAccounts())?.accountUuid ?? null });
     if (landed) return { swapped: true, account: landed, reason: "swapped" };
 
-    // Every account is depleted. Wait for whichever recovers soonest (including
-    // the current one), if that reset is within the auto-wait window. A dead
-    // grant on the chosen pre-park target must not abort the wait: performSwap
-    // persists needs-reauth before throwing, so each retry re-ranks without the
-    // dead account and the loop terminates (mirrors the greedy loop above).
+    // ── LAYER 2 (the wall). Every account is exhausted at the Layer 1
+    // screening bars, so Layer 1 alone would park the pool right here with
+    // quota still unspent on every account. Before parking, pump the last drops
+    // against the hard wall bars (default the server's own 100% limit, the same
+    // figure /rate-limit-options reads): hold the seat while it is still under
+    // its wall, else move onto the best still-under-wall account (chooseAndSwap
+    // keeps the usual pace-pressure ranking - squeeze the account whose weekly
+    // quota is most about to be forfeited first). Only when EVERY account has
+    // truly walled do we fall through to the depleted-wait park below. The wall
+    // reading is the statusLine's authoritative rate_limits tee (the same data
+    // /rate-limit-options renders); a single-turn overshoot is caught one
+    // boundary later by the check timer or the next Stop hook, and the serve/SDK
+    // path additionally stamps observed limits on errored results.
+    const hardCtx = { now, thresholds: hardBars(cfg), currentAccountUuid: null, switchFamilies };
+    const seat = seatOf(loadAccounts());
+    if (seat && !seat.needsReauth && !isExhausted(seat, hardCtx)) {
+      log("decide.last_drop_hold", { account: seat.accountUuid.slice(0, 8) });
+      return { swapped: false, account: null, reason: "last-drop-hold" };
+    }
+    const squeezed = await chooseAndSwap({ ...hardCtx, currentAccountUuid: seat?.accountUuid ?? null });
+    if (squeezed) {
+      log("decide.last_drop_swap", { account: squeezed.accountUuid.slice(0, 8) });
+      return { swapped: true, account: squeezed, reason: "last-drop-swap" };
+    }
+
+    // Every account is walled. Wait for whichever drops below its wall soonest
+    // (including the current one), if that reset is within the auto-wait window.
+    // Recovery is measured against the WALL, not the screening bars: an account
+    // whose session window resets below 100 is squeezable again even while its
+    // weekly window still sits above the Layer 1 bar, so waiting on the Layer 1
+    // reset would over-park. A dead grant on the chosen pre-park target must not
+    // abort the wait: performSwap persists needs-reauth before throwing, so each
+    // retry re-ranks without the dead account and the loop terminates (mirrors
+    // the greedy loop above).
     while (true) {
       const fresh = loadAccounts();
       const current = seatOf(fresh);
-      const ctx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: current?.accountUuid ?? null, switchFamilies };
+      const ctx = { now, thresholds: hardBars(cfg), currentAccountUuid: current?.accountUuid ?? null, switchFamilies };
       const currentAt = current ? usableAt(current, ctx) : Number.POSITIVE_INFINITY;
       const other = pickEarliestReset(fresh.accounts, ctx);
 

package/src/lib/picker.ts

@@ -27,6 +27,23 @@ export function effectiveBars(cfg: Config): Thresholds {
   };
 }
 
+/** LAYER 2 - the wall bars. The projection margin is subtracted the SAME way
+ *  effectiveBars does it, for two reasons: (1) it keeps the documented disable
+ *  contract honest - `hardThresholds == thresholds` then yields hardBars ==
+ *  effectiveBars, so Layer 2 has no band to act in and is truly off (without
+ *  the margin here a nonzero margin left a live band between the two, review
+ *  catch PR #47); (2) at the default margin 0 the wall is still the literal 100
+ *  (the server's own figure /rate-limit-options reads). Used only in the
+ *  all-Layer-1-exhausted fallback, where an account under its wall is still
+ *  worth squeezing. Config's refine (hardThresholds >= thresholds) guarantees
+ *  hardBars >= effectiveBars, so Layer 2 is never stricter than Layer 1. */
+export function hardBars(cfg: Config): Thresholds {
+  return {
+    session: cfg.hardThresholds.session - cfg.policy.projectionMargin,
+    weekly: cfg.hardThresholds.weekly - cfg.policy.projectionMargin,
+  };
+}
+
 const PickCtxSchema = z.object({
   now: z.number(),
   thresholds: ThresholdsSchema,

package/src/lib/state.ts

@@ -20,9 +20,14 @@ import {
 // ---- config.json (minimal, fixed schema) ---------------------------------
 
 const DEFAULT_CONFIG: Config = {
-  // Screening bars, split per window (user 2026-07-16): a session reset is
-  // cheap to sit out, weekly quota is use-it-or-lose-it so it drains to 98.
+  // LAYER 1 - screening bars, split per window (user 2026-07-16): a session
+  // reset is cheap to sit out, weekly quota is use-it-or-lose-it so it drains
+  // to 98. These drive normal account-to-account switching with headroom.
   thresholds: { session: 95, weekly: 98 },
+  // LAYER 2 - the wall bars (default the server's own 100% limit). Reached only
+  // once every account is over its Layer 1 bar: from there a session pumps the
+  // last drops up to the wall instead of parking with quota unspent.
+  hardThresholds: { session: 100, weekly: 100 },
   claudeBin: "",
   codexBin: "",
   // per-model weekly caps exist only for Sonnet and Fable (no Opus-only quota,
@@ -42,6 +47,7 @@ const PercentSchema = z.number().min(0).max(100);
 export const ConfigFileSchema = z
   .object({
     thresholds: z.object({ session: PercentSchema, weekly: PercentSchema }).partial(),
+    hardThresholds: z.object({ session: PercentSchema, weekly: PercentSchema }).partial(),
     claudeBin: z.string(),
     codexBin: z.string(),
     policy: z
@@ -69,9 +75,16 @@ export type MergeOutcome = z.infer<typeof MergeOutcomeSchema>;
  *  throw, silently disabling status/switch/hooks/statusline until the file is
  *  hand-repaired (closing-review catch). */
 export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutcome {
-  const cfg: Config = { ...DEFAULT_CONFIG, thresholds: { ...DEFAULT_CONFIG.thresholds }, policy: { ...DEFAULT_CONFIG.policy } };
+  const cfg: Config = {
+    ...DEFAULT_CONFIG,
+    thresholds: { ...DEFAULT_CONFIG.thresholds },
+    hardThresholds: { ...DEFAULT_CONFIG.hardThresholds },
+    policy: { ...DEFAULT_CONFIG.policy },
+  };
   cfg.thresholds.session = p.thresholds?.session ?? cfg.thresholds.session;
   cfg.thresholds.weekly = p.thresholds?.weekly ?? cfg.thresholds.weekly;
+  cfg.hardThresholds.session = p.hardThresholds?.session ?? cfg.hardThresholds.session;
+  cfg.hardThresholds.weekly = p.hardThresholds?.weekly ?? cfg.hardThresholds.weekly;
   cfg.claudeBin = p.claudeBin ?? cfg.claudeBin;
   cfg.codexBin = p.codexBin ?? cfg.codexBin;
   cfg.policy.projectionMargin = p.policy?.projectionMargin ?? cfg.policy.projectionMargin;

package/src/lib/types.ts

@@ -142,6 +142,18 @@ export type Thresholds = z.infer<typeof ThresholdsSchema>;
 export const ConfigSchema = z
   .object({
     thresholds: ThresholdsSchema,
+    /** LAYER 2 - the wall bars. `thresholds` (Layer 1) screen normal
+     *  account-to-account switching and deliberately leave headroom; these are
+     *  the true-wall bars the decision falls back to ONLY once every account is
+     *  exhausted at Layer 1. Below the wall a session holds its seat and pumps
+     *  the last drops; a window at/over the wall (default 100 = the server's own
+     *  limit, the same figure /rate-limit-options reads) is genuinely spent and
+     *  the pool moves to the next account, parking only when all are walled.
+     *  Set equal to `thresholds` to disable Layer 2 (hardBars subtracts the same
+     *  projectionMargin as effectiveBars, so equal thresholds collapse to one
+     *  effective bar and Layer 2 has no band to act in). At the default margin 0
+     *  the wall is the literal 100. */
+    hardThresholds: ThresholdsSchema,
     claudeBin: z.string(),
     /** the real codex binary (empty = resolve from PATH); pinned by `init --codex`. */
     codexBin: z.string(),
@@ -168,6 +180,14 @@ export const ConfigSchema = z
   // switch path churns. Per-field bounds alone cannot see this.
   .refine((cfg) => cfg.policy.projectionMargin < Math.min(cfg.thresholds.session, cfg.thresholds.weekly), {
     message: "policy.projectionMargin must be strictly below both thresholds (effectiveBars would hit zero and every account would read as exhausted)",
+  })
+  // The wall must sit at or above each screening bar. A wall BELOW its
+  // screening bar would make Layer 2 "usable" a stricter test than Layer 1
+  // screening - the pool could reach the wall fallback and find every account
+  // already over the (lower) wall, parking earlier than Layer 1 alone would.
+  // Equal is allowed and simply disables Layer 2 for that window.
+  .refine((cfg) => cfg.hardThresholds.session >= cfg.thresholds.session && cfg.hardThresholds.weekly >= cfg.thresholds.weekly, {
+    message: "hardThresholds (the Layer 2 wall) must be at or above thresholds (the Layer 1 screening bars) for both windows",
   });
 export type Config = z.infer<typeof ConfigSchema>;