tokenmaxxing 1.8.0 → 1.9.0

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";
@@ -25,28 +13,10 @@ import { loadConfig } from "../lib/state.ts";
 import { effectiveBars } from "../lib/picker.ts";
 import { CODEX_SUPERVISOR_ID_ENV } from "./codexsupervisor.ts";
 import { CodexReconcileMarkerSchema, CodexRespawnMarkerSchema, CodexStopStdinSchema, type CodexAccount } from "../lib/types.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 { 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;
@@ -55,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"));
@@ -64,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 });
@@ -85,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();
@@ -104,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;
   }
@@ -128,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 {
@@ -141,28 +92,11 @@ export async function handleCodexStop(input: { rawStdin: string }): Promise<void
   const sessionId = parsed.success ? (parsed.data.session_id ?? null) : null;
 
   try {
-    // Additive relay turn-done marker (never writes into respawn/).
-    const relaySid = process.env[RELAY_SESSION_ENV];
-    if (relaySid != null && registryHas({ sessionId: relaySid })) {
-      writeTurnDoneMarker({ sessionId: relaySid, source: "codex-stop" });
-      log("codexstop.relay_turn_done", { session: relaySid.slice(0, 8) });
-    }
-
-    // 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) {
@@ -176,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) });
@@ -191,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) {

package/src/entries/statusline.ts

@@ -1,22 +1,3 @@
-// Native statusLine. Reads Claude's statusLine stdin, tees the rate-limit data
-// to usage.json (write-on-change, O(ms)), then renders ONE line:
-//   worktree name (linked worktrees only), model name painted by context fill
-//   (effort in parens), +added/-removed, then quota as COLOR (user decisions
-//   2026-07-18): each window is its time-to-reset painted on a continuous
-//   green->yellow->red ramp by used% - "◆ 𝒇 2h 1d  ◇ 2d  ◇ full" - the
-//   active account's windows after a green ◆ (per-model by bare initial
-//   first, fable as 𝒇, other families uppercased; "𝒇?" unpainted when the
-//   cap applies but is unmeasured, then session/5h, then week), then EVERY
-//   parked account's week after its own cyan ◇ (red ✗ if needs-reauth),
-//   sorted by earliest upcoming reset (needs-reauth last). A window with no
-//   upcoming reset renders "0" (empty again); measured usage with an unknown
-//   reset clock renders a painted "?". With color disabled the numeric format
-//   returns ("2h5" = resets in 2h, 5 used; "ctx 42"): without color a drained
-//   window must not look fresh. Blocks are joined by TWO spaces, tokens
-//   within a block by one. Per-model resets are omitted (they match the
-//   weekly reset).
-// Must NEVER break the status line: render what parses, skip what doesn't.
-
 import { sortBy } from "es-toolkit";
 import { z } from "zod";
 import { readOAuthAccount } from "../lib/claudejson.ts";
@@ -36,27 +17,16 @@ import {
   type UsageWindow,
 } from "../lib/types.ts";
 
-/** A session that hasn't adopted a fresh swap yet (<=30s keychain cache) pushes
- *  the OLD account's windows while ~/.claude.json already names the NEW org.
- *  Suppress the tee for this long after a swap so that mislabel never lands. */
 const ADOPTION_GRACE_MS = 45_000;
 
 const RenderCtxSchema = z.object({
   accounts: AccountsIndexSchema,
-  /** active account's per-model weekly windows ({} unless fresh for the live org). */
   perModel: z.record(z.string(), UsageWindowSchema),
-  /** families (lowercased) whose per-model weekly cap gates a switch. */
   switchModels: z.array(z.string()),
-  /** linked-worktree basename, null in a main checkout. */
   worktree: z.string().nullable(),
-  /** the LIVE login's org from claude.json, the seat's identity - the
-   *  activeAccountUuid label drifts after a manual /login (the same rule as
-   *  decide.ts's seatOf; closing-review catch: the label-keyed split rendered
-   *  the live account twice and hid the stale-labeled one). */
   liveOrg: z.string().nullable(),
   now: z.number(),
   color: z.boolean(),
-  /** terminal advertises 24-bit color (COLORTERM); false steps the ramp to the 256-color cube. */
   truecolor: z.boolean(),
 });
 export type RenderCtx = z.infer<typeof RenderCtxSchema>;
@@ -67,22 +37,17 @@ export async function readStdin(): Promise<string> {
   return Buffer.concat(chunks).toString("utf8");
 }
 
-/** Pure renderer: statusLine stdin + tokenmaxxing state → the emitted line. */
 export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
   const col = makeColors(ctx.color);
   const paint = makeUsagePaint({ enabled: ctx.color, truecolor: ctx.truecolor });
-  // Used quota in a window; one whose reset has passed is empty again.
   const used = (w: UsageWindow) => (w.resetsAt != null && w.resetsAt <= ctx.now ? 0 : w.usedPercentage);
   const reset = (epochMs: number | null) => fmtResetShort(epochMs, ctx.now);
 
   const parsed = StatusLineStdinSchema.safeParse(stdinObj);
   const d = parsed.success ? parsed.data : null;
 
-  // ---- info block: worktree, model, ctx, diff
   const info: string[] = [];
   if (ctx.worktree != null) info.push(ctx.worktree);
-  // The model name carries the context-fill color (user rule 2026-07-18, no
-  // ctx token); colorless mode keeps the numeric ctx token instead.
   const modelName = d?.model?.display_name ?? d?.model?.id;
   const ctxUsed = d?.context_window?.used_percentage;
   if (modelName) {
@@ -93,26 +58,17 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
   if (!ctx.color && ctxUsed != null) info.push(`ctx ${Math.round(ctxUsed)}`);
   const added = d?.cost?.total_lines_added ?? 0;
   const removed = d?.cost?.total_lines_removed ?? 0;
-  // -removed stays unpainted: red means quota alarm and nothing else.
   if (added > 0 || removed > 0) info.push(`${col.green(`+${added}`)}/-${removed}`);
 
-  // ---- active account block
-  // A window token: color carries the used%, the text is the reset countdown
-  // (or the bare per-model initial - per-model resets are omitted). "0" = no
-  // upcoming reset (the window is empty again); a painted "?" = measured usage
-  // whose reset clock is unknown. Colorless mode glues the number back on.
   const seg = (label: string, w: UsageWindow, resetAt: number | null) => {
     const u = used(w);
     if (!ctx.color) return `${label}${reset(resetAt)}${Math.round(u)}`;
     const body = label !== "" ? label : reset(resetAt);
     return col.bold(paint(u)(body !== "" ? body : u > 0 ? "?" : "0"));
   };
-  // Per-model initial: fable renders 𝒇 (user rule 2026-07-18), family-matched
-  // as always; other families keep their uppercased first letter.
   const initial = (name: string) => (familyTokens(name).includes("fable") ? "𝒇" : name.slice(0, 1).toUpperCase());
   const wins = parseStatusLineStdin(stdinObj);
   const windows: string[] = [];
-  // A capacity-constrained model whose cap is unmeasured must not look safe.
   const family = matchedFamily(parseStatusLineModel(stdinObj), ctx.switchModels);
   if (family && !Object.keys(ctx.perModel).some((k) => familyTokens(k).includes(family))) {
     windows.push(`${initial(family)}?`);
@@ -122,7 +78,6 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
     windows.push(seg("", wins.fiveHour, wins.fiveHour.resetsAt));
     windows.push(seg("", wins.sevenDay, wins.sevenDay.resetsAt));
   }
-  // The seat: live-org first, stored label fallback (unknown live identity).
   const seatUuid =
     (ctx.liveOrg != null ? ctx.accounts.accounts.find((a) => a.organizationUuid === ctx.liveOrg)?.accountUuid : undefined) ??
     ctx.accounts.activeAccountUuid;
@@ -133,13 +88,10 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
         ? `${col.green("◆")} ?`
         : "";
 
-  // ---- parked accounts, earliest upcoming reset first (needs-reauth last)
   const parked = sortBy(
     ctx.accounts.accounts.filter((a) => a.accountUuid !== seatUuid),
     [(a) => (a.needsReauth ? 1 : 0), (a) => earliestReset(a, ctx.now)],
   );
-  // Every parked account renders its own marker (user rule 2026-07-18: the
-  // old counted collapse "◇ 3 full" hid the pool size and read as confusing).
   const poolSeg = (a: Account): string => {
     const marker = a.needsReauth ? col.red("✗") : col.cyan("◇");
     const week = a.lastUsage?.sevenDay;
@@ -148,7 +100,6 @@ export function renderStatusline(stdinObj: unknown, ctx: RenderCtx): string {
     if (Math.round(weekUsed) <= 0) return `${marker} ${paint(0)("full")}`;
 
     const parts: string[] = [];
-    // A per-model weekly cap with more used than the aggregate is the binding constraint - surface it.
     for (const [name, w] of Object.entries(a.lastPerModel ?? {})) {
       if (used(w) > weekUsed) parts.push(seg(initial(name), w, null));
     }
@@ -166,25 +117,11 @@ export async function runStatusline(): Promise<number> {
   try {
     obj = JSON.parse(raw);
   } catch {
-    // malformed stdin - render from state alone
   }
   const now = Date.now();
 
-  // The stdin payload's own org label: those rate_limits and that
-  // organizationUuid ride the SAME API response, so the label can never lie
-  // about whose windows these are. claude.json's org is only the fallback -
-  // it flips at the swap while a session that has made no post-swap request
-  // keeps rendering the OLD account's windows indefinitely, and the 45s
-  // ADOPTION_GRACE_MS bounds nothing for such a session (closing-review
-  // catch: a stale-window tee labeled with the new org could hard-swap a
-  // healthy account and stamp foreign usage into it). The render below uses
-  // the same preference so the active ◆ seat matches the windows painted
-  // beside it (PR #36 review catch). Trusted ONLY when the payload's windows
-  // parsed too: an org label without windows would re-label state the payload
-  // did not carry (second-round catch).
   let stdinOrg: string | null = null;
 
-  // tee usage for the Stop hook / status - best effort, never blocks rendering.
   let org: string | null = null;
   try {
     org = readOAuthAccount()?.organizationUuid ?? null;
@@ -197,7 +134,6 @@ export async function runStatusline(): Promise<number> {
       writeUsage(state);
     }
   } catch {
-    // skip the tee, still render below
   }
 
   let line: string;
@@ -219,8 +155,6 @@ export async function runStatusline(): Promise<number> {
     };
     line = renderStatusline(obj, ctx);
   } catch (e) {
-    // Corrupt local state (the loaders throw on it) must stay VISIBLE: render
-    // the failure as the statusline itself, never abort into a blank line.
     line = `tokenmaxxing: ${e instanceof Error ? e.message : String(e)}`;
   }
   process.stdout.write(line + "\n");

package/src/entries/stopfailurehook.ts

@@ -0,0 +1,93 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { paths } from "../lib/paths.ts";
+import { writeFileAtomic } from "../lib/atomic.ts";
+import { readOAuthAccount } from "../lib/claudejson.ts";
+import { enforcedWindowMs, evaluateAndMaybeSwap, postSwapProof, recordEnforcedLimit } from "../lib/decide.ts";
+import { loadConfig, loadLastSwapAt } from "../lib/state.ts";
+import { classifyEnforcedLimit, findEnforcedRow, parseErrorBody, readTranscriptTail } from "../lib/usage.ts";
+import { RespawnMarkerSchema, type EnforcedLimit } from "../lib/types.ts";
+import { log } from "../lib/log.ts";
+
+export const RETRIGGER_PROMPT = "Continue where the previous turn left off; it was interrupted by a usage limit and tokenmaxxing switched accounts.";
+
+const StopFailureStdin = z.looseObject({
+  session_id: z.uuid().optional().catch(undefined),
+  transcript_path: z.string().optional().catch(undefined),
+  error: z.string().optional().catch(undefined),
+  agent_id: z.string().optional().catch(undefined),
+  last_assistant_message: z.string().optional().catch(undefined),
+});
+
+const LaunchedAtSchema = z.coerce.number().finite().optional().catch(undefined);
+
+async function readStdin(): Promise<string> {
+  const chunks: Uint8Array[] = [];
+  for await (const c of Bun.stdin.stream()) chunks.push(c);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runStopFailureHook(): Promise<number> {
+  if (process.env.TOKENMAXXING_PROBE) return 0;
+
+  const org = readOAuthAccount()?.organizationUuid ?? null;
+  const now = Date.now();
+  const raw = await readStdin();
+  const parsed = StopFailureStdin.safeParse((() => { try { return JSON.parse(raw); } catch { return {}; } })());
+  const stdin = parsed.success ? parsed.data : {};
+  if (stdin.error !== undefined && stdin.error !== "rate_limit") return 0;
+
+  const stdinSid = stdin.session_id;
+  const pinnedSid = process.env.TOKENMAXXING_SESSION_ID;
+  const launchedAt = LaunchedAtSchema.parse(process.env.TOKENMAXXING_LAUNCHED_AT) ?? null;
+  const mainLoop = stdin.agent_id === undefined;
+  const canPause = process.env.TOKENMAXXING_SUPERVISED === "1" && pinnedSid != null && mainLoop;
+
+  try {
+    const cfg = loadConfig();
+    const found = stdin.transcript_path
+      ? findEnforcedRow({ rows: readTranscriptTail(stdin.transcript_path), lastAssistantMessage: stdin.last_assistant_message, now })
+      : null;
+    const limit = found ? classifyEnforcedLimit(found.row, cfg.policy.switchModels) : null;
+
+    let enforced: EnforcedLimit | null = null;
+    if (limit && found && org) {
+      if (postSwapProof({ swapAt: loadLastSwapAt(), launchedAt, errorAt: found.errorAt, now })) {
+        const stamp = await recordEnforcedLimit({ limit, org, now });
+        log("stopfailure.enforced", { kind: limit.kind, family: limit.kind === "model" ? limit.family : undefined, outcome: stamp.outcome, resetsAt: stamp.resetsAt, subagent: !mainLoop });
+        if (stamp.outcome !== "org-moved") {
+          enforced = { org, family: limit.kind === "model" ? limit.family : null, resetsAt: stamp.resetsAt, windowMs: enforcedWindowMs(limit) };
+        }
+      } else {
+        log("stopfailure.unproven", { kind: limit.kind });
+      }
+    } else {
+      log("stopfailure.unclassified", {
+        row: found != null,
+        type: found?.row.quotaLimits?.rateLimitType,
+        transient: found?.row.apiErrorIsTransient,
+        body: found ? parseErrorBody(found.row.errorDetails)?.error?.type : undefined,
+      });
+    }
+
+    const decision = await evaluateAndMaybeSwap(now, canPause && enforced != null, enforced);
+    if (enforced && canPause && pinnedSid && decision.account && (decision.swapped || decision.waitUntil !== undefined)) {
+      const marker = join(paths.respawnDir, pinnedSid);
+      const payload = RespawnMarkerSchema.parse({
+        account: decision.account.label,
+        ts: Date.now(),
+        waitUntil: decision.waitUntil ?? now,
+        sessionId: stdinSid ?? pinnedSid,
+        prompt: RETRIGGER_PROMPT,
+        ...(launchedAt != null ? { launchedAt } : {}),
+      });
+      writeFileAtomic(marker, JSON.stringify(payload));
+      log("stopfailure.marker", { session: (stdinSid ?? pinnedSid).slice(0, 8), account: decision.account.accountUuid.slice(0, 8), waitUntil: payload.waitUntil });
+    } else {
+      log("stopfailure.decision", { reason: decision.reason, swapped: decision.swapped, account: decision.account?.accountUuid.slice(0, 8), waitUntil: decision.waitUntil });
+    }
+  } catch (e) {
+    log("stopfailure.error", { err: e instanceof Error ? e.message : String(e) });
+  }
+  return 0;
+}