tokenmaxxing 1.28.0 → 1.30.0

package/DESIGN.md

@@ -105,7 +105,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 ---
 
 ## 7. Scope
-**v1:** `tokenmaxxing init` / `add` / `ls` / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; threshold swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
+**v1:** `tokenmaxxing init` / `add` / `ls` (removed in 1.30.0, `status --cached` covers it) / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; threshold swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
 
 **v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
 
@@ -115,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

@@ -68,14 +68,15 @@ claude                  # use claude as always
 | `tokenmaxxing auth [sel \| --all]` | reauthenticate a pooled account in place: bare lists the pool (emails shown) and asks which; a selector targets one account and tells you the email to sign in with; `--all` walks every needs-reauth account one by one |
 | `tokenmaxxing switch [sel]` | switch the claude pool: bare picks the best account (no-op when the current one wins), a selector targets one |
 | `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 watch [seconds]` | live status: re-render every N seconds (default 120, floor 30) |
+| `tokenmaxxing status [--cached]` | accounts with 5h / weekly usage bars, active + exhausted-until-reset; `--cached` renders the stored figures without sampling |
 | `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
 | `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`, `config`, `doctor`, `check`, `switch`, `rename`, `rm`, `uninstall`, `setup-token --print`, `cursor init`, and `cloud run` (`ok` mirrors the exit code, failures add `error`) |
 
 ## How switching decides
 
@@ -123,10 +124,14 @@ tokenmaxxing add --codex    # log in another account, isolated - your primary lo
 codex                       # use codex as always
 ```
 
-Codex mechanics differ from Claude Code in one hard way: a running codex process refuses a credential swapped to a different account, so **a restart is the switch**. The installed Stop hook runs the same pace-pressure decision at each turn boundary (usage read free from codex's own rate-limit endpoint: percentages plus absolute reset times, weekly aggregate and per-model caps alike); when it swaps, the supervisor relaunches `codex resume <session-id>` on the fresh account with the transcript intact. `tokenmaxxing switch --codex [sel]` does it manually, `status`/`watch`/`ls` show both pools.
+Codex mechanics differ from Claude Code in one hard way: a running codex process refuses a credential swapped to a different account, so **a restart is the switch**. The installed Stop hook runs the same pace-pressure decision at each turn boundary (usage read free from codex's own rate-limit endpoint: percentages plus absolute reset times, weekly aggregate and per-model caps alike); when it swaps, the supervisor relaunches `codex resume <session-id>` on the fresh account with the transcript intact. `tokenmaxxing switch --codex [sel]` does it manually, `status` (and `status --cached`) shows both pools.
 
 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.28.0",
+  "version": "1.30.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/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,6 +44,7 @@ export async function cmdRm(selector?: string, json = false): Promise<number> {
         return 1;
       }
     }
+    const setupTokens = loadSetupTokens();
     await deleteItem(parkedTarget(a.keychainItem));
     const item = credItemFor(a.accountUuid);
     for (const sampleDir of [join(paths.sampleDir, item), join(paths.sampleDir, `${item}-tick`)]) {
@@ -51,6 +53,9 @@ export async function cmdRm(selector?: string, json = false): Promise<number> {
     }
     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/cli/status.ts

@@ -15,7 +15,7 @@ import { gatedFamilies, type FullUsage } from "../lib/usage.ts";
 import { ThresholdsSchema, UsageWindowSchema, type Account, type CodexWindow, type Config, type UsageWindow } from "../lib/types.ts";
 
 const SampleReportSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), source: z.enum(["statusline", "probe"]) }),
+  z.object({ ok: z.literal(true), source: z.enum(["statusline", "probe", "cached"]) }),
   z.object({ ok: z.literal(false), reason: z.string() }),
 ]);
 
@@ -31,6 +31,7 @@ const ClaudeStatusAccountSchema = z.object({
   usage: z.object({ fiveHour: UsageWindowSchema, week: UsageWindowSchema }).nullable(),
   perModel: z.record(z.string(), UsageWindowSchema),
   usageAt: z.number().nullable(),
+  perModelAt: z.number().nullable(),
   sample: SampleReportSchema,
 });
 type ClaudeStatusAccount = z.infer<typeof ClaudeStatusAccountSchema>;
@@ -83,11 +84,11 @@ function currentCodexWindow(w: CodexWindow, now: number): CodexWindow {
   return { ...currentWindow(w, !isSessionWindow({ window: w }), now), windowSeconds: w.windowSeconds };
 }
 
