tokenmaxxing 1.7.0 → 1.9.0

package/src/cli/switch.ts

@@ -1,19 +1,3 @@
-// `tokenmaxxing switch [selector]`.
-// No selector → greedy: rank EVERY account (current included) by pace pressure
-// (furthest behind its own weekly pace first, see picker.ts) among those with
-// session/week under threshold, off the cached windows.
-// When the current account already wins (or ties - swapping between equals buys
-// nothing), do nothing: the command is idempotent, so running it periodically
-// converges on the right account. With a selector → switch to that one. Runs
-// under the flock. When everything is depleted it stays on / switches to
-// whichever account recovers soonest.
-//
-// The active LABEL can drift from the live login (manual /login is the
-// surviving drift source). A no-op would freeze that drift forever, so when
-// ~/.claude.json names a different account than accounts.json we swap for real
-// instead of trusting the label - performSwap resolves the live credential's
-// true owner, harvesting the drifted login correctly.
-
 import { withLock } from "../lib/lock.ts";
 import { paths } from "../lib/paths.ts";
 import { loadAccounts, loadConfig } from "../lib/state.ts";
@@ -36,10 +20,6 @@ export async function cmdSwitch(selector?: string): Promise<number> {
 
   return withLock(paths.lockFile, async () => {
     const idx = loadAccounts();
-    // ONE claude.json read for both identity fields: two reads could straddle
-    // a concurrent /login and describe two different live identities - the
-    // drift check and the seat must come from the same snapshot (cubic review
-    // catch, PR #33).
     const liveClaim = readOAuthAccount();
     const claimed = liveClaim?.accountUuid ?? null;
     const claimedOrg = liveClaim?.organizationUuid ?? null;
@@ -64,26 +44,9 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       return swapTo(target);
     }
 
-    // auto: greedy over everyone, current included - a no-op when current wins.
-    // No session context here, so every configured per-model family gates.
-    // Dead-token fallback mirrors decide.ts's greedy loop, NOT chooseAndSwap:
-    // its fallback lands on the next usable candidate unconditionally, which
-    // is right when over a bar but wrong here - a dead grant on the pace
-    // winner must re-check the seat, or a healthy current account gets a real
-    // swap onto a pace-WORSE account and the next periodic check bounces it
-    // straight back (closing-review catch). performSwap persists needs-reauth
-    // before throwing, so each reload shrinks the candidate set and the loop
-    // terminates.
     const everyone: PickCtx = { now, thresholds: effectiveBars(cfg), currentAccountUuid: null, switchFamilies: cfg.policy.switchModels };
     while (true) {
       const cur = loadAccounts();
-      // The seat is the LIVE login's pooled account when resolvable, the
-      // stored label only as fallback - the same identity rule AND the same
-      // identity KEY as decide.ts's seatOf: the organizationUuid, since quota
-      // is metered per org and the org is what the roles endpoint verifies
-      // (bugbot review catches, PR #33). Under drift this also makes ties
-      // favor the live account: the realign swap then keeps the same
-      // credential instead of hopping accounts on a tie.
       const active =
         (claimedOrg != null ? cur.accounts.find((a) => a.organizationUuid === claimedOrg) : null) ??
         cur.accounts.find((a) => a.accountUuid === cur.activeAccountUuid) ??
@@ -96,7 +59,7 @@ export async function cmdSwitch(selector?: string): Promise<number> {
         return 0;
       }
       const best = pickBest(cur.accounts, { ...everyone, currentAccountUuid: active?.accountUuid ?? null });
-      if (!best) break; // no usable target: the depleted path below decides
+      if (!best) break;
       try {
         await performSwap(best);
       } catch (e) {
@@ -110,20 +73,11 @@ export async function cmdSwitch(selector?: string): Promise<number> {
       return 0;
     }
 
-    // No usable target swapped in: everything is depleted, or the remaining
-    // candidates' refresh tokens just died (performSwap persists needs-reauth
-    // before throwing, hence the reload). Stay on / switch to whichever
-    // recovers soonest. (Layer 2 - the wall squeeze - is deliberately confined
-    // to the automatic decision path in decide.ts, which decides off the live
-    // statusLine tee; bare `xx switch` stays cache-only and simply parks here.)
     const fresh = loadAccounts();
     const earliest = pickEarliestReset(fresh.accounts, everyone);
     if (!earliest) {
-      // Either every account needs re-auth, or every account is blocked with no
-      // recoverable bound (unparsed reset clocks AND no sample time - see log).
       const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
       if (reauth.length > 0) { console.error(c.yellow(`no switchable account - reauth needed (run \`tokenmaxxing auth --all\`): ${reauth.join(", ")}`)); return 1; }
-      // never freeze a label drift behind a no-op (see header).
       const freshActive = fresh.accounts.find((a) => a.accountUuid === fresh.activeAccountUuid) ?? null;
       if (drifted && freshActive) return swapTo(freshActive);
       console.log(c.yellow("all accounts at their limit with unknown reset times (unparsed reset clocks? see tokenmaxxing.log) - staying put"));
@@ -132,8 +86,6 @@ export async function cmdSwitch(selector?: string): Promise<number> {
     const reauth = fresh.accounts.filter((a) => a.needsReauth).map((a) => a.label);
     const reauthNote = reauth.length ? ` - re-auth needed: ${reauth.join(", ")}` : "";
     if (earliest.account.accountUuid === fresh.activeAccountUuid && !drifted) {
-      // availableAt in the past means the current account is fine and the
-      // others are simply unusable - do not claim a limit that is not there.
       const msg = earliest.availableAt <= now
         ? `staying on ${c.bold(earliest.account.label)} - no usable switch target${reauthNote}`
         : `all accounts at limit - staying on ${c.bold(earliest.account.label)} (${fmtReset(earliest.availableAt, now)})${reauthNote}`;

package/src/cli/watch.ts

@@ -1,23 +1,12 @@
-// `tokenmaxxing watch [seconds]`: native live status (issue #3) - re-render
-// `status` on an interval instead of `watch -n 120 'tokenmaxxing status'`.
-// Plain `status` per tick, never `--force`: a ping meters real quota and starts
-// 5h session windows, so watching must stay free; each refresh costs only the
-// parked accounts' `/usage` probes the one-shot status already does.
-
 import { clamp, delay } from "es-toolkit";
 import { loadAccounts } from "../lib/state.ts";
 import { cmdStatus } from "./status.ts";
 import { c } from "./render.ts";
 
 const DEFAULT_INTERVAL_S = 120;
-/** Floor: each tick spawns a `/usage` probe per parked account (seconds each,
- *  under the flock); anything faster than this just queues probes. */
 const MIN_INTERVAL_S = 30;
-/** Cap: past ~24.8 days the setTimeout ms overflow collapses the sleep to ~1ms
- *  and the loop runs hot; a day is already beyond any sane watch cadence. */
 const MAX_INTERVAL_S = 86_400;
 
-/** Seconds between refreshes, clamped; null when the argument is not a positive number. */
 export function resolveWatchInterval(arg?: string): number | null {
   if (arg === undefined) return DEFAULT_INTERVAL_S;
   const n = Number(arg);
@@ -25,9 +14,6 @@ export function resolveWatchInterval(arg?: string): number | null {
   return clamp(n, MIN_INTERVAL_S, MAX_INTERVAL_S);
 }
 
-/** Home + clear screen + clear scrollback. Written only once the fresh frame is
- *  ready to paint (cmdStatus preRender), so the previous frame stays readable
- *  through the multi-second sample instead of blanking - watch(1) semantics. */
 const CLEAR = "\x1b[H\x1b[2J\x1b[3J";
 
 export async function cmdWatch(intervalArg?: string): Promise<number> {
@@ -43,9 +29,6 @@ export async function cmdWatch(intervalArg?: string): Promise<number> {
     console.log(c.dim(`watch: every ${intervalS}s, ${new Date().toLocaleTimeString()}, ctrl-c to quit`));
   };
   while (true) {
-    // One failed tick (a mid-write ~/.claude.json read, a transient probe or
-    // lock error) must not kill an hours-long monitor: report it and keep the
-    // cadence, exactly like watch(1) showing a failing command's output.
     try {
       await cmdStatus(false, paintHeader);
     } catch (e) {

package/src/entries/codexstophook.ts

@@ -1,15 +1,3 @@
-// Codex Stop hook (installed in ~/.codex/hooks.json by `init --codex`). Fires
-// when codex finishes a turn: the transcript is committed and the process is
-// idle, the one boundary where killing it loses nothing. If the decision swaps
-// accounts and this session runs under the codex supervisor, drop a respawn
-// marker keyed by the supervisor's id; the supervisor SIGTERMs codex and
-// relaunches `codex resume <session-id>` on the new account (a running codex
-// never adopts a different account's credential: restart IS the switch).
-//
-// Contract with codex (verified against the 0.144.4 binary + hooks reference):
-// stdin carries session_id, stdout `{}` on exit 0 is the documented no-op, and
-// a hook failure must never block the stop - errors are logged, not thrown.
-
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { z } from "zod";
@@ -29,21 +17,6 @@ import { log } from "../lib/log.ts";
 
 const SupervisorIdSchema = z.string().min(1).optional().catch(undefined);
 
-/** Consume a cross-session reconcile signal addressed to THIS supervisor
- *  (owner-approved option b, 2026-07-20): a deciding actor saw this session
- *  running on an exhausted/dead account and asked it to respawn onto the live
- *  seat. The Stop boundary is the only safe respawn point, and only THIS
- *  hook's stdin carries the session id a resume needs, so promotion happens
- *  here: the signal becomes a normal respawn marker the supervisor already
- *  consumes. Returns true when the respawn marker was written (the session is
- *  about to die - skip the normal decision). Everything past the cheap
- *  no-marker fast path runs under the codex FLOCK (pullfrog review catch,
- *  PR #34): the usability revalidation is only as good as its atomicity with
- *  the marker write - unlocked, a concurrent `xx switch --codex` could move
- *  the live seat onto a blocked account between the check and the write. The
- *  flock serializes promotion against every tokenmaxxing actor (codex's own
- *  actions are unserialized as ever); no nesting occurs because the hook
- *  calls promote strictly before or after the evaluation's own lock. */
 async function promoteReconcile(input: { supervisorId: string; sessionId: string | null }): Promise<boolean> {
   const markerPath = join(codexPaths.reconcileDir, input.supervisorId);
   if (!existsSync(markerPath)) return false;
@@ -52,7 +25,7 @@ async function promoteReconcile(input: { supervisorId: string; sessionId: string
 
 function promoteReconcileLocked(input: { supervisorId: string; sessionId: string | null }): boolean {
   const markerPath = join(codexPaths.reconcileDir, input.supervisorId);
-  if (!existsSync(markerPath)) return false; // re-checked under the lock: a raced consumer may have taken it
+  if (!existsSync(markerPath)) return false;
   const parsed = CodexReconcileMarkerSchema.safeParse((() => {
     try {
       return JSON.parse(readFileSync(markerPath, "utf8"));
@@ -61,15 +34,10 @@ function promoteReconcileLocked(input: { supervisorId: string; sessionId: string
     }
   })());
   if (!parsed.success) {
-    // unlike a presence file, a broken signal guards nothing: drop it loudly.
     rmSync(markerPath, { force: true });
     log("codexstop.reconcile_unparsable", {});
     return false;
   }
-  // Staleness guard: the signal names the account this session was seen on;
-  // if the session has since respawned onto another account the signal is
-  // moot. Same when the live seat changed to (or still is) our own account -
-  // a respawn would land right back where we are.
   const presence = livingCodexPresences().find((p) => p.supervisorId === input.supervisorId) ?? null;
   if (presence == null || presence.accountId !== parsed.data.accountId) {
     rmSync(markerPath, { force: true });
@@ -82,14 +50,6 @@ function promoteReconcileLocked(input: { supervisorId: string; sessionId: string
     log("codexstop.reconcile_moot", {});
     return false;
   }
-  // Revalidate the DESTINATION at consumption time (bugbot/pullfrog/vercel/
-  // cubic review catches, PR #34): a signal can sit across resets and usage
-  // changes, and identity checks alone would move a session onto a live seat
-  // that has since become exhausted, needs-reauth, or left the pool entirely.
-  // The SOURCE seat's state is deliberately not re-checked (owner ruling
-  // 2026-07-20: every pooled non-live sibling follows the seat, healthy or
-  // not - a non-live session wedges at token expiry regardless of quota).
-  // Dropped signals are cheap: the sweep re-signals next evaluation.
   const now = Date.now();
   const bars = effectiveBars(loadConfig());
   const index = loadCodexAccounts();
@@ -101,11 +61,7 @@ function promoteReconcileLocked(input: { supervisorId: string; sessionId: string
     log("codexstop.reconcile_blocked_target", {});
     return false;
   }
-  // blank counts as missing: the supervisor treats a falsy sessionId as
-  // "resume --last", the exact fallback this guard exists to avoid.
   if (input.sessionId == null || input.sessionId.trim() === "") {
-    // keep the signal for the next boundary, whose stdin will carry a real
-    // id - a resume without one could revive the wrong transcript.
     log("codexstop.reconcile_no_session", {});
     return false;
   }
@@ -125,8 +81,6 @@ async function readStdin(): Promise<string> {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-/** The testable core: decide, and on a swap under a supervisor, drop the
- *  respawn marker. Never throws (a hook failure must not block the stop). */
 export async function handleCodexStop(input: { rawStdin: string }): Promise<void> {
   const parsed = CodexStopStdinSchema.safeParse((() => {
     try {
@@ -138,21 +92,11 @@ export async function handleCodexStop(input: { rawStdin: string }): Promise<void
   const sessionId = parsed.success ? (parsed.data.session_id ?? null) : null;
 
   try {
-    // No supervisor = no decision AT ALL, checked before evaluate can swap:
-    // hooks.json is global, so this hook also fires in sessions launched
-    // around the PATH shim (IDE extension, absolute path), and a swap with
-    // nobody to respawn strands that session - codex cannot hot-adopt, and
-    // its guarded reload refuses a cross-account auth.json, so the session
-    // dies on its stale token with "Please sign in again" (closing-review
-    // catch). Restart IS the switch; without a restarter, do not switch.
     const supervisorId = SupervisorIdSchema.parse(process.env[CODEX_SUPERVISOR_ID_ENV]);
     if (supervisorId === undefined) {
       log("codexstop.unsupervised_skip", {});
       return;
     }
-    // A pending reconcile signal outranks the normal decision: this session
-    // is about to respawn onto the live seat, so evaluating it would waste a
-    // sample (and could even swap the seat out from under the respawn).
     if (await promoteReconcile({ supervisorId, sessionId })) return;
     const decision = await evaluateAndMaybeSwapCodex({});
     if (decision.swapped && decision.account) {
@@ -166,11 +110,6 @@ export async function handleCodexStop(input: { rawStdin: string }): Promise<void
       log("codexstop.marker", { supervisorId: supervisorId.slice(0, 8) });
       return;
     }
-    // The evaluation's sweep may have signaled THIS session (its own account
-    // is the wedged one while the live seat is healthy - the lone-stranded
-    // case the removed self-skip used to lose, bugbot/cubic review catch,
-    // PR #34): consume it at this very boundary instead of burning one more
-    // turn on the dead account.
     await promoteReconcile({ supervisorId, sessionId });
   } catch (e) {
     log("codexstop.error", { err: e instanceof Error ? e.message : String(e) });
@@ -181,6 +120,6 @@ export async function runCodexStopHook(): Promise<number> {
   if (!process.env.TOKENMAXXING_PROBE) {
     await handleCodexStop({ rawStdin: await readStdin() });
   }
-  process.stdout.write("{}"); // documented no-op hook output; never block the stop
+  process.stdout.write("{}");
   return 0;
 }

package/src/entries/codexsupervisor.ts

@@ -1,13 +1,3 @@
-// The `codex` supervisor. Invoked in place of codex (via ~/.config/tokenmaxxing/
-// bin/codex on PATH). Codex REQUIRES a restart to change accounts: a running
-// process refuses an auth.json swap to a different account (verified
-// rust-v0.144.5 reload_if_account_id_matches), so unlike the claude supervisor
-// (whose child hot-adopts swaps) this respawn IS the switch mechanism, not just
-// UX. The codex Stop hook performs the swap at an idle turn boundary and drops
-// a marker keyed by THIS supervisor's id (passed down via env, so N concurrent
-// sessions pair correctly); the supervisor then SIGTERMs its child and
-// relaunches `codex resume <session-id>` on the freshly-installed account.
-
 import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
@@ -23,7 +13,6 @@ import { log } from "../lib/log.ts";
 
 export const CODEX_SUPERVISOR_ID_ENV = "TOKENMAXXING_CODEX_SUPERVISOR_ID";
 
-/** Subcommands that never host an interactive session worth managing. */
 const NONINTERACTIVE_SUBCMDS = new Set([
   "exec", "review", "login", "logout", "mcp", "plugin", "mcp-server", "app-server",
   "remote-control", "app", "completion", "update", "doctor", "sandbox", "debug",
@@ -32,11 +21,6 @@ const NONINTERACTIVE_SUBCMDS = new Set([
 
 const PASSTHROUGH_FLAGS = new Set(["--version", "-V", "--help", "-h"]);
 
-/** Read + validate a codex respawn marker. An unparseable one (version-skew
- *  hook, corruption) is dropped loudly and reported as absent: the watcher
- *  checks validity BEFORE the SIGTERM, so garbage never kills the session, and
- *  the post-exit consume never throws after the child is already dead (PR #36
- *  review catch, mirroring the claude supervisor). */
 function consumableCodexMarker(marker: string): z.infer<typeof CodexRespawnMarkerSchema> | null {
   try {
     return CodexRespawnMarkerSchema.parse(JSON.parse(readFileSync(marker, "utf8")));
@@ -47,9 +31,6 @@ function consumableCodexMarker(marker: string): z.infer<typeof CodexRespawnMarke
   }
 }
 
-/** Root options that consume the NEXT token as their value (verified against
- *  `codex --help` 0.144.4): without skipping them, `codex -m gpt exec ...`
- *  would read "gpt" as the subcommand and wrongly supervise an exec run. */
 const VALUE_TAKING_ROOT_FLAGS = new Set([
   "-c", "--config", "-i", "--image", "-m", "--model", "--local-provider", "-p", "--profile",
   "-s", "--sandbox", "-a", "--ask-for-approval", "-C", "--cd", "--add-dir", "--enable",
@@ -70,7 +51,6 @@ export function shouldManageCodex(input: { argv: string[] }): boolean {
   return firstPositional === null || !NONINTERACTIVE_SUBCMDS.has(firstPositional);
 }
 
-/** Entry point: `codex ...args` through the on-PATH shim. */
 export async function runCodexSupervisor(input: { argv: string[] }): Promise<number> {
   const { argv } = input;
   const depth = wrapDepth();
@@ -92,19 +72,7 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
   const real = resolveRealCodex();
   const childEnv = { ...process.env, [WRAP_DEPTH_ENV]: String(depth + 1) };
 
-  // The unmanaged-zone sentinel forces passthrough regardless of argv, exactly
-  // like the claude shim: a serve turn's agent running `codex exec` must reach
-  // the real codex instead of dying at the shared depth cap.
   if (!shouldManageCodex({ argv }) || process.env[UNMANAGED_ENV]) {
-    // STRIP the supervisor pairing env from unmanaged spawns: a nested codex
-    // launched from inside a supervised session (e.g. its agent running
-    // `codex exec ...`) would otherwise inherit the OUTER session's id, and
-    // its global Stop hook could then write a respawn marker that SIGTERMs
-    // the outer session MID-TURN and resumes it onto the nested transcript
-    // (closing-review catch). A managed nested launch is already safe - it
-    // exports its own fresh id below; only a shim-bypassed absolute-path
-    // nested launch keeps the inherited env, the same accepted gap as
-    // claude's bg-daemon bypass.
     const passthroughEnv: Record<string, string | undefined> = { ...childEnv };
     delete passthroughEnv[CODEX_SUPERVISOR_ID_ENV];
     const p = Bun.spawn([real, ...argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: passthroughEnv });
@@ -120,28 +88,12 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
   process.on("SIGINT", () => {});
   process.on("SIGHUP", () => {});
 
-  // On respawn the ONLY reliable relaunch is `codex resume <session-id>`:
-  // codex generates its own session ids (there is no flag to pin one at
-  // launch), so original launch args are used verbatim only for the first
-  // spawn. Model/sandbox preferences persist in config.toml either way.
   let launchArgs = argv;
   let respawns = 0;
   while (true) {
     if (existsSync(marker)) rmSync(marker, { force: true });
     log("codexsupervisor.launch", { supervisorId: supervisorId.slice(0, 8), respawns, args: launchArgs.join(" ") });
 
-    // Declare which account THIS session runs on (the live identity at spawn):
-    // the picker must never target it and the sampler must never rotate its
-    // parked token while the session lives. Rewritten every respawn (the swap
-    // changed the live identity); cleared on exit; PID-validated by readers.
-    // Read + presence-write + spawn run under the codex FLOCK (closing-review
-    // catch): unlocked, a swap could land between the read and the child's
-    // auth.json read, seating the child on the NEW account while presence
-    // named the old one for the session's whole life - un-benching the
-    // running account for samplers and the picker. Under the flock no swap
-    // can interleave until after the spawn; the residual window (child
-    // startup vs a swap acquiring the lock immediately after) is sub-ms in
-    // practice against a swap's network-bound critical section.
     const child = await withLock(codexPaths.lockFile, async () => {
       const spawnAccountId = liveCodexAccountId();
       const spawned = Bun.spawn([real, ...launchArgs], {
@@ -150,32 +102,16 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
         stderr: "inherit",
         env: { ...childEnv, [CODEX_SUPERVISOR_ID_ENV]: supervisorId },
       });
-      // Presence pins the CHILD's pid, written after the spawn (still inside
-      // the flock): the session IS the codex process, and pinning this
-      // supervisor's pid let a SIGKILLed supervisor prune the presence while
-      // its orphaned codex kept rotating the account's token (closing-review
-      // catch). Brief retries cover ps visibility lag on a just-spawned pid.
-      // FAIL CLOSED on final failure (PR #36 review catch): a session running
-      // without presence is exactly the unprotected state presence exists to
-      // prevent - its account would look swappable and samplable - so kill
-      // the just-spawned child (nothing is in flight yet) and surface the
-      // error instead of running unprotected.
       if (spawnAccountId) {
         for (let attempt = 0; attempt < 10; attempt++) {
           try {
             writeCodexPresence({ supervisorId, accountId: spawnAccountId, pid: spawned.pid });
             break;
           } catch (e) {
-            // a child that already exited needs no presence (its absence is
-            // correct) and must keep its own exit result - the normal exit
-            // path below handles it (PR #36 second-round catch)
             if (spawned.exitCode !== null || spawned.signalCode !== null) break;
             if (attempt === 9) {
               log("codexsupervisor.presence_failed", { err: e instanceof Error ? e.message : String(e) });
               spawned.kill();
-              // the child may have entered raw mode during the retries: await
-              // its death and restore the terminal before surfacing (PR #36
-              // second-round catch)
               await spawned.exited;
               restoreTermios(savedTermios);
               throw new Error("could not write the codex presence file - refusing to run an unprotected session (its account would look like a swap target)");
@@ -202,7 +138,7 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
     const winner = await Promise.race([exited, markerWatch.then((found) => (found ? "marker" : "exit"))]);
 
     if (winner === "marker") {
-      child.kill(); // SIGTERM at the committed turn boundary the Stop hook chose
+      child.kill();
     }
     await child.exited;
     done = true;
@@ -218,8 +154,6 @@ export async function runCodexSupervisor(input: { argv: string[] }): Promise<num
       continue;
     }
     clearCodexPresence({ supervisorId });
-    // a reconcile signal addressed to this now-gone session is moot; the
-    // deciding actor's sweep would gc it eventually, this is just prompt.
     rmSync(join(codexPaths.reconcileDir, supervisorId), { force: true });
     log("codexsupervisor.exit", { supervisorId: supervisorId.slice(0, 8), respawns, code: child.exitCode, signal: child.signalCode });
     return child.exitCode ?? (child.signalCode ? 1 : 0);

package/src/entries/mcp.ts

@@ -1,7 +1,3 @@
-// Stdio MCP entry for the portable Agent Plugin (agent-plugin/).
-// Tools wrap existing CLI commands. stdout is reserved for MCP JSON-RPC, so
-// every CLI call captures console.log / console.error and returns the text.
-
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
@@ -27,13 +23,11 @@ function packageVersion(): string {
   }
 }
 
-/** Refuse ambient Claude store overrides the same way the CLI and SDK do. */
 export function refuseAmbientStoreEnv(): string | null {
   const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
   return nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
 }
 
-/** Redact token-shaped spans so tool results never echo credentials. */
 export function scrubSecrets(text: string): string {
   return text
     .replace(/\b(Bearer\s+)[A-Za-z0-9._\-+/=]+/gi, "$1[redacted]")
@@ -43,11 +37,8 @@ export function scrubSecrets(text: string): string {
 
 type CaptureResult = { code: number; stdout: string; stderr: string };
 
-/** Serialize captureCli: console.log/error are process-global, so concurrent
- *  tool calls would interleave stdout into each other and corrupt JSON-RPC. */
 let captureChain: Promise<unknown> = Promise.resolve();
 
-/** Run a CLI cmd while keeping stdout clean for the MCP transport. */
 export async function captureCli(run: () => number | Promise<number>): Promise<CaptureResult> {
   const job = async (): Promise<CaptureResult> => {
     const out: string[] = [];
@@ -264,8 +255,6 @@ export function createTokenmaxxingMcpServer(): McpServer {
   return server;
 }
 
-/** Entrypoint for the Agent Plugin launcher (`agent-plugin/bin/tokenmaxxing-mcp`).
- *  Exported because that bin imports this module (so `import.meta.main` is false here). */
 export async function main(): Promise<void> {
   const ambient = refuseAmbientStoreEnv();
   if (ambient != null) {

package/src/entries/sessionstart.ts

@@ -1,15 +1,9 @@
-// SessionStart hook. A launch/resume backstop: if the active account is already
-// over threshold with FRESH usage (e.g. a prior session left it exhausted), swap
-// the credential before this session's first turn so it starts on a good account.
-// Right after a respawn, the post-swap cooldown in evaluateAndMaybeSwap makes
-// this correctly no-op.
-
 import { z } from "zod";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
 import { log } from "../lib/log.ts";
 
 const SessionStartStdin = z.looseObject({
-  source: z.string().optional(), // startup | resume | clear | compact
+  source: z.string().optional(),
   session_id: z.string().optional(),
 });
 
@@ -29,7 +23,6 @@ export async function runSessionStart(): Promise<number> {
   try {
     const decision = await evaluateAndMaybeSwap();
     if (decision.swapped && decision.account) {
-      // fresh session → it will read the new credential on its first API call.
       log("sessionstart.swapped", { source, account: decision.account.accountUuid.slice(0, 8) });
     }
   } catch (e) {