tokenmaxxing 1.27.0 → 1.29.0

package/DESIGN.md

@@ -50,7 +50,7 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
 1. Read `usage.json` and exit while the live account is under both bars, as defined in the [switching policy](docs/content/docs/switching.mdx).
-2. Take the pool lock, re-check state, select a candidate under the [switching policy](docs/content/docs/switching.mdx), and attempt bounded verification of stale usage before swapping the credential.
+2. Take the pool lock, re-check state, select a candidate under the [switching policy](docs/content/docs/switching.mdx) from the cached usage figures, and swap the credential.
 3. Done - the running session adopts the new credential on its own within a request or two. Only when the pool is depleted (the decision returned a `waitUntil`: pre-parked on the soonest-recovering account, or staying on the current one when it recovers first) does the hook write `respawn/<session_id>` (atomic temp+rename).
 
 ### 3.3 Depleted-pool pause (supervisor)
@@ -82,10 +82,7 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 The [switching policy](docs/content/docs/switching.mdx) is one rule: under both bars, hold; at or over a bar, move to the usable account with the highest pace pressure; nothing usable, wait for the soonest reset.
 
 - Automatic and manual switching rank by pace pressure alone; organization membership is not an input.
-- Successful candidate probes persist their results and restart selection.
-- Verification attempts at most two candidates with a shared 12-second deadline per candidate for identity reads and CLI execution.
-- Expiring access tokens are not refreshed for verification, and the isolated CLI receives no refresh grant.
-- Failed or budget-limited verification uses the existing cached data, so stale-target handoffs remain possible.
+- Selection reads the cached figures only. Each periodic check tick samples the parked account whose last `/usage` attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, so every parked account is attempted about once per tick per pooled account, or once per `policy.usagePollTtlMs` plus a tick when that is longer, and its cached figure is as fresh as its last successful attempt. No sample runs inside the post-swap cooldown. The pool lock covers only the reservation (its owner lookups and refresh under one 20-second deadline) and the result write, never the `/usage` child.
 - The depleted pause happens at the bar, not at 100; Codex has no pause and rides its account until the server refuses it, because a running sibling cannot adopt another account without restarting.
 
 The [profile](docs/content/docs/switching-profile.mdx) records observed cache rewrites across swaps and does not infer subscription quota savings.
@@ -118,6 +115,8 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 
 **Shipped since (0.13.0):** Codex as a second pool, parallel state (`codex-accounts.json`, `codex-creds/`, own flock), same pace-pressure policy. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`). Sibling sessions left on ANY non-live account are reconciled cross-session (owner decisions 2026-07-20; a non-live session cannot refresh cross-account and would wedge at token expiry, healthy or not): the deciding actor drops a reconcile marker addressed to the sibling's supervisor, and the sibling's own Stop hook promotes it into a respawn onto the live account at its next turn boundary - the only safe respawn point - while a blocked live seat never receives a signal.
 
+**Shipped since (1.29.0):** a Cursor Cloud relay. A cloud VM has no keychain, no pool state, and no hot swap, so the path uses what it does have (environment variables, a shell, repo files) and a different credential primitive, one-year inference-only setup tokens, minted once per pooled account by `tokenmaxxing setup-token` on the owner's machine and carried to the VM as one user-scoped Runtime Secret (`TOKENMAXXING_TOKENS`). `tokenmaxxing cursor init` writes a `claude` project subagent (`.cursor/agents/claude.md`) that forwards each task to `tokenmaxxing cloud run`, which spawns `claude -p --dangerously-skip-permissions --output-format json` under `CLAUDE_CODE_OAUTH_TOKEN` and pins the thread to that token (the API caches by exact prefix, so a rotation busts one thread, not all). A setup token carries no usage signal, so rotation is reactive. A run whose transcript gained a non-transient rate-limit row during that run (the structured row the StopFailure hook reads) walls the label until the reset the row names (five hours without one) and resumes the same session on the next token; the result's `api_error_status` alone never walls, so a transient 429 or an older row from a previous token does not cascade across the pool. The local switching engine never reads a setup token; `/usage` prints no percentages under one. Details in [Cursor Cloud](docs/content/docs/cursor-cloud.mdx).
+
 **Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap; Slack as a message bus; soft concurrency caps.
 
 ---

package/README.md

@@ -75,7 +75,10 @@ claude                  # use claude as always
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
 | `tokenmaxxing rename [--codex] <sel> <label>` / `rm [--codex] <sel>` | manage the pool (`--codex` targets the codex pool: one email can hold both a claude and a codex account) |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
-| `--json` | machine-readable output: one JSON document on stdout for `status`, `ls`, `config`, `doctor`, `check`, `switch`, `rename`, `rm`, `uninstall`, and one per tick for `watch` (`ok` mirrors the exit code, failures add `error`) |
+| `tokenmaxxing setup-token [--print \| rm <label\|uuid>]` | Cursor Cloud only: mint one `claude setup-token` per pooled account (a browser sign-in each) and print the `TOKENMAXXING_TOKENS` secret value; `--print` prints the stored set, `rm` drops one |
+| `tokenmaxxing cursor init [dir]` | write the Claude relay subagent and `.cursor/environment.json` into a repo |
+| `tokenmaxxing cloud run [--session <id>] [--max-turns <n>] "<prompt>"` | on a Cursor Cloud VM: run `claude -p` on a setup token, rotate to the next token on a usage limit |
+| `--json` | machine-readable output: one JSON document on stdout for `status`, `ls`, `config`, `doctor`, `check`, `switch`, `rename`, `rm`, `uninstall`, `setup-token --print`, `cursor init`, `cloud run`, and one per tick for `watch` (`ok` mirrors the exit code, failures add `error`) |
 
 ## How switching decides
 
@@ -88,8 +91,7 @@ The bars' headroom is deliberate: it's the budget to reach a clean turn boundary
 
 Selection ranks usable candidates by remaining weekly percentage divided by time to reset, highest first; organization membership is not an input, and manual `tokenmaxxing switch` uses the same ranking.
 
-- Candidate verification makes at most two bounded `/usage` attempts per evaluation and re-ranks successful samples before switching.
-- Failed verification leaves cached figures in force, so it cannot guarantee a fresh target.
+- Every periodic check tick samples the parked account whose last `/usage` attempt is oldest, skipping any attempted within `policy.usagePollTtlMs`, so every parked account is attempted about once per tick per pooled account, or once per `usagePollTtlMs` plus a tick when that is longer; the swap reads the cached figures, which are as fresh as each account's last successful attempt. No sample runs inside the 45-second post-swap cooldown.
 - When no account is usable, the session pauses until the soonest reset if that lands within `policy.maxWaitMs`, and otherwise stays put.
 
 See [How switching decides](docs/content/docs/switching.mdx) for the policy and the [cache-cost profile](docs/content/docs/switching-profile.mdx) for measurements and their limits.
@@ -110,7 +112,7 @@ See [How switching decides](docs/content/docs/switching.mdx) for the policy and
 }
 ```
 
-`thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `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; `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 - re-run `tokenmaxxing init` after changing it so the timer unit picks up the new tick.
+`thresholds.session` and `thresholds.weekly` are the two bars, one number each (an array `thresholds.session`, the former ladder, fails config loading with a message naming the field); `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; `switchModels` names the models whose per-model cap triggers a switch; `usagePollTtlMs` is how long a `/usage` attempt stays fresh, for the live per-model poll and for the parked account each check tick samples; `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 - 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`).
 
@@ -128,6 +130,10 @@ Codex mechanics differ from Claude Code in one hard way: a running codex process
 
 Two codex-specific facts worth knowing: codex does not run hooks it has not been told to trust, so after `init --codex` you must open codex once and trust the tokenmaxxing Stop hook via `/hooks` (auto-switching is inert until then); and codex has no cross-process lock on `auth.json`, so tokenmaxxing serializes all of its own credential writes behind its own lock and swaps only at idle turn boundaries.
 
+## Cursor Cloud
+
+A Cursor Cloud Agent can hand substantial work to Claude Code running on your own accounts. The VM has no keychain and no hot swap, so this path uses setup tokens instead. `tokenmaxxing setup-token` mints one `claude setup-token` per pooled account on your machine and prints the value for a user-scoped Runtime Secret named `TOKENMAXXING_TOKENS`; `tokenmaxxing cursor init` writes a `claude` project subagent and an `environment.json` install line into the repo; on the VM, the subagent forwards each task to `tokenmaxxing cloud run`, which runs `claude -p` on one token per thread and moves the thread to the next token when a run ends on a usage limit. Setup tokens are inference-only and report no usage percentages, so cloud rotation is reactive and the local switching engine never reads one. Details and limits in [Cursor Cloud](docs/content/docs/cursor-cloud.mdx).
+
 ## Honest limitations
 
 - **One cold turn.** The first turn on a new account re-uploads context once (prompt cache is org-scoped).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.27.0",
