tokenmaxxing 1.13.1 → 1.15.0

package/DESIGN.md

@@ -37,7 +37,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
   - `bin/claude` - the supervisor.
 - Per-account **credentials** follow the platform's Claude Code store: macOS = login-keychain items `tokenmaxxing-cred-<accountUuid[:8]>` (never plaintext on disk); Linux = 0600 files `creds/tokenmaxxing-cred-<accountUuid[:8]>.json` (the same plaintext model claude itself uses - its Linux build has no keyring path at all, binary-verified 2.1.205). One `credstore` facade dispatches on a `{kind: keychain|file}` target; call sites never branch on platform.
 
-- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check --if-due` every 60s, self-paced up to 300s from the live account's headroom: hooks alone miss long agentic turns, so the timer is the backstop that keeps switching engaged mid-turn.
+- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check --if-due` once per tick (`policy.checkIntervalMs`, 60s by default), self-paced up to five ticks from the live account's headroom: hooks alone miss long agentic turns, so the timer is the backstop that keeps switching engaged mid-turn.
 
 The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. The `claude` binary and `~/.claude` layout are untouched.
 

package/README.md

@@ -70,7 +70,7 @@ claude                  # use claude as always
 | `tokenmaxxing switch --codex [sel]` | switch the codex pool (takes effect on the next codex start) |
 | `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 status --ping [--count N]` | additionally ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; `--count N` pings N randomly picked accounts instead, to stagger the resets |
 | `tokenmaxxing watch [seconds]` | live status: re-render every N seconds (default 120, floor 30; never pings) |
 | `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
@@ -100,12 +100,13 @@ The **target** is chosen greedily off each account's cached windows: among usabl
     "projectionMargin": 0,
     "greedySessionFloor": 80,
     "switchModels": ["fable"],
-    "usagePollTtlMs": 90000
+    "usagePollTtlMs": 90000,
+    "checkIntervalMs": 60000
   }
 }
 ```
 
