tokenmaxxing 1.29.0 → 1.31.0

package/DESIGN.md

@@ -30,7 +30,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
 - A `claude` **supervisor** on your PATH ahead of the real binary (`~/.config/tokenmaxxing/bin/claude`), or a shell function - you invoke it identically.
 - Four `~/.claude/settings.json` entries (merged - other settings keys are preserved, but the `statusLine` slot is taken over): the tokenmaxxing `statusLine` renderer (native since 2026-07-11; it also tees usage), a `subagentStatusLine` (per-subagent rows in the agents panel), a `Stop` hook, a `SessionStart` hook.
 - **`~/.config/tokenmaxxing/`** - the single home for config and state:
-  - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin pins, policy.*); defaults merge at read time, `xx config` edits it.
+  - `config.json` - SPARSE overrides only (thresholds.session/weekly, claudeBin/codexBin pins, policy.*); defaults apply at read time, `xx config` prints the path and the effective values, and edits happen in an editor.
   - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, label, lastUsage, lastPerModel, needsReauth, ...}` (window resets live inside lastUsage).
   - `usage.json` - live usage, written by the statusLine shim.
   - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal, depleted-pool waits only).
@@ -105,7 +105,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 ---
 
 ## 7. Scope
-**v1:** `tokenmaxxing init` / `add` / `ls` / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; threshold swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
+**v1:** `tokenmaxxing init` / `add` / `ls` (removed in 1.30.0, `status --cached` covers it) / `status` / `doctor`; the supervisor; statusLine shim + Stop/SessionStart hooks; threshold swap with `flock` + reset-aware picker; platform credential store (macOS keychain / Linux 0600 files, one facade); auto-respawn across concurrent sessions. macOS + Linux.
 
 **v2:** projected-threshold pre-emption; a `UserPromptSubmit` guard that respawns *before* a turn starts when already over; Windows.
 

package/README.md

@@ -68,17 +68,15 @@ claude                  # use claude as always
 | `tokenmaxxing auth [sel \| --all]` | reauthenticate a pooled account in place: bare lists the pool (emails shown) and asks which; a selector targets one account and tells you the email to sign in with; `--all` walks every needs-reauth account one by one |
 | `tokenmaxxing switch [sel]` | switch the claude pool: bare picks the best account (no-op when the current one wins), a selector targets one |
 | `tokenmaxxing switch --codex [sel]` | switch the codex pool (takes effect on the next codex start) |
-| `tokenmaxxing ls` | list pooled accounts |
-| `tokenmaxxing status` | accounts with 5h / weekly usage bars, active + exhausted-until-reset |
-| `tokenmaxxing watch [seconds]` | live status: re-render every N seconds (default 120, floor 30) |
-| `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
+| `tokenmaxxing status [--cached]` | accounts with 5h / weekly usage bars, active + exhausted-until-reset; `--cached` renders the stored figures without sampling |
+| `tokenmaxxing config` | the config path and the effective values; edit the file in an editor, a bad value fails the next load with the field name |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
 | `tokenmaxxing rename [--codex] <sel> <label>` / `rm [--codex] <sel>` | manage the pool (`--codex` targets the codex pool: one email can hold both a claude and a codex account) |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
 | `tokenmaxxing setup-token [--print \| rm <label\|uuid>]` | Cursor Cloud only: mint one `claude setup-token` per pooled account (a browser sign-in each) and print the `TOKENMAXXING_TOKENS` secret value; `--print` prints the stored set, `rm` drops one |
 | `tokenmaxxing cursor init [dir]` | write the Claude relay subagent and `.cursor/environment.json` into a repo |
 | `tokenmaxxing cloud run [--session <id>] [--max-turns <n>] "<prompt>"` | on a Cursor Cloud VM: run `claude -p` on a setup token, rotate to the next token on a usage limit |
-| `--json` | machine-readable output: one JSON document on stdout for `status`, `ls`, `config`, `doctor`, `check`, `switch`, `rename`, `rm`, `uninstall`, `setup-token --print`, `cursor init`, `cloud run`, and one per tick for `watch` (`ok` mirrors the exit code, failures add `error`) |
+| `--json` | machine-readable output: one JSON document on stdout for `status`, `config`, `doctor`, `check`, `switch`, `rename`, `rm`, `uninstall`, `setup-token --print`, `cursor init`, and `cloud run` (`ok` mirrors the exit code, failures add `error`) |
 
 ## How switching decides
 
