tokenmaxxing 1.173.0 → 1.175.0

package/src/lib/cursor.ts

@@ -0,0 +1,185 @@
+import { dirname, join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.ts";
+import { http, safeErrorDetail } from "./http.ts";
+import { errorMessage } from "./log.ts";
+import { cursorAuthJsonFor, cursorPaths, cursorPool, cursorStoreDirFor, env } from "./paths.ts";
+import type { SampleReport } from "./provider.ts";
+import { readJsonFile, type Harvest } from "./state.ts";
+import { statusOnlyProvider, type AuthEntry } from "./statusonly.ts";
+import { ErrnoSchema, JsonTextSchema, type Account, type Window } from "./types.ts";
+import { c } from "../cli/render.ts";
+
+const CursorAuthSchema = z.looseObject({ accessToken: z.string().optional() });
+type CursorAuth = z.infer<typeof CursorAuthSchema>;
+
+const CliConfigSchema = z.looseObject({
+  authInfo: z.looseObject({ authId: z.string().optional(), email: z.string().nullish() }).optional(),
+});
+
+const JwtPayloadSchema = z.looseObject({ sub: z.string().min(1) });
+
+function readOptional<T>(path: string, schema: z.ZodType<T>): T | null {
+  try {
+    return readJsonFile(path, schema);
+  } catch (e) {
+    if (ErrnoSchema.safeParse(e).data?.code === "ENOENT") return null;
+    throw e;
+  }
+}
+
+function tokenSubject(token: string): string | null {
+  const payload = token.split(".")[1] ?? "";
+  return JwtPayloadSchema.safeParse(JsonTextSchema.safeParse(Buffer.from(payload, "base64url").toString("utf8")).data).data?.sub ?? null;
+}
+
+// The CLI caches the signed-in user next to auth.json; it is the only local copy of the email, because the token carries none.
+function cachedEmail(authPath: string, subject: string): string | null {
+  let config: z.infer<typeof CliConfigSchema> | null;
+  try {
+    config = readOptional(join(dirname(authPath), "cli-config.json"), CliConfigSchema);
+  } catch {
+    return null;
+  }
+  const info = config?.authInfo;
+  if (info?.authId !== subject) return null;
+  const email = info.email?.trim().toLowerCase() ?? "";
+  return email === "" ? null : email;
+}
+
+const harvestTokens = new WeakMap<Harvest, string>();
+
+function readAuth(path: string): AuthEntry[] {
+  const file: CursorAuth | null = readOptional(path, CursorAuthSchema);
+  const token = file?.accessToken ?? "";
+  if (file == null || token === "") return [];
+  const subject = tokenSubject(token);
+  if (subject == null) return [{ id: "", usable: false, harvest: null }];
+  const id = new Bun.CryptoHasher("sha256").update(subject).digest("hex");
+  const harvest: Harvest = {
+    id,
+    email: cachedEmail(path, subject),
+    tier: null,
+    sample: null,
+    park: async () => {
+      writeFileAtomic(cursorAuthJsonFor(id), JSON.stringify(file, null, 2), 0o600);
+    },
+  };
+  harvestTokens.set(harvest, token);
+  return [{ id, usable: true, harvest }];
+}
+
+const EpochMsSchema = z.coerce.number();
+
+const PeriodUsageSchema = z.looseObject({
+  billingCycleStart: EpochMsSchema,
+  billingCycleEnd: EpochMsSchema,
+  planUsage: z
+    .looseObject({
+      includedSpend: z.number().default(0),
+      limit: z.number().default(0),
+      totalPercentUsed: z.number().optional(),
+      apiPercentUsed: z.number().optional(),
+    })
+    .optional(),
+});
+
+const PlanInfoSchema = z.looseObject({ planInfo: z.looseObject({ planName: z.string().optional() }).optional() });
+
+const MeSchema = z.looseObject({ email: z.string().optional() });
+
+function dashboardUrl(method: string): string {
+  return `${env("TOKENMAXXING_CURSOR_API_URL", "https://api2.cursor.sh")}/aiserver.v1.DashboardService/${method}`;
+}
+
+async function dashboard(token: string, method: string): Promise<Response> {
+  return http.post(dashboardUrl(method), { headers: { Authorization: `Bearer ${token}`, "Connect-Protocol-Version": "1" }, json: {} });
+}
+
+async function dashboardField<T>(token: string, method: string, schema: z.ZodType<T>): Promise<T | null> {
+  try {
+    const res = await dashboard(token, method);
+    return res.ok ? (schema.safeParse(JsonTextSchema.safeParse(await res.text()).data).data ?? null) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readCursorUsage(account: Account, now: number): Promise<SampleReport> {
+  let token: string;
+  try {
+    token = readOptional(cursorAuthJsonFor(account.id), CursorAuthSchema)?.accessToken ?? "";
+  } catch (e) {
+    return { ok: false, reason: `this account's store is unreadable (${errorMessage(e)}) - run \`tokenmaxxing auth --cursor\`` };
+  }
+  if (token === "") return { ok: false, reason: "no accessToken in this account's store - run `tokenmaxxing auth --cursor`" };
+  let res: Response;
+  let text: string;
+  const plan = dashboardField(token, "GetPlanInfo", PlanInfoSchema);
+  const me = account.email == null ? dashboardField(token, "GetMe", MeSchema) : null;
+  try {
+    res = await dashboard(token, "GetCurrentPeriodUsage");
+    text = await res.text();
+  } catch (e) {
+    return { ok: false, reason: `Cursor usage read failed: endpoint unreachable: ${errorMessage(e)}` };
+  }
+  if (res.status === 401 || res.status === 403) {
+    account.needsReauth = true;
+    return { ok: false, reason: `Cursor rejected the stored login (HTTP ${res.status}) - run \`tokenmaxxing auth --cursor\`` };
+  }
+  if (!res.ok) return { ok: false, reason: `Cursor usage read failed: HTTP ${res.status}: ${safeErrorDetail({ text })}` };
+  const parsed = PeriodUsageSchema.safeParse(JsonTextSchema.safeParse(text).data);
+  if (!parsed.success) return { ok: false, reason: "Cursor usage read failed: endpoint returned an unexpected body shape (withheld)" };
+  const { billingCycleStart, billingCycleEnd, planUsage } = parsed.data;
+  const total = planUsage?.totalPercentUsed ?? (planUsage != null && planUsage.limit > 0 ? Math.min(100, (planUsage.includedSpend / planUsage.limit) * 100) : null);
+  if (total == null) return { ok: false, reason: "Cursor reports no included-usage limit for this account" };
+  const cycle = { resetsAt: billingCycleEnd, windowSeconds: billingCycleEnd > billingCycleStart ? Math.round((billingCycleEnd - billingCycleStart) / 1000) : null, sampledAt: now };
+  const windows: Window[] = [{ name: null, usedPercentage: total, ...cycle }];
+  if (planUsage?.apiPercentUsed != null) windows.push({ name: "API", usedPercentage: planUsage.apiPercentUsed, ...cycle });
+  account.windows = windows;
+  account.lastUsageAt = now;
+  const planName = (await plan)?.planInfo?.planName?.trim().toLowerCase();
+  if (planName) account.tier = planName;
+  const email = (await me)?.email?.trim().toLowerCase();
+  if (email) account.email = email;
+  return { ok: true, source: "probe" };
+}
+
+async function identify(harvest: Harvest): Promise<void> {
+  const token = harvestTokens.get(harvest);
+  if (harvest.email != null || token == null) return;
+  const email = (await dashboardField(token, "GetMe", MeSchema))?.email?.trim().toLowerCase();
+  if (email) harvest.email = email;
+}
+
+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 readCursorUsage(account, now))));
+  return reports;
+}
+
+export const cursor = statusOnlyProvider({
+  name: "cursor",
+  flag: " --cursor",
+  pool: cursorPool,
+  binName: "cursor-agent",
+  binKey: "cursorBin",
+  storeDirFor: cursorStoreDirFor,
+  authJsonFor: cursorAuthJsonFor,
+  homeEnv: "XDG_CONFIG_HOME",
+  loginArgs: ["login"],
+  onboardAuthRel: "cursor/auth.json",
+  liveAuthPath: () => cursorPaths.authJson,
+  readAuth,
+  liveId: () => null,
+  presence: () => new Map(),
+  versionOk: (out) => /^\d{4}\.\d{2}\.\d{2}-[0-9a-f]+$/.test(out.trim()),
+  importIntro: "Opening an isolated Cursor login for your first pooled account - the login you already have stays as it is.",
+  foundLive: () => `found the Cursor login in ${cursorPaths.authJson} - pooling it; use \`tokenmaxxing add --cursor\` for more.`,
+  install: () => {
+    console.log(c.dim("cursor pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled Cursor accounts."));
+  },
+  loginStep: () => `Approve the login in the browser that ${c.bold("cursor-agent login")} opens.`,
+  samplePool,
+  identify,
+});

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

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { paths } from "./paths.ts";
 import { pidExists } from "./proc.ts";
 
