tokenmaxxing 1.7.0 → 1.9.0

package/src/lib/settings.ts

@@ -1,16 +1,9 @@
-// Idempotent merge of tokenmaxxing's entries into the user-owned
-// ~/.claude/settings.json: our statusLine + subagentStatusLine, a Stop hook,
-// a SessionStart hook. Hooks APPEND to existing arrays; the statusLine slots
-// are ours outright - tokenmaxxing renders them natively, so any other
-// statusLine command is replaced.
-
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
 
-/** Absolute path to the installed tokenmaxxing binary the settings entries call. */
 export function installedBin(): string {
   return join(paths.binDir, "tokenmaxxing");
 }
@@ -30,62 +23,50 @@ const SUBCMD = {
   statusline: "__statusline",
   subagentStatusline: "__subagent-statusline",
   stop: "__stop-hook",
+  stopFailure: "__stop-failure-hook",
   sessionStart: "__session-start",
 } as const;
 
+const STOP_FAILURE_MATCHER = "rate_limit";
+
 function readSettings(): Settings {
   if (!existsSync(paths.claudeSettings)) return {};
   return SettingsSchema.parse(JSON.parse(readFileSync(paths.claudeSettings, "utf8")));
 }
 
 function writeSettings(s: Settings): void {
-  // Preserve the user's mode: settings.json can carry an env block with
-  // credentials, and the atomic rename would otherwise widen a 0600 file to
-  // world-readable. A brand-new file starts at the conservative 0600.
   const mode = existsSync(paths.claudeSettings) ? statSync(paths.claudeSettings).mode & 0o777 : 0o600;
   writeFileAtomic(paths.claudeSettings, JSON.stringify(s, null, 2) + "\n", mode);
 }
 
-/** True if a hook/statusline command string is one tokenmaxxing installed. */
 function isOurCommand(cmd: string | undefined): boolean {
   if (!cmd) return false;
   return (
     cmd.includes(SUBCMD.statusline) ||
     cmd.includes(SUBCMD.subagentStatusline) ||
     cmd.includes(SUBCMD.stop) ||
+    cmd.includes(SUBCMD.stopFailure) ||
     cmd.includes(SUBCMD.sessionStart) ||
-    // also match the installed bin path even if the subcommand text changes
     cmd.includes(installedBin())
   );
 }
 
-/** The exact command string installSettings writes for a subcommand; doctor
- *  compares against it verbatim, so a green check proves the canonical entry. */
 function ourCommand(sub: string): string {
   return `${JSON.stringify(installedBin())} ${sub}`;
 }
 
