tokenmaxxing 0.13.1 → 0.15.0

package/DESIGN.md

@@ -1,6 +1,6 @@
 # tokenmaxxing - design
 
-Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (**95%** of the 5h session window, **98%** of a weekly window), tokenmaxxing swaps to a fresh account and - at the next safe turn boundary - **restarts your session resumed on it, automatically**. Works across many concurrent sessions at once.
+Automatic Claude Code account switching. You run `claude` exactly as always; when the active account crosses its swap threshold (**95%** of the 5h session window, **98%** of a weekly window), tokenmaxxing swaps the credential to a fresh account at a safe turn boundary and **your running session adopts it in place - no restart**. Works across many concurrent sessions at once; a fully depleted pool pauses with a countdown and auto-resumes at the soonest reset.
 
 > Scope: **Claude Code only, macOS first.** Codex and other CLIs deferred (see `.memory/cc-codex-auth-mechanics.md`).
 >
@@ -10,11 +10,11 @@ Automatic Claude Code account switching. You run `claude` exactly as always; whe
 
 ## 1. Why there is a thin supervisor (and why that's the whole trick)
 
-A **running** `claude` DOES adopt an externally swapped credential (verified live 2026-07-10, correcting this document's original claim): an ensure-fresh poll re-reads the credential store around every request, so a swap lands within ~30s on macOS (raw keychain cache) and on the next request on Linux. What a swap alone cannot give you is a *clean cutover*: a mid-flight 429 retry keeps its already-snapshotted token, and an account already at the wall still needs the session paused until something resets.
+A **running** `claude` DOES adopt an externally swapped credential (verified live 2026-07-10, correcting this document's original claim): an ensure-fresh poll re-reads the credential store around every request, so a swap lands within ~30s on macOS (raw keychain cache) and on the next request on Linux. A plain swap therefore needs no process management at all (since 0.15.0, 2026-07-16; earlier versions respawned on every swap): the Stop hook swaps the credential and the session keeps running. What adoption cannot give you is the depleted case: when every account is at the wall the session must be PAUSED until something resets, and a live `claude` cannot pause itself.
 
-So the supervisor's job is to **replace the process at a salvageable moment**: after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt - killing it there loses nothing, and a `claude --resume <session-id>` comes back cold on the new account and continues exactly where it left off. **This is why we swap below 100%: the headroom is the budget to reach a clean turn boundary and respawn before the account actually hits the wall.** The session window swaps at 95 (a 5h reset is cheap to sit out) while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
+So the supervisor's job is narrow: on a depleted pool it **replaces the process at a salvageable moment** - after a turn completes, the conversation is fully written to the transcript JSONL and `claude` is idle at the prompt, so killing it there loses nothing - shows an interruptible countdown to the soonest reset, and relaunches `claude --resume <session-id>` when it passes. **Thresholds still sit below 100%: the headroom is the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the account actually hits the wall.** The session window swaps at 95 (a 5h reset is cheap to sit out) while the weekly windows drain to 98 (weekly allowance is use-it-or-lose-it).
 
-A hook can't do the respawn - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
+A hook can't do the pause-and-relaunch - when `claude` exits, the shell owns the terminal. So tokenmaxxing installs a **supervisor** (aliased to `claude`) that owns the process lifecycle:
 
 ```
 supervisor (you type `claude`)  →  real claude (in a PTY)  →  Stop hook
@@ -33,7 +33,7 @@ It is a process/PTY manager only - spawn, forward the terminal, wait, restore te
   - `config.json` - threshold, account order/policy.
   - `accounts.json` - non-secret index `{email, organizationUuid, accountUuid, lastUsage, resetsAt, needs_reauth}`.
   - `usage.json` - live usage, written by the statusLine shim.
-  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal).
+  - `respawn/<session-id>` - per-session respawn markers (the hook→supervisor signal, depleted-pool waits only).
   - `bin/claude` - the supervisor.
 - Per-account **credentials** follow the platform's Claude Code store: macOS = login-keychain items `tokenmaxxing-cred-<accountUuid[:8]>` (never plaintext on disk); Linux = 0600 files `creds/tokenmaxxing-cred-<accountUuid[:8]>.json` (the same plaintext model claude itself uses - its Linux build has no keyring path at all, binary-verified 2.1.205). One `credstore` facade dispatches on a `{kind: keychain|file}` target; call sites never branch on platform.
 
@@ -49,10 +49,10 @@ The Stop hook's stdin has no usage data, but the **statusLine does** (`rate_limi
 ### 3.2 Detect + swap + signal (Stop hook, per turn)
 1. Read `usage.json`; `exit 0` fast if every window is under its threshold (metered per `organizationUuid`).
 2. Else take a `flock` on `~/.config/tokenmaxxing/lock`, re-check under it (parallel sessions race - first winner already swapped), pick the best parked account (not rate-limited, furthest behind its own weekly pace first: highest remaining% / time-to-weekly-reset, since unused allowance is forfeited at the fixed per-account reset; tiebreak soonest expiry then lowest 7-day usage), and **swap the credential** (§3.4).
-3. Write `respawn/<session_id>` (atomic temp+rename) and `SIGTERM` the parent `claude` (`kill -TERM $PPID`). The turn is already committed, so this is a clean stop.
+3. Done - the running session adopts the new credential on its own within a request or two. Only when the pool is depleted (the decision returned a `waitUntil`: pre-parked on the soonest-recovering account, or staying on the current one when it recovers first) does the hook write `respawn/<session_id>` (atomic temp+rename).
 
-### 3.3 Respawn (supervisor)
-The supervisor's `claude` call returns; it sees `respawn/<sid>`, deletes it, resets the terminal, prints `↻ switched to <account>`, and relaunches `claude --resume <sid>`. The resumed process reads the keychain cold → runs on the new account, same conversation. The `SessionStart` hook (source `resume`) re-checks the account before the first turn as a backstop.
+### 3.3 Depleted-pool pause (supervisor)
+The supervisor sees `respawn/<sid>`, SIGTERMs its child at the already-committed turn boundary, deletes the marker, resets the terminal, shows an interruptible countdown to the reset, and relaunches `claude --resume <sid>` when it passes. The resumed process reads the keychain cold → runs on the recovered account, same conversation. The `SessionStart` hook (source `resume`) re-checks the account before the first turn as a backstop.
 
 ### 3.4 Swap sequence (under the lock)
 1. **Harvest the live credential into its TRUE owner's backup** - read the current `Claude Code-credentials` blob and resolve which account it actually belongs to via the roles endpoint (`GET /api/oauth/claude_cli/roles`), NOT the `accounts.json` active label. The label drifts from the live blob (a kill mid-swap, a manual `/login`), and harvesting by label once overwrote another account's backup and destroyed its only credential. Mandatory anyway: Claude rotates the refresh token in place, so older backups are dead. Refuse the swap if the live credential belongs to no pooled account.
@@ -62,7 +62,7 @@ The supervisor's `claude` call returns; it sees `respawn/<sid>`, deletes it, res
 5. Do steps 1, 3, 4 inside Claude's own `~/.claude.lock` so the writes can't collide with a token refresh.
 
 ### 3.5 Multiple concurrent sessions
-Each terminal ran the supervisor, so each has its own child `claude`, its own `--session-id`, and its own respawn marker. When the shared account hits a threshold, the first Stop hook to win the `flock` performs the one swap; **every** session's Stop hook writes its own respawn marker and SIGTERMs its own `claude`; **every** supervisor independently relaunches `claude --resume <its-own-sid>`. All of them come back on the new account, each continuing its own conversation. (They share one credential, so they always move together - consistent with "one current account, many windows.")
+Each terminal ran the supervisor, so each has its own child `claude` and its own `--session-id`. When the shared account hits a threshold, the first Stop hook to win the `flock` performs the one swap; every running session then adopts the new credential in place - no restarts. (They share one credential, so they always move together - consistent with "one current account, many windows.") Only a depleted pool fans out: each supervised session's Stop hook writes its own `respawn/<sid>` marker, and each supervisor independently pauses and later relaunches `claude --resume <its-own-sid>`.
 
 ---
 
@@ -83,10 +83,11 @@ The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from the
 ---
 
 ## 6. Honest papercuts
-- **Respawn hiccup.** At the swap turn you see `claude` restart (~1–2s) and resume. Anything you typed in the split second before respawn is lost - mitigate by respawning fast and showing a clear "switching" state; the supervisor resets terminal mode so nothing is left garbled.
-- **One cold turn.** Prompt cache is org-scoped: the first turn after resuming on B re-uploads context once (bigger on long transcripts).
-- **Single-turn overshoot.** If one turn jumps from under the threshold straight past the wall, that turn can end rate-limited before the Stop hook swaps; the respawn then still recovers it. Projected threshold reduces this.
-- **Shared blast radius.** All default-profile sessions share one keychain item, so a swap moves them all (each via its own respawn). The `flock` + re-check is mandatory or racing hooks burn two accounts at once.
+- **Respawn hiccup (depleted pause only).** Plain swaps never restart the session. When the whole pool is depleted you see `claude` stop, a countdown, and a resume; anything typed in the split second before the SIGTERM is lost, and the supervisor resets terminal mode so nothing is left garbled.
+- **Adoption lag.** macOS reads the keychain through a raw 30s cache, so at most the first turn after a swap can still meter the old account. The bars' headroom absorbs it.
+- **One cold turn.** Prompt cache is org-scoped: the first turn on B re-uploads context once (bigger on long transcripts).
+- **Single-turn overshoot.** If one turn jumps from under the threshold straight past the wall, that turn can end rate-limited before the Stop hook swaps; the swap then still recovers the session (its next turn adopts the fresh account). Projected threshold reduces this.
+- **Shared blast radius.** All default-profile sessions share one keychain item, so a swap moves them all (each adopts in place). The `flock` + re-check is mandatory or racing hooks burn two accounts at once.
 - **Refresh-token rotation / parked-token rot.** Step 1 re-harvest is mandatory; a parked refresh token can be invalidated by logging in elsewhere → picker must catch `invalid_grant`, mark `needs_reauth`, fall through.
 - **statusLine fragility.** The shim is the most visible surface - a bug flickers or breaks your real status line. Keep it O(ms), write-on-change.
 - **Keychain blob size & ps-safety.** The live `Claude Code-credentials` item also holds per-MCP-server OAuth state, so it can exceed `security -i`'s ~4KB interactive line buffer (verified on a real machine - a 4.3KB blob truncated). tokenmaxxing therefore stores parked backups as **`claudeAiOauth`-only** (small → always the ps-safe stdin write) and, on a swap, **merges** the fresh `claudeAiOauth` into the *current* live blob so MCP tokens survive the switch - using the argv write path (secret briefly visible in `ps` on your own machine) only for that one oversized live write.

package/README.md

@@ -1,19 +1,18 @@
 # tokenmaxxing
 
-**Automatic Claude Code account switching.** Run `claude` exactly as you always do; when the active account crosses its usage limit, tokenmaxxing swaps to a fresh account and - at the next safe turn boundary - restarts your session *resumed on it*, automatically. Works across many concurrent sessions.
+**Automatic Claude Code account switching.** Run `claude` exactly as you always do; when the active account nears its usage limit, tokenmaxxing swaps the credential to a fresher account at a safe turn boundary and your session keeps running on it - no restart, same conversation. Works across many concurrent sessions. Only when the whole pool is at its limit does anything visible happen: a countdown that auto-resumes at the soonest reset.
 
 > **Scope:** Claude Code only, macOS and Linux. It pools **subscription** accounts (Pro/Max), not API keys.
 
 ```
 $ claude
-  ...you work normally...
-  ↻ tokenmaxxing: switched to work@acme.com - resuming...
-  ...same conversation, fresh quota...
+  ...you work normally; swaps are invisible (watch the statusline account flip)...
+  ⏳ tokenmaxxing: all accounts at their limit. Resuming on work@acme.com when it resets (Ctrl-C to resume now).
 ```
 
 ## Why
 
-A running `claude` re-checks the credential store between requests, so a swapped credential is adopted in-place (within ~30s on macOS, the next request on Linux). tokenmaxxing performs the swap at a committed turn boundary and **respawns** `claude --resume <id>` (the transcript is already on disk, so nothing is lost) - the respawn is what gives you a clean cutover and, when the whole pool is depleted, a countdown that auto-resumes at the soonest reset. A thin `claude` supervisor on your PATH owns that respawn; everything else about `claude` is unchanged - all flags, MCP, hooks, and skills pass through.
+A running `claude` re-checks the credential store between requests, so a swapped credential is adopted in-place (within ~30s on macOS, the next request on Linux) - a swap never restarts your session. The one case that still needs process management is a fully depleted pool: a session cannot pause itself, so a thin `claude` supervisor on your PATH stops it at a committed turn boundary (the transcript is already on disk, nothing is lost), shows a countdown, and auto-resumes `claude --resume <id>` at the soonest reset. Everything else about `claude` is unchanged - all flags, MCP, hooks, and skills pass through.
 
 ## Install
 
@@ -44,8 +43,9 @@ claude                  # use claude as always
 | `tokenmaxxing status` | accounts with 5h / weekly usage bars, active + exhausted-until-reset |
 | `tokenmaxxing status --force` | additionally ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh |
 | `tokenmaxxing watch [seconds]` | live status: re-render every N seconds (default 120, floor 30; never pings) |
+| `tokenmaxxing config` | effective config with sources; `get`/`set`/`unset` dotted keys, `tidy` prunes unknown keys |
 | `tokenmaxxing doctor` | verify the supervisor + settings entries survived |
-| `tokenmaxxing rename <sel> <label>` · `rm <sel>` | manage the pool |
+| `tokenmaxxing rename <sel> <label>` / `rm <sel>` | manage the pool |
 | `tokenmaxxing uninstall` | remove supervisor + settings entries (accounts/credentials kept) |
 
 ## How switching decides
@@ -55,7 +55,7 @@ Switching engages (configurable) once the active account's 5-hour session window
 - **Session** (5-hour) or **week (all models)** - the aggregate windows, fed free/push-based by the statusLine.
 - **Per-model weekly cap** - the most capable model (Fable) has its own tighter weekly limit that binds *before* the aggregate (per-model caps currently exist only for Sonnet and Fable, and Sonnet's is generous). tokenmaxxing reads it from `claude -p '/usage'` (free, 0 tokens, TTL-cached) whenever the active model is one of `policy.switchModels`, so a Fable session switches on the Fable cap while a Sonnet session rides the aggregate.
 
-The bars' headroom is deliberate: it's the budget to reach a clean turn boundary and respawn before the wall. The session bar sits lower (95) because a 5-hour reset is cheap to sit out; weekly quota is use-it-or-lose-it, so it drains closer to the wall (98). The greedy engagement floor sits far below both: weekly allowance is forfeited at each account's fixed reset, so once half a session window justifies the swap, quota is best burned on whichever account has the most at risk.
+The bars' headroom is deliberate: it's the budget to reach a clean turn boundary (plus up to one turn of adoption lag on macOS) before the wall. The session bar sits lower (95) because a 5-hour reset is cheap to sit out; weekly quota is use-it-or-lose-it, so it drains closer to the wall (98). The greedy engagement floor sits far below both: weekly allowance is forfeited at each account's fixed reset, so once half a session window justifies the swap, quota is best burned on whichever account has the most at risk.
 
 The **target** is chosen greedily off each account's cached windows: among usable accounts (every window under its bar, or past its reset), the one **furthest behind its own weekly pace** - highest remaining% divided by time to its weekly reset - because unused weekly allowance is forfeited at the fixed per-account reset. Cached resets are absolute UTC epochs, so a stale snapshot still resolves correctly: a weekly reset that has passed extrapolates forward in 7-day steps, and a session window past its reset counts as empty. Both `tokenmaxxing switch` and the automatic path rank the current account too and do nothing when it already wins, so they are idempotent - evaluating periodically converges on the right account.
 
@@ -120,9 +120,10 @@ Two codex-specific facts worth knowing: codex does not run hooks it has not been
 
 ## Honest limitations
 
-- **One cold turn.** The first turn after resuming on a new account re-uploads context once (prompt cache is org-scoped).
-- **Respawn hiccup.** At the swap you see `claude` restart (~1–2s); anything typed in that split second is lost.
-- **Shared blast radius.** All default-profile sessions share one live credential, so a swap moves them all together (each respawns its own session). A `flock` + re-check keeps racing hooks from burning two accounts.
+- **One cold turn.** The first turn on a new account re-uploads context once (prompt cache is org-scoped).
+- **Depleted-pause hiccup.** Plain swaps never restart the session. Only when the whole pool is at its limit does `claude` stop for the countdown; anything typed in that split second is lost.
+- **Adoption lag.** On macOS the first turn within ~30s of a swap can still meter the old account; the bars' headroom absorbs it.
+- **Shared blast radius.** All default-profile sessions share one live credential, so a swap moves them all together (each adopts in place). A `flock` + re-check keeps racing hooks from burning two accounts.
 - **Keychain ACL (macOS).** `init`/`add` touch the keychain interactively so the first `security` access isn't cold inside a headless hook.
 - **Plaintext credentials (Linux).** Claude Code itself stores Linux credentials as a 0600 plaintext file; tokenmaxxing's parked copies follow the same model.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "0.13.1",
+  "version": "0.15.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

@@ -0,0 +1,200 @@
+// `tokenmaxxing config` - inspect, edit, and housekeep config.json (user ask
+// 2026-07-16). Operates on the SPARSE file: config.json holds only overrides
+// and loadConfig merges defaults at read time, so baking defaults into the
+// file would freeze future default changes. `tidy` is the housekeeper: it
+// drops keys the schema no longer knows (e.g. the pre-0.7 flat `threshold`)
+// and normalizes switchModels casing; get/set/unset only ever report them.
+
+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 } from "../lib/state.ts";
+import { writeFileAtomic } from "../lib/atomic.ts";
+import { c } from "./render.ts";
+
+/** Hand-maintained mirror of ConfigFileSchema's dotted keys; an invariant test
+ *  (test/config.test.ts) pins the two together so a new schema field cannot
+ *  silently become invisible to get/set/tidy. */
+export const KNOWN_KEYS = [
+  "thresholds.session",
+  "thresholds.weekly",
+  "claudeBin",
+  "codexBin",
+  "policy.projectionMargin",
+  "policy.greedySessionFloor",
+  "policy.switchModels",
+  "policy.usagePollTtlMs",
+  "policy.maxWaitMs",
+] as const;
+
+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");
+}
+
+/** Dotted keys in `obj` (two levels: this config nests exactly once). */
+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 envSourceFor(key: string): string | null {
+  if (key === "claudeBin" && realClaudeBinFromEnv()) return "TOKENMAXXING_CLAUDE_BIN";
+  if (key === "codexBin" && realCodexBinFromEnv()) return "TOKENMAXXING_CODEX_BIN";
+  return null;
+}
+
+function printEffective(): number {
+  const effective = loadConfig();
+  const raw = readRawFile();
+  console.log(c.dim(`config.json: ${paths.configJson}`));
+  for (const key of KNOWN_KEYS) {
+    const env = envSourceFor(key);
+    const source = env ? c.yellow(`env ${env}`) : get(raw, key) !== undefined ? c.green("file") : c.dim("default");
+    console.log(`  ${key.padEnd(28)} ${JSON.stringify(get(effective, key))}  ${source}`);
+  }
+  const unknown = unknownFileKeys(raw);
+  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): number {
+  if (!KNOWN_KEYS.some((known) => known === key)) {
+    console.error(c.red(`unknown config key: ${key}`));
+    console.error(c.dim(`known keys: ${KNOWN_KEYS.join(", ")}`));
+    return 1;
+  }
+  console.log(JSON.stringify(get(loadConfig(), key)));
+  return 0;
+}
+
+/** JSON when it parses (numbers, booleans, arrays), else the literal string. */
+function parseValue(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function cmdSet(key: string, valueText: string): number {
+  if (!KNOWN_KEYS.some((known) => known === key)) {
+    console.error(c.red(`unknown config key: ${key}`));
+    console.error(c.dim(`known keys: ${KNOWN_KEYS.join(", ")}`));
+    return 1;
+  }
+  const raw = readRawFile();
+  const next = structuredClone(raw);
+  set(next, key, parseValue(valueText));
+  const validated = ConfigFileSchema.safeParse(next);
+  if (!validated.success) {
+    console.error(c.red(`rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`));
+    return 1;
+  }
+  writeRawFile({ raw: next });
+  // Report the FILE-level change: with an env override in place, the effective
+  // value would not move, and an unchanged-looking arrow would misrepresent
+  // the write that just happened.
+  const beforeFile = get(raw, key);
+  console.log(
+    `${key}: ${beforeFile === undefined ? "(default)" : JSON.stringify(beforeFile)} -> ${JSON.stringify(get(next, key))}`,
+  );
+  const env = envSourceFor(key);
+  if (env) console.log(c.yellow(`note: ${env} is set and overrides the file value in this environment`));
+  return 0;
+}
+
+/** Remove parents emptied by a deletion or a strip: the sparse file must not
+ *  accumulate `{}` husks. */
+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): number {
+  if (!KNOWN_KEYS.some((known) => known === key)) {
+    console.error(c.red(`unknown config key: ${key}`));
+    return 1;
+  }
+  const raw = readRawFile();
+  if (get(raw, key) === undefined) {
+    console.log(c.dim(`${key} has no file override (default already applies)`));
+    return 0;
+  }
+  const next = structuredClone(raw);
+  unset(next, key);
+  pruneEmptyParents(next);
+  writeRawFile({ raw: next });
+  console.log(`${key} unset -> ${JSON.stringify(get(loadConfig(), key))} (default)`);
+  return 0;
+}
+
+function cmdTidy(): number {
+  const raw = readRawFile();
+  const dropped = unknownFileKeys(raw);
+  // ConfigFileSchema strips unknown keys at both levels; switchModels casing
+  // normalizes to what the loader would use anyway.
+  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);
+
+  // Honest housekeeping: say exactly what changed, write only when something did.
+  if (JSON.stringify(next) === JSON.stringify(raw)) {
+    console.log(c.dim("nothing to tidy"));
+    return 0;
+  }
+  writeRawFile({ raw: next });
+  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)");
+  return 0;
+}
+
+export function cmdConfig(args: string[]): number {
+  const [sub, key, value] = args;
+  try {
+    if (sub === undefined) return printEffective();
+    if (sub === "get" && key !== undefined) return cmdGet(key);
+    if (sub === "set" && key !== undefined && value !== undefined) return cmdSet(key, value);
+    if (sub === "unset" && key !== undefined) return cmdUnset(key);
+    if (sub === "tidy") return cmdTidy();
+  } catch (e) {
+    // A corrupt config.json fails fast with a recovery step, not a stack trace.
+    console.error(c.red(`config.json is unreadable: ${e instanceof Error ? e.message : String(e)}`));
+    console.error(c.dim(`fix or delete ${paths.configJson} (defaults apply when it is absent), then re-run`));
+    return 1;
+  }
+  console.error(c.red("usage: tokenmaxxing config [get <key> | set <key> <value> | unset <key> | tidy]"));
+  return 2;
+}

