tokenmaxxing 0.2.0 → 0.3.0

package/src/lib/picker.ts

@@ -0,0 +1,79 @@
+// Choose the best account to switch TO when the active one crosses threshold.
+// Policy: exclude the current account and any that need reauth or are still
+// rate-limited (usage >= threshold and not yet past resets_at). Among the rest,
+// prefer the account whose weekly window expires soonest: weekly limits reset
+// at a fixed per-account time and unused allowance is forfeited at reset, so
+// quota nearest its reset is use-it-or-lose-it and should be drained first.
+// Tiebreak on lowest 7-day usage, then soonest 5h reset.
+
+import { minBy, sortBy } from "es-toolkit";
+import { z } from "zod";
+import { AccountSchema, type Account } from "./types.ts";
+
+const PickCtxSchema = z.object({
+  now: z.number(),
+  threshold: z.number(),
+  currentAccountUuid: z.string().nullable(),
+});
+export type PickCtx = z.infer<typeof PickCtxSchema>;
+
+/** An account is "exhausted" if a window is >= threshold and hasn't reset yet. */
+export function isExhausted(a: Account, ctx: PickCtx): boolean {
+  const u = a.lastUsage;
+  if (!u) return false;
+  const blocked = (w: { usedPercentage: number; resetsAt: number | null }) =>
+    w.usedPercentage >= ctx.threshold && (w.resetsAt == null || w.resetsAt > ctx.now);
+  return blocked(u.fiveHour) || blocked(u.sevenDay);
+}
+
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Epoch ms when the account's weekly quota is next forfeited. The weekly reset
+ *  is a fixed per-account anchor, so a stale (past) resetsAt extrapolates
+ *  forward in 7-day steps; an account with no sampled reset sorts last. */
+export function weeklyExpiry(a: Account, now: number): number {
+  const r = a.lastUsage?.sevenDay.resetsAt;
+  if (r == null) return Number.POSITIVE_INFINITY;
+  if (r > now) return r;
+  return r + (Math.floor((now - r) / WEEK_MS) + 1) * WEEK_MS;
+}
+
+export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
+  const candidates = accounts.filter(
+    (a) =>
+      a.accountUuid !== ctx.currentAccountUuid &&
+      !a.needsReauth &&
+      !isExhausted(a, ctx),
+  );
+  if (candidates.length === 0) return null;
+
+  // soonest weekly expiry first; tiebreak lowest 7-day usage, then soonest 5h reset.
+  return sortBy(candidates, [
+    (a) => weeklyExpiry(a, ctx.now),
+    (a) => a.lastUsage?.sevenDay.usedPercentage ?? 0,
+    (a) => a.lastUsage?.fiveHour.resetsAt ?? Number.POSITIVE_INFINITY,
+  ])[0]!;
+}
+
+/** When an account becomes usable again: the latest reset among its over-threshold
+ *  windows (all must reset), or `now` if nothing is over. */
+export function usableAt(a: Account, threshold: number, now: number): number {
+  const u = a.lastUsage;
+  if (!u) return now;
+  const blocking = [u.fiveHour, u.sevenDay]
+    .filter((w) => w.usedPercentage >= threshold && w.resetsAt != null)
+    .map((w) => w.resetsAt as number);
+  return blocking.length ? Math.max(...blocking) : now;
+}
+
+const EarliestResetSchema = z.object({ account: AccountSchema, availableAt: z.number() });
+export type EarliestReset = z.infer<typeof EarliestResetSchema>;
+
+/** For the all-depleted case: the account (not current, not reauth) that becomes
+ *  usable soonest. */
+export function pickEarliestReset(accounts: Account[], ctx: PickCtx): EarliestReset | null {
+  const mapped = accounts
+    .filter((a) => a.accountUuid !== ctx.currentAccountUuid && !a.needsReauth)
+    .map((a) => ({ account: a, availableAt: usableAt(a, ctx.threshold, ctx.now) }));
+  return minBy(mapped, (x) => x.availableAt) ?? null;
+}

package/src/lib/sample.ts