@@ -126,7 +124,7 @@ tokenmaxxing add --codex    # log in another account, isolated - your primary lo
 codex                       # use codex as always
 ```
 
-Codex mechanics differ from Claude Code in one hard way: a running codex process refuses a credential swapped to a different account, so **a restart is the switch**. The installed Stop hook runs the same pace-pressure decision at each turn boundary (usage read free from codex's own rate-limit endpoint: percentages plus absolute reset times, weekly aggregate and per-model caps alike); when it swaps, the supervisor relaunches `codex resume <session-id>` on the fresh account with the transcript intact. `tokenmaxxing switch --codex [sel]` does it manually, `status`/`watch`/`ls` show both pools.
+Codex mechanics differ from Claude Code in one hard way: a running codex process refuses a credential swapped to a different account, so **a restart is the switch**. The installed Stop hook runs the same pace-pressure decision at each turn boundary (usage read free from codex's own rate-limit endpoint: percentages plus absolute reset times, weekly aggregate and per-model caps alike); when it swaps, the supervisor relaunches `codex resume <session-id>` on the fresh account with the transcript intact. `tokenmaxxing switch --codex [sel]` does it manually, `status` (and `status --cached`) shows both pools.
 
 Two codex-specific facts worth knowing: codex does not run hooks it has not been told to trust, so after `init --codex` you must open codex once and trust the tokenmaxxing Stop hook via `/hooks` (auto-switching is inert until then); and codex has no cross-process lock on `auth.json`, so tokenmaxxing serializes all of its own credential writes behind its own lock and swaps only at idle turn boundaries.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.29.0",
+  "version": "1.31.0",
   "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",

package/src/cli/config.ts

@@ -1,242 +1,25 @@
-import { existsSync, readFileSync } from "node:fs";
-import { isPlainObject } from "es-toolkit";
-import { get, set, unset } from "es-toolkit/compat";
-import { z } from "zod";
-import { paths, realClaudeBinFromEnv, realCodexBinFromEnv } from "../lib/paths.ts";
-import { ConfigFileSchema, loadConfig, mergeConfigFile } from "../lib/state.ts";
-import { writeFileAtomic } from "../lib/atomic.ts";
+import { paths } from "../lib/paths.ts";
+import { loadConfig } from "../lib/state.ts";
+import type { Config } from "../lib/types.ts";
 import { c, emitError, emitJson } from "./render.ts";
 
-export const KNOWN_KEYS = [
-  "thresholds.session",
-  "thresholds.weekly",
-  "claudeBin",
-  "codexBin",
-  "policy.projectionMargin",
-  "policy.switchModels",
-  "policy.usagePollTtlMs",
-  "policy.maxWaitMs",
-  "policy.checkIntervalMs",
-] as const;
-
-const TIMER_REWRITE_NOTE = "note: run `tokenmaxxing init` to rewrite the periodic timer at the new tick";
-
-const RawFileSchema = z.record(z.string(), z.unknown());
-
-function readRawFile(): Record<string, unknown> {
-  if (!existsSync(paths.configJson)) return {};
-  return RawFileSchema.parse(JSON.parse(readFileSync(paths.configJson, "utf8")));
-}
-
-function writeRawFile(input: { raw: Record<string, unknown> }): void {
-  writeFileAtomic(paths.configJson, JSON.stringify(input.raw, null, 2) + "\n");
-}
-
-function dottedKeys(obj: Record<string, unknown>): string[] {
-  const keys: string[] = [];
-  for (const [key, value] of Object.entries(obj)) {
-    if (isPlainObject(value)) {
-      for (const nested of Object.keys(value)) keys.push(`${key}.${nested}`);
-      continue;
-    }
-    keys.push(key);
-  }
-  return keys;
-}
-
-function unknownFileKeys(raw: Record<string, unknown>): string[] {
-  const known = new Set<string>(KNOWN_KEYS);
-  return dottedKeys(raw).filter((key) => !known.has(key));
-}
-
-function isKnownKey(key: string): boolean {
-  return KNOWN_KEYS.some((known) => known === key);
-}
-
-function envSourceFor(key: string): string | null {
-  if (key === "claudeBin" && realClaudeBinFromEnv()) return "TOKENMAXXING_CLAUDE_BIN";
-  if (key === "codexBin" && realCodexBinFromEnv()) return "TOKENMAXXING_CODEX_BIN";
-  return null;
-}
-
-function sourceOf(input: { key: string; raw: Record<string, unknown> }): { source: "env" | "file" | "default"; env: string | null } {
-  const env = envSourceFor(input.key);
-  if (env) return { source: "env", env };
-  return { source: get(input.raw, input.key) !== undefined ? "file" : "default", env: null };
-}
-
-function unknownKey(input: { key: string; json: boolean }): number {
-  emitError({
-    json: input.json,
-    message: `unknown config key: ${input.key}`,
-    notes: [`known keys: ${KNOWN_KEYS.join(", ")}`],
-    extra: { knownKeys: KNOWN_KEYS },
-  });
-  return 1;
-}
-
-function printEffective(json: boolean): number {
-  const effective = loadConfig();
-  const raw = readRawFile();
-  const unknown = unknownFileKeys(raw);
-  if (json) {
-    const sources: Record<string, string> = {};
-    const envOverrides: Record<string, string> = {};
-    for (const key of KNOWN_KEYS) {
-      const { source, env } = sourceOf({ key, raw });
-      sources[key] = source;
-      if (env) envOverrides[key] = env;
-    }
-    emitJson({ ok: true, path: paths.configJson, config: effective, sources, envOverrides, unknownKeys: unknown });
-    return 0;
-  }
-  console.log(c.dim(`config.json: ${paths.configJson}`));
-  for (const key of KNOWN_KEYS) {
-    const { source, env } = sourceOf({ key, raw });
-    const painted = source === "env" ? c.yellow(`env ${env}`) : source === "file" ? c.green("file") : c.dim("default");
-    console.log(`  ${key.padEnd(28)} ${JSON.stringify(get(effective, key))}  ${painted}`);
-  }
-  if (unknown.length > 0) {
-    console.log();
-    console.log(c.yellow(`unknown keys in the file (ignored by the loader): ${unknown.join(", ")}`));
-    console.log(c.dim("run `tokenmaxxing config tidy` to drop them"));
-  }
-  return 0;
-}
-
-function cmdGet(key: string, json: boolean): number {
-  if (!isKnownKey(key)) return unknownKey({ key, json });
-  const value = get(loadConfig(), key);
-  if (json) {
-    emitJson({ ok: true, key, value, source: sourceOf({ key, raw: readRawFile() }).source });
-    return 0;
+export function cmdConfig(args: string[], json = false): number {
+  if (args.length > 0) {
+    emitError({ json, message: `unknown config option: ${args[0]} (config takes no options; edit ${paths.configJson} in an editor)` });
+    return 2;
   }
-  console.log(JSON.stringify(value));
-  return 0;
-}
-
-function parseValue(text: string): unknown {
+  let effective: Config;
   try {
-    return JSON.parse(text);
-  } catch {
-    return text;
-  }
-}
-
-function cmdSet(key: string, valueText: string, json: boolean): number {
-  if (!isKnownKey(key)) return unknownKey({ key, json });
-  const raw = readRawFile();
-  const next = structuredClone(raw);
-  set(next, key, parseValue(valueText));
-  const validated = ConfigFileSchema.safeParse(next);
-  if (!validated.success) {
-    emitError({ json, message: `rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}` });
-    return 1;
-  }
-  const mergedCheck = mergeConfigFile(validated.data);
-  if (!mergedCheck.ok) {
-    emitError({ json, message: `rejected: ${mergedCheck.detail}` });
-    return 1;
-  }
-  writeRawFile({ raw: next });
-  const beforeFile = get(raw, key);
-  const env = envSourceFor(key);
-  if (json) {
-    emitJson({ ok: true, key, before: beforeFile === undefined ? null : beforeFile, after: get(next, key), envOverride: env });
-    return 0;
-  }
-  console.log(
-    `${key}: ${beforeFile === undefined ? "(default)" : JSON.stringify(beforeFile)} -> ${JSON.stringify(get(next, key))}`,
-  );
-  if (env) console.log(c.yellow(`note: ${env} is set and overrides the file value in this environment`));
-  if (key === "policy.checkIntervalMs") console.log(c.yellow(TIMER_REWRITE_NOTE));
-  return 0;
-}
-
-function pruneEmptyParents(raw: Record<string, unknown>): void {
-  for (const [topKey, value] of Object.entries(raw)) {
-    if (isPlainObject(value) && Object.keys(value).length === 0) {
-      delete raw[topKey];
-    }
-  }
-}
-
-function cmdUnset(key: string, json: boolean): number {
-  if (!isKnownKey(key)) return unknownKey({ key, json });
-  const raw = readRawFile();
-  if (get(raw, key) === undefined) {
-    if (json) emitJson({ ok: true, key, unset: false, value: get(loadConfig(), key) });
-    else console.log(c.dim(`${key} has no file override (default already applies)`));
-    return 0;
-  }
-  const next = structuredClone(raw);
-  unset(next, key);
-  pruneEmptyParents(next);
-  const validated = ConfigFileSchema.safeParse(next);
-  if (!validated.success) {
-    emitError({ json, message: `rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}` });
-    return 1;
-  }
-  const mergedCheck = mergeConfigFile(validated.data);
-  if (!mergedCheck.ok) {
-    emitError({ json, message: `rejected: ${mergedCheck.detail} (adjust the conflicting override before unsetting ${key})` });
+    effective = loadConfig();
+  } catch (e) {
+    emitError({ json, message: e instanceof Error ? e.message : String(e), extra: { path: paths.configJson } });
     return 1;
   }
-  writeRawFile({ raw: next });
-  const value = get(loadConfig(), key);
   if (json) {
-    emitJson({ ok: true, key, unset: true, value });
-    return 0;
-  }
-  console.log(`${key} unset -> ${JSON.stringify(value)} (default)`);
-  if (key === "policy.checkIntervalMs") console.log(c.yellow(TIMER_REWRITE_NOTE));
-  return 0;
-}
-
-function cmdTidy(json: boolean): number {
-  const raw = readRawFile();
-  const dropped = unknownFileKeys(raw);
-  const parsed = ConfigFileSchema.parse(raw);
-  const next = RawFileSchema.parse(JSON.parse(JSON.stringify(parsed)));
-  const models = get(next, "policy.switchModels");
-  const normalized = Array.isArray(models) ? models.map((model) => String(model).toLowerCase()) : null;
-  const casingChanged = normalized != null && JSON.stringify(normalized) !== JSON.stringify(models);
-  if (normalized != null) set(next, "policy.switchModels", normalized);
-  pruneEmptyParents(next);
-
-  const changed = JSON.stringify(next) !== JSON.stringify(raw);
-  if (changed) writeRawFile({ raw: next });
-  if (json) {
-    emitJson({ ok: true, changed, droppedKeys: dropped, casingNormalized: casingChanged });
-    return 0;
-  }
-  if (!changed) {
-    console.log(c.dim("nothing to tidy"));
+    emitJson({ ok: true, path: paths.configJson, effective });
     return 0;
   }
-  if (dropped.length > 0) console.log(`dropped unknown keys: ${dropped.join(", ")}`);
-  if (casingChanged) console.log("normalized switchModels casing");
-  if (dropped.length === 0 && !casingChanged) console.log("canonicalized file layout (pruned empty sections / key order)");
+  console.log(c.dim(`config.json: ${paths.configJson}`));
+  console.log(JSON.stringify(effective, null, 2));
   return 0;
 }
-
-export function cmdConfig(args: string[], json = false): number {
-  const [sub, key, value] = args;
-  try {
-    if (sub === undefined) return printEffective(json);
-    if (sub === "get" && key !== undefined) return cmdGet(key, json);
-    if (sub === "set" && key !== undefined && value !== undefined) return cmdSet(key, value, json);
-    if (sub === "unset" && key !== undefined) return cmdUnset(key, json);
-    if (sub === "tidy") return cmdTidy(json);
-  } catch (e) {
-    emitError({
-      json,
-      message: `config.json is unreadable: ${e instanceof Error ? e.message : String(e)}`,
-      notes: [`fix or delete ${paths.configJson} (defaults apply when it is absent), then re-run`],
-      extra: { path: paths.configJson },
-    });
-    return 1;
-  }
-  emitError({ json, message: "usage: tokenmaxxing config [get <key> | set <key> <value> | unset <key> | tidy]" });
-  return 2;
-}

package/src/cli/status.ts

@@ -15,7 +15,7 @@ import { gatedFamilies, type FullUsage } from "../lib/usage.ts";
 import { ThresholdsSchema, UsageWindowSchema, type Account, type CodexWindow, type Config, type UsageWindow } from "../lib/types.ts";
 
 const SampleReportSchema = z.discriminatedUnion("ok", [
-  z.object({ ok: z.literal(true), source: z.enum(["statusline", "probe"]) }),
+  z.object({ ok: z.literal(true), source: z.enum(["statusline", "probe", "cached"]) }),
   z.object({ ok: z.literal(false), reason: z.string() }),
 ]);
 
@@ -31,6 +31,7 @@ const ClaudeStatusAccountSchema = z.object({
   usage: z.object({ fiveHour: UsageWindowSchema, week: UsageWindowSchema }).nullable(),
   perModel: z.record(z.string(), UsageWindowSchema),
   usageAt: z.number().nullable(),
+  perModelAt: z.number().nullable(),
   sample: SampleReportSchema,
 });
 type ClaudeStatusAccount = z.infer<typeof ClaudeStatusAccountSchema>;
@@ -83,11 +84,11 @@ function currentCodexWindow(w: CodexWindow, now: number): CodexWindow {
   return { ...currentWindow(w, !isSessionWindow({ window: w }), now), windowSeconds: w.windowSeconds };
 }
 
-async function collectClaude(input: { cfg: Config; now: number }): Promise<StatusReport["claude"]> {
-  const { cfg, now } = input;
+async function collectClaude(input: { cfg: Config; now: number; cached: boolean }): Promise<StatusReport["claude"]> {
+  const { cfg, now, cached } = input;
   let idx = loadAccounts();
   const samples = new Map<string, { outcome: SampleOutcome; viaTee: boolean }>();
-  if (idx.accounts.length > 0) {
+  if (idx.accounts.length > 0 && !cached) {
     await withLock(paths.lockFile, async () => {
       idx = loadAccounts();
       console.error(c.dim("sampling live usage..."));
@@ -137,11 +138,11 @@ async function collectClaude(input: { cfg: Config; now: number }): Promise<Statu
 
   const families = gatedFamilies(loadUsage()?.model ?? null, cfg.policy.switchModels);
   const bars = thresholdBars(cfg);
-  const liveAccount = readOAuthAccount()?.accountUuid ?? null;
+  const liveAccount = cached ? idx.activeAccountUuid : (readOAuthAccount()?.accountUuid ?? 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 sampled = samples.get(a.accountUuid);
+    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 {
@@ -156,7 +157,14 @@ async function collectClaude(input: { cfg: Config; now: number }): Promise<Statu
       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 },
+      perModelAt: a.lastPerModelAt ?? null,
+      sample: sampled
+        ? sampled.outcome.ok
+          ? { ok: true, source: sampled.viaTee ? "statusline" : "probe" }
+          : { ok: false, reason: sampled.outcome.reason }
+        : cached
+          ? { ok: true, source: "cached" }
+          : { ok: false, reason: "not sampled" },
     };
   });
   return {
@@ -167,34 +175,38 @@ async function collectClaude(input: { cfg: Config; now: number }): Promise<Statu
   };
 }
 
-async function collectCodex(input: { cfg: Config; now: number }): Promise<StatusReport["codex"]> {
-  const { cfg, now } = input;
+async function collectCodex(input: { cfg: Config; now: number; cached: boolean }): Promise<StatusReport["codex"]> {
+  const { cfg, now, cached } = input;
   const bars = thresholdBars(cfg);
   let index = loadCodexAccounts();
   if (index.accounts.length === 0) return { bars, accounts: [] };
 
-  console.error(c.dim("sampling codex usage..."));
   const outcomes = new Map<string, CodexSampleOutcome>();
   let liveId: string | null = null;
-  await withLock(codexPaths.lockFile, async () => {
-    index = loadCodexAccounts();
-    liveId = liveCodexAccountId();
-    await Promise.all(
-      index.accounts.map(async (account) => {
-        const outcome = await sampleCodexAccount({ account, liveAccountId: liveId, now });
-        outcomes.set(account.accountId, outcome);
-        if (outcome.ok) {
-          account.lastUsage = { aggregate: outcome.usage.aggregate, perLimit: outcome.usage.perLimit };
-          account.lastUsageAt = Date.now();
-          if (outcome.usage.email != null) account.email = outcome.usage.email;
-          if (outcome.usage.planType != null) account.planType = outcome.usage.planType;
-        } else if (outcome.deadGrant) {
-          account.needsReauth = true;
-        }
-      }),
-    );
-    saveCodexAccounts({ index });
-  });
+  if (cached) {
+    liveId = index.activeAccountId;
+  } else {
+    console.error(c.dim("sampling codex usage..."));
+    await withLock(codexPaths.lockFile, async () => {
+      index = loadCodexAccounts();
+      liveId = liveCodexAccountId();
+      await Promise.all(
+        index.accounts.map(async (account) => {
+          const outcome = await sampleCodexAccount({ account, liveAccountId: liveId, now });
+          outcomes.set(account.accountId, outcome);
+          if (outcome.ok) {
+            account.lastUsage = { aggregate: outcome.usage.aggregate, perLimit: outcome.usage.perLimit };
+            account.lastUsageAt = Date.now();
+            if (outcome.usage.email != null) account.email = outcome.usage.email;
+            if (outcome.usage.planType != null) account.planType = outcome.usage.planType;
+          } else if (outcome.deadGrant) {
+            account.needsReauth = true;
+          }
+        }),
+      );
+      saveCodexAccounts({ index });
+    });
+  }
 
   const ordered = sortBy(index.accounts, [
     (a) => (a.needsReauth ? 1 : 0),
@@ -205,7 +217,7 @@ async function collectCodex(input: { cfg: Config; now: number }): Promise<Status
     },
   ]);
   const accounts = ordered.map((account): CodexStatusAccount => {
-    const outcome = outcomes.get(account.accountId) ?? { ok: false, reason: "not sampled", deadGrant: false };
+    const outcome = outcomes.get(account.accountId);
     const usage = account.lastUsage;
     return {
       label: account.label,
@@ -224,7 +236,13 @@ async function collectCodex(input: { cfg: Config; now: number }): Promise<Status
           }
         : null,
       usageAt: account.lastUsageAt ?? null,
-      sample: outcome.ok ? { ok: true, source: "probe" } : { ok: false, reason: outcome.reason },
+      sample: outcome
+        ? outcome.ok
+          ? { ok: true, source: "probe" }
+          : { ok: false, reason: outcome.reason }
+        : cached
+          ? { ok: true, source: "cached" }
+          : { ok: false, reason: "not sampled" },
     };
   });
   return { bars, accounts };
@@ -298,6 +316,10 @@ function sampleFailedNotes(input: { cached: boolean; usageAt: number | null; rea
   ];
 }
 
+function cachedNote(usageAt: number | null, now: number): Note {
+  return { paint: c.dim, text: usageAt != null ? `cached ${fmtAgo(usageAt, now)}` : "never sampled" };
+}
+
 function headerLine(input: { active: boolean; needsReauth: boolean; exhausted: boolean; name: string; tier: string | null }): string {
   const marker = input.active ? c.green("●") : c.dim("○");
   const badges: string[] = [];
@@ -317,7 +339,11 @@ function codexCard(account: CodexStatusAccount, now: number): Card {
       for (const window of windows) lines.push(usageRow(codexLimitLabel({ limitName: name }), window));
     }
   }
-  const notes = account.sample.ok ? [] : sampleFailedNotes({ cached: account.usage != null, usageAt: account.usageAt, reason: account.sample.reason, now });
+  const notes = account.sample.ok
+    ? account.sample.source === "cached"
+      ? [cachedNote(account.usageAt, now)]
+      : []
+    : sampleFailedNotes({ cached: account.usage != null, usageAt: account.usageAt, reason: account.sample.reason, now });
   return { lines, notes };
 }
 
@@ -342,6 +368,11 @@ function claudeCard(a: ClaudeStatusAccount, now: number, staleAfterMs: number):
     const age = a.usageAt != null ? fmtAgo(a.usageAt, now) : "age unknown";
     notes.push({ paint: stale ? c.yellow : c.dim, text: `statusline tee ${age}${stale ? " (stale)" : ""}` });
   }
+  if (a.sample.ok && a.sample.source === "cached") {
+    const note = cachedNote(a.usageAt, now);
+    const perModelAged = Object.keys(a.perModel).length > 0 && a.perModelAt !== a.usageAt;
+    notes.push(perModelAged ? { ...note, text: `${note.text}, per-model ${a.perModelAt != null ? fmtAgo(a.perModelAt, now) : "age unknown"}` } : note);
+  }
   if (!a.sample.ok) {
     notes.push(...sampleFailedNotes({ cached: a.usage != null || Object.keys(a.perModel).length > 0, usageAt: a.usageAt, reason: a.sample.reason, now }));
   }
@@ -365,17 +396,15 @@ function renderClaude(input: { claude: StatusReport["claude"]; codexPooled: bool
   renderGrid(claude.accounts.map((a) => claudeCard(a, now, staleAfterMs)));
 }
 
-export async function cmdStatus(opts: { json?: boolean; preRender?: () => void } = {}): Promise<number> {
-  const { json = false } = opts;
+export async function cmdStatus(opts: { json?: boolean; cached?: boolean } = {}): Promise<number> {
+  const { json = false, cached = false } = opts;
   const cfg = loadConfig();
   const now = Date.now();
-  const claude = await collectClaude({ cfg, now });
+  const claude = await collectClaude({ cfg, now, cached });
   if (!json) {
-    opts.preRender?.();
-    const at = Date.now();
-    renderClaude({ claude, codexPooled: loadCodexAccounts().accounts.length > 0, now: at, staleAfterMs: cfg.policy.usagePollTtlMs });
+    renderClaude({ claude, codexPooled: loadCodexAccounts().accounts.length > 0, now: Date.now(), staleAfterMs: cfg.policy.usagePollTtlMs });
   }
-  const codex = await collectCodex({ cfg, now });
+  const codex = await collectCodex({ cfg, now, cached });
   if (json) {
     const report: StatusReport = { now, claude, codex };
     emitJson({ ok: true, ...report });

package/src/lib/state.ts

@@ -15,91 +15,26 @@ import {
   type UsageState,
 } from "./types.ts";
 
-const DEFAULT_CONFIG: Config = {
-  thresholds: { session: 90, weekly: 98 },
-  claudeBin: "",
-  codexBin: "",
-  policy: {
-    projectionMargin: 0,
-    switchModels: ["fable"],
-    usagePollTtlMs: 90_000,
-    maxWaitMs: 3_600_000,
-    checkIntervalMs: 60_000,
-  },
-};
-
-const PercentSchema = z.number().min(0).max(100);
-
-export const ConfigFileSchema = z
-  .object({
-    thresholds: z.object({ session: PercentSchema, weekly: PercentSchema }).partial(),
-    claudeBin: z.string(),
-    codexBin: z.string(),
-    policy: z
-      .object({
-        projectionMargin: PercentSchema,
-        switchModels: z.array(z.string()),
-        usagePollTtlMs: z.number().int().positive(),
-        maxWaitMs: z.number().int().positive(),
-        checkIntervalMs: z.number().int().min(10_000),
-      })
-      .partial(),
-  })
-  .partial();
-
-const MergeOutcomeSchema = z.union([
-  z.object({ ok: z.literal(true), config: ConfigSchema }),
-  z.object({ ok: z.literal(false), detail: z.string() }),
-]);
-export type MergeOutcome = z.infer<typeof MergeOutcomeSchema>;
-
-export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutcome {
-  const cfg: Config = {
-    ...DEFAULT_CONFIG,
-    thresholds: { ...DEFAULT_CONFIG.thresholds },
-    policy: { ...DEFAULT_CONFIG.policy },
-  };
-  cfg.thresholds.session = p.thresholds?.session ?? cfg.thresholds.session;
-  cfg.thresholds.weekly = p.thresholds?.weekly ?? cfg.thresholds.weekly;
-  cfg.claudeBin = p.claudeBin ?? cfg.claudeBin;
-  cfg.codexBin = p.codexBin ?? cfg.codexBin;
-  cfg.policy.projectionMargin = p.policy?.projectionMargin ?? cfg.policy.projectionMargin;
-  cfg.policy.usagePollTtlMs = p.policy?.usagePollTtlMs ?? cfg.policy.usagePollTtlMs;
-  cfg.policy.maxWaitMs = p.policy?.maxWaitMs ?? cfg.policy.maxWaitMs;
-  cfg.policy.checkIntervalMs = p.policy?.checkIntervalMs ?? cfg.policy.checkIntervalMs;
-  if (p.policy?.switchModels) {
-    cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
-  }
-  const envBin = realClaudeBinFromEnv();
-  if (envBin) cfg.claudeBin = envBin;
-  const envCodexBin = realCodexBinFromEnv();
-  if (envCodexBin) cfg.codexBin = envCodexBin;
-  const merged = ConfigSchema.safeParse(cfg);
-  if (!merged.success) {
-    return { ok: false, detail: merged.error.issues.map((issue) => issue.message).join("; ") };
-  }
-  return { ok: true, config: merged.data };
-}
-
 export function loadConfig(): Config {
-  let fileData: z.infer<typeof ConfigFileSchema> = {};
+  let raw: unknown = {};
   if (existsSync(paths.configJson)) {
-    let raw: unknown;
     try {
       raw = JSON.parse(readFileSync(paths.configJson, "utf8"));
     } catch {
       throw new Error(`${paths.configJson} is corrupt (unparsable JSON) - fix or remove it`);
     }
-    const parsed = ConfigFileSchema.safeParse(raw);
-    if (!parsed.success) {
-      const fields = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
-      throw new Error(`${paths.configJson} has wrong-typed values (${fields}) - fix or remove them`);
-    }
-    fileData = parsed.data;
   }
-  const outcome = mergeConfigFile(fileData);
-  if (!outcome.ok) throw new Error(`${paths.configJson} is invalid: ${outcome.detail} - fix or remove the offending values`);
-  return outcome.config;
+  const parsed = ConfigSchema.safeParse(raw);
+  if (!parsed.success) {
+    const fields = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
+    throw new Error(`${paths.configJson} is invalid (${fields}) - fix or remove the offending values`);
+  }
+  const cfg = parsed.data;
+  const envBin = realClaudeBinFromEnv();
+  if (envBin) cfg.claudeBin = envBin;
+  const envCodexBin = realCodexBinFromEnv();
+  if (envCodexBin) cfg.codexBin = envCodexBin;
+  return cfg;
 }
 
 export function pinBinOverride(input: { key: "claudeBin" | "codexBin"; bin: string }): void {

package/src/lib/types.ts

@@ -101,19 +101,30 @@ export type Thresholds = z.infer<typeof ThresholdsSchema>;
 
 export const ConfigSchema = z
   .object({
-    thresholds: ThresholdsSchema,
-    claudeBin: z.string(),
-    codexBin: z.string(),
-    policy: z.object({
-      projectionMargin: z.number().min(0).max(100),
-      switchModels: z.array(z.string()),
-      usagePollTtlMs: z.number().int().positive(),
-      maxWaitMs: z.number().int().positive(),
-      checkIntervalMs: z.number().int().min(10_000),
-    }),
+    thresholds: z
+      .object({
+        session: z.number().min(0).max(100).default(90),
+        weekly: z.number().min(0).max(100).default(98),
+      })
+      .prefault({}),
+    claudeBin: z.string().default(""),
+    codexBin: z.string().default(""),
+    policy: z
+      .object({
+        projectionMargin: z.number().min(0).max(100).default(0),
+        switchModels: z
+          .array(z.string())
+          .default(["fable"])
+          .transform((models) => models.map((model) => model.toLowerCase())),
+        usagePollTtlMs: z.number().int().positive().default(90_000),
+        maxWaitMs: z.number().int().positive().default(3_600_000),
+        checkIntervalMs: z.number().int().min(10_000).default(60_000),
+      })
+      .prefault({}),
   })
   .refine((cfg) => cfg.policy.projectionMargin < Math.min(cfg.thresholds.session, cfg.thresholds.weekly), {
-    message: "policy.projectionMargin must be strictly below both thresholds (the bars would hit zero and every account would read as exhausted)",
+    path: ["policy", "projectionMargin"],
+    message: "must be strictly below both thresholds (the bars would hit zero and every account would read as exhausted)",
   });
 export type Config = z.infer<typeof ConfigSchema>;
 

package/src/main.ts

@@ -15,9 +15,7 @@ import { cmdCodexInit } from "./cli/codexinit.ts";
 import { cmdCodexSwitch } from "./cli/codexswitch.ts";
 import { runCodexSupervisor } from "./entries/codexsupervisor.ts";
 import { runCodexStopHook } from "./entries/codexstophook.ts";
-import { cmdLs } from "./cli/ls.ts";
 import { cmdStatus } from "./cli/status.ts";
-import { cmdWatch } from "./cli/watch.ts";
 import { cmdDoctor } from "./cli/doctor.ts";
 import { cmdRm } from "./cli/rm.ts";
 import { cmdCodexRm } from "./cli/codexrm.ts";
@@ -32,6 +30,7 @@ import { timerDeactivationHint, uninstallSupervisor } from "./lib/install.ts";
 import { c, emitError, emitJson } from "./cli/render.ts";
 
 const JSON_FLAG = "--json";
+const CACHED_FLAG = "--cached";
 const INTERACTIVE_COMMANDS = new Set(["init", "add", "auth"]);
 
 function printHelp(): void {
@@ -46,10 +45,8 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing add --codex")}   register an additional codex account (isolated login)
   ${c.cyan("tokenmaxxing auth")} [sel | --all]  reauthenticate a pooled account in place (bare = pick from a list; --all = every needs-reauth account, one by one)
   ${c.cyan("tokenmaxxing switch --codex")} [sel]  switch the codex pool (takes effect on next codex start)
-  ${c.cyan("tokenmaxxing ls")}         list pooled accounts
-  ${c.cyan("tokenmaxxing status")}     accounts with 5h / weekly / per-model usage bars
-  ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120)
-  ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
+  ${c.cyan("tokenmaxxing status")} [--cached]  accounts with 5h / weekly / per-model usage bars (--cached: the stored figures, no sampling)
+  ${c.cyan("tokenmaxxing config")}     print the config path and the effective values (edit the file in an editor)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex] <sel>
@@ -58,7 +55,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing cursor init")} [dir]  write the Claude relay subagent (.cursor/agents/claude.md) and .cursor/environment.json into a repo
   ${c.cyan("tokenmaxxing cloud run")} [--session <id>] [--max-turns <n>] "<prompt>"  on a Cursor Cloud VM: run claude -p on a setup token from TOKENMAXXING_TOKENS, rotate to the next token on a usage limit
 
-  ${c.cyan("--json")}                  print one JSON document on stdout instead of text (status, ls, config, doctor, check, switch, rename, rm, uninstall, setup-token --print, cursor init, cloud run; one per tick for watch); every document carries ${c.bold("ok")}, failures add ${c.bold("error")}
+  ${c.cyan("--json")}                  print one JSON document on stdout instead of text (status, config, doctor, check, switch, rename, rm, uninstall, setup-token --print, cursor init, cloud run); every document carries ${c.bold("ok")}, failures add ${c.bold("error")}
 
   ${c.dim("(aliased as")} ${c.cyan("xx")}${c.dim(")")} - then just run ${c.bold("claude")} as always; it switches accounts near quota automatically.`);
 }
