tokenmaxxing 1.34.0 → 1.38.0

package/DESIGN.md

@@ -31,7 +31,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
 - Four `~/.claude/settings.json` entries (merged - other settings keys are preserved, but the `statusLine` slot is taken over): the tokenmaxxing `statusLine` renderer (native since 2026-07-11; it also tees usage), a `subagentStatusLine` (per-subagent rows in the agents panel), a `Stop` hook, a `SessionStart` hook.
 - **`~/.config/tokenmaxxing/`** - the single home for config and state:
   - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin pins, policy.*); defaults apply at read time, `xx config` prints the path and the effective values, and edits happen in an editor.
-  - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, label, lastUsage, needsReauth, ...}` (window resets and the per-model rows live inside lastUsage).
+  - `accounts.json` - non-secret index `{id, label, email, tier, windows, lastUsageAt, needsReauth, oauthAccount, ...}` (each cached window carries its name, duration, reset, and sample time; the same shape serves the Codex pool as `codex-accounts.json`).
   - `usage.json` - live usage, written by the statusLine shim.
   - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal, depleted-pool waits only).
   - `bin/claude` - the supervisor.
@@ -60,7 +60,7 @@ The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed
 1. **Harvest the live credential into its TRUE owner's backup** - read the current `Claude Code-credentials` blob and resolve which account it actually belongs to via the profile endpoint (`GET /api/oauth/profile`, matched on `account.uuid`), NOT the `accounts.json` active label and NOT the organization (team seats share one). The label drifts from the live blob (a kill mid-swap, a manual `/login`), and harvesting by label once overwrote another account's backup and destroyed its only credential. Mandatory anyway: Claude rotates the refresh token in place, so older backups are dead. Refuse the swap if the live credential belongs to no pooled account.
 2. **Refresh B** - a blob Claude Code dead-cleared (empty tokens) is dead without a request. Resolve the owner of B's parked token through the profile endpoint first; a token that belongs to another account is never refreshed, because a refresh rotation revokes that account's live sessions, and B is marked `needs_reauth` instead. Then OAuth refresh-grant with B's parked refresh token → fresh access token; persist the rotated refresh token. On `invalid_grant`, mark B `needs_reauth`, notify, try the next account. On any other 4xx, skip B for this evaluation without marking it and try the next account.
 3. **Install B** - `security add-generic-password -U ... 'Claude Code-credentials' ...` with B's fresh (non-expired) `claudeAiOauth` JSON.
-4. **Swap identity + mark B active** - atomically rewrite only the `oauthAccount` object in `~/.claude.json` (temp+rename) to B's, and write `activeAccountUuid = B` in the SAME critical section, so a crash can't leave the installed credential and the active label pointing at different accounts.
+4. **Swap identity + mark B active** - atomically rewrite only the `oauthAccount` object in `~/.claude.json` (temp+rename) to B's, and write `activeId = B` in the SAME critical section, so a crash can't leave the installed credential and the active label pointing at different accounts.
 5. Do steps 1, 3, 4 inside Claude's own refresh locks - the primary `<credDir>/.oauth_refresh.lock` plus the legacy sibling `<realpath(credDir)>.lock` (`~/.claude.lock` by default), both mkdir-based proper-lockfile locks, binary-verified against 2.1.214 - so the writes can't collide with a token refresh. Contention fails the swap fast (claude itself gives up with `lock_timeout` rather than refreshing unlocked); the next check retries.
 
 ### 3.5 Multiple concurrent sessions
@@ -111,9 +111,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 
 **Removed (1.23.0):** the programmatic SDK surface, the stdio MCP server, and the Agent Plugin that shipped from 0.11.0 through 1.22.0. The CLI, the hooks, and the supervisor are the only surfaces.
 
-**Later:** tool-agnostic picker.
-
-**Shipped since (0.13.0):** Codex as a second pool, parallel state (`codex-accounts.json`, `codex-creds/`, own flock), same pace-pressure policy. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`). Sibling sessions left on ANY non-live account are reconciled cross-session (owner decisions 2026-07-20; a non-live session cannot refresh cross-account and would wedge at token expiry, healthy or not): the deciding actor drops a reconcile marker addressed to the sibling's supervisor, and the sibling's own Stop hook promotes it into a respawn onto the live account at its next turn boundary - the only safe respawn point - while a blocked live seat never receives a signal.
+**Shipped since (0.13.0):** Codex as a second pool with its own state (`codex-accounts.json`, `codex-creds/`, own flock). Since 1.35.0 the engine is one: a generic account record (`id`, `label`, `email`, `tier`, `windows`), one picker, one decision, and one set of account commands run against a `Provider` (`src/lib/provider.ts`); `src/lib/claude.ts` and `src/lib/codex.ts` hold only what differs per product (credential store, identity, usage source, presence, login and install flows). Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`). Sibling sessions left on ANY non-live account are reconciled cross-session (owner decisions 2026-07-20; a non-live session cannot refresh cross-account and would wedge at token expiry, healthy or not): the deciding actor drops a reconcile marker addressed to the sibling's supervisor, and the sibling's own Stop hook promotes it into a respawn onto the live account at its next turn boundary - the only safe respawn point - while a blocked live seat never receives a signal.
 
 **Shipped since (1.29.0):** a Cursor Cloud relay. A cloud VM has no keychain, no pool state, and no hot swap, so the path uses what it does have (environment variables, a shell, repo files) and a different credential primitive, one-year inference-only setup tokens, minted once per pooled account by `tokenmaxxing setup-token` on the owner's machine and carried to the VM as one user-scoped Runtime Secret (`TOKENMAXXING_TOKENS`). `tokenmaxxing cursor init` writes a `claude` project subagent (`.cursor/agents/claude.md`) that forwards each task to `tokenmaxxing cloud run`, which spawns `claude -p --dangerously-skip-permissions --output-format json` under `CLAUDE_CODE_OAUTH_TOKEN` and pins the thread to that token (the API caches by exact prefix, so a rotation busts one thread, not all). A setup token carries no usage signal, so rotation is reactive. A run whose transcript gained a non-transient rate-limit row during that run (the structured row the StopFailure hook reads) walls the label until the reset the row names (five hours without one) and resumes the same session on the next token; the result's `api_error_status` alone never walls, so a transient 429 or an older row from a previous token does not cascade across the pool. The local switching engine never reads a setup token; `/usage` prints no percentages under one. Details in [Cursor Cloud](docs/content/docs/cursor-cloud.mdx).
 

package/README.md

@@ -65,7 +65,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 auth [--codex] [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; `--codex` does the same for the codex pool |
 | `tokenmaxxing switch [sel]` | switch the claude pool: bare picks the best account (no-op when the current one wins), a selector targets one |
 | `tokenmaxxing switch --codex [sel]` | switch the codex pool (takes effect on the next codex start) |
 | `tokenmaxxing status [--cached]` | accounts with 5h / weekly usage bars, active + exhausted-until-reset; `--cached` renders the stored figures without sampling |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.34.0",
+  "version": "1.38.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,51 +1,34 @@
 import { withLock } from "../lib/lock.ts";
-import { loadAccounts, saveAccounts } from "../lib/state.ts";
-import { credItemFor, paths } from "../lib/paths.ts";
-import { writeItem, parkedTarget, claudeAiOauthOnly } from "../lib/credstore.ts";
-import { harvestIsolatedLogin } from "./onboard.ts";
-import { type Account } from "../lib/types.ts";
-import { keepRows } from "../lib/usage.ts";
-import { c, claudeTierLabel, count } from "./render.ts";
+import type { Provider } from "../lib/provider.ts";
+import { loadAccounts, saveAccounts, upsertAccount } from "../lib/state.ts";
+import { sessionWindow, weeklyWindow } from "../lib/picker.ts";
+import { c, count } from "./render.ts";
+import type { Account } from "../lib/types.ts";
 
-export async function cmdAdd(): Promise<number> {
-  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.`));
+export function usageNote(account: Account): string {
+  const session = sessionWindow(account);
+  const week = weeklyWindow(account);
+  return session && week ? ` (session ${session.usedPercentage}% / week ${week.usedPercentage}%)` : "";
+}
+
+export async function cmdAdd(p: Provider): Promise<number> {
+  console.log(c.cyan(`Opening an isolated ${p.name} login - your primary login is untouched.`));
+  console.log(c.dim(p.loginStep("the account to add")));
   console.log();
 
-  const harvested = await harvestIsolatedLogin();
+  const harvested = await p.login();
   if (!harvested) return 1;
-  const { blobRaw, blob, oauthAccount, sampled } = harvested;
-
-  const uuid = oauthAccount.accountUuid;
-  const keychainItem = credItemFor(uuid);
 
-  const { account, poolSize } = await withLock(paths.lockFile, async () => {
-    await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw));
-    const idx = loadAccounts();
-    const existing = idx.accounts.find((a) => a.accountUuid === uuid);
-    const sampledAt = Date.now();
-    const fresh: Account = {
-      accountUuid: uuid,
-      email: oauthAccount.emailAddress,
-      organizationUuid: oauthAccount.organizationUuid,
-      label: existing?.label ?? oauthAccount.emailAddress,
-      keychainItem,
-      oauthAccount,
-      addedAt: existing?.addedAt ?? new Date().toISOString(),
-      subscriptionType: blob.claudeAiOauth.subscriptionType,
-      rateLimitTier: blob.claudeAiOauth.rateLimitTier,
-      needsReauth: false,
-      lastUsage: sampled ? keepRows(sampled, existing?.lastUsage, sampledAt) : existing?.lastUsage,
-      lastUsageAt: sampled ? sampledAt : existing?.lastUsageAt,
-    };
-    if (existing) Object.assign(existing, fresh);
-    else idx.accounts.push(fresh);
-    saveAccounts(idx);
-    return { account: fresh, poolSize: idx.accounts.length };
+  const { account, poolSize } = await withLock(p.pool.lockFile, async () => {
+    await harvested.park();
+    const idx = loadAccounts(p.pool);
+    const account = upsertAccount(idx, harvested, p.mergeWindows);
+    saveAccounts(p.pool, idx);
+    return { account, poolSize: idx.accounts.length };
   });
 
   console.log();
-  const usageNote = sampled ? ` (session ${sampled.fiveHour.usedPercentage}% / week ${sampled.sevenDay.usedPercentage}%)` : "";
-  console.log(`${c.green("✓")} added ${c.bold(account.email)} (${claudeTierLabel(account) ?? "?"})${usageNote} → pool now has ${count({ n: poolSize, noun: "account" })}`);
+  const note = harvested.sample ? usageNote(account) : "";
+  console.log(`${c.green("✓")} added ${c.bold(account.label)} (${account.tier ?? "?"})${note} → pool now has ${count({ n: poolSize, noun: "account" })}`);
   return 0;
 }