@@ -0,0 +1,144 @@
+// Live-sample a PARKED account's `/usage` without disturbing the live login.
+// `/usage` is free (0 tokens), so `status` can show every account's real usage.
+// We install the account's parked credential into a throwaway CLAUDE_CONFIG_DIR
+// (the isolated credential claude reads for that dir), run `claude -p /usage`
+// against it, then tear the item down.
+//
+// Contamination guards (the incident that motivated these):
+//   1. probeUsage scrubs every ambient credential-override env var, so an
+//      inherited CLAUDE_CODE_OAUTH_TOKEN can't hijack the isolated probe.
+//   2. before trusting a backup we verify (roles endpoint) that its token really
+//      belongs to this account - a mislabeled backup (drifted harvest) surfaces
+//      as an explicit error, never as another account's bars.
+//
+// Refresh tokens rotate single-use, so the one hazard is a rotation we fail to
+// capture. Two guards: refresh an expiring token OURSELVES up front, and
+// capture-before-delete the isolated item in case claude rotated it anyway.
+//
+// The caller MUST hold the tokenmaxxing flock so a parked refresh cannot collide
+// with an in-flight performSwap refreshing the same account.
+
+import { mkdirSync, rmSync, writeFileSync } 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 { credItemFor, paths } from "./paths.ts";
+import { withClaudeRefreshLock } from "./claudelock.ts";
+import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
+import { FullUsageSchema, probeUsage } from "./usage.ts";
+import { CredentialBlobSchema, type Account, type OAuthCreds, type RolesResponse } from "./types.ts";
+
+/** Result of a live sample: the fresh usage, or why it could not be taken. */
+export const SampleOutcomeSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), usage: FullUsageSchema }),
+  z.object({ ok: z.literal(false), reason: z.string() }),
+]);
+export type SampleOutcome = z.infer<typeof SampleOutcomeSchema>;
+
+/** Verify `creds` belongs to `account`; null on match, else the mismatch reason. */
+async function identityMismatch(creds: OAuthCreds, account: Account): Promise<string | null> {
+  let org: RolesResponse;
+  try {
+    org = await fetchTokenOrg(creds.accessToken);
+  } catch (e) {
+    return `credential identity check failed: ${String((e as Error).message ?? e)}`;
+  }
+  if (org.organization_uuid === account.organizationUuid) return null;
+  return `credential actually belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)})`;
+}
+
+/**
+ * Live-sample `account`'s `/usage` in isolation. On a dead refresh token or a
+ * mislabeled credential it sets `account.needsReauth` in place (the caller
+ * persists accounts.json). Mutates only the passed object and keychain items.
+ */
+export async function probeParkedUsage(account: Account): Promise<SampleOutcome> {
+  const backup = parkedTarget(account.keychainItem);
+  const parkedRaw = await readItem(backup);
+  if (!parkedRaw) return { ok: false, reason: "no parked credential - re-add with `tokenmaxxing add`" };
+
+  let creds: OAuthCreds;
+  try {
+    creds = CredentialBlobSchema.parse(JSON.parse(parkedRaw)).claudeAiOauth;
+  } catch (e) {
+    return { ok: false, reason: `parked credential unreadable (${String((e as Error).message ?? e).slice(0, 80)}) - re-add with \`tokenmaxxing add\`` };
+  }
+
+  // Hand claude a token with comfortable headroom so it won't run its own refresh
+  // (which claude does within 120s of expiry). Refresh + persist ourselves first.
+  if (isAccessTokenExpiring(creds, 300_000)) {
+    try {
+      creds = await refreshCredential(creds);
+      await writeItem(backup, JSON.stringify({ claudeAiOauth: creds }));
+    } catch (e) {
+      if (e instanceof InvalidGrantError) {
+        account.needsReauth = true;
+        return { ok: false, reason: "refresh token dead - re-auth with `tokenmaxxing add`" };
+      }
+      return { ok: false, reason: `token refresh failed: ${String((e as Error).message ?? e)}` };
+    }
+  }
+
+  const mismatch = await identityMismatch(creds, account);
+  if (mismatch) {
+    account.needsReauth = true;
+    return { ok: false, reason: `${mismatch} - this account's own credential is gone; re-auth with \`tokenmaxxing add\`` };
+  }
+
+  const dir = join(paths.sampleDir, credItemFor(account.accountUuid));
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync(dir, { recursive: true });
+  const isoTarget = isolatedTarget(dir);
+  const installed = JSON.stringify({ claudeAiOauth: creds });
+
+  try {
+    await writeItem(isoTarget, installed);
+    writeFileSync(join(dir, ".claude.json"), JSON.stringify({ oauthAccount: account.oauthAccount, hasCompletedOnboarding: true }));
+    const usage = await probeUsage(dir);
+    return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+  } finally {
+    // capture-before-delete: never discard a rotation claude may have performed.
+    const afterIso = await readItem(isoTarget);
+    if (afterIso && afterIso !== installed) await writeItem(backup, claudeAiOauthOnly(afterIso));
+    await deleteItem(isoTarget);
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Live-sample the ACTIVE account off the live login, verifying the live
+ * credential belongs to it. `/usage` with no CLAUDE_CONFIG_DIR meters the live
+ * keychain item. A drifted active label surfaces as an error, not another
+ * account's bars.
+ */
+export async function probeActiveUsage(account: Account): Promise<SampleOutcome> {
+  const liveRaw = await readItem(liveTarget());
+  if (!liveRaw) return { ok: false, reason: "no live credential - run `claude` and `/login`" };
+  let creds: OAuthCreds;
+  try {
+    creds = CredentialBlobSchema.parse(JSON.parse(liveRaw)).claudeAiOauth;
+  } catch (e) {
+    return { ok: false, reason: `live credential blob unreadable (${String((e as Error).message ?? e).slice(0, 80)})` };
+  }
+
+  // A running claude keeps the live token fresh; after long idle it may not have.
+  if (isAccessTokenExpiring(creds, 300_000)) {
+    try {
+      await withClaudeRefreshLock(async () => {
+        const raw2 = (await readItem(liveTarget())) ?? liveRaw;
+        const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
+        creds = isAccessTokenExpiring(current, 300_000) ? await refreshCredential(current) : current;
+        if (creds !== current) await writeItem(liveTarget(), mergeIntoLive(raw2, creds));
+      });
+    } catch (e) {
+      if (e instanceof InvalidGrantError) return { ok: false, reason: "live refresh token dead - run `claude` and `/login`" };
+      return { ok: false, reason: `token refresh failed: ${String((e as Error).message ?? e)}` };
+    }
+  }
+
+  const mismatch = await identityMismatch(creds, account);
+  if (mismatch) return { ok: false, reason: `live ${mismatch} - active label drifted; run \`tokenmaxxing switch\`` };
+
+  const usage = await probeUsage();
+  return usage ? { ok: true, usage } : { ok: false, reason: "`/usage` returned no limit data (see log)" };
+}

package/src/lib/sessions.ts

@@ -0,0 +1,27 @@
+// Persist the flags a managed session was launched with, so any later relaunch
+// of that session id (a fresh supervisor invocation, or the depleted-pool
+// recovery in #20) re-applies them instead of dropping --dangerously-skip-
+// permissions / --model / etc.
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+const SessionSchema = z.object({ flags: z.array(z.string()), cwd: z.string() });
+
+function sessionFile(sid: string): string {
+  return join(paths.home, "sessions", `${sid}.json`);
+}
+
+export function saveSessionFlags(sid: string, flags: string[], cwd: string): void {
+  mkdirSync(join(paths.home, "sessions"), { recursive: true });
+  writeFileAtomic(sessionFile(sid), JSON.stringify({ flags, cwd }));
+}
+
+export function loadSessionFlags(sid: string): string[] | null {
+  const f = sessionFile(sid);
+  if (!existsSync(f)) return null;
+  return SessionSchema.parse(JSON.parse(readFileSync(f, "utf8"))).flags;
+}

package/src/lib/settings.ts

@@ -0,0 +1,141 @@
+// Idempotent merge of tokenmaxxing's three entries into the user-owned
+// ~/.claude/settings.json: a statusLine shim, a Stop hook, a SessionStart hook.
+// We APPEND to existing hook arrays and WRAP the existing statusLine - never clobber.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+/** Absolute path to the installed tokenmaxxing binary the settings entries call. */
+export function installedBin(): string {
+  return join(paths.binDir, "tokenmaxxing");
+}
+
+const HookCmdSchema = z.looseObject({ type: z.string(), command: z.string() });
+const HookGroupSchema = z.looseObject({ matcher: z.string().optional(), hooks: z.array(HookCmdSchema).default([]) });
+const StatusLineSchema = z.looseObject({ type: z.string(), command: z.string() });
+const SettingsSchema = z.looseObject({
+  statusLine: StatusLineSchema.optional(),
+  hooks: z.record(z.string(), z.array(HookGroupSchema)).optional(),
+});
+type Settings = z.infer<typeof SettingsSchema>;
+type HookGroup = z.infer<typeof HookGroupSchema>;
+
+const PRIOR_STATUSLINE_FILE = join(paths.home, "prior-statusline.json");
+
+const SUBCMD = {
+  statusline: "__statusline",
+  stop: "__stop-hook",
+  sessionStart: "__session-start",
+} as const;
+
+function readSettings(): Settings {
+  if (!existsSync(paths.claudeSettings)) return {};
+  return SettingsSchema.parse(JSON.parse(readFileSync(paths.claudeSettings, "utf8")));
+}
+
+function writeSettings(s: Settings): void {
+  writeFileAtomic(paths.claudeSettings, JSON.stringify(s, null, 2) + "\n", 0o644);
+}
+
+/** True if a hook/statusline command string is one tokenmaxxing installed. */
+export function isOurCommand(cmd: string | undefined): boolean {
+  if (!cmd) return false;
+  return (
+    cmd.includes(SUBCMD.statusline) ||
+    cmd.includes(SUBCMD.stop) ||
+    cmd.includes(SUBCMD.sessionStart) ||
+    // also match the installed bin path even if the subcommand text changes
+    cmd.includes(installedBin())
+  );
+}
+
+function ourHookGroup(sub: string): HookGroup {
+  return { hooks: [{ type: "command", command: `${JSON.stringify(installedBin())} ${sub}` }] };
+}
+
+function appendHook(s: Settings, event: string, sub: string): void {
+  s.hooks ??= {};
+  s.hooks[event] ??= [];
+  const arr = s.hooks[event]!;
+  const present = arr.some((g) => g.hooks?.some((h) => h.command?.includes(sub)));
+  if (!present) arr.push(ourHookGroup(sub));
+}
+
+function removeHook(s: Settings, event: string, sub: string): void {
+  const arr = s.hooks?.[event];
+  if (!arr) return;
+  s.hooks![event] = arr.filter((g) => !g.hooks?.some((h) => h.command?.includes(sub)));
+  if (s.hooks![event]!.length === 0) delete s.hooks![event];
+}
+
+const InstallResultSchema = z.object({ priorStatusLine: z.string().nullable() });
+export type InstallResult = z.infer<typeof InstallResultSchema>;
+
+/**
+ * Install the three entries. Returns the prior statusLine command that was
+ * wrapped (stored to disk so the shim can chain to it and uninstall can restore).
+ */
+export function installSettings(): InstallResult {
+  const s = readSettings();
+
+  // ---- statusLine: capture prior (unless it's already ours), then wrap.
+  let prior: string | null;
+  if (s.statusLine && !isOurCommand(s.statusLine.command)) {
+    prior = s.statusLine.command;
+    writeFileAtomic(PRIOR_STATUSLINE_FILE, JSON.stringify({ command: prior }) + "\n", 0o644);
+  } else {
+    prior = readPriorStatusLine();
+  }
+  s.statusLine = {
+    type: "command",
+    command: `${JSON.stringify(installedBin())} ${SUBCMD.statusline}`,
+  };
+
+  // ---- hooks: append ours if absent.
+  appendHook(s, "Stop", SUBCMD.stop);
+  appendHook(s, "SessionStart", SUBCMD.sessionStart);
+
+  writeSettings(s);
+  return { priorStatusLine: prior };
+}
+
+/** Remove our three entries and restore the prior statusLine if we have it. */
+export function uninstallSettings(): void {
+  const s = readSettings();
+  removeHook(s, "Stop", SUBCMD.stop);
+  removeHook(s, "SessionStart", SUBCMD.sessionStart);
+  if (s.statusLine && isOurCommand(s.statusLine.command)) {
+    const prior = readPriorStatusLine();
+    if (prior) s.statusLine = { type: "command", command: prior };
+    else delete s.statusLine;
+  }
+  writeSettings(s);
+}
+
+const PriorStatusLineSchema = z.object({ command: z.string() });
+
+export function readPriorStatusLine(): string | null {
+  if (!existsSync(PRIOR_STATUSLINE_FILE)) return null;
+  return PriorStatusLineSchema.parse(JSON.parse(readFileSync(PRIOR_STATUSLINE_FILE, "utf8"))).command;
+}
+
+const SettingsCheckSchema = z.object({
+  statusLineOk: z.boolean(),
+  stopOk: z.boolean(),
+  sessionStartOk: z.boolean(),
+});
+export type SettingsCheck = z.infer<typeof SettingsCheckSchema>;
+
+export function checkSettings(): SettingsCheck {
+  const s = readSettings();
+  const has = (event: string, sub: string) =>
+    !!s.hooks?.[event]?.some((g) => g.hooks?.some((h) => h.command?.includes(sub)));
+  return {
+    statusLineOk: isOurCommand(s.statusLine?.command),
+    stopOk: has("Stop", SUBCMD.stop),
+    sessionStartOk: has("SessionStart", SUBCMD.sessionStart),
+  };
+}

package/src/lib/state.ts

@@ -0,0 +1,125 @@
+// Config + accounts index + usage snapshot persistence. All writes atomic.
+
+import { existsSync, readFileSync } from "node:fs";
+import { isEqual } from "es-toolkit";
+import { z } from "zod";
+import { paths, realClaudeBinFromEnv } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+import {
+  AccountsIndexSchema,
+  ConfigSchema,
+  ModelUsageStateSchema,
+  UsageStateSchema,
+  type AccountsIndex,
+  type Config,
+  type ModelUsageState,
+  type UsageState,
+} from "./types.ts";
+
+// ---- config.json (minimal, fixed schema) ---------------------------------
+
+const DEFAULT_CONFIG: Config = {
+  threshold: 95,
+  claudeBin: "",
+  policy: { projectionMargin: 0, switchModels: ["fable", "opus"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
+};
+
+/** On-disk shape (all optional); validated via Zod, merged over defaults. */
+const ConfigFileSchema = z
+  .object({
+    threshold: z.number(),
+    claudeBin: z.string(),
+    policy: z
+      .object({
+        projectionMargin: z.number(),
+        switchModels: z.array(z.string()),
+        usagePollTtlMs: z.number(),
+        maxWaitMs: z.number(),
+      })
+      .partial(),
+  })
+  .partial();
+
+export function loadConfig(): Config {
+  const cfg: Config = { ...DEFAULT_CONFIG, policy: { ...DEFAULT_CONFIG.policy } };
+  if (existsSync(paths.configJson)) {
+    let raw: unknown = {};
+    try {
+      raw = JSON.parse(readFileSync(paths.configJson, "utf8"));
+    } catch {
+      raw = {};
+    }
+    const parsed = ConfigFileSchema.safeParse(raw);
+    const p = parsed.success ? parsed.data : {};
+    cfg.threshold = p.threshold ?? cfg.threshold;
+    cfg.claudeBin = p.claudeBin ?? cfg.claudeBin;
+    cfg.policy.projectionMargin = p.policy?.projectionMargin ?? cfg.policy.projectionMargin;
+    cfg.policy.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
+    cfg.policy.maxWaitMs = p.policy?.maxWaitMs ?? cfg.policy.maxWaitMs;
+    if (p.policy?.switchModels) {
+      cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
+    }
+  }
+  // env override wins for the claude binary (tests / relocation)
+  const envBin = realClaudeBinFromEnv();
+  if (envBin) cfg.claudeBin = envBin;
+  return ConfigSchema.parse(cfg);
+}
+
+export function saveConfig(c: Config): void {
+  writeFileAtomic(paths.configJson, JSON.stringify(ConfigSchema.parse(c), null, 2) + "\n");
+}
+
+// ---- accounts.json -------------------------------------------------------
+
+const emptyIndex = (): AccountsIndex => ({ version: 1, activeAccountUuid: null, accounts: [] });
+
+export function loadAccounts(): AccountsIndex {
+  if (!existsSync(paths.accountsJson)) return emptyIndex();
+  try {
+    const parsed = AccountsIndexSchema.safeParse(JSON.parse(readFileSync(paths.accountsJson, "utf8")));
+    return parsed.success ? parsed.data : emptyIndex();
+  } catch {
+    return emptyIndex();
+  }
+}
+
+export function saveAccounts(idx: AccountsIndex): void {
+  writeFileAtomic(paths.accountsJson, JSON.stringify(AccountsIndexSchema.parse(idx), null, 2) + "\n");
+}
+
+// ---- usage.json ----------------------------------------------------------
+
+export function loadUsage(): UsageState | null {
+  if (!existsSync(paths.usageJson)) return null;
+  try {
+    const parsed = UsageStateSchema.safeParse(JSON.parse(readFileSync(paths.usageJson, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Write-on-change: skip the write (and its fsync) when only `ts` would differ. */
+export function writeUsage(next: UsageState): boolean {
+  const prev = loadUsage();
+  if (prev && isEqual({ ...prev, ts: 0 }, { ...next, ts: 0 })) return false;
+  writeFileAtomic(paths.usageJson, JSON.stringify(next));
+  return true;
+}
+
+// ---- model-usage.json (per-model caps from `/usage`, TTL-cached) ----------
+
+export function loadModelUsage(): ModelUsageState | null {
+  if (!existsSync(paths.modelUsageJson)) return null;
+  try {
+    const parsed = ModelUsageStateSchema.safeParse(JSON.parse(readFileSync(paths.modelUsageJson, "utf8")));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveModelUsage(next: ModelUsageState): void {
+  writeFileAtomic(paths.modelUsageJson, JSON.stringify(next));
+}

package/src/lib/swap.ts

@@ -0,0 +1,143 @@
+// The account-switch sequence. Runs under the tokenmaxxing flock (held by the
+// caller - the Stop hook or a CLI command). The keychain/json writes additionally
+// run under claude's own refresh lock so they can't interleave with a token refresh.
+//
+//   refresh B (network, no lock)
+//   resolve the live credential's TRUE owner (network, no lock)
+//   ── under claude refresh lock ──
+//     harvest live → its OWNER's backup (mandatory: refresh token rotates in place)
+//     install B into the live item
+//     persist B's rotated token into B's backup
+//     rewrite oauthAccount in ~/.claude.json
+//     mark B active (inside the lock: a crash before this write leaves a stale
+//     active label, which is exactly what once made a harvest destroy a backup)
+
+import { loadAccounts, saveAccounts } from "./state.ts";
+import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
+import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
+import { swapOAuthAccount } from "./claudejson.ts";
+import { withLock } from "./lock.ts";
+import { withClaudeRefreshLock } from "./claudelock.ts";
+import { paths } from "./paths.ts";
+import { log } from "./log.ts";
+import { pickBest, type PickCtx } from "./picker.ts";
+import { CredentialBlobSchema, type Account, type OAuthCreds } from "./types.ts";
+
+function parseBlob(raw: string) {
+  return CredentialBlobSchema.parse(JSON.parse(raw));
+}
+
+/**
+ * Mechanically switch the LIVE credential to `target`. Assumes the caller holds
+ * the tokenmaxxing flock. Throws InvalidGrantError (after marking needs_reauth)
+ * when target's refresh token is dead.
+ */
+export async function performSwap(target: Account): Promise<void> {
+  const idx = loadAccounts();
+
+  // 1. refresh target's parked credential (network) BEFORE taking claude's lock.
+  const parkedRaw = await readItem(parkedTarget(target.keychainItem));
+  if (!parkedRaw) throw new Error(`no parked credential for ${target.email}`);
+  let fresh: OAuthCreds;
+  try {
+    fresh = await refreshCredential(parseBlob(parkedRaw).claudeAiOauth);
+  } catch (e) {
+    if (e instanceof InvalidGrantError) {
+      const t = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
+      if (t) { t.needsReauth = true; saveAccounts(idx); }
+      log("swap.invalid_grant", { account: target.accountUuid.slice(0, 8) });
+    }
+    throw e;
+  }
+  // 2. resolve the live credential's TRUE owner - the harvest destination.
+  //    activeAccountUuid is a label, and labels drift from the blob they describe
+  //    (crash mid-swap, manual /login, historical re-init); harvesting by label is
+  //    how a backup once got destroyed. The token itself cannot lie. A rotation
+  //    between here and the harvest write keeps the same owner, so this can stay
+  //    outside the (fast, local) critical section.
+  const preLive = await readItem(liveTarget());
+  let liveOwner: Account | null = null;
+  if (preLive) {
+    let liveCreds = parseBlob(preLive).claudeAiOauth;
+    let identifiable = true;
+    if (isAccessTokenExpiring(liveCreds, 60_000)) {
+      try {
+        liveCreds = await refreshCredential(liveCreds);
+        await writeItem(liveTarget(), mergeIntoLive(preLive, liveCreds));
+      } catch (e) {
+        if (!(e instanceof InvalidGrantError)) throw e;
+        // dead credential family: nothing worth preserving, skip the harvest.
+        identifiable = false;
+        log("swap.harvest_skipped_dead_live", {});
+      }
+    }
+    if (identifiable) {
+      const org = await fetchTokenOrg(liveCreds.accessToken);
+      liveOwner = idx.accounts.find((a) => a.organizationUuid === org.organization_uuid) ?? null;
+      if (!liveOwner) {
+        throw new Error(
+          `live credential belongs to ${org.organization_name} (org ${org.organization_uuid.slice(0, 8)}), which is not in the pool - refusing to swap over it; import it first with \`tokenmaxxing add\``,
+        );
+      }
+      if (liveOwner.accountUuid !== idx.activeAccountUuid) {
+        log("swap.harvest_drift", {
+          labeled: idx.activeAccountUuid?.slice(0, 8) ?? null,
+          actual: liveOwner.accountUuid.slice(0, 8),
+        });
+      }
+    }
+  }
+
+  // 3. the fast, local, atomic-vs-claude-refresh critical section.
+  await withClaudeRefreshLock(async () => {
+    const currentLive = await readItem(liveTarget());
+
+    // harvest the live claudeAiOauth into its OWNER's (small) backup item.
+    if (liveOwner && currentLive) {
+      await writeItem(parkedTarget(liveOwner.keychainItem), claudeAiOauthOnly(currentLive));
+      log("swap.harvest", { account: liveOwner.accountUuid.slice(0, 8) });
+    }
+
+    // install B: merge B's fresh claudeAiOauth into the CURRENT live blob so all
+    // sibling state (MCP OAuth tokens, etc.) is preserved across the swap.
+    await writeItem(liveTarget(), mergeIntoLive(currentLive, fresh));
+    // persist B's rotated token into its small backup item.
+    await writeItem(parkedTarget(target.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
+    swapOAuthAccount(target.oauthAccount);
+    // record B as active INSIDE the critical section so a crash cannot leave the
+    // installed credential and the active label pointing at different accounts.
+    idx.activeAccountUuid = target.accountUuid;
+    const t2 = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
+    if (t2) { t2.needsReauth = false; }
+    saveAccounts(idx);
+  });
+  log("swap.done", { account: target.accountUuid.slice(0, 8), email: target.email });
+}
+
+/**
+ * Pick the best candidate and swap to it, retrying past dead refresh tokens.
+ * Assumes the caller holds the flock (does NOT lock - avoids same-process
+ * flock self-deadlock). Returns the account landed on, or null if none usable.
+ */
+export async function chooseAndSwap(ctx: Omit<PickCtx, "currentAccountUuid">): Promise<Account | null> {
+  const tried = new Set<string>();
+  while (true) {
+    const idx = loadAccounts();
+    const candidates = idx.accounts.filter((a) => !tried.has(a.accountUuid));
+    const best = pickBest(candidates, { ...ctx, currentAccountUuid: idx.activeAccountUuid });
+    if (!best) return null;
+    tried.add(best.accountUuid);
+    try {
+      await performSwap(best);
+      return best;
+    } catch (e) {
+      if (e instanceof InvalidGrantError) continue; // dead token - next candidate
+      throw e;
+    }
+  }
+}
+
+/** Standalone lock-taking variant for CLI/manual use (NEVER call under a held flock). */
+export async function swapToBest(ctx: Omit<PickCtx, "currentAccountUuid">): Promise<Account | null> {
+  return withLock(paths.lockFile, () => chooseAndSwap(ctx));
+}

package/src/lib/tty.ts

@@ -0,0 +1,14 @@
+// Save/restore the controlling terminal's line settings around a child that owns
+// the tty via inherited stdio. If we SIGTERM such a child (supervisor respawn, or
+// `add` auto-exit), the terminal can be left in raw mode; restoring stty fixes it.
+
+export function saveTermios(): string | null {
+  const p = Bun.spawnSync(["/bin/sh", "-c", "stty -g </dev/tty"]);
+  const s = p.stdout?.toString().trim();
+  return s && p.exitCode === 0 ? s : null;
+}
+
+export function restoreTermios(saved: string | null): void {
+  const cmd = saved ? `stty ${saved} </dev/tty` : "stty sane </dev/tty";
+  Bun.spawnSync(["/bin/sh", "-c", cmd], { stdout: "ignore", stderr: "ignore" });
+}