tokenmaxxing 0.8.0 → 0.9.0

package/README.md

@@ -39,6 +39,7 @@ 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) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.8.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/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/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]);