tokenmaxxing 1.8.0 → 1.9.0

package/src/lib/claudejson.ts

@@ -1,6 +1,3 @@
-// Read/replace the `oauthAccount` identity object in ~/.claude.json.
-// We touch ONLY oauthAccount and preserve every other key verbatim.
-
 import { existsSync, readFileSync } from "node:fs";
 import { z } from "zod";
 import { paths } from "./paths.ts";
@@ -19,20 +16,13 @@ export function readOAuthAccount(): OAuthAccount | null {
   return parsed.success ? parsed.data : null;
 }
 
-/** Detect API-key / helper auth mode (no poolable subscription credential). */
 export function isApiKeyMode(): boolean {
   if (process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN) return true;
   const j = readClaudeJson();
-  // apiKeyHelper is configured in settings, but a persisted flag may appear here too.
   if (z.string().min(1).safeParse(j["apiKeyHelper"]).success) return true;
   return false;
 }
 
-/**
- * Atomically replace ONLY oauthAccount, preserving all other keys and their
- * insertion order. Reads fresh from disk so we never clobber concurrent edits
- * to unrelated keys with a stale in-memory copy.
- */
 export function swapOAuthAccount(next: OAuthAccount): void {
   const j = readClaudeJson();
   j["oauthAccount"] = next;

package/src/lib/claudelock.ts

@@ -1,22 +1,3 @@
-// Interlock with Claude Code's OWN credential-refresh locks so our live-store
-// writes can't interleave with a concurrent token refresh. Binary-verified
-// against 2.1.214's embedded refresh code: claude takes TWO proper-lockfile
-// (mkdir-based) locks rooted at its credentials dir - the primary
-// <credDir>/.oauth_refresh.lock plus a legacy sibling <realpath(credDir)>.lock
-// (~/.claude.lock by default, kept for coordination with older versions) -
-// with stale: 60s, a 5s lock-mtime heartbeat while held, and on contention it
-// retries 5x with 1-2s jitter then FAILS the refresh (lock_timeout) instead of
-// proceeding unlocked. We mirror all of that, including the failure: a lock
-// still held past the retries means a refresh is mid-flight, which is exactly
-// when a live-store write could clobber a rotation. Callers retry next tick.
-//
-// Theft is detected the way proper-lockfile does it: the heartbeat re-stats
-// each lock and compares against the mtime WE last stored - a deviation or a
-// vanished dir means someone reclaimed the lock (only possible if this process
-// stalled past the 60s stale bar). fn gets a `compromised()` probe to check
-// before persisting, release skips dirs we no longer own, and the wrapper
-// throws terminally so no caller trusts work done on a stolen lock.
-
 import { mkdirSync, realpathSync, rmdirSync, statSync, utimesSync } from "node:fs";
 import { join } from "node:path";
 import { delay } from "es-toolkit";
@@ -24,12 +5,11 @@ import { z } from "zod";
 import { credDir } from "./paths.ts";
 import { log } from "./log.ts";
 
-const STALE_MS = 60_000; // claude's own proper-lockfile `stale`
-const HEARTBEAT_MS = 5_000; // claude's own `update` cadence
-const ATTEMPTS = 5; // claude's own ELOCKED retry budget
-const RETRY_MS = 1_000; // claude sleeps 1000 + rand(1000) between attempts
+const STALE_MS = 60_000;
+const HEARTBEAT_MS = 5_000;
+const ATTEMPTS = 5;
+const RETRY_MS = 1_000;
 
-/** mkdir-take one lock dir, reclaiming it when older than claude's stale bar. */
 function tryAcquire(lockDir: string): boolean {
   try {
     mkdirSync(lockDir);
@@ -44,7 +24,7 @@ function tryAcquire(lockDir: string): boolean {
       mkdirSync(lockDir);
       return true;
     }
-  } catch { /* raced: another actor reclaimed it first */ }
+  } catch {  }
   return false;
 }
 
