tokenmaxxing 1.8.0 → 1.9.0

package/src/entries/stophook.ts

@@ -1,26 +1,11 @@
-// Stop hook. Fires when claude finishes a turn (transcript already committed).
-// A plain swap needs no respawn: the running session adopts the swapped
-// credential on its own (<=30s on macOS, next request on Linux). Only a
-// depleted-pool wait - when running under the supervisor - drops a respawn
-// marker keyed by this session id: the supervisor SIGTERMs its child at this
-// clean boundary, counts down to the reset, then relaunches `--resume`. We
-// never kill claude ourselves.
-
 import { join } from "node:path";
 import { z } from "zod";
 import { paths } from "../lib/paths.ts";
 import { writeFileAtomic } from "../lib/atomic.ts";
 import { evaluateAndMaybeSwap } from "../lib/decide.ts";
-import { writeTurnDoneMarker } from "../lib/relay/markers.ts";
-import { registryHas } from "../lib/relay/registry.ts";
-import { RELAY_SESSION_ENV } from "../lib/relay/worker.ts";
 import { RespawnMarkerSchema } from "../lib/types.ts";
 import { log } from "../lib/log.ts";
 
-// session_id must be a real transcript UUID: a malformed value would ride the
-// respawn marker into `--resume <garbage>`, which claude treats as a picker
-// search term (PR #36 review catch); non-UUID input drops to undefined and the
-// marker falls back to the pinned sid.
 const StopStdin = z.looseObject({ session_id: z.uuid().optional().catch(undefined) });
 
 async function readStdin(): Promise<string> {
@@ -30,43 +15,27 @@ async function readStdin(): Promise<string> {
 }
 
 export async function runStopHook(): Promise<number> {
-  // recursion guard - our own `-p '/usage'` probe re-enters hooks.
   if (process.env.TOKENMAXXING_PROBE) return 0;
 
   const raw = await readStdin();
   const parsed = StopStdin.safeParse((() => { try { return JSON.parse(raw); } catch { return {}; } })());
-  // TWO session ids with different jobs (closing-review HIGH catch): the
-  // PINNED id (env, set once by the supervisor) names the marker file the
-  // supervisor actually watches and survives /clear; the STDIN id names the
-  // CURRENT transcript to resume and drifts to a new value after /clear.
-  // Keying the file by the stdin id orphaned every post-/clear marker.
   const stdinSid = parsed.success ? parsed.data.session_id : undefined;
   const pinnedSid = process.env.TOKENMAXXING_SESSION_ID;
 
   try {
-    // Additive relay turn-done marker (never writes into respawn/). Only when
-    // a registry entry exists for this relay session.
-    const relaySid = process.env[RELAY_SESSION_ENV];
-    if (relaySid != null && registryHas({ sessionId: relaySid })) {
-      writeTurnDoneMarker({ sessionId: relaySid, source: "claude-stop" });
-      log("stop.relay_turn_done", { session: relaySid.slice(0, 8) });
-    }
-
-    // Anticipatory depleted swaps are only sane when the respawn marker below
-    // will actually pause the session until the reset.
     const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && pinnedSid != null;
     const decision = await evaluateAndMaybeSwap(Date.now(), canPause);
     if (decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
       log(decision.swapped ? "stop.swapped" : "stop.wait", { account: decision.account.accountUuid.slice(0, 8), waitUntil: decision.waitUntil });
-      // Respawn only for a depleted-pool wait: pausing until the reset requires
-      // killing the child. A plain swap leaves the session running to adopt.
       if (decision.waitUntil !== undefined && canPause && pinnedSid) {
         const marker = join(paths.respawnDir, pinnedSid);
+        const launchedAt = z.coerce.number().finite().optional().catch(undefined).parse(process.env.TOKENMAXXING_LAUNCHED_AT);
         const payload = RespawnMarkerSchema.parse({
           account: decision.account.label,
           ts: Date.now(),
           waitUntil: decision.waitUntil,
           sessionId: stdinSid ?? pinnedSid,
+          ...(launchedAt != null ? { launchedAt } : {}),
         });
         writeFileAtomic(marker, JSON.stringify(payload));
         log("stop.marker", { session: (stdinSid ?? pinnedSid).slice(0, 8) });
@@ -75,5 +44,5 @@ export async function runStopHook(): Promise<number> {
   } catch (e) {
     log("stop.error", { err: e instanceof Error ? e.message : String(e) });
   }
-  return 0; // never block the stop
+  return 0;
 }

package/src/entries/subagentstatusline.ts

@@ -1,16 +1,3 @@
-// Renders claude's subagentStatusLine: one {id, content} JSON line per active
-// subagent task, so the agents panel shows each subagent's model, effort, and
-// ctx fill the way the main statusline shows the session's (user ask
-// 2026-07-18). This per-row panel surface is the only place subagent info can
-// appear: the main statusLine command never learns which subagent the UI is
-// viewing (verified against the 2.1.214 bundle). Row shape mirrors the main
-// info block, info first so claude's end-truncation eats the label instead:
-//   "fable (high)  <task label>" - the family name painted by the task's
-//   context fill (colorless mode keeps a numeric ctx token).
-// A task we emit nothing for keeps claude's default row (emitting empty
-// content would HIDE it). Must NEVER break the panel: render what parses,
-// skip what doesn't.
-
 import { z } from "zod";
 import { makeColors, makeUsagePaint } from "../cli/render.ts";
 import { readStdin } from "./statusline.ts";
@@ -19,14 +6,11 @@ import { SubagentStatusLineStdinSchema } from "../lib/types.ts";
 const RowCtxSchema = z.object({ color: z.boolean(), truecolor: z.boolean() });
 export type RowCtx = z.infer<typeof RowCtxSchema>;
 
-/** "claude-fable-5" -> "fable" (lowercase family, matching the chart-label
- *  convention); an id without the claude- prefix passes through whole. */
 function modelFamily(id: string): string {
   const [head, family] = id.split("-");
   return head === "claude" && family ? family : id;
 }
 
-/** Pure renderer: subagentStatusLine stdin -> {id, content} JSON lines. */
 export function renderSubagentRows(stdinObj: unknown, ctx: RowCtx): string[] {
   const parsed = SubagentStatusLineStdinSchema.safeParse(stdinObj);
   if (!parsed.success) return [];
@@ -41,8 +25,6 @@ export function renderSubagentRows(stdinObj: unknown, ctx: RowCtx): string[] {
         ? Math.round((t.tokenCount / t.contextWindowSize) * 100)
         : null;
     const info: string[] = [];
-    // The model name carries the task's context-fill color (same rule as the
-    // main line); colorless mode keeps the numeric ctx token instead.
     if (t.model != null) {
       const family = modelFamily(t.model);
       const body = pct != null ? col.bold(paint(pct)(family)) : col.bold(family);
@@ -66,7 +48,6 @@ export async function runSubagentStatusline(): Promise<number> {
   try {
     obj = JSON.parse(raw);
   } catch {
-    // malformed stdin - emit nothing, claude keeps its default rows
   }
   const colorterm = z.string().optional().parse(process.env.COLORTERM);
   const rows = renderSubagentRows(obj, {

package/src/entries/supervisor.ts

@@ -1,12 +1,3 @@
-// The `claude` supervisor. Invoked in place of claude (via ~/.config/tokenmaxxing/
-// bin/claude on PATH). Runs the REAL claude with inherited stdio (claude owns the
-// real terminal exactly as if run directly), pins a session id, and watches for a
-// respawn marker dropped by the Stop hook on a depleted-pool wait (plain swaps
-// adopt in place and never respawn). When the marker appears it SIGTERMs its own
-// child at the (already-committed) turn boundary, counts down to the reset, and
-// relaunches `claude --resume <id>`. Process/terminal manager only - it never
-// reads or proxies tokens.
-
 import { existsSync, mkdirSync, readFileSync, rmSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { maxBy } from "es-toolkit";
@@ -23,13 +14,6 @@ const NONINTERACTIVE_SUBCMDS = new Set([
   "setup-token", "plugin", "agents", "completion", "help",
 ]);
 
-// Root flags whose VALUE tokens must never be read as the subcommand (e.g.
-// `--settings config` is an interactive session, not `claude config`): the
-// same hardening class shouldManageCodex got. Split by arity, mirroring
-// claude's own commander declarations (--help-verified 2.1.215; claude changes
-// monthly - a newly added value-taking flag regresses only that flag's
-// collision case). `--session-id` / `-r` / `--resume` consume their values in
-// dedicated branches below.
 const VALUE_TAKING_ROOT_FLAGS = new Set([
   "--agent", "--agents", "--append-system-prompt", "--append-system-prompt-file",
   "--debug-file", "--effort", "--fallback-model", "--input-format",
@@ -38,12 +22,10 @@ const VALUE_TAKING_ROOT_FLAGS = new Set([
   "--remote-control-session-name-prefix", "--setting-sources", "--settings",
   "--system-prompt",
 ]);
-// Variadic (`<x...>`): commander consumes EVERY following non-dash token.
 const VARIADIC_ROOT_FLAGS = new Set([
   "--add-dir", "--allowedTools", "--allowed-tools", "--betas",
   "--disallowedTools", "--disallowed-tools", "--file", "--mcp-config", "--tools",
 ]);
-// Optional value (`[x]`): commander consumes the next token unless it is a flag.
 const OPTIONAL_VALUE_ROOT_FLAGS = new Set([
   "-d", "--debug", "--from-pr", "--prompt-suggestions", "--remote-control", "-w", "--worktree",
 ]);
@@ -73,33 +55,17 @@ export function analyzeArgs(argv: string[]): Analysis {
     if (a === "-p" || a === "--print") printMode = true;
     else if (a === "--version" || a === "-v" || a === "--help" || a === "-h") printMode = true;
     else if (a === "--session-id") {
-      // A non-UUID here must never become supervisor state: the sid names the
-      // respawn-marker and session-flag paths (an unvalidated value could
-      // traverse out of them), and real claude rejects a malformed id anyway -
-      // pass it through unmanaged and let claude do the rejecting.
       const next = argv[++i] ?? null;
       if (next && isUuid(next)) sessionId = next;
       else invalidSessionArg = true;
     }
     else if (a === "-c" || a === "--continue") continueLatest = true;
     else if (a === "-r" || a === "--resume") {
-      // A UUID resume is managed (the sid is known, marker paths can be
-      // pinned). Bare `-r`, or `-r <term>` (binary-verified 2.1.214: a non-id
-      // value is an interactive-picker SEARCH TERM), choose the sid INSIDE
-      // claude - the supervisor cannot pin marker paths for an unknown sid, so
-      // those pass through unmanaged and claude behaves exactly as without the
-      // wrapper (same accepted state as claude's bg-daemon sessions: swaps
-      // still adopt in place, hooks still fire; only the depleted-pool
-      // countdown is absent).
       const next = argv[i + 1];
       if (next && !next.startsWith("-") && isUuid(next)) { resumeId = next; i++; }
       else pickerResume = true;
     }
     else if (a === "--fork-session") forkSession = true;
-    // commander's `--flag=value` forms (closing-review catch: unrecognized,
-    // they were skipped as unknown dash-args, so the supervisor pinned a
-    // fresh random sid while claude ran the flag-selected session - markers
-    // and session flags landed under an id nothing was running).
     else if (a.startsWith("--session-id=")) {
       const value = a.slice("--session-id=".length);
       if (isUuid(value)) sessionId = value;
@@ -123,18 +89,11 @@ export function analyzeArgs(argv: string[]): Analysis {
   }
 
   const isSubcmd = firstPositional !== null && NONINTERACTIVE_SUBCMDS.has(firstPositional);
-  // A forked resume gets a NEW session id chosen inside claude, so the
-  // supervisor cannot pin marker paths - pass through unmanaged like
-  // picker-mode resume (closing-review catch: managing it paired the marker
-  // to the stale pre-fork sid, and a respawn would fork yet another session).
   const forkResume = forkSession && (resumeId !== null || continueLatest);
   const manage = !printMode && !isSubcmd && !invalidSessionArg && !pickerResume && !forkResume && !process.env.TOKENMAXXING_PROBE;
   return { manage, sessionId, resumeId, continueLatest };
 }
 
-/** Remove session-selecting flags so we can inject our own on respawn. Managed
- *  argv can only carry a UUID-valued resume (picker-mode passes through
- *  unmanaged), so the value is always consumed with its flag. */
 export function stripSessionFlags(argv: string[]): string[] {
   const out: string[] = [];
   for (let i = 0; i < argv.length; i++) {
@@ -142,43 +101,17 @@ export function stripSessionFlags(argv: string[]): string[] {
     if (a === "--session-id") { i++; continue; }
     if (a === "-c" || a === "--continue") continue;
     if (a === "-r" || a === "--resume") { i++; continue; }
-    // the commander `=` forms carry their value in the same token
     if (a.startsWith("--session-id=") || a.startsWith("--resume=")) continue;
-    // --fork-session must not survive into respawn args: bare `--fork-session`
-    // is inert and stays managed, but a depleted-pool respawn injects
-    // `--resume <sid>` - with the flag still present claude would FORK to a
-    // NEW session id, permanently unpairing the supervisor's marker path from
-    // the running session (closing-review catch).
     if (a === "--fork-session") continue;
     out.push(a);
   }
   return out;
 }
 
-/** Remove positional tokens (the one-shot initial prompt) while keeping every
- *  flag and its consumed value(s). A positional is a submit-once user turn:
- *  persisting or replaying it on a respawn / later `--resume` re-injects the
- *  original instruction into an already-progressed session (adversarial-review
- *  HIGH catch) - only real flags like --model belong in sessions/ files and
- *  respawn args.
- *
- *  TRADEOFF (WONTFIX, flagged PR #37): when claude adds a value-taking root
- *  flag before the sets above are updated, that value reads as a positional
- *  and is dropped, so the respawn launches without it and claude errors on the
- *  missing argument - loud, and the user relaunches. The alternative default
- *  (treat a bare token after an UNRECOGNIZED flag as that flag's value) turns
- *  the same staleness silent: a newly added BOOLEAN flag sitting before the
- *  prompt would make the prompt look like a value and replay a submit-once
- *  turn, which is the exact harm this function exists to prevent. The
- *  ambiguity is irreducible without claude's own option table, and a loud
- *  broken launch beats a silent re-submit. */
 export function stripPositionals(argv: string[]): string[] {
   const out: string[] = [];
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i]!;
-    // `--` ends option parsing: everything after it is positional (a prompt
-    // deliberately starting with "-"), never a flag to persist (PR #37
-    // review catch). The delimiter itself is dropped with them.
     if (a === "--") break;
     if (!a.startsWith("-")) continue;
     out.push(a);
@@ -193,12 +126,6 @@ export function stripPositionals(argv: string[]): string[] {
   return out;
 }
 
-/** Newest transcript session id for the current cwd (for `-c`). claude's
- *  project-dir slug maps EVERY non-alphanumeric char to "-": the regex below
- *  mirrors claude's own, byte for byte (binary-verified 2.1.215, the external-
- *  contract regex exception). The old [/.]-only mapping missed underscores
- *  etc., so `-c` in such a cwd silently opened a brand-new session instead of
- *  continuing (closing-review catch). */
 function latestSessionForCwd(): string | null {
   const slug = process.cwd().replace(/[^a-zA-Z0-9]/g, "-");
   const projDir = join(paths.claudeDir, "projects", slug);
@@ -214,24 +141,35 @@ function latestSessionForCwd(): string | null {
   }
 }
 
-/** Read + validate a respawn marker. An unparseable one (a version-skew hook,
- *  corruption) is dropped loudly and reported as absent: the watcher checks
- *  validity BEFORE the SIGTERM, so garbage can never kill the session, and the
- *  post-exit consume can never throw after the child is already dead (PR #36
- *  review catch). */
-function consumableMarker(marker: string): z.infer<typeof RespawnMarkerSchema> | null {
+const MarkerGateSchema = z.object({
+  launchedAt: z.number(),
+  overriddenUntil: z.number(),
+});
+type MarkerGate = z.infer<typeof MarkerGateSchema>;
+
+function consumableMarker(marker: string, gate: MarkerGate): z.infer<typeof RespawnMarkerSchema> | null {
+  let m: z.infer<typeof RespawnMarkerSchema>;
   try {
-    return RespawnMarkerSchema.parse(JSON.parse(readFileSync(marker, "utf8")));
+    m = RespawnMarkerSchema.parse(JSON.parse(readFileSync(marker, "utf8")));
   } catch (e) {
     rmSync(marker, { force: true });
     log("supervisor.marker_invalid", { err: e instanceof Error ? e.message : String(e) });
     return null;
   }
+  if (m.launchedAt !== undefined && m.launchedAt !== gate.launchedAt) {
+    rmSync(marker, { force: true });
+    log("supervisor.marker_stale", { markerLaunch: m.launchedAt, childLaunch: gate.launchedAt });
+    return null;
+  }
+  if (m.waitUntil > Date.now() && m.waitUntil <= gate.overriddenUntil) {
+    rmSync(marker, { force: true });
+    log("supervisor.marker_overridden", { waitUntil: m.waitUntil });
+    return null;
+  }
+  return m;
 }
 
-/** Interruptible countdown until `until`, shown in the terminal (claude is dead,
- *  so the statusLine can't render it). Ctrl-C resumes immediately. */
-async function countdownWait(acct: string, until: number): Promise<void> {
+async function countdownWait(acct: string, until: number): Promise<boolean> {
   let aborted = false;
   const onInt = () => { aborted = true; };
   process.on("SIGINT", onInt);
@@ -245,13 +183,10 @@ async function countdownWait(acct: string, until: number): Promise<void> {
   }
   process.removeListener("SIGINT", onInt);
   process.stdout.write(`\n\x1b[36m↻ resuming on ${acct}...\x1b[0m\n`);
+  return aborted;
 }
 
-/** Entry point: `claude ...args`. */
 export async function runSupervisor(argv: string[]): Promise<number> {
-  // Depth cap: every spawn below tags its child, so a claudeBin that leads back
-  // here (pinned shim re-execing `claude` from PATH) dies at a handful of
-  // processes instead of fork-bombing the machine (2026-07-12 incident).
   const depth = wrapDepth();
   if (depth >= MAX_WRAP_DEPTH) {
     console.error(
@@ -260,8 +195,6 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     log("supervisor.loop_abort", { depth });
     return 1;
   }
-  // Rate backstop: an env-sanitizing shim in the loop strips the sentinel, but
-  // it cannot erase the on-disk entry counter.
   if (wrapperEntryRateTripped(Date.now())) {
     console.error(
       `tokenmaxxing: ${LOOP_DIAGNOSIS} (over ${WRAP_RATE_MAX} wrapper entries in ${WRAP_RATE_WINDOW_MS / 1000}s) - claudeBin in ${paths.configJson} does not launch the real Claude binary. Fix claudeBin, then run \`tokenmaxxing doctor\`.`,
@@ -273,21 +206,7 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   const info = analyzeArgs(argv);
   const childEnv = { ...process.env, [WRAP_DEPTH_ENV]: String(depth + 1) };
 
-  // Pass-through: no session management, no respawn - exact stock behavior.
-  // The unmanaged-zone sentinel (pooledSpawnEnv) forces it regardless of argv:
-  // everything below an SDK-driven session runs the real claude unsupervised,
-  // so a repo script invoking `claude` from inside a serve turn works instead
-  // of dying at the depth cap. The sentinel rides childEnv, so the whole
-  // subtree stays unmanaged, and depth still counts wrapper entries toward
-  // the cap above, keeping a poisoned pin inside the zone bounded.
   if (!info.manage || process.env[UNMANAGED_ENV]) {
-    // STRIP the supervision pairing env (mirrors the codex shim's passthrough
-    // arm, closing-review catch): a nested unmanaged claude inside a
-    // supervised session (e.g. the agent running `claude -p ...`) would
-    // otherwise inherit TOKENMAXXING_SUPERVISED/TOKENMAXXING_SESSION_ID, and
-    // its Stop hooks - which DO fire in print mode - would compute
-    // canPause=true and could anticipatorily pre-park the pool against a
-    // marker path the OUTER supervisor owns.
     const passthroughEnv: Record<string, string | undefined> = { ...childEnv };
     delete passthroughEnv.TOKENMAXXING_SUPERVISED;
     delete passthroughEnv.TOKENMAXXING_SESSION_ID;
@@ -296,7 +215,6 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     return p.exitCode ?? (p.signalCode ? 1 : 0);
   }
 
-  // Decide the managed session id + whether we're resuming an existing one.
   let base = stripSessionFlags(argv);
   let sid: string;
   let resuming = false;
@@ -312,19 +230,10 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     sid = crypto.randomUUID();
   }
 
-  // Restore the original launch flags when resuming a session with none given
-  // this time (a bare `claude --resume <id>`, or the depleted-pool recovery).
   if (resuming && base.length === 0) {
     const persisted = loadSessionFlags(sid);
-    // enforce the flags-only contract at the trust boundary, not just at
-    // write: a sessions/ file written before stripPositionals existed can
-    // still carry the original prompt, and restoring it verbatim would
-    // re-submit that prompt on a bare `claude --resume` (PR #37 review
-    // catch). Idempotent on well-formed files.
     if (persisted) base = stripPositionals(persisted);
   }
-  // The FIRST launch keeps a positional prompt (the user just typed it);
-  // everything persisted or respawned carries flags only.
   const persistable = stripPositionals(base);
   saveSessionFlags(sid, persistable, process.cwd());
   pruneStaleSessions(Date.now());
@@ -335,28 +244,27 @@ export async function runSupervisor(argv: string[]): Promise<number> {
   const marker = join(paths.respawnDir, sid);
   const savedTermios = saveTermios();
 
-  // Supervisor survives the SIGINT/SIGHUP that flow to the foreground group;
-  // claude (the child, same pgrp) receives and handles them itself.
   process.on("SIGINT", () => {});
   process.on("SIGHUP", () => {});
 
   let respawns = 0;
+  let overriddenUntil = 0;
   while (true) {
     if (existsSync(marker)) rmSync(marker, { force: true });
     log("supervisor.launch", { sid, respawns, args: launchArgs.join(" ") });
 
+    const gate: MarkerGate = { launchedAt: Date.now(), overriddenUntil };
     const child = Bun.spawn([real, ...launchArgs], {
       stdin: "inherit",
       stdout: "inherit",
       stderr: "inherit",
-      env: { ...childEnv, TOKENMAXXING_SUPERVISED: "1", TOKENMAXXING_SESSION_ID: sid },
+      env: { ...childEnv, TOKENMAXXING_SUPERVISED: "1", TOKENMAXXING_SESSION_ID: sid, TOKENMAXXING_LAUNCHED_AT: String(gate.launchedAt) },
     });
 
-    // Race the child's own exit against the appearance of a respawn marker.
     let done = false;
     const markerWatch = (async () => {
       while (!done) {
-        if (existsSync(marker) && consumableMarker(marker) != null) return true;
+        if (existsSync(marker) && consumableMarker(marker, gate) != null) return true;
         await Bun.sleep(150);
       }
       return false;
@@ -365,32 +273,24 @@ export async function runSupervisor(argv: string[]): Promise<number> {
     const winner = await Promise.race([exited, markerWatch.then((m) => (m ? "marker" : "exit"))]);
 
     if (winner === "marker") {
-      child.kill(); // SIGTERM at the committed turn boundary
+      child.kill();
     }
     await child.exited;
     done = true;
     await markerWatch.catch(() => {});
     restoreTermios(savedTermios);
 
-    const m = existsSync(marker) ? consumableMarker(marker) : null;
+    const m = existsSync(marker) ? consumableMarker(marker, gate) : null;
     if (m) {
       rmSync(marker, { force: true });
       respawns++;
-      if (m.waitUntil > Date.now()) await countdownWait(m.account, m.waitUntil);
-      else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming...\x1b[0m\n`);
-      // resume the marker's CURRENT transcript, not the pinned id: after
-      // /clear they differ, and resuming the pinned id would revive the
-      // pre-/clear conversation (closing-review HIGH catch). Persist the
-      // flags under that transcript id too, so a later bare
-      // `claude --resume <id>` restores them (PR #36 review catch). FLAGS
-      // only: replaying a positional prompt would re-submit it as a fresh
-      // turn on the progressed session (adversarial-review HIGH catch).
+      if (m.waitUntil > Date.now()) {
+        if (await countdownWait(m.account, m.waitUntil)) overriddenUntil = m.waitUntil;
+      } else process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched to ${m.account} - resuming...\x1b[0m\n`);
       saveSessionFlags(m.sessionId, persistable, process.cwd());
-      launchArgs = ["--resume", m.sessionId, ...persistable];
+      launchArgs = ["--resume", m.sessionId, ...persistable, ...(m.prompt ? ["--", m.prompt] : [])];
       continue;
     }
-    // No marker: claude exited on its own (quit, crash, resume refused). Log it -
-    // "the process just exited" is undiagnosable without the code/signal.
     log("supervisor.exit", { sid, respawns, code: child.exitCode, signal: child.signalCode });
     return child.exitCode ?? (child.signalCode ? 1 : 0);
   }

package/src/lib/atomic.ts

@@ -1,13 +1,6 @@
-// Atomic file writes (temp + rename on the same filesystem) and small fs utils.
-
 import { closeSync, mkdirSync, openSync, renameSync, rmSync, writeSync, fsyncSync } from "node:fs";
 import { dirname } from "node:path";
 
-/**
- * Write `data` to `file` atomically: write a sibling temp file, fsync it, then
- * rename over the target. A concurrent reader sees either the old or new file,
- * never a partial one.
- */
 export function writeFileAtomic(file: string, data: string | Uint8Array, mode = 0o600): void {
   const dir = dirname(file);
   mkdirSync(dir, { recursive: true });
@@ -16,11 +9,6 @@ export function writeFileAtomic(file: string, data: string | Uint8Array, mode =
   const fd = openSync(tmp, "wx", mode);
   try {
     try {
-      // write(2) may write FEWER bytes than asked without throwing (ENOSPC mid-
-      // write, signal interruption): loop until done and fail loudly on a stuck
-      // fd, or a truncated temp file gets fsynced and renamed over the target
-      // as a successful-looking corrupt file (closing-review catch - for a
-      // parked credential that silently loses a just-rotated refresh token).
       let offset = 0;
       while (offset < bytes.length) {
         const written = writeSync(fd, bytes, offset);
@@ -33,13 +21,9 @@ export function writeFileAtomic(file: string, data: string | Uint8Array, mode =
     }
     renameSync(tmp, file);
   } catch (e) {
-    // a failed write must not strand the partial temp file - it can hold a
-    // truncated credential (PR #36 review catch) - and a failed CLEANUP must
-    // not mask the write error the caller needs (second-round catch)
     try {
       rmSync(tmp, { force: true });
     } catch {
-      // the original write error below is the one that matters
     }
     throw e;
   }

package/src/lib/claudebin.ts

@@ -1,5 +1,3 @@
-// Resolve the REAL claude binary (never our shim on PATH).
-
 import { existsSync, mkdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { uniq } from "es-toolkit";
@@ -8,23 +6,9 @@ import { paths } from "./paths.ts";
 import { loadConfig } from "./state.ts";
 import { writeFileAtomic } from "./atomic.ts";
 
-/** How many tokenmaxxing wrappers sit above this process. Every supervisor
- *  spawn increments it in the child env; the wrapper refuses to run at the cap,
- *  so ANY claudeBin indirection that leads back to the wrapper (a pinned shim
- *  that re-execs `claude` from PATH) dies in a handful of processes instead of
- *  fork-bombing the machine (2026-07-12: ~1800 runaway bun processes). */
 export const WRAP_DEPTH_ENV = "TOKENMAXXING_WRAP_DEPTH";
 export const MAX_WRAP_DEPTH = 5;
-/** "No session management anywhere below this env": the wrapper passes a
- *  `claude`/`codex` invocation straight through to the real binary, unmanaged.
- *  Set by pooledSpawnEnv so an SDK-driven session's descendants (an agent
- *  running `bun run validate` whose script invokes `claude -p`) still work
- *  instead of dying at the depth cap, which is a LOOP diagnostic, not an
- *  unmanaged-zone marker. Depth keeps incrementing per wrapper entry under
- *  this sentinel, so a poisoned pin inside the zone still aborts at the cap. */
 export const UNMANAGED_ENV = "TOKENMAXXING_UNMANAGED";
-/** Stable fragment of the loop-abort diagnostic; verifyRealClaude greps a
- *  child's stderr for it to name the failure precisely. */
 export const LOOP_DIAGNOSIS = "wrapper re-entered without reaching the real claude";
 
 export function wrapDepth(env: Record<string, string | undefined> = process.env): number {
@@ -32,12 +16,6 @@ export function wrapDepth(env: Record<string, string | undefined> = process.env)
   return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
 }
 
-/** Non-env backstop for the depth sentinel: an env-sanitizing shim in the loop
- *  (env -i / corporate launchers) strips the sentinel every cycle, so the
- *  wrapper ALSO counts its own entries in an on-disk sliding window that no
- *  child environment can erase. A self-spawn loop sustains several entries per
- *  second indefinitely; legitimate bursts (a tmux session restore launching
- *  dozens of panes) land once and go quiet, staying far under the cap. */
 export const WRAP_RATE_MAX = 60;
 export const WRAP_RATE_WINDOW_MS = 30_000;
 const SpawnRateSchema = z.object({ entries: z.array(z.number()) });
@@ -47,13 +25,13 @@ export function wrapperEntryRateTripped(now: number): boolean {
   let entries: number[] = [];
   try {
     entries = SpawnRateSchema.parse(JSON.parse(readFileSync(file, "utf8"))).entries;
-  } catch { /* absent or corrupt - start a fresh window */ }
+  } catch {  }
   entries = entries.filter((t) => now - t < WRAP_RATE_WINDOW_MS);
   entries.push(now);
   try {
     mkdirSync(paths.home, { recursive: true });
     writeFileAtomic(file, JSON.stringify({ entries }));
-  } catch { /* an unwritable home must never block launching claude */ }
+  } catch {  }
   return entries.length > WRAP_RATE_MAX;
 }
 
@@ -65,21 +43,12 @@ function realpathOrNull(p: string): string | null {
   }
 }
 
-/** True when `bin` IS tokenmaxxing (the `claude` wrapper, the `xx` alias, or the
- *  installed binary, via any symlink): spawning it as claude recurses through
- *  the supervisor. Realpath-based - a trailing slash, a symlinked dir, or a
- *  symlink to the wrapper must not defeat it the way the old exact-string
- *  binDir compare could. */
 export function pointsBackAtUs(bin: string): boolean {
   const resolved = realpathOrNull(bin);
   const binDir = realpathOrNull(paths.binDir);
   return resolved != null && binDir != null && dirname(resolved) === binDir;
 }
 
-/** Every PATH `claude` that is not us, in PATH order, deduped by realpath.
- *  All of them, not just the first: a user-made wrapper script named claude can
- *  sit ahead of the real binary, and verified resolution must be able to walk
- *  past it. */
 function scanPathForClaudeCandidates(): string[] {
   const seen = new Set<string>();
   const out: string[] = [];
@@ -94,12 +63,11 @@ function scanPathForClaudeCandidates(): string[] {
           out.push(cand);
         }
       }
-    } catch { /* ignore */ }
+    } catch {  }
   }
   return out;
 }
 
-/** First PATH entry with a `claude` that is not us. null when PATH has none. */
 export function scanPathForClaude(): string | null {
   return scanPathForClaudeCandidates()[0] ?? null;
 }
@@ -107,14 +75,9 @@ export function scanPathForClaude(): string | null {
 export function resolveRealClaude(): string {
   const cfg = loadConfig();
   if (cfg.claudeBin) {
-    // A configured-but-vanished binary must not silently degrade to the PATH
-    // scan: under a relocated TOKENMAXXING_HOME the scan's binDir guard misses
-    // the installed wrapper, which then recurses through the supervisor
-    // (observed 2026-07-12 as a forever-hung `/usage` probe).
     if (!existsSync(cfg.claudeBin)) {
       throw new Error(`configured claudeBin does not exist: ${cfg.claudeBin} - fix config.json`);
     }
-    // A pin that leads back to us is the recursion incident, not a claude.
     if (pointsBackAtUs(cfg.claudeBin)) {
       throw new Error(
         `configured claudeBin (${cfg.claudeBin}) is tokenmaxxing's own wrapper - spawning it recurses. Point claudeBin at the real claude binary in ${paths.configJson}`,
@@ -127,18 +90,10 @@ export function resolveRealClaude(): string {
   throw new Error("could not locate the real `claude` binary (set claudeBin in config.json)");
 }
 
-/** Behavioral check used by init/doctor before trusting a pin: the binary must
- *  answer `--version` without re-entering this wrapper. Depth is preset to the
- *  cap so an indirection back into us aborts on its FIRST wrapper entry instead
- *  of recursing. Returns null when the binary passes, else the failure detail. */
 export function verifyRealClaude(bin: string): string | null {
   const env = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH), TOKENMAXXING_PROBE: "1" };
   let p: ReturnType<typeof Bun.spawnSync>;
   try {
-    // spawnSync throws on an unrunnable path (ENOENT/EACCES) - that is a
-    // verification failure to report, not a crash. SIGKILL: a TERM-trapping
-    // candidate must not hang the very repair commands (init/doctor) that the
-    // loop-abort diagnostic points the user at.
     p = Bun.spawnSync([bin, "--version"], { env, stdout: "pipe", stderr: "pipe", timeout: 15_000, killSignal: "SIGKILL" });
   } catch (e) {
     return e instanceof Error ? e.message : String(e);
@@ -146,8 +101,6 @@ export function verifyRealClaude(bin: string): string | null {
   const outText = (p.stdout?.toString() ?? "").trim();
   const err = (p.stderr?.toString() ?? "").trim();
   if (p.exitCode === 0) {
-    // exit 0 only proves something ran; the output must identify as claude
-    // ("2.1.207 (Claude Code)" on 2.1.207) or the pin is some other program.
     if (/claude/i.test(outText)) return null;
     return `--version output does not identify claude: "${outText.slice(0, 80)}"`;
   }
@@ -155,15 +108,11 @@ export function verifyRealClaude(bin: string): string | null {
   return `--version exited ${p.exitCode ?? "on signal/timeout"}: ${(err || outText).slice(0, 160)}`;
 }
 
-/** Resolution for `init`'s pin: resolve, then behaviorally verify. A configured
- *  bin that fails verification (e.g. a shim pinned by an old version) falls back
- *  to the PATH scan, and the scan walks past failing candidates (a user-made
- *  claude wrapper ahead of the real binary) instead of giving up on the first. */
 export function resolveVerifiedClaude(): string {
   const candidates: string[] = [];
   try {
     candidates.push(resolveRealClaude());
-  } catch { /* broken config - the scan below is init's repair path */ }
+  } catch {  }
   candidates.push(...scanPathForClaudeCandidates());
 
   const failures: string[] = [];