package/src/cli/auth.ts

@@ -1,39 +1,37 @@
 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 type { Provider } from "../lib/provider.ts";
+import { loadAccounts, saveAccounts, upsertAccount } from "../lib/state.ts";
 import { findAccount } from "./rename.ts";
-import { harvestIsolatedLogin } from "./onboard.ts";
-import { keepRows } from "../lib/usage.ts";
-import { c, claudeTierLabel, count } from "./render.ts";
+import { usageNote } from "./add.ts";
+import { c, count } from "./render.ts";
 import type { Account, AccountsIndex } from "../lib/types.ts";
 
-const AUTH_USAGE = "usage: tokenmaxxing auth [<email|label|id> | --all]";
+const AUTH_USAGE = "usage: tokenmaxxing auth [--codex] [<email|label|id> | --all]";
 
 const AuthPlanSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("usage") }),
   z.object({ kind: z.literal("error"), message: z.string() }),
   z.object({ kind: z.literal("pick") }),
-  z.object({ kind: z.literal("targets"), uuids: z.array(z.string()) }),
+  z.object({ kind: z.literal("targets"), ids: z.array(z.string()) }),
 ]);
 export type AuthPlan = z.infer<typeof AuthPlanSchema>;
 
-export function planAuth(input: { accounts: Account[]; argv: string[] }): AuthPlan {
+export function planAuth(input: { p: Provider; 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 (input.accounts.length === 0) return { kind: "error", message: `no accounts in the pool - run \`tokenmaxxing init${input.p.flag}\` first` };
   if (all) {
     const flagged = input.accounts.filter((a) => a.needsReauth === true);
-    return { kind: "targets", uuids: flagged.map((a) => a.accountUuid) };
+    return { kind: "targets", ids: flagged.map((a) => a.id) };
   }
   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] };
+    if (!found) return { kind: "error", message: `no ${input.p.name} account matches "${selector}"` };
+    return { kind: "targets", ids: [found.id] };
   }
   return { kind: "pick" };
 }
