tokenmaxxing 0.9.0 → 0.10.0

package/DESIGN.md

@@ -1,6 +1,6 @@
 # tokenmaxxing - design
 
-Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses **98%** usage, tokenmaxxing swaps to a fresh account and - at the next safe turn boundary - **restarts your session resumed on it, automatically**. Works across many concurrent sessions at once.
+Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (**95%** of the 5h session window, **98%** of a weekly window), tokenmaxxing swaps to a fresh account and - at the next safe turn boundary - **restarts your session resumed on it, automatically**. Works across many concurrent sessions at once.
 
 > Scope: **Claude Code only, macOS first.** Codex and other CLIs deferred (see `.memory/cc-codex-auth-mechanics.md`).
 >
@@ -10,9 +10,9 @@ Automatic Claude Code account switching. You run `claude` exactly as always; whe
 
 ## 1. Why there is a thin supervisor (and why that's the whole trick)
 
-A **running** `claude` cannot adopt a swapped credential mid-flight - binary-verified: it holds its OAuth token in memory and a 429 (the limit event) does **not** invalidate it, so it never re-reads the keychain on the event we care about. A keychain swap is only picked up by a **fresh** `claude` process.
+A **running** `claude` DOES adopt an externally swapped credential (verified live 2026-07-10, correcting this document's original claim): an ensure-fresh poll re-reads the credential store around every request, so a swap lands within ~30s on macOS (raw keychain cache) and on the next request on Linux. What a swap alone cannot give you is a *clean cutover*: a mid-flight 429 retry keeps its already-snapshotted token, and an account already at the wall still needs the session paused until something resets.
 
-The clean way to exploit that is not to fight the live process but to **replace it at a salvageable moment**: after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt - killing it there loses nothing, and a `claude --resume <session-id>` comes back cold on the new account and continues exactly where it left off. **This is why we swap at 98%: the 2% headroom is the budget to reach a clean turn boundary and respawn before the account actually hits the wall.**
+So the supervisor's job is to **replace the process at a salvageable moment**: after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt - killing it there loses nothing, and a `claude --resume <session-id>` comes back cold on the new account and continues exactly where it left off. **This is why we swap below 100%: the headroom is the budget to reach a clean turn boundary and respawn before the account actually hits the wall.** The session window swaps at 95 (a 5h reset is cheap to sit out) while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
 
 A hook can't do the respawn - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
 
@@ -47,7 +47,7 @@ No background daemon - it's event-driven (statusline pushes usage; hooks + super
 The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limits.{five_hour,seven_day}.{used_percentage,resets_at}`, after every turn, 300ms debounce, zero cost). tokenmaxxing's statusLine shim tees that to `usage.json` (write-on-change, O(ms)) and passes your real statusline through unchanged. Cold-start fallback if `usage.json` is absent: `TOKENMAXXING_PROBE=1 claude -p '/usage'`, with `[ -n "$TOKENMAXXING_PROBE" ] && exit 0` as the hook's first line to stop the nested process recursing (hooks fire in `-p` too). The probe scrubs every ambient credential override claude reads before the keychain (`CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_SECURESTORAGE_CONFIG_DIR`, etc.) so it can only meter the credential in the keychain item, and retries the transient empty-footer case (claude prints local stats with no percentages when its own usage fetch throttles).
 
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
-1. Read `usage.json`; `exit 0` fast if both windows `< 98%` (metered per `organizationUuid`).
+1. Read `usage.json`; `exit 0` fast if every window is under its threshold (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, 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.
 
@@ -62,7 +62,7 @@ The supervisor's `claude` call returns; it sees `respawn/<sid>`, deletes it, res
 5. Do steps 1, 3, 4 inside Claude's own `~/.claude.lock` so the writes can't collide with a token refresh.
 
 ### 3.5 Multiple concurrent sessions
-Each terminal ran the supervisor, so each has its own child `claude`, its own `--session-id`, and its own respawn marker. When the shared account hits 98%, the first Stop hook to win the `flock` performs the one swap; **every** session's Stop hook writes its own respawn marker and SIGTERMs its own `claude`; **every** supervisor independently relaunches `claude --resume <its-own-sid>`. All of them come back on the new account, each continuing its own conversation. (They share one credential, so they always move together - consistent with "one current account, many windows.")
+Each terminal ran the supervisor, so each has its own child `claude`, its own `--session-id`, and its own respawn marker. When the shared account hits a threshold, the first Stop hook to win the `flock` performs the one swap; **every** session's Stop hook writes its own respawn marker and SIGTERMs its own `claude`; **every** supervisor independently relaunches `claude --resume <its-own-sid>`. All of them come back on the new account, each continuing its own conversation. (They share one credential, so they always move together - consistent with "one current account, many windows.")
 
 ---
 
@@ -76,7 +76,7 @@ Each terminal ran the supervisor, so each has its own child `claude`, its own `-
 ---
 
 ## 5. Rotation policy
-Trigger at `five_hour >= 98%` OR `seven_day >= 98%`, per org. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`98 − EMA(per-turn Δ%)`) so a single large turn can't 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 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 - EMA(per-turn Δ%)`) so a single large turn can't 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.
 
