tokenmaxxing 0.15.0 → 0.17.0

package/DESIGN.md

@@ -71,6 +71,7 @@ Each terminal ran the supervisor, so each has its own child `claude` and its own
 - **`tokenmaxxing init` imports the account you're already on - automatically, no prompts, no re-login.** It reads the live `Claude Code-credentials` keychain blob plus the `oauthAccount` object in `~/.claude.json` (email, `organizationUuid`, `accountUuid`, plan tier) and writes them as **account #1** into tokenmaxxing's store (`tokenmaxxing-cred-<accountUuid[:8]>` + an `accounts.json` index entry). Nothing about your current session changes - that account stays active; it's now just also a registered pool member. After this one command you already have a working (single-account) pool. `init` also installs the supervisor + the three settings entries.
   - If the current auth is API-key mode (`ANTHROPIC_API_KEY`/`apiKeyHelper`) rather than a subscription `/login`, there's no quota-poolable subscription credential to import - `init` says so and points you to `/login` first (per-token API billing isn't what tokenmaxxing pools).
 - **`tokenmaxxing add`** - registers *additional* accounts: logs one in via a throwaway `CLAUDE_CONFIG_DIR=~/.config/tokenmaxxing/onboard` (your primary login untouched), harvests it into the store, deletes the temp dir + its namespaced item. This is the **only** time `CLAUDE_CONFIG_DIR` is ever used.
+- **`tokenmaxxing auth [sel | --all]`** - reauthenticates an *existing* pool member whose refresh token died (a needs-reauth account can never heal through a swap: the dead token is exactly what a swap would need). Same isolated-login harvest as `add`, but it states which email to sign in with and **requires the login to land on the target account** (harvested `accountUuid` must match, else nothing changes) - the credential write and the needs-reauth clear happen in one flock critical section so a concurrent swap's harvest cannot clobber the fresh backup. Bare `auth` lists the pool with emails and asks which; `--all` walks every flagged account one by one.
 - Both commands exercise `security` reads/writes interactively (where a macOS keychain ACL prompt is acceptable), so the first access never happens cold inside a headless hook.
 
 ---

package/README.md

@@ -38,6 +38,7 @@ claude                  # use claude as always
 | `tokenmaxxing init --codex` | same for codex: import login, install codex supervisor + Stop hook |
 | `tokenmaxxing add` | register an additional account (isolated login, harvested into the pool) |
 | `tokenmaxxing add --codex` | register an additional codex account (isolated login) |
+| `tokenmaxxing auth [sel \| --all]` | reauthenticate a pooled account in place: bare lists the pool (emails shown) and asks which; a selector targets one account and tells you the email to sign in with; `--all` walks every needs-reauth account one by one |
 | `tokenmaxxing switch --codex [sel]` | switch the codex pool (takes effect on the next codex start) |
 | `tokenmaxxing ls` | list pooled accounts |
 | `tokenmaxxing status` | accounts with 5h / weekly usage bars, active + exhausted-until-reset |
@@ -45,7 +46,7 @@ claude                  # use claude as always
 | `tokenmaxxing watch [seconds]` | live status: re-render every N seconds (default 120, floor 30; never pings) |
 | `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
-| `tokenmaxxing rename <sel> <label>` / `rm <sel>` | manage the pool |
+| `tokenmaxxing rename [--codex] <sel> <label>` / `rm <sel>` | manage the pool (`--codex` targets the codex pool: one email can hold both a claude and a codex account) |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
 
 ## How switching decides

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",

package/src/cli/add.ts

@@ -1,109 +1,32 @@
-// `tokenmaxxing add` - register an ADDITIONAL account. Logs one in inside a
-// throwaway CLAUDE_CONFIG_DIR (the ONLY use of CLAUDE_CONFIG_DIR), auto-exits the
-// moment the login lands, samples that account's usage, then harvests its
-// credential + identity into the pool and deletes the temp dir + isolated
-// credential. Your primary login is never touched.
+// `tokenmaxxing add` - register an ADDITIONAL account. Drives one isolated
+// login (see onboard.ts), then pools whatever account it landed on. Your
+// primary login is never touched.
 
-import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { z } from "zod";
-import { readItem, writeItem, deleteItem, parkedTarget, isolatedTarget, claudeAiOauthOnly } from "../lib/credstore.ts";
-import { resolveRealClaude } from "../lib/claudebin.ts";
-import { probeUsage } from "../lib/usage.ts";
-import { saveTermios, restoreTermios } from "../lib/tty.ts";
 import { withLock } from "../lib/lock.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
-import { CredentialBlobSchema, OAuthAccountSchema, type Account } from "../lib/types.ts";
-import { c, count } from "./render.ts";
-
-/** True once `/login` has written a usable identity into the onboard dir. */
-function identityReady(cjPath: string): boolean {
-  if (!existsSync(cjPath)) return false;
-  try {
-    const oauthAccount = JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount;
-    return z.object({ accountUuid: z.string().min(1) }).safeParse(oauthAccount).success;
-  } catch {
-    return false;
-  }
-}
+import { writeItem, parkedTarget, claudeAiOauthOnly } from "../lib/credstore.ts";
+import { harvestIsolatedLogin } from "./onboard.ts";
+import { type Account } from "../lib/types.ts";
+import { c, claudeTierLabel, count } from "./render.ts";
 
 export async function cmdAdd(): Promise<number> {
-  const onboardDir = paths.onboardDir;
-  rmSync(onboardDir, { recursive: true, force: true });
-  mkdirSync(onboardDir, { recursive: true });
-  const iso = isolatedTarget(onboardDir);
-  const cjPath = join(onboardDir, ".claude.json");
-  const real = resolveRealClaude();
-
   console.log(c.cyan("Opening an isolated Claude login - your primary login is untouched."));
   console.log(c.dim(`In the session that opens, run  ${c.bold("/login")}  with the account to add. It closes itself once you're in.`));
   console.log();
 