@@ -48,11 +46,11 @@ function askWhichAccount(idx: AccountsIndex): Account | null {
   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.id === idx.activeId) 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 labelNote = a.email != null && a.label !== a.email ? ` (${a.label})` : "";
     const tag = flags.length ? ` ${flags.join(" ")}` : "";
-    console.log(`  ${i + 1}. ${c.bold(a.email)}${labelNote}${tag}`);
+    console.log(`  ${i + 1}. ${c.bold(a.email ?? a.label)}${labelNote}${tag}`);
   }
   const answer = prompt("account (number, email, or label):")?.trim();
   if (!answer) {
@@ -69,59 +67,47 @@ function askWhichAccount(idx: AccountsIndex): Account | 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.`));
+async function reauthOne(p: Provider, target: Account): Promise<boolean> {
+  console.log(c.cyan(`Reauthenticating ${c.bold(target.label)} - sign in as  ${c.bold(target.email ?? target.label)}.`));
+  console.log(c.dim(p.loginStep("that account")));
   console.log();
 
-  const harvested = await harvestIsolatedLogin();
+  const harvested = await p.login();
   if (!harvested) return false;
-  const { blobRaw, blob, oauthAccount, sampled } = harvested;
 
-  if (oauthAccount.accountUuid !== target.accountUuid) {
+  if (harvested.id !== target.id) {
     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\`.`,
+        `that login is ${c.bold(harvested.email ?? harvested.id.slice(0, 8))}, but ${target.label} is ${c.bold(target.email ?? target.id.slice(0, 8))} - nothing changed. To pool it as its own account, run \`tokenmaxxing add${p.flag}\`.`,
       ),
     );
     return false;
   }
 
