tokenmaxxing 1.172.0 → 1.174.0

package/README.md

@@ -1,8 +1,8 @@
 # tokenmaxxing
 
-**Automatic Claude Code account switching.** Run `claude` exactly as you always do; each session starts on the pooled account with the most headroom per running session, 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).
+**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 as a status-only pool. It pools **subscription** accounts (Pro/Max), not API keys.
 
 ```
 $ claude
@@ -40,7 +40,7 @@ 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 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]` | 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 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 |
@@ -62,7 +62,7 @@ Each session runs on its own seat. One rule: while the seat is under its bars, n
 
 The bars' headroom is deliberate: it's the budget to reach a clean turn boundary before the account's real limit. The session bar sits lower (90) because a 5-hour reset is cheap to sit out; weekly quota is use-it-or-lose-it, so it drains closer to the limit (98). The default margin is 0, so the configured thresholds and the effective bars read the same.
 
-Launches and moves rank usable accounts by session-window headroom per running session, `(bar - used) / (sessions + 1)`, so two fresh accounts alternate and a third session goes to whichever has more headroom left per session; ties break by pace pressure (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, divided by time to its reset, highest first), then soonest weekly reset, then lowest weekly use. Organization membership is not an input.
+Launches and moves rank usable accounts in groups first: plan headroom before usage credits, a credential store that read cleanly, room for a whole session (session-window headroom per running session, `(bar - used) / (sessions + 1)`, scaled by plan size, at least 15 unless the session window resets within the hour), a weekly reset within 4 days, and a usage figure under 6 hours old. Within a group, the highest pace pressure scaled by plan size wins (remaining percent of the binding gated per-model cap, or of the weekly aggregate for an account with no gated row, divided by time to its reset), so weekly quota closest to expiring unused is spent first; ties break by soonest weekly reset, then headroom per session, then lowest weekly use, then fewest sessions. Plan size reads the account's tier: a Claude multiplier divided by 5 (`max 20x` is 4, `pro` 0.2), Codex relative to Plus (`prolite` 5, `pro` 10, `promax` 20). Organization membership is not an input.
 
 - Every periodic check tick folds fresh session tees (the statusline of a terminal session, the `rate_limit_event` stream of a T3 Code or Agent SDK session) into the index and samples up to three accounts whose last sample attempt is oldest, skipping any attempted within the account's sample interval (15 minutes for an empty account or one with no session on this host, shrinking to `policy.usagePollTtlMs` as a live account nears a bar, and 15 minutes again at or over an aggregate bar), with the direct no-spend usage read; a move reads the cached figures, which are as fresh as each account's last successful attempt or its sessions' latest push. A sample that finds the stored access token expired has Claude Code refresh it first (`claude -p /usage` under that store) and reads with the new token.
 - When no account is usable, the session queues first come first served onto a reset target (at most eight waiters per account; overflow waits for the next reset with room) and pauses until that reset if it lands within twice `policy.maxWaitMs`, and otherwise stays put.
@@ -126,7 +126,7 @@ 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.
+- **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.172.0",
+  "version": "1.174.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/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/status.ts

@@ -289,7 +289,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) {
@@ -336,7 +336,7 @@ 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);
   }
   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/claude.ts

@@ -140,6 +140,12 @@ async function storeUsable(a: Account): Promise<boolean> {
   }
 }
 