@@ -85,7 +85,7 @@ Trigger at `five_hour >= 98%` OR `seven_day >= 98%`, per org. "Exhausted" is a *
 ## 6. Honest papercuts
 - **Respawn hiccup.** At the swap turn you see `claude` restart (~1–2s) and resume. Anything you typed in the split second before respawn is lost - mitigate by respawning fast and showing a clear "switching" state; the supervisor resets terminal mode so nothing is left garbled.
 - **One cold turn.** Prompt cache is org-scoped: the first turn after resuming on B re-uploads context once (bigger on long transcripts).
-- **Single-turn overshoot.** If one turn jumps from <98% straight past the wall, that turn can end rate-limited before the Stop hook swaps; the respawn then still recovers it. Projected threshold reduces this.
+- **Single-turn overshoot.** If one turn jumps from under the threshold straight past the wall, that turn can end rate-limited before the Stop hook swaps; the respawn then still recovers it. Projected threshold reduces this.
 - **Shared blast radius.** All default-profile sessions share one keychain item, so a swap moves them all (each via its own respawn). The `flock` + re-check is mandatory or racing hooks burn two accounts at once.
 - **Refresh-token rotation / parked-token rot.** Step 1 re-harvest is mandatory; a parked refresh token can be invalidated by logging in elsewhere → picker must catch `invalid_grant`, mark `needs_reauth`, fall through.
 - **statusLine fragility.** The shim is the most visible surface - a bug flickers or breaks your real status line. Keep it O(ms), write-on-change.
@@ -95,7 +95,7 @@ Trigger at `five_hour >= 98%` OR `seven_day >= 98%`, per org. "Exhausted" is a *
 ---
 
 ## 7. Scope
-**v1:** `tokenmaxxing init` / `add` / `ls` / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; 98% swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
+**v1:** `tokenmaxxing init` / `add` / `ls` / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; threshold swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
 
 **v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
 

package/README.md

@@ -13,7 +13,7 @@ $ claude
 
 ## Why
 
-A running `claude` holds its OAuth token in memory and a 429 does **not** make it re-read the credential store - so you can't hot-swap a live session. tokenmaxxing instead swaps the credential and **respawns** `claude --resume <id>` at a committed turn boundary (the transcript is already on disk, so nothing is lost). A thin `claude` supervisor on your PATH owns that respawn; everything else about `claude` is unchanged - all flags, MCP, hooks, and skills pass through.
+A running `claude` re-checks the credential store between requests, so a swapped credential is adopted in-place (within ~30s on macOS, the next request on Linux). tokenmaxxing performs the swap at a committed turn boundary and **respawns** `claude --resume <id>` (the transcript is already on disk, so nothing is lost) - the respawn is what gives you a clean cutover and, when the whole pool is depleted, a countdown that auto-resumes at the soonest reset. A thin `claude` supervisor on your PATH owns that respawn; everything else about `claude` is unchanged - all flags, MCP, hooks, and skills pass through.
 
 ## Install
 
@@ -46,14 +46,14 @@ claude                  # use claude as always
 
 ## How switching decides
 
