tokenmaxxing 1.8.0 → 1.9.1

package/DESIGN.md

@@ -37,7 +37,7 @@ It is a process manager only - spawn with inherited stdio plus saved `stty -g` t
   - `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.
 
-- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check` every 180s: hooks alone miss long agentic turns, so the timer is the backstop that keeps switching engaged mid-turn.
+- A periodic check job (`com.tokenmaxxing.check` launchd agent on macOS, `tokenmaxxing-check.timer` systemd user timer on Linux) running `tokenmaxxing check --if-due` every 60s, self-paced up to 300s from the live account's headroom: hooks alone miss long agentic turns, so the timer is the backstop that keeps switching engaged mid-turn.
 
 The switching path runs no long-lived daemon. The statusline pushes usage. Hooks and the supervisor react. The periodic check job above is the only recurring process. The `claude` binary and `~/.claude` layout are untouched.
 
@@ -111,9 +111,7 @@ The decision engages at `five_hour >= 50%` (policy.greedySessionFloor): from the
 
 **Shipped since (0.13.0):** Codex as a second pool, parallel state (`codex-accounts.json`, `codex-creds/`, own flock), same pace-pressure policy. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (harvest-by-true-owner, persist every rotation), and codex's new Stop-hook system drives the auto-swap through a codex supervisor shim that respawns `codex resume <session-id>` (hooks must be trusted once via `/hooks`). Sibling sessions left on ANY non-live account are reconciled cross-session (owner decisions 2026-07-20; a non-live session cannot refresh cross-account and would wedge at token expiry, healthy or not): the deciding actor drops a reconcile marker addressed to the sibling's supervisor, and the sibling's own Stop hook promotes it into a respawn onto the live account at its next turn boundary - the only safe respawn point - while a blocked live seat never receives a signal.
 
-**Shipped since (relay companion):** `tokenmaxxing relay` hosts durable tmux workers for cheap host subagents. Claude `--permission-mode` vocabulary (default `auto`), Codex sandbox mapping, per-session flock + registry under `relay/`, additive turn-done markers (never `respawn/`), and `permission-needed` stdout pings decided by main. Host finish hooks still run on every return including pings. Skill + agents live under `agent-plugin/` (`relay-session`, `tokenmaxxing-claude`, `tokenmaxxing-codex`). Docs: `docs/content/docs/commands.mdx`, `state-directory.mdx`, `agent-plugin.mdx`.
-
-**Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap; Slack serve as the relay bus; soft concurrency caps; Cloud Agents without local tmux.
+**Non-goals:** an API/MITM proxy; reimplementing OAuth beyond the single refresh-grant call in the swap; Slack as a message bus; soft concurrency caps.
 
 ---
 

package/README.md