+  "version": "1.29.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",
@@ -19,7 +19,7 @@
     "DESIGN.md"
   ],
   "engines": {
-    "bun": ">=1.2.6"
+    "bun": ">=1.3.6"
   },
   "os": [
     "darwin",

package/src/cli/check.ts

@@ -1,11 +1,15 @@
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { sampleOldestParked } from "../lib/sample.ts";
+import { loadConfig } from "../lib/state.ts";
 import { log } from "../lib/log.ts";
 import { c, emitError, emitJson, fmtReset } from "./render.ts";
 
 export async function cmdCheck(json = false): Promise<number> {
+  const now = Date.now();
   let d;
   try {
-    d = await evaluateAndMaybeSwap(Date.now());
+    d = await evaluateAndMaybeSwap(now);
+    await sampleOldestParked(loadConfig());
   } catch (e) {
     const detail = e instanceof Error ? e.message : String(e);
     log("check.error", { err: detail });

package/src/cli/cloudrun.ts

@@ -0,0 +1,117 @@
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
+import {
+  limitWallUntil,
+  loadCloudSessions,
+  loadCloudWalled,
+  newReservationKey,
+  pickToken,
+  readCloudTokens,
+  saveCloudSessions,
+  saveCloudWalled,
+  spawnCloudClaude,
+  transcriptBytes,
+} from "../lib/cloud.ts";
+import { c, emitError, emitJson, fmtReset } from "./render.ts";
+
+const USAGE = "usage: tokenmaxxing cloud run [--session <id>] [--max-turns <n>] \"<prompt>\" (the prompt is also read from stdin)";
+
+function parseFlags(args: string[]): { session: string | null; maxTurns: number | null; prompt: string | null } | { error: string } {
+  let session: string | null = null;
+  let maxTurns: number | null = null;
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg === "--session") {
+      const raw = args[++i];
+      if (raw == null || raw === "") return { error: "--session needs a session id" };
+      session = raw;
+      continue;
+    }
+    if (arg === "--max-turns") {
+      const raw = args[++i];
+      maxTurns = Number(raw);
+      if (!Number.isInteger(maxTurns) || maxTurns < 1) return { error: `--max-turns needs a positive whole number, got: ${raw ?? "nothing"}` };
+      continue;
+    }
+    positional.push(arg);
+  }
+  return { session, maxTurns, prompt: positional.length > 0 ? positional.join(" ") : null };
+}
+
+export async function cmdCloudRun(args: string[], json = false): Promise<number> {
+  const flags = parseFlags(args);
+  if ("error" in flags) {
+    emitError({ json, message: `${flags.error} - ${USAGE}` });
+    return 2;
+  }
+  const prompt = flags.prompt ?? (process.stdin.isTTY ? null : await Bun.stdin.text());
+  if (prompt == null || prompt.trim() === "") {
+    emitError({ json, message: USAGE });
+    return 2;
+  }
+  const tokens = readCloudTokens();
+  let sessionId = flags.session;
+  while (true) {
+    const reservation = newReservationKey();
+    const pick = await withLock(paths.cloudLockFile, () => {
+      const sessions = loadCloudSessions();
+      const picked = pickToken({ tokens, sessions, walled: loadCloudWalled(), sessionId, now: Date.now() });
+      if (picked.ok) saveCloudSessions({ ...sessions, [reservation]: picked.token.label });
+      return picked;
+    });
+    if (!pick.ok) {
+      emitError({
+        json,
+        message: `every token is at its limit - earliest ${fmtReset(pick.earliestReset)}`,
+        extra: { earliestReset: pick.earliestReset, session_id: sessionId },
+      });
+      return 1;
+    }
+    const label = pick.token.label;
+    console.error(c.dim(`cloud run: ${label}${sessionId ? ` (resuming ${sessionId})` : ""}`));
+    const transcriptBefore = transcriptBytes(sessionId);
+    let spawned: Awaited<ReturnType<typeof spawnCloudClaude>>;
+    try {
+      spawned = await spawnCloudClaude({ token: pick.token.token, prompt, resume: sessionId, maxTurns: flags.maxTurns });
+    } catch (e) {
+      await withLock(paths.cloudLockFile, () => {
+        const sessions = loadCloudSessions();
+        delete sessions[reservation];
+        saveCloudSessions(sessions);
+      });
+      throw e;
+    }
+    const { exitCode, result } = spawned;
+    sessionId = result.session_id;
+    const failed = result.is_error || result.subtype !== "success";
+    const until = failed ? limitWallUntil({ sessionId: result.session_id, sinceBytes: transcriptBefore, now: Date.now() }) : null;
+    await withLock(paths.cloudLockFile, () => {
+      const sessions = loadCloudSessions();
+      delete sessions[reservation];
+      saveCloudSessions({ ...sessions, [result.session_id]: label });
+      if (until != null) saveCloudWalled({ ...loadCloudWalled(), [label]: until });
+    });
+    if (failed) {
+      if (until != null) {
+        console.error(c.yellow(`cloud run: ${label} hit its limit (${fmtReset(until)}) - resuming the session on the next token`));
+        continue;
+      }
+      const errors = result.subtype === "success" ? [result.result] : result.errors;
+      emitError({
+        json,
+        message: `claude exited ${exitCode ?? "on signal"} (${result.subtype}): ${errors.join("; ")}`,
+        notes: [`session ${result.session_id}`],
+        extra: { session_id: result.session_id, subtype: result.subtype, errors },
+      });
+      return 1;
+    }
+    if (json) {
+      emitJson({ ok: true, session_id: result.session_id, result: result.result, num_turns: result.num_turns, total_cost_usd: result.total_cost_usd });
+      return 0;
+    }
+    console.log(result.result);
+    console.log(`session ${result.session_id}`);
+    return 0;
+  }
+}

package/src/cli/cursorinit.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "../lib/atomic.ts";
+import { c, emitError, emitJson } from "./render.ts";
+
+export const CLOUD_INSTALL_LINE =
+  'curl -fsSL https://bun.sh/install | bash && curl -fsSL https://claude.ai/install.sh | bash && "$HOME/.bun/bin/bun" add -g tokenmaxxing && test -x "$HOME/.bun/bin/bun" && test -x "$HOME/.local/bin/claude" && test -e "$HOME/.bun/bin/tokenmaxxing"';
+
+export const CLOUD_RUN_COMMAND = 'TOKENMAXXING_CLAUDE_BIN="$HOME/.local/bin/claude" "$HOME/.bun/bin/bun" "$HOME/.bun/bin/tokenmaxxing" cloud run';
+
+export const RELAY_AGENT = `---
+name: claude
+description: Runs a task in Claude Code on the owner's subscription accounts. Use proactively for substantial implementation, debugging, or research work that should not consume the parent's context.
+model: inherit
+readonly: false
+---
+
+You are a thin forwarding wrapper around Claude Code.
+
+Your only job is to forward the task to the runner and return its output. Do not do anything else.
+
+Rules:
+
+- Use exactly one shell call. Pass the task on stdin through a quoted heredoc. Pick the delimiter fresh for every call as \`TASK_\` followed by eight random letters and digits, and check that no line of the task equals it; a quoted heredoc ends only on a line that matches the delimiter exactly, so the task text can never become shell commands.
+
+\`\`\`sh
+${CLOUD_RUN_COMMAND} <<'TASK_k3v9qx2m'
+<task>
+TASK_k3v9qx2m
+\`\`\`
+
+- When the task continues earlier Claude Code work, add \`--session <id>\` after \`cloud run\` with the session id from the previous output.
+- Preserve the task text as given. Do not inspect the repository, read files, run other commands, or summarize.
+- Return the command's stdout exactly as-is, including the trailing \`session <id>\` line.
+- If the command fails, return its stderr as-is.
+`;
+
+const ENVIRONMENT_JSON = JSON.stringify({ install: CLOUD_INSTALL_LINE }, null, 2) + "\n";
+const ExistingEnvironmentSchema = z.looseObject({ user: z.string().optional() });
+
+const REPO_FILE_MODE = 0o644;
+const USAGE = "usage: tokenmaxxing cursor init [dir]";
+
+export function cmdCursorInit(args: string[], json = false): number {
+  if (args.length > 1) {
+    emitError({ json, message: USAGE });
+    return 2;
+  }
+  const dir = resolve(args[0] ?? ".");
+  if (!existsSync(dir)) {
+    emitError({ json, message: `no such directory: ${dir}` });
+    return 1;
+  }
+  const agentFile = join(dir, ".cursor", "agents", "claude.md");
+  const environmentFile = join(dir, ".cursor", "environment.json");
+  const existing = existsSync(environmentFile) ? ExistingEnvironmentSchema.parse(Bun.JSONC.parse(readFileSync(environmentFile, "utf8"))) : null;
+  const agent = existsSync(agentFile) && readFileSync(agentFile, "utf8") === RELAY_AGENT ? "unchanged" : "written";
+  if (agent === "written") writeFileAtomic(agentFile, RELAY_AGENT, REPO_FILE_MODE);
+  const environment = existing == null ? "written" : "exists";
+  const warnings: string[] = [];
+  if (existing == null) {
+    writeFileAtomic(environmentFile, ENVIRONMENT_JSON, REPO_FILE_MODE);
+  } else if (existing.user === "root" || existing.user === "0") {
+    warnings.push(".cursor/environment.json sets user to root; Claude Code refuses --dangerously-skip-permissions under root, so every relay call fails until user is a non-root account");
+  }
+  if (json) {
+    emitJson({ ok: true, dir, agent, environment, install: CLOUD_INSTALL_LINE, warnings });
+    return 0;
+  }
+  console.log(`${c.green("✓")} .cursor/agents/claude.md ${agent}`);
+  if (environment === "written") {
+    console.log(`${c.green("✓")} .cursor/environment.json written`);
+  } else {
+    console.log(c.yellow("⚠ .cursor/environment.json exists - left untouched; add this to its install command:"));
+    console.log(`  ${CLOUD_INSTALL_LINE}`);
+  }
+  for (const warning of warnings) console.log(c.yellow(`⚠ ${warning}`));
+  console.log(c.dim("next: commit both files, add the TOKENMAXXING_TOKENS user-scoped Runtime Secret at cursor.com/dashboard/cloud-agents, and start a cloud agent on the repo"));
+  return 0;
+}

package/src/cli/doctor.ts

@@ -7,7 +7,8 @@ import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { readItem, liveTarget, parkedTarget } from "../lib/credstore.ts";
 import { isAccessTokenExpiring, fetchTokenIdentity, describeIdentity } from "../lib/oauth.ts";
 import { CredentialBlobSchema, type TokenIdentity } from "../lib/types.ts";
-import { c, emitJson } from "./render.ts";
+import { SETUP_TOKEN_STALE_MS, loadSetupTokens } from "../lib/setuptokens.ts";
+import { c, emitJson, fmtAgo } from "./render.ts";
 
 async function blobIdentity(raw: string): Promise<TokenIdentity | null> {
   const creds = CredentialBlobSchema.parse(JSON.parse(raw)).claudeAiOauth;
@@ -77,6 +78,15 @@ export async function cmdDoctor(json = false): Promise<number> {
     if (a.needsReauth) check(false, `${a.email} needs re-auth`, `run \`tokenmaxxing auth ${a.label}\` to re-login`);
   }
 
+  if (existsSync(paths.setupTokensJson)) {
+    const setupTokens = loadSetupTokens().tokens;
+    for (const a of idx.accounts) {
+      const token = setupTokens.find((t) => t.accountUuid === a.accountUuid);
+      if (!token) warn(`no setup token stored for ${a.label} - run \`tokenmaxxing setup-token\` to mint one for Cursor Cloud`);
+      else if (Date.now() - token.mintedAt > SETUP_TOKEN_STALE_MS) warn(`the setup token for ${a.label} was minted ${fmtAgo(token.mintedAt)} and expires a year after minting - \`tokenmaxxing setup-token rm ${a.label}\` then \`tokenmaxxing setup-token\` re-mints it`);
+    }
+  }
+
   const cfg = loadConfig();
   check(!!cfg.claudeBin && existsSync(cfg.claudeBin), "real claude binary resolved", "set claudeBin in config.json");
   if (cfg.claudeBin && existsSync(cfg.claudeBin)) {

package/src/cli/rm.ts

@@ -4,6 +4,7 @@ import { deleteItem, isolatedTarget, liveTarget, parkedTarget, readItem } from "
 import { fetchTokenIdentity } from "../lib/oauth.ts";
 import { withLock } from "../lib/lock.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
+import { loadSetupTokens, saveSetupTokens } from "../lib/setuptokens.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
 import { CredentialBlobSchema } from "../lib/types.ts";
 import { findAccount } from "./rename.ts";
@@ -43,12 +44,18 @@ export async function cmdRm(selector?: string, json = false): Promise<number> {
         return 1;
       }
     }
+    const setupTokens = loadSetupTokens();
     await deleteItem(parkedTarget(a.keychainItem));
-    const sampleDir = join(paths.sampleDir, credItemFor(a.accountUuid));
-    await deleteItem(isolatedTarget(sampleDir));
-    rmSync(sampleDir, { recursive: true, force: true });
+    const item = credItemFor(a.accountUuid);
+    for (const sampleDir of [join(paths.sampleDir, item), join(paths.sampleDir, `${item}-tick`)]) {
+      await deleteItem(isolatedTarget(sampleDir));
+      rmSync(sampleDir, { recursive: true, force: true });
+    }
     idx.accounts = idx.accounts.filter((x) => x.accountUuid !== a.accountUuid);
     saveAccounts(idx);
+    if (setupTokens.tokens.some((t) => t.accountUuid === a.accountUuid)) {
+      saveSetupTokens({ ...setupTokens, tokens: setupTokens.tokens.filter((t) => t.accountUuid !== a.accountUuid) });
+    }
     if (json) emitJson({ ok: true, pool: "claude", removed: a.label, remaining: idx.accounts.length });
     else console.log(`removed ${c.bold(a.label)} from the pool (${idx.accounts.length} left)`);
     return 0;

package/src/cli/setuptoken.ts

@@ -0,0 +1,160 @@
+import { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { resolveRealClaude } from "../lib/claudebin.ts";
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
+import { loadAccounts } from "../lib/state.ts";
+import { scrubCredentialEnv } from "../lib/usage.ts";
+import { CURSOR_SECRET_VALUE_CAP_BYTES, cursorSecretValue, loadSetupTokens, saveSetupTokens, type SetupToken } from "../lib/setuptokens.ts";
+import type { Account } from "../lib/types.ts";
+import { c, emitError, emitJson } from "./render.ts";
+
+const TOKEN_BEGIN_MARKER = "Your OAuth token (valid for";
+const TOKEN_END_MARKER = "Store this token securely";
+const USAGE = "usage: tokenmaxxing setup-token [--print] | tokenmaxxing setup-token rm <label|uuid>";
+
+export function extractSetupToken(output: string): string | null {
+  const lines = Bun.stripANSI(output).split("\n").map((line) => line.trim());
+  const end = lines.findLastIndex((line) => line.includes(TOKEN_END_MARKER));
+  if (end < 0) return null;
+  const begin = lines.slice(0, end).findLastIndex((line) => line.includes(TOKEN_BEGIN_MARKER));
+  if (begin < 0) return null;
+  const token = lines.slice(begin + 1, end).join("");
+  return token === "" ? null : token;
+}
+
+async function mint(input: { real: string; item: string }): Promise<string | null> {
+  const configDir = join(paths.setupTokenDir, input.item);
+  rmSync(configDir, { recursive: true, force: true });
+  mkdirSync(configDir, { recursive: true });
+  const env = scrubCredentialEnv({ ...process.env, CLAUDE_CONFIG_DIR: configDir });
+  const child = Bun.spawn([input.real, "setup-token"], { env, stdin: "inherit", stdout: "pipe", stderr: "inherit" });
+  const decoder = new TextDecoder();
+  let captured = "";
+  for await (const chunk of child.stdout) {
+    process.stdout.write(chunk);
+    captured += decoder.decode(chunk, { stream: true });
+  }
+  await child.exited;
+  rmSync(configDir, { recursive: true, force: true });
+  if (child.exitCode !== 0) {
+    console.error(c.red(`claude setup-token exited ${child.exitCode ?? "on signal"} - nothing stored`));
+    return null;
+  }
+  const captureToken = extractSetupToken(captured);
+  if (captureToken) return captureToken;
+  const pasted = prompt("the token line was not captured from the output above - paste the token here:")?.trim() ?? "";
+  if (pasted === "") {
+    console.error(c.red("no token pasted - nothing stored"));
+    return null;
+  }
+  return pasted;
+}
+
+function currentTokens(tokens: SetupToken[], accounts: Account[]): { label: string; token: string }[] {
+  return accounts.flatMap((a) => {
+    const stored = tokens.find((t) => t.accountUuid === a.accountUuid);
+    return stored ? [{ label: a.label, token: stored.token }] : [];
+  });
+}
+
+async function rmToken(selector: string, json: boolean): Promise<number> {
+  const outcome = await withLock(paths.lockFile, async (): Promise<{ error: string } | { kept: SetupToken[] }> => {
+    const store = loadSetupTokens();
+    const accounts = loadAccounts().accounts;
+    const pooled = accounts.find((a) => a.label === selector);
+    const orphan = (t: SetupToken) => !accounts.some((a) => a.accountUuid === t.accountUuid);
+    const targets = store.tokens.filter((t) =>
+      t.accountUuid === selector || (pooled ? t.accountUuid === pooled.accountUuid : t.label === selector && orphan(t)),
+    );
+    if (targets.length === 0) return { error: `no setup token stored for "${selector}"` };
+    if (targets.length > 1) return { error: `"${selector}" matches ${targets.length} stored tokens (${targets.map((t) => `${t.label} ${t.accountUuid}`).join(", ")}) - nothing removed` };
+    const kept = store.tokens.filter((t) => t !== targets[0]);
+    saveSetupTokens({ ...store, tokens: kept });
+    return { kept };
+  });
+  if ("error" in outcome) {
+    emitError({ json, message: outcome.error });
+    return 1;
+  }
+  const remaining = outcome.kept;
+  if (json) {
+    emitJson({ ok: true, removed: selector, remaining: remaining.map((t) => t.label) });
+    return 0;
+  }
+  console.log(`removed the setup token for ${selector} (local only: Claude Code documents no revocation for setup tokens)`);
+  return 0;
+}
+
+export async function cmdSetupToken(args: string[], json = false): Promise<number> {
+  const [sub, label] = args;
+  if (sub === "rm" && label !== undefined && args.length === 2) return rmToken(label, json);
+  const print = sub === "--print" && args.length === 1;
+  if (args.length > 0 && !print) {
+    emitError({ json, message: USAGE });
+    return 2;
+  }
+  if (json && !print) {
+    emitError({ json, message: "setup-token mints through a browser login flow and has no --json form; `setup-token --print --json` prints the stored set" });
+    return 2;
+  }
+  let store = loadSetupTokens();
+  let idx = loadAccounts();
+  if (!print) {
+    if (idx.accounts.length === 0) {
+      emitError({ json, message: "no accounts in the pool - run `tokenmaxxing init` first" });
+      return 1;
+    }
+    const real = resolveRealClaude();
+    const missing = idx.accounts.filter((a) => !store.tokens.some((t) => t.accountUuid === a.accountUuid));
+    if (missing.length === 0) console.log(c.dim("every pooled account already has a stored setup token (`setup-token rm <label>` drops one so it can be re-minted)"));
+    for (const a of missing) {
+      console.log();
+      console.log(`${c.bold(a.label)} - sign into this account in the browser (${a.email})`);
+      const token = await mint({ real, item: a.keychainItem });
+      if (!token) return 1;
+      const stored = await withLock(paths.lockFile, async () => {
+        if (!loadAccounts().accounts.some((x) => x.accountUuid === a.accountUuid)) return false;
+        const fresh = loadSetupTokens();
+        const tokens = fresh.tokens.filter((t) => t.accountUuid !== a.accountUuid);
+        saveSetupTokens({ ...fresh, tokens: [...tokens, { accountUuid: a.accountUuid, label: a.label, token, mintedAt: Date.now() }] });
+        return true;
+      });
+      if (!stored) {
+        console.log(c.yellow(`${a.label} left the pool during the login - token discarded`));
+        continue;
+      }
+      console.log(`${c.green("✓")} stored the setup token for ${c.bold(a.label)} ${c.dim("(ownership not verified: an inference-only token cannot read the profile endpoint, so the label is the sign-in you chose)")}`);
+    }
+    store = loadSetupTokens();
+    idx = loadAccounts();
+  }
+  if (store.tokens.length === 0) {
+    emitError({ json, message: "no setup tokens stored - run `tokenmaxxing setup-token` to mint them" });
+    return 1;
+  }
+  const tokens = currentTokens(store.tokens, idx.accounts);
+  const orphaned = store.tokens
+    .filter((t) => !idx.accounts.some((a) => a.accountUuid === t.accountUuid))
+    .map((t) => ({ label: t.label, accountUuid: t.accountUuid }));
+  if (tokens.length === 0) {
+    emitError({ json, message: "no stored setup token belongs to a pooled account - run `tokenmaxxing setup-token` to mint them" });
+    return 1;
+  }
+  const secret = cursorSecretValue(tokens);
+  const bytes = Buffer.byteLength(secret);
+  if (json) {
+    emitJson({ ok: true, tokens, orphaned, bytes, cap: CURSOR_SECRET_VALUE_CAP_BYTES });
+    return 0;
+  }
+  console.log();
+  if (orphaned.length > 0) {
+    console.log(c.dim(`left out of the secret (no longer in the pool): ${orphaned.map((t) => `${t.label} (${t.accountUuid})`).join(", ")}; \`setup-token rm <label|uuid>\` drops one`));
+  }
+  console.log(`${c.bold("TOKENMAXXING_TOKENS")} ${c.dim("(user-scoped Runtime Secret at cursor.com/dashboard/cloud-agents)")}`);
+  console.log(secret);
+  if (bytes > CURSOR_SECRET_VALUE_CAP_BYTES) {
+    console.log(c.yellow(`⚠ ${bytes} bytes: over the ${CURSOR_SECRET_VALUE_CAP_BYTES}-byte value cap Cursor documents for API-created environment variables`));
+  }
+  return 0;
+}

package/src/lib/cloud.ts

@@ -0,0 +1,176 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { minBy } from "es-toolkit";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+import { UNMANAGED_ENV, resolveRealClaude } from "./claudebin.ts";
+import { pidExists } from "./proc.ts";
+import { CloudTokenSchema, CloudTokensSchema, type CloudToken } from "./setuptokens.ts";
+import { normalizeResetsAt, parseErrorBody, readTranscriptTail, scrubCredentialEnv } from "./usage.ts";
+
+export const TOKENS_ENV = "TOKENMAXXING_TOKENS";
+export const FALLBACK_WALL_MS = 5 * 3_600_000;
+const RESERVATION_PREFIX = "pending:";
+
+export function readCloudTokens(): CloudToken[] {
+  const raw = process.env[TOKENS_ENV];
+  if (raw == null || raw === "") {
+    throw new Error(`${TOKENS_ENV} is not set - add it as a user-scoped Runtime Secret with the value \`tokenmaxxing setup-token --print\` prints`);
+  }
+  let json: unknown;
+  try {
+    json = JSON.parse(raw);
+  } catch {
+    throw new Error(`${TOKENS_ENV} is not valid JSON`);
+  }
+  const parsed = CloudTokensSchema.safeParse(json);
+  if (!parsed.success) throw new Error(`${TOKENS_ENV} must be a non-empty JSON array of {label, token} objects`);
+  const labels = parsed.data.map((t) => t.label);
+  if (new Set(labels).size !== labels.length) throw new Error(`${TOKENS_ENV} carries a duplicate label`);
+  const reserved = labels.find((label) => label in {});
+  if (reserved != null) throw new Error(`${TOKENS_ENV} carries the label "${reserved}", which is a reserved object property name`);
+  return parsed.data;
+}
+
+const SessionsSchema = z.record(z.string(), z.string());
+const WalledSchema = z.record(z.string(), z.number());
+
+function loadState<T>(file: string, schema: z.ZodType<T>, empty: T): T {
+  if (!existsSync(file)) return empty;
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    throw new Error(`${file} is corrupt (unparsable JSON) - repair or remove the file`);
+  }
+  return schema.parse(json);
+}
+
+export function loadCloudSessions(): Record<string, string> {
+  const sessions = loadState(paths.cloudSessionsJson, SessionsSchema, {});
+  for (const key of Object.keys(sessions)) {
+    if (!key.startsWith(RESERVATION_PREFIX)) continue;
+    const pid = Number(key.slice(RESERVATION_PREFIX.length).split(":")[0]);
+    if (!Number.isInteger(pid) || !pidExists(pid)) delete sessions[key];
+  }
+  return sessions;
+}
+
+export function saveCloudSessions(sessions: Record<string, string>): void {
+  writeFileAtomic(paths.cloudSessionsJson, JSON.stringify(SessionsSchema.parse(sessions), null, 2) + "\n");
+}
+
+export function newReservationKey(): string {
+  return `${RESERVATION_PREFIX}${process.pid}:${crypto.randomUUID().slice(0, 8)}`;
+}
+
+export function loadCloudWalled(): Record<string, number> {
+  return loadState(paths.cloudWalledJson, WalledSchema, {});
+}
+
+export function saveCloudWalled(walled: Record<string, number>): void {
+  writeFileAtomic(paths.cloudWalledJson, JSON.stringify(WalledSchema.parse(walled), null, 2) + "\n");
+}
+
+const PickSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), token: CloudTokenSchema }),
+  z.object({ ok: z.literal(false), earliestReset: z.number() }),
+]);
+export type Pick = z.infer<typeof PickSchema>;
+
+export function pickToken(input: {
+  tokens: CloudToken[];
+  sessions: Record<string, string>;
+  walled: Record<string, number>;
+  sessionId: string | null;
+  now: number;
+}): Pick {
+  const walled = new Map(Object.entries(input.walled));
+  const sessions = new Map(Object.entries(input.sessions));
+  const open = (label: string) => (walled.get(label) ?? 0) <= input.now;
+  if (input.sessionId != null) {
+    const pinned = sessions.get(input.sessionId);
+    const token = input.tokens.find((t) => t.label === pinned);
+    if (token && open(token.label)) return { ok: true, token };
+  }
+  const candidates = input.tokens.filter((t) => open(t.label));
+  if (candidates.length === 0) {
+    return { ok: false, earliestReset: Math.min(...input.tokens.map((t) => walled.get(t.label) ?? input.now)) };
+  }
+  const load = new Map<string, number>();
+  for (const label of sessions.values()) load.set(label, (load.get(label) ?? 0) + 1);
+  return { ok: true, token: minBy(candidates, (t) => load.get(t.label) ?? 0) ?? candidates[0]! };
+}
+
+const ResultBase = {
+  type: z.literal("result"),
+  session_id: z.string(),
+  is_error: z.boolean(),
+  num_turns: z.number(),
+  total_cost_usd: z.number(),
+};
+const CloudResultSchema = z.discriminatedUnion("subtype", [
+  z.looseObject({ ...ResultBase, subtype: z.literal("success"), result: z.string(), api_error_status: z.number().nullish() }),
+  z.looseObject({
+    ...ResultBase,
+    subtype: z.enum(["error_max_turns", "error_during_execution", "error_max_budget_usd", "error_max_structured_output_retries"]),
+    errors: z.array(z.string()),
+  }),
+]);
+export type CloudResult = z.infer<typeof CloudResultSchema>;
+
+export async function spawnCloudClaude(input: {
+  token: string;
+  prompt: string;
+  resume: string | null;
+  maxTurns: number | null;
+}): Promise<{ exitCode: number | null; result: CloudResult }> {
+  const args = [
+    "-p", "--output-format", "json", "--dangerously-skip-permissions",
+    ...(input.resume ? ["--resume", input.resume] : []),
+    ...(input.maxTurns != null ? ["--max-turns", String(input.maxTurns)] : []),
+    "--", input.prompt,
+  ];
+  const env: Record<string, string> = { ...scrubCredentialEnv({ ...process.env, [UNMANAGED_ENV]: "1" }), CLAUDE_CODE_OAUTH_TOKEN: input.token };
+  delete env[TOKENS_ENV];
+  const child = Bun.spawn([resolveRealClaude(), ...args], { env, stdin: "ignore", stdout: "pipe", stderr: "inherit" });
+  const stdout = await new Response(child.stdout).text();
+  await child.exited;
+  let json: unknown;
+  try {
+    json = JSON.parse(stdout);
+  } catch {
+    throw new Error(`claude exited ${child.exitCode ?? "on signal"} without a JSON result: ${stdout.trim().slice(0, 200)}`);
+  }
+  const parsed = CloudResultSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new Error(`claude exited ${child.exitCode ?? "on signal"} with a result that does not match the documented result message: ${stdout.trim().slice(0, 200)}`);
+  }
+  return { exitCode: child.exitCode, result: parsed.data };
+}
+
+export function cloudTranscriptPath(sessionId: string): string | null {
+  const projects = join(paths.claudeDir, "projects");
+  if (!existsSync(projects)) return null;
+  for (const dir of readdirSync(projects)) {
+    const candidate = join(projects, dir, `${sessionId}.jsonl`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+export function transcriptBytes(sessionId: string | null): number {
+  const transcript = sessionId ? cloudTranscriptPath(sessionId) : null;
+  return transcript ? statSync(transcript).size : 0;
+}
+
+export function limitWallUntil(input: { sessionId: string; sinceBytes: number; now: number }): number | null {
+  const transcript = cloudTranscriptPath(input.sessionId);
+  const rows = transcript ? readTranscriptTail(transcript, statSync(transcript).size - input.sinceBytes + 1) : [];
+  const row = rows.findLast((r) => r.isApiErrorMessage === true);
+  if (!row || row.error !== "rate_limit" || row.apiErrorIsTransient === true) return null;
+  if ((row.quotaLimits?.rateLimitType ?? "") === "" && parseErrorBody(row.errorDetails)?.error?.type !== "rate_limit_error") return null;
+  const resetsAt = row.quotaLimits?.resetsAt != null ? normalizeResetsAt(row.quotaLimits.resetsAt) : null;
+  return resetsAt != null && resetsAt > input.now ? resetsAt : input.now + FALLBACK_WALL_MS;
+}

package/src/lib/decide.ts

@@ -4,9 +4,8 @@ import { withLock } from "./lock.ts";
 import { paths } from "./paths.ts";
 import { POST_SWAP_COOLDOWN_MS, loadAccounts, loadConfig, loadDepletedWait, loadLastSwapAt, loadUsage, loadUsageSnapshot, loadModelUsage, saveAccounts, saveDepletedWait, saveModelUsage, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
-import { isSkippableSwapError, performSwap, type VerifyVerdict } from "./swap.ts";
-import { probeParkedUsage } from "./sample.ts";
-import { isExhausted, nextWeeklyReset, pickBest, pickEarliestReset, thresholdBars, usableAt, type PickCtx } from "./picker.ts";
+import { isSkippableSwapError, performSwap } from "./swap.ts";
+import { nextWeeklyReset, pickBest, pickEarliestReset, thresholdBars, usableAt } from "./picker.ts";
 import { familyTokens, gatedFamilies, probeUsage, type EnforcedClass } from "./usage.ts";
 import { log } from "./log.ts";
 import { AccountSchema, ModelUsageStateSchema, UsageStateSchema, type Account, type Config, type EnforcedLimit, type ModelUsageState, type Thresholds, type UsageState, type UsageWindow } from "./types.ts";
@@ -21,8 +20,6 @@ export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
 const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
-const VERIFY_PROBE_BUDGET = 2;
-const VERIFY_PROBE_KILL_MS = 12_000;
 
 function liveUsed(input: { window: UsageWindow; windowMs: number; sampledAt: number; now: number }): number {
   const { window: w, windowMs, sampledAt, now } = input;
@@ -186,53 +183,12 @@ export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = fals
       rejected.add(candidate.accountUuid);
       log("decide.candidate_rejected", { account: candidate.accountUuid.slice(0, 8), error: e instanceof Error ? e.message : String(e) });
     };
-    let probeBudget = VERIFY_PROBE_BUDGET;
-    const verified = async (candidate: Account, ctx: PickCtx): Promise<VerifyVerdict> => {
-      if (candidate.lastUsageAt != null && now - candidate.lastUsageAt <= cfg.policy.usagePollTtlMs) return "go";
-      const short = candidate.accountUuid.slice(0, 8);
-      const idx2 = loadAccounts();
-      const stored = idx2.accounts.find((a) => a.accountUuid === candidate.accountUuid);
-      if (!stored) return "go";
-      if (probeBudget <= 0) {
-        log("decide.verify_budget_spent", { account: short });
-        return "go";
-      }
-      probeBudget -= 1;
-      const sample = await probeParkedUsage(stored, { retries: 0, refreshParked: false, killMs: VERIFY_PROBE_KILL_MS, signal: AbortSignal.timeout(VERIFY_PROBE_KILL_MS) });
-      if (sample.ok) {
-        const at = Date.now();
-        stored.lastUsage = { fiveHour: sample.usage.session, sevenDay: sample.usage.weekAll };
-        stored.lastUsageAt = at;
-        if (Object.keys(sample.usage.perModel).length > 0) {
-          stored.lastPerModel = sample.usage.perModel;
-          stored.lastPerModelAt = at;
-        }
-      }
-      if (sample.ok || stored.needsReauth === true) saveAccounts(idx2);
-      if (stored.needsReauth === true) {
-        rejected.add(candidate.accountUuid);
-        log("decide.candidate_rejected", { account: short, error: "needs reauth" });
-        return "skip";
-      }
-      if (!sample.ok) {
-        log("decide.candidate_unverified", { account: short });
-        return "go";
-      }
-      log(isExhausted(stored, ctx) ? "decide.candidate_walled" : "decide.candidate_verified", {
-        account: short,
-        session: sample.usage.session.usedPercentage,
-        weekly: sample.usage.weekAll.usedPercentage,
-      });
-      return "rerank";
-    };
-
     while (true) {
       const cur = loadAccounts();
       const seat = seatOf(cur);
       const ctx = { now, thresholds: bars, currentAccountUuid: seat?.accountUuid ?? null, switchFamilies };
       const best = pickBest(usable(cur.accounts), ctx);
       if (!best) break;
-      if ((await verified(best, ctx)) !== "go") continue;
       try {
         await performSwap(best);
       } catch (e) {

package/src/lib/oauth.ts

@@ -40,7 +40,7 @@ export function isDeadCredential(creds: OAuthCreds): boolean {
   return creds.refreshToken === "" || creds.accessToken === "";
 }
 
-export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Promise<OAuthCreds> {
+export async function refreshCredential(creds: OAuthCreds, now = Date.now(), signal?: AbortSignal): Promise<OAuthCreds> {
   if (isDeadCredential(creds)) throw new InvalidGrantError("credential was cleared after a failed refresh");
   const scope = (creds.scopes?.length ? creds.scopes : DEFAULT_SCOPES).join(" ");
   const body = {
@@ -55,6 +55,7 @@ export async function refreshCredential(creds: OAuthCreds, now = Date.now()): Pr
     res = await http.post(TOKEN_URL, {
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify(body),
+      signal,
     });
   } catch (e) {
     throw new Error(`token endpoint unreachable: ${e instanceof Error ? e.message : String(e)}`);

package/src/lib/paths.ts

@@ -28,6 +28,11 @@ export const paths = {
   onboardDir: join(TM_HOME, "onboard"),
   sampleDir: join(TM_HOME, "sample"),
   credsDir: join(TM_HOME, "creds"),
+  setupTokensJson: join(TM_HOME, "setup-tokens.json"),
+  setupTokenDir: join(TM_HOME, "setup-token"),
+  cloudSessionsJson: join(TM_HOME, "cloud", "sessions.json"),
+  cloudWalledJson: join(TM_HOME, "cloud", "walled.json"),
+  cloudLockFile: join(TM_HOME, "cloud", "lock"),
 
   claudeJson: env("TOKENMAXXING_CLAUDE_JSON", join(HOME, ".claude.json")),
   claudeSettings: env(

package/src/lib/sample.ts

@@ -1,15 +1,18 @@
 import { mkdirSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { minBy } from "es-toolkit";
 import { z } from "zod";
 import { readItem, writeItem, deleteItem, liveTarget, parkedTarget, isolatedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
 import { credItemFor, paths } from "./paths.ts";
 import { withClaudeRefreshLock } from "./claudelock.ts";
+import { withLock } from "./lock.ts";
+import { readOAuthAccount } from "./claudejson.ts";
 import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity, IdentityUnavailableError, InvalidGrantError } from "./oauth.ts";
 import { FullUsageSchema, probeUsage } from "./usage.ts";
-import { loadAccounts } from "./state.ts";
+import { POST_SWAP_COOLDOWN_MS, loadAccounts, loadLastSwapAt, saveAccounts } from "./state.ts";
 import { keepRotatedPair } from "./swap.ts";
 import { log } from "./log.ts";
-import { CredentialBlobSchema, TokenIdentitySchema, type Account, type OAuthCreds, type TokenIdentity } from "./types.ts";
+import { CredentialBlobSchema, TokenIdentitySchema, type Account, type Config, type OAuthCreds, type TokenIdentity } from "./types.ts";
 
 const SampleOutcomeSchema = z.discriminatedUnion("ok", [
   z.object({ ok: z.literal(true), usage: FullUsageSchema }),
@@ -44,10 +47,12 @@ function refreshPlanFields(account: Account, creds: OAuthCreds): void {
   if (creds.rateLimitTier != null) account.rateLimitTier = creds.rateLimitTier;
 }
 
-export async function probeParkedUsage(
-  account: Account,
-  opts: { retries?: number; refreshParked?: boolean; killMs?: number; signal?: AbortSignal } = {},
-): Promise<SampleOutcome> {
+const ProbeFailureSchema = z.object({ ok: z.literal(false), reason: z.string() });
+type ProbeFailure = z.infer<typeof ProbeFailureSchema>;
+const PreparedProbeSchema = z.discriminatedUnion("ok", [z.object({ ok: z.literal(true), dir: z.string(), installed: z.string() }), ProbeFailureSchema]);
+type PreparedProbe = z.infer<typeof PreparedProbeSchema>;
+
+async function prepareParkedProbe(account: Account, dir: string, signal?: AbortSignal): Promise<PreparedProbe> {
   const backup = parkedTarget(account.keychainItem);
   const parkedRaw = await readItem(backup);
   if (!parkedRaw) return { ok: false, reason: "no parked credential - run `tokenmaxxing auth`" };
@@ -62,13 +67,11 @@ export async function probeParkedUsage(
     account.needsReauth = true;
     return { ok: false, reason: "parked credential was cleared after a failed refresh - re-auth with `tokenmaxxing auth`" };
   }
-  if (opts.refreshParked === false && isAccessTokenExpiring(creds, 300_000)) {
-    return { ok: false, reason: "parked access token is near expiry - verification requires an unexpired token" };
-  }
 
   const liveRaw = await readItem(liveTarget());
   let liveAccount: string | null = null;
   let liveToken: string | null = null;
+  let liveRefresh: string | null = null;
   if (liveRaw != null) {
     let liveCreds: OAuthCreds;
     try {
@@ -78,8 +81,9 @@ export async function probeParkedUsage(
     }
     if (!isDeadCredential(liveCreds)) {
       liveToken = liveCreds.accessToken;
+      liveRefresh = liveCreds.refreshToken;
       try {
-        liveAccount = (await fetchTokenIdentity(liveCreds.accessToken, opts.signal)).accountUuid;
+        liveAccount = (await fetchTokenIdentity(liveCreds.accessToken, signal)).accountUuid;
       } catch (e) {
         return { ok: false, reason: `cannot verify the live credential's owner (${(e instanceof Error ? e.message : String(e)).slice(0, 80)}) - refusing to sample a possibly-live account` };
       }
@@ -98,10 +102,7 @@ export async function probeParkedUsage(
   };
 
   if (isAccessTokenExpiring(creds, 300_000)) {
-    if (opts.refreshParked === false) {
-      return { ok: false, reason: "parked access token is near expiry - verification requires an unexpired token" };
-    }
-    const owner = await checkIdentity(creds, account);
+    const owner = await checkIdentity(creds, account, signal);
     if (owner.status === "mismatch") {
       const kept = await relocate(owner.owner);
       account.needsReauth = true;
@@ -110,9 +111,9 @@ export async function probeParkedUsage(
     if (owner.status === "unavailable" && !owner.stale) {
       return { ok: false, reason: `${owner.reason} - refusing to refresh a parked credential whose owner cannot be verified` };
     }
-    const rotate = async (): Promise<{ fresh: OAuthCreds } | { failed: SampleOutcome }> => {
+    const rotate = async (): Promise<{ fresh: OAuthCreds } | { failed: ProbeFailure }> => {
       try {
-        return { fresh: await refreshCredential(creds) };
+        return { fresh: await refreshCredential(creds, Date.now(), signal) };
       } catch (e) {
         if (e instanceof InvalidGrantError) {
           account.needsReauth = true;
@@ -121,16 +122,24 @@ export async function probeParkedUsage(
         return { failed: { ok: false, reason: `token refresh failed: ${e instanceof Error ? e.message : String(e)}` } };
       }
     };
-    let result: { fresh: OAuthCreds } | { failed: SampleOutcome };
+    let result: { fresh: OAuthCreds } | { failed: ProbeFailure };
     if (owner.status === "match") {
       result = await rotate();
     } else {
+      if (liveRefresh != null && creds.refreshToken === liveRefresh) {
+        return { ok: false, reason: "this slot holds a copy of the LIVE login's grant - refusing to rotate it from a parked slot; run `tokenmaxxing switch` to reconcile" };
+      }
       try {
+        signal?.throwIfAborted();
         result = await withClaudeRefreshLock(async (lock) => {
           const rotated = await rotate();
           if ("failed" in rotated) return rotated;
-          const verified = await checkIdentity(rotated.fresh, account);
-          if (verified.status !== "mismatch") return rotated;
+          const verified = await checkIdentity(rotated.fresh, account, signal);
+          if (verified.status === "match") return rotated;
+          if (verified.status === "unavailable") {
+            await writeItem(backup, JSON.stringify({ claudeAiOauth: rotated.fresh }));
+            return { failed: { ok: false, reason: `${verified.reason} - the rotated pair stays in this slot unverified until the next pass` } };
+          }
           const trueOwner = loadAccounts().accounts.find((a) => a.accountUuid === verified.owner.accountUuid) ?? null;
           const kept = await keepRotatedPair({ fresh: rotated.fresh, owner: trueOwner, fallback: account, liveOwnerUuid: liveAccount, expectedLiveToken: liveToken, lock });
           account.needsReauth = true;
@@ -145,7 +154,7 @@ export async function probeParkedUsage(
     await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
   }
 
-  const identity = await checkIdentity(creds, account, opts.signal);
+  const identity = await checkIdentity(creds, account, signal);
   if (identity.status === "mismatch") {
     const kept = await relocate(identity.owner);
     account.needsReauth = true;
@@ -156,27 +165,100 @@ export async function probeParkedUsage(
   }
   refreshPlanFields(account, creds);
 
-  const dir = join(paths.sampleDir, credItemFor(account.accountUuid));
   rmSync(dir, { recursive: true, force: true });
   mkdirSync(dir, { recursive: true });
-  const isoTarget = isolatedTarget(dir);
-  const installed = JSON.stringify({ claudeAiOauth: opts.refreshParked === false ? { ...creds, refreshToken: "" } : creds });
-
+  const installed = JSON.stringify({ claudeAiOauth: creds });
   try {
-    await writeItem(isoTarget, installed);
+    await writeItem(isolatedTarget(dir), installed);
     writeFileSync(join(dir, ".claude.json"), JSON.stringify({ oauthAccount: account.oauthAccount, hasCompletedOnboarding: true }));
-    const usage = await probeUsage(dir, Date.now(), opts);
-    return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+  } catch (e) {
+    await finishParkedProbe(account, { dir, installed });
+    throw e;
+  }
+  return { ok: true, dir, installed };
+}
+
+async function runParkedProbe(dir: string, opts: { retries?: number }): Promise<SampleOutcome> {
+  const usage = await probeUsage(dir, Date.now(), { retries: opts.retries });
+  return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+}
+
+async function finishParkedProbe(account: Account, prepared: { dir: string; installed: string }): Promise<void> {
+  const isoTarget = isolatedTarget(prepared.dir);
+  const backup = parkedTarget(account.keychainItem);
+  try {
+    const afterIso = await readItem(isoTarget);
+    if (afterIso && afterIso !== prepared.installed) {
+      const parkedNow = await readItem(backup);
+      const installedToken = CredentialBlobSchema.parse(JSON.parse(prepared.installed)).claudeAiOauth.accessToken;
+      const parkedToken = parkedNow == null ? null : CredentialBlobSchema.parse(JSON.parse(parkedNow)).claudeAiOauth.accessToken;
+      if (parkedToken === installedToken) await writeItem(backup, claudeAiOauthOnly(afterIso));
+      else log("sample.harvest_skipped", { account: account.accountUuid.slice(0, 8) });
+    }
   } finally {
-    try {
-      if (opts.refreshParked !== false) {
-        const afterIso = await readItem(isoTarget);
-        if (afterIso && afterIso !== installed) await writeItem(backup, claudeAiOauthOnly(afterIso));
-      }
-    } finally {
-      await deleteItem(isoTarget);
-      rmSync(dir, { recursive: true, force: true });
+    await deleteItem(isoTarget);
+    rmSync(prepared.dir, { recursive: true, force: true });
+  }
+}
+
+export async function probeParkedUsage(account: Account): Promise<SampleOutcome> {
+  const prepared = await prepareParkedProbe(account, join(paths.sampleDir, credItemFor(account.accountUuid)));
+  if (!prepared.ok) return prepared;
+  try {
+    return await runParkedProbe(prepared.dir, {});
+  } finally {
+    await finishParkedProbe(account, prepared);
+  }
+}
+
+const PREPARE_DEADLINE_MS = 20_000;
+
+export async function sampleOldestParked(cfg: Config): Promise<void> {
+  const reserved = await withLock(paths.lockFile, async () => {
+    const now = Date.now();
+    const lastSwapAt = loadLastSwapAt();
+    if (lastSwapAt != null && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) return null;
+    const idx = loadAccounts();
+    const live = readOAuthAccount()?.accountUuid ?? null;
+    const sampledAt = (a: Account) => Math.max(a.lastUsageAt ?? 0, a.lastProbeAt ?? 0);
+    const stale = idx.accounts.filter((a) => a.accountUuid !== live && a.needsReauth !== true && now - sampledAt(a) > cfg.policy.usagePollTtlMs);
+    const target = minBy(stale, sampledAt);
+    if (!target) return null;
+    target.lastProbeAt = now;
+    const prepared = await prepareParkedProbe(target, join(paths.sampleDir, `${credItemFor(target.accountUuid)}-tick`), AbortSignal.timeout(PREPARE_DEADLINE_MS));
+    saveAccounts(idx);
+    if (!prepared.ok) {
+      log("sample.parked_failed", { account: target.accountUuid.slice(0, 8), reason: prepared.reason.slice(0, 200) });
+      return null;
     }
+    return { account: target, prepared };
+  });
+  if (!reserved) return;
+  const { account, prepared } = reserved;
+  const startedAt = Date.now();
+  let outcome: SampleOutcome | null = null;
+  try {
+    outcome = await runParkedProbe(prepared.dir, { retries: 0 });
+  } finally {
+    await withLock(paths.lockFile, async () => {
+      await finishParkedProbe(account, prepared);
+      if (outcome == null) return;
+      const idx = loadAccounts();
+      const stored = idx.accounts.find((a) => a.accountUuid === account.accountUuid);
+      if (stored && outcome.ok && (stored.lastUsageAt == null || startedAt > stored.lastUsageAt)) {
+        stored.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
+        stored.lastUsageAt = startedAt;
+        if (Object.keys(outcome.usage.perModel).length > 0) {
+          stored.lastPerModel = outcome.usage.perModel;
+          stored.lastPerModelAt = startedAt;
+        }
+        saveAccounts(idx);
+      }
+      log(outcome.ok ? "sample.parked_ok" : "sample.parked_failed", {
+        account: account.accountUuid.slice(0, 8),
+        ...(outcome.ok ? {} : { reason: outcome.reason.slice(0, 200) }),
+      });
+    });
   }
 }
 

package/src/lib/setuptokens.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync } from "node:fs";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+export const CURSOR_SECRET_VALUE_CAP_BYTES = 4096;
+export const SETUP_TOKEN_STALE_MS = 335 * 86_400_000;
+
+const SetupTokenSchema = z.object({ accountUuid: z.string().min(1), label: z.string().min(1), token: z.string().min(1), mintedAt: z.number() });
+export type SetupToken = z.infer<typeof SetupTokenSchema>;
+
+const SetupTokensFileSchema = z.object({ version: z.literal(1), tokens: z.array(SetupTokenSchema).default([]) });
+export type SetupTokensFile = z.infer<typeof SetupTokensFileSchema>;
+
+export const CloudTokenSchema = z.object({ label: z.string().min(1), token: z.string().min(1) });
+export type CloudToken = z.infer<typeof CloudTokenSchema>;
+export const CloudTokensSchema = z.array(CloudTokenSchema).min(1);
+
+export function loadSetupTokens(): SetupTokensFile {
+  if (!existsSync(paths.setupTokensJson)) return { version: 1, tokens: [] };
+  let json: unknown;
+  try {
+    json = JSON.parse(readFileSync(paths.setupTokensJson, "utf8"));
+  } catch {
+    throw new Error(`${paths.setupTokensJson} is corrupt (unparsable JSON) - refusing to treat a damaged token store as empty; repair or remove the file`);
+  }
+  const parsed = SetupTokensFileSchema.safeParse(json);
+  if (!parsed.success) {
+    throw new Error(`${paths.setupTokensJson} does not match the setup-token schema - repair or remove the file`);
+  }
+  return parsed.data;
+}
+
+export function saveSetupTokens(file: SetupTokensFile): void {
+  writeFileAtomic(paths.setupTokensJson, JSON.stringify(SetupTokensFileSchema.parse(file), null, 2) + "\n");
+}
+
+export function cursorSecretValue(tokens: CloudToken[]): string {
+  return JSON.stringify(CloudTokensSchema.parse(tokens));
+}

package/src/lib/swap.ts

@@ -1,4 +1,3 @@
-import { z } from "zod";
 import { clearDepletedWait, clearUsageSnapshots, loadAccounts, saveAccounts, saveLastSwapAt } from "./state.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
 import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity, IdentityUnavailableError, InvalidGrantError, RefreshRejectedError } from "./oauth.ts";
@@ -11,9 +10,6 @@ function parseBlob(raw: string) {
   return CredentialBlobSchema.parse(JSON.parse(raw));
 }
 
-const VerifyVerdictSchema = z.enum(["go", "rerank", "skip"]);
-export type VerifyVerdict = z.infer<typeof VerifyVerdictSchema>;
-
 export async function performSwap(target: Account): Promise<void> {
   const idx = loadAccounts();
 

package/src/lib/types.ts

@@ -68,6 +68,7 @@ export const AccountSchema = z.object({
   lastPerModel: z.record(z.string(), UsageWindowSchema).optional(),
   lastPerModelAt: z.number().optional(),
   lastUsageAt: z.number().optional(),
+  lastProbeAt: z.number().optional(),
   enforcedUntil: z.number().optional(),
   needsReauth: z.boolean().optional(),
   subscriptionType: z.string().optional(),

package/src/lib/usage.ts

@@ -280,17 +280,9 @@ const SpawnResultSchema = z.object({
 });
 type SpawnResult = z.infer<typeof SpawnResultSchema>;
 
-async function spawnClaudeBounded(
-  cmd: string[],
-  env: Record<string, string>,
-  killMs = PROBE_KILL_MS,
-  signal?: AbortSignal,
-): Promise<SpawnResult | null> {
-  signal?.throwIfAborted();
+async function spawnClaudeBounded(cmd: string[], env: Record<string, string>): Promise<SpawnResult | null> {
   const p = Bun.spawn(cmd, { env, stdout: "pipe", stderr: "pipe" });
-  const abort = () => p.kill("SIGKILL");
-  signal?.addEventListener("abort", abort, { once: true });
-  const killer = setTimeout(() => p.kill("SIGKILL"), killMs);
+  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([
@@ -303,14 +295,13 @@ async function spawnClaudeBounded(
     return { exitCode: p.exitCode, stdout, stderr };
   } finally {
     clearTimeout(killer);
-    signal?.removeEventListener("abort", abort);
   }
 }
 
-async function probeUsageOnce(env: Record<string, string>, now: number, killMs: number, signal?: AbortSignal): Promise<FullUsage | null> {
+async function probeUsageOnce(env: Record<string, string>, now: number): Promise<FullUsage | null> {
   let out: string;
   try {
-    const r = await spawnClaudeBounded([resolveRealClaude(), "-p", "/usage", "--output-format", "json"], env, killMs, signal);
+    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;
@@ -341,20 +332,25 @@ async function probeUsageOnce(env: Record<string, string>, now: number, killMs:
 
 const PROBE_RETRY_DELAYS_MS = [2000, 5000];
 
+export function scrubCredentialEnv(env: Record<string, string>): Record<string, string> {
+  const scrubbed = { ...env };
+  for (const k of CRED_ENV_OVERRIDES) delete scrubbed[k];
+  return scrubbed;
+}
+
 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];
+  const env = scrubCredentialEnv({ ...process.env, TOKENMAXXING_PROBE: "1", [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) });
   if (configDir) env.CLAUDE_CONFIG_DIR = configDir;
   return env;
 }
 
-export async function probeUsage(configDir?: string, now = Date.now(), opts: { retries?: number; killMs?: number; signal?: AbortSignal } = {}): Promise<FullUsage | null> {
+export async function probeUsage(configDir?: string, now = Date.now(), opts: { retries?: number } = {}): Promise<FullUsage | null> {
   const env = probeEnv(configDir);
 
   for (let attempt = 0; ; attempt++) {
-    const full = await probeUsageOnce(env, now, opts.killMs ?? PROBE_KILL_MS, opts.signal);
+    const full = await probeUsageOnce(env, now);
     if (full) return full;
-    if (attempt >= (opts.retries ?? PROBE_RETRY_DELAYS_MS.length) || opts.signal?.aborted) {
+    if (attempt >= (opts.retries ?? PROBE_RETRY_DELAYS_MS.length)) {
       log("usage.probe_gave_up", { attempts: attempt + 1 });
       return null;
     }

package/src/main.ts

@@ -25,6 +25,9 @@ import { cmdRename } from "./cli/rename.ts";
 import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
+import { cmdSetupToken } from "./cli/setuptoken.ts";
+import { cmdCloudRun } from "./cli/cloudrun.ts";
+import { cmdCursorInit } from "./cli/cursorinit.ts";
 import { timerDeactivationHint, uninstallSupervisor } from "./lib/install.ts";
 import { c, emitError, emitJson } from "./cli/render.ts";
 
@@ -51,8 +54,11 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex] <sel>
   ${c.cyan("tokenmaxxing uninstall")}  remove supervisor + settings entries
+  ${c.cyan("tokenmaxxing setup-token")} [--print | rm <label|uuid>]  Cursor Cloud only: mint one \`claude setup-token\` per pooled account (browser sign-in each) and print the TOKENMAXXING_TOKENS secret value; ${c.cyan("--print")} prints the stored set, ${c.cyan("rm")} drops one
+  ${c.cyan("tokenmaxxing cursor init")} [dir]  write the Claude relay subagent (.cursor/agents/claude.md) and .cursor/environment.json into a repo
+  ${c.cyan("tokenmaxxing cloud run")} [--session <id>] [--max-turns <n>] "<prompt>"  on a Cursor Cloud VM: run claude -p on a setup token from TOKENMAXXING_TOKENS, rotate to the next token on a usage limit
 
-  ${c.cyan("--json")}                  print one JSON document on stdout instead of text (status, ls, config, doctor, check, switch, rename, rm, uninstall; one per tick for watch); every document carries ${c.bold("ok")}, failures add ${c.bold("error")}
+  ${c.cyan("--json")}                  print one JSON document on stdout instead of text (status, ls, config, doctor, check, switch, rename, rm, uninstall, setup-token --print, cursor init, cloud run; one per tick for watch); every document carries ${c.bold("ok")}, failures add ${c.bold("error")}
 
   ${c.dim("(aliased as")} ${c.cyan("xx")}${c.dim(")")} - then just run ${c.bold("claude")} as always; it switches accounts near quota automatically.`);
 }
@@ -134,6 +140,17 @@ async function main(): Promise<number> {
       return args.includes("--codex") ? cmdCodexRm(rest[0], json) : cmdRm(rest[0], json);
     }
     case "rename": return cmdRename(args.slice(1), json);
+    case "setup-token": return cmdSetupToken(args.slice(1), json);
+    case "cursor": {
+      if (args[1] === "init") return cmdCursorInit(args.slice(2), json);
+      emitError({ json, message: "usage: tokenmaxxing cursor init [dir]" });
+      return 2;
+    }
+    case "cloud": {
+      if (args[1] === "run") return cmdCloudRun(args.slice(2), json);
+      emitError({ json, message: 'usage: tokenmaxxing cloud run [--session <id>] [--max-turns <n>] "<prompt>"' });
+      return 2;
+    }
     case "uninstall": {
       const out = uninstallSupervisor();
       const removed = [