-async function collectClaude(input: { cfg: Config; now: number }): Promise<StatusReport["claude"]> {
-  const { cfg, now } = input;
+async function collectClaude(input: { cfg: Config; now: number; cached: boolean }): Promise<StatusReport["claude"]> {
+  const { cfg, now, cached } = input;
   let idx = loadAccounts();
   const samples = new Map<string, { outcome: SampleOutcome; viaTee: boolean }>();
-  if (idx.accounts.length > 0) {
+  if (idx.accounts.length > 0 && !cached) {
     await withLock(paths.lockFile, async () => {
       idx = loadAccounts();
       console.error(c.dim("sampling live usage..."));
@@ -137,11 +138,11 @@ async function collectClaude(input: { cfg: Config; now: number }): Promise<Statu
 
   const families = gatedFamilies(loadUsage()?.model ?? null, cfg.policy.switchModels);
   const bars = thresholdBars(cfg);
-  const liveAccount = readOAuthAccount()?.accountUuid ?? null;
+  const liveAccount = cached ? idx.activeAccountUuid : (readOAuthAccount()?.accountUuid ?? null);
   const ordered = sortBy(idx.accounts, [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, now)]);
   const accounts = ordered.map((a): ClaudeStatusAccount => {
-    const sampled = samples.get(a.accountUuid) ?? { outcome: { ok: false, reason: "not sampled" }, viaTee: false };
-    const usage = sampled.outcome.ok ? sampled.outcome.usage : undefined;
+    const sampled = samples.get(a.accountUuid);
+    const usage = sampled?.outcome.ok ? sampled.outcome.usage : undefined;
     const aggregate = usage ? { fiveHour: usage.session, sevenDay: usage.weekAll } : a.lastUsage;
     const perModel = usage ? usage.perModel : (a.lastPerModel ?? {});
     return {
@@ -156,7 +157,14 @@ async function collectClaude(input: { cfg: Config; now: number }): Promise<Statu
       usage: aggregate ? { fiveHour: currentWindow(aggregate.fiveHour, false, now), week: currentWindow(aggregate.sevenDay, true, now) } : null,
       perModel: Object.fromEntries(Object.entries(perModel).map(([name, w]) => [name, currentWindow(w, true, now)])),
       usageAt: a.lastUsageAt ?? null,
-      sample: sampled.outcome.ok ? { ok: true, source: sampled.viaTee ? "statusline" : "probe" } : { ok: false, reason: sampled.outcome.reason },
+      perModelAt: a.lastPerModelAt ?? null,
+      sample: sampled
+        ? sampled.outcome.ok
+          ? { ok: true, source: sampled.viaTee ? "statusline" : "probe" }
+          : { ok: false, reason: sampled.outcome.reason }
+        : cached
+          ? { ok: true, source: "cached" }
+          : { ok: false, reason: "not sampled" },
     };
   });
   return {
@@ -167,34 +175,38 @@ async function collectClaude(input: { cfg: Config; now: number }): Promise<Statu
   };
 }
 
-async function collectCodex(input: { cfg: Config; now: number }): Promise<StatusReport["codex"]> {
-  const { cfg, now } = input;
+async function collectCodex(input: { cfg: Config; now: number; cached: boolean }): Promise<StatusReport["codex"]> {
+  const { cfg, now, cached } = input;
   const bars = thresholdBars(cfg);
   let index = loadCodexAccounts();
   if (index.accounts.length === 0) return { bars, accounts: [] };
 
-  console.error(c.dim("sampling codex usage..."));
   const outcomes = new Map<string, CodexSampleOutcome>();
   let liveId: string | null = null;
-  await withLock(codexPaths.lockFile, async () => {
-    index = loadCodexAccounts();
-    liveId = liveCodexAccountId();
-    await Promise.all(
-      index.accounts.map(async (account) => {
-        const outcome = await sampleCodexAccount({ account, liveAccountId: liveId, now });
-        outcomes.set(account.accountId, outcome);
-        if (outcome.ok) {
-          account.lastUsage = { aggregate: outcome.usage.aggregate, perLimit: outcome.usage.perLimit };
-          account.lastUsageAt = Date.now();
-          if (outcome.usage.email != null) account.email = outcome.usage.email;
-          if (outcome.usage.planType != null) account.planType = outcome.usage.planType;
-        } else if (outcome.deadGrant) {
-          account.needsReauth = true;
-        }
-      }),
-    );
-    saveCodexAccounts({ index });
-  });
+  if (cached) {
+    liveId = index.activeAccountId;
+  } else {
+    console.error(c.dim("sampling codex usage..."));
+    await withLock(codexPaths.lockFile, async () => {
+      index = loadCodexAccounts();
+      liveId = liveCodexAccountId();
+      await Promise.all(
+        index.accounts.map(async (account) => {
+          const outcome = await sampleCodexAccount({ account, liveAccountId: liveId, now });
+          outcomes.set(account.accountId, outcome);
+          if (outcome.ok) {
+            account.lastUsage = { aggregate: outcome.usage.aggregate, perLimit: outcome.usage.perLimit };
+            account.lastUsageAt = Date.now();
+            if (outcome.usage.email != null) account.email = outcome.usage.email;
+            if (outcome.usage.planType != null) account.planType = outcome.usage.planType;
+          } else if (outcome.deadGrant) {
+            account.needsReauth = true;
+          }
+        }),
+      );
+      saveCodexAccounts({ index });
+    });
+  }
 
   const ordered = sortBy(index.accounts, [
     (a) => (a.needsReauth ? 1 : 0),
@@ -205,7 +217,7 @@ async function collectCodex(input: { cfg: Config; now: number }): Promise<Status
     },
   ]);
   const accounts = ordered.map((account): CodexStatusAccount => {
-    const outcome = outcomes.get(account.accountId) ?? { ok: false, reason: "not sampled", deadGrant: false };
+    const outcome = outcomes.get(account.accountId);
     const usage = account.lastUsage;
     return {
       label: account.label,
@@ -224,7 +236,13 @@ async function collectCodex(input: { cfg: Config; now: number }): Promise<Status
           }
         : null,
       usageAt: account.lastUsageAt ?? null,
-      sample: outcome.ok ? { ok: true, source: "probe" } : { ok: false, reason: outcome.reason },
+      sample: outcome
+        ? outcome.ok
+          ? { ok: true, source: "probe" }
+          : { ok: false, reason: outcome.reason }
+        : cached
+          ? { ok: true, source: "cached" }
+          : { ok: false, reason: "not sampled" },
     };
   });
   return { bars, accounts };
@@ -298,6 +316,10 @@ function sampleFailedNotes(input: { cached: boolean; usageAt: number | null; rea
   ];
 }
 
+function cachedNote(usageAt: number | null, now: number): Note {
+  return { paint: c.dim, text: usageAt != null ? `cached ${fmtAgo(usageAt, now)}` : "never sampled" };
+}
+
 function headerLine(input: { active: boolean; needsReauth: boolean; exhausted: boolean; name: string; tier: string | null }): string {
   const marker = input.active ? c.green("●") : c.dim("○");
   const badges: string[] = [];
@@ -317,7 +339,11 @@ function codexCard(account: CodexStatusAccount, now: number): Card {
       for (const window of windows) lines.push(usageRow(codexLimitLabel({ limitName: name }), window));
     }
   }
-  const notes = account.sample.ok ? [] : sampleFailedNotes({ cached: account.usage != null, usageAt: account.usageAt, reason: account.sample.reason, now });
+  const notes = account.sample.ok
+    ? account.sample.source === "cached"
+      ? [cachedNote(account.usageAt, now)]
+      : []
+    : sampleFailedNotes({ cached: account.usage != null, usageAt: account.usageAt, reason: account.sample.reason, now });
   return { lines, notes };
 }
 
@@ -342,6 +368,11 @@ function claudeCard(a: ClaudeStatusAccount, now: number, staleAfterMs: number):
     const age = a.usageAt != null ? fmtAgo(a.usageAt, now) : "age unknown";
     notes.push({ paint: stale ? c.yellow : c.dim, text: `statusline tee ${age}${stale ? " (stale)" : ""}` });
   }
+  if (a.sample.ok && a.sample.source === "cached") {
+    const note = cachedNote(a.usageAt, now);
+    const perModelAged = Object.keys(a.perModel).length > 0 && a.perModelAt !== a.usageAt;
+    notes.push(perModelAged ? { ...note, text: `${note.text}, per-model ${a.perModelAt != null ? fmtAgo(a.perModelAt, now) : "age unknown"}` } : note);
+  }
   if (!a.sample.ok) {
     notes.push(...sampleFailedNotes({ cached: a.usage != null || Object.keys(a.perModel).length > 0, usageAt: a.usageAt, reason: a.sample.reason, now }));
   }
@@ -365,17 +396,15 @@ function renderClaude(input: { claude: StatusReport["claude"]; codexPooled: bool
   renderGrid(claude.accounts.map((a) => claudeCard(a, now, staleAfterMs)));
 }
 
-export async function cmdStatus(opts: { json?: boolean; preRender?: () => void } = {}): Promise<number> {
-  const { json = false } = opts;
+export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {}): Promise<number> {
+  const { json = false, cached = false } = opts;
   const cfg = loadConfig();
   const now = Date.now();
-  const claude = await collectClaude({ cfg, now });
+  const claude = await collectClaude({ cfg, now, cached });
   if (!json) {
-    opts.preRender?.();
-    const at = Date.now();
-    renderClaude({ claude, codexPooled: loadCodexAccounts().accounts.length > 0, now: at, staleAfterMs: cfg.policy.usagePollTtlMs });
+    renderClaude({ claude, codexPooled: loadCodexAccounts().accounts.length > 0, now: Date.now(), staleAfterMs: cfg.policy.usagePollTtlMs });
   }
-  const codex = await collectCodex({ cfg, now });
+  const codex = await collectCodex({ cfg, now, cached });
   if (json) {
     const report: StatusReport = { now, claude, codex };
     emitJson({ ok: true, ...report });

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/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/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/usage.ts

@@ -332,9 +332,14 @@ async function probeUsageOnce(env: Record<string, string>, now: number): Promise
 
 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;
 }

package/src/main.ts

@@ -15,9 +15,7 @@ import { cmdCodexInit } from "./cli/codexinit.ts";
 import { cmdCodexSwitch } from "./cli/codexswitch.ts";
 import { runCodexSupervisor } from "./entries/codexsupervisor.ts";
 import { runCodexStopHook } from "./entries/codexstophook.ts";
-import { cmdLs } from "./cli/ls.ts";
 import { cmdStatus } from "./cli/status.ts";
-import { cmdWatch } from "./cli/watch.ts";
 import { cmdDoctor } from "./cli/doctor.ts";
 import { cmdRm } from "./cli/rm.ts";
 import { cmdCodexRm } from "./cli/codexrm.ts";
@@ -25,10 +23,14 @@ 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";
 
 const JSON_FLAG = "--json";
+const CACHED_FLAG = "--cached";
 const INTERACTIVE_COMMANDS = new Set(["init", "add", "auth"]);
 
 function printHelp(): void {
@@ -43,16 +45,17 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing add --codex")}   register an additional codex account (isolated login)
   ${c.cyan("tokenmaxxing auth")} [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every needs-reauth account, one by one)
   ${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 watch")} [seconds]  live status: re-render every N seconds (default 120)
+  ${c.cyan("tokenmaxxing status")} [--cached]  accounts with 5h / weekly / per-model usage bars (--cached: the stored figures, no sampling)
   ${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
   ${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, config, doctor, check, switch, rename, rm, uninstall, setup-token --print, cursor init, cloud run); 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.`);
 }
@@ -76,9 +79,15 @@ async function main(): Promise<number> {
 
   jsonMode = argv.includes(JSON_FLAG);
   const json = jsonMode;
-  const args = argv.filter((a) => a !== JSON_FLAG);
+  const cached = argv.includes(CACHED_FLAG);
+  const args = argv.filter((a) => a !== JSON_FLAG && a !== CACHED_FLAG);
   const sub = args[0];
 
+  if (cached && sub != null && sub !== "status") {
+    emitError({ json, message: `${CACHED_FLAG} applies to status only, not ${sub}` });
+    return 2;
+  }
+
   if (json && sub != null && INTERACTIVE_COMMANDS.has(sub)) {
     emitError({ json, message: `${sub} is interactive (it runs a login flow) and has no --json form` });
     return 2;
@@ -106,10 +115,10 @@ async function main(): Promise<number> {
     case "status": {
       const extra = args[1];
       if (extra != null) {
-        emitError({ json, message: `unknown status option: ${extra} (status takes no options)` });
+        emitError({ json, message: `unknown status option: ${extra} (status takes only ${CACHED_FLAG})` });
         return 2;
       }
-      return cmdStatus({ json });
+      return cmdStatus({ json, cached });
     }
     case "switch": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
@@ -126,14 +135,23 @@ async function main(): Promise<number> {
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "auth": return cmdAuth(args.slice(1));
-    case "ls": return cmdLs(json);
-    case "watch": return cmdWatch(args[1], json);
     case "doctor": return cmdDoctor(json);
     case "rm": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
       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 = [

package/src/cli/ls.ts

@@ -1,75 +0,0 @@
-import { loadAccounts } from "../lib/state.ts";
-import { loadCodexAccounts } from "../lib/codexstate.ts";
-import { liveCodexAccountId } from "../lib/codexsample.ts";
-import { c, claudeTierLabel, emitJson } from "./render.ts";
-
-export function cmdLs(json = false): number {
-  const idx = loadAccounts();
-
-  if (json) {
-    const codex = loadCodexAccounts();
-    const liveId = codex.accounts.length > 0 ? liveCodexAccountId() : null;
-    emitJson({
-      ok: true,
-      claude: {
-        activeAccountUuid: idx.activeAccountUuid,
-        accounts: idx.accounts.map((a) => ({
-          label: a.label,
-          email: a.email,
-          accountUuid: a.accountUuid,
-          organizationUuid: a.organizationUuid,
-          tier: claudeTierLabel(a),
-          active: a.accountUuid === idx.activeAccountUuid,
-          needsReauth: a.needsReauth === true,
-          addedAt: a.addedAt,
-        })),
-      },
-      codex: {
-        activeAccountId: liveId,
-        accounts: codex.accounts.map((account) => ({
-          label: account.label,
-          email: account.email,
-          accountId: account.accountId,
-          planType: account.planType,
-          active: account.accountId === liveId,
-          needsReauth: account.needsReauth === true,
-          addedAt: account.addedAt,
-        })),
-      },
-    });
-    return 0;
-  }
-
-  if (idx.accounts.length === 0) {
-    console.log(c.dim("no accounts yet - run `tokenmaxxing init` then `tokenmaxxing add`"));
-  }
-  for (const a of idx.accounts) {
-    const active = a.accountUuid === idx.activeAccountUuid;
-    const marker = active ? c.green("●") : c.dim("○");
-    const flags: string[] = [];
-    if (active) flags.push(c.green("active"));
-    if (a.needsReauth) flags.push(c.red("needs-reauth"));
-    const tag = flags.length ? ` ${flags.join(" ")}` : "";
-    const label = a.label || a.email;
-    console.log(`${marker} ${c.bold(label)}${tag}`);
-    console.log(`  ${c.dim(`org ${a.organizationUuid.slice(0, 8)}, ${claudeTierLabel(a) ?? "?"}, uuid ${a.accountUuid.slice(0, 8)}`)}`);
-  }
-
-  const codex = loadCodexAccounts();
-  if (codex.accounts.length > 0) {
-    const liveId = liveCodexAccountId();
-    console.log();
-    console.log(c.dim("codex"));
-    for (const account of codex.accounts) {
-      const active = account.accountId === liveId;
-      const marker = active ? c.green("●") : c.dim("○");
-      const flags: string[] = [];
-      if (active) flags.push(c.green("active"));
-      if (account.needsReauth) flags.push(c.red("needs-reauth"));
-      const tag = flags.length ? ` ${flags.join(" ")}` : "";
-      console.log(`${marker} ${c.bold(account.label)}${tag}`);
-      console.log(`  ${c.dim(`${account.planType ?? "?"}, id ${account.accountId.slice(0, 8)}`)}`);
-    }
-  }
-  return 0;
-}

package/src/cli/watch.ts

@@ -1,46 +0,0 @@
-import { clamp, delay } from "es-toolkit";
-import { loadAccounts } from "../lib/state.ts";
-import { loadCodexAccounts } from "../lib/codexstate.ts";
-import { cmdStatus } from "./status.ts";
-import { c, emitError, emitJson } from "./render.ts";
-
-const DEFAULT_INTERVAL_S = 120;
-const MIN_INTERVAL_S = 30;
-const MAX_INTERVAL_S = 86_400;
-
-export function resolveWatchInterval(arg?: string): number | null {
-  if (arg === undefined) return DEFAULT_INTERVAL_S;
-  const n = Number(arg);
-  if (!Number.isFinite(n) || n <= 0) return null;
-  return clamp(n, MIN_INTERVAL_S, MAX_INTERVAL_S);
-}
-
-const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
-
-export async function cmdWatch(intervalArg?: string, json = false): Promise<number> {
-  const intervalS = resolveWatchInterval(intervalArg);
-  if (intervalS === null) {
-    emitError({ json, message: `watch interval must be a positive number of seconds, got: ${intervalArg}` });
-    return 2;
-  }
-  if (loadAccounts().accounts.length === 0 && loadCodexAccounts().accounts.length === 0) return cmdStatus({ json });
-
-  const paintHeader = () => {
-    process.stdout.write(process.stdout.isTTY ? CLEAR : "\n");
-    console.log(c.dim(`watch: every ${intervalS}s, ${new Date().toLocaleTimeString()}, ctrl-c to quit`));
-  };
-  while (true) {
-    try {
-      await cmdStatus(json ? { json } : { preRender: paintHeader });
-    } catch (e) {
-      const message = `status failed this tick: ${e instanceof Error ? e.message : String(e)}`;
-      if (json) {
-        emitJson({ ok: false, error: message });
-      } else {
-        paintHeader();
-        console.error(c.red(message));
-      }
-    }
-    await delay(intervalS * 1000);
-  }
-}