@@ -50,7 +50,7 @@ programs.tokenmaxxing.package = inputs.tokenmaxxing.packages.${pkgs.system}.defa
 # then: tokenmaxxing init
 ```
 
-`init` imports the account you're already on, installs the `claude` supervisor + four `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a SessionStart hook), and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
+`init` imports the account you're already on, installs the `claude` supervisor + five `settings.json` entries (the tokenmaxxing statusLine, a subagentStatusLine, a Stop hook, a StopFailure hook, a SessionStart hook), and adds the supervisor's bin dir to PATH in your shell rc (idempotent; it must sit ahead of the real `claude` to intercept it). Restart your shell, then add more accounts and go:
 
 ```sh
 tokenmaxxing add        # logs one in, in isolation, and pools it

package/agent-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "tokenmaxxing",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "description": "Pool Claude Code and Codex logins, switch on pace pressure, and expose safe ops tools to agent clients.",
   "author": {
     "name": "anaclumos",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.8.0",
+  "version": "1.9.1",
   "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/add.ts

@@ -1,7 +1,3 @@
-// `tokenmaxxing add` - register an ADDITIONAL account. Drives one isolated
-// login (see onboard.ts), then pools whatever account it landed on. Your
-// primary login is never touched.
-
 import { withLock } from "../lib/lock.ts";
 import { loadAccounts, saveAccounts } from "../lib/state.ts";
 import { credItemFor, paths } from "../lib/paths.ts";
@@ -22,11 +18,8 @@ export async function cmdAdd(): Promise<number> {
   const uuid = oauthAccount.accountUuid;
   const keychainItem = credItemFor(uuid);
 
-  // under the flock: a concurrent swap both harvests into parked items and
-  // writes the index, so the backup write and the index upsert must land in
-  // one critical section.
   const { account, poolSize } = await withLock(paths.lockFile, async () => {
-    await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw)); // park a small backup
+    await writeItem(parkedTarget(keychainItem), claudeAiOauthOnly(blobRaw));
     const idx = loadAccounts();
     const existing = idx.accounts.find((a) => a.accountUuid === uuid);
     const fresh: Account = {

package/src/cli/auth.ts

@@ -1,11 +1,3 @@
-// `tokenmaxxing auth` - reauthenticate a pooled account in place. The dead
-// refresh token cannot heal itself (a needs-reauth account can never win a
-// swap), so this drives one isolated login per target and REQUIRES the login
-// to land on the target account: the harvested identity must match, otherwise
-// nothing changes. Bare `auth` lists the pool (emails shown) and asks which;
-// `auth <sel>` targets one account, stating the email to sign in with;
-// `auth --all` walks every needs-reauth account one by one.
-
 import { partition } from "es-toolkit";
 import { z } from "zod";
 import { withLock } from "../lib/lock.ts";
@@ -20,18 +12,13 @@ import type { Account, AccountsIndex } from "../lib/types.ts";
 const AUTH_USAGE = "usage: tokenmaxxing auth [<email|label|id> | --all]";
 
 const AuthPlanSchema = z.discriminatedUnion("kind", [
-  /** malformed argv: print AUTH_USAGE, exit 2. */
   z.object({ kind: z.literal("usage") }),
-  /** unresolvable state (empty pool, unknown selector): exit 1. */
   z.object({ kind: z.literal("error"), message: z.string() }),
-  /** bare `auth`: ask interactively. */
   z.object({ kind: z.literal("pick") }),
   z.object({ kind: z.literal("targets"), uuids: z.array(z.string()) }),
 ]);
 export type AuthPlan = z.infer<typeof AuthPlanSchema>;
 
-/** Resolve argv into a reauth plan (pure - unit-tested). Argv shape is
- *  validated before any pool state is consulted. */
 export function planAuth(input: { accounts: Account[]; argv: string[] }): AuthPlan {
   const all = input.argv.includes("--all");
   const rest = input.argv.filter((a) => a !== "--all");
@@ -50,7 +37,6 @@ export function planAuth(input: { accounts: Account[]; argv: string[] }): AuthPl
   return { kind: "pick" };
 }
 
-/** Needs-reauth accounts first (they are why the user is here), pool order within. */
 export function pickerOrder(accounts: Account[]): Account[] {
   const [flagged, healthy] = partition(accounts, (a) => a.needsReauth === true);
   return [...flagged, ...healthy];
@@ -100,16 +86,7 @@ async function reauthOne(target: Account): Promise<boolean> {
     return false;
   }
 
-  // under the flock: a concurrent swap both harvests into parked items and
-  // writes the index, so the credential write and the needsReauth clear must
-  // land in one critical section (else a swap-away harvest of the live blob
-  // could overwrite this fresh backup right before it is marked healthy).
   const isActive = await withLock(paths.lockFile, async () => {
-    // The account must still be pooled BEFORE anything is written: the
-    // interactive login can sit open for minutes, and a concurrent `xx rm`
-    // completing in that window used to get its parked item recreated as an
-    // orphan no pool entry tracks - plus a false "reauthed" success
-    // (closing-review catch).
     const idx = loadAccounts();
     const account = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
     if (!account) {

package/src/cli/check.ts

@@ -1,30 +1,36 @@
-// `tokenmaxxing check` - one auto-switch evaluation, the same decision the
-// Stop/SessionStart hooks make (flocked, idempotent). Installed as a periodic
-// launchd/systemd job so a limit crossed mid-turn, or with no session running,
-// still switches within minutes; the hooks only ever see turn boundaries.
-// Running claude sessions adopt the swapped credential in place (<=30s).
-
-import { evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { CHECK_DELAY_FLOOR_MS, checkDelayMs, evaluateAndMaybeSwap } from "../lib/decide.ts";
+import { readOAuthAccount } from "../lib/claudejson.ts";
 import { log } from "../lib/log.ts";
+import { loadConfig, loadNextCheckDueAt, saveNextCheckDueAt } from "../lib/state.ts";
 import { c, fmtReset } from "./render.ts";
 
-export async function cmdCheck(): Promise<number> {
+const TICK_SLACK_MS = CHECK_DELAY_FLOOR_MS / 2;
+
+export async function cmdCheck(args: string[] = []): Promise<number> {
+  const now = Date.now();
+  const dueAt = args.includes("--if-due") ? loadNextCheckDueAt(now) : null;
+  if (dueAt != null && now + TICK_SLACK_MS < dueAt) {
+    console.log(c.dim(`not due (${Math.ceil((dueAt - now) / 1000)}s)`));
+    return 0;
+  }
   let d;
   try {
-    d = await evaluateAndMaybeSwap();
+    d = await evaluateAndMaybeSwap(now);
   } catch (e) {
-    // unattended under the timer: the log is the only place anyone will look.
     const detail = e instanceof Error ? e.message : String(e);
     log("check.error", { err: detail });
     console.error(c.red(`check failed: ${detail}`));
     return 1;
   }
+  const delayMs = checkDelayMs({ cfg: loadConfig(), org: readOAuthAccount()?.organizationUuid ?? null, now, decision: d });
+  saveNextCheckDueAt({ dueAt: now + delayMs, ts: now });
+  const next = c.dim(`next in ${Math.round(delayMs / 1000)}s`);
   if (d.swapped && d.account) {
-    console.log(`${c.green("↻")} switched to ${c.bold(d.account.label)}`);
+    console.log(`${c.green("↻")} switched to ${c.bold(d.account.label)} ${next}`);
   } else if (d.waitUntil !== undefined && d.account) {
-    console.log(c.yellow(`all accounts at limit - staying on ${c.bold(d.account.label)} (${fmtReset(d.waitUntil)})`));
+    console.log(c.yellow(`all accounts at limit - staying on ${c.bold(d.account.label)} (${fmtReset(d.waitUntil)})`) + ` ${next}`);
   } else {
-    console.log(c.dim(`no switch (${d.reason})`));
+    console.log(c.dim(`no switch (${d.reason}) `) + next);
   }
   return 0;
 }

package/src/cli/codexadd.ts

@@ -1,12 +1,3 @@
-// `tokenmaxxing add --codex` - register an ADDITIONAL codex account. Runs
-// `codex login --device-auth` inside a throwaway CODEX_HOME pinned to
-// file-mode credential storage (auto mode would keyring-namespace the login on
-// macOS and leave nothing harvestable), then parks the resulting auth.json
-// under the token's OWN identity and indexes it. The primary login is never
-// touched. Device auth is the default (user decision 2026-07-20): the browser
-// flow binds localhost on the machine running the command, so it dead-ends
-// over ssh; the device code works from any browser.
-
 import { mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV } from "../lib/claudebin.ts";
@@ -24,11 +15,6 @@ import { c, count } from "./render.ts";
 export async function cmdCodexAdd(): Promise<number> {
   const real = resolveRealCodex();
   const onboardDir = codexPaths.onboardDir;
-  // Deliberate hard delete (not trash; user decision 2026-07-16): the onboard
-  // dir holds a plaintext live credential after login, and a trashed copy
-  // would keep that token readable. The dir is tokenmaxxing's own transient
-  // artifact; its one durable output is parked separately before cleanup.
-  // Same rationale at the end-of-run cleanup below.
   rmSync(onboardDir, { recursive: true, force: true });
   mkdirSync(onboardDir, { recursive: true });
   writeFileAtomic(join(onboardDir, "config.toml"), 'cli_auth_credentials_store = "file"\n');
@@ -52,9 +38,6 @@ export async function cmdCodexAdd(): Promise<number> {
   await p.exited;
   restoreTermios(savedTermios);
 
-  // The finally guarantees the plaintext onboard home is destroyed on every
-  // non-signal exit; an exception mid-registration must not strand it. (An
-  // interactive Ctrl-C is reaped by the next run's rmSync-first.)
   let account: CodexAccount;
   let poolSize: number;
   try {

package/src/cli/codexinit.ts

@@ -1,10 +1,3 @@
-// `tokenmaxxing init --codex` - bring the codex side up: verify + pin the real
-// codex binary, import the existing live login as codex account #1, install
-// the on-PATH codex supervisor shim and the Stop hook declaration, and tell
-// the user about the one step tokenmaxxing cannot do for them: codex skips
-// hooks it has not been TRUSTED to run (trust is recorded against the hook's
-// hash via /hooks in the codex TUI), so auto-switching stays inert until then.
-
 import { existsSync, readFileSync } from "node:fs";
 import { resolveRealCodex, verifyRealCodex } from "../lib/codexbin.ts";
 import { codexIdentityOf, readLiveCodexAuth, writeParkedCodexAuth } from "../lib/codexauth.ts";
@@ -18,16 +11,6 @@ import { codexCredItemFor, codexPaths } from "../lib/paths.ts";
 import type { CodexAccount, CodexUsage } from "../lib/types.ts";
 import { c } from "./render.ts";
 
-/** Fail fast when config.toml pins the credential store away from the plain
- *  file tokenmaxxing swaps (structural line scan: the repo ships no TOML
- *  parser, and this single key is the only one we ever inspect). The real key
- *  is `cli_auth_credentials_store` (binary-verified 0.144.5; an earlier
- *  verification misread the enum TYPE name as a `_mode` key). An ABSENT key is
- *  allowed: the DEFAULT at 0.144.5 is `file` itself (source-verified:
- *  AuthCredentialsStoreMode derives Default on the File variant), and init
- *  separately verifies a harvestable auth.json.
- *  Any EXPLICIT non-file pin (keyring, auto, ephemeral) is a deliberate store
- *  choice tokenmaxxing cannot honor. */
 function storePinnedAwayFromFile(): boolean {
   const configToml = `${codexPaths.home}/config.toml`;
   if (!existsSync(configToml)) return false;
@@ -36,8 +19,6 @@ function storePinnedAwayFromFile(): boolean {
     if (!line.startsWith("cli_auth_credentials_store")) continue;
     const rest = line.slice("cli_auth_credentials_store".length).trimStart();
     if (!rest.startsWith("=")) continue;
-    // Value only: strip an inline TOML comment and the quotes structurally so
-    // a comment mentioning "keyring" never false-positives the fail-fast.
     const beforeComment = rest.slice(1).split("#", 1)[0]!;
     const value = beforeComment.replaceAll('"', "").replaceAll("'", "").trim();
     return value !== "file";
@@ -46,7 +27,6 @@ function storePinnedAwayFromFile(): boolean {
 }
 
 export async function cmdCodexInit(): Promise<number> {
-  // Fail fast on a broken merged config before installing (see cmdInit).
   loadConfig();
   const real = resolveRealCodex();
   const fail = verifyRealCodex({ bin: real });
@@ -54,7 +34,6 @@ export async function cmdCodexInit(): Promise<number> {
     console.error(c.red(`codex binary failed verification: ${real}: ${fail}`));
     return 1;
   }
-  // Sparse write: only the pin lands in the file, never the merged config.
   pinBinOverride({ key: "codexBin", bin: real });
 
   if (storePinnedAwayFromFile()) {
@@ -81,13 +60,6 @@ export async function cmdCodexInit(): Promise<number> {
 
   const credFile = codexCredItemFor(identity.accountId);
 
-  // A RUNNING supervised session on this account can rotate auth.json at any
-  // moment (codex persists rotations instantly, and the flock serializes only
-  // tokenmaxxing actors) - a snapshot parked now could hold an already-
-  // superseded refresh token whose next refresh is reuse-punished (cubic
-  // review catch, PR #35). Refuse loudly, like the sampler's present-account
-  // rule; sessions launched around the shim are the same accepted gap as
-  // everywhere presence is the signal.
   if (presentCodexAccountIds().has(identity.accountId)) {
     console.error(c.red("a live supervised codex session is running this account - its token rotates under us, so parking a snapshot now could poison the backup."));
     console.error(c.dim("close that codex session (or let it exit) and re-run `tokenmaxxing init --codex`."));
@@ -95,21 +67,9 @@ export async function cmdCodexInit(): Promise<number> {
   }
 
   const account = await withLock(codexPaths.lockFile, () => {
-    // Re-check presence INSIDE the critical section (pullfrog review catch,
-    // PR #35): supervisor spawns are flock-serialized too, so one can start -
-    // check passed, presence written, session live - entirely between the
-    // friendly pre-lock check above and this lock acquisition. The throw
-    // routes through the CLI error boundary as a clean failure.
     if (presentCodexAccountIds().has(identity.accountId)) {
       throw new Error("a live supervised codex session started running this account mid-init - close it and re-run `tokenmaxxing init --codex`");
     }
-    // Park INSIDE the flock, from a blob RE-READ inside it (closing-review
-    // catch): the pre-lock snapshot is seconds stale (a network usage GET sits
-    // in between), and parking it unlocked could clobber a concurrent swap's
-    // just-harvested newest rotation with a superseded refresh token - whose
-    // next refresh is reuse-punished into a dead grant family. An identity
-    // that changed since the pre-lock read means a swap landed mid-init:
-    // abort rather than file the wrong account.
     const fresh2 = readLiveCodexAuth();
     if (!fresh2 || codexIdentityOf({ auth: fresh2 }).accountId !== identity.accountId) {
       throw new Error("the live codex login changed while init was running (a concurrent swap?) - re-run `tokenmaxxing init --codex`");

package/src/cli/codexrm.ts

@@ -1,8 +1,3 @@
-// `tokenmaxxing rm --codex <selector>` - remove a pooled codex account (not
-// the live one). Until this existed the uninstall message pointed users at
-// `xx rm` for every parked credential while codex blobs were unremovable
-// (adversarial-review catch).
-
 import { withLock } from "../lib/lock.ts";
 import { codexPaths } from "../lib/paths.ts";
 import { loadCodexAccounts, saveCodexAccounts } from "../lib/codexstate.ts";
@@ -17,7 +12,6 @@ export async function cmdCodexRm(selector?: string): Promise<number> {
     console.error("usage: tokenmaxxing rm --codex <email|label|id>");
     return 2;
   }
-  // under the codex flock: a concurrent swap's index write must not be clobbered.
   return withLock(codexPaths.lockFile, async () => {
     const index = loadCodexAccounts();
     const account = findCodexAccount(index.accounts, selector);
@@ -25,10 +19,6 @@ export async function cmdCodexRm(selector?: string): Promise<number> {
       console.error(c.red(`no codex account matches "${selector}"`));
       return 1;
     }
-    // The live identity is decoded from auth.json itself (id_token claims),
-    // offline ground truth - labels drift, the blob cannot lie. An unreadable
-    // live blob THROWS out of liveCodexAccountId (the codex loaders' contract),
-    // which fails this destructive command loudly rather than trusting a label.
     if (liveCodexAccountId() === account.accountId) {
       console.error(c.red(`${account.label} is the LIVE codex account - run \`tokenmaxxing switch --codex\` to move off it first.`));
       return 1;
