tokenmaxxing 1.9.1 → 1.11.0

package/src/cli/status.ts

@@ -1,50 +1,103 @@
 import { sortBy } from "es-toolkit";
+import { z } from "zod";
 import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts } from "../lib/state.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { ensureLiveTokenFresh, probeActiveUsage, probeParkedUsage, type SampleOutcome } from "../lib/sample.ts";
 import { withLock } from "../lib/lock.ts";
 import { codexPaths, paths } from "../lib/paths.ts";
-import { earliestReset, effectiveBars, isExhausted, nextWeeklyReset } from "../lib/picker.ts";
+import { earliestReset, effectiveBars, isExhausted, nextWeeklyReset, terminalBars } from "../lib/picker.ts";
 import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
 import { liveCodexAccountId, sampleCodexAccount, type CodexSampleOutcome } from "../lib/codexsample.ts";
 import { isCodexExhausted } from "../lib/codexpick.ts";
 import { codexLimitLabel, isSessionWindow } from "../lib/codexusage.ts";
-import { bar, c, claudeTierLabel, count, fmtAgo, fmtReset } from "./render.ts";
-import type { FullUsage } from "../lib/usage.ts";
-import type { Account, Config, CodexWindow, UsageWindow } from "../lib/types.ts";
+import { bar, c, claudeTierLabel, count, emitJson, fmtAgo, fmtReset } from "./render.ts";
+import { gatedFamilies, type FullUsage } from "../lib/usage.ts";
+import { ThresholdsSchema, UsageWindowSchema, type Account, type CodexWindow, type Config, type UsageWindow } from "../lib/types.ts";
 
