tokenmaxxing 1.19.1 → 1.20.0

package/DESIGN.md

@@ -49,8 +49,8 @@ The switching path runs no long-lived daemon. The statusline pushes usage. Hooks
 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 tees that to `usage.json` (write-on-change, O(ms)) and renders its own native line (it replaced the earlier pass-through delegation on 2026-07-11: install takes the statusLine slot outright, so a pre-existing custom statusline command is overwritten). 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 below the engagement floor (`policy.greedySessionFloor`, default 80% of the 5h window) unless a screening bar is already crossed. Engaged-but-under-every-bar runs the GREEDY convergence: stay when the current account wins or ties, else swap onto the strictly better account. A crossed bar forces the hard path (metered per live `accountUuid`; team seats share one organization, so the organization never identifies a seat).
-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).
+1. Read `usage.json` and exit below the engagement floor unless a screening bar is crossed, then follow the greedy or hard path defined in the [switching policy](docs/content/docs/switching.mdx).
+2. Take the pool lock, re-check state, select a candidate under the [switching policy](docs/content/docs/switching.mdx), and attempt bounded verification of stale usage before swapping the credential.
 3. Done - the running session adopts the new credential on its own within a request or two. Only when the pool is depleted (the decision returned a `waitUntil`: pre-parked on the soonest-recovering account, or staying on the current one when it recovers first) does the hook write `respawn/<session_id>` (atomic temp+rename).
 
 ### 3.3 Depleted-pool pause (supervisor)
@@ -79,9 +79,22 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 ---
 
 ## 5. Rotation policy
-The decision engages at `five_hour >= 80%` (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 automatic greedy path adds **incumbent hysteresis** (`policy.greedySwapMargin`, default 0.15): the seat holds unless a parked account's pace pressure beats it by more than that fraction, so near-tied accounts stop trading the seat back and forth and busting the per-org prompt cache (each such swap forces a full uncached re-read next turn). The margin only gates lateral under-bar swaps, never a crossed bar or the wall; bare `tokenmaxxing switch` sets it to zero and still converges on the strictly best account. The **Layer 1 screening bars** - `five_hour >= <active rung>` (the 5h ladder `thresholds.session`, default `[90]`, a single rung: the lowest rung some pooled account still clears, the current one included) OR `seven_day >= 98%`, per org (`thresholds`) - force a switch onto a fresher account and also screen candidates. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`bar - policy.projectionMargin`, a fixed configured margin) so a single large turn is less likely to blow past 100% before the next Stop hook.
+The [switching policy](docs/content/docs/switching.mdx) defines engagement, screening bars, organization preference, incumbent hysteresis and the wall squeeze.
 
-**Two layers - pump the last drops.** The screening bars deliberately leave headroom, so when *every* account is over them Layer 1 alone would park the pool with 2-5% of each account's quota still unspent. **Layer 2 - the wall bars** (`hardThresholds`, default `100/100`, the server's own limit) - is the fallback reached only at that point: the session **holds its seat and squeezes** while it is under the wall, else swaps onto the best still-under-wall account (the same pace-pressure ranking as every other swap - squeeze the account whose weekly quota is most about to be forfeited first), and only parks (depleted-wait) once every account has truly walled. Recovery is then measured against the wall, not the screening bar, so an account whose 5h window drops below 100 is squeezable again even while its weekly window still sits above the Layer 1 bar. The wall reading is the statusLine's own `rate_limits` feed - the same server-side figure claude's `/rate-limit-options` renders - so when an account genuinely maxes out the tee shows 100 and Layer 2 moves on; a single-turn overshoot is caught one boundary later (the periodic `check` timer, or the next Stop hook) without needing to sniff assistant text. Set `hardThresholds` equal to `thresholds` to disable Layer 2. **Layer 2 is Claude-only:** a swap on Claude is a hot, in-place credential adoption every concurrent session follows automatically, whereas a running Codex refuses another account's credential (restart is the switch), so a last-drop-swap there would strand any sibling still on the walled account - Codex instead keeps riding its current account to the wall (its existing all-exhausted stay-put already squeezes it).
+- Automatic lateral moves stay within the incumbent organization, and a crossed bar can trigger a cross-organization handoff.
+- Organization preference requires measured headroom in every applicable window and is an optimization heuristic, not a cache-hit guarantee.
+- Manual switching retains pure pace-pressure ranking.
+- Successful candidate probes persist their results and restart selection, preserving candidates that fail a screening bar but still clear the wall.
+- Verification attempts at most two candidates with a shared 12-second deadline per candidate for identity reads and CLI execution.
+- Expiring access tokens are not refreshed for verification, and the isolated CLI receives no refresh grant.
+- Failed or budget-limited verification uses the existing cached data, so stale-target handoffs remain possible.
+
+The [profile](docs/content/docs/switching-profile.mdx) distinguishes observed cache rewrites from pricing-weighted estimates and does not infer subscription quota savings.
+
+The [wall policy](docs/content/docs/switching.mdx#the-wall) defines Layer 2 recovery and its conditional headroom preference, with pace-only selection under default bars.
+
+- Layer 2 is Claude-only because its running sessions can adopt a credential change.
+- Codex keeps its current account until the wall because a running sibling cannot adopt another account without restarting.
 
 **Model-aware trigger.** Claude subscriptions also enforce **per-model weekly caps** - currently only for Sonnet and Fable (there is no Opus-only quota), and Fable's tighter limit binds *before* the aggregate (e.g. 80% week-Fable at only 50% week-all-models). This cap isn't in statusLine stdin, so when the active model is in `policy.switchModels` we read it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) and add `week(<activeModel>) >= threshold` to the trigger. A Fable session switches on the Fable cap; a Sonnet session rides the aggregate. Both layers apply the per-model gate: a burnt Fable cap screens an account out of a Layer 1 switch, and a Fable cap at the wall screens it out of the Layer 2 squeeze too.
 