-  const savedTermios = saveTermios();
-  // Scrub the ambient credential/identity overrides claude honors BEFORE its
-  // keychain lookup (verified 2.1.205) - the onboard session must authenticate
-  // only via the /login the user performs inside it.
-  const env: Record<string, string> = { ...process.env, CLAUDE_CONFIG_DIR: onboardDir, TOKENMAXXING_PROBE: "1", TOKENMAXXING_SUPERVISED: "" };
-  delete env.ANTHROPIC_API_KEY;
-  delete env.ANTHROPIC_AUTH_TOKEN;
-  delete env.CLAUDE_CODE_OAUTH_TOKEN;
-  delete env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
-  const p = Bun.spawn([real], {
-    stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-    env,
-  });
-
-  // Auto-exit (#17): watch for a completed login - identity written AND the
-  // isolated credential present - then SIGTERM claude. No manual /exit.
-  let exited = false;
-  const onExit = p.exited.then(() => { exited = true; });
-  while (!exited) {
-    await Bun.sleep(400);
-    if (identityReady(cjPath) && (await readItem(iso))) {
-      p.kill();
-      break;
-    }
-  }
-  await p.exited;
-  await onExit;
-  restoreTermios(savedTermios);
-
-  const cleanup = async () => {
-    await deleteItem(iso);
-    rmSync(onboardDir, { recursive: true, force: true });
-  };
-
-  const blobRaw = await readItem(iso);
-  if (!blobRaw || !identityReady(cjPath)) {
-    console.error(c.red("no login detected in the isolated session - nothing added."));
-    await cleanup();
-    return 1;
-  }
-
-  let blob, oauthAccount;
-  try {
-    blob = CredentialBlobSchema.parse(JSON.parse(blobRaw));
-    oauthAccount = OAuthAccountSchema.parse(JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount);
-  } catch {
-    console.error(c.red("could not parse the onboarded account's credential/identity."));
-    await cleanup();
-    return 1;
-  }
-
-  // Sample usage now (#16) so the account isn't "not sampled yet" in status/ls.
-  console.log(c.dim("sampling usage..."));
-  const sampled = await probeUsage(onboardDir);
-  if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+  const harvested = await harvestIsolatedLogin();
+  if (!harvested) return 1;
+  const { blobRaw, blob, oauthAccount, sampled } = harvested;
 
   const uuid = oauthAccount.accountUuid;
   const keychainItem = credItemFor(uuid);
-  await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw)); // park a small backup
 
-  // under the flock: a concurrent swap's index write must not be clobbered.
+  // under the flock: a concurrent swap both harvests into parked items and
+  // writes the index, so the backup write and the index upsert must land in
+  // one critical section.
   const { account, poolSize } = await withLock(paths.lockFile, async () => {
+    await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw)); // park a small backup
     const idx = loadAccounts();
     const existing = idx.accounts.find((a) => a.accountUuid === uuid);
     const fresh: Account = {
@@ -115,6 +38,7 @@ export async function cmdAdd(): Promise<number> {
       oauthAccount,
       addedAt: existing?.addedAt ?? new Date().toISOString(),
       subscriptionType: blob.claudeAiOauth.subscriptionType,
+      rateLimitTier: blob.claudeAiOauth.rateLimitTier,
       needsReauth: false,
       lastUsage: sampled ? { fiveHour: sampled.session, sevenDay: sampled.weekAll } : existing?.lastUsage,
       lastPerModel: sampled && Object.keys(sampled.perModel).length > 0 ? sampled.perModel : existing?.lastPerModel,
@@ -126,10 +50,8 @@ export async function cmdAdd(): Promise<number> {
     return { account: fresh, poolSize: idx.accounts.length };
   });
 
-  await cleanup();
-
   console.log();
   const usageNote = sampled ? ` (session ${sampled.session.usedPercentage}% / week ${sampled.weekAll.usedPercentage}%)` : "";
-  console.log(`${c.green("✓")} added ${c.bold(account.email)} (${account.subscriptionType ?? "?"})${usageNote} → pool now has ${count({ n: poolSize, noun: "account" })}`);
+  console.log(`${c.green("✓")} added ${c.bold(account.email)} (${claudeTierLabel(account) ?? "?"})${usageNote} → pool now has ${count({ n: poolSize, noun: "account" })}`);
   return 0;
 }

package/src/cli/auth.ts

