tokenmaxxing 1.173.0 → 1.175.0

package/README.md

@@ -2,7 +2,7 @@
 
 **Automatic Claude Code account switching.** Run `claude` exactly as you always do; each session starts on the pooled account with room for it whose weekly quota is closest to expiring unused, and when that account nears its usage limit, tokenmaxxing resumes the session on a fresher account at a safe turn boundary - same conversation, compacted on the account it leaves and restarted under another account's credential store with a first prompt that asks Claude to continue. Works across many concurrent sessions, which spread over the pool instead of draining one account together. When the whole pool is at its limit, a session queues first come first served for a reset (at most eight sessions wait on one account; overflow waits for the next reset with room) and pauses with a countdown until its assigned reset, when that reset falls within twice `policy.maxWaitMs` (default 1h - a longer wait stays put rather than parking your terminal for hours).
 
-> **Scope:** Claude Code on macOS and Linux, plus OpenAI's Codex CLI as a second switching pool; grok and Muse Code as status-only pools. It pools **subscription** accounts (Pro/Max), not API keys.
+> **Scope:** Claude Code on macOS and Linux, plus OpenAI's Codex CLI and Muse Code as further switching pools; grok and Cursor as status-only pools. It pools **subscription** accounts (Pro/Max), not API keys.
 
 ```
 $ claude
@@ -40,15 +40,16 @@ claude                  # use claude as always; each session gets its own accoun
 | `tokenmaxxing init --codex` | same for codex: log in the first account (isolated), install codex supervisor + Stop hook |
 | `tokenmaxxing init --pi` | verify and pin the real `pi` and install the `pi` supervisor, which runs pi sessions on pooled Claude and ChatGPT accounts that have a pi login |
 | `tokenmaxxing init --grok` | pool the first grok login, status-only: no supervisor, no switching |
-| `tokenmaxxing init --muse` | pool the first Muse Code login, status-only: no supervisor, no switching |
-| `tokenmaxxing add [--codex \| --grok \| --muse]` | register an additional account in that pool (isolated login, harvested once into its own store) |
-| `tokenmaxxing auth [--codex \| --grok \| --muse] [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 account that is flagged or has no usable credential in its store, one by one |
+| `tokenmaxxing init --cursor` | pool the Cursor CLI login, status-only: no supervisor, no switching |
+| `tokenmaxxing init --muse` | same for Muse Code: log in the first account (isolated), install the `muse` supervisor, which starts each session on the freshest account and resumes it on another near quota |
+| `tokenmaxxing add [--codex \| --grok \| --muse \| --cursor]` | register an additional account in that pool (isolated login, harvested once into its own store) |
+| `tokenmaxxing auth [--codex \| --grok \| --muse \| --cursor] [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 account that is flagged or has no usable credential in its store, one by one |
 | `tokenmaxxing auth --pi [--codex] [sel \| --all]` | log a pooled Claude account (or a codex account with `--codex`) into pi, isolated, and keep that login as the account's pi credential after an identity check; `--all` walks every account without a pi login |
 | `tokenmaxxing status [--cached]` | every pool: accounts with 5h / weekly / per-model usage bars, live session counts, exhausted-until-reset; `--cached` renders the stored figures without sampling |
 | `tokenmaxxing config` | the config path and the effective values; edit the file in an editor, a bad value fails the next load with the field name |
 | `tokenmaxxing check` | fold fresh tees, sample up to three stale accounts, and self-update a Bun global install once a day; the periodic timer runs this every tick |
 | `tokenmaxxing doctor` | verify the install: PATH order, `claudeBin`, the five settings entries, the timer, the hub service, the credential identity of every Codex store and of every Claude store whose access token is still fresh (an expiring Claude token is reported as unverifiable, not as a failure), codex hook trust, and shell aliases that shadow `claude` |
-| `tokenmaxxing rename [--codex \| --grok \| --muse] <sel> <label>` / `rm [...] <sel>` | manage a pool (one email can hold both a claude and a codex account); `rm` is refused for an account with a running supervised session |
+| `tokenmaxxing rename [--codex \| --grok \| --muse \| --cursor] <sel> <label>` / `rm [...] <sel>` | manage a pool (one email can hold both a claude and a codex account); `rm` is refused for an account with a running supervised session |
 | `tokenmaxxing serve` | serve the CLIProxyAPI-compatible usage API on `http://localhost:8317` (`hub.port`) so a dashboard such as T3 Code's "Add a CLIProxyAPI hub" shows the quota of every pooled Claude and Codex account; the management key is the contents of `hub-key` in the state directory, minted on the first run, and `init` runs it as a background service beside the check timer. Details in [Usage hub](docs/content/docs/hub.mdx) |
 | `tokenmaxxing uninstall [--yes]` | print the targets, then remove the shims, settings entries, codex Stop hook, check timer, hub service, and rc PATH line (accounts/stores kept); refused without `--yes` when `HOME` is the login home |
 | `--json` | machine-readable output: one JSON document on stdout for `status`, `config`, and `check` (`ok` mirrors the exit code, failures add `error`) |
@@ -126,7 +127,8 @@ pi keeps its own credential and refreshes it itself, so each pooled account gets
 - **Keychain (macOS).** The first keychain access for a new store happens inside the interactive `init`, `add`, or `auth` run, where a prompt can be answered, not inside a headless hook.
 - **Plaintext credentials (Linux).** Claude Code itself stores Linux credentials as a 0600 plaintext file; a store follows the same model.
 - **The status-only grok pool does not switch.** grok `status` shows the weekly subscription credit window, and no grok session moves.
-- **The status-only Muse Code pool does not switch, and shows no usage before the first model request of a window.** Its usage read is the key mint, which reports no usage until a model request opens the 5-hour window.
+- **The status-only Cursor pool does not switch, and reads only a file login.** Cursor `status` shows the included usage of the monthly billing cycle. The Cursor CLI keeps its login in the keychain on macOS, which tokenmaxxing does not read, so the pool works where the login is `auth.json` (Linux).
+- **A Muse Code move stops the running turn.** `muse resume` takes no prompt, so a turn that was running when the move landed has to be sent again; `muse exec` and `muse serve` keep the account they started on.
 
 ## How it's built
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.173.0",
+  "version": "1.175.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/cli/auth.ts

@@ -13,7 +13,7 @@ import { c, count } from "./render.ts";
 import type { Account, AccountsIndex } from "../lib/types.ts";
 
 const AUTH_USAGE =
-  "usage: tokenmaxxing auth [--codex | --grok | --muse] [<email|label|id> | --all]\n       tokenmaxxing auth [--codex | --grok | --muse] --emails <email>...\n       tokenmaxxing auth --pi [--codex] [<email|label|id> | --all]";
+  "usage: tokenmaxxing auth [--codex | --grok | --muse | --cursor] [<email|label|id> | --all]\n       tokenmaxxing auth [--codex | --grok | --muse | --cursor] --emails <email>...\n       tokenmaxxing auth --pi [--codex] [<email|label|id> | --all]";
 const EMAILS_FLAG = "--emails";
 
 export type AuthPlan = { kind: "usage" } | { kind: "error"; message: string } | { kind: "pick" } | { kind: "targets"; ids: string[] };

package/src/cli/doctor.ts

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync } from "node:fs";
-import { CLAUDE_BIN, PI_BIN, verifyRealBin } from "../lib/claudebin.ts";
+import { CLAUDE_BIN, MUSE_BIN, PI_BIN, verifyRealBin } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
-import { activationHint, CHECK_JOB, codexStoreHookTrust, findClaudeShadowers, HUB_JOB, isBinDirAhead, jobHealthy, piSupervisorLink, shellRcPath } from "../lib/install.ts";
+import { activationHint, CHECK_JOB, codexStoreHookTrust, findClaudeShadowers, HUB_JOB, isBinDirAhead, jobHealthy, museSupervisorLink, piSupervisorLink, shellRcPath } from "../lib/install.ts";
+import { museStoreIdentity } from "../lib/muse.ts";
 import { readPiStore } from "../lib/piauth.ts";
 import { errorMessage } from "../lib/log.ts";