@@ -37,9 +27,6 @@ export async function cmdCodexRm(selector?: string): Promise<number> {
       console.error(c.red(`${account.label} is running in a live codex session - close that session before removing it.`));
       return 1;
     }
-    // Parked codex blobs are plain 0600 files; hard delete on purpose (the
-    // credential-dir cleanup exception - trashing would move a credential
-    // into the Trash folder).
     deleteParkedCodexAuth({ credFile: account.credFile });
     index.accounts = index.accounts.filter((x) => x.accountId !== account.accountId);
     saveCodexAccounts({ index });

package/src/cli/codexswitch.ts

@@ -1,12 +1,3 @@
-// `tokenmaxxing switch --codex [sel]`. Bare form is GREEDY and IDEMPOTENT off
-// cached windows, exactly like the claude switch: rank every codex account
-// (current included) by pace pressure among those under their screening bars;
-// when the current account already wins, do nothing. The current account is
-// the LIVE auth.json's own identity, never the stored label. The swap takes
-// effect for the NEXT codex start: a running codex refuses a different
-// account's credential (restart is the switch; the Stop hook + supervisor
-// automate that for supervised sessions).
-
 import { withLock } from "../lib/lock.ts";
 import { codexPaths } from "../lib/paths.ts";
 import { loadConfig } from "../lib/state.ts";