package/README.md

@@ -87,7 +87,14 @@ Switching engages (configurable) once the active account's 5-hour session window
 
 The bars' headroom is deliberate: it's the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the wall. The session ladder tops out lower (90) because a 5-hour reset is cheap to sit out, and any lower rungs you add keep the pool draining level by level; weekly quota is use-it-or-lose-it, so it drains closer to the wall (98). The greedy engagement floor (80) sits below both: weekly allowance is forfeited at each account's fixed reset, so once most of a session window is spent, quota is best burned on whichever account has the most at risk.
 
-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.
+Automatic selection prefers same-organization candidates with measured session and weekly headroom, then uses remaining weekly percentage divided by time to reset.
+
+- Lateral moves stay within the current organization, while a crossed bar or enforced limit may trigger a cross-organization handoff.
+- Candidate verification makes at most two bounded `/usage` attempts per evaluation and re-ranks successful samples before switching.
+- Failed verification leaves cached figures in force, so it cannot guarantee a fresh target.
+- Manual `tokenmaxxing switch` retains pure pace-pressure selection.
+
+See [How switching decides](docs/content/docs/switching.mdx) for the policy and the [cache-cost profile](docs/content/docs/switching-profile.mdx) for measurements and their limits.
 
 ## Configuration
 

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tokenmaxxing",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "description": "Pool Claude Code and Codex logins, switch on pace pressure, and expose safe ops tools to agent clients.",
   "author": {
     "name": "anaclumos",

package/agent-plugin/skills/switching-policy/SKILL.md

@@ -8,8 +8,13 @@ description: Explain and apply tokenmaxxing switch policy (greedy vs hard path,
 ## Vocabulary
 
 - **Engaged**: session used >= `policy.greedySessionFloor` (default 80) or any screening bar crossed.
-- **GREEDY path**: engaged but under every bar. Rank all accounts by pace pressure; keep seat on best-or-tie (`currentWins`); else swap to strictly better. Never depleted-waits or pre-parks. The automatic path adds incumbent hysteresis (`policy.greedySwapMargin`, default 0.15): hold the seat unless a parked account's pace pressure exceeds the current one's by more than that fraction, so near-tied accounts stop trading the seat and busting the per-org prompt cache. The margin gates lateral under-bar swaps only, never a crossed bar or the wall; bare `tokenmaxxing switch` uses margin 0 and always takes the strictly best account.
-- **HARD path**: a screening bar crossed. Swap to best usable target; if none, Layer 2 wall logic (Claude only).
+- **GREEDY path** permits lateral moves only within the incumbent organization and retains `greedySwapMargin` hysteresis.
+- **HARD path** starts at a crossed screening bar and may cross organizations, with Layer 2 as its fallback.
+- **Organization preference** requires measured headroom in session, aggregate weekly and gated model windows under the [policy](references/policy.md).
+- **Verification** attempts at most two stale candidates per evaluation, with a 12-second deadline covering identity reads and the CLI for each candidate.
+- **Probe results** are persisted and re-ranked, while screening exhaustion remains eligible for the wall squeeze and reset selection.
+- **Unavailable verification** leaves cached figures in force, and verification never spends a parked refresh grant.
+- **Manual switch** retains pure pace ranking with no organization preference or incumbent margin.
 - **Pace pressure**: remaining weekly percent / time to weekly reset (highest first). Not most-remaining.
 - **Effective bars**: `effectiveBars(cfg, pool)` = the active rung of the 5h ladder (`thresholds.session`, default `[90]`, a single rung: the lowest rung some pooled account, the current one included, still clears) and the weekly bar, each minus `policy.projectionMargin`. Trigger and screening must share these bars or swaps ping-pong. Codex reads `terminalBars(cfg)`, the top rung only. The check cadence is capped one band per rung climbed, and every band is a multiple of the tick `policy.checkIntervalMs` (default 60000).
 - **Banked reset**: opt-in via `policy.preferToUseBankedReset` (a provider list, default `[]`), hard path only. Claude: the seat holds between the session rung and the wall while a reset is believed available and the weekly windows have room for one more measured session window (`sessionWindowWeeklyCost`; unmeasured swaps), claims the `/limit-reset` server call at the wall, and keeps the seat on `reset` (the failed turn is retriggered in place). Codex: rides to the wall while a reset credit exists, consumes one, no restart. The greedy path never resets.

package/agent-plugin/skills/switching-policy/references/policy.md

@@ -3,6 +3,8 @@
 - `docs/content/docs/switching.mdx`
 - `src/lib/decide.ts`, `src/lib/picker.ts`
 - `src/lib/bankedreset.ts`, `src/lib/codexreset.ts` (banked limit resets)
-- `.memory/switch-policy-pace-pressure.md`
+- `.cursor/rules/switch-verification.md`
 
-Default screening bars: session ladder [90] (a single rung; add lower rungs such as [50, 80, 95] to hand off earlier) with the active rung resolved per pool, weekly 98. Engagement floor 80. Wall defaults 100. Cooldown 45s on the automatic path after a swap. Check tick `policy.checkIntervalMs` (default 60000, minimum 10000); `init` writes it into the timer unit. Check cadence ceiling per rung: five ticks, three, two, then the one-tick floor, with the headroom bands at the same multiples (40 points sleeps five ticks, 20 three, 8 two, less every tick). Banked resets off by default (`policy.preferToUseBankedReset: []`); Claude claims once a week per account at the wall, Codex consumes one credit at the wall.
+Automatic organization preference requires session usage below `greedySessionFloor` and more than `max(1, session bar - greedySessionFloor)` points below every applicable bar.
+
+The exact policy, defaults, verification limits and manual-switch behavior live in `docs/content/docs/switching.mdx`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.19.1",
+  "version": "1.20.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",

package/src/cli/switch.ts

@@ -7,6 +7,7 @@ import { currentWins, effectiveBars, pickBest, pickEarliestReset, weeklyExpiry,
 import { InvalidGrantError } from "../lib/oauth.ts";
 import { gatedFamilies } from "../lib/usage.ts";
 import { findAccount } from "./rename.ts";
+import { log } from "../lib/log.ts";
 import { c, emitError, emitJson, fmtReset } from "./render.ts";
 import type { Account } from "../lib/types.ts";
 
@@ -44,6 +45,7 @@ export async function cmdSwitch(selector?: string, json = false): Promise<number
         }
         throw e;
       }
+      log("switch.manual", { account: target.accountUuid.slice(0, 8), reason });
       emit(`${c.green("↻")} switched to ${c.bold(target.label)}`, { switched: true, account: target.label, reason, ...extra });
       return 0;
     };
