tokenmaxxing 1.33.0 → 1.35.0

package/src/entries/codexstophook.ts

@@ -1,18 +1,17 @@
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { z } from "zod";
-import { codexPaths } from "../lib/paths.ts";
+import { codexPaths, codexPool } from "../lib/paths.ts";
 import { withLock } from "../lib/lock.ts";
 import { writeFileAtomic } from "../lib/atomic.ts";
-import { evaluateAndMaybeSwapCodex } from "../lib/codexdecide.ts";
-import { isCodexExhausted } from "../lib/codexpick.ts";
+import { codex, codexPickCtx, reconcileSiblings } from "../lib/codex.ts";
+import { liveCodexAccountId } from "../lib/codexauth.ts";
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { isExhausted } from "../lib/picker.ts";
 import { livingCodexPresences } from "../lib/codexpresence.ts";
-import { liveCodexAccountId } from "../lib/codexsample.ts";
-import { loadCodexAccounts } from "../lib/codexstate.ts";
-import { loadConfig } from "../lib/state.ts";
-import { thresholdBars } from "../lib/picker.ts";
+import { loadAccounts } from "../lib/state.ts";
 import { CODEX_SUPERVISOR_ID_ENV } from "./codexsupervisor.ts";
-import { CodexReconcileMarkerSchema, CodexRespawnMarkerSchema, CodexStopStdinSchema, type CodexAccount } from "../lib/types.ts";
+import { CodexReconcileMarkerSchema, CodexRespawnMarkerSchema, CodexStopStdinSchema } from "../lib/types.ts";
 import { log } from "../lib/log.ts";
 
 const SupervisorIdSchema = z.string().min(1).optional().catch(undefined);
