tokenmaxxing 0.8.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
 
@@ -39,20 +39,21 @@ claude                  # use claude as always
 | `tokenmaxxing add` | register an additional account (isolated login, harvested into the pool) |
 | `tokenmaxxing ls` | list pooled accounts |
 | `tokenmaxxing status` | accounts with 5h / weekly usage bars, active + exhausted-until-reset |
+| `tokenmaxxing status --force` | additionally ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
 | `tokenmaxxing rename <sel> <label>` · `rm <sel>` | manage the pool |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
 
 ## 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
 
@@ -60,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.8.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",
@@ -21,7 +21,10 @@
   "engines": {
     "bun": ">=1.2.6"
   },
-  "os": ["darwin", "linux"],
+  "os": [
+    "darwin",
+    "linux"
+  ],
   "scripts": {
     "dev": "bun run src/main.ts",
     "test": "bun test",

package/src/cli/init.ts

@@ -30,6 +30,20 @@ function reportTimer(out: InstallOutcome): void {
   else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
 }
 
+/** The how-to-use epilogue both init paths end on: the whole point of the tool
+ *  is that after init you just run `claude`, so say exactly that, and teach the
+ *  `xx` shorthand every other command hangs off. Exported for the render test. */
+export function printUsage(): void {
+  console.log();
+  console.log(`  ${c.bold("how to use")} - ${c.cyan("xx")} is shorthand for ${c.cyan("tokenmaxxing")}:`);
+  console.log(`    ${c.cyan("claude")}             use claude as always; it switches accounts near quota automatically`);
+  console.log(`    ${c.cyan("xx")}                 show the pool with usage bars (same as ${c.cyan("xx status")})`);
+  console.log(`    ${c.cyan("xx status --force")}  ping every account (one tiny haiku request each) so all 5h timers start now, then sample fresh`);
+  console.log(`    ${c.cyan("xx add")}             log in and pool another account`);
+  console.log(`    ${c.cyan("xx switch")}          hop to the best account right now (the automatic switching needs no command)`);
+  console.log(`    ${c.cyan("xx help")}            everything else`);
+}
+
 export async function cmdInit(): Promise<number> {
   mkdirSync(paths.home, { recursive: true });
 
@@ -50,7 +64,8 @@ export async function cmdInit(): Promise<number> {
     console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
     reportTimer(out);
     if (!out.pathAhead) ensurePathAhead();
-    console.log(`  active: ${c.bold(active?.label ?? "unknown")} · run ${c.cyan("tokenmaxxing add")} for more, ${c.cyan("tokenmaxxing status")} to check`);
+    console.log(`  active: ${c.bold(active?.label ?? "unknown")}`);
+    printUsage();
     return 0;
   }
 
@@ -127,6 +142,7 @@ export async function cmdInit(): Promise<number> {
     ensurePathAhead();
   }
   console.log();
-  console.log(`  pool ready (${idx.accounts.length} account${idx.accounts.length === 1 ? "" : "s"}) · add more with ${c.cyan("tokenmaxxing add")}`);
+  console.log(`  pool ready (${idx.accounts.length} account${idx.accounts.length === 1 ? "" : "s"})`);
+  printUsage();
   return 0;
 }

package/src/cli/status.ts

@@ -4,18 +4,25 @@
 // own busy token. A sample that fails falls back to the last-known values with a
 // visible "(cached)" note - never a silent stale number. Fresh figures are
 // persisted onto each account for the picker/switch logic.
+//
+// `--force` additionally PINGS every account (one minimal haiku request each)
+// before sampling, so every account's 5h session window starts ticking NOW
+// instead of lying dormant until first real use, and every bar is a live probe
+// taken after the ping. The active account still prefers the tee only as a
+// fallback: its own `/usage` fail-silents exactly when a live session is
+// running it, and that session's tee is fresher than any cache.
 
 import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts } from "../lib/state.ts";
 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";
 