-`thresholds.session` is a ladder: the bar is the lowest rung some pooled account still clears, so the default `[90]` is one bar, while with `[50, 80, 95]` a seat past 50 hands off while a sibling is under 50, and the bar climbs to 80 and then 95 as the whole pool fills; `projectionMargin` is a fixed safety margin subtracted from each threshold bar (effective bar = threshold - margin), so a large turn is less likely to blow past a bar between checks; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers).
+`thresholds.session` is a ladder: the bar is the lowest rung some pooled account still clears, so the default `[90]` is one bar, while with `[50, 80, 95]` a seat past 50 hands off while a sibling is under 50, and the bar climbs to 80 and then 95 as the whole pool fills; `projectionMargin` is a fixed safety margin subtracted from each threshold bar (effective bar = threshold - margin), so a large turn is less likely to blow past a bar between checks; `greedySessionFloor` is the session-used % at which the greedy convergence engages; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` per-model poll stays fresh; `maxWaitMs` bounds the depleted-pool countdown - a soonest reset further out than this does not pause the session (no respawn marker is written and the session simply keeps hitting its limit until an account recovers); `checkIntervalMs` is the periodic check tick (default 60s), which `init` writes into the timer and which every headroom band is a multiple of, one tick near a bar up to five with plenty of headroom (a depleted wait and the post-swap cooldown sleep to their own deadlines instead) - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick.
 
 State lives entirely in `~/.config/tokenmaxxing/`. Per-account credentials follow the platform's Claude Code store: the login keychain on macOS (`tokenmaxxing-cred-<uuid8>` items, never plaintext on disk), 0600 files under `~/.config/tokenmaxxing/creds/` on Linux (the same plaintext model claude itself uses for `~/.claude/.credentials.json`).
 

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tokenmaxxing",
-  "version": "1.13.1",
+  "version": "1.15.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/pool-status/SKILL.md

@@ -10,18 +10,18 @@ description: Read the Claude and Codex account pool safely (list, usage bars, wa
 - `pool_ls` for labels, active marker, needs-reauth
 - `pool_status` for 5h / weekly / per-model bars (free `/usage` path)
 
-If MCP is unavailable, run `tokenmaxxing ls --json` or `tokenmaxxing status --json` (alias `xx`) and parse the document. Never add `--force`.
+If MCP is unavailable, run `tokenmaxxing ls --json` or `tokenmaxxing status --json` (alias `xx`) and parse the document. Never add `--ping`.
 
 ## Hard stops
 
-- Do not run `status --force` or bare `xx --force`. That pings every account with a real request and opens each 5h window.
+- Do not run `status --ping` or bare `xx --ping`. That pings every account with a real request and opens each 5h window.
 - Do not print credential files, keychain blobs, or OAuth tokens. Labels and status only.
 - Do not kill sessions or supervisors to "free" an account.
 
 ## Notes
 
 - Active Claude usage often comes from the statusLine tee; parked accounts are probed in isolation.
-- `watch` re-renders status on an interval and never force-pings.
+- `watch` re-renders status on an interval and never pings.
 - Hermetic agents: set `TOKENMAXXING_HOME` to a throwaway directory. That isolates state files only: `init`, `uninstall`, and the codex hook install still write settings.json, codex `hooks.json`, the shell rc, and the timer unit under `HOME`, so never run them from an agent.
 
 See [references/commands.md](references/commands.md).

package/agent-plugin/skills/pool-status/references/commands.md

@@ -1,9 +1,9 @@
 # Status and list commands
 
 - `tokenmaxxing` / `tokenmaxxing status`: sample and show bars; persists cached usage for the picker.
-- `tokenmaxxing status --force`: DENIED for agents without explicit user approval. Meters every account.
+- `tokenmaxxing status --ping [--count N]`: DENIED for agents without explicit user approval. Meters every account, or N random ones under `--count`.
 - `tokenmaxxing ls`: compact list.
-- `tokenmaxxing watch [seconds]`: live re-render (default 120), never `--force`.
+- `tokenmaxxing watch [seconds]`: live re-render (default 120), never `--ping`.
 - `--json` on any of these: one JSON document on stdout (`ok` mirrors the exit code); parse it instead of scraping the bars. `watch --json` prints one document per tick and never exits on its own.
 
 Docs: `docs/content/docs/commands.mdx`.

package/agent-plugin/skills/safe-contribution/SKILL.md

@@ -9,11 +9,11 @@ description: Safely change and ship tokenmaxxing (verification without a test su
 
 - The repo carries no test code and no comments (owner ruling 2026-09-02). Never add tests, a test script, or comments.
 - Verify with `bun run typecheck`, then hermetic CLI runs: `TOKENMAXXING_HOME=/tmp/xx-test bun run src/main.ts ...` (for decision-path changes, write accounts.json, usage.json, config.json, and a claude.json under that root and run `check`; point `TOKENMAXXING_KEYCHAIN_SERVICE` and `TOKENMAXXING_KEYCHAIN_ACCOUNT` at throwaway names and `TOKENMAXXING_CLAUDE_JSON` at that claude.json, because the CLI resolves claude.json from HOME, not from `TOKENMAXXING_HOME`).
-- Ask before any run that meters real quota (`status --force`, live-pool inference). Free `/usage` / plain status is fine.
+- Ask before any run that meters real quota (`status --ping`, live-pool inference). Free `/usage` / plain status is fine.
 
 ## Ship
 
-- Work on a branch; bump `package.json` in the same PR; open PR; wait the full review window; handle every review; merge; `gh release create v<version>`; verify npm publish.
+- Work on a branch; bump `package.json` and `agent-plugin/plugin.json` to the same version in the same PR; open PR; wait the full review window; handle every review; merge; `gh release create v<version>`; verify npm publish.
 - Never push directly to main. npm trusted publishing is bound to workflow filename `ci.yml`.
 
 ## Machine gotchas

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

@@ -11,7 +11,7 @@ description: Explain and apply tokenmaxxing switch policy (greedy vs hard path,
 - **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).
 - **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.
+- **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).
 
 ## Layer 2 (Claude only)
 

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

@@ -4,4 +4,4 @@
 - `src/lib/decide.ts`, `src/lib/picker.ts`
 - `.memory/switch-policy-pace-pressure.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 cadence ceiling per rung: 300s, 180s, 120s, then the 60s floor.