@@ -82,9 +79,15 @@ async function main(): Promise<number> {
 
   jsonMode = argv.includes(JSON_FLAG);
   const json = jsonMode;
-  const args = argv.filter((a) => a !== JSON_FLAG);
+  const cached = argv.includes(CACHED_FLAG);
+  const args = argv.filter((a) => a !== JSON_FLAG && a !== CACHED_FLAG);
   const sub = args[0];
 
+  if (cached && sub != null && sub !== "status") {
+    emitError({ json, message: `${CACHED_FLAG} applies to status only, not ${sub}` });
+    return 2;
+  }
+
   if (json && sub != null && INTERACTIVE_COMMANDS.has(sub)) {
     emitError({ json, message: `${sub} is interactive (it runs a login flow) and has no --json form` });
     return 2;
@@ -112,10 +115,10 @@ async function main(): Promise<number> {
     case "status": {
       const extra = args[1];
       if (extra != null) {
-        emitError({ json, message: `unknown status option: ${extra} (status takes no options)` });
+        emitError({ json, message: `unknown status option: ${extra} (status takes only ${CACHED_FLAG})` });
         return 2;
       }
-      return cmdStatus({ json });
+      return cmdStatus({ json, cached });
     }
     case "switch": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
@@ -132,8 +135,6 @@ async function main(): Promise<number> {
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "auth": return cmdAuth(args.slice(1));
-    case "ls": return cmdLs(json);
-    case "watch": return cmdWatch(args[1], json);
     case "doctor": return cmdDoctor(json);
     case "rm": {
       const rest = args.slice(1).filter((a) => a !== "--codex");

package/src/cli/ls.ts

@@ -1,75 +0,0 @@
-import { loadAccounts } from "../lib/state.ts";
-import { loadCodexAccounts } from "../lib/codexstate.ts";
-import { liveCodexAccountId } from "../lib/codexsample.ts";
-import { c, claudeTierLabel, emitJson } from "./render.ts";
-
-export function cmdLs(json = false): number {
-  const idx = loadAccounts();
-
-  if (json) {
-    const codex = loadCodexAccounts();
-    const liveId = codex.accounts.length > 0 ? liveCodexAccountId() : null;
-    emitJson({
-      ok: true,
-      claude: {
-        activeAccountUuid: idx.activeAccountUuid,
-        accounts: idx.accounts.map((a) => ({
-          label: a.label,
-          email: a.email,
-          accountUuid: a.accountUuid,
-          organizationUuid: a.organizationUuid,
-          tier: claudeTierLabel(a),
-          active: a.accountUuid === idx.activeAccountUuid,
-          needsReauth: a.needsReauth === true,
-          addedAt: a.addedAt,
-        })),
-      },
-      codex: {
-        activeAccountId: liveId,
-        accounts: codex.accounts.map((account) => ({
-          label: account.label,
-          email: account.email,
-          accountId: account.accountId,
-          planType: account.planType,
-          active: account.accountId === liveId,
-          needsReauth: account.needsReauth === true,
-          addedAt: account.addedAt,
-        })),
-      },
-    });
-    return 0;
-  }
-
-  if (idx.accounts.length === 0) {
-    console.log(c.dim("no accounts yet - run `tokenmaxxing init` then `tokenmaxxing add`"));
-  }
-  for (const a of idx.accounts) {
-    const active = a.accountUuid === idx.activeAccountUuid;
-    const marker = active ? c.green("●") : c.dim("○");
-    const flags: string[] = [];
-    if (active) flags.push(c.green("active"));
-    if (a.needsReauth) flags.push(c.red("needs-reauth"));
-    const tag = flags.length ? ` ${flags.join(" ")}` : "";
-    const label = a.label || a.email;
-    console.log(`${marker} ${c.bold(label)}${tag}`);
-    console.log(`  ${c.dim(`org ${a.organizationUuid.slice(0, 8)}, ${claudeTierLabel(a) ?? "?"}, uuid ${a.accountUuid.slice(0, 8)}`)}`);
-  }
-
-  const codex = loadCodexAccounts();
-  if (codex.accounts.length > 0) {
-    const liveId = liveCodexAccountId();
-    console.log();
-    console.log(c.dim("codex"));
-    for (const account of codex.accounts) {
-      const active = account.accountId === liveId;
-      const marker = active ? c.green("●") : c.dim("○");
-      const flags: string[] = [];
-      if (active) flags.push(c.green("active"));
-      if (account.needsReauth) flags.push(c.red("needs-reauth"));
-      const tag = flags.length ? ` ${flags.join(" ")}` : "";
-      console.log(`${marker} ${c.bold(account.label)}${tag}`);
-      console.log(`  ${c.dim(`${account.planType ?? "?"}, id ${account.accountId.slice(0, 8)}`)}`);
-    }
-  }
-  return 0;
-}

package/src/cli/watch.ts

@@ -1,46 +0,0 @@
-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, emitError, emitJson } from "./render.ts";
-
-const DEFAULT_INTERVAL_S = 120;
-const MIN_INTERVAL_S = 30;
-const MAX_INTERVAL_S = 86_400;
-
-export function resolveWatchInterval(arg?: string): number | null {
-  if (arg === undefined) return DEFAULT_INTERVAL_S;
-  const n = Number(arg);
-  if (!Number.isFinite(n) || n <= 0) return null;
-  return clamp(n, MIN_INTERVAL_S, MAX_INTERVAL_S);
-}
-
-const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
-
-export async function cmdWatch(intervalArg?: string, json = false): Promise<number> {
-  const intervalS = resolveWatchInterval(intervalArg);
-  if (intervalS === null) {
-    emitError({ json, message: `watch interval must be a positive number of seconds, got: ${intervalArg}` });
-    return 2;
-  }
-  if (loadAccounts().accounts.length === 0 && loadCodexAccounts().accounts.length === 0) return cmdStatus({ json });
-
-  const paintHeader = () => {
-    process.stdout.write(process.stdout.isTTY ? CLEAR : "\n");
-    console.log(c.dim(`watch: every ${intervalS}s, ${new Date().toLocaleTimeString()}, ctrl-c to quit`));
-  };
-  while (true) {
-    try {
-      await cmdStatus(json ? { json } : { preRender: paintHeader });
-    } catch (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);
-  }
-}