package/src/entries/stophook.ts

@@ -1,8 +1,10 @@
 // Stop hook. Fires when claude finishes a turn (transcript already committed).
-// If the active account crossed the threshold, swap the credential and - when
-// running under the supervisor - drop a respawn marker keyed by this session id.
-// The supervisor watches for the marker and SIGTERMs its child at this clean
-// boundary, then relaunches `--resume`. We never kill claude ourselves.
+// A plain swap needs no respawn: the running session adopts the swapped
+// credential on its own (<=30s on macOS, next request on Linux). Only a
+// depleted-pool wait - when running under the supervisor - drops a respawn
+// marker keyed by this session id: the supervisor SIGTERMs its child at this
+// clean boundary, counts down to the reset, then relaunches `--resume`. We
+// never kill claude ourselves.
 
 import { join } from "node:path";
 import { z } from "zod";
@@ -34,10 +36,11 @@ export async function runStopHook(): Promise<number> {
     // will actually pause the session until the reset.
     const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && sessionId != null;
     const decision = await evaluateAndMaybeSwap(Date.now(), canPause);
-    // Respawn on a swap, or on a depleted-pool wait (relaunch after the reset).
     if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       log(decision.swapped ? "stop.swapped" : "stop.wait", { account: decision.account.accountUuid.slice(0, 8), waitUntil: decision.waitUntil });
-      if (process.env.TOKENMAXXING_SUPERVISED === "1" && sessionId) {
+      // Respawn only for a depleted-pool wait: pausing until the reset requires
+      // killing the child. A plain swap leaves the session running to adopt.
+      if (decision.waitUntil !== undefined && process.env.TOKENMAXXING_SUPERVISED === "1" && sessionId) {
         const marker = join(paths.respawnDir, sessionId);
         const payload = RespawnMarkerSchema.parse({ account: decision.account.label, ts: Date.now(), waitUntil: decision.waitUntil });
         writeFileAtomic(marker, JSON.stringify(payload));

package/src/entries/supervisor.ts

@@ -1,10 +1,11 @@
 // The `claude` supervisor. Invoked in place of claude (via ~/.config/tokenmaxxing/
 // bin/claude on PATH). Runs the REAL claude with inherited stdio (claude owns the
 // real terminal exactly as if run directly), pins a session id, and watches for a
-// respawn marker dropped by the Stop/SessionStart hook. When the marker appears it
-// SIGTERMs its own child at the (already-committed) turn boundary and relaunches
-// `claude --resume <id>` on the freshly-swapped account. Process/terminal manager
-// only - it never reads or proxies tokens.
+// respawn marker dropped by the Stop hook on a depleted-pool wait (plain swaps
+// adopt in place and never respawn). When the marker appears it SIGTERMs its own
+// child at the (already-committed) turn boundary, counts down to the reset, and
+// relaunches `claude --resume <id>`. Process/terminal manager only - it never
+// reads or proxies tokens.
 
 import { existsSync, mkdirSync, rmSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
@@ -213,7 +214,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
       const m = RespawnMarkerSchema.parse(await Bun.file(marker).json());
       rmSync(marker, { force: true });
       respawns++;
-      if (m.waitUntil && m.waitUntil > Date.now()) await countdownWait(m.account, m.waitUntil);
+      if (m.waitUntil > Date.now()) await countdownWait(m.account, m.waitUntil);
       else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming...\x1b[0m\n`);
       launchArgs = ["--resume", sid, ...base];
       continue;

package/src/lib/state.ts

@@ -31,8 +31,9 @@ const DEFAULT_CONFIG: Config = {
   policy: { projectionMargin: 0, greedySessionFloor: 50, switchModels: ["fable"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
 };
 
-/** On-disk shape (all optional); validated via Zod, merged over defaults. */
-const ConfigFileSchema = z
+/** On-disk shape (all optional); validated via Zod, merged over defaults.
+ *  Exported for `xx config`, which edits and housekeeps the sparse file. */
+export const ConfigFileSchema = z
   .object({
     thresholds: z.object({ session: z.number(), weekly: z.number() }).partial(),
     claudeBin: z.string(),

package/src/lib/types.ts

@@ -141,12 +141,13 @@ export const ConfigSchema = z.object({
 });
 export type Config = z.infer<typeof ConfigSchema>;
 
-/** The hook -> supervisor respawn marker at respawn/<session-id>. */
+/** The hook -> supervisor respawn marker at respawn/<session-id>. Written only
+ *  for a depleted-pool wait (plain swaps adopt in place, no respawn). */
 export const RespawnMarkerSchema = z.object({
   account: z.string(),
   ts: z.number(),
-  /** when set, the supervisor waits until this epoch ms before relaunching. */
-  waitUntil: z.number().optional(),
+  /** the supervisor waits until this epoch ms before relaunching. */
+  waitUntil: z.number(),
 });
 export type RespawnMarker = z.infer<typeof RespawnMarkerSchema>;
 

package/src/main.ts

@@ -23,6 +23,7 @@ import { cmdRm } from "./cli/rm.ts";
 import { cmdRename } from "./cli/rename.ts";
 import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
+import { cmdConfig } from "./cli/config.ts";
 import { uninstallSupervisor } from "./lib/install.ts";
 import { c } from "./cli/render.ts";
 
@@ -41,6 +42,7 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing status")}     accounts with 5h / weekly / per-model usage bars
   ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
+  ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} <sel> <label>
   ${c.cyan("tokenmaxxing rm")} <sel>
@@ -75,6 +77,7 @@ async function main(): Promise<number> {
     case "--force": return cmdStatus(true); // bare `xx --force` → status --force
     case "switch": return args[1] === "--codex" ? cmdCodexSwitch(args[2]) : cmdSwitch(args[1]);
     case "check": return cmdCheck();
+    case "config": return cmdConfig(args.slice(1));
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
     case "ls": return cmdLs();