tokenmaxxing 0.1.0 → 0.2.1

package/src/cli/rename.ts

@@ -0,0 +1,33 @@
+// `tokenmaxxing rename <selector> <new-label>` - relabel a pooled account.
+
+import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { c } from "./render.ts";
+import type { Account } from "../lib/types.ts";
+
+/** Resolve an account by email, label, or accountUuid prefix. */
+export function findAccount(accounts: Account[], selector: string): Account | undefined {
+  const s = selector.toLowerCase();
+  return (
+    accounts.find((a) => a.email.toLowerCase() === s) ??
+    accounts.find((a) => a.label.toLowerCase() === s) ??
+    accounts.find((a) => a.accountUuid.toLowerCase().startsWith(s))
+  );
+}
+
+export function cmdRename(selector?: string, newLabel?: string): number {
+  if (!selector || !newLabel) {
+    console.error("usage: tokenmaxxing rename <email|label|uuid> <new-label>");
+    return 2;
+  }
+  const idx = loadAccounts();
+  const a = findAccount(idx.accounts, selector);
+  if (!a) {
+    console.error(c.red(`no account matches "${selector}"`));
+    return 1;
+  }
+  const old = a.label;
+  a.label = newLabel;
+  saveAccounts(idx);
+  console.log(`renamed ${c.dim(old)} → ${c.bold(newLabel)}`);
+  return 0;
+}

package/src/cli/render.ts

@@ -0,0 +1,36 @@
+// Terminal rendering helpers for the CLI (bars, colors, relative times).
+
+import { clamp } from "es-toolkit";
+
+const useColor = !process.env.NO_COLOR && process.stdout.isTTY;
+
+export const c = {
+  dim: (s: string) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s: string) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+  green: (s: string) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  yellow: (s: string) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+  red: (s: string) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+  cyan: (s: string) => (useColor ? `\x1b[36m${s}\x1b[0m` : s),
+};
+
+/** A fixed-width usage bar, colored by fill. */
+export function bar(pct: number, width = 16): string {
+  const clamped = clamp(pct, 0, 100);
+  const filled = Math.round((clamped / 100) * width);
+  const body = "█".repeat(filled) + "░".repeat(width - filled);
+  const label = `${clamped.toFixed(0).padStart(3)}%`;
+  const paint = clamped >= 95 ? c.red : clamped >= 75 ? c.yellow : c.green;
+  return `${paint(body)} ${label}`;
+}
+
+/** Relative-time string for a reset epoch, e.g. "resets in 2h13m". */
+export function fmtReset(epochMs: number | null | undefined, now = Date.now()): string {
+  if (epochMs == null) return "";
+  const dsec = Math.round((epochMs - now) / 1000);
+  if (dsec <= 0) return "reset now";
+  const h = Math.floor(dsec / 3600);
+  const m = Math.floor((dsec % 3600) / 60);
+  if (h > 24) return `resets in ${Math.floor(h / 24)}d${h % 24}h`;
+  if (h > 0) return `resets in ${h}h${m}m`;
+  return `resets in ${m}m`;
+}

package/src/cli/rm.ts

@@ -0,0 +1,28 @@
+// `tokenmaxxing rm <selector>` - remove a pooled account (not the active one).
+
+import { deleteItem, parkedTarget } from "../lib/credstore.ts";
+import { loadAccounts, saveAccounts } from "../lib/state.ts";
+import { findAccount } from "./rename.ts";
+import { c } from "./render.ts";
+
+export async function cmdRm(selector?: string): Promise<number> {
+  if (!selector) {
+    console.error("usage: tokenmaxxing rm <email|label|uuid>");
+    return 2;
+  }
+  const idx = loadAccounts();
+  const a = findAccount(idx.accounts, selector);
+  if (!a) {
+    console.error(c.red(`no account matches "${selector}"`));
+    return 1;
+  }
+  if (a.accountUuid === idx.activeAccountUuid) {
+    console.error(c.red(`${a.email} is the ACTIVE account - switch away before removing it.`));
+    return 1;
+  }
+  await deleteItem(parkedTarget(a.keychainItem));
+  idx.accounts = idx.accounts.filter((x) => x.accountUuid !== a.accountUuid);
+  saveAccounts(idx);
+  console.log(`removed ${c.bold(a.label)} from the pool (${idx.accounts.length} left)`);
+  return 0;
+}