-export async function cmdStatus(): Promise<number> {
+export async function cmdStatus(force = false): Promise<number> {
   let idx = loadAccounts();
   const cfg = loadConfig();
   const now = Date.now();
@@ -28,7 +35,7 @@ export async function cmdStatus(): Promise<number> {
   // Load, sample, and save entirely under the flock: parked refreshes must not
   // collide with an in-flight swap, and a save of an index loaded before a
   // concurrent swap would clobber the swap's activeAccountUuid.
-  console.error(c.dim("sampling live usage..."));
+  console.error(c.dim(force ? "pinging every account (starts each 5h session timer) + sampling live usage..." : "sampling live usage..."));
   const outcomes = new Map<string, SampleOutcome>();
   await withLock(paths.lockFile, async () => {
     idx = loadAccounts();
@@ -49,24 +56,40 @@ export async function cmdStatus(): Promise<number> {
                 perModel: modelUsage && modelUsage.org === a.organizationUuid ? modelUsage.perModel : {},
               }
             : null;
-        const outcome: SampleOutcome = fromStatusLine
-          ? { ok: true, usage: fromStatusLine }
-          : isActive
-            ? await probeActiveUsage(a)
-            : await probeParkedUsage(a);
+        let viaTee = false;
+        let outcome: SampleOutcome;
+        if (force) {
+          // Force: ping + live probe for everyone. The tee predates the ping,
+          // so it serves only as the active account's fallback when its own
+          // `/usage` fail-silents (a running session's tee is still fresh).
+          outcome = isActive ? await probeActiveUsage(a, { ping: true }) : await probeParkedUsage(a, { ping: true });
+          if (!outcome.ok && fromStatusLine) {
+            const failed = outcome;
+            outcome = { ok: true, usage: fromStatusLine };
+            if (failed.pingError != null) outcome.pingError = failed.pingError;
+            viaTee = true;
+          }
+        } else {
+          viaTee = fromStatusLine != null;
+          outcome = fromStatusLine
+            ? { ok: true, usage: fromStatusLine }
+            : isActive
+              ? await probeActiveUsage(a)
+              : await probeParkedUsage(a);
+        }
         outcomes.set(a.accountUuid, outcome);
         if (!outcome.ok) return;
         a.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
         if (Object.keys(outcome.usage.perModel).length > 0) a.lastPerModel = outcome.usage.perModel;
         // stamp when the figures were actually measured: the statusLine tee's
         // own write time for the push-fed active account, else the probe time.
-        a.lastUsageAt = fromStatusLine && live ? live.ts : Date.now();
+        a.lastUsageAt = viaTee && live ? live.ts : Date.now();
       }),
     );
     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
@@ -92,7 +115,7 @@ export async function cmdStatus(): 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(" ")}`);
@@ -105,6 +128,16 @@ export async function cmdStatus(): Promise<number> {
       const cached = aggregate || perModel ? `cached${a.lastUsageAt != null ? ` ${fmtAgo(a.lastUsageAt, now)}` : ""} · ` : "";
       console.log(`    ${c.yellow(`${cached}live sample failed`)}: ${c.dim(outcome.reason)}`);
     }
+    if (outcome?.pingError != null) {
+      console.log(`    ${c.yellow("ping failed (5h timer may not have started)")}: ${c.dim(outcome.pingError)}`);
+    }
+    // A successful ping ALWAYS opens the 5h window (live-verified 2026-07-16),
+    // but the server's usage feed reflects it with a lag of up to a few
+    // minutes, so a probe taken seconds later can still show a dormant window.
+    // Say so rather than looking like the ping did nothing.
+    if (force && outcome?.ok && outcome.pingError == null && aggregate && aggregate.fiveHour.resetsAt == null) {
+      console.log(`    ${c.dim("pinged - 5h timer started this run; the usage feed lags, re-run status shortly for the fresh window")}`);
+    }
     console.log();
   }
   return 0;

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/sample.ts

@@ -25,13 +25,15 @@ import { readItem, writeItem, deleteItem, liveTarget, parkedTarget, isolatedTarg
 import { credItemFor, paths } from "./paths.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
 import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
-import { FullUsageSchema, probeUsage } from "./usage.ts";
+import { FullUsageSchema, pingSession, probeUsage } from "./usage.ts";
 import { CredentialBlobSchema, type Account, type OAuthCreds, type RolesResponse } from "./types.ts";
 
-/** Result of a live sample: the fresh usage, or why it could not be taken. */
+/** Result of a live sample: the fresh usage, or why it could not be taken.
+ *  `pingError` is set only when a requested ping (status --force) failed - the
+ *  account's 5h timer may not have started even if the sample itself succeeded. */
 export const SampleOutcomeSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), usage: FullUsageSchema }),
-  z.object({ ok: z.literal(false), reason: z.string() }),
+  z.object({ ok: z.literal(true), usage: FullUsageSchema, pingError: z.string().optional() }),
+  z.object({ ok: z.literal(false), reason: z.string(), pingError: z.string().optional() }),
 ]);
 export type SampleOutcome = z.infer<typeof SampleOutcomeSchema>;
 
@@ -51,8 +53,11 @@ async function identityMismatch(creds: OAuthCreds, account: Account): Promise<st
  * Live-sample `account`'s `/usage` in isolation. On a dead refresh token or a
  * mislabeled credential it sets `account.needsReauth` in place (the caller
  * persists accounts.json). Mutates only the passed object and keychain items.
+ * With `ping`, one minimal metered request runs first (through the same
+ * isolated credential) so the account's 5h session window starts now and the
+ * sample that follows reports the freshly opened window.
  */
-export async function probeParkedUsage(account: Account): Promise<SampleOutcome> {
+export async function probeParkedUsage(account: Account, opts: { ping?: boolean } = {}): Promise<SampleOutcome> {
   const backup = parkedTarget(account.keychainItem);
   const parkedRaw = await readItem(backup);
   if (!parkedRaw) return { ok: false, reason: "no parked credential - re-add with `tokenmaxxing add`" };
@@ -94,8 +99,13 @@ export async function probeParkedUsage(account: Account): Promise<SampleOutcome>
   try {
     await writeItem(isoTarget, installed);
     writeFileSync(join(dir, ".claude.json"), JSON.stringify({ oauthAccount: account.oauthAccount, hasCompletedOnboarding: true }));
+    const pingError = opts.ping ? await pingSession(dir) : null;
     const usage = await probeUsage(dir);
-    return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+    const outcome: SampleOutcome = usage
+      ? { ok: true, usage }
+      : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+    if (pingError != null) outcome.pingError = pingError;
+    return outcome;
   } finally {
     // capture-before-delete: never discard a rotation claude may have performed.
     const afterIso = await readItem(isoTarget);
@@ -109,9 +119,10 @@ export async function probeParkedUsage(account: Account): Promise<SampleOutcome>
  * Live-sample the ACTIVE account off the live login, verifying the live
  * credential belongs to it. `/usage` with no CLAUDE_CONFIG_DIR meters the live
  * keychain item. A drifted active label surfaces as an error, not another
- * account's bars.
+ * account's bars. With `ping`, one minimal metered request runs first (after
+ * the identity check - never spend quota on a drifted credential).
  */
-export async function probeActiveUsage(account: Account): Promise<SampleOutcome> {
+export async function probeActiveUsage(account: Account, opts: { ping?: boolean } = {}): Promise<SampleOutcome> {
   const liveRaw = await readItem(liveTarget());
   if (!liveRaw) return { ok: false, reason: "no live credential - run `claude` and `/login`" };
   let creds: OAuthCreds;
@@ -139,6 +150,9 @@ export async function probeActiveUsage(account: Account): Promise<SampleOutcome>
   const mismatch = await identityMismatch(creds, account);
   if (mismatch) return { ok: false, reason: `live ${mismatch} - active label drifted; run \`tokenmaxxing switch\`` };
 
