tokenmaxxing 1.8.0 → 1.9.0

package/src/cli/onboard.ts

@@ -1,10 +1,3 @@
-// One isolated Claude login, harvested. Shared by `add` (register whatever
-// account the login lands on) and `auth` (require it to match an existing
-// account). Drives the login in a throwaway CLAUDE_CONFIG_DIR - the ONLY use
-// of CLAUDE_CONFIG_DIR in the tool - auto-exits the moment the login lands,
-// samples that account's usage, then returns the credential + identity. The
-// temp dir and isolated credential are always destroyed before returning.
-
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -17,7 +10,6 @@ import { CredentialBlobSchema, OAuthAccountSchema } from "../lib/types.ts";
 import { c } from "./render.ts";
 
 const HarvestedLoginSchema = z.object({
-  /** the raw isolated credential blob (park it via claudeAiOauthOnly). */
   blobRaw: z.string(),
   blob: CredentialBlobSchema,
   oauthAccount: OAuthAccountSchema,
@@ -25,7 +17,6 @@ const HarvestedLoginSchema = z.object({
 });
 export type HarvestedLogin = z.infer<typeof HarvestedLoginSchema>;
 
-/** True once `/login` has written a usable identity into the onboard dir. */
 function identityReady(cjPath: string): boolean {
   if (!existsSync(cjPath)) return false;
   try {
@@ -36,32 +27,16 @@ function identityReady(cjPath: string): boolean {
   }
 }
 
-/**
- * Run one isolated login session and harvest it. The caller prints its own
- * instructions (which account to sign in as) BEFORE calling. Prints progress
- * and failure diagnostics; returns null when no usable login landed.
- */
 export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
   const onboardDir = paths.onboardDir;
   rmSync(onboardDir, { recursive: true, force: true });
   mkdirSync(onboardDir, { recursive: true });
   const iso = isolatedTarget(onboardDir);
-  // Reap a PREVIOUS run's stranded isolated credential too: on macOS the
-  // isolated store is a namespaced KEYCHAIN item, not a file in onboardDir,
-  // so the rmSync above never touched it - a signal-killed harvest (Ctrl-C
-  // after /login, before the ~400ms poll) left a live credential in the
-  // keychain that the next run's spawned claude would silently reuse as an
-  // already-authenticated session (closing-review catch). deleteItem on a
-  // missing item is a no-op; on Linux iso is a file inside onboardDir and the
-  // rmSync already covered it.
   await deleteItem(iso);
   const cjPath = join(onboardDir, ".claude.json");
   const real = resolveRealClaude();
 
   const savedTermios = saveTermios();
-  // Scrub the ambient credential/identity overrides claude honors BEFORE its
-  // keychain lookup (verified 2.1.205) - the onboard session must authenticate
-  // only via the /login the user performs inside it.
   const env: Record<string, string> = { ...process.env, CLAUDE_CONFIG_DIR: onboardDir, TOKENMAXXING_PROBE: "1", TOKENMAXXING_SUPERVISED: "" };
   for (const key of CRED_ENV_OVERRIDES) delete env[key];
   const p = Bun.spawn([real], {
@@ -71,15 +46,7 @@ export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
     env,
   });
 
-  // The finally makes the "always destroyed before returning" header true for
-  // every non-signal exit - INCLUDING a failure while the login session is
-  // still being polled (review catch, PR #31): an exception must not strand a
-  // plaintext credential on disk or leave the spawned claude running. (An
-  // interactive Ctrl-C is reaped by the next run's cleanup-first, which
-  // deletes the isolated keychain item as well as the dir.)
   try {
-    // Auto-exit (#17): watch for a completed login - identity written AND the
-    // isolated credential present - then SIGTERM claude. No manual /exit.
     let exited = false;
     const onExit = p.exited.then(() => { exited = true; });
     while (!exited) {
@@ -91,9 +58,6 @@ export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
     }
     await p.exited;
     await onExit;
-    // restore promptly so the harvest's own output renders on a sane terminal;
-    // the finally's second restore is an idempotent stty and covers the
-    // thrown-mid-poll path.
     restoreTermios(savedTermios);
 
     const blobRaw = await readItem(iso);
@@ -111,7 +75,6 @@ export async function harvestIsolatedLogin(): Promise<HarvestedLogin | null> {
       return null;
     }
 
-    // Sample usage now (#16) so the account isn't "not sampled yet" in status/ls.
     console.log(c.dim("sampling usage..."));
     const sampled = await probeUsage(onboardDir);
     if (!sampled) console.log(c.yellow("could not sample usage now - it will fill in on first use."));

package/src/cli/rename.ts

@@ -1,8 +1,3 @@
-// `tokenmaxxing rename [--codex] <selector> <new-label>` - relabel a pooled
-// account. The pools are separate namespaces and one email can hold both a
-// claude and a codex account, so the codex pool is targeted explicitly via
-// `--codex` (mirroring `switch --codex`), never by searching both pools.
-
 import { withLock } from "../lib/lock.ts";
 import { codexPaths, paths } from "../lib/paths.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
@@ -10,7 +5,6 @@ import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
 import { c } from "./render.ts";
 import type { Account, CodexAccount } from "../lib/types.ts";
 
-/** Resolve a claude account by email, label, or accountUuid prefix. */
 export function findAccount(accounts: Account[], selector: string): Account | undefined {
   const s = selector.toLowerCase();
   return (
@@ -20,7 +14,6 @@ export function findAccount(accounts: Account[], selector: string): Account | un
   );
 }
 
-/** Resolve a codex account by email, label, or accountId prefix. */
 export function findCodexAccount(accounts: CodexAccount[], selector: string): CodexAccount | undefined {
   const s = selector.toLowerCase();
   return (
@@ -31,7 +24,6 @@ export function findCodexAccount(accounts: CodexAccount[], selector: string): Co
 }
 
 async function renameCodexAccount(input: { selector: string; newLabel: string }): Promise<number> {
-  // under the codex flock: a concurrent codex swap's index write must not be clobbered.
   return withLock(codexPaths.lockFile, async () => {
     const index = loadCodexAccounts();
     const account = findCodexAccount(index.accounts, input.selector);
@@ -39,11 +31,6 @@ async function renameCodexAccount(input: { selector: string; newLabel: string })
       console.error(c.red(`no codex account matches "${input.selector}"`));
       return 1;
     }
-    // labels resolve selectors first-match: a duplicate would make the other
-    // account unreachable by label and misdirect destructive commands like
-    // `rm` onto the wrong one (adversarial-review catch)
-    // case-insensitive, matching how findCodexAccount resolves selectors (PR
-    // #37 review catch: a casing-only duplicate slipped the === guard)
     const taken = index.accounts.find((x) => x.accountId !== account.accountId && x.label.toLowerCase() === input.newLabel.toLowerCase());
     if (taken) {
       console.error(c.red(`label "${input.newLabel}" is already used by ${taken.accountId.slice(0, 8)} - labels must be unique within the pool`));
@@ -65,7 +52,6 @@ export async function cmdRename(argv: string[]): Promise<number> {
     return 2;
   }
   if (codex) return renameCodexAccount({ selector, newLabel });
-  // under the flock: a concurrent swap's index write must not be clobbered.
   return withLock(paths.lockFile, async () => {
     const idx = loadAccounts();
     const a = findAccount(idx.accounts, selector);
@@ -73,11 +59,6 @@ export async function cmdRename(argv: string[]): Promise<number> {
       console.error(c.red(`no claude account matches "${selector}" (codex accounts rename via --codex)`));
       return 1;
     }
-    // labels resolve selectors first-match: a duplicate would make the other
-    // account unreachable by label and misdirect destructive commands like
-    // `rm` onto the wrong one (adversarial-review catch)
-    // case-insensitive, matching how findAccount resolves selectors (PR #37
-    // review catch: a casing-only duplicate slipped the === guard)
     const taken = idx.accounts.find((x) => x.accountUuid !== a.accountUuid && x.label.toLowerCase() === newLabel.toLowerCase());
     if (taken) {
       console.error(c.red(`label "${newLabel}" is already used by ${taken.email} - labels must be unique within the pool`));

package/src/cli/render.ts

@@ -1,9 +1,5 @@
-// Terminal rendering helpers for the CLI (bars, colors, relative times).
-
 import { clamp } from "es-toolkit";
 
-/** ANSI painters, no-ops when disabled. The statusLine renders through a pipe
- *  (never a TTY), so it needs its own enable gate; the CLI gates on stdout. */
 export function makeColors(enabled: boolean) {
   const paint = (code: string) => (s: string) => (enabled ? `\x1b[${code}m${s}\x1b[0m` : s);
   return {
@@ -18,9 +14,6 @@ export function makeColors(enabled: boolean) {
 
 export const c = makeColors(!process.env.NO_COLOR && !!process.stdout.isTTY);
 
-/** Used% -> RGB on a continuous green->yellow->red ramp, anchored at the
- *  semantic severity bands (pure green at 0, yellow at 75, red from 95) so the
- *  band boundaries read exactly like the old 3-color scheme. Blue stays 0. */
 function rampRgb(usedPct: number): { r: number; g: number } {
   const u = clamp(usedPct, 0, 100);
   if (u >= 95) return { r: 255, g: 0 };
@@ -28,11 +21,6 @@ function rampRgb(usedPct: number): { r: number; g: number } {
   return { r: Math.round((255 * u) / 75), g: 255 };
 }
 
-/** Usage-severity painter for the statusLine (user decision 2026-07-18: colors
- *  carry quota status instead of numbers). Truecolor when the terminal
- *  advertises it, else the nearest 256-color cube step; disabled -> identity,
- *  and callers must then fall back to numeric rendering (without color a
- *  drained window must not look fresh). */
 export function makeUsagePaint(input: { enabled: boolean; truecolor: boolean }) {
   return (usedPct: number) =>
     (s: string): string => {
@@ -45,12 +33,6 @@ export function makeUsagePaint(input: { enabled: boolean; truecolor: boolean })
     };
 }
 
-/** Plan label for a claude account, e.g. "max 20x": subscription name plus the
- *  multiplier segment of the rate-limit tier id ("default_claude_max_20x").
- *  Structural, never exact-string: the multiplier is any <digits>x segment, so
- *  tiers without one (e.g. "default_claude_zero") fall back to the bare
- *  subscription name, and an absent blob field falls back to null (unmeasured
- *  must not look like a tier). */
 export function claudeTierLabel(input: { subscriptionType?: string; rateLimitTier?: string }): string | null {
   const segments = input.rateLimitTier?.split("_") ?? [];
   const multiplier = segments.find((seg) => seg.length > 1 && seg.endsWith("x") && Number.isInteger(Number(seg.slice(0, -1))));
@@ -58,12 +40,10 @@ export function claudeTierLabel(input: { subscriptionType?: string; rateLimitTie
   return multiplier ? `${input.subscriptionType} ${multiplier}` : input.subscriptionType;
 }
 
-/** "1 account" / "3 accounts": counted nouns always pluralize properly. */
 export function count(input: { n: number; noun: string }): string {
   return `${input.n} ${input.noun}${input.n === 1 ? "" : "s"}`;
 }
 
-/** A fixed-width usage bar, colored by fill. */
 export function bar(pct: number, width = 16): string {
   const clamped = clamp(pct, 0, 100);
   const filled = Math.round((clamped / 100) * width);
@@ -73,7 +53,6 @@ export function bar(pct: number, width = 16): string {
   return `${paint(body)} ${label}`;
 }
 
-/** Relative-time string for a reset epoch, e.g. "resets in 2h13m". */
 export function fmtReset(epochMs: number | null | undefined, now = Date.now()): string {
   if (epochMs == null) return "";
   const dsec = Math.round((epochMs - now) / 1000);
@@ -85,8 +64,6 @@ export function fmtReset(epochMs: number | null | undefined, now = Date.now()):
   return `resets in ${m}m`;
 }
 
-/** Age of a cached sample, largest unit only: "just now", "3m ago", "2h ago",
- *  "5d ago". */
 export function fmtAgo(epochMs: number, now = Date.now()): string {
   const dsec = Math.max(0, Math.round((now - epochMs) / 1000));
   if (dsec < 60) return "just now";

package/src/cli/rm.ts

@@ -1,5 +1,3 @@
-// `tokenmaxxing rm <selector>` - remove a pooled account (not the active one).
-
 import { rmSync } from "node:fs";
 import { join } from "node:path";
 import { deleteItem, isolatedTarget, liveTarget, parkedTarget, readItem } from "../lib/credstore.ts";
@@ -16,7 +14,6 @@ export async function cmdRm(selector?: string): Promise<number> {
     console.error("usage: tokenmaxxing rm <email|label|uuid>");
     return 2;
   }
-  // under the flock: a concurrent swap's index write must not be clobbered.
   return withLock(paths.lockFile, async () => {
     const idx = loadAccounts();
     const a = findAccount(idx.accounts, selector);
@@ -28,13 +25,6 @@ export async function cmdRm(selector?: string): Promise<number> {
       console.error(c.red(`${a.email} is the ACTIVE account - switch away before removing it.`));
       return 1;
     }
-    // The label drifts (manual /login); the token cannot lie. Removing the
-    // account whose credential is actually LIVE would destroy its only backup
-    // and leave the next swap refusing over an unpooled credential. Fail
-    // CLOSED (review catch, PR #31): when the live owner cannot be verified -
-    // unparsable blob, expired token, roles outage - refuse rather than trust
-    // the stale label; rm is destructive and can wait. The check is read-only:
-    // an expired bearer simply fails the roles call, nothing is ever rotated.
     const live = await readItem(liveTarget());
     if (live != null) {
       let liveOrg: string;
@@ -51,15 +41,6 @@ export async function cmdRm(selector?: string): Promise<number> {
       }
     }
     await deleteItem(parkedTarget(a.keychainItem));
-    // Sweep sample-probe residue too: a probe killed mid-run strands the
-    // account's isolated credential (macOS: a namespaced keychain item), and
-    // once the account leaves the pool nothing would ever probe-and-heal it
-    // again (closing-review critic gap). deleteItem on a missing item is a
-    // no-op. Hard delete, not trash, on purpose: the sample dir is a
-    // throwaway CLAUDE_CONFIG_DIR that can hold PLAINTEXT credential material
-    // on Linux - the credential-dir cleanup exception (owner 2026-07-16, same
-    // rule sample.ts and onboard.ts follow); trashing would move credentials
-    // into the Trash folder.
     const sampleDir = join(paths.sampleDir, credItemFor(a.accountUuid));
     await deleteItem(isolatedTarget(sampleDir));
     rmSync(sampleDir, { recursive: true, force: true });

package/src/cli/status.ts

@@ -1,17 +1,3 @@
-// `tokenmaxxing status`: accounts with 5h / weekly / per-model usage bars.
-// Parked accounts are live-sampled in isolation (`claude -p /usage`); the active
-// account is read off the free statusLine feed (usage.json) so we never poll its
-// own busy token. A sample that fails falls back to the last-known values with a
-// visible "(cached)" note - never a silent stale number. Fresh figures are
-// persisted onto each account for the picker/switch logic.
-//
-// `--force` additionally PINGS every account (one minimal haiku request each)
-// before sampling, so every account's 5h session window starts ticking NOW
-// instead of lying dormant until first real use, and every bar is a live probe
-// taken after the ping. The active account still prefers the tee only as a
-// fallback: its own `/usage` fail-silents exactly when a live session is
-// running it, and that session's tee is fresher than any cache.
-
 import { sortBy } from "es-toolkit";
 import { loadAccounts, loadConfig, loadUsage, loadModelUsage, saveAccounts } from "../lib/state.ts";
 import { readOAuthAccount } from "../lib/claudejson.ts";
@@ -27,17 +13,11 @@ 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";
 
-/** `preRender` runs after sampling, right before the first output line: `watch`
- *  keeps the previous frame on screen through the multi-second sample and
- *  clears only when the fresh frame is ready to paint (watch(1) semantics). */
 export async function cmdStatus(force = false, preRender?: () => void): Promise<number> {
   let idx = loadAccounts();
   const cfg = loadConfig();
   const now = Date.now();
 
-  // A window whose cached reset has passed is empty again; weekly windows recur
-  // on a fixed per-account anchor, so a stale weekly reset extrapolates forward.
-  // Fresh samples pass through unchanged (their resets are in the future).
   const row = (name: string, w: UsageWindow, weekly: boolean) => {
     const passed = w.resetsAt != null && w.resetsAt <= now;
     const pct = passed ? 0 : w.usedPercentage;
@@ -46,10 +26,6 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
   };
 
   if (idx.accounts.length === 0) {
-    // A codex-only pool is a documented standalone flow: the empty-claude
-    // early return must still render it, and only a fully empty install gets
-    // the init hint (closing-review catch: bare `xx` claimed "no accounts"
-    // over a populated codex pool and pointed at the wrong init).
     if (loadCodexAccounts().accounts.length > 0) {
       console.log(c.dim("no claude accounts (run `tokenmaxxing init` to pool claude too)"));
       console.log();
@@ -60,9 +36,6 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
     return 0;
   }
 
-  // Load, sample, and save entirely under the flock: parked refreshes must not
-  // collide with an in-flight swap, and a save of an index loaded before a
-  // concurrent swap would clobber the swap's activeAccountUuid.
   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 () => {
@@ -72,19 +45,8 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
     const liveOAuth = readOAuthAccount();
     const activeOrg = liveOAuth?.organizationUuid ?? null;
     const probeOne = async (a: Account) => {
-        // Active = the org claude's own oauthAccount names, NOT the stored
-        // label conjunction: after a manual /login the label lags, and routing
-        // the genuinely-live account through the parked prober would refresh
-        // its stale parked grant and could flag a healthy account needs-reauth.
-        // probeActiveUsage's own roles check still fail-fasts on residual drift.
         const isActive = activeOrg != null && activeOrg === a.organizationUuid;
-        // The tee path never opens the credential blob, so the active account's
-        // tier comes from the live oauthAccount instead - it names this very org
-        // (uuid-matched above), so the tier is attributed to its own identity.
         if (isActive && liveOAuth?.organizationRateLimitTier != null) a.rateLimitTier = liveOAuth.organizationRateLimitTier;
-        // Active account: prefer the free statusLine push (usage.json) so we never
-        // poll its own token, which is busy exactly when it matters. per-model
-        // comes from model-usage.json (also statusLine-driven).
         const fromStatusLine: FullUsage | null =
           isActive && live && live.org === a.organizationUuid
             ? {
@@ -96,13 +58,6 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
         let viaTee = false;
         let outcome: SampleOutcome;
         if (force) {
-          // Force: ping + live probe for everyone. The tee predates the ping,
-          // so it serves ONLY as the fallback for the fail-silent `/usage`
-          // case (the probe got past every guard and claude printed no limit
-          // lines). Any other failure - identity mismatch, dead refresh, a
-          // refused ping - must stay VISIBLE: the old unconditional fallback
-          // masked pre-ping failures as healthy tee data, silently skipping
-          // the ping with no warning (closing-review catch).
           outcome = isActive ? await probeActiveUsage(a, { ping: true }) : await probeParkedUsage(a, { ping: true });
           if (!outcome.ok && fromStatusLine && outcome.reason.includes("no limit data")) {
             const failed = outcome;
@@ -121,35 +76,17 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
         outcomes.set(a.accountUuid, outcome);
         if (!outcome.ok) return;
         a.lastUsage = { fiveHour: outcome.usage.session, sevenDay: outcome.usage.weekAll };
-        // stamp when the figures were actually measured: the statusLine tee's
-        // own write time for the push-fed active account, else the probe time.
         a.lastUsageAt = viaTee && live ? live.ts : Date.now();
         if (Object.keys(outcome.usage.perModel).length > 0) {
           a.lastPerModel = outcome.usage.perModel;
-          // via the tee, the per-model rows come from model-usage.json whose
-          // own sample time may be DAYS older than the aggregate tee - dating
-          // them by the tee's timestamp inflated the null-reset self-bound
-          // (closing-review catch). A fresh probe's rows date by the probe.
           a.lastPerModelAt = viaTee && modelUsage ? (modelUsage.sampledAt ?? modelUsage.ts) : a.lastUsageAt;
         }
     };
-    // The ACTIVE probe runs FIRST, alone: it refreshes an expired live access
-    // token under claude's refresh lock, and every parked probe's fail-closed
-    // live-owner check reads that same live token - run concurrently they
-    // raced the refresh and, after the machine idled past the token lifetime,
-    // every parked sample 401'd on the first `xx status` (closing-review
-    // catch). Parked probes then run concurrently as before.
     const activeAccount = idx.accounts.find((a) => activeOrg != null && activeOrg === a.organizationUuid) ?? null;
     if (activeAccount) await probeOne(activeAccount);
-    // even when the active account's usage came from the TEE (no active
-    // probe, no refresh side effect), the parked probes still need a fresh
-    // live token for their fail-closed live-owner checks (cubic review
-    // catch, PR #35). A dead live grant is deliberately not fatal here: each
-    // parked probe reports its own honest failure reason.
     try {
       await ensureLiveTokenFresh();
     } catch {
-      // per-account guards surface the failure per probe
     }
     await Promise.all(idx.accounts.filter((a) => a !== activeAccount).map(probeOne));
     saveAccounts(idx);
@@ -159,18 +96,12 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
   console.log(c.dim(`thresholds 5h ${cfg.thresholds.session}% weekly ${cfg.thresholds.weekly}%  (${count({ n: idx.accounts.length, noun: "claude account" })})`));
   console.log();
 
-  // Display order (user decision 2026-07-18): earliest upcoming reset first
-  // (5h or extrapolated weekly, from the just-refreshed samples), needs-reauth
-  // last; the ● marker identifies the active account wherever it sorts.
   const displayAccounts = sortBy(idx.accounts, [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, now)]);
-  // The marker matches the probe routing above: active = the org claude's own
-  // oauthAccount names (the swap label can lag after a manual /login).
   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;
-    // On a failed sample, fall back to the last-known values (with a note below).
     const usage = outcome?.ok ? outcome.usage : undefined;
     const aggregate = usage ? { fiveHour: usage.session, sevenDay: usage.weekAll } : a.lastUsage;
     const perModel = usage ? usage.perModel : a.lastPerModel;
@@ -184,8 +115,6 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
 
     const tier = claudeTierLabel(a);
     console.log(`${marker} ${c.bold(a.label || a.email)}${tier ? ` ${c.dim(tier)}` : ""}${badges.length ? ` ${badges.join(" ")}` : ""}`);
-    // Chart label convention (user rule 2026-07-17): everything lowercase,
-    // model names short ("fable", "spark").
     if (aggregate) {
       row("5h", aggregate.fiveHour, false);
       row("week", aggregate.sevenDay, true);
@@ -198,10 +127,6 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
     if (outcome?.pingError != null) {
       console.log(`    ${c.yellow("ping failed (5h timer may not have started)")}: ${c.dim(outcome.pingError)}`);
     }
-    // A successful ping ALWAYS opens the 5h window (live-verified 2026-07-16),
-    // but the server's usage feed reflects it with a lag of up to a few
-    // minutes, so a probe taken seconds later can still show a dormant window.
-    // Say so rather than looking like the ping did nothing.
     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")}`);
     }
@@ -212,9 +137,6 @@ export async function cmdStatus(force = false, preRender?: () => void): Promise<
   return 0;
 }
 
-/** The codex pool, appended when it is non-empty. Every account samples via
- *  the free usage GET (nothing metered, no window started): the live account
- *  through the live auth.json, parked accounts through their parked blobs. */
 async function renderCodexSection(input: {
   cfg: Config;
   now: number;
@@ -251,8 +173,6 @@ async function renderCodexSection(input: {
   console.log();
   const windowLabel = (window: CodexWindow) =>
     isSessionWindow({ window }) ? `${Math.round((window.windowSeconds ?? 0) / 3600)}h` : "week";
-  // Same display order as the claude pool: earliest upcoming reset first
-  // across every cached window, needs-reauth last.
   const displayAccounts = sortBy(index.accounts, [
     (a) => (a.needsReauth ? 1 : 0),
     (a) => {

package/src/cli/switch.ts

@@ -1,19 +1,3 @@
-// `tokenmaxxing switch [selector]`.
-// No selector → greedy: rank EVERY account (current included) by pace pressure
-// (furthest behind its own weekly pace first, see picker.ts) among those with
-// session/week under threshold, off the cached windows.
-// When the current account already wins (or ties - swapping between equals buys
-// nothing), do nothing: the command is idempotent, so running it periodically
-// converges on the right account. With a selector → switch to that one. Runs
-// under the flock. When everything is depleted it stays on / switches to
-// whichever account recovers soonest.
-//
-// The active LABEL can drift from the live login (manual /login is the
-// surviving drift source). A no-op would freeze that drift forever, so when
-// ~/.claude.json names a different account than accounts.json we swap for real
-// instead of trusting the label - performSwap resolves the live credential's
-// true owner, harvesting the drifted login correctly.
-
 import { withLock } from "../lib/lock.ts";
 import { paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
@@ -36,10 +20,6 @@ export async function cmdSwitch(selector?: string): Promise<number> {
 
   return withLock(paths.lockFile, async () => {
     const idx = loadAccounts();
-    // ONE claude.json read for both identity fields: two reads could straddle
-    // a concurrent /login and describe two different live identities - the
-    // drift check and the seat must come from the same snapshot (cubic review
-    // catch, PR #33).
     const liveClaim = readOAuthAccount();
     const claimed = liveClaim?.accountUuid ?? null;
     const claimedOrg = liveClaim?.organizationUuid ?? null;
@@ -64,26 +44,9 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       return swapTo(target);
     }
 
-    // auto: greedy over everyone, current included - a no-op when current wins.
-    // No session context here, so every configured per-model family gates.
-    // Dead-token fallback mirrors decide.ts's greedy loop, NOT chooseAndSwap:
-    // its fallback lands on the next usable candidate unconditionally, which
-    // is right when over a bar but wrong here - a dead grant on the pace
-    // winner must re-check the seat, or a healthy current account gets a real
-    // swap onto a pace-WORSE account and the next periodic check bounces it
-    // straight back (closing-review catch). performSwap persists needs-reauth
-    // before throwing, so each reload shrinks the candidate set and the loop
-    // terminates.
     const everyone: PickCtx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: null, switchFamilies: cfg.policy.switchModels };
     while (true) {
       const cur = loadAccounts();
-      // The seat is the LIVE login's pooled account when resolvable, the
-      // stored label only as fallback - the same identity rule AND the same
-      // identity KEY as decide.ts's seatOf: the organizationUuid, since quota
-      // is metered per org and the org is what the roles endpoint verifies
-      // (bugbot review catches, PR #33). Under drift this also makes ties
-      // favor the live account: the realign swap then keeps the same
-      // credential instead of hopping accounts on a tie.
       const active =
         (claimedOrg != null ? cur.accounts.find((a) => a.organizationUuid === claimedOrg) : null) ??
         cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ??
@@ -96,7 +59,7 @@ export async function cmdSwitch(selector?: string): Promise<number> {
         return 0;
       }
       const best = pickBest(cur.accounts, { ...everyone, currentAccountUuid: active?.accountUuid ?? null });
-      if (!best) break; // no usable target: the depleted path below decides
+      if (!best) break;
       try {
         await performSwap(best);
       } catch (e) {
@@ -110,20 +73,11 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       return 0;
     }
 
-    // No usable target swapped in: everything is depleted, or the remaining
-    // candidates' refresh tokens just died (performSwap persists needs-reauth
-    // before throwing, hence the reload). Stay on / switch to whichever
-    // recovers soonest. (Layer 2 - the wall squeeze - is deliberately confined
-    // to the automatic decision path in decide.ts, which decides off the live
-    // statusLine tee; bare `xx switch` stays cache-only and simply parks here.)
     const fresh = loadAccounts();
     const earliest = pickEarliestReset(fresh.accounts, everyone);
     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 - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`)); return 1; }
-      // never freeze a label drift behind a no-op (see header).
       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"));
@@ -132,8 +86,6 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     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) {
-      // availableAt in the past means the current account is fine and the
-      // others are simply unusable - do not claim a limit that is not there.
       const msg = earliest.availableAt <= now
         ? `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}`;

package/src/cli/watch.ts

@@ -1,23 +1,12 @@
-// `tokenmaxxing watch [seconds]`: native live status (issue #3) - re-render
-// `status` on an interval instead of `watch -n 120 'tokenmaxxing status'`.
-// Plain `status` per tick, never `--force`: a ping meters real quota and starts
-// 5h session windows, so watching must stay free; each refresh costs only the
-// parked accounts' `/usage` probes the one-shot status already does.
-
 import { clamp, delay } from "es-toolkit";
 import { loadAccounts } from "../lib/state.ts";
 import { cmdStatus } from "./status.ts";
 import { c } from "./render.ts";
 
 const DEFAULT_INTERVAL_S = 120;
-/** Floor: each tick spawns a `/usage` probe per parked account (seconds each,
- *  under the flock); anything faster than this just queues probes. */
 const MIN_INTERVAL_S = 30;
-/** Cap: past ~24.8 days the setTimeout ms overflow collapses the sleep to ~1ms
- *  and the loop runs hot; a day is already beyond any sane watch cadence. */
 const MAX_INTERVAL_S = 86_400;
 
-/** Seconds between refreshes, clamped; null when the argument is not a positive number. */
 export function resolveWatchInterval(arg?: string): number | null {
   if (arg === undefined) return DEFAULT_INTERVAL_S;
   const n = Number(arg);
@@ -25,9 +14,6 @@ export function resolveWatchInterval(arg?: string): number | null {
   return clamp(n, MIN_INTERVAL_S, MAX_INTERVAL_S);
 }
 
-/** Home + clear screen + clear scrollback. Written only once the fresh frame is
- *  ready to paint (cmdStatus preRender), so the previous frame stays readable
- *  through the multi-second sample instead of blanking - watch(1) semantics. */
 const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
 
 export async function cmdWatch(intervalArg?: string): Promise<number> {
@@ -43,9 +29,6 @@ export async function cmdWatch(intervalArg?: string): Promise<number> {
     console.log(c.dim(`watch: every ${intervalS}s, ${new Date().toLocaleTimeString()}, ctrl-c to quit`));
   };
   while (true) {
-    // One failed tick (a mid-write ~/.claude.json read, a transient probe or
-    // lock error) must not kill an hours-long monitor: report it and keep the
-    // cadence, exactly like watch(1) showing a failing command's output.
     try {
       await cmdStatus(false, paintHeader);
     } catch (e) {