tokenmaxxing 0.6.1 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Automatic Claude Code account switching: pool multiple accounts and hot-swap when quota fills, resuming your session on the fresh account.",
   "type": "module",
   "license": "MIT",
@@ -19,7 +19,7 @@
     "DESIGN.md"
   ],
   "engines": {
-    "bun": ">=1.1.0"
+    "bun": ">=1.2.6"
   },
   "os": ["darwin", "linux"],
   "scripts": {

package/src/cli/doctor.ts

@@ -1,9 +1,10 @@
 // `tokenmaxxing doctor` - verify the supervisor + three settings entries survived
 // and the pool is healthy.
 
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
+import { verifyRealClaude } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
-import { checkTimerHealthy, isBinDirAhead, timerActivationHint } from "../lib/install.ts";
+import { checkTimerHealthy, findClaudeShadowers, isBinDirAhead, shellRcPath, timerActivationHint } from "../lib/install.ts";
 import { paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
 import { readItem, liveTarget, parkedTarget } from "../lib/credstore.ts";
@@ -74,6 +75,24 @@ export async function cmdDoctor(): Promise<number> {
 
   const cfg = loadConfig();
   check(!!cfg.claudeBin && existsSync(cfg.claudeBin), "real claude binary resolved", "set claudeBin in config.json");
+  if (cfg.claudeBin && existsSync(cfg.claudeBin)) {
+    // Behavioral: the pin must answer --version without re-entering the wrapper.
+    // Catches a poisoned pin (a shim that resolves `claude` back to us) that
+    // existence checks cannot - the 2026-07-12 recursive-spawn incident.
+    const fail = verifyRealClaude(cfg.claudeBin);
+    check(fail === null, "claudeBin launches the real claude", fail ?? undefined);
+  }
+
+  // Warnings only: an interactive alias/function can shadow or bypass the
+  // wrapper in ways PATH checks cannot see (`alias claude=...`, or a `cc`-style
+  // alias hardcoding an absolute path to the real binary).
+  const rc = shellRcPath();
+  if (rc && existsSync(rc)) {
+    for (const s of findClaudeShadowers(readFileSync(rc, "utf8"))) {
+      if (s.kind === "shadow") console.log(c.yellow(`⚠ ${rc}: \`${s.line}\` shadows the supervised claude wrapper - launches through it skip tokenmaxxing`));
+      else console.log(c.yellow(`⚠ ${rc}: alias \`${s.name}\` hardcodes a claude path and bypasses the supervisor - use plain \`claude\` in its body instead`));
+    }
+  }
 
   console.log();
   console.log(ok ? c.green("all good ✓") : c.yellow("issues found - see above"));

package/src/cli/init.ts

@@ -7,7 +7,7 @@ import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "..
 import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg } from "../lib/oauth.ts";
 import { loadAccounts, saveAccounts, loadConfig, saveConfig } from "../lib/state.ts";
 import { installSupervisor, shellRcPath, ensurePathInRc, timerActivationHint, type InstallOutcome } from "../lib/install.ts";
-import { resolveRealClaude } from "../lib/claudebin.ts";
+import { resolveVerifiedClaude } from "../lib/claudebin.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, type Account } from "../lib/types.ts";
 import { c } from "./render.ts";
@@ -40,9 +40,11 @@ export async function cmdInit(): Promise<number> {
   if (existingIdx.accounts.length > 0) {
     const out = installSupervisor();
     // repair the claudeBin pin too - hooks run with claude's PATH and must
-    // never have to guess which binary is the real claude.
+    // never have to guess which binary is the real claude. Verified pinning:
+    // a pin that fails --version (or loops back into the wrapper) is replaced
+    // by a fresh PATH scan instead of being re-saved.
     const cfg = loadConfig();
-    cfg.claudeBin = resolveRealClaude();
+    cfg.claudeBin = resolveVerifiedClaude();
     saveConfig(cfg);
     const active = existingIdx.accounts.find((a) => a.accountUuid === existingIdx.activeAccountUuid);
     console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
@@ -112,7 +114,7 @@ export async function cmdInit(): Promise<number> {
   saveAccounts(idx);
 
   const cfg = loadConfig();
-  cfg.claudeBin = resolveRealClaude();
+  cfg.claudeBin = resolveVerifiedClaude();
   saveConfig(cfg);
 
   const out = installSupervisor();

package/src/entries/supervisor.ts

@@ -11,7 +11,7 @@ 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 { LOOP_DIAGNOSIS, MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, WRAP_RATE_MAX, WRAP_RATE_WINDOW_MS, resolveRealClaude, wrapDepth, wrapperEntryRateTripped } from "../lib/claudebin.ts";
 import { saveTermios, restoreTermios } from "../lib/tty.ts";
 import { loadSessionFlags, saveSessionFlags } from "../lib/sessions.ts";
 import { RespawnMarkerSchema } from "../lib/types.ts";
@@ -111,12 +111,33 @@ async function countdownWait(acct: string, until: number): Promise<void> {
 
 /** Entry point: `claude ...args`. */
 export async function runSupervisor(argv: string[]): Promise<number> {
+  // Depth cap: every spawn below tags its child, so a claudeBin that leads back
+  // here (pinned shim re-execing `claude` from PATH) dies at a handful of
+  // processes instead of fork-bombing the machine (2026-07-12 incident).
+  const depth = wrapDepth();
+  if (depth >= MAX_WRAP_DEPTH) {
+    console.error(
+      `tokenmaxxing: ${LOOP_DIAGNOSIS} (depth ${depth}) - claudeBin in ${paths.configJson} does not launch the real Claude binary. Fix claudeBin, then run \`tokenmaxxing doctor\`.`,
+    );
+    log("supervisor.loop_abort", { depth });
+    return 1;
+  }
+  // Rate backstop: an env-sanitizing shim in the loop strips the sentinel, but
+  // it cannot erase the on-disk entry counter.
+  if (wrapperEntryRateTripped(Date.now())) {
+    console.error(
+      `tokenmaxxing: ${LOOP_DIAGNOSIS} (over ${WRAP_RATE_MAX} wrapper entries in ${WRAP_RATE_WINDOW_MS / 1000}s) - claudeBin in ${paths.configJson} does not launch the real Claude binary. Fix claudeBin, then run \`tokenmaxxing doctor\`.`,
+    );
+    log("supervisor.rate_abort", { max: WRAP_RATE_MAX });
+    return 1;
+  }
   const real = resolveRealClaude();
   const info = analyzeArgs(argv);
+  const childEnv = { ...process.env, [WRAP_DEPTH_ENV]: String(depth + 1) };
 
   // 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" });
+    const p = Bun.spawn([real, ...argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: childEnv });
     await p.exited;
     return p.exitCode ?? (p.signalCode ? 1 : 0);
   }
@@ -165,7 +186,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       stdin: "inherit",
       stdout: "inherit",
       stderr: "inherit",
-      env: { ...process.env, TOKENMAXXING_SUPERVISED: "1", TOKENMAXXING_SESSION_ID: sid },
+      env: { ...childEnv, TOKENMAXXING_SUPERVISED: "1", TOKENMAXXING_SESSION_ID: sid },
     });
 
     // Race the child's own exit against the appearance of a respawn marker.

package/src/lib/claudebin.ts

@@ -1,26 +1,169 @@
 // Resolve the REAL claude binary (never our shim on PATH).
 
-import { existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { uniq } from "es-toolkit";
+import { z } from "zod";
 import { paths } from "./paths.ts";
 import { loadConfig } from "./state.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+/** How many tokenmaxxing wrappers sit above this process. Every supervisor
+ *  spawn increments it in the child env; the wrapper refuses to run at the cap,
+ *  so ANY claudeBin indirection that leads back to the wrapper (a pinned shim
+ *  that re-execs `claude` from PATH) dies in a handful of processes instead of
+ *  fork-bombing the machine (2026-07-12: ~1800 runaway bun processes). */
+export const WRAP_DEPTH_ENV = "TOKENMAXXING_WRAP_DEPTH";
+export const MAX_WRAP_DEPTH = 5;
+/** Stable fragment of the loop-abort diagnostic; verifyRealClaude greps a
+ *  child's stderr for it to name the failure precisely. */
+export const LOOP_DIAGNOSIS = "wrapper re-entered without reaching the real claude";
+
+export function wrapDepth(env: Record<string, string | undefined> = process.env): number {
+  const n = Number(env[WRAP_DEPTH_ENV] ?? "");
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+/** Non-env backstop for the depth sentinel: an env-sanitizing shim in the loop
+ *  (env -i / corporate launchers) strips the sentinel every cycle, so the
+ *  wrapper ALSO counts its own entries in an on-disk sliding window that no
+ *  child environment can erase. A self-spawn loop sustains several entries per
+ *  second indefinitely; legitimate bursts (a tmux session restore launching
+ *  dozens of panes) land once and go quiet, staying far under the cap. */
+export const WRAP_RATE_MAX = 60;
+export const WRAP_RATE_WINDOW_MS = 30_000;
+const SpawnRateSchema = z.object({ entries: z.array(z.number()) });
+
+export function wrapperEntryRateTripped(now: number): boolean {
+  const file = join(paths.home, "spawnrate.json");
+  let entries: number[] = [];
+  try {
+    entries = SpawnRateSchema.parse(JSON.parse(readFileSync(file, "utf8"))).entries;
+  } catch { /* absent or corrupt - start a fresh window */ }
+  entries = entries.filter((t) => now - t < WRAP_RATE_WINDOW_MS);
+  entries.push(now);
+  try {
+    mkdirSync(paths.home, { recursive: true });
+    writeFileAtomic(file, JSON.stringify({ entries }));
+  } catch { /* an unwritable home must never block launching claude */ }
+  return entries.length > WRAP_RATE_MAX;
+}
+
+function realpathOrNull(p: string): string | null {
+  try {
+    return realpathSync(p);
+  } catch {
+    return null;
+  }
+}
+
+/** True when `bin` IS tokenmaxxing (the `claude` wrapper, the `xx` alias, or the
+ *  installed binary, via any symlink): spawning it as claude recurses through
+ *  the supervisor. Realpath-based - a trailing slash, a symlinked dir, or a
+ *  symlink to the wrapper must not defeat it the way the old exact-string
+ *  binDir compare could. */
+export function pointsBackAtUs(bin: string): boolean {
+  const resolved = realpathOrNull(bin);
+  const binDir = realpathOrNull(paths.binDir);
+  return resolved != null && binDir != null && dirname(resolved) === binDir;
+}
+
+/** Every PATH `claude` that is not us, in PATH order, deduped by realpath.
+ *  All of them, not just the first: a user-made wrapper script named claude can
+ *  sit ahead of the real binary, and verified resolution must be able to walk
+ *  past it. */
+export function scanPathForClaudeCandidates(): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const d of (process.env.PATH ?? "").split(":")) {
+    if (!d) continue;
+    const cand = join(d, "claude");
+    try {
+      if (existsSync(cand) && statSync(cand).isFile() && !pointsBackAtUs(cand)) {
+        const key = realpathOrNull(cand) ?? cand;
+        if (!seen.has(key)) {
+          seen.add(key);
+          out.push(cand);
+        }
+      }
+    } catch { /* ignore */ }
+  }
+  return out;
+}
+
+/** First PATH entry with a `claude` that is not us. null when PATH has none. */
+export function scanPathForClaude(): string | null {
+  return scanPathForClaudeCandidates()[0] ?? null;
+}
 
 export function resolveRealClaude(): string {
   const cfg = loadConfig();
   if (cfg.claudeBin) {
-    if (existsSync(cfg.claudeBin)) return cfg.claudeBin;
     // A configured-but-vanished binary must not silently degrade to the PATH
     // scan: under a relocated TOKENMAXXING_HOME the scan's binDir guard misses
     // the installed wrapper, which then recurses through the supervisor
     // (observed 2026-07-12 as a forever-hung `/usage` probe).
-    throw new Error(`configured claudeBin does not exist: ${cfg.claudeBin} - fix config.json`);
+    if (!existsSync(cfg.claudeBin)) {
+      throw new Error(`configured claudeBin does not exist: ${cfg.claudeBin} - fix config.json`);
+    }
+    // A pin that leads back to us is the recursion incident, not a claude.
+    if (pointsBackAtUs(cfg.claudeBin)) {
+      throw new Error(
+        `configured claudeBin (${cfg.claudeBin}) is tokenmaxxing's own wrapper - spawning it recurses. Point claudeBin at the real claude binary in ${paths.configJson}`,
+      );
+    }
+    return cfg.claudeBin;
   }
-  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 */ }
+  const scanned = scanPathForClaude();
+  if (scanned) return scanned;
+  throw new Error("could not locate the real `claude` binary (set claudeBin in config.json)");
+}
+
+/** Behavioral check used by init/doctor before trusting a pin: the binary must
+ *  answer `--version` without re-entering this wrapper. Depth is preset to the
+ *  cap so an indirection back into us aborts on its FIRST wrapper entry instead
+ *  of recursing. Returns null when the binary passes, else the failure detail. */
+export function verifyRealClaude(bin: string): string | null {
+  const env = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH), TOKENMAXXING_PROBE: "1" };
+  let p: ReturnType<typeof Bun.spawnSync>;
+  try {
+    // spawnSync throws on an unrunnable path (ENOENT/EACCES) - that is a
+    // verification failure to report, not a crash. SIGKILL: a TERM-trapping
+    // candidate must not hang the very repair commands (init/doctor) that the
+    // loop-abort diagnostic points the user at.
+    p = Bun.spawnSync([bin, "--version"], { env, stdout: "pipe", stderr: "pipe", timeout: 15_000, killSignal: "SIGKILL" });
+  } catch (e) {
+    return String((e as Error).message ?? e);
+  }
+  const outText = (p.stdout?.toString() ?? "").trim();
+  const err = (p.stderr?.toString() ?? "").trim();
+  if (p.exitCode === 0) {
+    // exit 0 only proves something ran; the output must identify as claude
+    // ("2.1.207 (Claude Code)" on 2.1.207) or the pin is some other program.
+    if (/claude/i.test(outText)) return null;
+    return `--version output does not identify claude: "${outText.slice(0, 80)}"`;
+  }
+  if (err.includes(LOOP_DIAGNOSIS)) return "it leads back into the tokenmaxxing wrapper (recursion)";
+  return `--version exited ${p.exitCode ?? "on signal/timeout"}: ${(err || outText).slice(0, 160)}`;
+}
+
+/** Resolution for `init`'s pin: resolve, then behaviorally verify. A configured
+ *  bin that fails verification (e.g. a shim pinned by an old version) falls back
+ *  to the PATH scan, and the scan walks past failing candidates (a user-made
+ *  claude wrapper ahead of the real binary) instead of giving up on the first. */
+export function resolveVerifiedClaude(): string {
+  const candidates: string[] = [];
+  try {
+    candidates.push(resolveRealClaude());
+  } catch { /* broken config - the scan below is init's repair path */ }
+  candidates.push(...scanPathForClaudeCandidates());
+
+  const failures: string[] = [];
+  for (const cand of uniq(candidates)) {
+    const fail = verifyRealClaude(cand);
+    if (fail === null) return cand;
+    failures.push(`${cand}: ${fail}`);
   }
+  if (failures.length > 0) throw new Error(`no usable claude binary found:\n  ${failures.join("\n  ")}`);
   throw new Error("could not locate the real `claude` binary (set claudeBin in config.json)");
 }

package/src/lib/install.ts

@@ -204,6 +204,42 @@ export function ensurePathInRc(rc: string): "added" | "present" {
   return "added";
 }
 
+const ShellShadowerSchema = z.object({
+  /** shadow: a `claude` alias/function hides the wrapper entirely.
+   *  bypass: another alias (e.g. `cc`, `cco`) hardcodes an absolute path to a
+   *  claude binary, so launches through it skip supervision. */
+  kind: z.enum(["shadow", "bypass"]),
+  name: z.string(),
+  line: z.string(),
+});
+export type ShellShadower = z.infer<typeof ShellShadowerSchema>;
+
+/** Scan shell-rc text for aliases/functions that shadow `claude` or hardcode a
+ *  path to a claude binary. Aliases whose body starts with plain `claude` are
+ *  fine (they expand through PATH into the wrapper); an absolute path is not.
+ *  Lines referencing the wrapper itself are deliberate and skipped. */
+export function findClaudeShadowers(rcText: string): ShellShadower[] {
+  const out: ShellShadower[] = [];
+  const absClaude = /(?:^|[\s"'=])(\/[^\s"']*\/claude)(?:[\s"']|$)/;
+  for (const rawLine of rcText.split("\n")) {
+    const line = rawLine.trim();
+    if (line.startsWith("#") || line.includes(paths.supervisorLink)) continue;
+    const alias = line.match(/^alias\s+([A-Za-z0-9_-]+)=(.*)$/);
+    if (alias) {
+      if (alias[1] === "claude") {
+        out.push(ShellShadowerSchema.parse({ kind: "shadow", name: "claude", line }));
+      } else if (absClaude.test(alias[2]!)) {
+        out.push(ShellShadowerSchema.parse({ kind: "bypass", name: alias[1]!, line }));
+      }
+      continue;
+    }
+    if (/^(?:function\s+)?claude\s*\(\)/.test(line)) {
+      out.push(ShellShadowerSchema.parse({ kind: "shadow", name: "claude", line }));
+    }
+  }
+  return out;
+}
+
 export function uninstallSupervisor(): void {
   uninstallSettings();
   uninstallCheckTimer();

package/src/lib/usage.ts

@@ -6,7 +6,7 @@
 
 import { delay } from "es-toolkit";
 import { z } from "zod";
-import { resolveRealClaude } from "./claudebin.ts";
+import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealClaude } from "./claudebin.ts";
 import { log } from "./log.ts";
 import { RateLimitsStdinSchema, UsageWindowSchema, type ModelInfo, type UsageWindow, type UsageWindows } from "./types.ts";
 
@@ -212,6 +212,8 @@ const CRED_ENV_OVERRIDES = [
  *  Stop/SessionStart hooks or the status flock forever; a healthy `/usage`
  *  answers in seconds. */
 const PROBE_KILL_MS = 60_000;
+/** How long after the child's death to keep waiting for pipe EOF. */
+const PIPE_GRACE_MS = 2_000;
 
 async function probeUsageOnce(env: Record<string, string>, now: number): Promise<FullUsage | null> {
   let out: string;
@@ -221,15 +223,30 @@ async function probeUsageOnce(env: Record<string, string>, now: number): Promise
       stdout: "pipe",
       stderr: "pipe",
     });
-    const killer = setTimeout(() => p.kill(), PROBE_KILL_MS);
+    // SIGKILL: claude traps SIGTERM, and a wedged probe child that survives the
+    // kill would keep p.exited pending and re-wedge the read race below.
+    const killer = setTimeout(() => p.kill("SIGKILL"), PROBE_KILL_MS);
     try {
-      out = await new Response(p.stdout).text();
-      const errText = await new Response(p.stderr).text();
+      // Descendants inherit the output pipes, so EOF can lag the child's death
+      // or never arrive at all - a leaked grandchild holding the pipe wedged
+      // the 2026-07-12 probes forever, defeating the kill guard above. Bound
+      // the reads by child-exit + grace instead of awaiting EOF unconditionally.
+      const reads = Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
+      const settled = await Promise.race([
+        reads,
+        p.exited.then(() => delay(PIPE_GRACE_MS)).then(() => null),
+      ]);
+      if (settled === null) {
+        log("usage.probe_failed", { err: "output pipes still open after child exit (leaked descendant)" });
+        return null;
+      }
+      const [text, errText] = settled;
       await p.exited;
       if (p.exitCode !== 0) {
         log("usage.probe_failed", { exit: p.exitCode ?? "signal", stderr: errText.trim().slice(0, 200) });
         return null;
       }
+      out = text;
     } finally {
       clearTimeout(killer);
     }
@@ -269,7 +286,11 @@ const PROBE_RETRY_DELAYS_MS = [2000, 5000];
  * transient, so retry with backoff. Returns null if it never yields data.
  */
 export async function probeUsage(configDir?: string, now = Date.now()): Promise<FullUsage | null> {
-  const env: Record<string, string> = { ...process.env, TOKENMAXXING_PROBE: "1" };
+  // The probe spawns the real claude DIRECTLY - it never legitimately passes
+  // through the wrapper again. Preset the depth to the cap so a poisoned pin
+  // that leads back to the wrapper aborts on its first entry (the 2026-07-12
+  // ~1800-process recursion started as exactly this probe).
+  const env: Record<string, string> = { ...process.env, TOKENMAXXING_PROBE: "1", [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) };
   for (const k of CRED_ENV_OVERRIDES) delete env[k];
   if (configDir) env.CLAUDE_CONFIG_DIR = configDir;