@@ -32,10 +23,6 @@ export async function cmdCodexSwitch(sel?: string): Promise<number> {
     }
     const currentId = liveCodexAccountId();
 
-    // truthiness on purpose, mirroring the claude switch: an EMPTY selector
-    // must mean "no selector" - `startsWith("")` matches every account, so
-    // `sel !== undefined` let `xx switch --codex ""` swap onto the first
-    // account (adversarial-review catch)
     if (sel) {
       const target = index.accounts.find(
         (account) => account.label === sel || account.email === sel || account.accountId.startsWith(sel),
@@ -60,8 +47,6 @@ export async function cmdCodexSwitch(sel?: string): Promise<number> {
       try {
         await performCodexSwap({ target });
       } catch (e) {
-        // a dead grant is an expected operational state, not a stack trace
-        // (closing-review catch; mirrors the claude selector path).
         if (e instanceof CodexInvalidGrantError) {
           console.error(c.red(`${target.label}'s refresh token is dead - re-add it with \`tokenmaxxing add --codex\``));
           return 1;

package/src/cli/config.ts

@@ -1,10 +1,3 @@
-// `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";
@@ -14,9 +7,6 @@ import { ConfigFileSchema, loadConfig, mergeConfigFile } 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",
@@ -42,7 +32,6 @@ 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)) {
@@ -94,7 +83,6 @@ function cmdGet(key: string): number {
   return 0;
 }
 
-/** JSON when it parses (numbers, booleans, arrays), else the literal string. */
 function parseValue(text: string): unknown {
   try {
     return JSON.parse(text);
@@ -117,19 +105,12 @@ function cmdSet(key: string, valueText: string): number {
     console.error(c.red(`rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`));
     return 1;
   }
-  // The per-field gate passed; the MERGED whole must too, or this write makes
-  // every later loadConfig throw (the projectionMargin-vs-thresholds refine),
-  // silently disabling status/switch/hooks/statusline until the file is
-  // hand-repaired (closing-review catch).
   const mergedCheck = mergeConfigFile(validated.data);
   if (!mergedCheck.ok) {
     console.error(c.red(`rejected: ${mergedCheck.detail}`));
     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))}`,
@@ -139,8 +120,6 @@ function cmdSet(key: string, valueText: string): number {
   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) {
@@ -162,11 +141,6 @@ function cmdUnset(key: string): number {
   const next = structuredClone(raw);
   unset(next, key);
   pruneEmptyParents(next);
-  // Same merged-whole gate as `set` (adversarial-review catch): removing one
-  // override shifts the merged value back to its default, and the
-  // projectionMargin-vs-thresholds refine can fail on the RESULT even though
-  // every remaining field is individually valid - writing that file would make
-  // every later loadConfig throw, bricking status/switch/hooks/statusline.
   const validated = ConfigFileSchema.safeParse(next);
   if (!validated.success) {
     console.error(c.red(`rejected: ${validated.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ")}`));
@@ -185,8 +159,6 @@ function cmdUnset(key: string): number {
 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");
@@ -195,7 +167,6 @@ function cmdTidy(): number {
   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;
@@ -216,7 +187,6 @@ export function cmdConfig(args: string[]): number {
     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;

package/src/cli/doctor.ts

@@ -1,6 +1,3 @@
-// `tokenmaxxing doctor` - verify the supervisor + four settings entries survived
-// and the pool is healthy.
-
 import { existsSync, readFileSync } from "node:fs";
 import { verifyRealClaude } from "../lib/claudebin.ts";
 import { checkSettings, installedBin } from "../lib/settings.ts";
@@ -12,8 +9,6 @@ import { isAccessTokenExpiring, fetchTokenOrg } from "../lib/oauth.ts";
 import { CredentialBlobSchema, type RolesResponse } from "../lib/types.ts";
 import { c } from "./render.ts";
 
-/** The org a stored blob's token truly belongs to; null = expired (unverifiable
- *  read-only - doctor never refreshes). Throws on unreadable blob / API failure. */
 async function blobOrg(raw: string): Promise<RolesResponse | null> {
   const creds = CredentialBlobSchema.parse(JSON.parse(raw)).claudeAiOauth;
   if (isAccessTokenExpiring(creds)) return null;
@@ -35,6 +30,7 @@ export async function cmdDoctor(): Promise<number> {
   check(s.statusLineOk, "statusLine shim installed in settings.json", "run `tokenmaxxing init`");
   check(s.subagentStatusLineOk, "subagentStatusLine shim installed in settings.json", "run `tokenmaxxing init`");
   check(s.stopOk, "Stop hook installed in settings.json", "run `tokenmaxxing init`");
+  check(s.stopFailureOk, "StopFailure hook installed in settings.json", "run `tokenmaxxing init`");
   check(s.sessionStartOk, "SessionStart hook installed in settings.json", "run `tokenmaxxing init`");
   check(checkTimerHealthy(), "periodic check timer active", timerActivationHint());
 
@@ -45,9 +41,6 @@ export async function cmdDoctor(): Promise<number> {
   const live = await readItem(liveTarget());
   check(!!live, "live credential readable");
 
-  // Identity agreement: a stored credential must belong to the account it is
-  // filed under - a mislabeled blob once made every consumer of a backup
-  // (sampling, swap) silently act on another account.
   const active = idx.accounts.find((a) => a.accountUuid === idx.activeAccountUuid);
   if (live && active) {
     try {
@@ -77,16 +70,10 @@ export async function cmdDoctor(): Promise<number> {
   const cfg = loadConfig();
   check(!!cfg.claudeBin && existsSync(cfg.claudeBin), "real claude binary resolved", "set claudeBin in config.json");
   if (cfg.claudeBin && existsSync(cfg.claudeBin)) {
-    // Behavioral: the pin must answer --version without re-entering the wrapper.
-    // Catches a poisoned pin (a shim that resolves `claude` back to us) that
-    // existence checks cannot - the 2026-07-12 recursive-spawn incident.
     const fail = verifyRealClaude(cfg.claudeBin);
     check(fail === null, "claudeBin launches the real claude", fail ?? undefined);
   }
 
-  // Warnings only: an interactive alias/function can shadow or bypass the
-  // wrapper in ways PATH checks cannot see (`alias claude=...`, or a `cc`-style
-  // alias hardcoding an absolute path to the real binary).
   const rc = shellRcPath();
   if (rc && existsSync(rc)) {
     for (const s of findClaudeShadowers(readFileSync(rc, "utf8"))) {

package/src/cli/init.ts

@@ -1,6 +1,3 @@
-// `tokenmaxxing init` - import the account you're already on (no prompts), then
-// install the supervisor + the four settings entries.
-
 import { mkdirSync } from "node:fs";
 import { isApiKeyMode, readOAuthAccount } from "../lib/claudejson.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, mergeIntoLive } from "../lib/credstore.ts";
@@ -14,9 +11,6 @@ import { credItemFor, paths } from "../lib/paths.ts";
 import { CredentialBlobSchema, type Account } from "../lib/types.ts";
 import { c, claudeTierLabel } from "./render.ts";
 
-/** Put the supervisor bin dir on PATH via the user's shell rc (idempotent).
- *  Falls back to the manual instruction when the shell is unknown or the rc
- *  target is immutable (Home Manager / nix-store). */
 function ensurePathAhead(): void {
   const rc = shellRcPath();
   if (!rc) {
@@ -38,9 +32,6 @@ function reportTimer(out: InstallOutcome): void {
   else console.log(c.yellow(`⚠ check timer written but not activated - run: ${timerActivationHint()}`));
 }
 
-/** The how-to-use epilogue both init paths end on: the whole point of the tool
- *  is that after init you just run `claude`, so say exactly that, and teach the
- *  `xx` shorthand every other command hangs off. Exported for the render test. */
 export function printUsage(): void {
   console.log();
   console.log(`  ${c.bold("how to use")} - ${c.cyan("xx")} is shorthand for ${c.cyan("tokenmaxxing")}:`);
@@ -54,25 +45,11 @@ export function printUsage(): void {
 
 export async function cmdInit(): Promise<number> {
   mkdirSync(paths.home, { recursive: true });
-  // Fail fast on a broken merged config BEFORE installing or claiming a
-  // successful repair: pinBinOverride writes sparsely without validating, so
-  // without this gate a re-init printed success while hooks, switching, and
-  // the statusline kept throwing on every loadConfig until the file was
-  // hand-repaired (bugbot review catch, PR #33). The throw carries the
-  // fix-or-remove recovery message.
   loadConfig();
 
-  // Already initialized → repair install ONLY. Never re-import: ~/.claude.json's
-  // oauthAccount can drift from the live keychain cred (after swaps / concurrent
-  // sessions), and re-importing would park the wrong cred + mislabel active.
   const existingIdx = loadAccounts();
   if (existingIdx.accounts.length > 0) {
     const out = installSupervisor();
-    // repair the claudeBin pin too - hooks run with claude's PATH and must
-    // never have to guess which binary is the real claude. Verified pinning:
-    // a pin that fails --version (or loops back into the wrapper) is replaced
-    // by a fresh PATH scan instead of being re-saved. Sparse write: only the
-    // pin lands in the file, never the merged config.
     pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() });
     const active = existingIdx.accounts.find((a) => a.accountUuid === existingIdx.activeAccountUuid);
     console.log(`${c.green("✓")} re-installed supervisor + hooks (pool already has ${existingIdx.accounts.length} account${existingIdx.accounts.length === 1 ? "" : "s"} - not re-importing)`);
@@ -105,13 +82,9 @@ export async function cmdInit(): Promise<number> {
     return 1;
   }
 
-  // Verify the live credential actually belongs to the identity we're about to
-  // file it under - ~/.claude.json's oauthAccount can drift from the live
-  // keychain credential, and importing on drifted state parks a mislabeled blob.
   let creds = blob.claudeAiOauth;
   if (isAccessTokenExpiring(creds)) {
     await withClaudeRefreshLock(async (lock) => {
-      // re-read inside the lock: a running claude may have rotated it already.
       const raw2 = await readItem(liveTarget());
       if (raw2 == null) throw new Error("live credential vanished while waiting for the refresh lock");
       const current = CredentialBlobSchema.parse(JSON.parse(raw2)).claudeAiOauth;
@@ -130,12 +103,8 @@ export async function cmdInit(): Promise<number> {
 
   const uuid = oauthAccount.accountUuid;
   const keychainItem = credItemFor(uuid);
-  // Park + index update under the tokenmaxxing flock, like every sibling
-  // index writer (add/auth/rm/status/rename): unlocked, a concurrent `xx add`
-  // completing between this path's load and save had its just-registered
-  // account silently clobbered out of the index (closing-review catch).
   const account = await withLock(paths.lockFile, async () => {
-    await writeItem(parkedTarget(keychainItem), JSON.stringify({ claudeAiOauth: creds })); // park a small backup
+    await writeItem(parkedTarget(keychainItem), JSON.stringify({ claudeAiOauth: creds }));
     const idx = loadAccounts();
     const existing = idx.accounts.find((a) => a.accountUuid === uuid);
     const imported: Account = {
@@ -157,7 +126,6 @@ export async function cmdInit(): Promise<number> {
     return imported;
   });
 
-  // Sparse write: only the pin lands in the file, never the merged config.
   pinBinOverride({ key: "claudeBin", bin: resolveVerifiedClaude() });
 
   const out = installSupervisor();

package/src/cli/ls.ts

@@ -1,5 +1,3 @@
-// `tokenmaxxing ls` - compact list of pooled accounts, claude then codex.
-
 import { loadAccounts } from "../lib/state.ts";
 import { loadCodexAccounts } from "../lib/codexstate.ts";
 import { liveCodexAccountId } from "../lib/codexsample.ts";