+export function claudePlanWeight(a: Account): number {
+  const multiplier = a.tier?.match(/(\d+)x\b/)?.[1];
+  if (multiplier != null) return Number(multiplier) / 5;
+  return a.tier?.startsWith("pro") ? 0.2 : 1;
+}
+
 export type Seat = { account: Account; depletedUntil?: number };
 
 export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Account) => boolean = () => true): Seat | null {
@@ -150,7 +156,7 @@ export function pickSeat(now: number, model: ModelInfo | null, eligible: (a: Acc
   for (const a of idx.accounts) dirty = foldTee(a, bars) || dirty;
   if (dirty) saveAccounts(claudePool, idx);
   const seats = presence();
-  const ctx: PickCtx = { now, thresholds: bars, currentId: null, families: gatedFamilies(model, cfg.policy.switchModels), seats };
+  const ctx: PickCtx = { now, thresholds: bars, currentId: null, families: gatedFamilies(model, cfg.policy.switchModels), seats, planWeight: claudePlanWeight };
   const candidates = idx.accounts.filter(eligible);
   const best = pickBest(candidates, ctx);
   if (best) return { account: best };
@@ -204,7 +210,7 @@ export async function borrowClaudeSeat(pid: number, named?: string): Promise<Sea
     }
     const open = idx.accounts.filter((a) => a.needsReauth !== true);
     const usable = await Promise.all(open.map(storeUsable));
-    const ctx: PickCtx = { now: Date.now(), thresholds: bars, currentId: null, families: gatedFamilies(null, cfg.policy.switchModels), seats: presence(living) };
+    const ctx: PickCtx = { now: Date.now(), thresholds: bars, currentId: null, families: gatedFamilies(null, cfg.policy.switchModels), seats: presence(living), planWeight: claudePlanWeight };
     const picked = pickBest(open.filter((_, i) => usable[i]), ctx);
     if (!picked) return null;
     writePresence({ dir: paths.presenceDir, id: seatId, accountId: picked.id, pid });
@@ -361,6 +367,7 @@ export const claude: Provider = {
   apiKeys: claudeApiKeys,
   liveId,
   presence,
+  planWeight: claudePlanWeight,
   gatedFamilies: (cfg) => {
     const seat = liveId();
     const model = modelFromFlag(env("TOKENMAXXING_MODEL", "")) ?? (seat == null ? null : (loadUsageSnapshot(seat)?.state.model ?? null));

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;

package/src/lib/codex.ts

@@ -276,8 +276,31 @@ function install(): void {
   console.log(c.yellow("`tokenmaxxing doctor` lists seats still needing trust."));
 }
 
+// Relative to Plus. prolite (Pro 100) is 5x per OpenAI's launch; pro (Pro 200) was 20x and is about 10x for new
+// subscribers; promax (Pro 500) is unpublished beyond "the most". Business, Enterprise, and Edu seats match Plus.
+const CODEX_PLAN_WEIGHTS: Record<string, number> = {
+  free: 0.2,
+  go: 0.5,
+  plus: 1,
+  team: 1,
+  business: 1,
+  enterprise: 1,
+  ent26: 1,
+  edu: 1,
+  edu_plus: 1,
+  prolite: 5,
+  self_serve_business_prolite: 5,
+  edu_pro: 5,
+  pro: 10,
+  promax: 20,
+};
+
+export function codexPlanWeight(a: Account): number {
+  return (a.tier == null ? undefined : CODEX_PLAN_WEIGHTS[a.tier.toLowerCase()]) ?? 1;
+}
+
 export function codexPickCtx(now: number, currentId: string | null): PickCtx {
-  return { now, thresholds: thresholdBars(loadConfig()), currentId, families: null, seats: null };
+  return { now, thresholds: thresholdBars(loadConfig()), currentId, families: null, seats: null, planWeight: codexPlanWeight };
 }
 
 export function pickCodexSeat(now: number, eligible: (a: Account) => boolean = (a) => codexStoreUsable(a.id)): Account | null {
@@ -343,6 +366,7 @@ export const codex: Provider = {
   statusOnly: false,
   liveId,
   presence,
+  planWeight: codexPlanWeight,
   gatedFamilies: () => null,
   observeLive: (account, cfg, now, opts) => observeCodex(account, cfg, now, { probe: opts.probe, refresh: true }),
   samplePool,

package/src/lib/decide.ts

@@ -199,7 +199,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     while (true) {
       const cur = loadAccounts(p.pool);
       const seat = seatOf(cur);
-      const ctx: PickCtx = { now, thresholds: bars, currentId: seat?.id ?? null, families: switchFamilies, seats };
+      const ctx: PickCtx = { now, thresholds: bars, currentId: seat?.id ?? null, families: switchFamilies, seats, planWeight: p.planWeight };
       const credited = !enforced2 && seat != null && !seat.needsReauth && !isExhausted(seat, ctx) && onCredits(seat, ctx);
       const best = pickBest(usable(cur.accounts).filter((a) => !((credited || keyId != null) && opts.refused?.includes(a.id))), ctx);
       if (credited && (best == null || onCredits(best, ctx))) return { swapped: false, account: null, reason: "no-plan-headroom" };
@@ -232,7 +232,7 @@ export async function evaluateAndMaybeSwap(p: Provider, now = Date.now(), canRes
     while (true) {
       const fresh = loadAccounts(p.pool);
       const current = seatOf(fresh);
-      const ctx: PickCtx = { now, thresholds: bars, currentId: current?.id ?? null, families: switchFamilies, seats };
+      const ctx: PickCtx = { now, thresholds: bars, currentId: current?.id ?? null, families: switchFamilies, seats, planWeight: p.planWeight };
       const others = liveWaitClaims(now).filter((c) => c.sessionId !== waiterId);
       const waiters = new Map(Object.entries(countBy(others, (c) => c.accountId)));
       const waitable = usable(fresh.accounts).filter((a) => keyId == null || !opts.refused?.includes(a.id));

package/src/lib/grok.ts

@@ -134,7 +134,9 @@ export const grok = statusOnlyProvider({
   versionOk: (out) => out.toLowerCase().includes("grok"),
   importIntro: "Opening an isolated grok login for your first pooled account - the login you already have stays as it is.",
   foundLive: (count) => `found ${count} grok login(s) in ${grokPaths.home} - pooling the first; use \`tokenmaxxing add --grok\` for the rest.`,
-  installNotice: "grok pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled grok accounts.",
+  install: () => {
+    console.log(c.dim("grok pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled grok accounts."));
+  },
   loginStep: () => `Sign in in the browser session that opens (or run ${c.bold("grok login --device-auth")} on headless hosts first).`,
   samplePool,
 });

package/src/lib/install.ts

@@ -180,6 +180,14 @@ export function installPiSupervisor(): void {
   writeFileAtomic(piSupervisorLink(), `#!/bin/sh\nexec ${shellQuote(installEntryPoints())} __supervise-pi "$@"\n`, 0o755);
 }
 
+export function museSupervisorLink(): string {
+  return join(paths.binDir, "muse");
+}
+
+export function installMuseSupervisor(): void {
+  writeFileAtomic(museSupervisorLink(), `#!/bin/sh\nexec ${shellQuote(installEntryPoints())} __supervise-muse "$@"\n`, 0o755);
+}
+
 export type UnitJob = {
   label: string;
   arg: string;
@@ -484,6 +492,7 @@ export function uninstallTargets(live: boolean): string[] {
     paths.supervisorLink,
     codexSupervisorLink(),
     piSupervisorLink(),
+    museSupervisorLink(),
     join(paths.binDir, "xx"),
     installedBin(),
     ...(rc == null ? [] : [`${rc}: the ${PATH_LINE_MARK} line`]),
@@ -495,7 +504,7 @@ export function uninstallSupervisor(input: { live: boolean }): UninstallOutcome
   const timer = uninstallJob(CHECK_JOB, input.live);
   const hub = uninstallJob(HUB_JOB, input.live);
   uninstallCodexSupervisor();
-  for (const f of [paths.supervisorLink, piSupervisorLink(), join(paths.binDir, "xx"), installedBin()]) {
+  for (const f of [paths.supervisorLink, piSupervisorLink(), museSupervisorLink(), join(paths.binDir, "xx"), installedBin()]) {
     rmSync(f, { force: true });
   }
   const rc = shellRcPath();

package/src/lib/muse.ts

@@ -1,12 +1,20 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { join, sep } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
+import { ensurePathAhead } from "./claude.ts";
+import { MUSE_BIN } from "./claudebin.ts";
 import { http, safeErrorDetail } from "./http.ts";
-import { errorMessage } from "./log.ts";
-import { env, museAuthJsonFor, musePaths, musePool, museStoreDirFor } from "./paths.ts";
-import type { SampleReport } from "./provider.ts";
-import { readJsonFile, type Harvest } from "./state.ts";
+import { isBinDirAhead, installMuseSupervisor, museSupervisorLink } from "./install.ts";
+import { withLock } from "./lock.ts";
+import { errorMessage, log } from "./log.ts";
+import { env, museAuthJsonFor, musePaths, musePool, museSeatFromEnv, museStoreDirFor } from "./paths.ts";
+import { isExhausted, landWindows, pickBest, pickEarliestReset, thresholdBars, type PickCtx } from "./picker.ts";
+import { seatCounts } from "./presence.ts";
+import { StoreUnusableError, type Observation, type Provider, type SampleReport } from "./provider.ts";
+import { loadAccounts, loadConfig, readJsonFile, saveAccounts, type Harvest } from "./state.ts";
 import { statusOnlyProvider, type AuthEntry } from "./statusonly.ts";
-import { EpochSecondsSchema, ErrnoSchema, JsonTextSchema, type Account } from "./types.ts";
+import { EpochSecondsSchema, ErrnoSchema, JsonTextSchema, type Account, type Config, type Window } from "./types.ts";
 import { c } from "../cli/render.ts";
 
 const MuseProviderSchema = z.looseObject({
@@ -54,6 +62,108 @@ function readAuth(path: string): AuthEntry[] {
   return out;
 }
 
+export function museStoreUsable(accountId: string): boolean {
+  try {
+    return readAuth(museAuthJsonFor(accountId)).some((e) => e.id === accountId && e.usable);
+  } catch {
+    return false;
+  }
+}
+
+export function museStoreIdentity(accountId: string): string[] {
+  return readAuth(museAuthJsonFor(accountId)).map((e) => e.id);
+}
+
+function namesIn(dir: string): string[] {
+  try {
+    return readdirSync(dir);
+  } catch (e) {
+    if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return [];
+    throw e;
+  }
+}
+
+// A mirror link is one this code made: a symlink to the real config home's entry of the same name.
+function isMirrorLink(from: string, to: string, name: string): boolean {
+  if (lstatSync(join(to, name), { throwIfNoEntry: false })?.isSymbolicLink() !== true) return false;
+  return readlinkSync(join(to, name)) === join(from, name);
+}
+
+function linkEntries(from: string, to: string, keep: (name: string) => boolean): void {
+  for (const name of namesIn(from)) {
+    if (!keep(name)) continue;
+    try {
+      symlinkSync(join(from, name), join(to, name));
+    } catch (e) {
+      if (ErrnoSchema.safeParse(e).data?.code !== "EEXIST") throw e;
+    }
+  }
+}
+
+function sharedTop(name: string): boolean {
+  return name !== "muse" && !`${musePaths.storesDir}${sep}`.startsWith(join(musePaths.configHome, name) + sep);
+}
+
+function sharedMuse(name: string): boolean {
+  return !name.startsWith("auth.json") && !name.endsWith(".lock");
+}
+
+// The store doubles as the seated session's XDG_CONFIG_HOME, which every tool the session runs inherits, so it
+// mirrors the real config home: a link to each entry but `muse`, and in `muse/` a link to each entry but the login.
+function configHomeMarker(accountId: string): string {
+  return `${museStoreDirFor(accountId)}.config-home`;
+}
+
+// A store mirrors one config home, recorded beside it. Relinking it to another while a session may run on it could
+// redirect that session, so a launch from another config home is refused instead.
+function recordedConfigHome(accountId: string): string | null {
+  try {
+    return readFileSync(configHomeMarker(accountId), "utf8");
+  } catch (e) {
+    if (ErrnoSchema.safeParse(e).data?.code !== "ENOENT") throw e;
+    return null;
+  }
+}
+
+// Why this process cannot seat the account's store, or null when it can.
+export function museStoreMismatch(accountId: string): string | null {
+  const recorded = recordedConfigHome(accountId);
+  if (recorded == null || recorded === musePaths.configHome) return null;
+  return `${museStoreDirFor(accountId)} mirrors the config home ${recorded}, not ${musePaths.configHome} - launch with XDG_CONFIG_HOME=${recorded}, or run \`tokenmaxxing rm --muse\` and add the account again`;
+}
+
+export function ensureMuseStoreHome(accountId: string): string {
+  const store = museStoreDirFor(accountId);
+  const config = join(store, "muse");
+  const mismatch = museStoreMismatch(accountId);
+  if (mismatch != null) throw new Error(mismatch);
+  mkdirSync(config, { recursive: true, mode: 0o700 });
+  if (recordedConfigHome(accountId) == null) writeFileAtomic(configHomeMarker(accountId), musePaths.configHome);
+  linkEntries(musePaths.configHome, store, sharedTop);
+  linkEntries(join(musePaths.configHome, "muse"), config, sharedMuse);
+  return store;
+}
+
+// Deletes the login. Anything in the store besides the login and the mirror links (an entry a seated tool or Muse
+// Code made there, such as a settings.json rewritten in place of its link) keeps the store whole, mirror links
+// included, since a kept entry may point through one; the command names each kept entry.
+function removeMuseStore(accountId: string): void {
+  const store = museStoreDirFor(accountId);
+  const config = join(store, "muse");
+  for (const name of namesIn(config)) if (name.startsWith("auth.json")) rmSync(join(config, name), { force: true });
+  const home = recordedConfigHome(accountId) ?? musePaths.configHome;
+  const kept = [
+    ...namesIn(config).filter((n) => !isMirrorLink(join(home, "muse"), config, n)).map((n) => join(config, n)),
+    ...namesIn(store).filter((n) => n !== "muse" && !isMirrorLink(home, store, n)).map((n) => join(store, n)),
+  ];
+  if (kept.length > 0) {
+    console.log(c.yellow(`kept ${store} without its login: it holds ${kept.join(", ")}, which a seated session made there - move what you need, then delete the directory`));
+    return;
+  }
+  rmSync(store, { recursive: true, force: true });
+  rmSync(configHomeMarker(accountId), { force: true });
+}
+
 const SubscriptionWindowSchema = z.looseObject({ used_percent: z.number(), resets_at: EpochSecondsSchema });
 
 const MintSchema = z.looseObject({
@@ -62,7 +172,7 @@ const MintSchema = z.looseObject({
       window: SubscriptionWindowSchema.extend({ window_duration_mins: z.number() }),
       weekly: SubscriptionWindowSchema,
     })
-    .nullable(),
+    .nullish(),
 });
 
 const WEEK_S = 7 * 86400;
@@ -81,51 +191,136 @@ function storedAccessToken(id: string): string | null {
   return null;
 }
 
-async function readMuseUsage(account: Account, now: number): Promise<SampleReport> {
+// windows null: the mint carried no subs_usage, which it leaves out while no 5-hour window is open.
+type MuseRead = { ok: true; windows: Window[] | null; at: number } | { ok: false; reason: string; rejected: boolean };
+
+// With no window open, a stored window that has not reset (the weekly one at its limit, say) still binds.
+function landedWindows(read: { windows: Window[] | null }, stored: Window[], now: number): Window[] {
+  return read.windows ?? stored.filter((w) => w.resetsAt != null && w.resetsAt > now);
+}
+
+async function readMuseUsage(accountId: string, now: number): Promise<MuseRead> {
   let token: string | null;
   try {
-    token = storedAccessToken(account.id);
+    token = storedAccessToken(accountId);
   } catch (e) {
-    return { ok: false, reason: `this account's store is unreadable (${errorMessage(e)}) - run \`tokenmaxxing auth --muse\`` };
+    return { ok: false, rejected: false, reason: `this account's store is unreadable (${errorMessage(e)}) - run \`tokenmaxxing auth --muse\`` };
   }
-  if (token == null) return { ok: false, reason: "no access_token in this account's store - run `tokenmaxxing auth --muse`" };
+  if (token == null) return { ok: false, rejected: false, reason: "no access_token in this account's store - run `tokenmaxxing auth --muse`" };
   let res: Response;
   let text: string;
   try {
     res = await http.post(usageUrl(), { headers: { Authorization: `Bearer ${token}` }, json: {} });
     text = await res.text();
   } catch (e) {
-    return { ok: false, reason: `Muse Code usage read failed: endpoint unreachable: ${errorMessage(e)}` };
+    return { ok: false, rejected: false, reason: `Muse Code usage read failed: endpoint unreachable: ${errorMessage(e)}` };
   }
   if (res.status === 401 || res.status === 403) {
-    account.needsReauth = true;
-    return { ok: false, reason: `Muse Code rejected the stored login (HTTP ${res.status}) - run \`tokenmaxxing auth --muse\`` };
+    return { ok: false, rejected: true, reason: `Muse Code rejected the stored login (HTTP ${res.status}) - run \`tokenmaxxing auth --muse\`` };
   }
-  if (!res.ok) return { ok: false, reason: `Muse Code usage read failed: HTTP ${res.status}: ${safeErrorDetail({ text })}` };
+  if (!res.ok) return { ok: false, rejected: false, reason: `Muse Code usage read failed: HTTP ${res.status}: ${safeErrorDetail({ text })}` };
   const parsed = MintSchema.safeParse(JsonTextSchema.safeParse(text).data);
-  if (!parsed.success) return { ok: false, reason: "Muse Code usage read failed: endpoint returned an unexpected body shape (withheld)" };
-  if (parsed.data.subs_usage == null) return { ok: false, reason: "Muse Code reports no usage until a model request opens the 5-hour window" };
+  if (!parsed.success) return { ok: false, rejected: false, reason: "Muse Code usage read failed: endpoint returned an unexpected body shape (withheld)" };
+  if (parsed.data.subs_usage == null) return { ok: true, windows: null, at: now };
   const { window, weekly } = parsed.data.subs_usage;
-  account.windows = [
-    { name: null, usedPercentage: window.used_percent, resetsAt: window.resets_at, windowSeconds: window.window_duration_mins * 60, sampledAt: now },
-    { name: null, usedPercentage: weekly.used_percent, resetsAt: weekly.resets_at, windowSeconds: WEEK_S, sampledAt: now },
-  ];
-  account.lastUsageAt = now;
-  return { ok: true, source: "probe" };
+  return {
+    ok: true,
+    at: now,
+    windows: [
+      { name: null, usedPercentage: window.used_percent, resetsAt: window.resets_at, windowSeconds: window.window_duration_mins * 60, sampledAt: now },
+      { name: null, usedPercentage: weekly.used_percent, resetsAt: weekly.resets_at, windowSeconds: WEEK_S, sampledAt: now },
+    ],
+  };
 }
 
 async function samplePool(accounts: Account[], now: number): Promise<Map<string, SampleReport>> {
   const reports = new Map<string, SampleReport>();
-  await Promise.all(accounts.map(async (account) => reports.set(account.id, await readMuseUsage(account, now))));
+  await Promise.all(
+    accounts.map(async (account) => {
+      const read = await readMuseUsage(account.id, now);
+      if (read.ok) {
+        account.windows = landedWindows(read, account.windows, read.at);
+        account.lastUsageAt = read.at;
+        reports.set(account.id, { ok: true, source: "probe" });
+        return;
+      }
+      if (read.rejected) account.needsReauth = true;
+      reports.set(account.id, { ok: false, reason: read.reason });
+    }),
+  );
   return reports;
 }
 
-export const muse = statusOnlyProvider({
+export async function observeMuse(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null> {
+  if (opts.probe && (account.lastUsageAt == null || now - account.lastUsageAt > cfg.policy.usagePollTtlMs)) {
+    const read = await readMuseUsage(account.id, Date.now());
+    if (!read.ok) log("muse.usage_failed", { account: account.id.slice(0, 8), reason: read.reason.slice(0, 200) });
+    await withLock(musePool.lockFile, () => {
+      const idx = loadAccounts(musePool);
+      const a = idx.accounts.find((x) => x.id === account.id);
+      if (!a) return;
+      if (read.ok) {
+        if (a.lastUsageAt == null || read.at > a.lastUsageAt) landWindows(a, landedWindows(read, a.windows, read.at), read.at, thresholdBars(cfg));
+      } else if (read.rejected) {
+        a.needsReauth = true;
+      }
+      saveAccounts(musePool, idx);
+    });
+  }
+  const current = loadAccounts(musePool).accounts.find((a) => a.id === account.id) ?? account;
+  return current.lastUsageAt != null ? { windows: current.windows, at: current.lastUsageAt } : null;
+}
+
+function presence(): Map<string, number> {
+  return seatCounts(musePaths.presenceDir);
+}
+
+// A store that mirrors another config home is no seat for this process; moving a session onto it would stop the
+// session and then refuse to start it.
+function seatable(a: Account): boolean {
+  return a.needsReauth !== true && museStoreUsable(a.id) && museStoreMismatch(a.id) == null;
+}
+
+// Reads the usage of every seatable account whose sample is stale. It takes the pool lock itself, so it runs
+// before the lock a placement holds.
+export async function probeMuseSeats(now: number): Promise<void> {
+  const cfg = loadConfig();
+  await Promise.all(loadAccounts(musePool).accounts.filter(seatable).map((a) => observeMuse(a, cfg, now, { probe: true })));
+}
+
+export function museSeatOpen(a: Account, now: number): boolean {
+  return seatable(a) && !isExhausted(a, { now, thresholds: thresholdBars(loadConfig()), currentId: null, families: null, seats: null });
+}
+
+// Ranks the stored accounts the way a move does, spreading sessions across accounts with the same headroom; with
+// none under its bars, the one that frees up first. Call it under the pool lock, after probeMuseSeats.
+export function rankMuseSeat(now: number): Account | null {
+  const ctx: PickCtx = { now, thresholds: thresholdBars(loadConfig()), currentId: null, families: null, seats: presence() };
+  const open = loadAccounts(musePool).accounts.filter(seatable);
+  return pickBest(open, ctx) ?? pickEarliestReset(open, ctx)?.account ?? null;
+}
+
+async function prepareMove(target: Account): Promise<void> {
+  if (!museStoreUsable(target.id)) {
+    throw new StoreUnusableError(`${target.label} has no usable login in its store - run \`tokenmaxxing auth --muse ${target.label}\``);
+  }
+  const mismatch = museStoreMismatch(target.id);
+  if (mismatch != null) throw new StoreUnusableError(mismatch);
+  log("move.prepared", { account: target.id.slice(0, 8), label: target.label, muse: true });
+}
+
+function install(): void {
+  installMuseSupervisor();
+  console.log(`${c.green("✓")} muse supervisor installed at ${museSupervisorLink()}`);
+  if (!isBinDirAhead(MUSE_BIN)) ensurePathAhead();
+}
+
+const base = statusOnlyProvider({
   name: "muse",
   flag: " --muse",
   pool: musePool,
-  binName: "muse",
-  binKey: "museBin",
+  binName: MUSE_BIN.name,
+  binKey: MUSE_BIN.key,
   storeDirFor: museStoreDirFor,
   authJsonFor: museAuthJsonFor,
   homeEnv: "XDG_CONFIG_HOME",
@@ -133,12 +328,22 @@ export const muse = statusOnlyProvider({
   onboardAuthRel: "muse/auth.json",
   liveAuthPath: () => musePaths.authJson,
   readAuth,
-  liveId: () => null,
-  presence: () => new Map(),
-  versionOk: (out) => out.toLowerCase().includes("muse code"),
+  liveId: () => museSeatFromEnv(loadAccounts(musePool).accounts.map((a) => a.id)),
+  presence,
+  versionOk: MUSE_BIN.versionOk,
   importIntro: "Opening an isolated Muse Code login for your first pooled account - the login you already have stays as it is.",
   foundLive: (count) => `found ${count} Muse Code login(s) in ${musePaths.authJson} - pooling the first; use \`tokenmaxxing add --muse\` for the rest.`,
-  installNotice: "muse pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled Muse Code accounts.",
+  install,
   loginStep: () => `Approve the code in the browser that ${c.bold("muse login")} opens.`,
   samplePool,
 });
+
+export const muse: Provider = {
+  ...base,
+  seats: "shared",
+  statusOnly: false,
+  observeLive: (account, cfg, now, opts) => observeMuse(account, cfg, now, { probe: opts.probe }),
+  swap: prepareMove,
+  removeCredentials: async (a) => removeMuseStore(a.id),
+  classifySwapError: (e) => (e instanceof StoreUnusableError ? "skip" : "fatal"),
+};

package/src/lib/paths.ts

@@ -1,5 +1,5 @@
 import { homedir, userInfo } from "node:os";
-import { join, resolve } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { z } from "zod";
 
 const HOME = homedir();
@@ -124,17 +124,41 @@ export function grokAuthJsonFor(accountId: string): string {
   return join(grokStoreDirFor(accountId), "auth.json");
 }
 
+const MUSE_STORES_DIR = join(TM_HOME, "muse-stores");
+const XDG_CONFIG = optionalEnv("XDG_CONFIG_HOME");
+export const MUSE_CONFIG_HOME_ENV = "TOKENMAXXING_XDG_CONFIG_HOME";
+
+export function inMuseStores(path: string): boolean {
+  return path === MUSE_STORES_DIR || path.startsWith(MUSE_STORES_DIR + sep);
+}
+
+// Inside a seat XDG_CONFIG_HOME names a store, and the seat carries the real config home it mirrors in
+// MUSE_CONFIG_HOME_ENV; a store named with no such record (one rm --muse kept) falls back to ~/.config.
+const MUSE_CONFIG_HOME =
+  XDG_CONFIG == null ? join(HOME, ".config") : !inMuseStores(XDG_CONFIG) ? XDG_CONFIG : (optionalEnv(MUSE_CONFIG_HOME_ENV) ?? join(HOME, ".config"));
+
 export const musePaths = {
-  authJson: join(env("XDG_CONFIG_HOME", join(HOME, ".config")), "muse", "auth.json"),
-  storesDir: join(TM_HOME, "muse-stores"),
+  configHome: MUSE_CONFIG_HOME,
+  authJson: join(MUSE_CONFIG_HOME, "muse", "auth.json"),
+  sessionsDir: join(env("XDG_DATA_HOME", join(HOME, ".local", "share")), "muse", "sessions"),
+  storesDir: MUSE_STORES_DIR,
+  presenceDir: join(TM_HOME, "muse-live"),
 } as const;
 
+// A store is the XDG_CONFIG_HOME of the sessions seated on its account: Muse Code reads its login only from
+// $XDG_CONFIG_HOME/muse/auth.json.
 export function museStoreDirFor(accountId: string): string {
   return join(musePaths.storesDir, shortId(accountId));
 }
 
 export function museAuthJsonFor(accountId: string): string {
-  return join(museStoreDirFor(accountId), "auth.json");
+  return join(museStoreDirFor(accountId), "muse", "auth.json");
+}
+
+export function museSeatFromEnv(accountIds: string[], env: Record<string, string | undefined> = process.env): string | null {
+  const home = env.XDG_CONFIG_HOME;
+  if (home == null || home === "") return null;
+  return accountIds.find((id) => museStoreDirFor(id) === home) ?? null;
 }
 
 export function grokSeatFromEnv(accountIds: string[], env: Record<string, string | undefined> = process.env): string | null {

package/src/lib/picker.ts

@@ -17,6 +17,7 @@ export type PickCtx = {
   currentId: string | null;
   families: string[] | null;
   seats: Map<string, number> | null;
+  planWeight?: (a: Account) => number;
 };
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
@@ -166,29 +167,58 @@ export function seatHeadroom(a: Account, ctx: PickCtx): number {
 
 const MIN_SEAT_HEADROOM = 5;
 
+const planWeight = (a: Account, ctx: PickCtx): number => ctx.planWeight?.(a) ?? 1;
+
 function seatFull(a: Account, ctx: PickCtx): boolean {
   const session = sessionWindow(a);
   if (ctx.seats == null || session == null || spendsCredits(a, ctx.thresholds)) return false;
-  return seatHeadroom(a, ctx) < MIN_SEAT_HEADROOM;
+  return seatHeadroom(a, ctx) * planWeight(a, ctx) < MIN_SEAT_HEADROOM;
 }
 
 export function onCredits(a: Account, ctx: PickCtx): boolean {
   return spendsCredits(a, ctx.thresholds) && isExhausted({ ...a, hasCredits: false }, ctx);
 }
 
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEKLY_SOON_MS = 4 * DAY_MS;
+const THREAD_HEADROOM = 15;
+const SESSION_SOON_MS = 60 * 60 * 1000;
+const STALE_MS = 6 * 60 * 60 * 1000;
+
+function cramped(a: Account, ctx: PickCtx): boolean {
+  const session = sessionWindow(a);
+  if (session == null || spendsCredits(a, ctx.thresholds)) return false;
+  const end = windowEnd(session);
+  const resetsSoon = end > ctx.now && end - ctx.now <= SESSION_SOON_MS;
+  return !resetsSoon && seatHeadroom(a, ctx) * planWeight(a, ctx) < THREAD_HEADROOM;
+}
+
+// Judged per window, because a fresh statusline sample refreshes the session and weekly figures but carries an old per-model cap forward.
+function stale(a: Account, ctx: PickCtx): boolean {
+  const read = [sessionWindow(a), weeklyWindow(a), ...gatedWindows(a, ctx.families)];
+  return read.some((w) => w != null && windowEnd(w) > ctx.now && ctx.now - w.sampledAt > STALE_MS);
+}
+
 const swapPreference = (ctx: PickCtx) => [
   (a: Account) => (onCredits(a, ctx) ? 1 : 0),
-  ...(ctx.seats == null ? [] : [(a: Account) => -seatHeadroom(a, ctx)]),
-  (a: Account) => -pacePressure(a, ctx),
+  (a: Account) => ((a.storeFails ?? 0) > 0 ? 1 : 0),
+  (a: Account) => (a.windows.length === 0 ? 1 : 0),
+  // A full account ranks after every open one, and among full accounts the most room per session wins.
+  (a: Account) => (seatFull(a, ctx) ? 1 : 0),
+  (a: Account) => (seatFull(a, ctx) ? -seatHeadroom(a, ctx) * planWeight(a, ctx) : 0),
+  (a: Account) => (cramped(a, ctx) ? 1 : 0),
+  (a: Account) => (weeklyExpiry(a, ctx.now) - ctx.now <= WEEKLY_SOON_MS ? 0 : 1),
+  (a: Account) => (stale(a, ctx) ? 1 : 0),
+  (a: Account) => -pacePressure(a, ctx) * planWeight(a, ctx),
   (a: Account) => weeklyExpiry(a, ctx.now),
+  ...(ctx.seats == null ? [] : [(a: Account) => -seatHeadroom(a, ctx) * planWeight(a, ctx)]),
   (a: Account) => weeklyWindow(a)?.usedPercentage ?? 101,
   ...(ctx.seats == null ? [] : [(a: Account) => ctx.seats?.get(a.id) ?? 0]),
 ];
 
 export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   const usable = accounts.filter((a) => a.id !== ctx.currentId && !a.needsReauth && !isExhausted(a, ctx));
-  const open = usable.filter((a) => !seatFull(a, ctx));
-  return sortBy(open.length > 0 ? open : usable, swapPreference(ctx))[0] ?? null;
+  return sortBy(usable, swapPreference(ctx))[0] ?? null;
 }
 
 export function usableAt(a: Account, ctx: PickCtx): number {

package/src/lib/provider.ts

@@ -36,6 +36,7 @@ export type Provider = {
   liveId(): string | null;
   presence(): Map<string, number>;
   gatedFamilies(cfg: Config): string[] | null;
+  planWeight?(account: Account): number;
   observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean; perModel: boolean }): Promise<Observation | null>;
   samplePool(accounts: Account[], now: number): Promise<Map<string, SampleReport>>;
   mergeWindows(next: Window[], prev: Window[]): Window[];

package/src/lib/sessions.ts

@@ -59,12 +59,15 @@ function listDir(dir: string, root: string): Dirent[] {
 }
 
 function tmpSweepDirs(root: string): string[] {
-  const dirs = [paths.home, paths.usageDir, paths.presenceDir, paths.respawnDir, sessionsDir(), paths.binDir, paths.apiKeysDir, codexPaths.presenceDir, codexPaths.respawnDir];
+  const dirs = [paths.home, paths.usageDir, paths.presenceDir, paths.respawnDir, sessionsDir(), paths.binDir, paths.apiKeysDir, codexPaths.presenceDir, codexPaths.respawnDir, musePaths.presenceDir];
   for (const parent of SWEEP_PARENTS) {
     for (const child of listDir(parent, root)) {
       if (child.isDirectory()) dirs.push(join(parent, child.name));
     }
   }
+  for (const child of listDir(musePaths.storesDir, root)) {
+    if (child.isDirectory()) dirs.push(join(musePaths.storesDir, child.name, "muse"));
+  }
   return dirs;
 }
 

package/src/lib/statusonly.ts

@@ -28,7 +28,7 @@ export type StatusOnlySpec = {
   versionOk: (versionOutput: string) => boolean;
   importIntro: string;
   foundLive: (count: number) => string;
-  installNotice: string;
+  install: () => void;
   loginStep: () => string;
   samplePool: Provider["samplePool"];
 };
@@ -110,9 +110,7 @@ export function statusOnlyProvider(spec: StatusOnlySpec): Provider {
     login,
     importLive,
     preflight,
-    install: () => {
-      console.log(c.dim(spec.installNotice));
-    },
+    install: spec.install,
     loginStep: spec.loginStep,
     windowLabel: (name) => name.toLowerCase(),
   };

package/src/lib/supervise.ts

@@ -8,7 +8,7 @@ import { readLines } from "./proc.ts";
 import { writePresence } from "./presence.ts";
 import { restoreTermios } from "./tty.ts";
 
-export type WrappedProduct = "claude" | "codex" | "pi";
+export type WrappedProduct = "claude" | "codex" | "pi" | "muse";
 
 export const SEAT_POLL_MS = 10_000;
 export const SEAT_RETRY_MS = 60_000;
@@ -29,6 +29,7 @@ const WRAPPED: Record<WrappedProduct, { setting: string; binary: string; events:
   claude: { setting: "claudeBin", binary: "Claude", events: "supervisor" },
   codex: { setting: "codexBin", binary: "codex", events: "codexsupervisor" },
   pi: { setting: "piBin", binary: "pi", events: "pisupervisor" },
+  muse: { setting: "museBin", binary: "muse", events: "musesupervisor" },
 };
 
 export function exitStatus(child: { exitCode: number | null; signalCode: string | null }): number {

package/src/main.ts

@@ -10,6 +10,7 @@ import { runStopFailureHook } from "./entries/stopfailurehook.ts";
 import { runCodexSupervisor } from "./entries/codexsupervisor.ts";
 import { runCodexStopHook } from "./entries/codexstophook.ts";
 import { runPiSupervisor } from "./entries/pisupervisor.ts";
+import { runMuseSupervisor } from "./entries/musesupervisor.ts";
 import { claude } from "./lib/claude.ts";
 import { codex } from "./lib/codex.ts";
 import { grok } from "./lib/grok.ts";
@@ -41,7 +42,7 @@ const MUSE_FLAG = "--muse";
 const PI_FLAG = "--pi";
 const JSON_COMMANDS = new Set(["status", "config", "check"]);
 const CODEX_COMMANDS = new Set(["init", "add", "auth", "emails", "rm", "rename", "seat"]);
-const STATUS_ONLY_COMMANDS = new Set(["init", "add", "auth", "emails", "rm", "rename"]);
+const POOL_COMMANDS = new Set(["init", "add", "auth", "emails", "rm", "rename"]);
 const MAX_OPERANDS = new Map([["init", 0], ["add", 0], ["emails", 0], ["rm", 1], ["rename", 2], ["key", 4]]);
 
 function printHelp(): void {
@@ -53,7 +54,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing init --codex")}  same for codex: log in the first account, isolated, install codex supervisor + Stop hook
   ${c.cyan("tokenmaxxing init --pi")}     install the pi supervisor: pi sessions run on pooled Claude or ChatGPT accounts that are logged into pi
   ${c.cyan("tokenmaxxing init --grok")}   pool grok Build logins (status-only: no supervisor yet)
-  ${c.cyan("tokenmaxxing init --muse")}   pool Muse Code logins (status-only: no supervisor and no usage read)
+  ${c.cyan("tokenmaxxing init --muse")}   same for Muse Code: log in the first account, isolated, install the muse supervisor
   ${c.cyan("tokenmaxxing add")}        register an additional account (isolated login)
   ${c.cyan("tokenmaxxing add")} --codex | --grok | --muse   same for the codex, grok, or muse pool
   ${c.cyan("tokenmaxxing auth")} [--codex | --grok | --muse] [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every account that is flagged or has no usable credential in its store, one by one)
@@ -99,6 +100,9 @@ async function main(): Promise<number> {
   if (argv0 === "pi" || argv[0] === "__supervise-pi") {
     return runPiSupervisor(argv[0] === "__supervise-pi" ? argv.slice(1) : argv);
   }
+  if (argv0 === "muse" || argv[0] === "__supervise-muse") {
+    return runMuseSupervisor(argv[0] === "__supervise-muse" ? argv.slice(1) : argv);
+  }
 
   jsonMode = argv.includes(JSON_FLAG);
   const json = jsonMode;
@@ -139,8 +143,8 @@ async function main(): Promise<number> {
     return 2;
   }
 
-  if (provider.statusOnly && (sub == null || !STATUS_ONLY_COMMANDS.has(sub))) {
-    emitError({ json, message: `${provider.flag.trim()} applies to ${[...STATUS_ONLY_COMMANDS].join(", ")}, not ${sub ?? "status"}` });
+  if ((provider === grok || provider === muse) && (sub == null || !POOL_COMMANDS.has(sub))) {
+    emitError({ json, message: `${provider.flag.trim()} applies to ${[...POOL_COMMANDS].join(", ")}, not ${sub ?? "status"}` });
     return 2;
   }