package/src/cli/status.ts

@@ -0,0 +1,99 @@
+// `tokenmaxxing status`: accounts with 5h / weekly / per-model usage bars.
+// Parked accounts are live-sampled in isolation (`claude -p /usage`); the active
+// account is read off the free statusLine feed (usage.json) so we never poll its
+// own busy token. A sample that fails falls back to the last-known values with a
+// visible "(cached)" note - never a silent stale number. Fresh figures are
+// persisted onto each account for the picker/switch logic.
+
+import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts } from "../lib/state.ts";
+import { readOAuthAccount } from "../lib/claudejson.ts";
+import { probeActiveUsage, probeParkedUsage, type SampleOutcome } from "../lib/sample.ts";
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
+import { isExhausted } from "../lib/picker.ts";
+import { bar, c, fmtReset } from "./render.ts";
+import type { FullUsage } from "../lib/usage.ts";
+import type { UsageWindow } from "../lib/types.ts";
+
+export async function cmdStatus(): Promise<number> {
+  const idx = loadAccounts();
+  const cfg = loadConfig();
+  const live = loadUsage();
+  const modelUsage = loadModelUsage();
+  const now = Date.now();
+
+  if (idx.accounts.length === 0) {
+    console.log(c.dim("no accounts yet, run `tokenmaxxing init`"));
+    return 0;
+  }
+
+  const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+
+  // Sample under the flock so parked refreshes can't collide with an in-flight swap.
+  console.error(c.dim("sampling live usage…"));
+  const outcomes = new Map<string, SampleOutcome>();
+  await withLock(paths.lockFile, () =>
+    Promise.all(
+      idx.accounts.map(async (a) => {
+        const isActive = a.accountUuid === idx.activeAccountUuid && activeOrg === a.organizationUuid;
+        // Active account: prefer the free statusLine push (usage.json) so we never
+        // poll its own token, which is busy exactly when it matters. per-model
+        // comes from model-usage.json (also statusLine-driven).
+        const fromStatusLine: FullUsage | null =
+          isActive && live && live.org === a.organizationUuid
+            ? {
+                session: live.fiveHour,
+                weekAll: live.sevenDay,
+                perModel: modelUsage && modelUsage.org === a.organizationUuid ? modelUsage.perModel : {},
+              }
+            : null;
+        const outcome: SampleOutcome = fromStatusLine
+          ? { ok: true, usage: fromStatusLine }
+          : isActive
+            ? await probeActiveUsage(a)
+            : await probeParkedUsage(a);
+        outcomes.set(a.accountUuid, outcome);
+        if (!outcome.ok) return;
+        a.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
+        if (Object.keys(outcome.usage.perModel).length > 0) a.lastPerModel = outcome.usage.perModel;
+      }),
+    ),
+  );
+  saveAccounts(idx);
+
+  console.log(c.dim(`threshold ${cfg.threshold}%  ·  ${idx.accounts.length} account(s)`));
+  console.log();
+
+  const row = (name: string, w: UsageWindow) =>
+    console.log(`    ${name.padEnd(5)} ${bar(w.usedPercentage)}  ${c.dim(fmtReset(w.resetsAt, now))}`);
+
+  for (const a of idx.accounts) {
+    const active = a.accountUuid === idx.activeAccountUuid;
+    const outcome = outcomes.get(a.accountUuid);
+    const failed = outcome ? !outcome.ok : false;
+    // On a failed sample, fall back to the last-known values (with a note below).
+    const usage = outcome?.ok ? outcome.usage : undefined;
+    const aggregate = usage ? { fiveHour: usage.session, sevenDay: usage.weekAll } : a.lastUsage;
+    const perModel = usage ? usage.perModel : a.lastPerModel;
+
+    const marker = active ? c.green("●") : c.dim("○");
+    const badges: string[] = [];
+    if (active) badges.push(c.green("active"));
+    if (a.needsReauth) badges.push(c.red("needs-reauth"));
+    if (isExhausted(a, { now, threshold: cfg.threshold, currentAccountUuid: idx.activeAccountUuid }))
+      badges.push(c.yellow("exhausted"));
+
+    console.log(`${marker} ${c.bold(a.label || a.email)} ${badges.join(" ")}`);
+    if (aggregate) {
+      row("5h", aggregate.fiveHour);
+      row("week", aggregate.sevenDay);
+    }
+    if (perModel) for (const [name, w] of Object.entries(perModel)) row(name, w);
+    if (failed && outcome && !outcome.ok) {
+      const note = aggregate || perModel ? "cached · live sample failed" : "live sample failed";
+      console.log(`    ${c.yellow(note)}: ${c.dim(outcome.reason)}`);
+    }
+    console.log();
+  }
+  return 0;
+}