@@ -69,12 +71,12 @@ export async function cmdSwitch(selector?: string, json = false): Promise<number
     const rejected = new Set<string>();
     while (true) {
       const cur = loadAccounts();
-      const everyone = everyoneIn(cur.accounts);
       const pool = cur.accounts.filter((a) => !rejected.has(a.accountUuid));
       const active =
         (claimed != null ? cur.accounts.find((a) => a.accountUuid === claimed) : null) ??
         cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ??
         null;
+      const everyone = everyoneIn(cur.accounts);
       if (active != null && currentWins(active, pool, everyone)) {
         if (drifted) return swapTo(active, "drift-reconciled");
         const expiry = weeklyExpiry(active, now);
@@ -104,6 +106,7 @@ export async function cmdSwitch(selector?: string, json = false): Promise<number
         }
         throw e;
       }
+      log("switch.manual", { account: best.accountUuid.slice(0, 8), reason: "best" });
       emit(`${c.green("↻")} switched to ${c.bold(best.label)}`, { switched: true, account: best.label, reason: "best" });
       return 0;
     }
@@ -159,6 +162,7 @@ export async function cmdSwitch(selector?: string, json = false): Promise<number
         }
         throw e;
       }
+      log("switch.manual", { account: earliest.account.accountUuid.slice(0, 8), reason: "earliest-reset" });
       emit(`${c.green("↻")} switched to ${c.bold(earliest.account.label)}`, { switched: true, account: earliest.account.label, reason: "earliest-reset", availableAt, reauthNeeded: reauth });
       if (availableAt != null && !json) {
         console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(availableAt, now)})${reauthNote}`));

package/src/lib/decide.ts

@@ -5,8 +5,9 @@ import { paths } from "./paths.ts";
 import { MAX_CHECK_DELAY_TICKS, POST_SWAP_COOLDOWN_MS, maxCheckDelayMs, loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadUsageSnapshot, loadModelUsage, measureFamilyWindow, saveAccounts, saveDepletedWait, saveModelUsage, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { bankedResetBelievedAvailable, claimBankedReset } from "./bankedreset.ts";
-import { chooseAndSwap, isSkippableSwapError, performSwap } from "./swap.ts";
-import { currentWins, effectiveBars, hardBars, isExhausted, nextWeeklyReset, pickBest, pickEarliestReset, sessionLadder, usableAt } from "./picker.ts";
+import { chooseAndSwap, isSkippableSwapError, performSwap, type VerifyVerdict } from "./swap.ts";
+import { probeParkedUsage } from "./sample.ts";
+import { currentWins, effectiveBars, hardBars, isExhausted, nextWeeklyReset, pickBest, pickEarliestReset, sessionLadder, usableAt, type PickCtx } from "./picker.ts";
 import { familyTokens, gatedFamilies, probeUsage, type EnforcedClass } from "./usage.ts";
 import { log } from "./log.ts";
 import { AccountSchema, ModelUsageStateSchema, UsageStateSchema, type Account, type Config, type EnforcedLimit, type ModelUsageState, type Thresholds, type UsageState, type UsageWindow } from "./types.ts";
@@ -22,6 +23,8 @@ export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+const VERIFY_PROBE_BUDGET = 2;
+const VERIFY_PROBE_KILL_MS = 12_000;
 
 function liveUsed(input: { window: UsageWindow; windowMs: number; sampledAt: number; now: number }): number {
   const { window: w, windowMs, sampledAt, now } = input;
@@ -253,18 +256,60 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       rejected.add(candidate.accountUuid);
       log("decide.candidate_rejected", { account: candidate.accountUuid.slice(0, 8), error: e instanceof Error ? e.message : String(e) });
     };
+    let probeBudget = VERIFY_PROBE_BUDGET;
+    const verified = async (candidate: Account, ctx: PickCtx): Promise<VerifyVerdict> => {
+      if (candidate.lastUsageAt != null && now - candidate.lastUsageAt <= cfg.policy.usagePollTtlMs) return "go";
+      const short = candidate.accountUuid.slice(0, 8);
+      const idx2 = loadAccounts();
+      const stored = idx2.accounts.find((a) => a.accountUuid === candidate.accountUuid);
+      if (!stored) return "go";
+      if (probeBudget <= 0) {
+        log("decide.verify_budget_spent", { account: short });
+        return "go";
+      }
+      probeBudget -= 1;
+      const sample = await probeParkedUsage(stored, { retries: 0, refreshParked: false, killMs: VERIFY_PROBE_KILL_MS, signal: AbortSignal.timeout(VERIFY_PROBE_KILL_MS) });
+      if (sample.ok) {
+        const at = Date.now();
+        stored.lastUsage = { fiveHour: sample.usage.session, sevenDay: sample.usage.weekAll };
+        stored.lastUsageAt = at;
+        if (Object.keys(sample.usage.perModel).length > 0) {
+          stored.lastPerModel = sample.usage.perModel;
+          stored.lastPerModelAt = at;
+        }
+      }
+      if (sample.ok || stored.needsReauth === true) saveAccounts(idx2);
+      if (stored.needsReauth === true) {
+        rejected.add(candidate.accountUuid);
+        log("decide.candidate_rejected", { account: short, error: "needs reauth" });
+        return "skip";
+      }
+      if (!sample.ok) {
+        log("decide.candidate_unverified", { account: short });
+        return "go";
+      }
+      log(isExhausted(stored, ctx) ? "decide.candidate_walled" : "decide.candidate_verified", {
+        account: short,
+        session: sample.usage.session.usedPercentage,
+        weekly: sample.usage.weekAll.usedPercentage,
+      });
+      return "rerank";
+    };
 
     const greedy = async (holdMargin: number): Promise<SwapDecision> => {
       while (true) {
         const cur = loadAccounts();
         const active = seatOf(cur);
-        const pool = usable(cur.accounts);
-        const ctxAll = { now, thresholds: barsOf(cur.accounts), currentAccountUuid: null, switchFamilies, holdMargin };
+        const ctxAll = { now, thresholds: barsOf(cur.accounts), currentAccountUuid: null, currentOrganizationUuid: active?.organizationUuid ?? null, orgAffinityFloor: cfg.policy.greedySessionFloor, switchFamilies, holdMargin };
+        const seatOrg = active != null && !active.needsReauth && !isExhausted(active, ctxAll) ? active.organizationUuid : null;
+        const pool = usable(cur.accounts).filter((a) => seatOrg == null || a.organizationUuid === seatOrg);
         if (currentWins(active, pool, ctxAll)) {
           return { swapped: false, account: null, reason: "current-best" };
         }
-        const best = pickBest(pool, { ...ctxAll, currentAccountUuid: active?.accountUuid ?? null });
+        const ctx = { ...ctxAll, currentAccountUuid: active?.accountUuid ?? null };
+        const best = pickBest(pool, ctx);
         if (!best) return { swapped: false, account: null, reason: "no-usable-target" };
+        if ((await verified(best, ctx)) !== "go") continue;
         try {
           await performSwap(best);
         } catch (e) {
@@ -297,14 +342,17 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
           if (claim === "reset") return { swapped: false, account: seat, reason: "banked-reset", reset: true };
         }
       }
-      const best = pickBest(pool, { now, thresholds, currentAccountUuid: seat?.accountUuid ?? null, switchFamilies });
+      const ctx = { now, thresholds, currentAccountUuid: seat?.accountUuid ?? null, currentOrganizationUuid: seat?.organizationUuid ?? null, orgAffinityFloor: cfg.policy.greedySessionFloor, switchFamilies };
+      const best = pickBest(pool, ctx);
       if (!best) break;
+      if ((await verified(best, ctx)) !== "go") continue;
       try {
         await performSwap(best);
       } catch (e) {
         skipOrThrow(e, best);
         continue;
       }
+      log("decide.hard_swap", { account: best.accountUuid.slice(0, 8), enforced: enforced2 != null });
       return { swapped: true, account: best, reason: "swapped" };
     }
 
@@ -314,7 +362,7 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       log("decide.last_drop_hold", { account: seat.accountUuid.slice(0, 8) });
       return { swapped: false, account: null, reason: "last-drop-hold" };
     }
-    const squeezed = await chooseAndSwap({ ...hardCtx, currentAccountUuid: seat?.accountUuid ?? null }, rejected);
+    const squeezed = await chooseAndSwap({ ...hardCtx, currentAccountUuid: seat?.accountUuid ?? null, currentOrganizationUuid: seat?.organizationUuid ?? null, orgAffinityFloor: cfg.policy.greedySessionFloor }, rejected, verified);
     if (squeezed) {
       log("decide.last_drop_swap", { account: squeezed.accountUuid.slice(0, 8) });
       return { swapped: true, account: squeezed, reason: "last-drop-swap" };

package/src/lib/oauth.ts

@@ -94,11 +94,12 @@ export function isAccessTokenExpiring(creds: OAuthCreds, skewMs = 120_000, now =
   return !creds.expiresAt || creds.expiresAt - now <= skewMs;
 }
 
-export async function fetchTokenIdentity(accessToken: string): Promise<TokenIdentity> {
+export async function fetchTokenIdentity(accessToken: string, signal?: AbortSignal): Promise<TokenIdentity> {
   let res: Response;
   try {
     res = await http.get(PROFILE_URL, {
       headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+      signal,
     });
   } catch (e) {
     throw new IdentityUnavailableError(null, e instanceof Error ? e.message : String(e));

package/src/lib/picker.ts

@@ -34,6 +34,8 @@ const PickCtxSchema = z.object({
   now: z.number(),
   thresholds: ThresholdsSchema,
   currentAccountUuid: z.string().nullable(),
+  currentOrganizationUuid: z.string().nullable().optional(),
+  orgAffinityFloor: z.number().optional(),
   switchFamilies: z.array(z.string()),
   holdMargin: z.number().min(0).optional(),
 });
@@ -94,9 +96,27 @@ export function pacePressure(a: Account, now: number): number {
   return Math.max(0, 100 - used) / Math.max(1, reset - now);
 }
 
-const swapPreference = (now: number) => [
-  (a: Account) => -pacePressure(a, now),
-  (a: Account) => weeklyExpiry(a, now),
+function sessionUsed(a: Account, now: number): number {
+  const w = a.lastUsage?.fiveHour;
+  if (w == null) return 101;
+  if (w.resetsAt != null) return w.resetsAt <= now ? 0 : w.usedPercentage;
+  if (a.lastUsageAt != null && now >= a.lastUsageAt + FIVE_HOURS_MS) return 0;
+  return w.usedPercentage;
+}
+
+function orgTier(a: Account, ctx: PickCtx): number {
+  if (ctx.currentOrganizationUuid == null || a.organizationUuid !== ctx.currentOrganizationUuid) return 1;
+  if (ctx.orgAffinityFloor != null && sessionUsed(a, ctx.now) >= ctx.orgAffinityFloor) return 1;
+  if (!a.lastUsage || ctx.switchFamilies.some((family) => gatedPerModelWindows(a, [family]).length === 0)) return 1;
+  const headroom = Math.max(1, ctx.thresholds.session - (ctx.orgAffinityFloor ?? ctx.thresholds.session));
+  if (isExhausted(a, { ...ctx, thresholds: { session: ctx.thresholds.session - headroom, weekly: ctx.thresholds.weekly - headroom } })) return 1;
+  return 0;
+}
+
+const swapPreference = (ctx: PickCtx) => [
+  (a: Account) => orgTier(a, ctx),
+  (a: Account) => -pacePressure(a, ctx.now),
+  (a: Account) => weeklyExpiry(a, ctx.now),
   (a: Account) => a.lastUsage?.sevenDay.usedPercentage ?? 101,
 ];
 
@@ -104,7 +124,7 @@ export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   const usable = accounts.filter(
     (a) => a.accountUuid !== ctx.currentAccountUuid && !a.needsReauth && !isExhausted(a, ctx),
   );
-  return sortBy(usable, swapPreference(ctx.now))[0] ?? null;
+  return sortBy(usable, swapPreference(ctx))[0] ?? null;
 }
 
 export function currentWins(active: Account | null, accounts: Account[], ctx: PickCtx): boolean {
@@ -114,7 +134,7 @@ export function currentWins(active: Account | null, accounts: Account[], ctx: Pi
   const margin = ctx.holdMargin ?? 0;
   const bestPace = pacePressure(best, ctx.now);
   if (margin > 0 && bestPace > 0 && bestPace <= pacePressure(active, ctx.now) * (1 + margin)) return true;
-  return swapPreference(ctx.now).every((k) => k(active) === k(best));
+  return swapPreference(ctx).every((k) => k(active) === k(best));
 }
 
 export function usableAt(a: Account, ctx: PickCtx): number {

package/src/lib/sample.ts

@@ -24,10 +24,10 @@ const IdentityCheckSchema = z.discriminatedUnion("status", [
 ]);
 type IdentityCheck = z.infer<typeof IdentityCheckSchema>;
 
-async function checkIdentity(creds: OAuthCreds, account: Account): Promise<IdentityCheck> {
+async function checkIdentity(creds: OAuthCreds, account: Account, signal?: AbortSignal): Promise<IdentityCheck> {
   let identity: TokenIdentity;
   try {
-    identity = await fetchTokenIdentity(creds.accessToken);
+    identity = await fetchTokenIdentity(creds.accessToken, signal);
   } catch (e) {
     return {
       status: "unavailable",
@@ -44,7 +44,10 @@ function refreshPlanFields(account: Account, creds: OAuthCreds): void {
   if (creds.rateLimitTier != null) account.rateLimitTier = creds.rateLimitTier;
 }
 
-export async function probeParkedUsage(account: Account, opts: { ping?: boolean } = {}): Promise<SampleOutcome> {
+export async function probeParkedUsage(
+  account: Account,
+  opts: { ping?: boolean; retries?: number; refreshParked?: boolean; killMs?: number; signal?: AbortSignal } = {},
+): Promise<SampleOutcome> {
   const backup = parkedTarget(account.keychainItem);
   const parkedRaw = await readItem(backup);
   if (!parkedRaw) return { ok: false, reason: "no parked credential - run `tokenmaxxing auth`" };
@@ -59,6 +62,9 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     account.needsReauth = true;
     return { ok: false, reason: "parked credential was cleared after a failed refresh - re-auth with `tokenmaxxing auth`" };
   }
+  if (opts.refreshParked === false && isAccessTokenExpiring(creds, 300_000)) {
+    return { ok: false, reason: "parked access token is near expiry - verification requires an unexpired token" };
+  }
 
   const liveRaw = await readItem(liveTarget());
   let liveAccount: string | null = null;
@@ -73,7 +79,7 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     if (!isDeadCredential(liveCreds)) {
       liveToken = liveCreds.accessToken;
       try {
-        liveAccount = (await fetchTokenIdentity(liveCreds.accessToken)).accountUuid;
+        liveAccount = (await fetchTokenIdentity(liveCreds.accessToken, opts.signal)).accountUuid;
       } catch (e) {
         return { ok: false, reason: `cannot verify the live credential's owner (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - refusing to sample a possibly-live account` };
       }