@@ -20,7 +19,7 @@ const SupervisorIdSchema = z.string().min(1).optional().catch(undefined);
 async function promoteReconcile(input: { supervisorId: string; sessionId: string | null }): Promise<boolean> {
   const markerPath = join(codexPaths.reconcileDir, input.supervisorId);
   if (!existsSync(markerPath)) return false;
-  return withLock(codexPaths.lockFile, async () => promoteReconcileLocked(input));
+  return withLock(codexPool.lockFile, async () => promoteReconcileLocked(input));
 }
 
 function promoteReconcileLocked(input: { supervisorId: string; sessionId: string | null }): boolean {
@@ -51,12 +50,8 @@ function promoteReconcileLocked(input: { supervisorId: string; sessionId: string
     return false;
   }
   const now = Date.now();
-  const bars = thresholdBars(loadConfig());
-  const index = loadCodexAccounts();
-  const unusable = (account: CodexAccount): boolean =>
-    account.needsReauth === true || isCodexExhausted({ account, thresholds: bars, now });
-  const liveAccount = index.accounts.find((a) => a.accountId === liveId);
-  if (!liveAccount || unusable(liveAccount)) {
+  const liveAccount = loadAccounts(codexPool).accounts.find((a) => a.id === liveId);
+  if (!liveAccount || liveAccount.needsReauth === true || isExhausted(liveAccount, codexPickCtx(now, liveId))) {
     rmSync(markerPath, { force: true });
     log("codexstop.reconcile_blocked_target", {});
     return false;
@@ -75,6 +70,14 @@ function promoteReconcileLocked(input: { supervisorId: string; sessionId: string
   return true;
 }
 
+async function sweepSiblings(now: number): Promise<void> {
+  try {
+    await withLock(codexPool.lockFile, () => reconcileSiblings(now));
+  } catch (e) {
+    log("codexstop.resweep_failed", { err: e instanceof Error ? e.message : String(e) });
+  }
+}
+
 async function readStdin(): Promise<string> {
   const chunks: Uint8Array[] = [];
   for await (const chunk of Bun.stdin.stream()) chunks.push(chunk);
@@ -98,8 +101,11 @@ export async function handleCodexStop(input: { rawStdin: string }): Promise<void
       return;
     }
     if (await promoteReconcile({ supervisorId, sessionId })) return;
-    const decision = await evaluateAndMaybeSwapCodex({});
+    const now = Date.now();
+    await withLock(codexPool.lockFile, () => reconcileSiblings(now));
+    const decision = await evaluateAndMaybeSwap(codex, now);
     if (decision.swapped && decision.account) {
+      await sweepSiblings(now);
       mkdirSync(codexPaths.respawnDir, { recursive: true });
       const payload = CodexRespawnMarkerSchema.parse({
         account: decision.account.label,

package/src/entries/codexsupervisor.ts

@@ -1,12 +1,12 @@
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
-import { codexPaths, paths } from "../lib/paths.ts";
+import { codexPaths, codexPool, paths } from "../lib/paths.ts";
 import { withLock } from "../lib/lock.ts";
 import { LOOP_DIAGNOSIS, MAX_WRAP_DEPTH, UNMANAGED_ENV, WRAP_DEPTH_ENV, WRAP_RATE_MAX, WRAP_RATE_WINDOW_MS, wrapDepth, wrapperEntryRateTripped } from "../lib/claudebin.ts";
 import { resolveRealCodex } from "../lib/codexbin.ts";
 import { clearCodexPresence, writeCodexPresence } from "../lib/codexpresence.ts";
-import { liveCodexAccountId } from "../lib/codexsample.ts";
+import { liveCodexAccountId } from "../lib/codexauth.ts";
 import { saveTermios, restoreTermios } from "../lib/tty.ts";
 import { CodexRespawnMarkerSchema } from "../lib/types.ts";
 import { log } from "../lib/log.ts";
@@ -95,7 +95,7 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
     if (existsSync(marker)) rmSync(marker, { force: true });
     log("codexsupervisor.launch", { supervisorId: supervisorId.slice(0, 8), respawns, args: launchArgs.join(" ") });
 
-    const child = await withLock(codexPaths.lockFile, async () => {
+    const child = await withLock(codexPool.lockFile, async () => {
       const spawnAccountId = liveCodexAccountId();
       const spawned = Bun.spawn([real, ...launchArgs], {
         stdin: "inherit",

package/src/entries/sessionstart.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { claude } from "../lib/claude.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { log } from "../lib/log.ts";
 
@@ -21,9 +22,9 @@ export async function runSessionStart(): Promise<number> {
   const source = parsed.success ? parsed.data.source : undefined;
 
   try {
-    const decision = await evaluateAndMaybeSwap();
+    const decision = await evaluateAndMaybeSwap(claude);
     if (decision.swapped && decision.account) {
-      log("sessionstart.swapped", { source, account: decision.account.accountUuid.slice(0, 8) });
+      log("sessionstart.swapped", { source, account: decision.account.id.slice(0, 8) });
     }
   } catch (e) {
     log("sessionstart.error", { err: e instanceof Error ? e.message : String(e) });

package/src/entries/statusline.ts

@@ -1,16 +1,17 @@
 import { sortBy } from "es-toolkit";
 import { z } from "zod";
 import { readOAuthAccount } from "../lib/claudejson.ts";
+import { claudePool } from "../lib/paths.ts";
 import { loadAccounts, loadConfig, loadLastSwapAt, writeUsage } from "../lib/state.ts";
 import { familyTokens, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
-import { earliestReset, weeklyExpiry } from "../lib/picker.ts";
+import { earliestReset, limitWindows, weeklyExpiry, weeklyWindow } from "../lib/picker.ts";
 import { worktreeName } from "../lib/worktree.ts";
 import { makeColors, makeUsagePaint } from "../cli/render.ts";
 import { fmtResetShort } from "../lib/usage.ts";
 import {
   AccountsIndexSchema,
   StatusLineStdinSchema,
-  UsageWindowSchema,
+  WindowSchema,
   type Account,
   type UsageState,
   type UsageWindow,
@@ -20,7 +21,7 @@ const ADOPTION_GRACE_MS = 45_000;
 
 const RenderCtxSchema = z.object({
   accounts: AccountsIndexSchema,
-  perModel: z.record(z.string(), UsageWindowSchema),
+  perModel: z.record(z.string(), WindowSchema),
   switchModels: z.array(z.string()),
   worktree: z.string().nullable(),
   liveAccount: z.string().nullable(),
@@ -78,11 +79,11 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
     windows.push(seg("", wins.sevenDay, wins.sevenDay.resetsAt));
   }
   const seatUuid =
-    (ctx.liveAccount != null && ctx.accounts.accounts.some((a) => a.accountUuid === ctx.liveAccount) ? ctx.liveAccount : null) ??
-    ctx.accounts.activeAccountUuid;
+    (ctx.liveAccount != null && ctx.accounts.accounts.some((a) => a.id === ctx.liveAccount) ? ctx.liveAccount : null) ??
+    ctx.accounts.activeId;
   const walled = (a: Account) => a.enforcedUntil != null && a.enforcedUntil > ctx.now;
   const wallSeg = (wall: number) => seg("", { usedPercentage: 100, resetsAt: wall }, wall);
-  const seat = ctx.accounts.accounts.find((a) => a.accountUuid === seatUuid);
+  const seat = ctx.accounts.accounts.find((a) => a.id === seatUuid);
   if (seat?.enforcedUntil != null && walled(seat)) windows.push(wallSeg(seat.enforcedUntil));
   const seatMarker = seat && walled(seat) ? paint(100)("◆") : col.green("◆");
   const active =
@@ -93,20 +94,20 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
         : "";
 
   const parked = sortBy(
-    ctx.accounts.accounts.filter((a) => a.accountUuid !== seatUuid),
+    ctx.accounts.accounts.filter((a) => a.id !== seatUuid),
     [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, ctx.now)],
   );
   const poolSeg = (a: Account): string => {
     const marker = a.needsReauth ? col.red("✗") : walled(a) ? paint(100)("◇") : col.cyan("◇");
     if (a.enforcedUntil != null && walled(a)) return `${marker} ${wallSeg(a.enforcedUntil)}`;
-    const week = a.lastUsage?.sevenDay;
+    const week = weeklyWindow(a);
     if (week == null) return `${marker} ?`;
     const weekUsed = used(week);
     if (Math.round(weekUsed) <= 0) return `${marker} ${paint(0)("full")}`;
 
     const parts: string[] = [];
-    for (const [name, w] of Object.entries(a.lastUsage?.perModel ?? {})) {
-      if (used(w) > weekUsed) parts.push(seg(initial(name), w, null));
+    for (const w of limitWindows(a)) {
+      if (used(w) > weekUsed) parts.push(seg(initial(w.name ?? ""), w, null));
     }
     const expiry = weeklyExpiry(a, ctx.now);
     parts.push(seg("", week, Number.isFinite(expiry) ? expiry : null));
@@ -129,7 +130,7 @@ export async function runStatusline(): Promise<number> {
   try {
     account = readOAuthAccount()?.accountUuid ?? null;
     const windows = obj == null ? null : parseStatusLineStdin(obj);
-    const lastSwapAt = loadLastSwapAt();
+    const lastSwapAt = loadLastSwapAt(claudePool);
     if (windows && (lastSwapAt == null || now - lastSwapAt >= ADOPTION_GRACE_MS)) {
       const state: UsageState = { fiveHour: windows.fiveHour, sevenDay: windows.sevenDay, account, ts: now, model: parseStatusLineModel(obj) };
       writeUsage(state);
@@ -140,13 +141,14 @@ export async function runStatusline(): Promise<number> {
   let line: string;
   try {
     const cfg = loadConfig();
-    const accounts = loadAccounts();
+    const accounts = loadAccounts(claudePool);
     const stdin = StatusLineStdinSchema.safeParse(obj);
     const dir = stdin.success ? (stdin.data.workspace?.current_dir ?? stdin.data.workspace?.project_dir ?? null) : null;
     const colorterm = z.string().optional().parse(process.env.COLORTERM);
+    const live = accounts.accounts.find((a) => a.id === account);
     const ctx: RenderCtx = {
       accounts,
-      perModel: accounts.accounts.find((a) => a.accountUuid === account)?.lastUsage?.perModel ?? {},
+      perModel: Object.fromEntries((live ? limitWindows(live) : []).map((w) => [w.name ?? "", w])),
       switchModels: cfg.policy.switchModels,
       worktree: dir == null ? null : worktreeName(dir),
       liveAccount: account,

package/src/entries/stopfailurehook.ts

@@ -2,9 +2,11 @@ import { join } from "node:path";
 import { z } from "zod";
 import { paths } from "../lib/paths.ts";
 import { writeFileAtomic } from "../lib/atomic.ts";
+import { claude } from "../lib/claude.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { withLock } from "../lib/lock.ts";
+import { claudePool } from "../lib/paths.ts";
 import { POST_SWAP_COOLDOWN_MS, loadConfig, loadLastSwapAt } from "../lib/state.ts";
 import { classifyEnforcedLimit, findEnforcedRow, parseErrorBody, readTranscriptTail } from "../lib/usage.ts";
 import { RespawnMarkerSchema, type EnforcedLimit } from "../lib/types.ts";
@@ -29,7 +31,7 @@ async function readStdin(): Promise<string> {
 export async function runStopFailureHook(): Promise<number> {
   if (process.env.TOKENMAXXING_PROBE) return 0;
 
-  const entry = await withLock(paths.lockFile, () => ({ swapClock: loadLastSwapAt(), account: readOAuthAccount()?.accountUuid ?? null }));
+  const entry = await withLock(claudePool.lockFile, () => ({ swapClock: loadLastSwapAt(claudePool), account: readOAuthAccount()?.accountUuid ?? null }));
   const account = entry.account;
   const now = Date.now();
   const raw = await readStdin();
@@ -44,7 +46,7 @@ export async function runStopFailureHook(): Promise<number> {
   const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && pinnedSid != null && mainLoop;
 
   try {
-    const lastSwapAt = loadLastSwapAt();
+    const lastSwapAt = loadLastSwapAt(claudePool);
     if (lastSwapAt != null && lastSwapAt === entry.swapClock && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) {
       log("stopfailure.cooldown", { sinceSwapMs: now - lastSwapAt });
       return 0;
@@ -68,7 +70,7 @@ export async function runStopFailureHook(): Promise<number> {
       });
     }
 
-    const decision = await evaluateAndMaybeSwap(now, canPause && enforced != null, enforced);
+    const decision = await evaluateAndMaybeSwap(claude, now, canPause && enforced != null, enforced);
     if (enforced && canPause && pinnedSid && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       const marker = join(paths.respawnDir, pinnedSid);
       const payload = RespawnMarkerSchema.parse({
@@ -79,9 +81,9 @@ export async function runStopFailureHook(): Promise<number> {
         ...(launchedAt != null ? { launchedAt } : {}),
       });
       writeFileAtomic(marker, JSON.stringify(payload));
-      log("stopfailure.marker", { session: (stdinSid ?? pinnedSid).slice(0, 8), account: decision.account.accountUuid.slice(0, 8), waitUntil: payload.waitUntil });
+      log("stopfailure.marker", { session: (stdinSid ?? pinnedSid).slice(0, 8), account: decision.account.id.slice(0, 8), waitUntil: payload.waitUntil });
     } else {
-      log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.accountUuid.slice(0, 8), waitUntil: decision.waitUntil });
+      log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.id.slice(0, 8), waitUntil: decision.waitUntil });
     }
   } catch (e) {
     log("stopfailure.error", { err: e instanceof Error ? e.message : String(e) });

package/src/entries/stophook.ts

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { z } from "zod";
 import { paths } from "../lib/paths.ts";
 import { writeFileAtomic } from "../lib/atomic.ts";
+import { claude } from "../lib/claude.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { RespawnMarkerSchema } from "../lib/types.ts";
 import { log } from "../lib/log.ts";
@@ -24,9 +25,9 @@ export async function runStopHook(): Promise<number> {
 
   try {
     const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && pinnedSid != null;
-    const decision = await evaluateAndMaybeSwap(Date.now(), canPause);
+    const decision = await evaluateAndMaybeSwap(claude, Date.now(), canPause);
     if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
-      log(decision.swapped ? "stop.swapped" : "stop.wait", { account: decision.account.accountUuid.slice(0, 8), waitUntil: decision.waitUntil });
+      log(decision.swapped ? "stop.swapped" : "stop.wait", { account: decision.account.id.slice(0, 8), waitUntil: decision.waitUntil });
       if (decision.waitUntil !== undefined && canPause && pinnedSid) {
         const marker = join(paths.respawnDir, pinnedSid);
         const launchedAt = z.coerce.number().finite().optional().catch(undefined).parse(process.env.TOKENMAXXING_LAUNCHED_AT);

package/src/lib/claude.ts

@@ -0,0 +1,320 @@
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { readItem, writeItem, deleteItem, liveTarget, parkedTarget, isolatedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
+import { resolveRealClaude, resolveVerifiedClaude } from "./claudebin.ts";
+import { withClaudeRefreshLock } from "./claudelock.ts";
+import { isApiKeyMode, readOAuthAccount } from "./claudejson.ts";
+import { ensurePathInRc, installSupervisor, managedShellRcSkipLines, shellRcPath, timerActivationHint } from "./install.ts";
+import { withLock } from "./lock.ts";
+import { log } from "./log.ts";
+import { claudeTierLabel, describeIdentity, fetchTokenIdentity, isAccessTokenExpiring, isDeadCredential, refreshCredential, InvalidGrantError } from "./oauth.ts";
+import { claudePool, credItemFor, paths } from "./paths.ts";
+import type { Observation, Provider, SampleReport } from "./provider.ts";
+import { ensureLiveTokenFresh, probeActiveUsage, probeParkedUsage } from "./sample.ts";
+import { loadAccounts, loadUsage, loadUsageSnapshot, pinBinOverride, saveAccounts, writeUsage, type Harvest } from "./state.ts";
+import { isSkippableSwapError, performSwap } from "./swap.ts";
+import { loadSetupTokens, saveSetupTokens } from "./setuptokens.ts";
+import { saveTermios, restoreTermios } from "./tty.ts";
+import { CRED_ENV_OVERRIDES, familyTokens, gatedFamilies, mergeWindows, probeUsage, windowsOf } from "./usage.ts";
+import { CredentialBlobSchema, OAuthAccountSchema, type Account, type Config, type UsageState } from "./types.ts";
+import { c } from "../cli/render.ts";
+
+function teeObservation(account: Account, snap: { state: UsageState; at: number } | null): Observation | null {
+  if (!snap || snap.state.account !== account.id) return null;
+  if (account.lastUsageAt != null && snap.at < account.lastUsageAt) return { windows: account.windows, at: account.lastUsageAt };
+  const at = snap.state.sampledAt ?? snap.at;
+  const aggregate = windowsOf({ fiveHour: snap.state.fiveHour, sevenDay: snap.state.sevenDay, perModel: {} }, at);
+  return { windows: mergeWindows(aggregate, account.windows), at };
+}
+
+async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null> {
+  let snap = loadUsageSnapshot();
+  const ttl = cfg.policy.usagePollTtlMs;
+  const probeAttempted = account.lastProbeAt != null && now - account.lastProbeAt <= ttl;
+  const fresh = snap != null && snap.state.account === account.id && now - snap.at <= ttl;
+  const needsPerModel = snap != null && gatedFamilies(snap.state.model, cfg.policy.switchModels).length > 0;
+  if (opts.probe && !probeAttempted && (!fresh || needsPerModel)) {
+    const startedAt = Date.now();
+    const full = await probeUsage();
+    const ts = Date.now();
+    if (readOAuthAccount()?.accountUuid === account.id) {
+      if (full) {
+        const teed = loadUsageSnapshot();
+        if (teed && teed.state.account === account.id && ts - teed.at <= ttl) {
+          snap = teed;
+        } else {
+          const state: UsageState = { fiveHour: full.fiveHour, sevenDay: full.sevenDay, account: account.id, ts, model: null };
+          writeUsage(state);
+          snap = { state, at: ts };
+        }
+        const expected = gatedFamilies(snap.state.model, cfg.policy.switchModels);
+        const rows = Object.keys(full.perModel);
+        if (expected.length > 0 && !expected.some((f) => rows.some((k) => familyTokens(k).includes(f)))) {
+          log("usage.no_permodel_row", { families: expected.join(","), rows: rows.join(",") });
+        }
+      }
+      await withLock(claudePool.lockFile, () => {
+        const idx = loadAccounts(claudePool);
+        const a = idx.accounts.find((x) => x.id === account.id);
+        if (!a) return;
+        a.lastProbeAt = startedAt;
+        if (full) {
+          const probed = windowsOf(full, startedAt);
+          const aggregate = a.windows.some((w) => w.name == null) ? a.windows.filter((w) => w.name == null) : probed.filter((w) => w.name == null);
+          if (a.lastUsageAt == null) a.lastUsageAt = startedAt;
+          a.windows = mergeWindows([...aggregate, ...probed.filter((w) => w.name != null)], a.windows);
+        }
+        saveAccounts(claudePool, idx);
+      });
+    }
+  }
+  const current = loadAccounts(claudePool).accounts.find((a) => a.id === account.id) ?? account;
+  return teeObservation(current, snap);
+}
+
+async function samplePool(accounts: Account[], liveId: string | null): Promise<Map<string, SampleReport>> {
+  const reports = new Map<string, SampleReport>();
+  const tee = loadUsageSnapshot();
+  const probeOne = async (a: Account): Promise<void> => {
+    const isActive = liveId != null && liveId === a.id;
+    const teeCurrent = tee != null && (a.lastUsageAt == null || tee.at >= a.lastUsageAt);
+    if (isActive && tee && teeCurrent && tee.state.account === a.id) {
+      const at = tee.state.sampledAt ?? tee.at;
+      a.lastUsageAt = at;
+      a.windows = mergeWindows(windowsOf({ fiveHour: tee.state.fiveHour, sevenDay: tee.state.sevenDay, perModel: {} }, at), a.windows);
+      reports.set(a.id, { ok: true, source: "statusline" });
+      return;
+    }
+    const outcome = isActive ? await probeActiveUsage(a) : await probeParkedUsage(a);
+    if (!outcome.ok) {
+      reports.set(a.id, { ok: false, reason: outcome.reason });
+      return;
+    }
+    const at = Date.now();
+    a.lastUsageAt = at;
+    a.windows = mergeWindows(windowsOf(outcome.usage, at), a.windows);
+    reports.set(a.id, { ok: true, source: "probe" });
+  };
+  const active = accounts.find((a) => liveId != null && liveId === a.id) ?? null;
+  if (active) await probeOne(active);
+  try {
+    await ensureLiveTokenFresh();
+  } catch {
+  }
+  await Promise.all(accounts.filter((a) => a !== active).map(probeOne));
+  return reports;
+}
+
+async function liveOwner(): Promise<string | null> {
+  const live = await readItem(liveTarget());
+  if (live == null) return null;
+  const creds = CredentialBlobSchema.parse(JSON.parse(live)).claudeAiOauth;
+  return (await fetchTokenIdentity(creds.accessToken)).accountUuid;
+}
+
+async function removeCredentials(a: Account): Promise<void> {
+  const setupTokens = loadSetupTokens();
+  const item = credItemFor(a.id);
+  await deleteItem(parkedTarget(item));
+  for (const sampleDir of [join(paths.sampleDir, item), join(paths.sampleDir, `${item}-tick`)]) {
+    await deleteItem(isolatedTarget(sampleDir));
+    rmSync(sampleDir, { recursive: true, force: true });
+  }
+  if (setupTokens.tokens.some((t) => t.accountUuid === a.id)) {
+    saveSetupTokens({ ...setupTokens, tokens: setupTokens.tokens.filter((t) => t.accountUuid !== a.id) });
+  }
+}
+
+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;
+  }
+}
+
+async function login(): Promise<Harvest | null> {
+  const onboardDir = paths.onboardDir;
+  rmSync(onboardDir, { recursive: true, force: true });
+  mkdirSync(onboardDir, { recursive: true });
+  const iso = isolatedTarget(onboardDir);
+  await deleteItem(iso);
+  const cjPath = join(onboardDir, ".claude.json");
+  const real = resolveRealClaude();
+
+  const savedTermios = saveTermios();
+  const env: Record<string, string> = { ...process.env, CLAUDE_CONFIG_DIR: onboardDir, TOKENMAXXING_PROBE: "1", TOKENMAXXING_SUPERVISED: "" };
+  for (const key of CRED_ENV_OVERRIDES) delete env[key];
+  const p = Bun.spawn([real], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env,
+  });
+
+  try {
+    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 blobRaw = await readItem(iso);
+    if (!blobRaw || !identityReady(cjPath)) {
+      console.error(c.red("no login detected in the isolated session - nothing changed."));
+      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."));
+      return null;
+    }
+
+    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 at = Date.now();
+    const id = oauthAccount.accountUuid;
+    return {
+      id,
+      email: oauthAccount.emailAddress,
+      tier: claudeTierLabel(blob.claudeAiOauth),
+      oauthAccount,
+      sample: sampled ? { windows: windowsOf(sampled, at), at } : null,
+      park: () => writeItem(parkedTarget(credItemFor(id)), claudeAiOauthOnly(blobRaw)),
+    };
+  } finally {
+    if (p.exitCode === null) {
+      p.kill();
+      await p.exited;
+    }
+    restoreTermios(savedTermios);
+    await deleteItem(iso);
+    rmSync(onboardDir, { recursive: true, force: true });
+  }
+}
+
+async function importLive(): Promise<Harvest | null> {
+  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 null;
+  }
+
+  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 null;
+  }
+
+  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 null;
+  }
+
+  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 null;
+  }
+  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 null;
+  }
+
+  const id = oauthAccount.accountUuid;
+  const parked = JSON.stringify({ claudeAiOauth: creds });
+  return {
+    id,
+    email: oauthAccount.emailAddress,
+    tier: claudeTierLabel(creds),
+    oauthAccount,
+    sample: null,
+    park: () => writeItem(parkedTarget(credItemFor(id)), parked),
+  };
+}
+
+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 install(): void {
+  const out = installSupervisor();
+  console.log(`${c.green("✓")} installed ${c.bold("claude")} supervisor + statusLine/Stop/SessionStart hooks`);
+  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()}`));
+  if (!out.pathAhead) {
+    console.log();
+    ensurePathAhead();
+  }
+}
+
+export const claude: Provider = {
+  name: "claude",
+  flag: "",
+  pool: claudePool,
+  waitsWhenDepleted: true,
+  switchMargin: 1,
+  switchNote: "",
+  liveId: () => readOAuthAccount()?.accountUuid ?? null,
+  liveOwner,
+  presentIds: () => new Set(),
+  gatedFamilies: (cfg) => gatedFamilies(loadUsage()?.model ?? null, cfg.policy.switchModels),
+  observeLive,
+  samplePool,
+  mergeWindows,
+  swap: performSwap,
+  classifySwapError: (e) => (e instanceof InvalidGrantError ? "dead-grant" : isSkippableSwapError(e) ? "skip" : "fatal"),
+  removeCredentials,
+  login,
+  importLive,
+  preflight: () => pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() }),
+  install,
+  loginStep: (who) => `In the session that opens, run  ${c.bold("/login")}  with ${who}. It closes itself once you're in.`,
+  windowLabel: (name) => name.toLowerCase(),
+};