package/src/cli/switch.ts

@@ -0,0 +1,61 @@
+// `tokenmaxxing switch [selector]` (also the bare `tokenmaxxing` / `xx`).
+// No selector → auto-pick the best available account. With a selector → switch to
+// that one. Manual/recovery tool: no threshold gate, runs under the flock. When
+// everything is depleted it still switches to the soonest-resetting account.
+
+import { withLock } from "../lib/lock.ts";
+import { paths } from "../lib/paths.ts";
+import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { performSwap, chooseAndSwap } from "../lib/swap.ts";
+import { pickEarliestReset } from "../lib/picker.ts";
+import { InvalidGrantError } from "../lib/oauth.ts";
+import { findAccount } from "./rename.ts";
+import { c, fmtReset } from "./render.ts";
+
+export async function cmdSwitch(selector?: string): Promise<number> {
+  const idx0 = loadAccounts();
+  if (idx0.accounts.length < 2) {
+    console.error(c.yellow("need at least 2 accounts to switch - add one with `tokenmaxxing add`"));
+    return 1;
+  }
+  const cfg = loadConfig();
+  const now = Date.now();
+
+  return withLock(paths.lockFile, async () => {
+    const idx = loadAccounts();
+
+    if (selector) {
+      const target = findAccount(idx.accounts, selector);
+      if (!target) { console.error(c.red(`no account matches "${selector}"`)); return 1; }
+      if (target.accountUuid === idx.activeAccountUuid) { console.log(`already on ${c.bold(target.label)}`); return 0; }
+      if (target.needsReauth) { console.error(c.red(`${target.label} needs re-auth - \`tokenmaxxing add\``)); return 1; }
+      try {
+        await performSwap(target);
+      } catch (e) {
+        if (e instanceof InvalidGrantError) { console.error(c.red(`${target.label}'s refresh token is dead - re-add it`)); return 1; }
+        throw e;
+      }
+      console.log(`${c.green("↻")} switched to ${c.bold(target.label)}`);
+      return 0;
+    }
+
+    // auto: best account under threshold
+    const landed = await chooseAndSwap({ now, threshold: cfg.threshold });
+    if (landed) {
+      console.log(`${c.green("↻")} switched to ${c.bold(landed.label)}`);
+      return 0;
+    }
+
+    // everything is depleted → switch to whichever recovers soonest
+    const earliest = pickEarliestReset(idx.accounts, { now, threshold: cfg.threshold, currentAccountUuid: idx.activeAccountUuid });
+    if (!earliest) { console.error(c.yellow("no switchable account (all need re-auth?)")); return 1; }
+    try {
+      await performSwap(earliest.account);
+    } catch (e) {
+      if (e instanceof InvalidGrantError) { console.error(c.red(`${earliest.account.label}'s refresh token is dead`)); return 1; }
+      throw e;
+    }
+    console.log(`${c.yellow("↻")} all accounts at limit - switched to ${c.bold(earliest.account.label)} (${fmtReset(earliest.availableAt, now)})`);
+    return 0;
+  });
+}