-function ourHookGroup(sub: string): HookGroup {
-  return { hooks: [{ type: "command", command: ourCommand(sub) }] };
+function ourHookGroup(sub: string, matcher?: string): HookGroup {
+  return { ...(matcher ? { matcher } : {}), hooks: [{ type: "command", command: ourCommand(sub) }] };
 }
 
-function appendHook(s: Settings, event: string, sub: string): void {
+function appendHook(s: Settings, event: string, sub: string, matcher?: string): void {
   s.hooks ??= {};
   s.hooks[event] ??= [];
   const arr = s.hooks[event]!;
   const present = arr.some((g) => g.hooks.some((h) => h.command === ourCommand(sub)));
-  if (!present) arr.push(ourHookGroup(sub));
+  if (!present) arr.push(ourHookGroup(sub, matcher));
 }
 
-/** True only for a command tokenmaxxing itself wrote - the exact historical
- *  shape `"<...>/tokenmaxxing" <sub>` at ANY install path (so stale
- *  pre-relocation entries match too). A foreign command that merely mentions
- *  the subcommand or the path as text is NOT ours and must survive removal. */
-/** Structural ownership: exactly `"<path>/tokenmaxxing" <sub>`. Exported for
- *  the codex hooks.json installer, whose old includes()-based match deleted
- *  foreign hooks sharing a group and misclassified commands merely mentioning
- *  the subcommand (closing-review catch; the same class settings.ts's own
- *  removeHook was fixed for in PR #31). */
 export function isOurHookCommand(cmd: string, sub: string): boolean {
   if (!cmd.endsWith(` ${sub}`)) return false;
   const quotedPath = cmd.slice(0, cmd.length - (sub.length + 1));
@@ -103,34 +84,28 @@ export function isOurHookCommand(cmd: string, sub: string): boolean {
 function removeHook(s: Settings, event: string, sub: string): void {
   const arr = s.hooks?.[event];
   if (!arr) return;
-  // Strip only VERIFIED tokenmaxxing-owned entries from WITHIN each group:
-  // foreign hooks sharing a group - or merely mentioning our strings - survive
-  // (review catches, PR #31), and a group is dropped only once it is empty.
   for (const g of arr) g.hooks = g.hooks.filter((h) => !isOurHookCommand(h.command, sub));
   s.hooks![event] = arr.filter((g) => g.hooks.length > 0);
   if (s.hooks![event]!.length === 0) delete s.hooks![event];
 }
 
-/** Install the entries: take both statusLine slots, append our hooks. Stale
- *  same-subcommand hooks from an OLD install path are dropped first, so a
- *  TOKENMAXXING_HOME relocation rewrites the entries instead of leaving dead
- *  paths that read as installed (relocation residue is how the supervisor
- *  recursion incident started). Foreign hooks are untouched. */
 export function installSettings(): void {
   const s = readSettings();
   s.statusLine = { type: "command", command: ourCommand(SUBCMD.statusline) };
   s.subagentStatusLine = { type: "command", command: ourCommand(SUBCMD.subagentStatusline) };
   removeHook(s, "Stop", SUBCMD.stop);
+  removeHook(s, "StopFailure", SUBCMD.stopFailure);
   removeHook(s, "SessionStart", SUBCMD.sessionStart);
   appendHook(s, "Stop", SUBCMD.stop);
+  appendHook(s, "StopFailure", SUBCMD.stopFailure, STOP_FAILURE_MATCHER);
   appendHook(s, "SessionStart", SUBCMD.sessionStart);
   writeSettings(s);
 }
 
-/** Remove our entries. The statusLine slots are deleted only if they are ours. */
 export function uninstallSettings(): void {
   const s = readSettings();
   removeHook(s, "Stop", SUBCMD.stop);
+  removeHook(s, "StopFailure", SUBCMD.stopFailure);
   removeHook(s, "SessionStart", SUBCMD.sessionStart);
   if (s.statusLine && isOurCommand(s.statusLine.command)) delete s.statusLine;
   if (s.subagentStatusLine && isOurCommand(s.subagentStatusLine.command)) delete s.subagentStatusLine;
@@ -141,22 +116,20 @@ const SettingsCheckSchema = z.object({
   statusLineOk: z.boolean(),
   subagentStatusLineOk: z.boolean(),
   stopOk: z.boolean(),
+  stopFailureOk: z.boolean(),
   sessionStartOk: z.boolean(),
 });
 export type SettingsCheck = z.infer<typeof SettingsCheckSchema>;
 
 export function checkSettings(): SettingsCheck {
   const s = readSettings();
-  // Exact-command identity (review catch, PR #31): only the verbatim string
-  // installSettings writes counts as installed. A hook pointing at an OLD
-  // install path reads as broken, and a foreign command that merely mentions
-  // the path or subcommand as text never green-lights.
-  const has = (event: string, sub: string) =>
-    !!s.hooks?.[event]?.some((g) => g.hooks.some((h) => h.command === ourCommand(sub)));
+  const has = (event: string, sub: string, matcher?: string) =>
+    !!s.hooks?.[event]?.some((g) => (matcher === undefined || g.matcher === matcher) && g.hooks.some((h) => h.command === ourCommand(sub)));
   return {
     statusLineOk: s.statusLine?.command === ourCommand(SUBCMD.statusline),
     subagentStatusLineOk: s.subagentStatusLine?.command === ourCommand(SUBCMD.subagentStatusline),
     stopOk: has("Stop", SUBCMD.stop),
+    stopFailureOk: has("StopFailure", SUBCMD.stopFailure, STOP_FAILURE_MATCHER),
     sessionStartOk: has("SessionStart", SUBCMD.sessionStart),
   };
 }

package/src/lib/state.ts

@@ -1,5 +1,3 @@
-// Config + accounts index + usage snapshot persistence. All writes atomic.
-
 import { existsSync, readFileSync, rmSync, statSync, utimesSync } from "node:fs";
 import { isEqual } from "es-toolkit";
 import { z } from "zod";
@@ -10,6 +8,7 @@ import {
   ConfigSchema,
   LastSwapSchema,
   ModelUsageStateSchema,
+  NextCheckSchema,
   UsageStateSchema,
   type AccountsIndex,
   type Config,
@@ -17,33 +16,16 @@ import {
   type UsageState,
 } from "./types.ts";
 
-// ---- config.json (minimal, fixed schema) ---------------------------------
-
 const DEFAULT_CONFIG: Config = {
-  // LAYER 1 - screening bars, split per window (user 2026-07-16): a session
-  // reset is cheap to sit out, weekly quota is use-it-or-lose-it so it drains
-  // to 98. These drive normal account-to-account switching with headroom.
   thresholds: { session: 95, weekly: 98 },
-  // LAYER 2 - the wall bars (default the server's own 100% limit). Reached only
-  // once every account is over its Layer 1 bar: from there a session pumps the
-  // last drops up to the wall instead of parking with quota unspent.
   hardThresholds: { session: 100, weekly: 100 },
   claudeBin: "",
   codexBin: "",
-  // per-model weekly caps exist only for Sonnet and Fable (no Opus-only quota,
-  // per the user 2026-07-12), and only Fable's is worth switching on.
-  // greedySessionFloor 50: half a session window buys the swap (user 2026-07-16).
   policy: { projectionMargin: 0, greedySessionFloor: 50, switchModels: ["fable"], usagePollTtlMs: 90_000, maxWaitMs: 3_600_000 },
 };
 
-/** Percent-of-window values: out-of-range bars make every account read as
- *  exhausted, so the schema rejects them at the config gate. The cross-field
- *  case (a projectionMargin at or above a threshold zeroes the effective bar)
- *  is caught by ConfigSchema's refine on the merged result. */
 const PercentSchema = z.number().min(0).max(100);
 
-/** 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: PercentSchema, weekly: PercentSchema }).partial(),
@@ -68,12 +50,6 @@ const MergeOutcomeSchema = z.union([
 ]);
 export type MergeOutcome = z.infer<typeof MergeOutcomeSchema>;
 
-/** Merge a validated sparse file over the defaults, apply the env binary
- *  overrides, and validate the merged WHOLE (the projectionMargin-vs-
- *  thresholds refine). Shared by loadConfig and `xx config set`: set must
- *  reject a value whose merged result would make every later loadConfig
- *  throw, silently disabling status/switch/hooks/statusline until the file is
- *  hand-repaired (closing-review catch). */
 export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutcome {
   const cfg: Config = {
     ...DEFAULT_CONFIG,
@@ -94,15 +70,12 @@ export function mergeConfigFile(p: z.infer<typeof ConfigFileSchema>): MergeOutco
   if (p.policy?.switchModels) {
     cfg.policy.switchModels = p.policy.switchModels.map((s) => s.toLowerCase());
   }
-  // env overrides win for the real binaries (tests / relocation)
   const envBin = realClaudeBinFromEnv();
   if (envBin) cfg.claudeBin = envBin;
   const envCodexBin = realCodexBinFromEnv();
   if (envCodexBin) cfg.codexBin = envCodexBin;
   const merged = ConfigSchema.safeParse(cfg);
   if (!merged.success) {
-    // per-field values passed but the merged whole is unusable (the
-    // projectionMargin-vs-thresholds refine); name the reason, not a zod dump.
     return { ok: false, detail: merged.error.issues.map((issue) => issue.message).join("; ") };
   }
   return { ok: true, config: merged.data };
@@ -115,15 +88,10 @@ export function loadConfig(): Config {
     try {
       raw = JSON.parse(readFileSync(paths.configJson, "utf8"));
     } catch {
-      // Silent defaults here once meant a corrupt file could quietly unpin
-      // claudeBin; a damaged config is the user's to repair, loudly.
       throw new Error(`${paths.configJson} is corrupt (unparsable JSON) - fix or remove it`);
     }
     const parsed = ConfigFileSchema.safeParse(raw);
     if (!parsed.success) {
-      // Valid JSON with wrong-typed KNOWN keys must not silently drop pins
-      // like claudeBin; unknown keys are stripped by the schema and stay
-      // tolerated (that is `config tidy`'s territory, not an error).
       const fields = parsed.error.issues.map((issue) => issue.path.join(".")).join(", ");
       throw new Error(`${paths.configJson} has wrong-typed values (${fields}) - fix or remove them`);
     }
@@ -134,12 +102,6 @@ export function loadConfig(): Config {
   return outcome.config;
 }
 
-/** Pin one binary path into the SPARSE config file, preserving every other
- *  override verbatim. Never write the merged config here: baking defaults (or
- *  an ambient TOKENMAXXING_*_BIN env override) into the file freezes future
- *  default changes as stale explicit values and misreports every `xx config`
- *  source as "file" (closing-review catch; the sparse-overrides contract is
- *  config.ts's header). Throws on a corrupt file, like loadConfig. */
 export function pinBinOverride(input: { key: "claudeBin" | "codexBin"; bin: string }): void {
   let raw: Record<string, unknown> = {};
   if (existsSync(paths.configJson)) {
@@ -149,15 +111,9 @@ export function pinBinOverride(input: { key: "claudeBin" | "codexBin"; bin: stri
   writeFileAtomic(paths.configJson, JSON.stringify(raw, null, 2) + "\n");
 }
 
-// ---- accounts.json -------------------------------------------------------
-
 const emptyIndex = (): AccountsIndex => ({ version: 1, activeAccountUuid: null, accounts: [] });
 
 export function loadAccounts(): AccountsIndex {
-  // Absent = genuinely empty. Present-but-unreadable THROWS (mirrors the codex
-  // state loaders): a truncated index once read as an empty pool would send
-  // `init` down first-time onboarding and overwrite it, orphaning every parked
-  // credential. Damaged state is the user's to repair, loudly.
   if (!existsSync(paths.accountsJson)) return emptyIndex();
   let json: unknown;
   try {
@@ -176,8 +132,6 @@ export function saveAccounts(idx: AccountsIndex): void {
   writeFileAtomic(paths.accountsJson, JSON.stringify(AccountsIndexSchema.parse(idx), null, 2) + "\n");
 }
 
-// ---- usage.json ----------------------------------------------------------
-
 export function loadUsage(): UsageState | null {
   if (!existsSync(paths.usageJson)) return null;
   try {
@@ -188,17 +142,11 @@ export function loadUsage(): UsageState | null {
   }
 }
 
-/** Drop the statusLine-fed snapshots after a swap: their windows belong to the
- *  pre-swap account and would otherwise be read under the new active org. */
 export function clearUsageSnapshots(): void {
   rmSync(paths.usageJson, { force: true });
   rmSync(paths.modelUsageJson, { force: true });
 }
 
-// ---- lastswap.json (epoch ms of the last swap; absent = never swapped;
-// present-but-corrupt THROWS - silently reading a damaged swap clock as
-// never-swapped would bypass the post-swap cooldown) ----
-
 export function loadLastSwapAt(): number | null {
   if (!existsSync(paths.lastSwapJson)) return null;
   let json: unknown;
@@ -214,16 +162,6 @@ export function saveLastSwapAt(ts: number): void {
   writeFileAtomic(paths.lastSwapJson, JSON.stringify(LastSwapSchema.parse({ ts })));
 }
 
-// ---- depleted.json (the last depleted-wait decision; absent = none) ----
-// Written on every depleted-wait so hooks that hit an early exit (post-swap
-// cooldown, raced re-check, cleared snapshots) can REPLAY the wait to their
-// own supervisor: without the replay only the first session's Stop hook ever
-// saw a marker-writable decision and sibling sessions never paused (DESIGN.md
-// 3.5's fan-out). The record dies three ways: waitUntil passing, the live
-// seat (claude's oauthAccount) moving off the recorded account, and ANY
-// completed swap clearing it outright (performSwap - the depleted path
-// re-records its own wait right after its pre-park swap returns).
-
 const DepletedWaitSchema = z.object({ waitUntil: z.number(), accountUuid: z.string(), ts: z.number() });
 export type DepletedWait = z.infer<typeof DepletedWaitSchema>;
 
@@ -246,23 +184,36 @@ export function clearDepletedWait(): void {
   rmSync(paths.depletedJson, { force: true });
 }
 
-/** An alive feed re-proving unchanged figures still refreshes `ts` this often,
- *  so cache-age displays stay honest without a write+fsync per tick. */
+export const MAX_CHECK_DELAY_MS = 300_000;
+
+export function loadNextCheckDueAt(now: number): number | null {
+  if (!existsSync(paths.nextCheckJson)) return null;
+  let parsed;
+  try {
+    parsed = NextCheckSchema.safeParse(JSON.parse(readFileSync(paths.nextCheckJson, "utf8")));
+  } catch {
+    return null;
+  }
+  if (!parsed.success) return null;
+  return parsed.data.dueAt - now > MAX_CHECK_DELAY_MS ? null : parsed.data.dueAt;
+}
+
+export function saveNextCheckDueAt(input: { dueAt: number; ts: number }): void {
+  writeFileAtomic(paths.nextCheckJson, JSON.stringify(NextCheckSchema.parse(input)));
+}
+
+export function clearNextCheck(): void {
+  rmSync(paths.nextCheckJson, { force: true });
+}
+
 const USAGE_TS_REFRESH_MS = 10 * 60_000;
 
-/** Write-on-change: skip the write (and its fsync) when only `ts` would differ,
- *  unless the stored `ts` has aged past the refresh window. A suppressed write
- *  still bumps the file's mtime (metadata only, no fsync): mtime is the feed's
- *  liveness heartbeat, and without the bump an alive tee re-proving unchanged
- *  figures reads as a dead feed and the decision path goes model-blind. */
 export function writeUsage(next: UsageState): boolean {
   const prev = loadUsage();
   if (prev && isEqual({ ...prev, ts: 0 }, { ...next, ts: 0 }) && next.ts - prev.ts < USAGE_TS_REFRESH_MS) {
     try {
       utimesSync(paths.usageJson, new Date(next.ts), new Date(next.ts));
     } catch (e) {
-      // The file vanished mid-race: a concurrent swap just invalidated these
-      // figures. Suppressing stays correct; a write would resurrect them.
       const errno = z.object({ code: z.string() }).safeParse(e);
       if (!errno.success || errno.data.code !== "ENOENT") throw e;
     }
@@ -272,9 +223,6 @@ export function writeUsage(next: UsageState): boolean {
   return true;
 }
 
-/** When the usage feed last proved itself alive (usage.json mtime), null if the
- *  snapshot is absent. Fresher than the embedded `ts`, which write-on-change
- *  deliberately lets age while figures hold still. */
 export function usageTeeAt(): number | null {
   try {
     return statSync(paths.usageJson).mtimeMs;
@@ -283,8 +231,6 @@ export function usageTeeAt(): number | null {
   }
 }
 
-// ---- model-usage.json (per-model caps from `/usage`, TTL-cached) ----------
-
 export function loadModelUsage(): ModelUsageState | null {
   if (!existsSync(paths.modelUsageJson)) return null;
   try {

package/src/lib/swap.ts

@@ -1,24 +1,4 @@
-// The account-switch sequence. Runs under the tokenmaxxing flock (held by the
-// caller - the Stop hook or a CLI command). The keychain/json writes additionally
-// run under claude's own refresh lock so they can't interleave with a token refresh.
-//
-//   resolve the live credential's TRUE owner (network, no lock; an expiring
-//     live credential refreshes under claude's refresh lock first)
-//   refresh B's parked credential (network, no lock), persisting the rotation
-//     at once - UNLESS B IS the live owner (label drift): then the live blob is
-//     already the newest rotation and the parked copy must not be refreshed
-//   ── under claude refresh lock ──
-//     verify the live item still holds the token the owner was resolved from
-//     (a concurrent /login or refresh in the unlocked gap aborts the swap)
-//     harvest live → its OWNER's backup (mandatory: refresh token rotates in
-//     place; when the owner IS the target this repairs its stale backup)
-//     install B into the live item
-//     rewrite oauthAccount in ~/.claude.json
-//     mark B active (kept adjacent to the identity write: the files cannot be
-//     crash-atomic together, but the next swap's true-owner resolution catches
-//     and logs any crash drift - swap.harvest_drift)
-
-import { clearDepletedWait, clearUsageSnapshots, loadAccounts, saveAccounts, saveLastSwapAt } from "./state.ts";
+import { clearDepletedWait, clearNextCheck, clearUsageSnapshots, loadAccounts, saveAccounts, saveLastSwapAt } from "./state.ts";
 import { readItem, writeItem, liveTarget, parkedTarget, claudeAiOauthOnly, mergeIntoLive } from "./credstore.ts";
 import { refreshCredential, isAccessTokenExpiring, fetchTokenOrg, InvalidGrantError } from "./oauth.ts";
 import { swapOAuthAccount } from "./claudejson.ts";
@@ -31,27 +11,12 @@ function parseBlob(raw: string) {
   return CredentialBlobSchema.parse(JSON.parse(raw));
 }
 
-/**
- * Mechanically switch the LIVE credential to `target`. Assumes the caller holds
- * the tokenmaxxing flock. Throws InvalidGrantError (after marking needs_reauth)
- * when target's refresh token is dead.
- */
 export async function performSwap(target: Account): Promise<void> {
   const idx = loadAccounts();
 
-  // 1. resolve the live credential's TRUE owner - the harvest destination -
-  //    BEFORE any rotation. activeAccountUuid is a label, and labels drift from
-  //    the blob they describe (crash mid-swap, manual /login, historical
-  //    re-init); harvesting by label is how a backup once got destroyed, and
-  //    refreshing the target's parked copy while the target is secretly the
-  //    LIVE account would rotate a superseded grant and flag a healthy account
-  //    needs-reauth (review catch, iteration 3). The token itself cannot lie.
   const preLive = await readItem(liveTarget());
   let liveOwner: Account | null = null;
   let liveCreds: OAuthCreds | null = null;
-  // What the live item's accessToken must still be when the critical section
-  // below re-reads it: the owner resolution here happens UNLOCKED, so a change
-  // in between means the resolved owner may describe a different credential.
   let expectedLiveToken: string | null = null;
   if (preLive) {
     liveCreds = parseBlob(preLive).claudeAiOauth;
@@ -59,7 +24,6 @@ export async function performSwap(target: Account): Promise<void> {
     if (isAccessTokenExpiring(liveCreds, 60_000)) {
       try {
         await withClaudeRefreshLock(async (lock) => {
-          // re-read inside the lock: claude may have rotated it while we waited.
           const raw2 = await readItem(liveTarget());
           if (raw2 == null) throw new Error("live credential vanished while waiting for the refresh lock");
           const current = parseBlob(raw2).claudeAiOauth;
@@ -72,9 +36,6 @@ export async function performSwap(target: Account): Promise<void> {
         });
       } catch (e) {
         if (!(e instanceof InvalidGrantError)) throw e;
-        // dead credential family: nothing worth preserving, skip the harvest.
-        // expectedLiveToken keeps the on-disk token - the failed refresh wrote
-        // nothing, so the blob is unchanged until someone else changes it.
         liveCreds = null;
         log("swap.harvest_skipped_dead_live", {});
       }
@@ -96,14 +57,6 @@ export async function performSwap(target: Account): Promise<void> {
     }
   }
 
-  // 2. the credential to install. When the target IS the live owner (label
-  //    drift made us "swap onto" the account already live), the live item holds
-  //    the newest rotation and NOTHING must be installed over it - refreshing
-  //    the parked copy would rotate a superseded grant, and installing any
-  //    pre-lock snapshot could clobber a rotation claude makes meanwhile; the
-  //    harvest below repairs the stale backup and the label commit repairs the
-  //    drift. Otherwise refresh the parked credential and persist the rotation
-  //    before ANY later step can fail (mirrors codexswap).
   const selfSwap = liveOwner != null && liveOwner.accountUuid === target.accountUuid;
   let fresh: OAuthCreds | null = null;
   if (!selfSwap) {
@@ -122,74 +75,37 @@ export async function performSwap(target: Account): Promise<void> {
     await writeItem(parkedTarget(target.keychainItem), JSON.stringify({ claudeAiOauth: fresh }));
   }
 
-  // 3. the fast, local, atomic-vs-claude-refresh critical section.
   await withClaudeRefreshLock(async (lock) => {
     const currentLive = await readItem(liveTarget());
     if (lock.compromised()) throw new Error("refresh lock compromised - aborting the swap before any write");
 
-    // The owner above was resolved UNLOCKED (network calls must not sit inside
-    // claude's refresh lock), so a manual /login or a claude refresh can have
-    // replaced the live item since. Harvesting the replaced blob under the
-    // stale owner would corrupt that owner's only backup - the exact incident
-    // class the owner-first order exists to prevent (review catch, PR #31).
-    // Any change aborts before a single write; the next check re-resolves the
-    // true owner and retries.
     const currentToken = currentLive == null ? null : parseBlob(currentLive).claudeAiOauth.accessToken;
     if (currentToken !== expectedLiveToken) {
       throw new Error("live credential changed while unlocked (concurrent /login or refresh) - aborting this swap; the next check re-resolves the owner and retries");
     }
 
-    // harvest the live claudeAiOauth into its OWNER's (small) backup item.
-    // When the owner IS the target (label drift), the live blob is the newest
-    // rotation - the parked refresh was skipped above - so this same write is
-    // exactly the repair of a stale or dead parked backup.
     if (liveOwner && currentLive) {
       await writeItem(parkedTarget(liveOwner.keychainItem), claudeAiOauthOnly(currentLive));
       log("swap.harvest", { account: liveOwner.accountUuid.slice(0, 8) });
     }
 
-    // install B: merge B's fresh claudeAiOauth into the CURRENT live blob so all
-    // sibling state (MCP OAuth tokens, etc.) is preserved across the swap.
-    // (B's rotation was already persisted to its backup right after the refresh.)
-    // A self-swap installs NOTHING: the live item already holds the newest
-    // rotation, re-read under this lock; only the label below needs repair.
     if (fresh != null) {
       await writeItem(liveTarget(), mergeIntoLive(currentLive, fresh));
     }
     swapOAuthAccount(target.oauthAccount);
-    // record B as active immediately after the identity write. These separate
-    // files cannot be crash-atomic together, so a crash may leave intermediate
-    // state; the next swap resolves the live owner from the token itself and
-    // logs any drift (swap.harvest_drift).
     idx.activeAccountUuid = target.accountUuid;
     const t2 = idx.accounts.find((a) => a.accountUuid === target.accountUuid);
     if (t2) { t2.needsReauth = false; }
     saveAccounts(idx);
-    // the snapshots on disk still describe the pre-swap account; under the new
-    // org label they'd trigger a bogus switch off the account just installed.
     clearUsageSnapshots();
-    // any completed swap supersedes a recorded depleted-wait: an unexpired
-    // stale record could otherwise replay through this swap's own cooldown
-    // and pause the fresh seat for a long-gone decision (review catch,
-    // PR #31). The depleted path re-records its own wait right after its
-    // pre-park swap returns.
     clearDepletedWait();
+    clearNextCheck();
     saveLastSwapAt(Date.now());
   });
   log("swap.done", { account: target.accountUuid.slice(0, 8), email: target.email });
 }
 
-/**
- * Pick the best candidate and swap to it, retrying past dead refresh tokens.
- * Assumes the caller holds the flock (does NOT lock - avoids same-process
- * flock self-deadlock). Returns the account landed on, or null if none usable.
- */
 export async function chooseAndSwap(ctx: PickCtx): Promise<Account | null> {
-  // ctx.currentAccountUuid is the caller-resolved SEAT (decide.ts resolves it
-  // by the live org, label fallback): resolving here off activeAccountUuid
-  // re-imported the label drift the caller just resolved away, and under
-  // drift the LIVE account could be picked as its own swap target (bugbot
-  // review catch, PR #33).
   const tried = new Set<string>();
   while (true) {
     const idx = loadAccounts();
@@ -201,7 +117,7 @@ export async function chooseAndSwap(ctx: PickCtx): Promise<Account | null> {
       await performSwap(best);
       return best;
     } catch (e) {
-      if (e instanceof InvalidGrantError) continue; // dead token - next candidate
+      if (e instanceof InvalidGrantError) continue;
       throw e;
     }
   }

package/src/lib/tty.ts

@@ -1,7 +1,3 @@
-// Save/restore the controlling terminal's line settings around a child that owns
-// the tty via inherited stdio. If we SIGTERM such a child (supervisor respawn, or
-// `add` auto-exit), the terminal can be left in raw mode; restoring stty fixes it.
-
 export function saveTermios(): string | null {
   const p = Bun.spawnSync(["/bin/sh", "-c", "stty -g </dev/tty"]);
   const s = p.stdout?.toString().trim();