tokenmaxxing 0.6.0 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.6.0",
+  "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/cli/status.ts

@@ -92,7 +92,7 @@ export async function cmdStatus(): Promise<number> {
     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 }))
+    if (isExhausted(a, { now, threshold: cfg.threshold, currentAccountUuid: idx.activeAccountUuid, switchFamilies: cfg.policy.switchModels }))
       badges.push(c.yellow("exhausted"));
 
     console.log(`${marker} ${c.bold(a.label || a.email)} ${badges.join(" ")}`);

package/src/cli/switch.ts

@@ -58,7 +58,8 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     }
 
     // auto: greedy over everyone, current included - a no-op when current wins.
-    const everyone: PickCtx = { now, threshold: cfg.threshold, currentAccountUuid: null };
+    // No session context here, so every configured per-model family gates.
+    const everyone: PickCtx = { now, threshold: cfg.threshold, currentAccountUuid: null, switchFamilies: cfg.policy.switchModels };
     const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid) ?? null;
     const best = pickBest(idx.accounts, everyone);
     const currentWins =
@@ -72,7 +73,7 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       return 0;
     }
     if (best) {
-      const landed = await chooseAndSwap({ now, threshold: cfg.threshold });
+      const landed = await chooseAndSwap({ now, threshold: cfg.threshold, switchFamilies: cfg.policy.switchModels });
       if (landed) {
         console.log(`${c.green("↻")} switched to ${c.bold(landed.label)}`);
         return 0;
@@ -84,7 +85,16 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     // hence the reload). Stay on / switch to whichever recovers soonest.
     const fresh = loadAccounts();
     const earliest = pickEarliestReset(fresh.accounts, everyone);
-    if (!earliest) { console.error(c.yellow("no switchable account (all need re-auth?)")); return 1; }
+    if (!earliest) {
+      // Either every account needs re-auth, or every account is blocked with no
+      // recoverable bound (unparsed reset clocks AND no sample time - see log).
+      const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
+      if (reauth.length > 0) { console.error(c.yellow(`no switchable account - re-auth needed: ${reauth.join(", ")}`)); return 1; }
+      // never freeze a label drift behind a no-op (see header).
+      if (drifted && active) return swapTo(active);
+      console.log(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"));
+      return 0;
+    }
     const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
     const reauthNote = reauth.length ? ` - re-auth needed: ${reauth.join(", ")}` : "";
     if (earliest.account.accountUuid === fresh.activeAccountUuid && !drifted) {

package/src/entries/sessionstart.ts

@@ -1,8 +1,8 @@
 // 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.
+// Right after a respawn, the post-swap cooldown in evaluateAndMaybeSwap makes
+// this correctly no-op.
 
 import { z } from "zod";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";

package/src/entries/statusline.ts

@@ -17,7 +17,7 @@ import { sortBy } from "es-toolkit";
 import { z } from "zod";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { loadAccounts, loadConfig, loadLastSwapAt, loadModelUsage, writeUsage } from "../lib/state.ts";
-import { familyTokens, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
+import { familyTokens, gatedFamilies, matchedFamily, parseStatusLineStdin, parseStatusLineModel } from "../lib/usage.ts";
 import { isExhausted, swapPreference, weeklyExpiry } from "../lib/picker.ts";
 import { worktreeName } from "../lib/worktree.ts";
 import { fmtResetShort, makeColors } from "../cli/render.ts";
@@ -105,7 +105,12 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
         : "";
 
   // ---- parked accounts, in swap order: the first usable ◇ is the next target
-  const pickCtx = { now: ctx.now, threshold: ctx.threshold, currentAccountUuid: ctx.accounts.activeAccountUuid };
+  const pickCtx = {
+    now: ctx.now,
+    threshold: ctx.threshold,
+    currentAccountUuid: ctx.accounts.activeAccountUuid,
+    switchFamilies: gatedFamilies(parseStatusLineModel(stdinObj), ctx.switchModels),
+  };
   const parked = sortBy(
     ctx.accounts.accounts.filter((a) => a.accountUuid !== ctx.accounts.activeAccountUuid),
     [(a) => (a.needsReauth || isExhausted(a, pickCtx) ? 1 : 0), ...swapPreference(ctx.now)],

package/src/entries/stophook.ts

@@ -30,7 +30,10 @@ export async function runStopHook(): Promise<number> {
     (parsed.success ? parsed.data.session_id : undefined) ?? process.env.TOKENMAXXING_SESSION_ID;
 
   try {
-    const decision = await evaluateAndMaybeSwap();
+    // Anticipatory depleted swaps are only sane when the respawn marker below
+    // will actually pause the session until the reset.
+    const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && sessionId != null;
+    const decision = await evaluateAndMaybeSwap(Date.now(), canPause);
     // 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 });

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/decide.ts

@@ -1,11 +1,16 @@
-// Shared switch decision used by both the Stop hook and the SessionStart hook.
-// Cheap pre-check off the lock; the authoritative re-check + swap under the flock.
+// Shared switch decision used by the Stop/SessionStart hooks and the periodic
+// `check` timer. Cheap pre-check off the lock; the authoritative re-check + swap
+// under the flock.
 //
 // Two limit families are checked, both metered against the CURRENTLY-active org:
-//   1. AGGREGATE windows (session=five_hour, week-all=seven_day) from statusLine.
-//   2. PER-MODEL weekly cap (e.g. "week (Fable)") - only when the active model is
-//      capacity-constrained (config policy.switchModels). This isn't in statusLine,
-//      so we read it from `claude -p '/usage'`, TTL-cached (not every turn).
+//   1. AGGREGATE windows (session=five_hour, week-all=seven_day). A rendering
+//      statusLine tees them fresh every turn; when nothing renders (headless
+//      boxes, idle TUIs) they come from `claude -p '/usage'`, re-probed once the
+//      snapshot ages past the poll TTL so they can never freeze at a stale value.
+//   2. PER-MODEL weekly cap (e.g. "week (Fable)") - when the active model is
+//      capacity-constrained (config policy.switchModels), or for EVERY configured
+//      family when the model is unknown (nothing rendered within the TTL, so the
+//      session that stamped the last model may be gone).
 //
 // The org guard is load-bearing: right after a respawn, usage.json still reflects
 // the OLD account, so org != activeOrg → we correctly do nothing until fresh usage
@@ -15,14 +20,14 @@ import { maxBy } from "es-toolkit";
 import { z } from "zod";
 import { withLock } from "./lock.ts";
 import { paths } from "./paths.ts";
-import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts, saveModelUsage, writeUsage } from "./state.ts";
+import { loadAccounts, loadConfig, loadLastSwapAt, loadUsage, loadModelUsage, saveAccounts, saveModelUsage, usageTeeAt, writeUsage } from "./state.ts";
 import { readOAuthAccount } from "./claudejson.ts";
 import { chooseAndSwap, performSwap } from "./swap.ts";
 import { pickEarliestReset, usableAt } from "./picker.ts";
 import { InvalidGrantError } from "./oauth.ts";
-import { familyTokens, matchedFamily, probeUsage } from "./usage.ts";
+import { familyTokens, gatedFamilies, probeUsage } from "./usage.ts";
 import { log } from "./log.ts";
-import { AccountSchema, type Account, type Config, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
+import { AccountSchema, ModelUsageStateSchema, UsageStateSchema, type Account, type Config, type ModelUsageState, type UsageState, type UsageWindow } from "./types.ts";
 
 const SwapDecisionSchema = z.object({
   swapped: z.boolean(),
@@ -33,75 +38,130 @@ const SwapDecisionSchema = z.object({
 });
 export type SwapDecision = z.infer<typeof SwapDecisionSchema>;
 
-/** Cold-start aggregate fallback when statusLine hasn't written usage.json yet. */
-async function probeAggregate(org: string | null): Promise<UsageState | null> {
-  const full = await probeUsage();
-  if (!full) return null;
-  return { fiveHour: full.session, sevenDay: full.weekAll, org, ts: Date.now(), model: null };
-}
-
-/** Ensure a fresh-enough per-model cache for the active org; poll `/usage` if stale. */
-async function ensurePerModel(cfg: Config, org: string | null): Promise<ModelUsageState | null> {
-  const cached = loadModelUsage();
-  const fresh = cached && cached.org === org && Date.now() - cached.ts < cfg.policy.usagePollTtlMs;
-  if (fresh) return cached;
-  const full = await probeUsage();
-  if (!full) {
-    // Probing the live token fail-silently while it's busy is expected; stamp the
-    // cache so the next probe waits out the TTL instead of every turn re-paying
-    // the full backoff (the 2026-07-10 post-swap probe storm).
-    saveModelUsage({ perModel: cached?.org === org ? cached.perModel : {}, org, ts: Date.now() });
-    return cached;
-  }
-  const state: ModelUsageState = { perModel: full.perModel, org, ts: Date.now() };
-  saveModelUsage(state);
-  return state;
+/** A window's usable-against percentage NOW: one whose cached reset has passed
+ *  is empty again, never a switch reason. */
+function liveUsed(w: UsageWindow, now: number): number {
+  return w.resetsAt != null && w.resetsAt <= now ? 0 : w.usedPercentage;
 }
 
 /** The family's weekly cap among the `/usage` rows; when several rows match the
- *  family, the most-used one wins (switching early beats metering a depleted cap). */
-function capForFamily(mu: ModelUsageState, family: string): UsageWindow | undefined {
+ *  family, the most-used LIVE one wins (switching early beats metering a depleted
+ *  cap, but a row whose reset passed must not mask a still-burning sibling). */
+function capForFamily(mu: ModelUsageState, family: string, now: number): UsageWindow | undefined {
   const rows = Object.entries(mu.perModel)
     .filter(([k]) => familyTokens(k).includes(family))
     .map(([, w]) => w);
-  return maxBy(rows, (w) => w.usedPercentage);
+  return maxBy(rows, (w) => liveUsed(w, now));
 }
 
 /** True if the active account is over the floor on ANY applicable limit. */
-function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, floor: number): boolean {
+function isOver(u: UsageState | null, mu: ModelUsageState | null, org: string | null, cfg: Config, floor: number, now: number): boolean {
   if (!u || !org || u.org !== org) return false;
-  if (u.fiveHour.usedPercentage >= floor || u.sevenDay.usedPercentage >= floor) return true;
-  const family = matchedFamily(u.model, cfg.policy.switchModels);
-  if (family && mu && mu.org === org) {
-    const cap = capForFamily(mu, family);
-    if (cap && cap.usedPercentage >= floor) return true;
+  if (liveUsed(u.fiveHour, now) >= floor || liveUsed(u.sevenDay, now) >= floor) return true;
+  if (mu && mu.org === org) {
+    for (const family of gatedFamilies(u.model, cfg.policy.switchModels)) {
+      const cap = capForFamily(mu, family, now);
+      if (cap && liveUsed(cap, now) >= floor) return true;
+    }
   }
   return false;
 }
 
-/** Does the active model warrant a per-model `/usage` poll? */
+/** Does a per-model cap gate the decision for this usage snapshot? */
 function needsPerModel(u: UsageState | null, cfg: Config): boolean {
-  return matchedFamily(u?.model ?? null, cfg.policy.switchModels) !== null;
+  return u != null && gatedFamilies(u.model, cfg.policy.switchModels).length > 0;
+}
+
+const SnapshotsSchema = z.object({
+  u: UsageStateSchema.nullable(),
+  mu: ModelUsageStateSchema.nullable(),
+});
+type Snapshots = z.infer<typeof SnapshotsSchema>;
+
+/** usage.json is trusted while the tee proved itself alive (mtime, NOT the
+ *  embedded ts - write-on-change lets ts age under an alive feed) within the
+ *  TTL for the live org. */
+function usageFresh(u: UsageState | null, org: string | null, ttl: number, now: number): boolean {
+  if (u == null || u.org !== org) return false;
+  const teeAt = usageTeeAt();
+  return teeAt != null && now - teeAt <= ttl;
+}
+
+/**
+ * Load the two usage snapshots, re-probing `/usage` (free, 0 tokens) when they
+ * are absent, org-drifted, or older than the poll TTL. ONE probe carries all
+ * three limit kinds, so a success refreshes BOTH files; anything less leaves a
+ * headless box (no rendering statusLine to tee) evaluating frozen or
+ * org-mismatched values forever - the 2026-07-12 stella blindness. The
+ * refreshed usage carries model: null (whatever session stamped the old model
+ * may be gone), which gates every configured family. model-usage.json's ts also
+ * stamps FAILED attempts, so a busy live token cannot cause a probe storm
+ * (2026-07-10): the next hook waits out the TTL instead of re-probing.
+ */
+async function loadFreshSnapshots(cfg: Config, org: string | null, now: number): Promise<Snapshots> {
+  let u = loadUsage();
+  let mu = loadModelUsage();
+  const ttl = cfg.policy.usagePollTtlMs;
+  const probeAttempted = mu != null && mu.org === org && now - mu.ts <= ttl;
+  if (org && !probeAttempted && (!usageFresh(u, org, ttl, now) || needsPerModel(u, cfg))) {
+    const full = await probeUsage();
+    const ts = Date.now();
+    // A swap can complete while the probe runs (no lock is held here). Its
+    // result would then be stamped under the pre-swap org over the files the
+    // swap just cleared - discard it; the locked re-check below rejects this
+    // evaluation anyway and the next one re-probes the new org.
+    if (readOAuthAccount()?.organizationUuid === org) {
+      if (full) {
+        // A probe takes seconds; a rendering session's tee may have landed
+        // while it ran. The tee is fresher AND model-aware, so it wins.
+        const teed = loadUsage();
+        if (usageFresh(teed, org, ttl, ts)) {
+          u = teed;
+        } else {
+          u = { fiveHour: full.session, sevenDay: full.weekAll, org, ts, model: null };
+          writeUsage(u);
+        }
+        mu = { perModel: full.perModel, org, ts };
+        saveModelUsage(mu);
+      } else {
+        mu = { perModel: mu?.org === org ? (mu?.perModel ?? {}) : {}, org, ts };
+        saveModelUsage(mu);
+      }
+    }
+  }
+  return { u, mu };
 }
 
-export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecision> {
+/** How long after a swap the auto paths hold still. The statusLine tee is
+ *  suppressed this long (sessions adopt the swap in <=30s), so a decision made
+ *  sooner runs model-blind on data the swap itself invalidated - that is how a
+ *  model-aware swap got immediately undone into an A<->B respawn loop. Manual
+ *  `switch` is unaffected. */
+const POST_SWAP_COOLDOWN_MS = 45_000;
+
+/**
+ * `anticipatory` allows the depleted path to swap onto an account that is still
+ * blocked but recovers soonest. Only a caller that can PAUSE until the reset
+ * (the supervised Stop hook, which writes a respawn marker the supervisor
+ * honors with a countdown) should pass true: from the check timer or an
+ * unsupervised hook, pre-parking silently yanks a live session onto a
+ * known-over-limit account, and buys nothing - the normal pick path adopts the
+ * recovering account the moment its reset passes.
+ */
+export async function evaluateAndMaybeSwap(now = Date.now(), anticipatory = false): Promise<SwapDecision> {
+  const lastSwapAt = loadLastSwapAt();
+  if (lastSwapAt != null && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) {
+    return { swapped: false, account: null, reason: "post-swap-cooldown" };
+  }
+
   const cfg = loadConfig();
   const floor = cfg.threshold - cfg.policy.projectionMargin;
   const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
 
-  let usage = loadUsage();
-  if (!usage && activeOrg) {
-    usage = await probeAggregate(activeOrg);
-    // Persist: post-swap the snapshots are cleared and the statusLine tee is in
-    // its grace window, so without this every turn boundary would re-probe.
-    if (usage) writeUsage(usage);
-  }
-
-  // per-model poll (TTL-cached) only when on a capacity-constrained model
-  const mu = needsPerModel(usage, cfg) ? await ensurePerModel(cfg, activeOrg) : null;
+  const { u: usage, mu } = await loadFreshSnapshots(cfg, activeOrg, now);
 
   // cheap pre-check off the lock - the common case exits here.
-  if (!isOver(usage, mu, activeOrg, cfg, floor)) {
+  if (!isOver(usage, mu, activeOrg, cfg, floor, now)) {
     return { swapped: false, account: null, reason: "under-threshold-or-stale" };
   }
 
@@ -118,24 +178,29 @@ export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecisi
         active.lastUsage = { fiveHour: u2.fiveHour, sevenDay: u2.sevenDay };
         active.lastUsageAt = u2.ts;
         // Snapshot per-model caps too, so they still show after we switch away.
-        if (mu2 && mu2.org === org2) active.lastPerModel = mu2.perModel;
+        // An empty map is a failed probe's anti-storm stamp, not a measurement -
+        // it must not erase the burnt-cap snapshot the picker screens on.
+        if (mu2 && mu2.org === org2 && Object.keys(mu2.perModel).length > 0) active.lastPerModel = mu2.perModel;
         saveAccounts(idx);
       }
     }
 
-    if (!isOver(u2, mu2, org2, cfg, floor)) {
+    if (!isOver(u2, mu2, org2, cfg, floor, now)) {
       return { swapped: false, account: null, reason: "raced-already-swapped" };
     }
 
-    const landed = await chooseAndSwap({ now, threshold: cfg.threshold });
+    // Candidates are screened by the same families that drove this decision, so
+    // the pool cannot ping-pong onto an account the gate would immediately flag.
+    const switchFamilies = gatedFamilies(u2?.model ?? null, cfg.policy.switchModels);
+    const landed = await chooseAndSwap({ now, threshold: cfg.threshold, switchFamilies });
     if (landed) return { swapped: true, account: landed, reason: "swapped" };
 
     // Every account is depleted. Wait for whichever recovers soonest (including the
     // current one), if that reset is within the auto-wait window.
     const fresh = loadAccounts();
-    const ctx = { now, threshold: cfg.threshold, currentAccountUuid: fresh.activeAccountUuid };
+    const ctx = { now, threshold: cfg.threshold, currentAccountUuid: fresh.activeAccountUuid, switchFamilies };
     const current = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid);
-    const currentAt = current ? usableAt(current, cfg.threshold, now) : Number.POSITIVE_INFINITY;
+    const currentAt = current ? usableAt(current, ctx) : Number.POSITIVE_INFINITY;
     const other = pickEarliestReset(fresh.accounts, ctx);
 
     let target: Account | null = null;
@@ -150,6 +215,10 @@ export async function evaluateAndMaybeSwap(now = Date.now()): Promise<SwapDecisi
     }
 
     const isCurrent = target.accountUuid === fresh.activeAccountUuid;
+    if (!isCurrent && !anticipatory) {
+      log("decide.depleted_no_park", { account: target.accountUuid.slice(0, 8), waitUntil });
+      return { swapped: false, account: null, reason: "all-depleted" };
+    }
     if (!isCurrent) {
       try {
         await performSwap(target);

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/picker.ts

@@ -9,26 +9,57 @@
 
 import { minBy, sortBy } from "es-toolkit";
 import { z } from "zod";
-import { AccountSchema, type Account } from "./types.ts";
+import { familyTokens } from "./usage.ts";
+import { AccountSchema, type Account, type UsageWindow } from "./types.ts";
 
 const PickCtxSchema = z.object({
   now: z.number(),
   threshold: z.number(),
   /** account to exclude (hooks switch AWAY from it); null ranks everyone. */
   currentAccountUuid: z.string().nullable(),
+  /** families whose per-model weekly cap counts toward exhaustion (from
+   *  gatedFamilies): a candidate with a burnt gated cap is no switch target -
+   *  landing on it would re-trigger the same gate and ping-pong the pool. */
+  switchFamilies: z.array(z.string()),
 });
 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);
+/** The account's cached per-model windows that belong to a gated family. */
+function gatedPerModelWindows(a: Account, families: string[]): UsageWindow[] {
+  return Object.entries(a.lastPerModel ?? {})
+    .filter(([model]) => families.some((f) => familyTokens(model).includes(f)))
+    .map(([, w]) => w);
 }
 
 const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+const FIVE_HOURS_MS = 5 * 60 * 60 * 1000;
+
+/** Epoch until which `w` blocks the account; anything <= now means it does not
+ *  block. A window with no known reset (unparsed clock) is still bounded by
+ *  its own duration past the sample time - a 5h window sampled 6h ago has
+ *  certainly reset - so a benched account always recovers by itself. With no
+ *  sample time either, it blocks indefinitely: guessing "usable now" would
+ *  swap onto it with waitUntil=now and churn kill/respawn. */
+function blockedUntil(w: UsageWindow, windowMs: number, sampledAt: number | undefined, ctx: PickCtx): number {
+  if (w.usedPercentage < ctx.threshold) return 0;
+  if (w.resetsAt != null) return w.resetsAt;
+  return sampledAt != null ? sampledAt + windowMs : Number.POSITIVE_INFINITY;
+}
+
+/** When each of the account's windows stops blocking: the two aggregates plus
+ *  the gated per-model caps. */
+function blockingUntil(a: Account, ctx: PickCtx): number[] {
+  const u = a.lastUsage;
+  return [
+    ...(u ? [blockedUntil(u.fiveHour, FIVE_HOURS_MS, a.lastUsageAt, ctx), blockedUntil(u.sevenDay, WEEK_MS, a.lastUsageAt, ctx)] : []),
+    ...gatedPerModelWindows(a, ctx.switchFamilies).map((w) => blockedUntil(w, WEEK_MS, a.lastUsageAt, ctx)),
+  ];
+}
+
+/** An account is "exhausted" if a window is >= threshold and hasn't reset yet. */
+export function isExhausted(a: Account, ctx: PickCtx): boolean {
+  return blockingUntil(a, ctx).some((t) => t > ctx.now);
+}
 
 /** Next occurrence of a weekly reset. The weekly reset is a fixed per-account
  *  anchor, so a cached (past) resetsAt extrapolates forward in 7-day steps -
@@ -59,25 +90,24 @@ export function pickBest(accounts: Account[], ctx: PickCtx): Account | null {
   return sortBy(usable, swapPreference(ctx.now))[0] ?? null;
 }
 
-/** 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;
+/** When an account becomes usable again: the latest blocking bound among its
+ *  windows (all must clear), or `now` if nothing blocks. Consistent with
+ *  isExhausted by construction (same blockingUntil). */
+export function usableAt(a: Account, ctx: PickCtx): number {
+  const blocking = blockingUntil(a, ctx).filter((t) => t > ctx.now);
+  return blocking.length ? Math.max(...blocking) : ctx.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. */
+ *  usable soonest. Accounts blocked with no known reset are unknowable, never
+ *  a wait target. */
 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) }));
+    .map((a) => ({ account: a, availableAt: usableAt(a, ctx) }))
+    .filter((x) => Number.isFinite(x.availableAt));
   return minBy(mapped, (x) => x.availableAt) ?? null;
 }

package/src/lib/state.ts

@@ -1,6 +1,6 @@
 // Config + accounts index + usage snapshot persistence. All writes atomic.
 
-import { existsSync, readFileSync, rmSync } from "node:fs";
+import { existsSync, readFileSync, rmSync, statSync, utimesSync } from "node:fs";
 import { isEqual } from "es-toolkit";
 import { z } from "zod";
 import { paths, realClaudeBinFromEnv } from "./paths.ts";
@@ -131,14 +131,37 @@ export function saveLastSwapAt(ts: number): void {
 const USAGE_TS_REFRESH_MS = 10 * 60_000;
 
 /** Write-on-change: skip the write (and its fsync) when only `ts` would differ,
- *  unless the stored `ts` has aged past the refresh window. */
+ *  unless the stored `ts` has aged past the refresh window. A suppressed write
+ *  still bumps the file's mtime (metadata only, no fsync): mtime is the feed's
+ *  liveness heartbeat, and without the bump an alive tee re-proving unchanged
+ *  figures reads as a dead feed and the decision path goes model-blind. */
 export function writeUsage(next: UsageState): boolean {
   const prev = loadUsage();
-  if (prev && isEqual({ ...prev, ts: 0 }, { ...next, ts: 0 }) && next.ts - prev.ts < USAGE_TS_REFRESH_MS) return false;
+  if (prev && isEqual({ ...prev, ts: 0 }, { ...next, ts: 0 }) && next.ts - prev.ts < USAGE_TS_REFRESH_MS) {
+    try {
+      utimesSync(paths.usageJson, new Date(next.ts), new Date(next.ts));
+    } catch (e) {
+      // The file vanished mid-race: a concurrent swap just invalidated these
+      // figures. Suppressing stays correct; a write would resurrect them.
+      if ((e as { code?: string }).code !== "ENOENT") throw e;
+    }
+    return false;
+  }
   writeFileAtomic(paths.usageJson, JSON.stringify(next));
   return true;
 }
 
+/** When the usage feed last proved itself alive (usage.json mtime), null if the
+ *  snapshot is absent. Fresher than the embedded `ts`, which write-on-change
+ *  deliberately lets age while figures hold still. */
+export function usageTeeAt(): number | null {
+  try {
+    return statSync(paths.usageJson).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
 // ---- model-usage.json (per-model caps from `/usage`, TTL-cached) ----------
 
 export function loadModelUsage(): ModelUsageState | null {

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";
 
@@ -67,6 +67,19 @@ export function matchedFamily(model: ModelInfo | null, families: string[]): stri
   return families.find((f) => tokens.has(f)) ?? null;
 }
 
+/** Families whose per-model weekly cap gates a switch, given the active model:
+ *  the model's own family when it is capacity-constrained, none when it is a
+ *  known-unconstrained model, and EVERY configured family when the model is
+ *  unknown. The unknown case matters on headless boxes: a swap clears the
+ *  snapshots and only an actively-rendering statusLine restores the model, so
+ *  the periodic check ran model-blind for hours while the active account sat at
+ *  its Fable cap (the 2026-07-12 stella incident). */
+export function gatedFamilies(model: ModelInfo | null, families: string[]): string[] {
+  if (!model) return families;
+  const family = matchedFamily(model, families);
+  return family ? [family] : [];
+}
+
 export const FullUsageSchema = z.object({
   session: UsageWindowSchema,
   weekAll: UsageWindowSchema,
@@ -199,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;
@@ -208,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);
     }
@@ -256,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;