package/src/entries/sessionstart.ts

@@ -0,0 +1,39 @@
+// SessionStart hook. A launch/resume backstop: if the active account is already
+// over threshold with FRESH usage (e.g. a prior session left it exhausted), swap
+// the credential before this session's first turn so it starts on a good account.
+// Right after a respawn, usage.json is stale for the new org, so the org guard in
+// evaluateAndMaybeSwap makes this correctly no-op.
+
+import { z } from "zod";
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { log } from "../lib/log.ts";
+
+const SessionStartStdin = z.looseObject({
+  source: z.string().optional(), // startup | resume | clear | compact
+  session_id: z.string().optional(),
+});
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runSessionStart(): Promise<number> {
+  if (process.env.TOKENMAXXING_PROBE) return 0;
+
+  const raw = await readStdin();
+  const parsed = SessionStartStdin.safeParse((() => { try { return JSON.parse(raw); } catch { return {}; } })());
+  const source = parsed.success ? parsed.data.source : undefined;
+
+  try {
+    const decision = await evaluateAndMaybeSwap();
+    if (decision.swapped && decision.account) {
+      // fresh session → it will read the new credential on its first API call.
+      log("sessionstart.swapped", { source, account: decision.account.accountUuid.slice(0, 8) });
+    }
+  } catch (e) {
+    log("sessionstart.error", { err: String((e as Error).message ?? e) });
+  }
+  return 0;
+}

package/src/entries/statusline.ts

@@ -0,0 +1,52 @@
+// statusLine shim. Reads Claude's statusLine stdin, tees the rate-limit data to
+// usage.json (write-on-change, O(ms)), then transparently delegates to the user's
+// prior statusLine command (same stdin) and passes its stdout through unchanged.
+// Must NEVER break the user's status line: every step is best-effort.
+
+import { readOAuthAccount } from "../lib/claudejson.ts";
+import { readPriorStatusLine } from "../lib/settings.ts";
+import { writeUsage } from "../lib/state.ts";
+import { parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
+import type { UsageState } from "../lib/types.ts";
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runStatusline(): Promise<number> {
+  const raw = await readStdin();
+
+  // 1) tee usage - best effort, never throws out.
+  try {
+    const obj = JSON.parse(raw);
+    const windows = parseStatusLineStdin(obj);
+    if (windows) {
+      const org = readOAuthAccount()?.organizationUuid ?? null;
+      const state: UsageState = { ...windows, org, ts: Date.now(), model: parseStatusLineModel(obj) };
+      writeUsage(state);
+    }
+  } catch {
+    // malformed stdin - skip usage, still delegate below
+  }
+
+  // 2) delegate to the prior statusLine, feeding it the same stdin.
+  const prior = readPriorStatusLine();
+  if (prior) {
+    try {
+      const p = Bun.spawn(["/bin/sh", "-c", prior], {
+        stdin: new TextEncoder().encode(raw),
+        stdout: "pipe",
+        stderr: "inherit",
+      });
+      const out = await new Response(p.stdout).text();
+      await p.exited;
+      if (out) process.stdout.write(out);
+      return p.exitCode ?? 0;
+    } catch {
+      // fall through to no-op
+    }
+  }
+  return 0;
+}

package/src/entries/stophook.ts

@@ -0,0 +1,48 @@
+// Stop hook. Fires when claude finishes a turn (transcript already committed).
+// If the active account crossed the threshold, swap the credential and - when
+// running under the supervisor - drop a respawn marker keyed by this session id.
+// The supervisor watches for the marker and SIGTERMs its child at this clean
+// boundary, then relaunches `--resume`. We never kill claude ourselves.
+
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "../lib/paths.ts";
+import { writeFileAtomic } from "../lib/atomic.ts";
+import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { RespawnMarkerSchema } from "../lib/types.ts";
+import { log } from "../lib/log.ts";
+
+const StopStdin = z.looseObject({ session_id: z.string().optional() });
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runStopHook(): Promise<number> {
+  // recursion guard - our own `-p '/usage'` probe re-enters hooks.
+  if (process.env.TOKENMAXXING_PROBE) return 0;
+
+  const raw = await readStdin();
+  const parsed = StopStdin.safeParse((() => { try { return JSON.parse(raw); } catch { return {}; } })());
+  const sessionId =
+    (parsed.success ? parsed.data.session_id : undefined) ?? process.env.TOKENMAXXING_SESSION_ID;
+
+  try {
+    const decision = await evaluateAndMaybeSwap();
+    // Respawn on a swap, or on a depleted-pool wait (relaunch after the reset).
+    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 });
+      if (process.env.TOKENMAXXING_SUPERVISED === "1" && sessionId) {
+        const marker = join(paths.respawnDir, sessionId);
+        const payload = RespawnMarkerSchema.parse({ account: decision.account.label, ts: Date.now(), waitUntil: decision.waitUntil });
+        writeFileAtomic(marker, JSON.stringify(payload));
+        log("stop.marker", { session: sessionId.slice(0, 8) });
+      }
+    }
+  } catch (e) {
+    log("stop.error", { err: String((e as Error).message ?? e) });
+  }
+  return 0; // never block the stop
+}