-export async function cmdStatus(force = false, preRender?: () => void): Promise<number> {
-  let idx = loadAccounts();
-  const cfg = loadConfig();
-  const now = Date.now();
+const SampleReportSchema = z.discriminatedUnion("ok", [
+  z.object({ ok: z.literal(true), source: z.enum(["statusline", "probe"]) }),
+  z.object({ ok: z.literal(false), reason: z.string() }),
+]);
+
+const ClaudeStatusAccountSchema = z.object({
+  label: z.string(),
+  email: z.string(),
+  accountUuid: z.string(),
+  organizationUuid: z.string(),
+  tier: z.string().nullable(),
+  active: z.boolean(),
+  needsReauth: z.boolean(),
+  exhausted: z.boolean(),
+  usage: z.object({ fiveHour: UsageWindowSchema, week: UsageWindowSchema }).nullable(),
+  perModel: z.record(z.string(), UsageWindowSchema),
+  usageAt: z.number().nullable(),
+  sample: SampleReportSchema,
+  pingError: z.string().nullable(),
+  pinged: z.boolean(),
+});
+type ClaudeStatusAccount = z.infer<typeof ClaudeStatusAccountSchema>;
+
+const CodexWindowReportSchema = UsageWindowSchema.extend({ windowSeconds: z.number().nullable() });
 
-  const row = (name: string, w: UsageWindow, weekly: boolean) => {
-    const passed = w.resetsAt != null && w.resetsAt <= now;
-    const pct = passed ? 0 : w.usedPercentage;
-    const resetsAt = weekly ? nextWeeklyReset(w.resetsAt, now) : passed ? null : w.resetsAt;
-    console.log(`    ${name.padEnd(5)} ${bar(pct)}  ${c.dim(fmtReset(resetsAt, now))}`);
+const CodexStatusAccountSchema = z.object({
+  label: z.string(),
+  email: z.string().nullable(),
+  accountId: z.string(),
+  planType: z.string().nullable(),
+  active: z.boolean(),
+  needsReauth: z.boolean(),
+  exhausted: z.boolean(),
+  usage: z
+    .object({
+      aggregate: z.array(CodexWindowReportSchema),
+      perLimit: z.record(z.string(), z.array(CodexWindowReportSchema)),
+    })
+    .nullable(),
+  usageAt: z.number().nullable(),
+  sample: SampleReportSchema,
+});
+type CodexStatusAccount = z.infer<typeof CodexStatusAccountSchema>;
+
+const StatusReportSchema = z.object({
+  now: z.number(),
+  claude: z.object({
+    thresholds: z.object({ session: z.array(z.number()), weekly: z.number() }),
+    bars: ThresholdsSchema,
+    projectionMargin: z.number(),
+    accounts: z.array(ClaudeStatusAccountSchema),
+  }),
+  codex: z.object({
+    bars: ThresholdsSchema,
+    accounts: z.array(CodexStatusAccountSchema),
+  }),
+});
+export type StatusReport = z.infer<typeof StatusReportSchema>;
+
+function currentWindow(w: UsageWindow, weekly: boolean, now: number): UsageWindow {
+  const passed = w.resetsAt != null && w.resetsAt <= now;
+  return {
+    usedPercentage: passed ? 0 : w.usedPercentage,
+    resetsAt: weekly ? nextWeeklyReset(w.resetsAt, now) : passed ? null : w.resetsAt,
   };
+}
 
-  if (idx.accounts.length === 0) {
-    if (loadCodexAccounts().accounts.length > 0) {
-      console.log(c.dim("no claude accounts (run `tokenmaxxing init` to pool claude too)"));
-      console.log();
-      await renderCodexSection({ cfg, now, row });
-      return 0;
-    }
-    console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`)"));
-    return 0;
-  }
+function currentCodexWindow(w: CodexWindow, now: number): CodexWindow {
+  return { ...currentWindow(w, !isSessionWindow({ window: w }), now), windowSeconds: w.windowSeconds };
+}
 
-  console.error(c.dim(force ? "pinging every account (starts each 5h session timer) + sampling live usage..." : "sampling live usage..."));
-  const outcomes = new Map<string, SampleOutcome>();
-  await withLock(paths.lockFile, async () => {
-    idx = loadAccounts();
-    const live = loadUsage();
-    const modelUsage = loadModelUsage();
-    const liveOAuth = readOAuthAccount();
-    const activeOrg = liveOAuth?.organizationUuid ?? null;
-    const probeOne = async (a: Account) => {
+async function collectClaude(input: { cfg: Config; force: boolean; now: number }): Promise<StatusReport["claude"]> {
+  const { cfg, force, now } = input;
+  let idx = loadAccounts();
+  const samples = new Map<string, { outcome: SampleOutcome; viaTee: boolean }>();
+  if (idx.accounts.length > 0) {
+    console.error(c.dim(force ? "pinging every account (starts each 5h session timer) + sampling live usage..." : "sampling live usage..."));
+    await withLock(paths.lockFile, async () => {
+      idx = loadAccounts();
+      const live = loadUsage();
+      const modelUsage = loadModelUsage();
+      const liveOAuth = readOAuthAccount();
+      const activeOrg = liveOAuth?.organizationUuid ?? null;
+      const probeOne = async (a: Account) => {
         const isActive = activeOrg != null && activeOrg === a.organizationUuid;
         if (isActive && liveOAuth?.organizationRateLimitTier != null) a.rateLimitTier = liveOAuth.organizationRateLimitTier;
         const fromStatusLine: FullUsage | null =
@@ -73,7 +126,7 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
               ? await probeActiveUsage(a)
               : await probeParkedUsage(a);
         }
-        outcomes.set(a.accountUuid, outcome);
+        samples.set(a.accountUuid, { outcome, viaTee });
         if (!outcome.ok) return;
         a.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
         a.lastUsageAt = viaTee && live ? live.ts : Date.now();
@@ -81,70 +134,57 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
           a.lastPerModel = outcome.usage.perModel;
           a.lastPerModelAt = viaTee && modelUsage ? (modelUsage.sampledAt ?? modelUsage.ts) : a.lastUsageAt;
         }
-    };
-    const activeAccount = idx.accounts.find((a) => activeOrg != null && activeOrg === a.organizationUuid) ?? null;
-    if (activeAccount) await probeOne(activeAccount);
-    try {
-      await ensureLiveTokenFresh();
-    } catch {
-    }
-    await Promise.all(idx.accounts.filter((a) => a !== activeAccount).map(probeOne));
-    saveAccounts(idx);
-  });
-
-  preRender?.();
-  console.log(c.dim(`thresholds 5h ${cfg.thresholds.session}% weekly ${cfg.thresholds.weekly}%  (${count({ n: idx.accounts.length, noun: "claude account" })})`));
-  console.log();
-
-  const displayAccounts = sortBy(idx.accounts, [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, now)]);
-  const displayActiveOrg = readOAuthAccount()?.organizationUuid ?? null;
-  for (const a of displayAccounts) {
-    const active = displayActiveOrg != null && a.organizationUuid === displayActiveOrg;
-    const outcome = outcomes.get(a.accountUuid);
-    const failed = outcome ? !outcome.ok : false;
-    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, thresholds: effectiveBars(cfg), currentAccountUuid: idx.activeAccountUuid, switchFamilies: cfg.policy.switchModels }))
-      badges.push(c.yellow("exhausted"));
-
-    const tier = claudeTierLabel(a);
-    console.log(`${marker} ${c.bold(a.label || a.email)}${tier ? ` ${c.dim(tier)}` : ""}${badges.length ? ` ${badges.join(" ")}` : ""}`);
-    if (aggregate) {
-      row("5h", aggregate.fiveHour, false);
-      row("week", aggregate.sevenDay, true);
-    }
-    if (perModel) for (const [name, w] of Object.entries(perModel)) row(name.toLowerCase(), w, true);
-    if (failed && outcome && !outcome.ok) {
-      const cached = aggregate || perModel ? `cached${a.lastUsageAt != null ? ` ${fmtAgo(a.lastUsageAt, now)}` : ""}, ` : "";
-      console.log(`    ${c.yellow(`${cached}live sample failed`)}: ${c.dim(outcome.reason)}`);
-    }
-    if (outcome?.pingError != null) {
-      console.log(`    ${c.yellow("ping failed (5h timer may not have started)")}: ${c.dim(outcome.pingError)}`);
-    }
-    if (force && outcome?.ok && outcome.pingError == null && aggregate && aggregate.fiveHour.resetsAt == null) {
-      console.log(`    ${c.dim("pinged - 5h timer started this run; the usage feed lags, re-run status shortly for the fresh window")}`);
-    }
-    console.log();
+      };
+      const activeAccount = idx.accounts.find((a) => activeOrg != null && activeOrg === a.organizationUuid) ?? null;
+      if (activeAccount) await probeOne(activeAccount);
+      try {
+        await ensureLiveTokenFresh();
+      } catch {
+      }
+      await Promise.all(idx.accounts.filter((a) => a !== activeAccount).map(probeOne));
+      saveAccounts(idx);
+    });
   }
 
-  await renderCodexSection({ cfg, now, row });
-  return 0;
+  const families = gatedFamilies(loadUsage()?.model ?? null, cfg.policy.switchModels);
+  const bars = effectiveBars(cfg, { accounts: idx.accounts, now, switchFamilies: families });
+  const activeOrg = readOAuthAccount()?.organizationUuid ?? null;
+  const ordered = sortBy(idx.accounts, [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, now)]);
+  const accounts = ordered.map((a): ClaudeStatusAccount => {
+    const sampled = samples.get(a.accountUuid) ?? { outcome: { ok: false, reason: "not sampled" }, viaTee: false };
+    const usage = sampled.outcome.ok ? sampled.outcome.usage : undefined;
+    const aggregate = usage ? { fiveHour: usage.session, sevenDay: usage.weekAll } : a.lastUsage;
+    const perModel = usage ? usage.perModel : (a.lastPerModel ?? {});
+    return {
+      label: a.label,
+      email: a.email,
+      accountUuid: a.accountUuid,
+      organizationUuid: a.organizationUuid,
+      tier: claudeTierLabel(a),
+      active: activeOrg != null && a.organizationUuid === activeOrg,
+      needsReauth: a.needsReauth === true,
+      exhausted: isExhausted(a, { now, thresholds: bars, currentAccountUuid: idx.activeAccountUuid, switchFamilies: families }),
+      usage: aggregate ? { fiveHour: currentWindow(aggregate.fiveHour, false, now), week: currentWindow(aggregate.sevenDay, true, now) } : null,
+      perModel: Object.fromEntries(Object.entries(perModel).map(([name, w]) => [name, currentWindow(w, true, now)])),
+      usageAt: a.lastUsageAt ?? null,
+      sample: sampled.outcome.ok ? { ok: true, source: sampled.viaTee ? "statusline" : "probe" } : { ok: false, reason: sampled.outcome.reason },
+      pingError: sampled.outcome.pingError ?? null,
+      pinged: force && sampled.outcome.ok && sampled.outcome.pingError == null && aggregate != null && aggregate.fiveHour.resetsAt == null,
+    };
+  });
+  return {
+    thresholds: { session: cfg.thresholds.session, weekly: cfg.thresholds.weekly },
+    bars,
+    projectionMargin: cfg.policy.projectionMargin,
+    accounts,
+  };
 }
 
-async function renderCodexSection(input: {
-  cfg: Config;
-  now: number;
-  row: (name: string, w: UsageWindow, weekly: boolean) => void;
-}): Promise<void> {
-  const { cfg, now, row } = input;
+async function collectCodex(input: { cfg: Config; now: number }): Promise<StatusReport["codex"]> {
+  const { cfg, now } = input;
+  const bars = terminalBars(cfg);
   let index = loadCodexAccounts();
-  if (index.accounts.length === 0) return;
+  if (index.accounts.length === 0) return { bars, accounts: [] };
 
   console.error(c.dim("sampling codex usage..."));
   const outcomes = new Map<string, CodexSampleOutcome>();
@@ -169,11 +209,7 @@ async function renderCodexSection(input: {
     saveCodexAccounts({ index });
   });
 
-  console.log(c.dim(`codex  (${count({ n: index.accounts.length, noun: "account" })})`));
-  console.log();
-  const windowLabel = (window: CodexWindow) =>
-    isSessionWindow({ window }) ? `${Math.round((window.windowSeconds ?? 0) / 3600)}h` : "week";
-  const displayAccounts = sortBy(index.accounts, [
+  const ordered = sortBy(index.accounts, [
     (a) => (a.needsReauth ? 1 : 0),
     (a) => {
       const windows = [...(a.lastUsage?.aggregate ?? []), ...Object.values(a.lastUsage?.perLimit ?? {}).flat()];
@@ -181,27 +217,122 @@ async function renderCodexSection(input: {
       return resets.length > 0 ? Math.min(...resets) : Number.POSITIVE_INFINITY;
     },
   ]);
-  for (const account of displayAccounts) {
-    const active = account.accountId === liveId;
-    const marker = active ? c.green("●") : c.dim("○");
+  const accounts = ordered.map((account): CodexStatusAccount => {
+    const outcome = outcomes.get(account.accountId) ?? { ok: false, reason: "not sampled", deadGrant: false };
+    const usage = account.lastUsage;
+    return {
+      label: account.label,
+      email: account.email,
+      accountId: account.accountId,
+      planType: account.planType,
+      active: account.accountId === liveId,
+      needsReauth: account.needsReauth === true,
+      exhausted: isCodexExhausted({ account, thresholds: bars, now }),
+      usage: usage
+        ? {
+            aggregate: usage.aggregate.map((w) => currentCodexWindow(w, now)),
+            perLimit: Object.fromEntries(
+              Object.entries(usage.perLimit).map(([name, windows]) => [name, windows.map((w) => currentCodexWindow(w, now))]),
+            ),
+          }
+        : null,
+      usageAt: account.lastUsageAt ?? null,
+      sample: outcome.ok ? { ok: true, source: "probe" } : { ok: false, reason: outcome.reason },
+    };
+  });
+  return { bars, accounts };
+}
+
+function renderCodex(input: { codex: StatusReport["codex"]; now: number; row: (name: string, w: UsageWindow) => void }): void {
+  const { codex, now, row } = input;
+  if (codex.accounts.length === 0) return;
+  console.log(c.dim(`codex  (${count({ n: codex.accounts.length, noun: "account" })})`));
+  console.log();
+  const windowLabel = (window: CodexWindow) =>
+    isSessionWindow({ window }) ? `${Math.round((window.windowSeconds ?? 0) / 3600)}h` : "week";
+  for (const account of codex.accounts) {
+    const marker = account.active ? c.green("●") : c.dim("○");
     const badges: string[] = [];
-    if (active) badges.push(c.green("active"));
+    if (account.active) badges.push(c.green("active"));
     if (account.needsReauth) badges.push(c.red("needs-reauth"));
-    if (isCodexExhausted({ account, thresholds: effectiveBars(cfg), now })) badges.push(c.yellow("exhausted"));
+    if (account.exhausted) badges.push(c.yellow("exhausted"));
     console.log(`${marker} ${c.bold(account.label)}${account.planType ? ` ${c.dim(account.planType)}` : ""}${badges.length ? ` ${badges.join(" ")}` : ""}`);
-
-    const usage = account.lastUsage;
-    if (usage) {
-      for (const window of usage.aggregate) row(windowLabel(window), window, !isSessionWindow({ window }));
-      for (const [name, windows] of Object.entries(usage.perLimit)) {
-        for (const window of windows) row(codexLimitLabel({ limitName: name }), window, !isSessionWindow({ window }));
+    if (account.usage) {
+      for (const window of account.usage.aggregate) row(windowLabel(window), window);
+      for (const [name, windows] of Object.entries(account.usage.perLimit)) {
+        for (const window of windows) row(codexLimitLabel({ limitName: name }), window);
       }
     }
-    const outcome = outcomes.get(account.accountId);
-    if (outcome && !outcome.ok) {
-      const cached = usage ? `cached${account.lastUsageAt != null ? ` ${fmtAgo(account.lastUsageAt, now)}` : ""}, ` : "";
-      console.log(`    ${c.yellow(`${cached}live sample failed`)}: ${c.dim(outcome.reason)}`);
+    if (!account.sample.ok) {
+      const cached = account.usage ? `cached${account.usageAt != null ? ` ${fmtAgo(account.usageAt, now)}` : ""}, ` : "";
+      console.log(`    ${c.yellow(`${cached}live sample failed`)}: ${c.dim(account.sample.reason)}`);
+    }
+    console.log();
+  }
+}
+
+function rowPrinter(now: number): (name: string, w: UsageWindow) => void {
+  return (name, w) => {
+    console.log(`    ${name.padEnd(5)} ${bar(w.usedPercentage)}  ${c.dim(fmtReset(w.resetsAt, now))}`);
+  };
+}
+
+function renderClaude(input: { claude: StatusReport["claude"]; codexPooled: boolean; now: number; row: (name: string, w: UsageWindow) => void }): void {
+  const { claude, codexPooled, now, row } = input;
+  if (claude.accounts.length === 0) {
+    if (!codexPooled) {
+      console.log(c.dim("no accounts yet, run `tokenmaxxing init` (or `tokenmaxxing init --codex`)"));
+      return;
+    }
+    console.log(c.dim("no claude accounts (run `tokenmaxxing init` to pool claude too)"));
+    console.log();
+    return;
+  }
+
+  console.log(c.dim(`thresholds 5h ${claude.thresholds.session.join("/")}% (at ${claude.bars.session + claude.projectionMargin}%) weekly ${claude.thresholds.weekly}%  (${count({ n: claude.accounts.length, noun: "claude account" })})`));
+  console.log();
+  for (const a of claude.accounts) {
+    const marker = a.active ? c.green("●") : c.dim("○");
+    const badges: string[] = [];
+    if (a.active) badges.push(c.green("active"));
+    if (a.needsReauth) badges.push(c.red("needs-reauth"));
+    if (a.exhausted) badges.push(c.yellow("exhausted"));
+    console.log(`${marker} ${c.bold(a.label || a.email)}${a.tier ? ` ${c.dim(a.tier)}` : ""}${badges.length ? ` ${badges.join(" ")}` : ""}`);
+    if (a.usage) {
+      row("5h", a.usage.fiveHour);
+      row("week", a.usage.week);
+    }
+    for (const [name, w] of Object.entries(a.perModel)) row(name.toLowerCase(), w);
+    if (!a.sample.ok) {
+      const cached = a.usage || Object.keys(a.perModel).length > 0 ? `cached${a.usageAt != null ? ` ${fmtAgo(a.usageAt, now)}` : ""}, ` : "";
+      console.log(`    ${c.yellow(`${cached}live sample failed`)}: ${c.dim(a.sample.reason)}`);
+    }
+    if (a.pingError != null) {
+      console.log(`    ${c.yellow("ping failed (5h timer may not have started)")}: ${c.dim(a.pingError)}`);
+    }
+    if (a.pinged) {
+      console.log(`    ${c.dim("pinged - 5h timer started this run; the usage feed lags, re-run status shortly for the fresh window")}`);
     }
     console.log();
   }
 }
+
+export async function cmdStatus(opts: { force?: boolean; json?: boolean; preRender?: () => void } = {}): Promise<number> {
+  const { force = false, json = false } = opts;
+  const cfg = loadConfig();
+  const now = Date.now();
+  const row = rowPrinter(now);
+  const claude = await collectClaude({ cfg, force, now });
+  if (!json) {
+    opts.preRender?.();
+    renderClaude({ claude, codexPooled: loadCodexAccounts().accounts.length > 0, now, row });
+  }
+  const codex = await collectCodex({ cfg, now });
+  if (json) {
+    const report: StatusReport = { now, claude, codex };
+    emitJson({ ok: true, ...report });
+    return 0;
+  }
+  renderCodex({ codex, now, row });
+  return 0;
+}

package/src/cli/switch.ts

@@ -1,20 +1,30 @@
 import { withLock } from "../lib/lock.ts";
 import { paths } from "../lib/paths.ts";
-import { loadAccounts, loadConfig } from "../lib/state.ts";
+import { loadAccounts, loadConfig, loadUsage } from "../lib/state.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
 import { performSwap } from "../lib/swap.ts";
 import { currentWins, effectiveBars, pickBest, pickEarliestReset, weeklyExpiry, type PickCtx } from "../lib/picker.ts";
 import { InvalidGrantError } from "../lib/oauth.ts";
+import { gatedFamilies } from "../lib/usage.ts";
 import { findAccount } from "./rename.ts";
-import { c, fmtReset } from "./render.ts";
+import { c, emitError, emitJson, fmtReset } from "./render.ts";
 import type { Account } from "../lib/types.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`"));
+export async function cmdSwitch(selector?: string, json = false): Promise<number> {
+  const deadGrants: string[] = [];
+  const withDeadGrants = (report: Record<string, unknown>) => (deadGrants.length > 0 ? { ...report, deadGrants } : report);
+  const emit = (text: string, report: Record<string, unknown>): void => {
+    if (json) emitJson({ ok: true, ...withDeadGrants(report) });
+    else console.log(text);
+  };
+  const fail = (message: string, opts: { paint?: (s: string) => string; extra?: Record<string, unknown> } = {}): number => {
+    emitError({ json, message, paint: opts.paint, extra: withDeadGrants(opts.extra ?? {}) });
     return 1;
-  }
+  };
+  const deadGrantMessage = (a: Account) => `${a.label}'s refresh token is dead - run \`tokenmaxxing auth ${a.label}\``;
+
+  const idx0 = loadAccounts();
+  if (idx0.accounts.length < 2) return fail("need at least 2 accounts to switch - add one with `tokenmaxxing add`", { paint: c.yellow });
   const cfg = loadConfig();
   const now = Date.now();
 
@@ -25,37 +35,55 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     const claimedOrg = liveClaim?.organizationUuid ?? null;
     const drifted = claimed != null && claimed !== idx.activeAccountUuid;
 
-    const swapTo = async (target: Account): Promise<number> => {
+    const swapTo = async (target: Account, reason: string, extra: Record<string, unknown> = {}): Promise<number> => {
       try {
         await performSwap(target);
       } catch (e) {
-        if (e instanceof InvalidGrantError) { console.error(c.red(`${target.label}'s refresh token is dead - run \`tokenmaxxing auth ${target.label}\``)); return 1; }
+        if (e instanceof InvalidGrantError) {
+          deadGrants.push(target.label);
+          return fail(deadGrantMessage(target));
+        }
         throw e;
       }
-      console.log(`${c.green("↻")} switched to ${c.bold(target.label)}`);
+      emit(`${c.green("↻")} switched to ${c.bold(target.label)}`, { switched: true, account: target.label, reason, ...extra });
       return 0;
     };
 
     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 && !drifted) { console.log(`already on ${c.bold(target.label)}`); return 0; }
-      if (target.needsReauth) { console.error(c.red(`${target.label} needs re-auth - run \`tokenmaxxing auth ${target.label}\``)); return 1; }
-      return swapTo(target);
+      if (!target) return fail(`no account matches "${selector}"`);
+      if (target.accountUuid === idx.activeAccountUuid && !drifted) {
+        emit(`already on ${c.bold(target.label)}`, { switched: false, account: target.label, reason: "already-on" });
+        return 0;
+      }
+      if (target.needsReauth) return fail(`${target.label} needs re-auth - run \`tokenmaxxing auth ${target.label}\``);
+      return swapTo(target, "selected");
     }
 
-    const everyone: PickCtx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: null, switchFamilies: cfg.policy.switchModels };
+    const switchFamilies = gatedFamilies(loadUsage()?.model ?? null, cfg.policy.switchModels);
+    const everyoneIn = (accounts: Account[]): PickCtx => ({
+      now,
+      thresholds: effectiveBars(cfg, { accounts, now, switchFamilies }),
+      currentAccountUuid: null,
+      switchFamilies,
+    });
     while (true) {
       const cur = loadAccounts();
+      const everyone = everyoneIn(cur.accounts);
       const active =
         (claimedOrg != null ? cur.accounts.find((a) => a.organizationUuid === claimedOrg) : null) ??
         cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ??
         null;
       if (active != null && currentWins(active, cur.accounts, everyone)) {
-        if (drifted) return swapTo(active);
+        if (drifted) return swapTo(active, "drift-reconciled");
         const expiry = weeklyExpiry(active, now);
         const why = Number.isFinite(expiry) ? ` (weekly ${fmtReset(expiry, now)})` : "";
-        console.log(`already on the best account: ${c.bold(active.label)}${why}`);
+        emit(`already on the best account: ${c.bold(active.label)}${why}`, {
+          switched: false,
+          account: active.label,
+          reason: "current-wins",
+          weeklyResetsAt: Number.isFinite(expiry) ? expiry : null,
+        });
         return 0;
       }
       const best = pickBest(cur.accounts, { ...everyone, currentAccountUuid: active?.accountUuid ?? null });
@@ -64,37 +92,53 @@ export async function cmdSwitch(selector?: string): Promise<number> {
         await performSwap(best);
       } catch (e) {
         if (e instanceof InvalidGrantError) {
-          console.error(c.red(`${best.label}'s refresh token is dead - run \`tokenmaxxing auth ${best.label}\``));
+          deadGrants.push(best.label);
+          if (!json) console.error(c.red(deadGrantMessage(best)));
           continue;
         }
         throw e;
       }
-      console.log(`${c.green("↻")} switched to ${c.bold(best.label)}`);
+      emit(`${c.green("↻")} switched to ${c.bold(best.label)}`, { switched: true, account: best.label, reason: "best" });
       return 0;
     }
 
     const fresh = loadAccounts();
-    const earliest = pickEarliestReset(fresh.accounts, everyone);
+    const earliest = pickEarliestReset(fresh.accounts, everyoneIn(fresh.accounts));
+    const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
     if (!earliest) {
-      const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
-      if (reauth.length > 0) { console.error(c.yellow(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`)); return 1; }
+      if (reauth.length > 0) {
+        return fail(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`, {
+          paint: c.yellow,
+          extra: { reauthNeeded: reauth },
+        });
+      }
       const freshActive = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid) ?? null;
-      if (drifted && freshActive) return swapTo(freshActive);
-      console.log(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"));
+      if (drifted && freshActive) return swapTo(freshActive, "drift-reconciled");
+      emit(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"), {
+        switched: false,
+        account: freshActive?.label ?? null,
+        reason: "unknown-resets",
+      });
       return 0;
     }
-    const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
     const reauthNote = reauth.length ? ` - re-auth needed: ${reauth.join(", ")}` : "";
+    const availableAt = earliest.availableAt > now ? earliest.availableAt : null;
     if (earliest.account.accountUuid === fresh.activeAccountUuid && !drifted) {
-      const msg = earliest.availableAt <= now
+      const msg = availableAt == null
         ? `staying on ${c.bold(earliest.account.label)} - no usable switch target${reauthNote}`
-        : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(earliest.availableAt, now)})${reauthNote}`;
-      console.log(c.yellow(msg));
+        : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(availableAt, now)})${reauthNote}`;
+      emit(c.yellow(msg), {
+        switched: false,
+        account: earliest.account.label,
+        reason: availableAt == null ? "no-target" : "all-at-limit",
+        availableAt,
+        reauthNeeded: reauth,
+      });
       return 0;
     }