+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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.13.1",
+  "version": "1.15.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/check.ts

@@ -1,21 +1,21 @@
-import { CHECK_DELAY_FLOOR_MS, checkDelayMs, evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { checkDelayMs, evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { log } from "../lib/log.ts";
 import { loadConfig, loadNextCheckDueAt, saveNextCheckDueAt } from "../lib/state.ts";
 import { c, emitError, emitJson, fmtReset } from "./render.ts";
 
-const TICK_SLACK_MS = CHECK_DELAY_FLOOR_MS / 2;
-
 export async function cmdCheck(args: string[] = [], json = false): Promise<number> {
   const now = Date.now();
-  const dueAt = args.includes("--if-due") ? loadNextCheckDueAt(now) : null;
-  if (dueAt != null && now + TICK_SLACK_MS < dueAt) {
-    if (json) emitJson({ ok: true, due: false, nextCheckAt: dueAt });
-    else console.log(c.dim(`not due (${Math.ceil((dueAt - now) / 1000)}s)`));
-    return 0;
-  }
+  let cfg;
   let d;
   try {
+    cfg = loadConfig();
+    const dueAt = args.includes("--if-due") ? loadNextCheckDueAt({ now, cfg }) : null;
+    if (dueAt != null && now + cfg.policy.checkIntervalMs / 2 < dueAt) {
+      if (json) emitJson({ ok: true, due: false, nextCheckAt: dueAt });
+      else console.log(c.dim(`not due (${Math.ceil((dueAt - now) / 1000)}s)`));
+      return 0;
+    }
     d = await evaluateAndMaybeSwap(now);
   } catch (e) {
     const detail = e instanceof Error ? e.message : String(e);
@@ -23,7 +23,7 @@ export async function cmdCheck(args: string[] = [], json = false): Promise<numbe
     emitError({ json, message: `check failed: ${detail}` });
     return 1;
   }
-  const delayMs = checkDelayMs({ cfg: loadConfig(), org: readOAuthAccount()?.organizationUuid ?? null, now, decision: d });
+  const delayMs = checkDelayMs({ cfg, org: readOAuthAccount()?.organizationUuid ?? null, now, decision: d });
   saveNextCheckDueAt({ dueAt: now + delayMs, ts: now });
   if (json) {
     emitJson({

package/src/cli/config.ts

@@ -20,8 +20,11 @@ export const KNOWN_KEYS = [
   "policy.switchModels",
   "policy.usagePollTtlMs",
   "policy.maxWaitMs",
+  "policy.checkIntervalMs",
 ] as const;
 
+const TIMER_REWRITE_NOTE = "note: run `tokenmaxxing init` to rewrite the periodic timer at the new tick";
+
 const RawFileSchema = z.record(z.string(), z.unknown());
 
 function readRawFile(): Record<string, unknown> {
@@ -150,6 +153,7 @@ function cmdSet(key: string, valueText: string, json: boolean): number {
     `${key}: ${beforeFile === undefined ? "(default)" : JSON.stringify(beforeFile)} -> ${JSON.stringify(get(next, key))}`,
   );
   if (env) console.log(c.yellow(`note: ${env} is set and overrides the file value in this environment`));
+  if (key === "policy.checkIntervalMs") console.log(c.yellow(TIMER_REWRITE_NOTE));
   return 0;
 }
 
@@ -189,6 +193,7 @@ function cmdUnset(key: string, json: boolean): number {
     return 0;
   }
   console.log(`${key} unset -> ${JSON.stringify(value)} (default)`);
+  if (key === "policy.checkIntervalMs") console.log(c.yellow(TIMER_REWRITE_NOTE));
   return 0;
 }
 

package/src/cli/init.ts

@@ -28,7 +28,7 @@ function ensurePathAhead(): void {
 }
 
 function reportTimer(out: InstallOutcome): void {
-  if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every 3m)`);
+  if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every ${out.checkIntervalS}s)`);
   else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
 }
 
@@ -37,7 +37,7 @@ export function printUsage(): void {
   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 status --ping")}   ping every account (one tiny haiku request each) so all 5h timers start now, then sample fresh; ${c.cyan("--count N")} pings N random accounts instead`);
   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`);

package/src/cli/status.ts

@@ -1,4 +1,4 @@
-import { sortBy } from "es-toolkit";
+import { sampleSize, sortBy } from "es-toolkit";
 import { z } from "zod";
 import { loadAccounts, loadConfig, loadUsage, loadUsageSnapshot, loadModelUsage, saveAccounts } from "../lib/state.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
@@ -86,14 +86,31 @@ function currentCodexWindow(w: CodexWindow, now: number): CodexWindow {
   return { ...currentWindow(w, !isSessionWindow({ window: w }), now), windowSeconds: w.windowSeconds };
 }
 
-async function collectClaude(input: { cfg: Config; force: boolean; now: number }): Promise<StatusReport["claude"]> {
-  const { cfg, force, now } = input;
+function pickForPing(accounts: Account[], pingCount: number | undefined): Account[] {
+  if (pingCount == null) return accounts;
+  const usable = accounts.filter((a) => a.needsReauth !== true);
+  return sampleSize(usable, Math.min(pingCount, usable.length));
+}
+
+function progressNote(input: { ping: boolean; pingCount: number | undefined; picked: Account[]; total: number }): string {
+  const { ping, pingCount, picked, total } = input;
+  if (!ping) return "sampling live usage...";
+  if (pingCount == null) return "pinging every account (starts each 5h session timer) + sampling live usage...";
+  if (picked.length === 0) return "no account to ping (every account needs reauth), sampling live usage...";
+  return `pinging ${picked.length} of ${count({ n: total, noun: "account" })} (${picked.map((a) => a.label || a.email).join(", ")}) so their 5h session timers start now + sampling live usage...`;
+}
+
+async function collectClaude(input: { cfg: Config; ping: boolean; pingCount: number | undefined; now: number }): Promise<StatusReport["claude"]> {
+  const { cfg, ping, pingCount, now } = input;
   let idx = loadAccounts();
   const samples = new Map<string, { outcome: SampleOutcome; viaTee: boolean }>();
+  let pings = new Set<string>();
   if (idx.accounts.length > 0) {
-    console.error(c.dim(force ? "pinging every account (starts each 5h session timer) + sampling live usage..." : "sampling live usage..."));
     await withLock(paths.lockFile, async () => {
       idx = loadAccounts();
+      const picked = ping ? pickForPing(idx.accounts, pingCount) : [];
+      pings = new Set(picked.map((a) => a.accountUuid));
+      console.error(c.dim(progressNote({ ping, pingCount, picked, total: idx.accounts.length })));
       const tee = loadUsageSnapshot();
       const live = tee?.state ?? null;
       const teeAt = tee?.at ?? null;
@@ -114,7 +131,7 @@ async function collectClaude(input: { cfg: Config; force: boolean; now: number }
             : null;
         let viaTee = false;
         let outcome: SampleOutcome;
-        if (force) {
+        if (pings.has(a.accountUuid)) {
           outcome = isActive ? await probeActiveUsage(a, { ping: true }) : await probeParkedUsage(a, { ping: true });
           if (!outcome.ok && fromStatusLine && outcome.reason.includes("no limit data")) {
             const failed = outcome;
@@ -177,7 +194,7 @@ async function collectClaude(input: { cfg: Config; force: boolean; now: number }
       sample: sampled.outcome.ok ? { ok: true, source: sampled.viaTee ? "statusline" : "probe" } : { ok: false, reason: sampled.outcome.reason },
       pingError: sampled.outcome.pingError ?? null,
       pingRejected: sampled.outcome.pingRejected === true,
-      pinged: force && sampled.outcome.ok && sampled.outcome.pingError == null && aggregate != null && aggregate.fiveHour.resetsAt == null,
+      pinged: pings.has(a.accountUuid) && sampled.outcome.ok && sampled.outcome.pingError == null && aggregate != null && aggregate.fiveHour.resetsAt == null,
     };
   });
   return {
@@ -341,11 +358,11 @@ function renderClaude(input: {
   }
 }
 
-export async function cmdStatus(opts: { force?: boolean; json?: boolean; preRender?: () => void } = {}): Promise<number> {
-  const { force = false, json = false } = opts;
+export async function cmdStatus(opts: { ping?: boolean; pingCount?: number; json?: boolean; preRender?: () => void } = {}): Promise<number> {
+  const { ping = false, pingCount, json = false } = opts;
   const cfg = loadConfig();
   const now = Date.now();
-  const claude = await collectClaude({ cfg, force, now });
+  const claude = await collectClaude({ cfg, ping, pingCount, now });
   if (!json) {
     opts.preRender?.();
     const at = Date.now();

package/src/entries/mcp.ts

@@ -97,7 +97,7 @@ const HELP_TEXT = `tokenmaxxing agent MCP
 
 Read tools (always available):
   pool_ls       list pooled Claude and Codex accounts (labels/status only)
-  pool_status   sample usage bars (free /usage path; never --force)
+  pool_status   sample usage bars (free /usage path; never --ping)
   doctor        verify install health (labels/status only)
   config_get    read effective config, or one key when provided
   help          this catalog
@@ -109,7 +109,7 @@ Mutating tools (confirm=true AND ${MUTATIONS_ENV}=1):
   config_unset  remove a config.json override
 
 Hard deny (no tools):
-  status --force / metered pings
+  status --ping / metered pings
   init / add / auth / rm / uninstall
   credential blobs or token values
   killing sessions or supervisors
@@ -147,7 +147,7 @@ export function createTokenmaxxingMcpServer(): McpServer {
   server.registerTool(
     "pool_status",
     {
-      description: "Show pool usage bars via the free /usage path. Never opens 5h windows. Do not request --force; that tool does not exist.",
+      description: "Show pool usage bars via the free /usage path. Never opens 5h windows. Do not request --ping; that tool does not exist.",
       inputSchema: {},
     },
     async () => {

package/src/lib/decide.ts

@@ -2,7 +2,7 @@ import { maxBy } from "es-toolkit";
 import { z } from "zod";
 import { withLock } from "./lock.ts";
 import { paths } from "./paths.ts";
-import { MAX_CHECK_DELAY_MS, loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadUsageSnapshot, loadModelUsage, saveAccounts, saveDepletedWait, saveModelUsage, writeUsage } from "./state.ts";
+import { MAX_CHECK_DELAY_TICKS, POST_SWAP_COOLDOWN_MS, maxCheckDelayMs, loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadUsageSnapshot, loadModelUsage, saveAccounts, saveDepletedWait, saveModelUsage, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { chooseAndSwap, performSwap } from "./swap.ts";
 import { currentWins, effectiveBars, hardBars, isExhausted, nextWeeklyReset, pickBest, pickEarliestReset, sessionLadder, usableAt } from "./picker.ts";
@@ -126,8 +126,6 @@ async function loadFreshSnapshots(cfg: Config, org: string | null, now: number):
   return { u, mu, uAt };
 }
 
-export const POST_SWAP_COOLDOWN_MS = 45_000;
-
 export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = false, enforced: EnforcedLimit | null = null): Promise<SwapDecision> {
   const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
   const enforced0 = enforced && enforced.org === activeOrg ? enforced : null;
@@ -357,17 +355,17 @@ export async function recordEnforcedLimit(input: { limit: EnforcedClass; org: st
   });
 }
 
-export const CHECK_DELAY_FLOOR_MS = 60_000;
-const CHECK_DELAY_UNKNOWN_MS = 180_000;
-const STAGE_CEILING_MS = [MAX_CHECK_DELAY_MS, 180_000, 120_000];
+const STAGE_CEILING_TICKS = [MAX_CHECK_DELAY_TICKS, 3, 2];
 
 export function checkDelayMs(input: { cfg: Config; org: string | null; now: number; decision: SwapDecision }): number {
   const { cfg, org, now, decision } = input;
-  if (decision.waitUntil !== undefined) return Math.min(MAX_CHECK_DELAY_MS, Math.max(CHECK_DELAY_FLOOR_MS, decision.waitUntil - now));
+  const tick = cfg.policy.checkIntervalMs;
+  const max = maxCheckDelayMs(cfg);
+  if (decision.waitUntil !== undefined) return Math.min(max, Math.max(tick, decision.waitUntil - now));
   const swapAt = loadLastSwapAt();
   if (swapAt != null && now - swapAt < POST_SWAP_COOLDOWN_MS) return swapAt + POST_SWAP_COOLDOWN_MS - now;
   const snap = loadUsageSnapshot();
-  if (!org || !snap || !usageFresh(snap.state, snap.at, org, cfg.policy.usagePollTtlMs, now)) return CHECK_DELAY_UNKNOWN_MS;
+  if (!org || !snap || !usageFresh(snap.state, snap.at, org, cfg.policy.usagePollTtlMs, now)) return 3 * tick;
   const accounts = loadAccounts().accounts;
   const u = freshest(snap.state, snap.at, accounts.find((a) => a.organizationUuid === org)) ?? { ...snap.state, ts: snap.at };
   const mu = loadModelUsage();
@@ -386,8 +384,8 @@ export function checkDelayMs(input: { cfg: Config; org: string | null; now: numb
     else capMissing = true;
   }
   const headroom = Math.min(...heads);
-  const banded = headroom >= 40 ? MAX_CHECK_DELAY_MS : headroom >= 20 ? 180_000 : headroom >= 8 ? 120_000 : CHECK_DELAY_FLOOR_MS;
+  const banded = headroom >= 40 ? max : headroom >= 20 ? 3 * tick : headroom >= 8 ? 2 * tick : tick;
   const stage = sessionLadder(cfg).indexOf(bars.session);
-  const staged = Math.min(banded, STAGE_CEILING_MS[stage] ?? CHECK_DELAY_FLOOR_MS);
-  return capMissing ? Math.min(staged, 120_000) : staged;
+  const staged = Math.min(banded, (STAGE_CEILING_TICKS[stage] ?? 1) * tick);
+  return capMissing ? Math.min(staged, 2 * tick) : staged;
 }

package/src/lib/install.ts

@@ -6,12 +6,14 @@ import { codexPaths, HOME, paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
 import { installedBin, installSettings, isOurHookCommand, uninstallSettings } from "./settings.ts";
 import { resolveRealClaude } from "./claudebin.ts";
+import { loadConfig } from "./state.ts";
 
 const InstallOutcomeSchema = z.object({
   claudeWrapper: z.string(),
   installedBin: z.string(),
   pathAhead: z.boolean(),
   timerLoaded: z.boolean(),
+  checkIntervalS: z.number().int().positive(),
 });
 export type InstallOutcome = z.infer<typeof InstallOutcomeSchema>;
 
@@ -105,11 +107,13 @@ export function installSupervisor(): InstallOutcome {
   writeFileAtomic(join(paths.binDir, "xx"), `#!/bin/sh\nexec ${JSON.stringify(target)} "$@"\n`, 0o755);
 
   installSettings();
+  const checkIntervalS = Math.ceil(loadConfig().policy.checkIntervalMs / 1000);
   return {
     claudeWrapper: paths.supervisorLink,
     installedBin: target,
     pathAhead: isBinDirAhead(),
-    timerLoaded: installCheckTimer(),
+    timerLoaded: installCheckTimer(checkIntervalS),
+    checkIntervalS,
   };
 }
 
@@ -179,7 +183,6 @@ export function uninstallCodexSupervisor(): void {
   if (existsSync(codexSupervisorLink())) rmSync(codexSupervisorLink(), { force: true });
 }
 
-const CHECK_INTERVAL_S = 60;
 const LAUNCHD_LABEL = "com.tokenmaxxing.check";
 
 function launchdPlist(): string {
@@ -199,7 +202,7 @@ function run(cmd: string[]): boolean {
   }
 }
 
-function installCheckTimer(): boolean {
+function installCheckTimer(intervalS: number): boolean {
   if (skipImperativeTimer()) return true;
 
   if (process.platform === "darwin") {
@@ -212,7 +215,7 @@ function installCheckTimer(): boolean {
 <dict>
   <key>Label</key><string>${LAUNCHD_LABEL}</string>
   <key>ProgramArguments</key><array><string>${escape(installedBin())}</string><string>check</string><string>--if-due</string></array>
-  <key>StartInterval</key><integer>${CHECK_INTERVAL_S}</integer>
+  <key>StartInterval</key><integer>${intervalS}</integer>
   <key>StandardOutPath</key><string>/dev/null</string>
   <key>StandardErrorPath</key><string>${escape(join(paths.home, "check.stderr.log"))}</string>
 </dict>
@@ -244,9 +247,9 @@ ExecStart=${exec}
 Description=tokenmaxxing periodic account-switch check
 
 [Timer]
-OnBootSec=60
-OnUnitActiveSec=${CHECK_INTERVAL_S}
-AccuracySec=5
+OnBootSec=${intervalS}
+OnUnitActiveSec=${intervalS}
+AccuracySec=${Math.max(1, Math.floor(intervalS / 12))}
 
 [Install]
 WantedBy=timers.target

package/src/lib/state.ts

@@ -22,7 +22,15 @@ const DEFAULT_CONFIG: Config = {
   hardThresholds: { session: 100, weekly: 100 },
   claudeBin: "",
   codexBin: "",
-  policy: { projectionMargin: 0, greedySessionFloor: 80, greedySwapMargin: 0.15, switchModels: ["fable"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
+  policy: {
+    projectionMargin: 0,
+    greedySessionFloor: 80,
+    greedySwapMargin: 0.15,
+    switchModels: ["fable"],
+    usagePollTtlMs: 90_000,
+    maxWaitMs: 3_600_000,
+    checkIntervalMs: 60_000,
+  },
 };
 
 const PercentSchema = z.number().min(0).max(100);
@@ -41,6 +49,7 @@ export const ConfigFileSchema = z
         switchModels: z.array(z.string()),
         usagePollTtlMs: z.number().int().positive(),
         maxWaitMs: z.number().int().positive(),
+        checkIntervalMs: z.number().int().min(10_000),
       })
       .partial(),
   })
@@ -70,6 +79,7 @@ export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutco
   cfg.policy.greedySwapMargin = p.policy?.greedySwapMargin ?? cfg.policy.greedySwapMargin;
   cfg.policy.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
   cfg.policy.maxWaitMs = p.policy?.maxWaitMs ?? cfg.policy.maxWaitMs;
+  cfg.policy.checkIntervalMs = p.policy?.checkIntervalMs ?? cfg.policy.checkIntervalMs;
   if (p.policy?.switchModels) {
     cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
   }
@@ -199,9 +209,14 @@ export function clearDepletedWait(): void {
   rmSync(paths.depletedJson, { force: true });
 }
 
-export const MAX_CHECK_DELAY_MS = 300_000;
+export const MAX_CHECK_DELAY_TICKS = 5;
+export const POST_SWAP_COOLDOWN_MS = 45_000;
 
-export function loadNextCheckDueAt(now: number): number | null {
+export function maxCheckDelayMs(cfg: Config): number {
+  return MAX_CHECK_DELAY_TICKS * cfg.policy.checkIntervalMs;
+}
+
+export function loadNextCheckDueAt(input: { now: number; cfg: Config }): number | null {
   if (!existsSync(paths.nextCheckJson)) return null;
   let parsed;
   try {
@@ -210,7 +225,7 @@ export function loadNextCheckDueAt(now: number): number | null {
     return null;
   }
   if (!parsed.success) return null;
-  return parsed.data.dueAt - now > MAX_CHECK_DELAY_MS ? null : parsed.data.dueAt;
+  return parsed.data.dueAt - input.now > Math.max(maxCheckDelayMs(input.cfg), POST_SWAP_COOLDOWN_MS) ? null : parsed.data.dueAt;
 }
 
 export function saveNextCheckDueAt(input: { dueAt: number; ts: number }): void {

package/src/lib/types.ts

@@ -125,6 +125,7 @@ export const ConfigSchema = z
       switchModels: z.array(z.string()),
       usagePollTtlMs: z.number().int().positive(),
       maxWaitMs: z.number().int().positive(),
+      checkIntervalMs: z.number().int().min(10_000),
     }),
   })
   .refine((cfg) => cfg.policy.projectionMargin < Math.min(...cfg.thresholds.session, cfg.thresholds.weekly), {

package/src/main.ts

@@ -45,7 +45,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing switch --codex")} [sel]  switch the codex pool (takes effect on next codex start)
   ${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 status --ping")} [--count N]  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("--count N")} pings N randomly picked accounts instead, to stagger the resets; ${c.cyan("xx --ping")} works too
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
@@ -60,6 +60,28 @@ function printHelp(): void {
 
 let jsonMode = false;
 
+function statusFlags(rest: string[]): { ping: boolean; pingCount: number | undefined } | { error: string } {
+  let ping = false;
+  let pingCount: number | undefined;
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]!;
+    if (arg === "--ping") {
+      ping = true;
+      continue;
+    }
+    if (arg === "--count") {
+      if (pingCount != null) return { error: "--count may only be given once" };
+      const raw = rest[++i];
+      pingCount = Number(raw);
+      if (!Number.isInteger(pingCount) || pingCount < 1) return { error: `--count needs a positive whole number of accounts, got: ${raw ?? "nothing"}` };
+      continue;
+    }
+    return { error: `unknown status option: ${arg} (status takes --ping and --count N)` };
+  }
+  if (pingCount != null && !ping) return { error: "--count only applies together with --ping" };
+  return { ping, pingCount };
+}
+
 async function main(): Promise<number> {
   if (process.platform !== "darwin" && process.platform !== "linux") {
     console.error(`tokenmaxxing supports macOS and Linux only (this is ${process.platform})`);
@@ -103,8 +125,17 @@ async function main(): Promise<number> {
     case "__stop-failure-hook": return runStopFailureHook();
     case "__session-start": return runSessionStart();
     case "__codex-stop-hook": return runCodexStopHook();
-    case undefined: return cmdStatus({ json });
-    case "--force": return cmdStatus({ force: true, json });
+    case undefined:
+    case "status":
+    case "--ping":
+    case "--count": {
+      const flags = statusFlags(sub === "status" ? args.slice(1) : args);
+      if ("error" in flags) {
+        emitError({ json, message: flags.error });
+        return 2;
+      }
+      return cmdStatus({ ...flags, json });
+    }
     case "switch": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
       return args.includes("--codex") ? cmdCodexSwitch(rest[0], json) : cmdSwitch(rest[0], json);
@@ -115,7 +146,6 @@ async function main(): Promise<number> {
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "auth": return cmdAuth(args.slice(1));
     case "ls": return cmdLs(json);
-    case "status": return cmdStatus({ force: args.includes("--force"), json });
     case "watch": return cmdWatch(args[1], json);
     case "doctor": return cmdDoctor(json);
     case "rm": {