@@ -0,0 +1,177 @@
+// `tokenmaxxing auth` - reauthenticate a pooled account in place. The dead
+// refresh token cannot heal itself (a needs-reauth account can never win a
+// swap), so this drives one isolated login per target and REQUIRES the login
+// to land on the target account: the harvested identity must match, otherwise
+// nothing changes. Bare `auth` lists the pool (emails shown) and asks which;
+// `auth <sel>` targets one account, stating the email to sign in with;
+// `auth --all` walks every needs-reauth account one by one.
+
+import { partition } from "es-toolkit";
+import { z } from "zod";
+import { withLock } from "../lib/lock.ts";
+import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { paths } from "../lib/paths.ts";
+import { writeItem, parkedTarget, claudeAiOauthOnly } from "../lib/credstore.ts";
+import { findAccount } from "./rename.ts";
+import { harvestIsolatedLogin } from "./onboard.ts";
+import { c, claudeTierLabel, count } from "./render.ts";
+import type { Account, AccountsIndex } from "../lib/types.ts";
+
+const AUTH_USAGE = "usage: tokenmaxxing auth [<email|label|id> | --all]";
+
+export const AuthPlanSchema = z.discriminatedUnion("kind", [
+  /** malformed argv: print AUTH_USAGE, exit 2. */
+  z.object({ kind: z.literal("usage") }),
+  /** unresolvable state (empty pool, unknown selector): exit 1. */
+  z.object({ kind: z.literal("error"), message: z.string() }),
+  /** bare `auth`: ask interactively. */
+  z.object({ kind: z.literal("pick") }),
+  z.object({ kind: z.literal("targets"), uuids: z.array(z.string()) }),
+]);
+export type AuthPlan = z.infer<typeof AuthPlanSchema>;
+
+/** Resolve argv into a reauth plan (pure - unit-tested). Argv shape is
+ *  validated before any pool state is consulted. */
+export function planAuth(input: { accounts: Account[]; argv: string[] }): AuthPlan {
+  const all = input.argv.includes("--all");
+  const rest = input.argv.filter((a) => a !== "--all");
+  if ((all && rest.length > 0) || rest.length > 1) return { kind: "usage" };
+  if (input.accounts.length === 0) return { kind: "error", message: "no accounts in the pool - run `tokenmaxxing init` first" };
+  if (all) {
+    const flagged = input.accounts.filter((a) => a.needsReauth === true);
+    return { kind: "targets", uuids: flagged.map((a) => a.accountUuid) };
+  }
+  const selector = rest[0];
+  if (selector !== undefined) {
+    const found = findAccount(input.accounts, selector);
+    if (!found) return { kind: "error", message: `no claude account matches "${selector}"` };
+    return { kind: "targets", uuids: [found.accountUuid] };
+  }
+  return { kind: "pick" };
+}
+
+/** Needs-reauth accounts first (they are why the user is here), pool order within. */
+export function pickerOrder(accounts: Account[]): Account[] {
+  const [flagged, healthy] = partition(accounts, (a) => a.needsReauth === true);
+  return [...flagged, ...healthy];
+}
+
+function askWhichAccount(idx: AccountsIndex): Account | null {
+  const ordered = pickerOrder(idx.accounts);
+  console.log("which account do you want to reauthenticate?");
+  for (const [i, a] of ordered.entries()) {
+    const flags: string[] = [];
+    if (a.accountUuid === idx.activeAccountUuid) flags.push(c.green("active"));
+    if (a.needsReauth) flags.push(c.red("needs-reauth"));
+    const labelNote = a.label && a.label !== a.email ? ` (${a.label})` : "";
+    const tag = flags.length ? ` ${flags.join(" ")}` : "";
+    console.log(`  ${i + 1}. ${c.bold(a.email)}${labelNote}${tag}`);
+  }
+  const answer = prompt("account (number, email, or label):")?.trim();
+  if (!answer) {
+    console.error(c.red("nothing selected"));
+    return null;
+  }
+  const n = Number(answer);
+  const byNumber = Number.isInteger(n) && n >= 1 && n <= ordered.length ? ordered[n - 1] : undefined;
+  const chosen = byNumber ?? findAccount(ordered, answer);
+  if (!chosen) {
+    console.error(c.red(`no account matches "${answer}"`));
+    return null;
+  }
+  return chosen;
+}
+
+async function reauthOne(target: Account): Promise<boolean> {
+  console.log(c.cyan(`Reauthenticating ${c.bold(target.label)} - sign in as  ${c.bold(target.email)}.`));
+  console.log(c.dim(`In the session that opens, run  ${c.bold("/login")}  with that account. It closes itself once you're in.`));
+  console.log();
+
+  const harvested = await harvestIsolatedLogin();
+  if (!harvested) return false;
+  const { blobRaw, blob, oauthAccount, sampled } = harvested;
+
+  if (oauthAccount.accountUuid !== target.accountUuid) {
+    console.error(
+      c.red(
+        `that login is ${c.bold(oauthAccount.emailAddress)}, but ${target.label} is ${c.bold(target.email)} - nothing changed. To pool it as its own account, run \`tokenmaxxing add\`.`,
+      ),
+    );
+    return false;
+  }
+
+  // under the flock: a concurrent swap both harvests into parked items and
+  // writes the index, so the credential write and the needsReauth clear must
+  // land in one critical section (else a swap-away harvest of the live blob
+  // could overwrite this fresh backup right before it is marked healthy).
+  const isActive = await withLock(paths.lockFile, async () => {
+    await writeItem(parkedTarget(target.keychainItem), claudeAiOauthOnly(blobRaw));
+    const idx = loadAccounts();
+    const account = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
+    if (account) {
+      account.email = oauthAccount.emailAddress;
+      account.organizationUuid = oauthAccount.organizationUuid;
+      account.oauthAccount = oauthAccount;
+      account.subscriptionType = blob.claudeAiOauth.subscriptionType;
+      account.rateLimitTier = blob.claudeAiOauth.rateLimitTier;
+      account.needsReauth = false;
+      if (sampled) {
+        account.lastUsage = { fiveHour: sampled.session, sevenDay: sampled.weekAll };
+        if (Object.keys(sampled.perModel).length > 0) account.lastPerModel = sampled.perModel;
+        account.lastUsageAt = Date.now();
+      }
+      saveAccounts(idx);
+    }
+    return idx.activeAccountUuid === target.accountUuid;
+  });
+
+  const usageNote = sampled ? ` (session ${sampled.session.usedPercentage}% / week ${sampled.weekAll.usedPercentage}%)` : "";
+  const tier = claudeTierLabel(blob.claudeAiOauth) ?? "?";
+  console.log(`${c.green("✓")} reauthed ${c.bold(oauthAccount.emailAddress)} (${tier})${usageNote}`);
+  if (isActive) {
+    console.log(c.dim("this account is the active one: the fresh credential is parked as its backup; the live session keeps its current token until the next swap."));
+  }
+  return true;
+}
+
+export async function cmdAuth(argv: string[]): Promise<number> {
+  const idx = loadAccounts();
+  const plan = planAuth({ accounts: idx.accounts, argv });
+  if (plan.kind === "usage") {
+    console.error(AUTH_USAGE);
+    return 2;
+  }
+  if (plan.kind === "error") {
+    console.error(c.red(plan.message));
+    return 1;
+  }
+
+  const targets: Account[] = [];
+  if (plan.kind === "pick") {
+    const picked = askWhichAccount(idx);
+    if (!picked) return 1;
+    targets.push(picked);
+  } else {
+    for (const uuid of plan.uuids) {
+      const account = idx.accounts.find((a) => a.accountUuid === uuid);
+      if (account) targets.push(account);
+    }
+    if (targets.length === 0) {
+      console.log(`${c.green("✓")} no account needs reauth`);
+      return 0;
+    }
+  }
+
+  let ok = 0;
+  for (const [i, target] of targets.entries()) {
+    console.log();
+    if (targets.length > 1) console.log(c.bold(`[${i + 1}/${targets.length}]`));
+    if (await reauthOne(target)) ok += 1;
+  }
+
+  if (targets.length > 1) {
+    console.log();
+    console.log(`reauthed ${count({ n: ok, noun: "account" })} of ${targets.length}`);
+  }
+  return ok === targets.length ? 0 : 1;
+}