+  const pingError = opts.ping ? await pingSession() : null;
   const usage = await probeUsage();
-  return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+  const outcome: SampleOutcome = usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+  if (pingError != null) outcome.pingError = pingError;
+  return outcome;
 }

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). */

package/src/lib/usage.ts

@@ -4,10 +4,13 @@
 // figures claude's own usage screen shows; we run it in a throwaway
 // CLAUDE_CONFIG_DIR to sample a parked account without disturbing the live login.
 
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
 import { delay } from "es-toolkit";
 import { z } from "zod";
 import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealClaude } from "./claudebin.ts";
 import { log } from "./log.ts";
+import { paths } from "./paths.ts";
 import { RateLimitsStdinSchema, UsageWindowSchema, type ModelInfo, type UsageWindow, type UsageWindows } from "./types.ts";
 
 /** Normalize a resets_at value (epoch s, epoch ms, or ISO string) to epoch ms. */
@@ -215,41 +218,56 @@ const PROBE_KILL_MS = 60_000;
 /** How long after the child's death to keep waiting for pipe EOF. */
 const PIPE_GRACE_MS = 2_000;
 
+const SpawnResultSchema = z.object({
+  exitCode: z.number().nullable(),
+  stdout: z.string(),
+  stderr: z.string(),
+});
+type SpawnResult = z.infer<typeof SpawnResultSchema>;
+
+/** Spawn one bounded claude invocation (shared by the `/usage` probe and the
+ *  `--force` ping). SIGKILL after PROBE_KILL_MS: claude traps SIGTERM, and a
+ *  wedged child that survives the kill would keep p.exited pending and re-wedge
+ *  the read race. Descendants inherit the output pipes, so EOF can lag the
+ *  child's death or never arrive at all - a leaked grandchild holding the pipe
+ *  wedged the 2026-07-12 probes forever, defeating the kill guard - so the
+ *  reads are bounded by child-exit + grace instead of awaiting EOF
+ *  unconditionally. Returns null when the pipes were withheld past the grace. */
+async function spawnClaudeBounded(
+  cmd: string[],
+  env: Record<string, string>,
+  cwd?: string,
+): Promise<SpawnResult | null> {
+  const p = Bun.spawn(cmd, { env, cwd, stdout: "pipe", stderr: "pipe" });
+  const killer = setTimeout(() => p.kill("SIGKILL"), PROBE_KILL_MS);
+  try {
+    const reads = Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
+    const settled = await Promise.race([
+      reads,
+      p.exited.then(() => delay(PIPE_GRACE_MS)).then(() => null),
+    ]);
+    if (settled === null) return null;
+    const [stdout, stderr] = settled;
+    await p.exited;
+    return { exitCode: p.exitCode, stdout, stderr };
+  } finally {
+    clearTimeout(killer);
+  }
+}
+
 async function probeUsageOnce(env: Record<string, string>, now: number): Promise<FullUsage | null> {
   let out: string;
   try {
-    const p = Bun.spawn([resolveRealClaude(), "-p", "/usage", "--output-format", "json"], {
-      env,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    // SIGKILL: claude traps SIGTERM, and a wedged probe child that survives the
-    // kill would keep p.exited pending and re-wedge the read race below.
-    const killer = setTimeout(() => p.kill("SIGKILL"), PROBE_KILL_MS);
-    try {
-      // Descendants inherit the output pipes, so EOF can lag the child's death
-      // or never arrive at all - a leaked grandchild holding the pipe wedged
-      // the 2026-07-12 probes forever, defeating the kill guard above. Bound
-      // the reads by child-exit + grace instead of awaiting EOF unconditionally.
-      const reads = Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
-      const settled = await Promise.race([
-        reads,
-        p.exited.then(() => delay(PIPE_GRACE_MS)).then(() => null),
-      ]);
-      if (settled === null) {
-        log("usage.probe_failed", { err: "output pipes still open after child exit (leaked descendant)" });
-        return null;
-      }
-      const [text, errText] = settled;
-      await p.exited;
-      if (p.exitCode !== 0) {
-        log("usage.probe_failed", { exit: p.exitCode ?? "signal", stderr: errText.trim().slice(0, 200) });
-        return null;
-      }
-      out = text;
-    } finally {
-      clearTimeout(killer);
+    const r = await spawnClaudeBounded([resolveRealClaude(), "-p", "/usage", "--output-format", "json"], env);
+    if (r === null) {
+      log("usage.probe_failed", { err: "output pipes still open after child exit (leaked descendant)" });
+      return null;
+    }
+    if (r.exitCode !== 0) {
+      log("usage.probe_failed", { exit: r.exitCode ?? "signal", stderr: r.stderr.trim().slice(0, 200) });
+      return null;
     }
+    out = r.stdout;
   } catch (e) {
     log("usage.probe_failed", { err: String((e as Error).message ?? e) });
     return null;
@@ -285,14 +303,20 @@ const PROBE_RETRY_DELAYS_MS = [2000, 5000];
  * keychain item. The empty-footer case (claude's own usage call throttled) is
  * transient, so retry with backoff. Returns null if it never yields data.
  */
-export async function probeUsage(configDir?: string, now = Date.now()): Promise<FullUsage | null> {
-  // The probe spawns the real claude DIRECTLY - it never legitimately passes
-  // through the wrapper again. Preset the depth to the cap so a poisoned pin
-  // that leads back to the wrapper aborts on its first entry (the 2026-07-12
-  // ~1800-process recursion started as exactly this probe).
+/** The scrubbed env every probe/ping spawn uses. The child spawns the real
+ *  claude DIRECTLY - it never legitimately passes through the wrapper again -
+ *  so the depth is preset to the cap and a poisoned pin that leads back to the
+ *  wrapper aborts on its first entry (the 2026-07-12 ~1800-process recursion
+ *  started as exactly this probe). */
+function probeEnv(configDir?: string): Record<string, string> {
   const env: Record<string, string> = { ...process.env, TOKENMAXXING_PROBE: "1", [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) };
   for (const k of CRED_ENV_OVERRIDES) delete env[k];
   if (configDir) env.CLAUDE_CONFIG_DIR = configDir;
+  return env;
+}
+
+export async function probeUsage(configDir?: string, now = Date.now()): Promise<FullUsage | null> {
+  const env = probeEnv(configDir);
 
   for (let attempt = 0; ; attempt++) {
     const full = await probeUsageOnce(env, now);
@@ -304,3 +328,53 @@ export async function probeUsage(configDir?: string, now = Date.now()): Promise<
     await delay(PROBE_RETRY_DELAYS_MS[attempt]!);
   }
 }
+
+// ---- `--force` ping --------------------------------------------------------
+
+/** The ping is a REAL (but minimal) inference request: `/usage` is free and
+ *  starts nothing, while any metered request opens the account's 5h session
+ *  window at the current instant. haiku: the cheapest model (verified $1/$5 per
+ *  MTok vs $3+ for every other current tier), and one with no per-model weekly
+ *  cap (those exist only for Sonnet and Fable), so a ping never adds to a
+ *  per-model cap the policy gates on; its dent in the aggregate 5h/7d windows
+ *  is negligible. Hooks are disabled for the nested call
+ *  (`--settings`, the only supported way; `--bare` would kill keychain reads)
+ *  even though our own hooks already no-op on the probe env. */
+const PING_ARGS = [
+  "-p", "Reply with exactly: ok",
+  "--model", "haiku",
+  "--settings", '{"disableAllHooks":true}',
+  "--output-format", "json",
+];
+
+const PingResultSchema = z.looseObject({ is_error: z.boolean(), result: z.string().optional() });
+
+/**
+ * Send one minimal metered request so the account's 5h session window starts
+ * NOW instead of lying dormant until first real use. Pass `configDir` to ping a
+ * parked account through its isolated dir (credential already installed); omit
+ * to ping the live login. Runs from an empty scratch cwd so no project context
+ * (CLAUDE.md, project settings) inflates the request. Returns null on success,
+ * else the failure reason.
+ */
+export async function pingSession(configDir?: string): Promise<string | null> {
+  const cwd = join(paths.sampleDir, "ping-cwd");
+  const fail = (reason: string): string => {
+    log("usage.ping_failed", { dir: configDir ?? "live", reason: reason.slice(0, 200) });
+    return reason;
+  };
+  let r: SpawnResult | null;
+  try {
+    mkdirSync(cwd, { recursive: true });
+    r = await spawnClaudeBounded([resolveRealClaude(), ...PING_ARGS], probeEnv(configDir), cwd);
+  } catch (e) {
+    return fail(String((e as Error).message ?? e));
+  }
+  if (r === null) return fail("output pipes still open after child exit (leaked descendant)");
+  if (r.exitCode !== 0) return fail(`claude exited ${r.exitCode ?? "on signal"}: ${(r.stderr.trim() || r.stdout.trim()).slice(0, 160)}`);
+  const parsed = PingResultSchema.safeParse((() => { try { return JSON.parse(r.stdout); } catch { return null; } })());
+  if (!parsed.success) return fail(`unrecognized ping output: ${r.stdout.trim().slice(0, 120)}`);
+  if (parsed.data.is_error) return fail((parsed.data.result?.trim() || "request errored").slice(0, 160));
+  log("usage.ping_ok", { dir: configDir ?? "live" });
+  return null;
+}

package/src/main.ts

@@ -30,6 +30,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing add")}        register an additional account (isolated login)
   ${c.cyan("tokenmaxxing ls")}         list pooled accounts
   ${c.cyan("tokenmaxxing status")}     accounts with 5h / weekly / per-model usage bars
+  ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} <sel> <label>
   ${c.cyan("tokenmaxxing rm")} <sel>
@@ -57,12 +58,13 @@ async function main(): Promise<number> {
     case "__stop-hook": return runStopHook();
     case "__session-start": return runSessionStart();
     case undefined: return cmdStatus(); // bare `tokenmaxxing` / `xx` → status
+    case "--force": return cmdStatus(true); // bare `xx --force` → status --force
     case "switch": return cmdSwitch(args[1]);
     case "check": return cmdCheck();
     case "init": return cmdInit();
     case "add": return cmdAdd();
     case "ls": return cmdLs();
-    case "status": return cmdStatus();
+    case "status": return cmdStatus(args.includes("--force"));
     case "doctor": return cmdDoctor();
     case "rm": return cmdRm(args[1]);
     case "rename": return cmdRename(args[1], args[2]);