@@ -55,13 +35,13 @@ export async function withClaudeRefreshLock<T>(
   const attempts = opts.attempts ?? ATTEMPTS;
   const retryMs = opts.retryMs ?? RETRY_MS;
   const dir = credDir();
-  mkdirSync(dir, { recursive: true }); // claude mkdirs it before locking too
+  mkdirSync(dir, { recursive: true });
   const primary = join(dir, ".oauth_refresh.lock");
   let legacyRoot = dir;
-  try { legacyRoot = realpathSync(dir); } catch { /* unresolvable: lock the raw path, like claude */ }
+  try { legacyRoot = realpathSync(dir); } catch {  }
   const legacy = `${legacyRoot}.lock`;
 
-  const held: string[] = []; // in release order: legacy first, then primary (claude's order)
+  const held: string[] = [];
   for (let attempt = 1; held.length === 0; attempt++) {
     if (tryAcquire(primary)) {
       try {
@@ -70,12 +50,11 @@ export async function withClaudeRefreshLock<T>(
           break;
         }
       } catch (e) {
-        // claude proceeds on a legacy acquire ERROR; only contention aborts.
         log("claudelock.legacy_error", { err: e instanceof Error ? e.message : String(e) });
         held.push(primary);
         break;
       }
-      rmdirSync(primary); // legacy contested: release and re-take both, like claude
+      rmdirSync(primary);
     }
     if (attempt >= attempts) {
       log("claudelock.contested", { attempts: attempt });
@@ -86,7 +65,6 @@ export async function withClaudeRefreshLock<T>(
     await delay(retryMs + Math.random() * retryMs);
   }
 
-  // the mtime we last stored per lock; a deviation means the lock was stolen.
   const ours = new Map<string, number>();
   for (const d of held) ours.set(d, statSync(d).mtimeMs);
   let compromised = false;
@@ -101,13 +79,13 @@ export async function withClaudeRefreshLock<T>(
     for (const d of held) {
       try {
         if (statSync(d).mtimeMs !== ours.get(d)) {
-          markCompromised(); // someone re-took it; stop touching their lock
+          markCompromised();
           continue;
         }
         utimesSync(d, now, now);
         ours.set(d, statSync(d).mtimeMs);
       } catch {
-        markCompromised(); // dir vanished: stolen or force-cleaned
+        markCompromised();
       }
     }
   }, opts.heartbeatMs ?? HEARTBEAT_MS);
@@ -122,8 +100,8 @@ export async function withClaudeRefreshLock<T>(
     clearInterval(heartbeat);
     for (const d of held) {
       try {
-        if (statSync(d).mtimeMs === ours.get(d)) rmdirSync(d); // release only what is still ours
-      } catch { /* already gone */ }
+        if (statSync(d).mtimeMs === ours.get(d)) rmdirSync(d);
+      } catch {  }
     }
   }
 }

package/src/lib/codexauth.ts