@@ -92,6 +98,9 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
   };
 
   if (isAccessTokenExpiring(creds, 300_000)) {
+    if (opts.refreshParked === false) {
+      return { ok: false, reason: "parked access token is near expiry - verification requires an unexpired token" };
+    }
     const owner = await checkIdentity(creds, account);
     if (owner.status === "mismatch") {
       const kept = await relocate(owner.owner);
@@ -136,7 +145,7 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
   }
 
-  const identity = await checkIdentity(creds, account);
+  const identity = await checkIdentity(creds, account, opts.signal);
   if (identity.status === "mismatch") {
     const kept = await relocate(identity.owner);
     account.needsReauth = true;
@@ -151,13 +160,13 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
   const isoTarget = isolatedTarget(dir);
-  const installed = JSON.stringify({ claudeAiOauth: creds });
+  const installed = JSON.stringify({ claudeAiOauth: opts.refreshParked === false ? { ...creds, refreshToken: "" } : creds });
 
   try {
     await writeItem(isoTarget, installed);
     writeFileSync(join(dir, ".claude.json"), JSON.stringify({ oauthAccount: account.oauthAccount, hasCompletedOnboarding: true }));
     const ping = opts.ping ? await pingSession(dir) : null;
-    const usage = await probeUsage(dir);
+    const usage = await probeUsage(dir, Date.now(), opts);
     const outcome: SampleOutcome = usage
       ? { ok: true, usage }
       : { ok: false, reason: "`/usage` returned no limit data (see log)" };
@@ -167,10 +176,15 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     }
     return outcome;
   } finally {
-    const afterIso = await readItem(isoTarget);
-    if (afterIso && afterIso !== installed) await writeItem(backup, claudeAiOauthOnly(afterIso));
-    await deleteItem(isoTarget);
-    rmSync(dir, { recursive: true, force: true });
+    try {
+      if (opts.refreshParked !== false) {
+        const afterIso = await readItem(isoTarget);
+        if (afterIso && afterIso !== installed) await writeItem(backup, claudeAiOauthOnly(afterIso));
+      }
+    } finally {
+      await deleteItem(isoTarget);
+      rmSync(dir, { recursive: true, force: true });
+    }
   }
 }
 