-    const code = await swapTo(earliest.account);
-    if (code === 0 && earliest.availableAt > now) {
-      console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(earliest.availableAt, now)})${reauthNote}`));
+    const code = await swapTo(earliest.account, "earliest-reset", { availableAt, reauthNeeded: reauth });
+    if (code === 0 && availableAt != null && !json) {
+      console.log(c.yellow(`all accounts at limit - ${c.bold(earliest.account.label)} recovers soonest (${fmtReset(availableAt, now)})${reauthNote}`));
     }
     return code;
   });

package/src/cli/watch.ts

@@ -1,7 +1,8 @@
 import { clamp, delay } from "es-toolkit";
 import { loadAccounts } from "../lib/state.ts";
+import { loadCodexAccounts } from "../lib/codexstate.ts";
 import { cmdStatus } from "./status.ts";
-import { c } from "./render.ts";
+import { c, emitError, emitJson } from "./render.ts";
 
 const DEFAULT_INTERVAL_S = 120;
 const MIN_INTERVAL_S = 30;
@@ -16,13 +17,13 @@ export function resolveWatchInterval(arg?: string): number | null {
 
 const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
 
-export async function cmdWatch(intervalArg?: string): Promise<number> {
+export async function cmdWatch(intervalArg?: string, json = false): Promise<number> {
   const intervalS = resolveWatchInterval(intervalArg);
   if (intervalS === null) {
-    console.error(c.red(`watch interval must be a positive number of seconds, got: ${intervalArg}`));
+    emitError({ json, message: `watch interval must be a positive number of seconds, got: ${intervalArg}` });
     return 2;
   }
-  if (loadAccounts().accounts.length === 0) return cmdStatus();
+  if (loadAccounts().accounts.length === 0 && loadCodexAccounts().accounts.length === 0) return cmdStatus({ json });
 
   const paintHeader = () => {
     process.stdout.write(process.stdout.isTTY ? CLEAR : "\n");
@@ -30,10 +31,15 @@ export async function cmdWatch(intervalArg?: string): Promise<number> {
   };
   while (true) {
     try {
-      await cmdStatus(false, paintHeader);
+      await cmdStatus(json ? { json } : { preRender: paintHeader });
     } catch (e) {
-      paintHeader();
-      console.error(c.red(`status failed this tick: ${e instanceof Error ? e.message : String(e)}`));
+      const message = `status failed this tick: ${e instanceof Error ? e.message : String(e)}`;
+      if (json) {
+        emitJson({ ok: false, error: message });
+      } else {
+        paintHeader();
+        console.error(c.red(message));
+      }
     }
     await delay(intervalS * 1000);
   }

package/src/entries/codexstophook.ts

@@ -10,7 +10,7 @@ import { livingCodexPresences } from "../lib/codexpresence.ts";
 import { liveCodexAccountId } from "../lib/codexsample.ts";
 import { loadCodexAccounts } from "../lib/codexstate.ts";
 import { loadConfig } from "../lib/state.ts";
-import { effectiveBars } from "../lib/picker.ts";
+import { terminalBars } from "../lib/picker.ts";
 import { CODEX_SUPERVISOR_ID_ENV } from "./codexsupervisor.ts";
 import { CodexReconcileMarkerSchema, CodexRespawnMarkerSchema, CodexStopStdinSchema, type CodexAccount } from "../lib/types.ts";
 import { log } from "../lib/log.ts";
@@ -51,7 +51,7 @@ function promoteReconcileLocked(input: { supervisorId: string; sessionId: string
     return false;
   }
   const now = Date.now();
-  const bars = effectiveBars(loadConfig());
+  const bars = terminalBars(loadConfig());
   const index = loadCodexAccounts();
   const unusable = (account: CodexAccount): boolean =>
     account.needsReauth === true || isCodexExhausted({ account, thresholds: bars, now });