package/src/cli/doctor.ts

@@ -60,17 +60,17 @@ export async function cmdDoctor(): Promise<number> {
 
   for (const a of idx.accounts) {
     const parked = await readItem(parkedTarget(a.keychainItem));
-    check(!!parked, `parked credential present for ${a.email}`, "re-run `tokenmaxxing init`/`add`");
+    check(!!parked, `parked credential present for ${a.email}`, `run \`tokenmaxxing auth ${a.label}\``);
     if (parked) {
       try {
         const org = await blobOrg(parked);
-        if (org) check(org.organization_uuid === a.organizationUuid, `parked credential identity matches ${a.email}`, `token belongs to ${org.organization_name} - re-auth with \`tokenmaxxing add\``);
+        if (org) check(org.organization_uuid === a.organizationUuid, `parked credential identity matches ${a.email}`, `token belongs to ${org.organization_name} - run \`tokenmaxxing auth ${a.label}\``);
         else console.log(c.dim(`  - ${a.email} identity unverifiable (access token expired)`));
       } catch (e) {
         check(false, `parked credential identity matches ${a.email}`, String((e as Error).message ?? e).slice(0, 100));
       }
     }
-    if (a.needsReauth) check(false, `${a.email} needs re-auth`, "run `tokenmaxxing add` to re-login");
+    if (a.needsReauth) check(false, `${a.email} needs re-auth`, `run \`tokenmaxxing auth ${a.label}\` to re-login`);
   }
 
   const cfg = loadConfig();

package/src/cli/init.ts

@@ -10,7 +10,7 @@ import { installSupervisor, shellRcPath, ensurePathInRc, timerActivationHint, ty
 import { resolveVerifiedClaude } from "../lib/claudebin.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, type Account } from "../lib/types.ts";
-import { c } from "./render.ts";
+import { c, claudeTierLabel } from "./render.ts";
 
 /** Put the supervisor bin dir on PATH via the user's shell rc (idempotent).
  *  Falls back to the manual instruction when the shell is unknown. */
@@ -121,6 +121,7 @@ export async function cmdInit(): Promise<number> {
     oauthAccount,
     addedAt: existing?.addedAt ?? new Date().toISOString(),
     subscriptionType: blob.claudeAiOauth.subscriptionType,
+    rateLimitTier: blob.claudeAiOauth.rateLimitTier,
     needsReauth: false,
   };
   if (existing) Object.assign(existing, account);
@@ -134,7 +135,7 @@ export async function cmdInit(): Promise<number> {
 
   const out = installSupervisor();
 
-  console.log(`${c.green("✓")} imported current account → ${c.bold(account.email)} (${account.subscriptionType ?? "?"})`);
+  console.log(`${c.green("✓")} imported current account → ${c.bold(account.email)} (${claudeTierLabel(account) ?? "?"})`);
   console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/SessionStart hooks`);
   reportTimer(out);
   if (!out.pathAhead) {

package/src/cli/ls.ts

@@ -3,7 +3,7 @@
 import { loadAccounts } from "../lib/state.ts";
 import { loadCodexAccounts } from "../lib/codexstate.ts";
 import { liveCodexAccountId } from "../lib/codexsample.ts";
-import { c } from "./render.ts";
+import { c, claudeTierLabel } from "./render.ts";
 
 export function cmdLs(): number {
   const idx = loadAccounts();
@@ -19,7 +19,7 @@ export function cmdLs(): number {
     const tag = flags.length ? ` ${flags.join(" ")}` : "";
     const label = a.label || a.email;
     console.log(`${marker} ${c.bold(label)}${tag}`);
-    console.log(`  ${c.dim(`org ${a.organizationUuid.slice(0, 8)}, ${a.subscriptionType ?? "?"}, uuid ${a.accountUuid.slice(0, 8)}`)}`);
+    console.log(`  ${c.dim(`org ${a.organizationUuid.slice(0, 8)}, ${claudeTierLabel(a) ?? "?"}, uuid ${a.accountUuid.slice(0, 8)}`)}`);
   }
 
   const codex = loadCodexAccounts();

package/src/cli/onboard.ts

@@ -0,0 +1,112 @@
+// One isolated Claude login, harvested. Shared by `add` (register whatever
+// account the login lands on) and `auth` (require it to match an existing
+// account). Drives the login in a throwaway CLAUDE_CONFIG_DIR - the ONLY use
+// of CLAUDE_CONFIG_DIR in the tool - auto-exits the moment the login lands,
+// samples that account's usage, then returns the credential + identity. The
+// temp dir and isolated credential are always destroyed before returning.
+
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { readItem, deleteItem, isolatedTarget } from "../lib/credstore.ts";
+import { resolveRealClaude } from "../lib/claudebin.ts";
+import { probeUsage, FullUsageSchema } from "../lib/usage.ts";
+import { saveTermios, restoreTermios } from "../lib/tty.ts";
+import { paths } from "../lib/paths.ts";
+import { CredentialBlobSchema, OAuthAccountSchema } from "../lib/types.ts";
+import { c } from "./render.ts";
+
+export const HarvestedLoginSchema = z.object({
+  /** the raw isolated credential blob (park it via claudeAiOauthOnly). */
+  blobRaw: z.string(),
+  blob: CredentialBlobSchema,
+  oauthAccount: OAuthAccountSchema,
+  sampled: FullUsageSchema.nullable(),
+});
+export type HarvestedLogin = z.infer<typeof HarvestedLoginSchema>;
+
+/** True once `/login` has written a usable identity into the onboard dir. */
+function identityReady(cjPath: string): boolean {
+  if (!existsSync(cjPath)) return false;
+  try {
+    const oauthAccount = JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount;
+    return z.object({ accountUuid: z.string().min(1) }).safeParse(oauthAccount).success;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Run one isolated login session and harvest it. The caller prints its own
+ * instructions (which account to sign in as) BEFORE calling. Prints progress
+ * and failure diagnostics; returns null when no usable login landed.
+ */
+export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
+  const onboardDir = paths.onboardDir;
+  rmSync(onboardDir, { recursive: true, force: true });
+  mkdirSync(onboardDir, { recursive: true });
+  const iso = isolatedTarget(onboardDir);
+  const cjPath = join(onboardDir, ".claude.json");
+  const real = resolveRealClaude();
+
+  const savedTermios = saveTermios();
+  // Scrub the ambient credential/identity overrides claude honors BEFORE its
+  // keychain lookup (verified 2.1.205) - the onboard session must authenticate
+  // only via the /login the user performs inside it.
+  const env: Record<string, string> = { ...process.env, CLAUDE_CONFIG_DIR: onboardDir, TOKENMAXXING_PROBE: "1", TOKENMAXXING_SUPERVISED: "" };
+  delete env.ANTHROPIC_API_KEY;
+  delete env.ANTHROPIC_AUTH_TOKEN;
+  delete env.CLAUDE_CODE_OAUTH_TOKEN;
+  delete env.CLAUDE_SECURESTORAGE_CONFIG_DIR;
+  const p = Bun.spawn([real], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env,
+  });
+
+  // Auto-exit (#17): watch for a completed login - identity written AND the
+  // isolated credential present - then SIGTERM claude. No manual /exit.
+  let exited = false;
+  const onExit = p.exited.then(() => { exited = true; });
+  while (!exited) {
+    await Bun.sleep(400);
+    if (identityReady(cjPath) && (await readItem(iso))) {
+      p.kill();
+      break;
+    }
+  }
+  await p.exited;
+  await onExit;
+  restoreTermios(savedTermios);
+
+  const cleanup = async () => {
+    await deleteItem(iso);
+    rmSync(onboardDir, { recursive: true, force: true });
+  };
+
+  const blobRaw = await readItem(iso);
+  if (!blobRaw || !identityReady(cjPath)) {
+    console.error(c.red("no login detected in the isolated session - nothing changed."));
+    await cleanup();
+    return null;
+  }
+
+  let blob, oauthAccount;
+  try {
+    blob = CredentialBlobSchema.parse(JSON.parse(blobRaw));
+    oauthAccount = OAuthAccountSchema.parse(JSON.parse(readFileSync(cjPath, "utf8")).oauthAccount);
+  } catch {
+    console.error(c.red("could not parse the onboarded account's credential/identity."));
+    await cleanup();
+    return null;
+  }
+
+  // Sample usage now (#16) so the account isn't "not sampled yet" in status/ls.
+  console.log(c.dim("sampling usage..."));
+  const sampled = await probeUsage(onboardDir);
+  if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+
+  await cleanup();
+  return { blobRaw, blob, oauthAccount, sampled };
+}

package/src/cli/rename.ts

@@ -1,12 +1,16 @@
-// `tokenmaxxing rename <selector> <new-label>` - relabel a pooled account.
+// `tokenmaxxing rename [--codex] <selector> <new-label>` - relabel a pooled
+// account. The pools are separate namespaces and one email can hold both a
+// claude and a codex account, so the codex pool is targeted explicitly via
+// `--codex` (mirroring `switch --codex`), never by searching both pools.
 
 import { withLock } from "../lib/lock.ts";
-import { paths } from "../lib/paths.ts";
+import { codexPaths, paths } from "../lib/paths.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
 import { c } from "./render.ts";
-import type { Account } from "../lib/types.ts";
+import type { Account, CodexAccount } from "../lib/types.ts";
 
-/** Resolve an account by email, label, or accountUuid prefix. */
+/** Resolve a claude account by email, label, or accountUuid prefix. */
 export function findAccount(accounts: Account[], selector: string): Account | undefined {
   const s = selector.toLowerCase();
   return (
@@ -16,17 +20,47 @@ export function findAccount(accounts: Account[], selector: string): Account | un
   );
 }
 
-export async function cmdRename(selector?: string, newLabel?: string): Promise<number> {
+/** Resolve a codex account by email, label, or accountId prefix. */
+export function findCodexAccount(accounts: CodexAccount[], selector: string): CodexAccount | undefined {
+  const s = selector.toLowerCase();
+  return (
+    accounts.find((a) => a.email?.toLowerCase() === s) ??
+    accounts.find((a) => a.label.toLowerCase() === s) ??
+    accounts.find((a) => a.accountId.toLowerCase().startsWith(s))
+  );
+}
+
+async function renameCodexAccount(input: { selector: string; newLabel: string }): Promise<number> {
+  // under the codex flock: a concurrent codex swap's index write must not be clobbered.
+  return withLock(codexPaths.lockFile, async () => {
+    const index = loadCodexAccounts();
+    const account = findCodexAccount(index.accounts, input.selector);
+    if (!account) {
+      console.error(c.red(`no codex account matches "${input.selector}"`));
+      return 1;
+    }
+    const old = account.label;
+    account.label = input.newLabel;
+    saveCodexAccounts({ index });
+    console.log(`renamed codex account ${c.dim(old)} → ${c.bold(input.newLabel)}`);
+    return 0;
+  });
+}
+
+export async function cmdRename(argv: string[]): Promise<number> {
+  const codex = argv.includes("--codex");
+  const [selector, newLabel] = argv.filter((a) => a !== "--codex");
   if (!selector || !newLabel) {
-    console.error("usage: tokenmaxxing rename <email|label|uuid> <new-label>");
+    console.error("usage: tokenmaxxing rename [--codex] <email|label|id> <new-label>");
     return 2;
   }
+  if (codex) return renameCodexAccount({ selector, newLabel });
   // under the flock: a concurrent swap's index write must not be clobbered.
   return withLock(paths.lockFile, async () => {
     const idx = loadAccounts();
     const a = findAccount(idx.accounts, selector);
     if (!a) {
-      console.error(c.red(`no account matches "${selector}"`));
+      console.error(c.red(`no claude account matches "${selector}" (codex accounts rename via --codex)`));
       return 1;
     }
     const old = a.label;

package/src/cli/render.ts

@@ -18,6 +18,19 @@ export function makeColors(enabled: boolean) {
 
 export const c = makeColors(!process.env.NO_COLOR && !!process.stdout.isTTY);
 
+/** Plan label for a claude account, e.g. "max 20x": subscription name plus the
+ *  multiplier segment of the rate-limit tier id ("default_claude_max_20x").
+ *  Structural, never exact-string: the multiplier is any <digits>x segment, so
+ *  tiers without one (e.g. "default_claude_zero") fall back to the bare
+ *  subscription name, and an absent blob field falls back to null (unmeasured
+ *  must not look like a tier). */
+export function claudeTierLabel(input: { subscriptionType?: string; rateLimitTier?: string }): string | null {
+  const segments = input.rateLimitTier?.split("_") ?? [];
+  const multiplier = segments.find((seg) => seg.length > 1 && seg.endsWith("x") && Number.isInteger(Number(seg.slice(0, -1))));
+  if (input.subscriptionType == null) return multiplier ?? null;
+  return multiplier ? `${input.subscriptionType} ${multiplier}` : input.subscriptionType;
+}
+
 /** "1 account" / "3 accounts": counted nouns always pluralize properly. */
 export function count(input: { n: number; noun: string }): string {
   return `${input.n} ${input.noun}${input.n === 1 ? "" : "s"}`;

package/src/cli/status.ts

@@ -21,8 +21,8 @@ import { effectiveBars, isExhausted, nextWeeklyReset } from "../lib/picker.ts";
 import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
 import { liveCodexAccountId, sampleCodexAccount, type CodexSampleOutcome } from "../lib/codexsample.ts";
 import { isCodexExhausted } from "../lib/codexpick.ts";
-import { isSessionWindow } from "../lib/codexusage.ts";
-import { bar, c, count, fmtAgo, fmtReset } from "./render.ts";
+import { codexLimitLabel, isSessionWindow } from "../lib/codexusage.ts";
+import { bar, c, claudeTierLabel, count, fmtAgo, fmtReset } from "./render.ts";
 import type { FullUsage } from "../lib/usage.ts";
 import type { Config, CodexWindow, UsageWindow } from "../lib/types.ts";
 
@@ -48,10 +48,15 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
     idx = loadAccounts();
     const live = loadUsage();
     const modelUsage = loadModelUsage();
-    const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+    const liveOAuth = readOAuthAccount();
+    const activeOrg = liveOAuth?.organizationUuid ?? null;
     await Promise.all(
       idx.accounts.map(async (a) => {
         const isActive = a.accountUuid === idx.activeAccountUuid && activeOrg === a.organizationUuid;
+        // The tee path never opens the credential blob, so the active account's
+        // tier comes from the live oauthAccount instead - it names this very org
+        // (uuid-matched above), so the tier is attributed to its own identity.
+        if (isActive && liveOAuth?.organizationRateLimitTier != null) a.rateLimitTier = liveOAuth.organizationRateLimitTier;
         // Active account: prefer the free statusLine push (usage.json) so we never
         // poll its own token, which is busy exactly when it matters. per-model
         // comes from model-usage.json (also statusLine-driven).
@@ -126,12 +131,15 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
     if (isExhausted(a, { now, thresholds: effectiveBars(cfg), currentAccountUuid: idx.activeAccountUuid, switchFamilies: cfg.policy.switchModels }))
       badges.push(c.yellow("exhausted"));
 
-    console.log(`${marker} ${c.bold(a.label || a.email)} ${badges.join(" ")}`);
+    const tier = claudeTierLabel(a);
+    console.log(`${marker} ${c.bold(a.label || a.email)}${tier ? ` ${c.dim(tier)}` : ""}${badges.length ? ` ${badges.join(" ")}` : ""}`);
+    // Chart label convention (user rule 2026-07-17): everything lowercase,
+    // model names short ("fable", "spark").
     if (aggregate) {
       row("5h", aggregate.fiveHour, false);
       row("week", aggregate.sevenDay, true);
     }
-    if (perModel) for (const [name, w] of Object.entries(perModel)) row(name, w, true);
+    if (perModel) for (const [name, w] of Object.entries(perModel)) row(name.toLowerCase(), w, true);
     if (failed && outcome && !outcome.ok) {
       const cached = aggregate || perModel ? `cached${a.lastUsageAt != null ? ` ${fmtAgo(a.lastUsageAt, now)}` : ""}, ` : "";
       console.log(`    ${c.yellow(`${cached}live sample failed`)}: ${c.dim(outcome.reason)}`);
@@ -199,13 +207,13 @@ async function renderCodexSection(input: {
     if (active) badges.push(c.green("active"));
     if (account.needsReauth) badges.push(c.red("needs-reauth"));
     if (isCodexExhausted({ account, thresholds: effectiveBars(cfg), now })) badges.push(c.yellow("exhausted"));
-    console.log(`${marker} ${c.bold(account.label)} ${account.planType ? c.dim(account.planType) : ""} ${badges.join(" ")}`);
+    console.log(`${marker} ${c.bold(account.label)}${account.planType ? ` ${c.dim(account.planType)}` : ""}${badges.length ? ` ${badges.join(" ")}` : ""}`);
 
     const usage = account.lastUsage;
     if (usage) {
       for (const window of usage.aggregate) row(windowLabel(window), window, !isSessionWindow({ window }));
       for (const [name, windows] of Object.entries(usage.perLimit)) {
-        for (const window of windows) row(name, window, !isSessionWindow({ window }));
+        for (const window of windows) row(codexLimitLabel({ limitName: name }), window, !isSessionWindow({ window }));
       }
     }
     const outcome = outcomes.get(account.accountId);

package/src/cli/switch.ts

@@ -43,7 +43,7 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       try {
         await performSwap(target);
       } catch (e) {
-        if (e instanceof InvalidGrantError) { console.error(c.red(`${target.label}'s refresh token is dead - re-add it`)); return 1; }
+        if (e instanceof InvalidGrantError) { console.error(c.red(`${target.label}'s refresh token is dead - run \`tokenmaxxing auth ${target.label}\``)); return 1; }
         throw e;
       }
       console.log(`${c.green("↻")} switched to ${c.bold(target.label)}`);
@@ -86,7 +86,7 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       // Either every account needs re-auth, or every account is blocked with no
       // recoverable bound (unparsed reset clocks AND no sample time - see log).
       const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
-      if (reauth.length > 0) { console.error(c.yellow(`no switchable account - re-auth needed: ${reauth.join(", ")}`)); return 1; }
+      if (reauth.length > 0) { console.error(c.yellow(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`)); return 1; }
       // never freeze a label drift behind a no-op (see header).
       if (drifted && active) return swapTo(active);
       console.log(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"));

package/src/lib/codexusage.ts

@@ -14,6 +14,7 @@ import { z } from "zod";
 import { http, safeErrorDetail } from "./http.ts";
 import { CodexUsageSchema, type CodexAuthJson, type CodexUsage, type CodexWindow } from "./types.ts";
 import { codexIdentityOf } from "./codexauth.ts";
+import { familyTokens } from "./usage.ts";
 
 const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
 const USAGE_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_USAGE_URL) ?? "https://chatgpt.com/backend-api/wham/usage";
@@ -114,6 +115,15 @@ export async function fetchCodexUsage(input: { auth: CodexAuthJson }): Promise<C
   });
 }
 
+/** Quota-chart label for an additional_rate_limits row: the model family,
+ *  lowercase ("GPT-5.3-Codex-Spark" -> "spark"). Wire names are versioned, so
+ *  the label is derived structurally (last non-numeric token), never by exact
+ *  string (user rule 2026-07-17: chart names are lowercase, e.g. "spark"). */
+export function codexLimitLabel(input: { limitName: string }): string {
+  const tokens = familyTokens(input.limitName).filter((t) => Number.isNaN(Number(t)));
+  return tokens.at(-1) ?? input.limitName.trim().toLowerCase();
+}
+
 const SESSION_WINDOW_MAX_S = 6 * 3600;
 
 /** A window's screening bar: short windows (5h-class) screen at the session

package/src/lib/sample.ts

@@ -49,6 +49,14 @@ async function identityMismatch(creds: OAuthCreds, account: Account): Promise<st
   return `credential actually belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)})`;
 }
 
+/** Stamp the blob's plan fields onto the account (caller persists). Runs only
+ *  after the identity check passed, so a drifted credential can never write
+ *  another account's tier. Absent blob fields keep the last-known values. */
+function refreshPlanFields(account: Account, creds: OAuthCreds): void {
+  if (creds.subscriptionType != null) account.subscriptionType = creds.subscriptionType;
+  if (creds.rateLimitTier != null) account.rateLimitTier = creds.rateLimitTier;
+}
+
 /**
  * Live-sample `account`'s `/usage` in isolation. On a dead refresh token or a
  * mislabeled credential it sets `account.needsReauth` in place (the caller
@@ -60,13 +68,13 @@ async function identityMismatch(creds: OAuthCreds, account: Account): Promise<st
 export async function probeParkedUsage(account: Account, opts: { ping?: boolean } = {}): Promise<SampleOutcome> {
   const backup = parkedTarget(account.keychainItem);
   const parkedRaw = await readItem(backup);
-  if (!parkedRaw) return { ok: false, reason: "no parked credential - re-add with `tokenmaxxing add`" };
+  if (!parkedRaw) return { ok: false, reason: "no parked credential - run `tokenmaxxing auth`" };
 
   let creds: OAuthCreds;
   try {
     creds = CredentialBlobSchema.parse(JSON.parse(parkedRaw)).claudeAiOauth;
   } catch (e) {
-    return { ok: false, reason: `parked credential unreadable (${String((e as Error).message ?? e).slice(0, 80)}) - re-add with \`tokenmaxxing add\`` };
+    return { ok: false, reason: `parked credential unreadable (${String((e as Error).message ?? e).slice(0, 80)}) - run \`tokenmaxxing auth\`` };
   }
 
   // Hand claude a token with comfortable headroom so it won't run its own refresh