package/src/lib/swap.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { clearDepletedWait, clearNextCheck, clearUsageSnapshots, loadAccounts, saveAccounts, saveLastSwapAt } from "./state.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
 import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity, IdentityUnavailableError, InvalidGrantError, RefreshRejectedError } from "./oauth.ts";
@@ -11,6 +12,9 @@ function parseBlob(raw: string) {
   return CredentialBlobSchema.parse(JSON.parse(raw));
 }
 
+const VerifyVerdictSchema = z.enum(["go", "rerank", "skip"]);
+export type VerifyVerdict = z.infer<typeof VerifyVerdictSchema>;
+
 export async function performSwap(target: Account): Promise<void> {
   const idx = loadAccounts();
 
@@ -196,13 +200,25 @@ export function isSkippableSwapError(e: unknown): boolean {
   return e instanceof InvalidGrantError || e instanceof RefreshRejectedError || e instanceof IdentityUnavailableError;
 }
 
-export async function chooseAndSwap(ctx: PickCtx, exclude: ReadonlySet<string> = new Set()): Promise<Account | null> {
+export async function chooseAndSwap(
+  ctx: PickCtx,
+  exclude: ReadonlySet<string> = new Set(),
+  verify?: (candidate: Account, ctx: PickCtx) => Promise<VerifyVerdict>,
+): Promise<Account | null> {
   const tried = new Set<string>(exclude);
   while (true) {
     const idx = loadAccounts();
     const candidates = idx.accounts.filter((a) => !tried.has(a.accountUuid));
     const best = pickBest(candidates, ctx);
     if (!best) return null;
+    if (verify) {
+      const verdict = await verify(best, ctx);
+      if (verdict === "rerank") continue;
+      if (verdict === "skip") {
+        tried.add(best.accountUuid);
+        continue;
+      }
+    }
     tried.add(best.accountUuid);
     try {
       await performSwap(best);

package/src/lib/usage.ts

@@ -286,9 +286,14 @@ async function spawnClaudeBounded(
   cmd: string[],
   env: Record<string, string>,
   cwd?: string,
+  killMs = PROBE_KILL_MS,
+  signal?: AbortSignal,
 ): Promise<SpawnResult | null> {
+  signal?.throwIfAborted();
   const p = Bun.spawn(cmd, { env, cwd, stdout: "pipe", stderr: "pipe" });
-  const killer = setTimeout(() => p.kill("SIGKILL"), PROBE_KILL_MS);
+  const abort = () => p.kill("SIGKILL");
+  signal?.addEventListener("abort", abort, { once: true });
+  const killer = setTimeout(() => p.kill("SIGKILL"), killMs);
   try {
     const reads = Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
     const settled = await Promise.race([
@@ -301,13 +306,14 @@ async function spawnClaudeBounded(
     return { exitCode: p.exitCode, stdout, stderr };
   } finally {
     clearTimeout(killer);
+    signal?.removeEventListener("abort", abort);
   }
 }
 
-async function probeUsageOnce(env: Record<string, string>, now: number): Promise<FullUsage | null> {
+async function probeUsageOnce(env: Record<string, string>, now: number, killMs: number, signal?: AbortSignal): Promise<FullUsage | null> {
   let out: string;
   try {
-    const r = await spawnClaudeBounded([resolveRealClaude(), "-p", "/usage", "--output-format", "json"], env);
+    const r = await spawnClaudeBounded([resolveRealClaude(), "-p", "/usage", "--output-format", "json"], env, undefined, killMs, signal);
     if (r === null) {
       log("usage.probe_failed", { err: "output pipes still open after child exit (leaked descendant)" });
       return null;
@@ -345,17 +351,17 @@ function probeEnv(configDir?: string): Record<string, string> {
   return env;
 }
 
-export async function probeUsage(configDir?: string, now = Date.now()): Promise<FullUsage | null> {
+export async function probeUsage(configDir?: string, now = Date.now(), opts: { retries?: number; killMs?: number; signal?: AbortSignal } = {}): Promise<FullUsage | null> {
   const env = probeEnv(configDir);
 
   for (let attempt = 0; ; attempt++) {
-    const full = await probeUsageOnce(env, now);
+    const full = await probeUsageOnce(env, now, opts.killMs ?? PROBE_KILL_MS, opts.signal);
     if (full) return full;
-    if (attempt >= PROBE_RETRY_DELAYS_MS.length) {
+    if (attempt >= (opts.retries ?? PROBE_RETRY_DELAYS_MS.length) || opts.signal?.aborted) {
       log("usage.probe_gave_up", { attempts: attempt + 1 });
       return null;
     }
-    await delay(PROBE_RETRY_DELAYS_MS[attempt]!);
+    await delay(PROBE_RETRY_DELAYS_MS[Math.min(attempt, PROBE_RETRY_DELAYS_MS.length - 1)]!);
   }
 }