package/src/entries/supervisor.ts

@@ -0,0 +1,202 @@
+// The `claude` supervisor. Invoked in place of claude (via ~/.config/tokenmaxxing/
+// bin/claude on PATH). Runs the REAL claude with inherited stdio (claude owns the
+// real terminal exactly as if run directly), pins a session id, and watches for a
+// respawn marker dropped by the Stop/SessionStart hook. When the marker appears it
+// SIGTERMs its own child at the (already-committed) turn boundary and relaunches
+// `claude --resume <id>` on the freshly-swapped account. Process/terminal manager
+// only - it never reads or proxies tokens.
+
+import { existsSync, mkdirSync, rmSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { maxBy } from "es-toolkit";
+import { z } from "zod";
+import { paths } from "../lib/paths.ts";
+import { resolveRealClaude } from "../lib/claudebin.ts";
+import { saveTermios, restoreTermios } from "../lib/tty.ts";
+import { loadSessionFlags, saveSessionFlags } from "../lib/sessions.ts";
+import { RespawnMarkerSchema } from "../lib/types.ts";
+import { log } from "../lib/log.ts";
+
+const NONINTERACTIVE_SUBCMDS = new Set([
+  "mcp", "config", "doctor", "update", "install", "migrate-installer",
+  "setup-token", "plugin", "agents", "completion", "help",
+]);
+
+const isUuid = (s: string) => z.uuid().safeParse(s).success;
+
+const AnalysisSchema = z.object({
+  manage: z.boolean(),
+  sessionId: z.string().nullable(),
+  resumeId: z.string().nullable(),
+  continueLatest: z.boolean(),
+});
+type Analysis = z.infer<typeof AnalysisSchema>;
+
+export function analyzeArgs(argv: string[]): Analysis {
+  let sessionId: string | null = null;
+  let resumeId: string | null = null;
+  let continueLatest = false;
+  let printMode = false;
+  let firstPositional: string | null = null;
+
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "-p" || a === "--print") printMode = true;
+    else if (a === "--version" || a === "-v" || a === "--help" || a === "-h") printMode = true;
+    else if (a === "--session-id") sessionId = argv[++i] ?? null;
+    else if (a === "-c" || a === "--continue") continueLatest = true;
+    else if (a === "-r" || a === "--resume") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-") && isUuid(next)) { resumeId = next; i++; }
+    } else if (!a.startsWith("-") && firstPositional === null) {
+      firstPositional = a;
+    }
+  }
+
+  const isSubcmd = firstPositional !== null && NONINTERACTIVE_SUBCMDS.has(firstPositional);
+  const manage = !printMode && !isSubcmd && !process.env.TOKENMAXXING_PROBE;
+  return { manage, sessionId, resumeId, continueLatest };
+}
+
+/** Remove session-selecting flags so we can inject our own on respawn. */
+export function stripSessionFlags(argv: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a === "--session-id") { i++; continue; }
+    if (a === "-c" || a === "--continue") continue;
+    if (a === "-r" || a === "--resume") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("-") && isUuid(next)) i++;
+      continue;
+    }
+    out.push(a);
+  }
+  return out;
+}
+
+/** Newest transcript session id for the current cwd (for `-c`/`-r`-without-id). */
+function latestSessionForCwd(): string | null {
+  const slug = process.cwd().replace(/[/.]/g, "-");
+  const projDir = join(paths.claudeDir, "projects", slug);
+  if (!existsSync(projDir)) return null;
+  try {
+    const files = readdirSync(projDir)
+      .filter((f) => f.endsWith(".jsonl"))
+      .map((f) => ({ f, m: statSync(join(projDir, f)).mtimeMs }));
+    const newest = maxBy(files, (x) => x.m);
+    return newest ? newest.f.replace(/\.jsonl$/, "") : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Interruptible countdown until `until`, shown in the terminal (claude is dead,
+ *  so the statusLine can't render it). Ctrl-C resumes immediately. */
+async function countdownWait(acct: string, until: number): Promise<void> {
+  let aborted = false;
+  const onInt = () => { aborted = true; };
+  process.on("SIGINT", onInt);
+  process.stdout.write(`\n\x1b[36m⏳ tokenmaxxing: all accounts at their limit. Resuming on ${acct} when it resets (Ctrl-C to resume now).\x1b[0m\n`);
+  while (!aborted && Date.now() < until) {
+    const left = until - Date.now();
+    const m = Math.floor(left / 60000);
+    const s = Math.floor((left % 60000) / 1000);
+    process.stdout.write(`\r\x1b[36m   resuming in ${m}m ${String(s).padStart(2, "0")}s \x1b[0m`);
+    await Bun.sleep(1000);
+  }
+  process.removeListener("SIGINT", onInt);
+  process.stdout.write(`\n\x1b[36m↻ resuming on ${acct}…\x1b[0m\n`);
+}
+
+/** Entry point: `claude ...args`. */
+export async function runSupervisor(argv: string[]): Promise<number> {
+  const real = resolveRealClaude();
+  const info = analyzeArgs(argv);
+
+  // Pass-through: no session management, no respawn - exact stock behavior.
+  if (!info.manage) {
+    const p = Bun.spawn([real, ...argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit" });
+    await p.exited;
+    return p.exitCode ?? (p.signalCode ? 1 : 0);
+  }
+
+  // Decide the managed session id + whether we're resuming an existing one.
+  let base = stripSessionFlags(argv);
+  let sid: string;
+  let resuming = false;
+  if (info.sessionId) {
+    sid = info.sessionId;
+  } else if (info.resumeId) {
+    sid = info.resumeId;
+    resuming = true;
+  } else if (info.continueLatest) {
+    const latest = latestSessionForCwd();
+    if (latest) { sid = latest; resuming = true; } else sid = crypto.randomUUID();
+  } else {
+    sid = crypto.randomUUID();
+  }
+
+  // Restore the original launch flags when resuming a session with none given
+  // this time (a bare `claude --resume <id>`, or the depleted-pool recovery).
+  if (resuming && base.length === 0) {
+    const persisted = loadSessionFlags(sid);
+    if (persisted) base = persisted;
+  }
+  saveSessionFlags(sid, base, process.cwd());
+
+  let launchArgs = resuming ? ["--resume", sid, ...base] : ["--session-id", sid, ...base];
+
+  mkdirSync(paths.respawnDir, { recursive: true });
+  const marker = join(paths.respawnDir, sid);
+  const savedTermios = saveTermios();
+
+  // Supervisor survives the SIGINT/SIGHUP that flow to the foreground group;
+  // claude (the child, same pgrp) receives and handles them itself.
+  process.on("SIGINT", () => {});
+  process.on("SIGHUP", () => {});
+
+  let respawns = 0;
+  while (true) {
+    if (existsSync(marker)) rmSync(marker, { force: true });
+    log("supervisor.launch", { sid, respawns, args: launchArgs.join(" ") });
+
+    const child = Bun.spawn([real, ...launchArgs], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { ...process.env, TOKENMAXXING_SUPERVISED: "1", TOKENMAXXING_SESSION_ID: sid },
+    });
+
+    // Race the child's own exit against the appearance of a respawn marker.
+    let done = false;
+    const markerWatch = (async () => {
+      while (!done) {
+        if (await Bun.file(marker).exists()) return true;
+        await Bun.sleep(150);
+      }
+      return false;
+    })();
+    const exited = child.exited.then(() => { done = true; return "exit" as const; });
+    const winner = await Promise.race([exited, markerWatch.then((m) => (m ? "marker" : "exit"))]);
+
+    if (winner === "marker") {
+      child.kill(); // SIGTERM at the committed turn boundary
+    }
+    await child.exited;
+    done = true;
+    await markerWatch.catch(() => {});
+    restoreTermios(savedTermios);
+
+    if (existsSync(marker)) {
+      const m = RespawnMarkerSchema.parse(await Bun.file(marker).json());
+      rmSync(marker, { force: true });
+      respawns++;
+      if (m.waitUntil && m.waitUntil > Date.now()) await countdownWait(m.account, m.waitUntil);
+      else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming…\x1b[0m\n`);
+      launchArgs = ["--resume", sid, ...base];
+      continue;
+    }
+    return child.exitCode ?? (child.signalCode ? 1 : 0);
+  }
+}

package/src/lib/atomic.ts

@@ -0,0 +1,24 @@
+// Atomic file writes (temp + rename on the same filesystem) and small fs utils.
+
+import { closeSync, mkdirSync, openSync, renameSync, writeSync, fsyncSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Write `data` to `file` atomically: write a sibling temp file, fsync it, then
+ * rename over the target. A concurrent reader sees either the old or new file,
+ * never a partial one.
+ */
+export function writeFileAtomic(file: string, data: string | Uint8Array, mode = 0o600): void {
+  const dir = dirname(file);
+  mkdirSync(dir, { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}.${Math.floor(Math.random() * 1e9).toString(36)}`;
+  const bytes = data instanceof Uint8Array ? data : new TextEncoder().encode(data);
+  const fd = openSync(tmp, "wx", mode);
+  try {
+    writeSync(fd, bytes);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  renameSync(tmp, file);
+}

package/src/lib/claudebin.ts

@@ -0,0 +1,21 @@
+// Resolve the REAL claude binary (never our shim on PATH).
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { paths } from "./paths.ts";
+import { loadConfig } from "./state.ts";
+
+export function resolveRealClaude(): string {
+  const cfg = loadConfig();
+  if (cfg.claudeBin && existsSync(cfg.claudeBin)) return cfg.claudeBin;
+  if (process.env.TOKENMAXXING_CLAUDE_BIN && existsSync(process.env.TOKENMAXXING_CLAUDE_BIN))
+    return process.env.TOKENMAXXING_CLAUDE_BIN;
+  for (const d of (process.env.PATH ?? "").split(":")) {
+    if (!d || d === paths.binDir) continue;
+    const cand = join(d, "claude");
+    try {
+      if (existsSync(cand) && statSync(cand).isFile()) return cand;
+    } catch { /* ignore */ }
+  }
+  throw new Error("could not locate the real `claude` binary (set claudeBin in config.json)");
+}