@@ -1,9 +1,3 @@
-// Read/write codex credential blobs ($CODEX_HOME/auth.json and parked copies)
-// and decode the id_token's identity claims. Codex has NO cross-process lock on
-// auth.json (its refresh serialization is an in-process semaphore, verified
-// rust-v0.144.5 manager.rs), so every mutation here runs under tokenmaxxing's
-// own codex flock, held by the caller.
-
 import { readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -15,14 +9,6 @@ function isEnoent(e: unknown): boolean {
   return e instanceof Error && "code" in e && e.code === "ENOENT";
 }
 
-/** auth.json at an explicit path (the live file, or an onboard dir's), or null
- *  when absent. Throws on a present-but-unparsable file: that is drift to
- *  surface, not to paper over. One valid-but-unpoolable state maps to null
- *  instead of throwing: `codex login --with-api-key` writes auth.json with
- *  `tokens` OMITTED (serde skip_serializing_if, verified rust-v0.144.5) - the
- *  real binary runs fine on it, so the shim and status must too, and with no
- *  ChatGPT tokens there is nothing tokenmaxxing can pool (closing-review
- *  catch). */
 export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
   let raw: string;
   try {
@@ -37,7 +23,6 @@ export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
   return CodexAuthJsonSchema.parse(parsed);
 }
 
-/** The live auth.json, or null when codex has no login here. */
 export function readLiveCodexAuth(): CodexAuthJson | null {
   return readCodexAuthAt({ path: codexPaths.authJson });
 }
@@ -65,15 +50,10 @@ export function writeParkedCodexAuth(input: { credFile: string; auth: CodexAuthJ
   writeFileAtomic(parkedPath(input), JSON.stringify(CodexAuthJsonSchema.parse(input.auth), null, 2), 0o600);
 }
 
-/** `rm --codex` uses this so the path shape (.json suffix) has one owner:
- *  a hand-built path without the suffix silently missed the real file under
- *  rmSync force (PR #37 review catch). */
 export function deleteParkedCodexAuth(input: { credFile: string }): void {
   rmSync(parkedPath(input), { force: true });
 }
 
-/** Identity claims inside the id_token JWT payload (verified against a live
- *  0.144.4 token: the chatgpt fields sit under the api.openai.com/auth claim). */
 const IdClaimsSchema = z.looseObject({
   email: z.string().optional(),
   "https://api.openai.com/auth": z
@@ -100,12 +80,6 @@ const CodexIdentitySchema = z.object({
 });
 export type CodexIdentity = z.infer<typeof CodexIdentitySchema>;
 
-/**
- * The blob's own identity, from its token material alone (no network): the
- * explicit tokens.account_id, else the id_token's chatgpt_account_id claim.
- * Parking MUST key on this (or the usage endpoint's echo of it), never on a
- * stored label - labels drift, tokens cannot lie.
- */
 export function codexIdentityOf(input: { auth: CodexAuthJson }): CodexIdentity {
   const { auth } = input;
   const claims = IdClaimsSchema.parse(decodeJwtPayload({ jwt: auth.tokens.id_token }));
@@ -121,9 +95,6 @@ export function codexIdentityOf(input: { auth: CodexAuthJson }): CodexIdentity {
   });
 }
 
-/** True when the access token is within `skewMs` of its JWT exp (or exp is
- *  unreadable). Codex's own proactive refresh margin is 5 minutes; matching it
- *  means we never install a token codex would immediately refresh. */
 export function isCodexAccessExpiring(input: { auth: CodexAuthJson; skewMs?: number; now?: number }): boolean {
   const { auth, skewMs = 300_000, now = Date.now() } = input;
   let exp: number | undefined;

package/src/lib/codexbin.ts

@@ -1,15 +1,9 @@
-// Resolve the REAL codex binary (never our shim on PATH). Same guarantees as
-// claudebin.ts: a configured-but-missing pin fails fast instead of degrading
-// to a scan, and anything that realpath-resolves into our binDir is refused
-// (spawning it as codex would recurse through the codex supervisor).
-
 import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { LOOP_DIAGNOSIS, MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, pointsBackAtUs } from "./claudebin.ts";
 import { loadConfig } from "./state.ts";
 import { paths } from "./paths.ts";
 
-/** First PATH entry with a `codex` that is not us. null when PATH has none. */
 function scanPathForCodex(): string | null {
   for (const d of (process.env.PATH ?? "").split(":")) {
     if (!d) continue;
@@ -41,10 +35,6 @@ export function resolveRealCodex(): string {
   throw new Error("could not locate the real `codex` binary (set codexBin in config.json)");
 }
 
-/** Behavioral check used by `init --codex` before pinning: the binary must
- *  answer `--version` identifying itself as codex, without re-entering our
- *  wrapper (depth preset to the cap kills a poisoned pin on first entry).
- *  Returns null when the binary passes, else the failure detail. */
 export function verifyRealCodex(input: { bin: string }): string | null {
   const env = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH), TOKENMAXXING_PROBE: "1" };
   let p: ReturnType<typeof Bun.spawnSync>;

package/src/lib/codexdecide.ts

@@ -1,11 +1,3 @@
-// Shared codex switch decision, used by the codex Stop hook and `xx switch
-// --codex`. Same policy as decide.ts, reshaped for codex mechanics: usage
-// comes from the free direct GET (no statusLine tee exists), the greedy floor
-// reads against every window class (current codex plans have no 5h window:
-// the weekly aggregate is primary, verified live 2026-07-16), and there is no
-// depleted pre-park (a swap only lands where a window is usable NOW; a
-// depleted pool stays put and recovers when a cached reset passes).
-
 import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -34,18 +26,6 @@ export type CodexSwapDecision = z.infer<typeof CodexSwapDecisionSchema>;
 
 const POST_SWAP_COOLDOWN_MS = 45_000;
 
-/**
- * Sample the LIVE credential's usage and stamp it onto its TRUE owner in the
- * pool (the id_token's own identity: labels drift, the token cannot lie).
- * Refreshes the live blob first when it is near expiry (and no supervised
- * session is running it - see the presence guard below), persisting the
- * rotation to the live file AND the owner's parked copy in the same step -
- * before the usage fetch, so a failed fetch can never strand the parked copy
- * on the reuse-punished superseded refresh token. A dead live grant marks the
- * owner needs-reauth and keeps the cached snapshot, so the decision below can
- * still swap AWAY from it. Returns the owner id, or null when the live
- * credential is absent or unpooled.
- */
 async function sampleLiveOntoOwner(input: { now: number }): Promise<string | null> {
   const { now } = input;
   let live = readLiveCodexAuth();
@@ -55,13 +35,6 @@ async function sampleLiveOntoOwner(input: { now: number }): Promise<string | nul
   const owner = index.accounts.find((account) => account.accountId === identity.accountId);
   if (!owner) return null;
 
-  // The near-expiry refresh is skipped while any supervised session RUNS the
-  // live account: a sibling's Stop hook (or the timer) can land mid-turn of
-  // that session, and two concurrent POSTs of the same rotating refresh token
-  // reuse-punish the loser into a dead grant family (closing-review catch).
-  // The unrotated token stays valid within the margin, so the fetch below
-  // still samples; once expired it fails loudly and the next cycle, after the
-  // running session's own refresh, recovers.
   if (isCodexAccessExpiring({ auth: live, now }) && !presentCodexAccountIds().has(identity.accountId)) {
     try {
       live = await refreshCodexAuth({ auth: live, now });
@@ -86,33 +59,6 @@ async function sampleLiveOntoOwner(input: { now: number }): Promise<string | nul
   return owner.accountId;
 }
 
-/**
- * OWNER-APPROVED sibling reconcile (option b 2026-07-20, widened to ALL
- * non-live siblings by the in-session owner ruling later that day): codex
- * cannot hot-swap, so a pool swap respawns only the deciding session -
- * siblings keep running whatever account they started on, cannot refresh it
- * cross-account, and would wedge at token expiry. The deciding actor
- * therefore SIGNALS every pooled non-live supervisor cross-session: a
- * reconcile marker addressed by supervisorId (presence filenames carry it).
- * The signal is a marker, never a kill: the only safe respawn point is the
- * sibling's own turn boundary, so its Stop hook promotes the marker into a
- * respawn marker there, adding the session id its stdin alone knows. No
- * respawn-cost margin applies - the alternative to a respawn is a guaranteed
- * eventual wedge - and no signal is ever sent while the LIVE seat is itself
- * unusable (the no-depleted-pre-park analog: never move a session onto a
- * blocked account). Orphaned markers (their supervisor exited before
- * promoting) are garbage-collected here. Idempotent per supervisor: an
- * existing marker is left alone.
- *
- * There is deliberately NO self-exclusion (bugbot/pullfrog/cubic review
- * catches, PR #34): a session whose presence names a non-live account IS the
- * stranded sibling even inside its own hook - its "normal decision" evaluates
- * only the live seat and would never rescue it. A signal the sweep writes for
- * the calling session is consumed by the promote pass its own hook runs right
- * after the evaluation, same boundary. The deciding session that just swapped
- * away leaves a self-addressed signal behind too; the promote staleness guard
- * (presence rewritten at respawn) drops it as moot.
- */
 function reconcileNonLiveSiblings(input: {
   index: { accounts: CodexAccount[] };
   liveAccountId: string;
@@ -125,8 +71,6 @@ function reconcileNonLiveSiblings(input: {
   const liveAccount = index.accounts.find((account) => account.accountId === liveAccountId);
   if (!liveAccount || unusable(liveAccount)) return;
   const living = livingCodexPresences();
-  // gc signals addressed to supervisors that no longer live (exited before
-  // promoting): nothing would ever consume them.
   if (existsSync(codexPaths.reconcileDir)) {
     const alive = new Set(living.map((presence) => presence.supervisorId));
     for (const name of readdirSync(codexPaths.reconcileDir)) {
@@ -134,16 +78,8 @@ function reconcileNonLiveSiblings(input: {
     }
   }
   for (const presence of living) {
-    if (presence.accountId === liveAccountId) continue; // riding the live seat: fine
+    if (presence.accountId === liveAccountId) continue;
     const seated = index.accounts.find((account) => account.accountId === presence.accountId);
-    // OWNER RULING (2026-07-20, in-session, superseding the exhausted-only
-    // scope of option b): EVERY pooled non-live sibling is signaled, healthy
-    // included. Codex's guarded reload refuses a cross-account auth.json
-    // refresh, so a non-live session WILL wedge with "Please sign in again"
-    // at its access token's expiry (hours) - the safe-boundary respawn onto
-    // the live seat costs one visible restart, keeps the transcript
-    // (`codex resume <sid>`), and makes the whole pool follow the seat.
-    // Unpooled seats stay untouched: not ours to move.
     if (!seated) continue;
     const markerPath = join(codexPaths.reconcileDir, presence.supervisorId);
     if (existsSync(markerPath)) continue;
@@ -153,9 +89,6 @@ function reconcileNonLiveSiblings(input: {
   }
 }
 
-/** The re-sweep after a PERSISTED swap: failures are logged, never thrown -
- *  the caller must still report swapped:true so the Stop hook writes the
- *  deciding session's own respawn marker. */
 function postSwapResweep(input: { liveAccountId: string; bars: { session: number; weekly: number }; now: number }): void {
   try {
     reconcileNonLiveSiblings({ index: loadCodexAccounts(), liveAccountId: input.liveAccountId, bars: input.bars, now: input.now });
@@ -173,23 +106,11 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
     let index = loadCodexAccounts();
     if (index.accounts.length === 0) return { swapped: false, account: null, reason: "no-pool" };
 
-    // The current account is ALWAYS the live auth.json's own identity: the
-    // stored activeAccountId label drifts (manual `codex login`, a crash
-    // before saveCodexAccounts), and trusting it once let the decision target
-    // the RUNNING account (adversarial review catch, 2026-07-16). A live
-    // identity outside the pool is the org-guard analog: do nothing, a swap
-    // over an unknown credential could destroy its only copy.
     const activeId = liveCodexAccountId();
     if (activeId == null || !index.accounts.some((account) => account.accountId === activeId)) {
       return { swapped: false, account: null, reason: "live-credential-not-in-pool" };
     }
 
-    // Cross-session sibling reconcile runs on EVERY evaluation, BEFORE both
-    // the cooldown return and the engagement gate: a swap strands siblings at
-    // exactly the moment the cooldown starts (bugbot/cubic review catch,
-    // PR #34), and a sibling can be dead while the live seat is healthy and
-    // disengaged. Cached windows are enough here - the promote pass
-    // revalidates the destination's usability at consumption time.
     reconcileNonLiveSiblings({ index, liveAccountId: activeId, bars, now });
 
     const lastSwapAt = loadCodexLastSwapAt();
@@ -197,8 +118,6 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
       return { swapped: false, account: null, reason: "post-swap-cooldown" };
     }
 
-    // Freshness: re-sample the live credential once its owner's cached
-    // snapshot ages past the poll TTL (there is no push feed in between).
     const activeEntry = index.accounts.find((account) => account.accountId === activeId);
     const stale = activeEntry?.lastUsageAt == null || now - activeEntry.lastUsageAt > cfg.policy.usagePollTtlMs;
     if (stale) {
@@ -212,20 +131,12 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
     const active = index.accounts.find((account) => account.accountId === activeId) ?? null;
     if (!active) return { swapped: false, account: null, reason: "no-active-account" };
 
-    // A dead live grant always engages: the seat is unusable regardless of
-    // cached usage, and codexCurrentWins/pickBestCodex already exclude
-    // needs-reauth accounts, so both branches route onto a healthy target.
     const engaged =
       active.needsReauth === true ||
       isCodexEngaged({ account: active, floor: cfg.policy.greedySessionFloor, now }) ||
       isCodexExhausted({ account: active, thresholds: bars, now });
     if (!engaged) return { swapped: false, account: null, reason: "under-threshold-or-stale" };
 
-    // Greedy path: engaged but under every bar. Swap only onto an account
-    // that beats the seat by the respawn-cost margin, never onto one RUNNING
-    // in another session (presence files); re-rank after a dead grant
-    // (performCodexSwap persists needs-reauth before throwing, so the loop
-    // terminates).
     if (!isCodexExhausted({ account: active, thresholds: bars, now })) {
       while (true) {
         const current = loadCodexAccounts();
@@ -243,30 +154,11 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
           throw e;
         }
         log("codexdecide.greedy_swap", { account: best.accountId.slice(0, 8) });
-        // Re-sweep with the NEW live seat: siblings on the account this swap
-        // just departed were invisible to the entry sweep (their account WAS
-        // the live seat then), and the cooldown blocks the next evaluation's
-        // sweep-entry for 45s (pullfrog review catch, PR #34). GUARDED: the
-        // swap is already persisted, so a sweep failure (e.g. a corrupt
-        // presence file, which livingCodexPresences throws on by design) must
-        // not eat the swapped:true return - the Stop hook needs it to write
-        // THIS session's respawn marker (bugbot/cubic P0 catch, PR #34). The
-        // entry sweep stays fail-loud: there nothing irreversible has
-        // happened yet.
         postSwapResweep({ liveAccountId: best.accountId, bars, now });
         return { swapped: true, account: best, reason: "swapped" };
       }
     }
 
-    // Hard path: a bar is crossed. Land on the best usable candidate, walking
-    // past dead grants; a fully depleted pool stays put (no pre-park: nothing
-    // can pause a codex session for a countdown yet). Layer 2 (the wall) is
-    // deliberately claude-only: a running codex cannot hot-adopt a swapped
-    // credential (restart IS the switch), so a last-drop-swap onto a still-
-    // under-wall account would strand any concurrent sibling on the departed
-    // account (the reconcile can only signal siblings onto a Layer-1-usable
-    // seat), and a hold-only Layer 2 is identical to codex already staying put
-    // here - so codex just rides the current account to its wall.
     const tried = new Set<string>();
     while (true) {
       const current = loadCodexAccounts();
@@ -283,9 +175,6 @@ export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promis
         throw e;
       }
       log("codexdecide.hard_swap", { account: best.accountId.slice(0, 8) });
-      // Same guarded post-swap re-sweep as the greedy branch: the departed
-      // account's siblings become signalable only once it stops being the
-      // live seat, and a sweep failure must not eat the swapped:true return.
       postSwapResweep({ liveAccountId: best.accountId, bars, now });
       return { swapped: true, account: best, reason: "swapped" };
     }

package/src/lib/codexoauth.ts

@@ -1,10 +1,3 @@
-// The one OAuth call tokenmaxxing makes for codex: the refresh_token grant.
-// Verified against openai/codex rust-v0.144.5 (login/src/auth/manager.rs):
-// POST auth.openai.com/oauth/token, JSON body {client_id, grant_type,
-// refresh_token}, no auth headers. The server ROTATES the refresh token and
-// punishes reuse of a superseded one (refresh_token_reused), so every rotation
-// must be persisted back into the blob it came from immediately.
-
 import { z } from "zod";
 import { http, safeErrorDetail } from "./http.ts";
 import { CodexAuthJsonSchema, type CodexAuthJson } from "./types.ts";
@@ -13,7 +6,6 @@ const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
 const TOKEN_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_TOKEN_URL) ?? "https://auth.openai.com/oauth/token";
 const CLIENT_ID = EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_CLIENT_ID) ?? "app_EMoamEEZ73f0CkXaXp7hrann";
 
-/** Refresh token dead, superseded, or revoked: mark needs-reauth and move on. */
 export class CodexInvalidGrantError extends Error {
   constructor(detail: string) {
     super(`codex invalid grant: ${detail}`);
@@ -21,8 +13,6 @@ export class CodexInvalidGrantError extends Error {
   }
 }
 
-/** The refresh could not run (endpoint unreachable, throttled, drifted body):
- *  an operational miss to retry later, NOT a dead grant and NOT a bug. */
 export class CodexRefreshFailedError extends Error {
   constructor(detail: string) {
     super(`codex token refresh failed: ${detail}`);
@@ -43,12 +33,6 @@ const DEAD_GRANT_MARKERS = [
   "refresh_token_invalidated",
 ];
 
-/**
- * Exchange the blob's refresh token for fresh tokens. Returns a NEW auth.json
- * value with rotated token material and last_refresh restamped; every sibling
- * field rides along verbatim. Throws CodexInvalidGrantError on a dead grant.
- * Error paths only ever surface response-body snippets, never request headers.
- */
 export async function refreshCodexAuth(input: { auth: CodexAuthJson; now?: number }): Promise<CodexAuthJson> {
   const { auth, now = Date.now() } = input;
   let res: Response;

package/src/lib/codexpick.ts

@@ -1,23 +1,8 @@
-// Choose the codex account to switch TO. Same policy as the claude picker:
-// among usable accounts (no reauth, no window at/over its screening bar that
-// has not reset), take the one furthest behind its own weekly pace (highest
-// pacePressure), because weekly allowance is forfeited at a fixed per-account
-// reset. Windows are duration-classified (isSessionWindow), never assumed:
-// codex's 5h window is absent on current Plus/Pro plans (July 2026), so the
-// weekly aggregate may be the only bar there is.
-
 import { sortBy } from "es-toolkit";
 import { nextWeeklyReset } from "./picker.ts";
 import { isSessionWindow, weeklyWindowOf } from "./codexusage.ts";
 import type { CodexAccount, CodexWindow, Thresholds } from "./types.ts";
 
-/** A window whose reset has passed reads as empty. A NULL reset self-bounds
- *  at sampledAt + the window's own duration (mirroring the claude picker's
- *  blockedUntil, closing-review catch): the wire schema allows reset_at null,
- *  and without the bound an over-bar null-reset window benched the account
- *  FOREVER on a headless box where nothing re-samples parked accounts - the
- *  no-permanent-bench invariant. No duration or sample time = trust the
- *  reading (unmeasured recovery must not look safe). */
 function liveUsed(input: { window: CodexWindow; now: number; sampledAt: number | null }): number {
   const { window, now, sampledAt } = input;
   if (window.resetsAt != null) return window.resetsAt <= now ? 0 : window.usedPercentage;
@@ -35,7 +20,6 @@ function barFor(input: { window: CodexWindow; thresholds: Thresholds }): number
   return isSessionWindow({ window: input.window }) ? input.thresholds.session : input.thresholds.weekly;
 }
 
-/** A window at/over its bar whose reset has not passed blocks the account. */
 export function isCodexExhausted(input: { account: CodexAccount; thresholds: Thresholds; now: number }): boolean {
   const { account, thresholds, now } = input;
   const sampledAt = account.lastUsageAt ?? null;
@@ -44,9 +28,6 @@ export function isCodexExhausted(input: { account: CodexAccount; thresholds: Thr
   );
 }
 
-/** Forward pace pressure on the weekly aggregate: the burn rate the remaining
- *  weekly quota demands before its reset forfeits it. No sampled weekly window
- *  or no reset anchor ranks last (0): unmeasured must not look urgent. */
 export function codexPacePressure(input: { account: CodexAccount; now: number }): number {
   const { account, now } = input;
   const weekly = account.lastUsage ? weeklyWindowOf({ aggregate: account.lastUsage.aggregate }) : null;
@@ -83,17 +64,8 @@ export function pickBestCodex(input: {
   return sortBy(usable, codexSwapPreference(now))[0] ?? null;
 }
 
-/** A codex greedy swap is a SIGTERM + respawn of a live session (codex cannot
- *  hot-adopt), and engagement is chronic on plans whose only window is weekly:
- *  without a margin, every hair of pace-pressure drift would visibly restart
- *  the user's session. The challenger must beat the incumbent by this factor
- *  (adversarial review catch, 2026-07-16); a crossed bar bypasses the margin
- *  entirely via the hard path. */
 export const CODEX_SWAP_IMPROVEMENT = 1.2;
 
-/** Greedy idempotence, mirroring picker.currentWins with the respawn-cost
- *  margin: the active account keeps its seat while usable unless a challenger
- *  beats its pace pressure by CODEX_SWAP_IMPROVEMENT. */
 export function codexCurrentWins(input: {
   active: CodexAccount | null;
   accounts: CodexAccount[];
@@ -107,9 +79,6 @@ export function codexCurrentWins(input: {
   return codexPacePressure({ account: best, now }) <= codexPacePressure({ account: active, now }) * CODEX_SWAP_IMPROVEMENT;
 }
 
-/** True once any window is at/over the greedy engagement floor: with no 5h
- *  window on current codex plans, the floor reads against every window class
- *  rather than the session window alone. */
 export function isCodexEngaged(input: { account: CodexAccount; floor: number; now: number }): boolean {
   const { account, floor, now } = input;
   const sampledAt = account.lastUsageAt ?? null;

package/src/lib/codexpresence.ts

@@ -1,15 +1,3 @@
-// Which codex accounts are RUNNING right now. Codex cannot hot-swap, so a swap
-// respawns only the session whose Stop hook decided it; sibling supervised
-// sessions keep running on whatever account they started with, rotating that
-// account's token live. Such an account is a landmine for the rest of the
-// pool: its parked copy is superseded (refresh trips reuse punishment) and
-// installing it as live would yank the running session's grant. Supervisors
-// therefore declare their session's account in a presence file at every
-// (re)spawn; the picker refuses to target present accounts and the sampler
-// refuses to refresh their parked blobs. Staleness is checked by process
-// IDENTITY (pid + ps lstart), not bare pid-aliveness: after a supervisor
-// crash a recycled pid would otherwise keep its account benched forever.
-
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -23,17 +11,9 @@ const PresenceSchema = z.object({
   startedAt: z.string(),
 });
 
-/** `pid` should be the CODEX CHILD's pid when known (the supervisor passes
- *  it): the session IS the child, and pinning the supervisor's own pid let a
- *  SIGKILLed supervisor prune the presence while its orphaned codex kept
- *  running and rotating the account's token - un-benching a live account for
- *  samplers and the picker (closing-review catch). Defaults to process.pid
- *  for callers that ARE the session-owning process (tests, future uses). */
 export function writeCodexPresence(input: { supervisorId: string; accountId: string; pid?: number }): void {
   const pid = input.pid ?? process.pid;
   const startedAt = pidStartTime(pid);
-  // The pid must be ps-visible; a null here means ps broke or the process
-  // already died - corrupt state to fail loudly on, never a masked placeholder.
   if (startedAt == null) throw new Error(`could not read pid ${pid}'s start time (ps lstart) - refusing to write an unverifiable presence file`);
   mkdirSync(codexPaths.presenceDir, { recursive: true });
   writeFileAtomic(
@@ -49,13 +29,6 @@ export function clearCodexPresence(input: { supervisorId: string }): void {
 const LivingPresenceSchema = z.object({ supervisorId: z.string(), accountId: z.string() });
 export type LivingPresence = z.infer<typeof LivingPresenceSchema>;
 
-/** Every LIVING supervised session (pid + start-time identity match), as
- *  {supervisorId, accountId} pairs - the reconcile sweep needs to address a
- *  specific supervisor, not just know which accounts are busy. Dead or
- *  recycled-pid presences are removed. A file that exists but fails to parse
- *  THROWS (review catch, PR #31): a presence file is what keeps a RUNNING
- *  session's account from being swapped out from under it, so damaged state
- *  must fail the decision loudly, never silently drop the protection. */
 export function livingCodexPresences(): LivingPresence[] {
   const living: LivingPresence[] = [];
   if (!existsSync(codexPaths.presenceDir)) return living;
@@ -65,7 +38,6 @@ export function livingCodexPresences(): LivingPresence[] {
     try {
       raw = readFileSync(file, "utf8");
     } catch (e) {
-      // a supervisor exiting between readdir and read clears its own file
       const errno = z.object({ code: z.string() }).safeParse(e);
       if (errno.success && errno.data.code === "ENOENT") continue;
       throw e;
@@ -82,10 +54,6 @@ export function livingCodexPresences(): LivingPresence[] {
     }
     const observed = pidStartTime(parsed.data.pid);
     if (observed !== parsed.data.startedAt) {
-      // A null lstart is ambiguous: dead pid, or ps itself failing. Deleting
-      // on a ps failure would silently unbench a RUNNING session's account
-      // (review catch, PR #31), so only a confirmed-dead pid - or a live pid
-      // with a DIFFERENT start time, a recycle - may clear the file.
       if (observed == null && pidExists(parsed.data.pid)) {
         throw new Error(`ps could not read the start time of live pid ${parsed.data.pid} (${file}) - refusing to clear a presence file that may guard a RUNNING codex session`);
       }
@@ -97,13 +65,10 @@ export function livingCodexPresences(): LivingPresence[] {
   return living;
 }
 
-/** Account ids with a LIVING supervisor - the picker/sampler exclusion view. */
 export function presentCodexAccountIds(): Set<string> {
   return new Set(livingCodexPresences().map((presence) => presence.accountId));
 }
 
-/** The accounts a swap may target: running accounts are off limits, except the
- *  seat itself (it is ranked as the incumbent, never installed over itself). */
 export function targetableCodexAccounts<T extends { accountId: string }>(input: {
   accounts: T[];
   activeAccountId: string | null;