tokenmaxxing 1.34.0 → 1.38.0

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(),
+};

package/src/lib/claudelock.ts

@@ -1,9 +1,9 @@
 import { mkdirSync, realpathSync, rmdirSync, statSync, utimesSync } from "node:fs";
 import { join } from "node:path";
 import { delay } from "es-toolkit";
-import { z } from "zod";
 import { credDir } from "./paths.ts";
 import { log } from "./log.ts";
+import { ErrnoSchema } from "./types.ts";
 
 const STALE_MS = 60_000;
 const HEARTBEAT_MS = 5_000;
@@ -15,8 +15,7 @@ function tryAcquire(lockDir: string): boolean {
     mkdirSync(lockDir);
     return true;
   } catch (e) {
-    const errno = z.object({ code: z.string() }).safeParse(e);
-    if (!errno.success || errno.data.code !== "EEXIST") throw e;
+    if (ErrnoSchema.safeParse(e).data?.code !== "EEXIST") throw e;
   }
   try {
     if (Date.now() - statSync(lockDir).mtimeMs > STALE_MS) {

package/src/lib/codex.ts

@@ -0,0 +1,345 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "./atomic.ts";
+import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV } from "./claudebin.ts";
+import { codexIdentityOf, deleteParkedCodexAuth, isCodexAccessExpiring, liveCodexAccountId, readCodexAuthAt, readLiveCodexAuth, readParkedCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
+import { resolveRealCodex, verifyRealCodex } from "./codexbin.ts";
+import { CodexInvalidGrantError, CodexRefreshFailedError, refreshCodexAuth } from "./codexoauth.ts";
+import { livingCodexPresences, presentCodexAccountIds } from "./codexpresence.ts";
+import { CodexUsageReadError, codexLimitLabel, fetchCodexUsage } from "./codexusage.ts";
+import { codexSupervisorLink, ensurePathInRc, installCodexSupervisor, managedShellRcSkipLines, shellRcPath } from "./install.ts";
+import { withLock } from "./lock.ts";
+import { log } from "./log.ts";
+import { codexCredItemFor, codexPaths, codexPool } from "./paths.ts";
+import { isExhausted, thresholdBars, type PickCtx } from "./picker.ts";
+import type { Observation, Provider, SampleReport } from "./provider.ts";
+import { loadAccounts, loadConfig, pinBinOverride, saveAccounts, saveLastSwapAt, type Harvest } from "./state.ts";
+import { restoreTermios, saveTermios } from "./tty.ts";
+import { CodexReconcileMarkerSchema, type Account, type CodexAuthJson, type CodexUsage, type Config } from "./types.ts";
+import { c } from "../cli/render.ts";
+
+function applyUsage(account: Account, usage: CodexUsage, at: number): void {
+  account.windows = usage.windows;
+  account.lastUsageAt = at;
+  if (usage.email != null) account.email = usage.email;
+  if (usage.planType != null) account.tier = usage.planType;
+}
+
+async function sampleLiveOntoOwner(now: number): Promise<void> {
+  let live = readLiveCodexAuth();
+  if (!live) return;
+  const idx = loadAccounts(codexPool);
+  const identity = codexIdentityOf({ auth: live });
+  const owner = idx.accounts.find((a) => a.id === identity.accountId);
+  if (!owner) return;
+
+  if (isCodexAccessExpiring({ auth: live, now }) && !presentCodexAccountIds().has(identity.accountId)) {
+    try {
+      live = await refreshCodexAuth({ auth: live, now });
+    } catch (e) {
+      if (e instanceof CodexInvalidGrantError) {
+        owner.needsReauth = true;
+        saveAccounts(codexPool, idx);
+        log("codex.live_invalid_grant", { account: owner.id.slice(0, 8) });
+        return;
+      }
+      throw e;
+    }
+    writeLiveCodexAuth({ auth: live });
+    writeParkedCodexAuth({ credFile: codexCredItemFor(owner.id), auth: live });
+  }
+  applyUsage(owner, await fetchCodexUsage({ auth: live, at: now }), now);
+  saveAccounts(codexPool, idx);
+}
+
+async function observeLive(account: Account, cfg: Config, now: number, opts: { probe: boolean }): Promise<Observation | null> {
+  if (opts.probe && (account.lastUsageAt == null || now - account.lastUsageAt > cfg.policy.usagePollTtlMs)) {
+    await withLock(codexPool.lockFile, () => sampleLiveOntoOwner(now));
+  }
+  const fresh = loadAccounts(codexPool).accounts.find((a) => a.id === account.id);
+  return fresh?.lastUsageAt != null ? { windows: fresh.windows, at: fresh.lastUsageAt } : null;
+}
+
+type CodexSampleOutcome = { ok: true; usage: CodexUsage; at: number } | { ok: false; reason: string; deadGrant: boolean };
+
+async function sampleAccount(account: Account, liveId: string | null, now: number): Promise<CodexSampleOutcome> {
+  const isLive = liveId != null && account.id === liveId;
+  const credFile = codexCredItemFor(account.id);
+  try {
+    let auth = isLive ? readLiveCodexAuth() : readParkedCodexAuth({ credFile });
+    if (!auth) return { ok: false, reason: isLive ? "live auth.json vanished" : "no parked credential", deadGrant: false };
+    if (isCodexAccessExpiring({ auth, now })) {
+      const running = presentCodexAccountIds().has(account.id);
+      if (running && !isLive) {
+        return { ok: false, reason: "running in a live codex session (parked token refresh unsafe)", deadGrant: false };
+      }
+      if (!running) {
+        auth = await refreshCodexAuth({ auth, now });
+        if (isLive) writeLiveCodexAuth({ auth });
+        writeParkedCodexAuth({ credFile, auth });
+      }
+    }
+    const at = Date.now();
+    return { ok: true, usage: await fetchCodexUsage({ auth, at }), at };
+  } catch (e) {
+    if (e instanceof CodexInvalidGrantError) return { ok: false, reason: e.message, deadGrant: true };
+    if (e instanceof CodexRefreshFailedError || e instanceof CodexUsageReadError) return { ok: false, reason: e.message, deadGrant: false };
+    throw e;
+  }
+}
+
+async function samplePool(accounts: Account[], liveId: string | null, now: number): Promise<Map<string, SampleReport>> {
+  const reports = new Map<string, SampleReport>();
+  await Promise.all(
+    accounts.map(async (account) => {
+      const outcome = await sampleAccount(account, liveId, now);
+      if (outcome.ok) {
+        applyUsage(account, outcome.usage, outcome.at);
+        reports.set(account.id, { ok: true, source: "probe" });
+      } else {
+        if (outcome.deadGrant) account.needsReauth = true;
+        reports.set(account.id, { ok: false, reason: outcome.reason });
+      }
+    }),
+  );
+  return reports;
+}
+
+async function swap(target: Account): Promise<void> {
+  const idx = loadAccounts(codexPool);
+  const live = readLiveCodexAuth();
+  let liveOwner: Account | null = null;
+  if (live) {
+    const liveIdentity = codexIdentityOf({ auth: live });
+    liveOwner = idx.accounts.find((a) => a.id === liveIdentity.accountId) ?? null;
+    if (!liveOwner) {
+      throw new Error(
+        `live codex credential belongs to ${liveIdentity.email ?? liveIdentity.accountId.slice(0, 8)}, which is not in the pool - refusing to swap over it; import it first with \`tokenmaxxing add --codex\``,
+      );
+    }
+    if (liveOwner.id !== idx.activeId) {
+      log("codexswap.harvest_drift", { labeled: idx.activeId?.slice(0, 8) ?? null, actual: liveOwner.id.slice(0, 8) });
+    }
+  }
+  const commit = (): void => {
+    idx.activeId = target.id;
+    const entry = idx.accounts.find((a) => a.id === target.id);
+    if (entry) entry.needsReauth = false;
+    saveAccounts(codexPool, idx);
+  };
+
+  if (live && liveOwner && liveOwner.id === target.id) {
+    writeParkedCodexAuth({ credFile: codexCredItemFor(target.id), auth: live });
+    commit();
+    log("codexswap.reconciled", { account: target.id.slice(0, 8) });
+    return;
+  }
+
+  const parked = readParkedCodexAuth({ credFile: codexCredItemFor(target.id) });
+  if (!parked) throw new Error(`no parked codex credential for ${target.label}`);
+
+  let fresh: CodexAuthJson;
+  try {
+    fresh = await refreshCodexAuth({ auth: parked });
+  } catch (e) {
+    if (e instanceof CodexInvalidGrantError) {
+      const entry = idx.accounts.find((a) => a.id === target.id);
+      if (entry) {
+        entry.needsReauth = true;
+        saveAccounts(codexPool, idx);
+      }
+      log("codexswap.invalid_grant", { account: target.id.slice(0, 8) });
+    }
+    throw e;
+  }
+  writeParkedCodexAuth({ credFile: codexCredItemFor(target.id), auth: fresh });
+
+  if (live && liveOwner) {
+    const liveNow = readLiveCodexAuth();
+    if (!liveNow || codexIdentityOf({ auth: liveNow }).accountId !== liveOwner.id) {
+      throw new Error("live codex credential changed mid-swap - refusing to harvest under a stale identity; retry");
+    }
+    writeParkedCodexAuth({ credFile: codexCredItemFor(liveOwner.id), auth: liveNow });
+    log("codexswap.harvest", { account: liveOwner.id.slice(0, 8) });
+  }
+
+  writeLiveCodexAuth({ auth: fresh });
+  commit();
+  saveLastSwapAt(codexPool, Date.now());
+  log("codexswap.done", { account: target.id.slice(0, 8), label: target.label });
+}
+
+async function login(): Promise<Harvest | null> {
+  const real = resolveRealCodex();
+  const onboardDir = codexPaths.onboardDir;
+  rmSync(onboardDir, { recursive: true, force: true });
+  mkdirSync(onboardDir, { recursive: true });
+  writeFileAtomic(join(onboardDir, "config.toml"), 'cli_auth_credentials_store = "file"\n');
+
+  const savedTermios = saveTermios();
+  const p = Bun.spawn([real, "login", "--device-auth"], {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: {
+      ...process.env,
+      CODEX_HOME: onboardDir,
+      TOKENMAXXING_PROBE: "1",
+      [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH),
+    },
+  });
+  await p.exited;
+  restoreTermios(savedTermios);
+
+  try {
+    const auth = readCodexAuthAt({ path: join(onboardDir, "auth.json") });
+    if (p.exitCode !== 0 || !auth) {
+      console.error(c.red("no codex login landed in the isolated home - nothing added."));
+      return null;
+    }
+    const identity = codexIdentityOf({ auth });
+    const usage = await sampleLogin(auth);
+    return {
+      id: identity.accountId,
+      email: usage?.usage.email ?? identity.email,
+      tier: usage?.usage.planType ?? identity.planType,
+      sample: usage ? { windows: usage.usage.windows, at: usage.at } : null,
+      park: async () => writeParkedCodexAuth({ credFile: codexCredItemFor(identity.accountId), auth }),
+    };
+  } finally {
+    rmSync(onboardDir, { recursive: true, force: true });
+  }
+}
+
+async function sampleLogin(auth: CodexAuthJson): Promise<{ usage: CodexUsage; at: number } | null> {
+  console.log(c.dim("sampling usage..."));
+  const at = Date.now();
+  try {
+    return { usage: await fetchCodexUsage({ auth, at }), at };
+  } catch (e) {
+    if (!(e instanceof CodexUsageReadError)) throw e;
+    console.log(c.yellow("could not sample usage now - it will fill in on first use."));
+    return null;
+  }
+}
+
+async function importLive(): Promise<Harvest | null> {
+  const live = readLiveCodexAuth();
+  if (!live) {
+    console.error(c.red(`no codex login found at ${codexPaths.authJson} - run \`codex login\` first, then re-run this.`));
+    return null;
+  }
+  const identity = codexIdentityOf({ auth: live });
+  const usage = await sampleLogin(live);
+
+  if (presentCodexAccountIds().has(identity.accountId)) {
+    console.error(c.red("a live supervised codex session is running this account - its token rotates under us, so parking a snapshot now could poison the backup."));
+    console.error(c.dim("close that codex session (or let it exit) and re-run `tokenmaxxing init --codex`."));
+    return null;
+  }
+
+  return {
+    id: identity.accountId,
+    email: usage?.usage.email ?? identity.email,
+    tier: usage?.usage.planType ?? identity.planType,
+    sample: usage ? { windows: usage.usage.windows, at: usage.at } : null,
+    park: async () => {
+      if (presentCodexAccountIds().has(identity.accountId)) {
+        throw new Error("a live supervised codex session started running this account mid-init - close it and re-run `tokenmaxxing init --codex`");
+      }
+      const fresh2 = readLiveCodexAuth();
+      if (!fresh2 || codexIdentityOf({ auth: fresh2 }).accountId !== identity.accountId) {
+        throw new Error("the live codex login changed while init was running (a concurrent swap?) - re-run `tokenmaxxing init --codex`");
+      }
+      writeParkedCodexAuth({ credFile: codexCredItemFor(identity.accountId), auth: fresh2 });
+    },
+  };
+}
+
+function storePinnedAwayFromFile(): boolean {
+  const configToml = `${codexPaths.home}/config.toml`;
+  if (!existsSync(configToml)) return false;
+  const config = Bun.TOML.parse(readFileSync(configToml, "utf8"));
+  return "cli_auth_credentials_store" in config && config.cli_auth_credentials_store !== "file";
+}
+
+function preflight(): void {
+  const real = resolveRealCodex();
+  const fail = verifyRealCodex({ bin: real });
+  if (fail !== null) throw new Error(`codex binary failed verification: ${real}: ${fail}`);
+  pinBinOverride({ key: "codexBin", bin: real });
+  if (storePinnedAwayFromFile()) {
+    throw new Error(
+      'codex config.toml pins cli_auth_credentials_store away from the plain auth.json file tokenmaxxing swaps - set cli_auth_credentials_store = "file" in ~/.codex/config.toml, run `codex login`, then re-run this.',
+    );
+  }
+}
+
+function install(): void {
+  installCodexSupervisor();
+  const rc = shellRcPath();
+  if (rc && ensurePathInRc(rc) === "skipped") {
+    const hint = managedShellRcSkipLines();
+    console.log(c.yellow(`⚠ ${hint.headline}`));
+    console.log(c.yellow(`  ${hint.detail}`));
+    console.log(c.yellow(`  ${hint.exportLine}`));
+  }
+  console.log(`${c.green("✓")} codex supervisor installed at ${codexSupervisorLink()}`);
+  console.log(`${c.green("✓")} Stop hook declared in ${codexPaths.hooksJson}`);
+  console.log();
+  console.log(c.bold(c.yellow("one manual step: codex skips untrusted hooks.")));
+  console.log(c.yellow("open codex, run /hooks, and trust the tokenmaxxing Stop hook - auto-switching is inert until then."));
+}
+
+export function codexPickCtx(now: number, currentId: string | null): PickCtx {
+  return { now, thresholds: thresholdBars(loadConfig()), currentId, families: null };
+}
+
+export function reconcileSiblings(now: number): void {
+  const liveId = liveCodexAccountId();
+  if (liveId == null) return;
+  const idx = loadAccounts(codexPool);
+  const liveAccount = idx.accounts.find((a) => a.id === liveId);
+  if (!liveAccount || liveAccount.needsReauth === true || isExhausted(liveAccount, codexPickCtx(now, liveId))) return;
+  const living = livingCodexPresences();
+  if (existsSync(codexPaths.reconcileDir)) {
+    const alive = new Set(living.map((presence) => presence.supervisorId));
+    for (const name of readdirSync(codexPaths.reconcileDir)) {
+      if (!alive.has(name)) rmSync(join(codexPaths.reconcileDir, name), { force: true });
+    }
+  }
+  for (const presence of living) {
+    if (presence.accountId === liveId) continue;
+    if (!idx.accounts.some((a) => a.id === presence.accountId)) continue;
+    const markerPath = join(codexPaths.reconcileDir, presence.supervisorId);
+    if (existsSync(markerPath)) continue;
+    mkdirSync(codexPaths.reconcileDir, { recursive: true });
+    writeFileAtomic(markerPath, JSON.stringify(CodexReconcileMarkerSchema.parse({ accountId: presence.accountId, ts: now })));
+    log("codex.reconcile_signal", { supervisorId: presence.supervisorId.slice(0, 8), account: presence.accountId.slice(0, 8) });
+  }
+}
+
+export const codex: Provider = {
+  name: "codex",
+  flag: " --codex",
+  pool: codexPool,
+  waitsWhenDepleted: false,
+  switchMargin: 1.2,
+  switchNote: " (takes effect on the next codex start)",
+  liveId: liveCodexAccountId,
+  liveOwner: async () => liveCodexAccountId(),
+  presentIds: presentCodexAccountIds,
+  gatedFamilies: () => null,
+  observeLive,
+  samplePool,
+  mergeWindows: (next) => next,
+  swap,
+  classifySwapError: (e) => (e instanceof CodexInvalidGrantError ? "dead-grant" : "fatal"),
+  removeCredentials: async (a) => deleteParkedCodexAuth({ credFile: codexCredItemFor(a.id) }),
+  login,
+  importLive,
+  preflight,
+  install,
+  loginStep: (who) => `Open the URL codex prints, enter the code, and sign in with ${who}; the command exits once you're in.`,
+  windowLabel: codexLimitLabel,
+};