-import { claudePool, codexPool, paths } from "../lib/paths.ts";
+import { claudePool, codexPool, musePool, paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { readStore } from "../lib/credstore.ts";
 import { codexIdentityOf, codexSeatIdOf, readCodexStoreAuth } from "../lib/codexauth.ts";
@@ -138,6 +139,30 @@ export async function cmdDoctor(): Promise<number> {
     }
   }
 
+  const midx = loadAccounts(musePool);
+  if (existsSync(museSupervisorLink())) {
+    check(!!cfg.museBin && existsSync(cfg.museBin), "real muse binary resolved", "run `tokenmaxxing init --muse`");
+    if (cfg.museBin && existsSync(cfg.museBin)) {
+      const fail = verifyRealBin({ ...MUSE_BIN, bin: cfg.museBin });
+      check(fail === null, "museBin launches the real muse", fail ?? undefined);
+      check(isBinDirAhead(MUSE_BIN), `${paths.binDir} is ahead of the real muse on PATH`, `export PATH="${paths.binDir}:$PATH"`);
+    }
+  } else if (midx.accounts.length > 0) {
+    warn("Muse Code accounts are pooled but the muse supervisor is not installed - run `tokenmaxxing init --muse`");
+  }
+  for (const a of midx.accounts) {
+    let ids: string[] = [];
+    let readErr: string | null = null;
+    try {
+      ids = museStoreIdentity(a.id);
+    } catch (e) {
+      readErr = errorMessage(e).slice(0, 100);
+    }
+    check(ids.length > 0, `Muse Code store login present for ${a.label}`, readErr ?? `run \`tokenmaxxing auth --muse ${a.label}\``);
+    if (ids.length > 0) check(ids.includes(a.id), `Muse Code store login identity matches ${a.label}`, `the store holds another account's login - run \`tokenmaxxing auth --muse ${a.label}\``);
+    if (a.needsReauth) check(false, `${a.label} (muse) needs re-auth`, `run \`tokenmaxxing auth --muse ${a.label}\` to re-login`);
+  }
+
   const rc = shellRcPath();
   if (rc && existsSync(rc)) {
     for (const s of findClaudeShadowers(readFileSync(rc, "utf8"))) {

package/src/cli/rename.ts

@@ -16,7 +16,7 @@ export function findAccount(accounts: Account[], selector: string): Account | un
 export async function cmdRename(p: Provider, argv: string[]): Promise<number> {
   const [selector, newLabel] = argv;
   if (!selector || !newLabel) {
-    emitError({ message: "usage: tokenmaxxing rename [--codex | --grok | --muse] <email|label|id> <new-label>", paint: plain });
+    emitError({ message: "usage: tokenmaxxing rename [--codex | --grok | --muse | --cursor] <email|label|id> <new-label>", paint: plain });
     return 2;
   }
   return withLock(p.pool.lockFile, async () => {

package/src/cli/status.ts

@@ -3,16 +3,19 @@ import { creditLeft, keySessions, loadApiKeys } from "../lib/apikeys.ts";
 import { claude } from "../lib/claude.ts";
 import { codex } from "../lib/codex.ts";
 import { grok } from "../lib/grok.ts";
+import { cursor } from "../lib/cursor.ts";
 import { muse } from "../lib/muse.ts";
 import { loadAccounts, loadConfig, saveAccounts } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
-import { codexPool, grokPool, musePool } from "../lib/paths.ts";
+import { codexPool, cursorPool, grokPool, musePool } from "../lib/paths.ts";
 import { barFor, bufferedUsed, earliestReset, gatedWindows, landGrant, landWindows, isExhausted, isSessionWindow, limitWindows, liveUsed, nextWeeklyReset, sessionWindow, thresholdBars, weeklyWindow } from "../lib/picker.ts";
 import type { Provider, SampleReport } from "../lib/provider.ts";
 import { usd } from "./key.ts";
 import { bar, c, count, emitJson, fmtAgo } from "./render.ts";
 import type { Account, AccountThresholds, Bars, Config, Thresholds, Window } from "../lib/types.ts";
 
+const WEEK_S = 7 * 86400;
+
 export type WindowReport = { usedPercentage: number; bufferedPercentage: number; resetsAt: number | null; windowSeconds: number | null };
 
 export type UsageReport = { fiveHour: WindowReport | null; week: WindowReport | null; limits: (WindowReport & { name: string })[] };
@@ -53,7 +56,7 @@ type StatusApiKey = {
   sessions: number;
 };
 
-export type StatusReport = { now: number; claude: PoolReport; codex: PoolReport; grok: PoolReport; muse: PoolReport; apiKeys?: StatusApiKey[] };
+export type StatusReport = { now: number; claude: PoolReport; codex: PoolReport; grok: PoolReport; muse: PoolReport; cursor: PoolReport; apiKeys?: StatusApiKey[] };
 
 function apiKeyReport(): StatusApiKey[] {
   const sessions = keySessions();
@@ -89,7 +92,7 @@ function currentWindow(a: Account, w: Window, bars: Bars | null, now: number): W
   return {
     usedPercentage: liveUsed(w, now),
     bufferedPercentage: bars == null ? liveUsed(w, now) : bufferedUsed(a, w, bars, now),
-    resetsAt: isSessionWindow(w) ? (passed ? null : w.resetsAt) : nextWeeklyReset(w.resetsAt, now),
+    resetsAt: isSessionWindow(w) || (w.windowSeconds ?? 0) > WEEK_S ? (passed ? null : w.resetsAt) : nextWeeklyReset(w.resetsAt, now),
     windowSeconds: w.windowSeconds,
   };
 }
@@ -161,6 +164,7 @@ async function collect(p: Provider, cfg: Config, now: number, cached: boolean):
           if (a.lastUsageAt != null && (stored.lastUsageAt == null || a.lastUsageAt > stored.lastUsageAt)) {
             landWindows(stored, p.mergeWindows(a.windows, stored.windows), a.lastUsageAt, bars);
             stored.hasCredits = a.hasCredits;
+            if (a.email != null && stored.email == null && stored.label === stored.id.slice(0, 8)) stored.label = a.email;
             if (a.email != null) stored.email = a.email;
             if (a.tier != null) stored.tier = a.tier;
             dirty = true;
@@ -267,7 +271,7 @@ function card(p: Provider, a: StatusAccount, now: number, staleAfterMs: number):
   const lines = [headerLine({ ...a, name: a.label })];
   if (a.usage) {
     if (a.usage.fiveHour) lines.push(usageRow(`${Math.round((a.usage.fiveHour.windowSeconds ?? 0) / 3600)}h`, a.usage.fiveHour));
-    if (a.usage.week) lines.push(usageRow("week", a.usage.week));
+    if (a.usage.week) lines.push(usageRow((a.usage.week.windowSeconds ?? 0) > WEEK_S ? "month" : "week", a.usage.week));
     for (const w of a.usage.limits) lines.push(usageRow(p.windowLabel(w.name), w));
   }
   const notes: Note[] = [];
@@ -289,7 +293,7 @@ function card(p: Provider, a: StatusAccount, now: number, staleAfterMs: number):
 
 function renderPool(p: Provider, pool: PoolReport, header: string, now: number, staleAfterMs: number): void {
   console.log(c.dim(header));
-  if (!p.statusOnly) console.log(c.dim("buffered usage quota: percent of each account's switch threshold, so it reads higher than the usage Claude or Codex reports"));
+  if (!p.statusOnly) console.log(c.dim("buffered usage quota: percent of each account's switch threshold, so it reads higher than the usage the provider reports"));
   console.log();
   renderGrid(pool.accounts.map((a) => card(p, a, now, staleAfterMs)));
   if (pool.gatedNote) {
@@ -308,9 +312,10 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
     const codexPooled = loadAccounts(codexPool).accounts.length > 0;
     const grokPooled = loadAccounts(grokPool).accounts.length > 0;
     const musePooled = loadAccounts(musePool).accounts.length > 0;
+    const cursorPooled = loadAccounts(cursorPool).accounts.length > 0;
     if (claudeReport.accounts.length === 0) {
-      if (!codexPooled && !grokPooled && !musePooled && apiKeys.length === 0) {
-        console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`, `--grok`, `--muse`)"));
+      if (!codexPooled && !grokPooled && !musePooled && !cursorPooled && apiKeys.length === 0) {
+        console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`, `--grok`, `--muse`, `--cursor`)"));
         return 0;
       }
       console.log(c.dim("no claude accounts (run `tokenmaxxing init` to pool claude too)"));
@@ -324,8 +329,9 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
   const codexReport = await collect(codex, cfg, now, cached);
   const grokReport = await collect(grok, cfg, now, cached);
   const museReport = await collect(muse, cfg, now, cached);
+  const cursorReport = await collect(cursor, cfg, now, cached);
   if (json) {
-    const report: StatusReport = { now, claude: claudeReport, codex: codexReport, grok: grokReport, muse: museReport, ...(apiKeys.length > 0 ? { apiKeys } : {}) };
+    const report: StatusReport = { now, claude: claudeReport, codex: codexReport, grok: grokReport, muse: museReport, cursor: cursorReport, ...(apiKeys.length > 0 ? { apiKeys } : {}) };
     emitJson({ ok: true, ...report });
     return 0;
   }
@@ -336,7 +342,10 @@ export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {})
     renderPool(grok, grokReport, `grok  (${count({ n: grokReport.accounts.length, noun: "account" })}, status-only)`, Date.now(), cfg.policy.usagePollTtlMs);
   }
   if (museReport.accounts.length > 0) {
-    renderPool(muse, museReport, `muse  (${count({ n: museReport.accounts.length, noun: "account" })}, status-only)`, Date.now(), cfg.policy.usagePollTtlMs);
+    renderPool(muse, museReport, `muse  (${count({ n: museReport.accounts.length, noun: "account" })})`, Date.now(), cfg.policy.usagePollTtlMs);
+  }
+  if (cursorReport.accounts.length > 0) {
+    renderPool(cursor, cursorReport, `cursor  (${count({ n: cursorReport.accounts.length, noun: "account" })}, status-only)`, Date.now(), cfg.policy.usagePollTtlMs);
   }
   return 0;
 }

package/src/entries/musesupervisor.ts

@@ -0,0 +1,335 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { join } from "node:path";
+import { omit } from "es-toolkit";
+import type { Subprocess } from "bun";
+import { MUSE_BIN, UNMANAGED_ENV, WRAP_DEPTH_ENV, resolveRealBin, wrapDepth } from "../lib/claudebin.ts";
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { withLock } from "../lib/lock.ts";
+import { errorMessage, log } from "../lib/log.ts";
+import { ensureMuseStoreHome, muse, museSeatOpen, observeMuse, probeMuseSeats, rankMuseSeat } from "../lib/muse.ts";
+import { MUSE_CONFIG_HOME_ENV, inMuseStores, musePaths, musePool, museSeatFromEnv } from "../lib/paths.ts";
+import { thresholdBars, usableAt } from "../lib/picker.ts";
+import { clearPresence } from "../lib/presence.ts";
+import { childStdout, exitStatus, loopGuardTripped, raceMarkerOrExit, recordPresenceOrStop, relayStdout, runPassthrough, SEAT_POLL_MS, SEAT_RETRY_MS } from "../lib/supervise.ts";
+import { saveTermios } from "../lib/tty.ts";
+import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { ErrnoSchema, type Account } from "../lib/types.ts";
+
+const SUBCOMMANDS = new Set([
+  "resume", "exec", "config", "export", "trace", "model-profile", "skills", "voice", "plugins", "sandbox",
+  "schema", "serve", "session-message", "mcp", "auth", "login", "logout", "init", "help",
+]);
+
+// Headless runs take a seat for their whole life: nothing can resume them elsewhere.
+const SEATED_SUBCMDS = new Set(["exec", "serve"]);
+
+const PASSTHROUGH_FLAGS = new Set(["-h", "--help", "-V", "--version"]);
+
+const VALUE_FLAGS = new Set([
+  "--agents", "--provider", "--preset", "--model", "--contributor-mode", "-c", "--config", "--reasoning-effort",
+  "--effort", "--base-url", "--image", "--workspace", "--worktree-base", "--worktree-existing", "--approval-mode",
+  "--permission-profile", "--approval-judge", "--echo-delay-ms", "--sandbox-network",
+]);
+
+const WORKTREE_MODES = new Set(["off", "create", "existing"]);
+
+// Flags that belong to the first launch only: a resumed session keeps its worktree and has had its image.
+const FIRST_LAUNCH_FLAGS = new Set(["--image", "-w", "--worktree", "--worktree-base", "--worktree-existing"]);
+
+type MuseArgs = { help: boolean; sub: string | null; provider: string | null; sessionLog: boolean; resumeFlags: string[] };
+
+export function analyzeMuseArgs(argv: string[]): MuseArgs {
+  const out: MuseArgs = { help: false, sub: null, provider: null, sessionLog: true, resumeFlags: [] };
+  let positionals = 0;
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--") break;
+    if (PASSTHROUGH_FLAGS.has(a)) out.help = true;
+    if (a === "--no-session-log") out.sessionLog = false;
+    const eq = a.indexOf("=");
+    const flag = a.startsWith("--") && eq > 0 ? a.slice(0, eq) : a;
+    if (flag === "-w" || flag === "--worktree") {
+      if (eq < 0 && WORKTREE_MODES.has(argv[i + 1] ?? "")) i++;
+      continue;
+    }
+    if (VALUE_FLAGS.has(flag)) {
+      const value = eq > 0 && flag !== a ? a.slice(eq + 1) : argv[++i];
+      if (flag === "--provider") out.provider = value ?? null;
+      if (!FIRST_LAUNCH_FLAGS.has(flag)) out.resumeFlags.push(...(flag === a && value !== undefined ? [a, value] : [a]));
+      continue;
+    }
+    if (a.startsWith("-")) {
+      if (a !== "--last" && !FIRST_LAUNCH_FLAGS.has(flag)) out.resumeFlags.push(a);
+      continue;
+    }
+    if (positionals++ === 0 && SUBCOMMANDS.has(a)) out.sub = a;
+  }
+  return out;
+}
+
+type LaunchMode = "passthrough" | "seat" | "managed";
+
+function launchMode(args: MuseArgs): { mode: LaunchMode; why: string; inherited?: string } {
+  if (args.help) return { mode: "passthrough", why: "help" };
+  if (process.env.TOKENMAXXING_PROBE || process.env[UNMANAGED_ENV]) return { mode: "passthrough", why: "unmanaged" };
+  if (args.provider != null && args.provider !== "meta") return { mode: "passthrough", why: `provider ${args.provider}` };
+  if (process.env.META_API_KEY) return { mode: "passthrough", why: "META_API_KEY overrides the account login" };
+  const inherited = museSeatFromEnv(loadAccounts(musePool).accounts.map((a) => a.id));
+  if (inherited != null) return { mode: "seat", why: "inherits its parent's seat", inherited };
+  if (args.sub != null && args.sub !== "resume") return SEATED_SUBCMDS.has(args.sub) ? { mode: "seat", why: args.sub } : { mode: "passthrough", why: args.sub };
+  if (!args.sessionLog) return { mode: "seat", why: "no session log to resume" };
+  if (process.stdin.isTTY !== true || process.stdout.isTTY !== true) return { mode: "seat", why: "no terminal" };
+  return { mode: "managed", why: "interactive" };
+}
+
+const LockSchema = { pid: /^pid=(\d+)$/m, host: /^host=(.*)$/m };
+
+function namesDescending(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort().reverse();
+  } catch (e) {
+    const code = ErrnoSchema.safeParse(e).data?.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return [];
+    throw e;
+  }
+}
+
+// Muse Code keeps each session in sessions/<yyyy>/<mm>/<dd>/<session id>/ and writes the pid of the process that
+// holds it open to .session.lock, a resume included. The newest sessions come first.
+function sessionHeldBy(pid: number): string | null {
+  const host = hostname();
+  for (const year of namesDescending(musePaths.sessionsDir)) {
+    for (const month of namesDescending(join(musePaths.sessionsDir, year))) {
+      for (const day of namesDescending(join(musePaths.sessionsDir, year, month))) {
+        const dayDir = join(musePaths.sessionsDir, year, month, day);
+        for (const id of namesDescending(dayDir)) {
+          let lock: string;
+          try {
+            lock = readFileSync(join(dayDir, id, ".session.lock"), "utf8");
+          } catch (e) {
+            const code = ErrnoSchema.safeParse(e).data?.code;
+            if (code === "ENOENT" || code === "ENOTDIR") continue;
+            throw e;
+          }
+          const lockHost = LockSchema.host.exec(lock)?.[1];
+          if (Number(LockSchema.pid.exec(lock)?.[1]) === pid && (lockHost == null || lockHost === host)) return id;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+type Watch = { decided: boolean; move: Account | null };
+
+async function watchSeat(seatId: string): Promise<Watch> {
+  try {
+    const now = Date.now();
+    const cfg = loadConfig();
+    const account = loadAccounts(musePool).accounts.find((a) => a.id === seatId);
+    if (!account) return { decided: false, move: null };
+    const observed = await observeMuse(account, cfg, now, { probe: true });
+    const unmeasured = observed == null || now - observed.at > cfg.policy.usagePollTtlMs;
+    if (unmeasured) log("musesupervisor.seat_unmeasured", { seat: account.id.slice(0, 8), usageAt: observed?.at });
+    const rejected = loadAccounts(musePool).accounts.find((a) => a.id === seatId)?.needsReauth === true;
+    const current = observed ? { ...account, windows: observed.windows } : account;
+    const until = usableAt({ ...current, hasCredits: false }, { now, thresholds: thresholdBars(cfg), currentId: account.id, families: null, seats: null });
+    if (!rejected && until <= now) return { decided: unmeasured, move: null };
+    // The move decision folds the other accounts from storage, so a destination is read fresh first.
+    await probeMuseSeats(now);
+    const decision = await evaluateAndMaybeSwap(muse, now, true, null, { seatId: account.id });
+    log("musesupervisor.seat_exhausted", { seat: account.id.slice(0, 8), until, reason: decision.reason, account: decision.account?.id.slice(0, 8) });
+    return { decided: true, move: decision.swapped ? decision.account : null };
+  } catch (e) {
+    log("musesupervisor.seat_watch_error", { err: errorMessage(e) });
+    return { decided: true, move: null };
+  }
+}
+
+function validWanted(wanted: string | null, now: number): Account | null {
+  if (wanted == null) return null;
+  const a = loadAccounts(musePool).accounts.find((x) => x.id === wanted);
+  return a && museSeatOpen(a, now) ? a : null;
+}
+
+const KILL_GRACE_MS = 30_000;
+
+// A launch that gets no seat must not run on a store its environment still names (one inherited from a seat whose
+// account was removed): without a presence file nothing would protect it.
+function unseatedEnv(env: Record<string, string | undefined>): Record<string, string | undefined> {
+  const home = env.XDG_CONFIG_HOME;
+  if (home == null || !inMuseStores(home)) return env;
+  const rest = omit(env, ["XDG_CONFIG_HOME", MUSE_CONFIG_HOME_ENV]);
+  return env[MUSE_CONFIG_HOME_ENV] != null ? { ...rest, XDG_CONFIG_HOME: env[MUSE_CONFIG_HOME_ENV] } : rest;
+}
+
+// A seated child runs with the store as XDG_CONFIG_HOME and keeps the real config home it mirrors, so a launch
+// from inside it mirrors the same one.
+function seatedEnv(env: Record<string, string | undefined>, accountId: string): Record<string, string | undefined> {
+  return { ...env, XDG_CONFIG_HOME: ensureMuseStoreHome(accountId), [MUSE_CONFIG_HOME_ENV]: musePaths.configHome };
+}
+
+function warnUnseated(): void {
+  if (loadAccounts(musePool).accounts.length === 0) return;
+  process.stderr.write("\x1b[33mtokenmaxxing: no pooled Muse Code account is usable (run `tokenmaxxing doctor`) - this session runs on your own Muse Code login\x1b[0m\n");
+}
+
+export async function runMuseSupervisor(argv: string[]): Promise<number> {
+  if (loopGuardTripped("muse")) return 1;
+  const real = resolveRealBin(MUSE_BIN);
+  const childEnv: Record<string, string | undefined> = { ...process.env, [WRAP_DEPTH_ENV]: String(wrapDepth() + 1) };
+  const args = analyzeMuseArgs(argv);
+  const { mode, why, inherited } = launchMode(args);
+
+  if (mode !== "managed") {
+    let child: Subprocess | null = null;
+    process.on("SIGTERM", () => {
+      if (child) child.kill("SIGTERM");
+      else process.exit(143);
+    });
+    if (mode === "passthrough") {
+      log("musesupervisor.passthrough", { why, seat: null });
+      // A store no pooled account owns any longer (rm --muse kept it for its leftovers) is no login to run on.
+      const env = museSeatFromEnv(loadAccounts(musePool).accounts.map((a) => a.id)) == null ? unseatedEnv(childEnv) : childEnv;
+      return runPassthrough({ real, argv, env, onSpawn: (p) => { child = p; } });
+    }
+    const id = `seat-${process.pid}`;
+    if (inherited == null) await probeMuseSeats(Date.now());
+    // Placement, spawn, and presence share one lock hold, so `rm` never removes an account a launch is taking. A
+    // launch inside a seat keeps that seat, and records its own presence so the seat outlives its parent.
+    const placed = await withLock(musePool.lockFile, async () => {
+      const seat = inherited != null ? (loadAccounts(musePool).accounts.find((a) => a.id === inherited) ?? null) : rankMuseSeat(Date.now());
+      log("musesupervisor.passthrough", { why, seat: seat?.id.slice(0, 8) ?? null });
+      if (!seat) warnUnseated();
+      const p = Bun.spawn([real, ...argv], {
+        stdin: "inherit",
+        stdout: childStdout(),
+        stderr: "inherit",
+        env: seat ? seatedEnv(childEnv, seat.id) : unseatedEnv(childEnv),
+      });
+      child = p;
+      if (seat) {
+        await recordPresenceOrStop({
+          child: p,
+          dir: musePaths.presenceDir,
+          id,
+          accountId: seat.id,
+          event: "musesupervisor.seat_presence_failed",
+          message: "could not write the muse seat's presence file - refusing to run a session that placement cannot see",
+          savedTermios: null,
+        });
+      }
+      return p;
+    });
+    const drain = placed.stdout instanceof ReadableStream ? relayStdout(placed.stdout) : null;
+    try {
+      await placed.exited;
+      await drain?.();
+      return exitStatus(placed);
+    } finally {
+      clearPresence({ dir: musePaths.presenceDir, id });
+    }
+  }
+
+  const id = crypto.randomUUID();
+  let child: Subprocess | null = null;
+  let terminating = false;
+  process.on("SIGTERM", () => {
+    terminating = true;
+    if (child) child.kill("SIGTERM");
+    else process.exit(143);
+  });
+  const savedTermios = saveTermios();
+  process.on("SIGINT", () => {});
+  process.on("SIGHUP", () => {});
+  const say = (text: string) => {
+    process.stderr.write(`\n\x1b[36m${text}\x1b[0m\n`);
+  };
+
+  let launchArgs = argv;
+  let respawns = 0;
+  let wanted: string | null = null;
+  try {
+    while (true) {
+      await probeMuseSeats(Date.now());
+      const launched = await withLock(musePool.lockFile, async () => {
+        clearPresence({ dir: musePaths.presenceDir, id });
+        if (terminating) return null;
+        const picked = validWanted(wanted, Date.now()) ?? rankMuseSeat(Date.now());
+        log("musesupervisor.launch", { id: id.slice(0, 8), respawns, seat: picked?.id.slice(0, 8) ?? null, args: launchArgs.join(" ") });
+        if (!picked) warnUnseated();
+        const spawned = Bun.spawn([real, ...launchArgs], {
+          stdin: "inherit",
+          stdout: "inherit",
+          stderr: "inherit",
+          env: picked ? seatedEnv(childEnv, picked.id) : unseatedEnv(childEnv),
+        });
+        child = spawned;
+        if (picked) {
+          await recordPresenceOrStop({
+            child: spawned,
+            dir: musePaths.presenceDir,
+            id,
+            accountId: picked.id,
+            event: "musesupervisor.presence_failed",
+            message: "could not write the muse session's presence file - refusing to run a session that placement cannot see",
+            savedTermios,
+          });
+        }
+        return { proc: spawned, picked };
+      });
+      if (launched == null) return 143;
+      const { proc, picked } = launched;
+
+      const pending: { move: Account | null; session: string | null; killed: boolean } = { move: null, session: null, killed: false };
+      let seatCheckAt = 0;
+      let escalate: Timer | null = null;
+      await raceMarkerOrExit({
+        child: proc,
+        tick: async () => {
+          if (!picked || terminating || Date.now() < seatCheckAt) return false;
+          const watched = await watchSeat(picked.id);
+          seatCheckAt = Date.now() + (watched.decided ? SEAT_RETRY_MS : SEAT_POLL_MS);
+          if (watched.move == null) return false;
+          const session = sessionHeldBy(proc.pid);
+          if (session == null) {
+            log("musesupervisor.session_unresolved", { id: id.slice(0, 8), pid: proc.pid, target: watched.move.id.slice(0, 8) });
+            return false;
+          }
+          pending.move = watched.move;
+          pending.session = session;
+          return true;
+        },
+        savedTermios,
+        onKill: () => {
+          pending.killed = true;
+          escalate = setTimeout(() => proc.kill("SIGKILL"), KILL_GRACE_MS);
+        },
+        onError: () => clearPresence({ dir: musePaths.presenceDir, id }),
+        onExited: () => {
+          child = null;
+          if (escalate) clearTimeout(escalate);
+        },
+      });
+
+      if (pending.killed && !terminating && pending.move && pending.session) {
+        respawns++;
+        log("musesupervisor.move", { id: id.slice(0, 8), from: picked?.id.slice(0, 8), to: pending.move.id.slice(0, 8), session: pending.session });
+        say(`↻ tokenmaxxing: moving Muse Code to ${pending.move.label} - resuming the session. A turn that was running stopped; send it again to continue.`);
+        wanted = pending.move.id;
+        launchArgs = [...args.resumeFlags, "resume", pending.session];
+        continue;
+      }
+      clearPresence({ dir: musePaths.presenceDir, id });
+      log("musesupervisor.exit", { id: id.slice(0, 8), respawns, code: proc.exitCode, signal: proc.signalCode, terminated: terminating || undefined });
+      return exitStatus(proc);
+    }
+  } catch (e) {
+    const msg = errorMessage(e);
+    say(msg.startsWith("tokenmaxxing:") ? msg : `tokenmaxxing: ${msg}`);
+    log("musesupervisor.fatal", { err: msg });
+    clearPresence({ dir: musePaths.presenceDir, id });
+    return 1;
+  }
+}

package/src/lib/claudebin.ts

@@ -109,6 +109,7 @@ export function verifyRealBin(input: { bin: string; name: string; versionOk: (ve
 
 export const CLAUDE_BIN = { name: "claude", key: "claudeBin", versionOk: (out: string) => out.toLowerCase().includes("claude") } as const;
 export const CODEX_BIN = { name: "codex", key: "codexBin", versionOk: (out: string) => out.toLowerCase().includes("codex") } as const;
+export const MUSE_BIN = { name: "muse", key: "museBin", versionOk: (out: string) => out.toLowerCase().includes("muse code") } as const;
 function isBareVersion(out: string): boolean {
   try {
     return Bun.semver.order(out, "0.0.0") >= 0;