-const POOLS = ["claude", "codex", "pi", "grok", "muse"] as const;
+const POOLS = ["claude", "codex", "pi", "grok", "muse", "cursor"] as const;
 
 export type OnboardPool = (typeof POOLS)[number];
 

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();
@@ -63,6 +63,11 @@ export const musePool = {
   lockFile: join(TM_HOME, "muse-lock"),
 } as const;
 
+export const cursorPool = {
+  accountsJson: join(TM_HOME, "cursor-accounts.json"),
+  lockFile: join(TM_HOME, "cursor-lock"),
+} as const;
+
 export type PoolPaths = { accountsJson: string; lockFile: string };
 
 const CODEX_HOME = env("TOKENMAXXING_CODEX_HOME", env("CODEX_HOME", join(HOME, ".codex")));
@@ -124,17 +129,54 @@ 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 const cursorPaths = {
+  authJson: join(env("XDG_CONFIG_HOME", join(HOME, ".config")), "cursor", "auth.json"),
+  storesDir: join(TM_HOME, "cursor-stores"),
+} as const;
+
+export function cursorStoreDirFor(accountId: string): string {
+  return join(cursorPaths.storesDir, shortId(accountId));
+}
+
+export function cursorAuthJsonFor(accountId: string): string {
+  return join(cursorStoreDirFor(accountId), "auth.json");
 }
 
 export function grokSeatFromEnv(accountIds: string[], env: Record<string, string | undefined> = process.env): string | null {

package/src/lib/provider.ts

@@ -26,7 +26,7 @@ export class StoreUnusableError extends Error {
 }
 
 export type Provider = {
-  name: "claude" | "codex" | "grok" | "muse";
+  name: "claude" | "codex" | "grok" | "muse" | "cursor";
   flag: string;
   pool: PoolPaths;
   seats: "shared" | "live";