-Switching triggers at **98%** (configurable) on any of:
+Switching engages (configurable) once the active account's 5-hour session window is **50% used** - from there, every evaluation greedily converges on the usable account **furthest behind its own weekly pace**, and does nothing when the current account already wins. Independent of that, crossing a hard screening bar - **95%** session or **98%** weekly - always forces a switch. The bars also screen candidates on any of:
 
 - **Session** (5-hour) or **week (all models)** - the aggregate windows, fed free/push-based by the statusLine.
 - **Per-model weekly cap** - the most capable model (Fable) has its own tighter weekly limit that binds *before* the aggregate (per-model caps currently exist only for Sonnet and Fable, and Sonnet's is generous). tokenmaxxing reads it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) whenever the active model is one of `policy.switchModels`, so a Fable session switches on the Fable cap while a Sonnet session rides the aggregate.
 
-The 2% headroom is deliberate: it's the budget to reach a clean turn boundary and respawn before the wall.
+The bars' headroom is deliberate: it's the budget to reach a clean turn boundary and respawn before the wall. The session bar sits lower (95) because a 5-hour reset is cheap to sit out; weekly quota is use-it-or-lose-it, so it drains closer to the wall (98). The greedy engagement floor sits far below both: weekly allowance is forfeited at each account's fixed reset, so once half a session window justifies the swap, quota is best burned on whichever account has the most at risk.
 
-The **target** is chosen greedily off each account's cached windows: the usable account (session and week under threshold, or past their reset) whose weekly window **expires soonest** - unused weekly allowance is forfeited at the fixed per-account reset. Cached resets are absolute UTC epochs, so a stale snapshot still resolves correctly: a weekly reset that has passed extrapolates forward in 7-day steps, and a session window past its reset counts as empty. `tokenmaxxing switch` ranks the current account too and does nothing when it already wins, so it is idempotent - running it periodically converges on the right account.
+The **target** is chosen greedily off each account's cached windows: among usable accounts (every window under its bar, or past its reset), the one **furthest behind its own weekly pace** - highest remaining% divided by time to its weekly reset - because unused weekly allowance is forfeited at the fixed per-account reset. Cached resets are absolute UTC epochs, so a stale snapshot still resolves correctly: a weekly reset that has passed extrapolates forward in 7-day steps, and a session window past its reset counts as empty. Both `tokenmaxxing switch` and the automatic path rank the current account too and do nothing when it already wins, so they are idempotent - evaluating periodically converges on the right account.
 
 ## Configuration
 
@@ -61,16 +61,17 @@ The **target** is chosen greedily off each account's cached windows: the usable
 
 ```json
 {
-  "threshold": 98,
+  "thresholds": { "session": 95, "weekly": 98 },
   "policy": {
     "projectionMargin": 0,
+    "greedySessionFloor": 50,
     "switchModels": ["fable"],
     "usagePollTtlMs": 90000
   }
 }
 ```
 
-`projectionMargin` subtracts an EMA of per-turn Δ% for pre-emption; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh.
+`projectionMargin` subtracts an EMA of per-turn Δ% for pre-emption; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh.
 
 State lives entirely in `~/.config/tokenmaxxing/`. Per-account credentials follow the platform's Claude Code store: the login keychain on macOS (`tokenmaxxing-cred-<uuid8>` items, never plaintext on disk), 0600 files under `~/.config/tokenmaxxing/creds/` on Linux (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.9.0",
+  "version": "0.10.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/status.ts

@@ -17,7 +17,7 @@ import { readOAuthAccount } from "../lib/claudejson.ts";
 import { probeActiveUsage, probeParkedUsage, type SampleOutcome } from "../lib/sample.ts";
 import { withLock } from "../lib/lock.ts";
 import { paths } from "../lib/paths.ts";
-import { isExhausted, nextWeeklyReset } from "../lib/picker.ts";
+import { effectiveBars, isExhausted, nextWeeklyReset } from "../lib/picker.ts";
 import { bar, c, fmtAgo, fmtReset } from "./render.ts";
 import type { FullUsage } from "../lib/usage.ts";
 import type { UsageWindow } from "../lib/types.ts";
@@ -89,7 +89,7 @@ export async function cmdStatus(force = false): Promise<number> {
     saveAccounts(idx);
   });
 
-  console.log(c.dim(`threshold ${cfg.threshold}%  ·  ${idx.accounts.length} account(s)`));
+  console.log(c.dim(`threshold 5h ${cfg.thresholds.session}% · week ${cfg.thresholds.weekly}%  ·  ${idx.accounts.length} account(s)`));
   console.log();
 
   // A window whose cached reset has passed is empty again; weekly windows recur
