tokenmaxxing 0.7.0 → 0.9.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 **95%** 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 **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.
 
 > Scope: **Claude Code only, macOS first.** Codex and other CLIs deferred (see `.memory/cc-codex-auth-mechanics.md`).
 >
@@ -12,7 +12,7 @@ Automatic Claude Code account switching. You run `claude` exactly as always; whe
 
 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.
 
-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 95%: the 5% headroom is the budget to reach a clean turn boundary and respawn before the account actually hits the wall.**
+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.**
 
 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 `< 95%` (metered per `organizationUuid`).
+1. Read `usage.json`; `exit 0` fast if both windows `< 98%` (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 95%, 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 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.")
 
 ---
 
@@ -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 >= 95%` OR `seven_day >= 95%`, per org. "Exhausted" is a **timestamped state** (`resets_at`), not a flag - an account is a candidate again after it resets. Optional projected threshold (`95 − EMA(per-turn Δ%)`) so a single large turn can't blow past 100% before the next Stop hook.
+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.
 
 **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 >= 95%` OR `seven_day >= 95%`, 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 <95% 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 <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.
 - **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 >= 95%` OR `seven_day >= 95%`, per org. "Exhausted" is a *
 ---
 
 ## 7. Scope
-**v1:** `tokenmaxxing init` / `add` / `ls` / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; 95% 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; 98% 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

@@ -39,18 +39,19 @@ 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 **95%** (configurable) on any of:
+Switching triggers at **98%** (configurable) 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 5% headroom is deliberate: it's the budget to reach a clean turn boundary and respawn before the wall.
+The 2% headroom is deliberate: it's the budget to reach a clean turn boundary and respawn before the wall.
 
 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.
 
@@ -60,7 +61,7 @@ The **target** is chosen greedily off each account's cached windows: the usable
 
 ```json
 {
-  "threshold": 95,
+  "threshold": 98,
   "policy": {
     "projectionMargin": 0,
     "switchModels": ["fable"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.7.0",
+  "version": "0.9.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,6 +4,13 @@
 // 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";
@@ -15,7 +22,7 @@ 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,18 +56,34 @@ 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);
@@ -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/lib/claudelock.ts

@@ -3,7 +3,7 @@
 // npm `proper-lockfile` (mkdir-based) at <claudeDir>/.oauth_refresh.lock - the
 // lock is the DIRECTORY itself. We mkdir it; on contention we wait briefly, then
 // proceed anyway (our own flock already serializes tokenmaxxing swaps, and claude
-// only refreshes near token expiry / on 401, rarely at the 95% usage trigger).
+// only refreshes near token expiry / on 401, rarely at the 98% usage trigger).
 
 import { mkdirSync, rmdirSync, statSync } from "node:fs";
 import { join } from "node:path";

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,7 +20,7 @@ import {
 // ---- config.json (minimal, fixed schema) ---------------------------------
 
 const DEFAULT_CONFIG: Config = {
-  threshold: 95,
+  threshold: 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.

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]);