@@ -89,6 +97,7 @@ export async function probeParkedUsage(account: Account, opts: { ping?: boolean
     account.needsReauth = true;
     return { ok: false, reason: `${mismatch} - this account's own credential is gone; re-auth with \`tokenmaxxing add\`` };
   }
+  refreshPlanFields(account, creds);
 
   const dir = join(paths.sampleDir, credItemFor(account.accountUuid));
   rmSync(dir, { recursive: true, force: true });
@@ -149,6 +158,7 @@ export async function probeActiveUsage(account: Account, opts: { ping?: boolean
 
   const mismatch = await identityMismatch(creds, account);
   if (mismatch) return { ok: false, reason: `live ${mismatch} - active label drifted; run \`tokenmaxxing switch\`` };
+  refreshPlanFields(account, creds);
 
   const pingError = opts.ping ? await pingSession() : null;
   const usage = await probeUsage();

package/src/lib/types.ts

@@ -36,6 +36,9 @@ export const OAuthAccountSchema = z.looseObject({
   seatTier: z.string().nullish(),
   billingType: z.string().nullish(),
   displayName: z.string().nullish(),
+  /** rate-limit tier id ("default_claude_max_20x"), same value the credential
+   *  blob carries; claude fills it in on profile fetch (live-verified 2.1.211). */
+  organizationRateLimitTier: z.string().nullish(),
 });
 export type OAuthAccount = z.infer<typeof OAuthAccountSchema>;
 
@@ -90,6 +93,10 @@ export const AccountSchema = z.object({
   lastUsageAt: z.number().optional(),
   needsReauth: z.boolean().optional(),
   subscriptionType: z.string().optional(),
+  /** the blob's rate-limit tier id (e.g. "default_claude_max_20x"): the only
+   *  field that distinguishes max 5x from max 20x (subscriptionType is just
+   *  "max" for both). Refreshed on every verified sample. */
+  rateLimitTier: z.string().optional(),
 });
 export type Account = z.infer<typeof AccountSchema>;
 

package/src/main.ts

@@ -10,6 +10,7 @@ import { runStopHook } from "./entries/stophook.ts";
 import { runSessionStart } from "./entries/sessionstart.ts";
 import { cmdInit } from "./cli/init.ts";
 import { cmdAdd } from "./cli/add.ts";
+import { cmdAuth } from "./cli/auth.ts";
 import { cmdCodexAdd } from "./cli/codexadd.ts";
 import { cmdCodexInit } from "./cli/codexinit.ts";
 import { cmdCodexSwitch } from "./cli/codexswitch.ts";
@@ -37,6 +38,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing init --codex")}  same for codex: import login, install codex supervisor + Stop hook (trust it via /hooks)
   ${c.cyan("tokenmaxxing add")}        register an additional account (isolated login)
   ${c.cyan("tokenmaxxing add --codex")}   register an additional codex account (isolated login)
+  ${c.cyan("tokenmaxxing auth")} [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every needs-reauth account, one by one)
   ${c.cyan("tokenmaxxing switch --codex")} [sel]  switch the codex pool (takes effect on next codex start)
   ${c.cyan("tokenmaxxing ls")}         list pooled accounts
   ${c.cyan("tokenmaxxing status")}     accounts with 5h / weekly / per-model usage bars
@@ -44,7 +46,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
-  ${c.cyan("tokenmaxxing rename")} <sel> <label>
+  ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} <sel>
   ${c.cyan("tokenmaxxing uninstall")}  remove supervisor + settings entries
 
@@ -80,12 +82,13 @@ async function main(): Promise<number> {
     case "config": return cmdConfig(args.slice(1));
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
+    case "auth": return cmdAuth(args.slice(1));
     case "ls": return cmdLs();
     case "status": return cmdStatus(args.includes("--force"));
     case "watch": return cmdWatch(args[1]);
     case "doctor": return cmdDoctor();
     case "rm": return cmdRm(args[1]);
-    case "rename": return cmdRename(args[1], args[2]);
+    case "rename": return cmdRename(args.slice(1));
     case "uninstall":
       uninstallSupervisor();
       console.log("removed supervisor wrapper + settings entries (accounts/credentials kept)");