@@ -115,7 +115,7 @@ export async function cmdStatus(force = false): Promise<number> {
     const badges: string[] = [];
     if (active) badges.push(c.green("active"));
     if (a.needsReauth) badges.push(c.red("needs-reauth"));
-    if (isExhausted(a, { now, threshold: cfg.threshold, currentAccountUuid: idx.activeAccountUuid, switchFamilies: cfg.policy.switchModels }))
+    if (isExhausted(a, { now, thresholds: effectiveBars(cfg), currentAccountUuid: idx.activeAccountUuid, switchFamilies: cfg.policy.switchModels }))
       badges.push(c.yellow("exhausted"));
 
     console.log(`${marker} ${c.bold(a.label || a.email)} ${badges.join(" ")}`);

package/src/cli/switch.ts

@@ -19,7 +19,7 @@ import { paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { performSwap, chooseAndSwap } from "../lib/swap.ts";
-import { isExhausted, pickBest, pickEarliestReset, swapPreference, weeklyExpiry, type PickCtx } from "../lib/picker.ts";
+import { currentWins, effectiveBars, pickEarliestReset, weeklyExpiry, type PickCtx } from "../lib/picker.ts";
 import { InvalidGrantError } from "../lib/oauth.ts";
 import { findAccount } from "./rename.ts";
 import { c, fmtReset } from "./render.ts";
@@ -60,21 +60,17 @@ export async function cmdSwitch(selector?: string): Promise<number> {
 
     // auto: greedy over everyone, current included - a no-op when current wins.
     // No session context here, so every configured per-model family gates.
-    const everyone: PickCtx = { now, threshold: cfg.threshold, currentAccountUuid: null, switchFamilies: cfg.policy.switchModels };
+    const everyone: PickCtx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: null, switchFamilies: cfg.policy.switchModels };
     const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid) ?? null;
-    const best = pickBest(idx.accounts, everyone);
-    const currentWins =
-      best != null && active != null && !active.needsReauth && !isExhausted(active, everyone) &&
-      (best.accountUuid === active.accountUuid || swapPreference(now).every((k) => k(active) === k(best)));
-    if (currentWins) {
+    if (active != null && currentWins(active, idx.accounts, everyone)) {
       if (drifted) return swapTo(active);
       const expiry = weeklyExpiry(active, now);
       const why = Number.isFinite(expiry) ? ` (weekly ${fmtReset(expiry, now)})` : "";
       console.log(`already on the best account: ${c.bold(active.label)}${why}`);
       return 0;
     }
-    if (best) {
-      const landed = await chooseAndSwap({ now, threshold: cfg.threshold, switchFamilies: cfg.policy.switchModels });
+    {
+      const landed = await chooseAndSwap({ now, thresholds: effectiveBars(cfg), switchFamilies: cfg.policy.switchModels });
       if (landed) {
         console.log(`${c.green("↻")} switched to ${c.bold(landed.label)}`);
         return 0;

package/src/entries/statusline.ts

@@ -18,12 +18,13 @@ import { z } from "zod";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { loadAccounts, loadConfig, loadLastSwapAt, loadModelUsage, writeUsage } from "../lib/state.ts";
 import { familyTokens, gatedFamilies, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
-import { isExhausted, swapPreference, weeklyExpiry } from "../lib/picker.ts";
+import { effectiveBars, isExhausted, swapPreference, weeklyExpiry } from "../lib/picker.ts";
 import { worktreeName } from "../lib/worktree.ts";
 import { fmtResetShort, makeColors } from "../cli/render.ts";
 import {
   AccountsIndexSchema,
   StatusLineStdinSchema,
+  ThresholdsSchema,
   UsageWindowSchema,
   type Account,
   type UsageState,
@@ -41,7 +42,7 @@ const RenderCtxSchema = z.object({
   perModel: z.record(z.string(), UsageWindowSchema),
   /** families (lowercased) whose per-model weekly cap gates a switch. */
   switchModels: z.array(z.string()),
-  threshold: z.number(),
+  thresholds: ThresholdsSchema,
   /** linked-worktree basename, null in a main checkout. */
   worktree: z.string().nullable(),
   now: z.number(),
@@ -107,7 +108,7 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
   // ---- parked accounts, in swap order: the first usable ◇ is the next target
   const pickCtx = {
     now: ctx.now,
-    threshold: ctx.threshold,
+    thresholds: ctx.thresholds,
     currentAccountUuid: ctx.accounts.activeAccountUuid,
     switchFamilies: gatedFamilies(parseStatusLineModel(stdinObj), ctx.switchModels),
   };
@@ -181,7 +182,7 @@ export async function runStatusline(): Promise<number> {
     accounts: loadAccounts(),
     perModel: modelUsage && modelUsage.org === org ? modelUsage.perModel : {},
     switchModels: cfg.policy.switchModels,
-    threshold: cfg.threshold,
+    thresholds: effectiveBars(cfg),
     worktree: dir == null ? null : worktreeName(dir),
     now,
     color: !process.env.NO_COLOR,

package/src/lib/decide.ts

@@ -2,7 +2,14 @@
 // `check` timer. Cheap pre-check off the lock; the authoritative re-check + swap
 // under the flock.
 //
-// Two limit families are checked, both metered against the CURRENTLY-active org:
+// The decision ENGAGES (user policy 2026-07-16) once the active account's 5h
+// session window reaches policy.greedySessionFloor, or once any screening bar
+// is crossed. Engaged-but-under-every-bar runs the same greedy pace-pressure
+// convergence as bare `xx switch` (swap only onto a STRICTLY better usable
+// account, current keeps its seat on ties, never a depleted pre-park); over a
+// bar keeps the original hard semantics (swap or depleted-wait).
+//
+// The windows feeding that, all metered against the CURRENTLY-active org:
 //   1. AGGREGATE windows (session=five_hour, week-all=seven_day). A rendering
 //      statusLine tees them fresh every turn; when nothing renders (headless
 //      boxes, idle TUIs) they come from `claude -p '/usage'`, re-probed once the
@@ -23,7 +30,7 @@ import { paths } from "./paths.ts";
 import { loadAccounts, loadConfig, loadLastSwapAt, loadUsage, loadModelUsage, saveAccounts, saveModelUsage, usageTeeAt, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { chooseAndSwap, performSwap } from "./swap.ts";
-import { pickEarliestReset, usableAt } from "./picker.ts";
+import { currentWins, effectiveBars, pickBest, pickEarliestReset, usableAt } from "./picker.ts";
 import { InvalidGrantError } from "./oauth.ts";
 import { familyTokens, gatedFamilies, probeUsage } from "./usage.ts";
 import { log } from "./log.ts";
@@ -54,14 +61,18 @@ function capForFamily(mu: ModelUsageState, family: string, now: number): UsageWi
   return maxBy(rows, (w) => liveUsed(w, now));
 }
 
-/** True if the active account is over the floor on ANY applicable limit. */
-function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, floor: number, now: number): boolean {
+/** True if the active account is over its floor on ANY screening bar: the 5h
+ *  session against thresholds.session, the 7-day aggregate and gated per-model
+ *  caps against thresholds.weekly. Over a bar means the hard path (swap away
+ *  or depleted-wait); the greedy path may fire well before this. */
+function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, now: number): boolean {
   if (!u || !org || u.org !== org) return false;
-  if (liveUsed(u.fiveHour, now) >= floor || liveUsed(u.sevenDay, now) >= floor) return true;
+  const bars = effectiveBars(cfg);
+  if (liveUsed(u.fiveHour, now) >= bars.session || liveUsed(u.sevenDay, now) >= bars.weekly) return true;
   if (mu && mu.org === org) {
     for (const family of gatedFamilies(u.model, cfg.policy.switchModels)) {
       const cap = capForFamily(mu, family, now);
-      if (cap && liveUsed(cap, now) >= floor) return true;
+      if (cap && liveUsed(cap, now) >= bars.weekly) return true;
     }
   }
   return false;
@@ -72,6 +83,14 @@ function needsPerModel(u: UsageState | null, cfg: Config): boolean {
   return u != null && gatedFamilies(u.model, cfg.policy.switchModels).length > 0;
 }
 
+/** Whether the decision engages at all: half a session window buys the swap
+ *  (greedySessionFloor), and a crossed screening bar always does. Below both,
+ *  a fresh session rides its account - no churn. */
+function isEngaged(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, now: number): boolean {
+  if (!u || !org || u.org !== org) return false;
+  return liveUsed(u.fiveHour, now) >= cfg.policy.greedySessionFloor || isOver(u, mu, org, cfg, now);
+}
+
 const SnapshotsSchema = z.object({
   u: UsageStateSchema.nullable(),
   mu: ModelUsageStateSchema.nullable(),
@@ -155,13 +174,12 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
   }
 
   const cfg = loadConfig();
-  const floor = cfg.threshold - cfg.policy.projectionMargin;
   const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
 
   const { u: usage, mu } = await loadFreshSnapshots(cfg, activeOrg, now);
 
   // cheap pre-check off the lock - the common case exits here.
-  if (!isOver(usage, mu, activeOrg, cfg, floor, now)) {
+  if (!isEngaged(usage, mu, activeOrg, cfg, now)) {
     return { swapped: false, account: null, reason: "under-threshold-or-stale" };
   }
 
@@ -185,20 +203,51 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       }
     }
 
-    if (!isOver(u2, mu2, org2, cfg, floor, now)) {
+    if (!isEngaged(u2, mu2, org2, cfg, now)) {
       return { swapped: false, account: null, reason: "raced-already-swapped" };
     }
 
     // Candidates are screened by the same families that drove this decision, so
     // the pool cannot ping-pong onto an account the gate would immediately flag.
     const switchFamilies = gatedFamilies(u2?.model ?? null, cfg.policy.switchModels);
-    const landed = await chooseAndSwap({ now, threshold: cfg.threshold, switchFamilies });
+
+    // Greedy path: engaged but under every screening bar. Converge like bare
+    // `xx switch` - swap only onto a strictly better usable account - and stay
+    // put otherwise: with a usable current account, a depleted pre-park or wait
+    // would trade a working session for nothing. NOT chooseAndSwap: its dead-
+    // token fallback lands on the next usable candidate unconditionally, but
+    // here the fallback must ALSO strictly beat the current account, or a dead
+    // refresh token on the winner would bounce a healthy session onto a worse
+    // account and back. performSwap marks needs-reauth before throwing, so each
+    // reload re-ranks without the dead account and the loop must terminate.
+    if (!isOver(u2, mu2, org2, cfg, now)) {
+      const ctxAll = { now, thresholds: effectiveBars(cfg), currentAccountUuid: null, switchFamilies };
+      while (true) {
+        const cur = loadAccounts();
+        const active = cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ?? null;
+        if (currentWins(active, cur.accounts, ctxAll)) {
+          return { swapped: false, account: null, reason: "current-best" };
+        }
+        const best = pickBest(cur.accounts, { ...ctxAll, currentAccountUuid: cur.activeAccountUuid });
+        if (!best) return { swapped: false, account: null, reason: "no-usable-target" };
+        try {
+          await performSwap(best);
+        } catch (e) {
+          if (e instanceof InvalidGrantError) continue;
+          throw e;
+        }
+        log("decide.greedy_swap", { account: best.accountUuid.slice(0, 8) });
+        return { swapped: true, account: best, reason: "swapped" };
+      }
+    }
+
+    const landed = await chooseAndSwap({ now, thresholds: effectiveBars(cfg), switchFamilies });
     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.
     const fresh = loadAccounts();
-    const ctx = { now, threshold: cfg.threshold, currentAccountUuid: fresh.activeAccountUuid, switchFamilies };
+    const ctx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: fresh.activeAccountUuid, switchFamilies };
     const current = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid);
     const currentAt = current ? usableAt(current, ctx) : Number.POSITIVE_INFINITY;
     const other = pickEarliestReset(fresh.accounts, ctx);

package/src/lib/picker.ts

@@ -13,11 +13,23 @@
 import { minBy, sortBy } from "es-toolkit";
 import { z } from "zod";
 import { familyTokens } from "./usage.ts";
-import { AccountSchema, type Account, type UsageWindow } from "./types.ts";
+import { AccountSchema, ThresholdsSchema, type Account, type Config, type Thresholds, type UsageWindow } from "./types.ts";
+
+/** The effective per-window bars: configured thresholds minus the projection
+ *  margin. ONE bar per window for BOTH the trigger and candidate screening -
+ *  a screen laxer than the trigger would land swaps on accounts the trigger
+ *  immediately re-flags (cooldown-throttled ping-pong). Every PickCtx and the
+ *  trigger floors must be built from this. */
+export function effectiveBars(cfg: Config): Thresholds {
+  return {
+    session: cfg.thresholds.session - cfg.policy.projectionMargin,
+    weekly: cfg.thresholds.weekly - cfg.policy.projectionMargin,
+  };
+}
 
 const PickCtxSchema = z.object({
   now: z.number(),
-  threshold: z.number(),
+  thresholds: ThresholdsSchema,
   /** account to exclude (hooks switch AWAY from it); null ranks everyone. */
   currentAccountUuid: z.string().nullable(),
   /** families whose per-model weekly cap counts toward exhaustion (from
@@ -43,23 +55,31 @@ const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
  *  certainly reset - so a benched account always recovers by itself. With no
  *  sample time either, it blocks indefinitely: guessing "usable now" would
  *  swap onto it with waitUntil=now and churn kill/respawn. */
-function blockedUntil(w: UsageWindow, windowMs: number, sampledAt: number | undefined, ctx: PickCtx): number {
-  if (w.usedPercentage < ctx.threshold) return 0;
+function blockedUntil(w: UsageWindow, windowMs: number, sampledAt: number | undefined, threshold: number): number {
+  if (w.usedPercentage < threshold) return 0;
   if (w.resetsAt != null) return w.resetsAt;
   return sampledAt != null ? sampledAt + windowMs : Number.POSITIVE_INFINITY;
 }
 
 /** When each of the account's windows stops blocking: the two aggregates plus
- *  the gated per-model caps. */
+ *  the gated per-model caps, each against its own threshold (session swaps
+ *  earlier than the weekly windows, and a candidate is screened by the same
+ *  bar that would trigger a switch off it - landing below the trigger bar
+ *  would ping-pong). */
 function blockingUntil(a: Account, ctx: PickCtx): number[] {
   const u = a.lastUsage;
   return [
-    ...(u ? [blockedUntil(u.fiveHour, FIVE_HOURS_MS, a.lastUsageAt, ctx), blockedUntil(u.sevenDay, WEEK_MS, a.lastUsageAt, ctx)] : []),
-    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastUsageAt, ctx)),
+    ...(u
+      ? [
+          blockedUntil(u.fiveHour, FIVE_HOURS_MS, a.lastUsageAt, ctx.thresholds.session),
+          blockedUntil(u.sevenDay, WEEK_MS, a.lastUsageAt, ctx.thresholds.weekly),
+        ]
+      : []),
+    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastUsageAt, ctx.thresholds.weekly)),
   ];
 }
 
-/** An account is "exhausted" if a window is >= threshold and hasn't reset yet. */
+/** An account is "exhausted" if a window is >= its threshold and hasn't reset yet. */
 export function isExhausted(a: Account, ctx: PickCtx): boolean {
   return blockingUntil(a, ctx).some((t) => t > ctx.now);
 }
@@ -111,6 +131,18 @@ export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   return sortBy(usable, swapPreference(ctx.now))[0] ?? null;
 }
 
+/** Greedy idempotence, shared by bare `xx switch` and the hooks/timer path:
+ *  the active account keeps its seat while it is usable and no other usable
+ *  account ranks STRICTLY better on swapPreference - swapping between equals
+ *  buys nothing and would ping-pong. Rank with currentAccountUuid null so the
+ *  active account competes. */
+export function currentWins(active: Account | null, accounts: Account[], ctx: PickCtx): boolean {
+  if (!active || active.needsReauth || isExhausted(active, ctx)) return false;
+  const best = pickBest(accounts, { ...ctx, currentAccountUuid: null });
+  if (best == null || best.accountUuid === active.accountUuid) return true;
+  return swapPreference(ctx.now).every((k) => k(active) === k(best));
+}
+
 /** When an account becomes usable again: the latest blocking bound among its
  *  windows (all must clear), or `now` if nothing blocks. Consistent with
  *  isExhausted by construction (same blockingUntil). */

package/src/lib/state.ts

@@ -20,21 +20,25 @@ import {
 // ---- config.json (minimal, fixed schema) ---------------------------------
 
 const DEFAULT_CONFIG: Config = {
-  threshold: 98,
+  // 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.
+  thresholds: { session: 95, weekly: 98 },
   claudeBin: "",
   // per-model weekly caps exist only for Sonnet and Fable (no Opus-only quota,
   // per the user 2026-07-12), and only Fable's is worth switching on.
-  policy: { projectionMargin: 0, switchModels: ["fable"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
+  // greedySessionFloor 50: half a session window buys the swap (user 2026-07-16).
+  policy: { projectionMargin: 0, greedySessionFloor: 50, switchModels: ["fable"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
 };
 
 /** On-disk shape (all optional); validated via Zod, merged over defaults. */
 const ConfigFileSchema = z
   .object({
-    threshold: z.number(),
+    thresholds: z.object({ session: z.number(), weekly: z.number() }).partial(),
     claudeBin: z.string(),
     policy: z
       .object({
         projectionMargin: z.number(),
+        greedySessionFloor: z.number(),
         switchModels: z.array(z.string()),
         usagePollTtlMs: z.number(),
         maxWaitMs: z.number(),
@@ -44,7 +48,7 @@ const ConfigFileSchema = z
   .partial();
 
 export function loadConfig(): Config {
-  const cfg: Config = { ...DEFAULT_CONFIG, policy: { ...DEFAULT_CONFIG.policy } };
+  const cfg: Config = { ...DEFAULT_CONFIG, thresholds: { ...DEFAULT_CONFIG.thresholds }, policy: { ...DEFAULT_CONFIG.policy } };
   if (existsSync(paths.configJson)) {
     let raw: unknown = {};
     try {
@@ -54,9 +58,11 @@ export function loadConfig(): Config {
     }
     const parsed = ConfigFileSchema.safeParse(raw);
     const p = parsed.success ? parsed.data : {};
-    cfg.threshold = p.threshold ?? cfg.threshold;
+    cfg.thresholds.session = p.thresholds?.session ?? cfg.thresholds.session;
+    cfg.thresholds.weekly = p.thresholds?.weekly ?? cfg.thresholds.weekly;
     cfg.claudeBin = p.claudeBin ?? cfg.claudeBin;
     cfg.policy.projectionMargin = p.policy?.projectionMargin ?? cfg.policy.projectionMargin;
+    cfg.policy.greedySessionFloor = p.policy?.greedySessionFloor ?? cfg.policy.greedySessionFloor;
     cfg.policy.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
     cfg.policy.maxWaitMs = p.policy?.maxWaitMs ?? cfg.policy.maxWaitMs;
     if (p.policy?.switchModels) {

package/src/lib/types.ts

@@ -105,11 +105,30 @@ export const AccountsIndexSchema = z.object({
 export const LastSwapSchema = z.object({ ts: z.number() });
 export type AccountsIndex = z.infer<typeof AccountsIndexSchema>;
 
+/** Per-window screening bars (used %): an account with a window at/over its bar
+ *  is no switch candidate until that window resets. The session bar is lower
+ *  than the weekly one: a session reset is at most 5h away, so burning a little
+ *  headroom there is cheap, while weekly quota is use-it-or-lose-it and worth
+ *  draining closer to the wall. Screening is these bars' ONLY job - the switch
+ *  trigger is the greedy pace-pressure convergence (policy.greedySessionFloor). */
+export const ThresholdsSchema = z.object({
+  /** 5h session window. */
+  session: z.number(),
+  /** 7-day aggregate AND per-model weekly caps. */
+  weekly: z.number(),
+});
+export type Thresholds = z.infer<typeof ThresholdsSchema>;
+
 export const ConfigSchema = z.object({
-  threshold: z.number(),
+  thresholds: ThresholdsSchema,
   claudeBin: z.string(),
   policy: z.object({
     projectionMargin: z.number(),
+    /** session-used % at which the greedy convergence engages: from here on,
+     *  every evaluation swaps to the usable account furthest behind its weekly
+     *  pace whenever that beats the current one (idempotent; current keeps its
+     *  seat on ties). Below the floor a fresh session rides its account. */
+    greedySessionFloor: z.number(),
     /** models whose PER-MODEL weekly cap should trigger a switch (display names, lowercased). */
     switchModels: z.array(z.string()),
     /** how long a `/usage` per-model poll stays fresh before we re-poll (ms). */