-  const isActive = await withLock(paths.lockFile, async () => {
-    const idx = loadAccounts();
-    const account = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
-    if (!account) {
-      console.error(c.red(`${target.label} was removed from the pool while the login was open - nothing written; re-add it with \`tokenmaxxing add\` if wanted`));
+  const result = await withLock(p.pool.lockFile, async () => {
+    const idx = loadAccounts(p.pool);
+    if (!idx.accounts.some((a) => a.id === target.id)) {
+      console.error(c.red(`${target.label} was removed from the pool while the login was open - nothing written; re-add it with \`tokenmaxxing add${p.flag}\` if wanted`));
       return null;
     }
-    await writeItem(parkedTarget(target.keychainItem), claudeAiOauthOnly(blobRaw));
-    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.lastUsageAt = Date.now();
-      account.lastUsage = keepRows(sampled, account.lastUsage, account.lastUsageAt);
-    }
-    saveAccounts(idx);
-    return idx.activeAccountUuid === target.accountUuid;
+    await harvested.park();
+    const account = upsertAccount(idx, harvested, p.mergeWindows);
+    saveAccounts(p.pool, idx);
+    return { account, isActive: idx.activeId === target.id };
   });
-  if (isActive === null) return false;
+  if (result === null) return false;
 
-  const usageNote = sampled ? ` (session ${sampled.fiveHour.usedPercentage}% / week ${sampled.sevenDay.usedPercentage}%)` : "";
-  const tier = claudeTierLabel(blob.claudeAiOauth) ?? "?";
-  console.log(`${c.green("✓")} reauthed ${c.bold(oauthAccount.emailAddress)} (${tier})${usageNote}`);
-  if (isActive) {
+  const note = harvested.sample ? usageNote(result.account) : "";
+  console.log(`${c.green("✓")} reauthed ${c.bold(result.account.email ?? result.account.label)} (${result.account.tier ?? "?"})${note}`);
+  if (result.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 });
+export async function cmdAuth(p: Provider, argv: string[]): Promise<number> {
+  const idx = loadAccounts(p.pool);
+  const plan = planAuth({ p, accounts: idx.accounts, argv });
   if (plan.kind === "usage") {
     console.error(AUTH_USAGE);
     return 2;
@@ -137,8 +123,8 @@ export async function cmdAuth(argv: string[]): Promise<number> {
     if (!picked) return 1;
     targets.push(picked);
   } else {
-    for (const uuid of plan.uuids) {
-      const account = idx.accounts.find((a) => a.accountUuid === uuid);
+    for (const id of plan.ids) {
+      const account = idx.accounts.find((a) => a.id === id);
       if (account) targets.push(account);
     }
     if (targets.length === 0) {
@@ -151,7 +137,7 @@ export async function cmdAuth(argv: string[]): Promise<number> {
   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 (await reauthOne(p, target)) ok += 1;
   }
 
   if (targets.length > 1) {

package/src/cli/check.ts

@@ -1,3 +1,4 @@
+import { claude } from "../lib/claude.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { sampleOldestParked } from "../lib/sample.ts";
 import { loadConfig } from "../lib/state.ts";
@@ -8,7 +9,7 @@ export async function cmdCheck(json = false): Promise<number> {
   const now = Date.now();
   let d;
   try {
-    d = await evaluateAndMaybeSwap(now);
+    d = await evaluateAndMaybeSwap(claude, now);
     await sampleOldestParked(loadConfig());
   } catch (e) {
     const detail = e instanceof Error ? e.message : String(e);

package/src/cli/doctor.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { verifyRealClaude } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
 import { checkTimerHealthy, findClaudeShadowers, isBinDirAhead, shellRcPath, timerActivationHint } from "../lib/install.ts";
-import { paths } from "../lib/paths.ts";
+import { claudePool, credItemFor, paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { readItem, liveTarget, parkedTarget } from "../lib/credstore.ts";
 import { isAccessTokenExpiring, fetchTokenIdentity, describeIdentity } from "../lib/oauth.ts";
@@ -37,43 +37,43 @@ export async function cmdDoctor(): Promise<number> {
   check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
   check(checkTimerHealthy(), "periodic check timer active", timerActivationHint());
 
-  const idx = loadAccounts();
+  const idx = loadAccounts(claudePool);
   check(idx.accounts.length > 0, "at least one account in the pool", "run `tokenmaxxing init`");
-  check(!!idx.activeAccountUuid, "an active account is set");
+  check(!!idx.activeId, "an active account is set");
 
   const live = await readItem(liveTarget());
   check(!!live, "live credential readable");
 
-  const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid);
+  const active = idx.accounts.find((a) => a.id === idx.activeId);
   if (live && active) {
     try {
       const identity = await blobIdentity(live);
-      if (identity) check(identity.accountUuid === active.accountUuid, `live credential identity matches active (${active.email})`, `token belongs to ${describeIdentity(identity)} - run \`tokenmaxxing switch\``);
+      if (identity) check(identity.accountUuid === active.id, `live credential identity matches active (${active.label})`, `token belongs to ${describeIdentity(identity)} - run \`tokenmaxxing switch\``);
       else note("live credential identity unverifiable (access token expired)");
     } catch (e) {
-      check(false, `live credential identity matches active (${active.email})`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
+      check(false, `live credential identity matches active (${active.label})`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
     }
   }
 
   for (const a of idx.accounts) {
-    const parked = await readItem(parkedTarget(a.keychainItem));
-    check(!!parked, `parked credential present for ${a.email}`, `run \`tokenmaxxing auth ${a.label}\``);
+    const parked = await readItem(parkedTarget(credItemFor(a.id)));
+    check(!!parked, `parked credential present for ${a.label}`, `run \`tokenmaxxing auth ${a.label}\``);
     if (parked) {
       try {
         const identity = await blobIdentity(parked);
-        if (identity) check(identity.accountUuid === a.accountUuid, `parked credential identity matches ${a.email}`, `token belongs to ${describeIdentity(identity)} - run \`tokenmaxxing auth ${a.label}\``);
-        else note(`${a.email} identity unverifiable (access token expired)`);
+        if (identity) check(identity.accountUuid === a.id, `parked credential identity matches ${a.label}`, `token belongs to ${describeIdentity(identity)} - run \`tokenmaxxing auth ${a.label}\``);
+        else note(`${a.label} identity unverifiable (access token expired)`);
       } catch (e) {
-        check(false, `parked credential identity matches ${a.email}`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
+        check(false, `parked credential identity matches ${a.label}`, (e instanceof Error ? e.message : String(e)).slice(0, 100));
       }
     }
-    if (a.needsReauth) check(false, `${a.email} needs re-auth`, `run \`tokenmaxxing auth ${a.label}\` to re-login`);
+    if (a.needsReauth) check(false, `${a.label} needs re-auth`, `run \`tokenmaxxing auth ${a.label}\` to re-login`);
   }
 
   if (existsSync(paths.setupTokensJson)) {
     const setupTokens = loadSetupTokens().tokens;
     for (const a of idx.accounts) {
-      const token = setupTokens.find((t) => t.accountUuid === a.accountUuid);
+      const token = setupTokens.find((t) => t.accountUuid === a.id);
       if (!token) warn(`no setup token stored for ${a.label} - run \`tokenmaxxing setup-token\` to mint one for Cursor Cloud`);
       else if (Date.now() - token.mintedAt > SETUP_TOKEN_STALE_MS) warn(`the setup token for ${a.label} was minted ${fmtAgo(token.mintedAt)} and expires a year after minting - \`tokenmaxxing setup-token rm ${a.label}\` then \`tokenmaxxing setup-token\` re-mints it`);
     }

package/src/cli/init.ts

@@ -1,149 +1,52 @@
 import { mkdirSync } from "node:fs";
-import { isApiKeyMode, readOAuthAccount } from "../lib/claudejson.ts";
-import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "../lib/credstore.ts";
-import { refreshCredential, isAccessTokenExpiring, isDeadCredential, fetchTokenIdentity, describeIdentity } from "../lib/oauth.ts";
-import { withClaudeRefreshLock } from "../lib/claudelock.ts";
-import { loadAccounts, saveAccounts, loadConfig, pinBinOverride } from "../lib/state.ts";
 import { withLock } from "../lib/lock.ts";
-import { installSupervisor, shellRcPath, ensurePathInRc, managedShellRcSkipLines, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
-import { resolveVerifiedClaude } from "../lib/claudebin.ts";
-import { credItemFor, paths } from "../lib/paths.ts";
-import { CredentialBlobSchema, type Account } from "../lib/types.ts";
-import { c, claudeTierLabel } from "./render.ts";
+import { paths } from "../lib/paths.ts";
+import type { Provider } from "../lib/provider.ts";
+import { loadAccounts, loadConfig, saveAccounts, upsertAccount } from "../lib/state.ts";
+import { c, count } from "./render.ts";
 
-function ensurePathAhead(): void {
-  const rc = shellRcPath();
-  if (!rc) {
-    console.log(c.yellow(`⚠ add to your shell rc: export PATH="${paths.binDir}:$PATH"`));
-    return;
-  }
-  const outcome = ensurePathInRc(rc);
-  if (outcome === "added") console.log(`${c.green("✓")} added ${paths.binDir} to PATH in ${rc} - restart your shell (or \`source ${rc}\`)`);
-  else if (outcome === "skipped") {
-    const hint = managedShellRcSkipLines();
-    console.log(c.yellow(`⚠ ${hint.headline}`));
-    console.log(c.yellow(`  ${hint.detail}`));
-    console.log(c.yellow(`  ${hint.exportLine}`));
-  } else console.log(c.yellow(`⚠ PATH line already in ${rc} - restart your shell to pick it up`));
-}
-
-function reportTimer(out: InstallOutcome): void {
-  if (out.timerLoaded) console.log(`${c.green("✓")} periodic check timer active (every ${out.checkIntervalS}s)`);
-  else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
-}
-
-export function printUsage(): void {
+export function printUsage(p: Provider): void {
   console.log();
   console.log(`  ${c.bold("how to use")} - ${c.cyan("xx")} is shorthand for ${c.cyan("tokenmaxxing")}:`);
-  console.log(`    ${c.cyan("claude")}             use claude as always; it switches accounts near quota automatically`);
+  console.log(`    ${c.cyan(p.name)}             use ${p.name} as always; it switches accounts near quota automatically`);
   console.log(`    ${c.cyan("xx")}                 show the pool with usage bars (same as ${c.cyan("xx status")})`);
-  console.log(`    ${c.cyan("xx add")}             log in and pool another account`);
-  console.log(`    ${c.cyan("xx switch")}          hop to the best account right now (the automatic switching needs no command)`);
+  console.log(`    ${c.cyan(`xx add${p.flag}`)}             log in and pool another account`);
+  console.log(`    ${c.cyan(`xx switch${p.flag}`)}          hop to the best account right now (the automatic switching needs no command)`);
   console.log(`    ${c.cyan("xx help")}            everything else`);
 }
 
-export async function cmdInit(): Promise<number> {
+export async function cmdInit(p: Provider): Promise<number> {
   mkdirSync(paths.home, { recursive: true });
   loadConfig();
+  p.preflight();
 
-  const existingIdx = loadAccounts();
-  if (existingIdx.accounts.length > 0) {
-    const out = installSupervisor();
-    pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() });
-    const active = existingIdx.accounts.find((a) => a.accountUuid === existingIdx.activeAccountUuid);
-    console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
-    reportTimer(out);
-    if (!out.pathAhead) ensurePathAhead();
+  const existing = loadAccounts(p.pool);
+  if (existing.accounts.length > 0) {
+    p.install();
+    const active = existing.accounts.find((a) => a.id === existing.activeId);
+    console.log(`${c.green("✓")} re-installed (pool already has ${count({ n: existing.accounts.length, noun: "account" })} - not re-importing)`);
     console.log(`  active: ${c.bold(active?.label ?? "unknown")}`);
-    printUsage();
+    printUsage(p);
     return 0;
   }
 
-  if (isApiKeyMode()) {
-    console.error(c.yellow("tokenmaxxing pools subscription accounts, but you're authed via API key / apiKeyHelper."));
-    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} with a Pro/Max account first, then re-run ${c.cyan("tokenmaxxing init")}.`);
-    return 1;
-  }
-
-  const oauthAccount = readOAuthAccount();
-  const liveRaw = await readItem(liveTarget());
-  if (!oauthAccount || !liveRaw) {
-    console.error(c.red("no active Claude subscription login found (missing oauthAccount or credential)."));
-    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} first, then re-run ${c.cyan("tokenmaxxing init")}.`);
-    return 1;
-  }
+  const harvested = await p.importLive();
+  if (!harvested) return 1;
 
-  let blob;
-  try {
-    blob = CredentialBlobSchema.parse(JSON.parse(liveRaw));
-  } catch {
-    console.error(c.red("the live credential is not a recognizable Claude OAuth blob."));
-    return 1;
-  }
-
-  let creds = blob.claudeAiOauth;
-  if (isDeadCredential(creds)) {
-    console.error(c.red("the live credential was cleared after a failed refresh."));
-    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} first, then re-run ${c.cyan("tokenmaxxing init")}.`);
-    return 1;
-  }
-  if (isAccessTokenExpiring(creds)) {
-    await withClaudeRefreshLock(async (lock) => {
-      const raw2 = await readItem(liveTarget());
-      if (raw2 == null) throw new Error("live credential vanished while waiting for the refresh lock");
-      const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
-      creds = isAccessTokenExpiring(current) ? await refreshCredential(current) : current;
-      if (creds === current) return;
-      if (lock.compromised()) throw new Error("refresh lock compromised mid-refresh - discarding the live rewrite");
-      await writeItem(liveTarget(), mergeIntoLive(raw2, creds));
-    });
-  }
-  const identity = await fetchTokenIdentity(creds.accessToken);
-  if (identity.accountUuid !== oauthAccount.accountUuid) {
-    console.error(c.red(`the live credential belongs to ${describeIdentity(identity)}, but ~/.claude.json identifies ${oauthAccount.emailAddress} - identity drift.`));
-    console.error(`Run ${c.cyan("claude")} → ${c.cyan("/login")} to realign them, then re-run ${c.cyan("tokenmaxxing init")}.`);
-    return 1;
-  }
-
-  const uuid = oauthAccount.accountUuid;
-  const keychainItem = credItemFor(uuid);
-  const account = await withLock(paths.lockFile, async () => {
-    await writeItem(parkedTarget(keychainItem), JSON.stringify({ claudeAiOauth: creds }));
-    const idx = loadAccounts();
-    const existing = idx.accounts.find((a) => a.accountUuid === uuid);
-    const imported: Account = {
-      accountUuid: uuid,
-      email: oauthAccount.emailAddress,
-      organizationUuid: oauthAccount.organizationUuid,
-      label: existing?.label ?? oauthAccount.emailAddress,
-      keychainItem,
-      oauthAccount,
-      addedAt: existing?.addedAt ?? new Date().toISOString(),
-      subscriptionType: blob.claudeAiOauth.subscriptionType,
-      rateLimitTier: blob.claudeAiOauth.rateLimitTier,
-      needsReauth: false,
-    };
-    if (existing) Object.assign(existing, imported);
-    else idx.accounts.push(imported);
-    idx.activeAccountUuid = uuid;
-    saveAccounts(idx);
+  const account = await withLock(p.pool.lockFile, async () => {
+    await harvested.park();
+    const idx = loadAccounts(p.pool);
+    const imported = upsertAccount(idx, harvested, p.mergeWindows);
+    idx.activeId = harvested.id;
+    saveAccounts(p.pool, idx);
     return imported;
   });
 
-  pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() });
-
-  const out = installSupervisor();
-
-  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) {
-    console.log();
-    ensurePathAhead();
-  }
-  const poolSize = loadAccounts().accounts.length;
+  console.log(`${c.green("✓")} imported current account → ${c.bold(account.label)} (${account.tier ?? "?"})`);
+  p.install();
+  const poolSize = loadAccounts(p.pool).accounts.length;
   console.log();
-  console.log(`  pool ready (${poolSize} account${poolSize === 1 ? "" : "s"})`);
-  printUsage();
+  console.log(`  pool ready (${count({ n: poolSize, noun: "account" })})`);
+  printUsage(p);
   return 0;
 }