tokenmaxxing 1.8.0 → 1.9.0

package/src/lib/usage.ts

@@ -1,22 +1,12 @@
-// Usage data from two sources: statusLine stdin (pushed every turn, aggregate
-// windows only, epoch resets) and `claude -p '/usage'` (free, 0 tokens, all
-// three limit kinds). `/usage` is a client-side command that renders the same
-// figures claude's own usage screen shows; we run it in a throwaway
-// CLAUDE_CONFIG_DIR to sample a parked account without disturbing the live login.
-
-import { mkdirSync } from "node:fs";
+import { closeSync, fstatSync, mkdirSync, openSync, readSync } from "node:fs";
 import { join } from "node:path";
 import { delay } from "es-toolkit";
 import { z } from "zod";
 import { MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, resolveRealClaude } from "./claudebin.ts";
-import { readOAuthAccount } from "./claudejson.ts";
-import { withLock } from "./lock.ts";
 import { log } from "./log.ts";
 import { paths } from "./paths.ts";
-import { loadUsage, writeUsage } from "./state.ts";
 import { RateLimitsStdinSchema, UsageWindowSchema, type ModelInfo, type UsageWindow, type UsageWindows } from "./types.ts";
 
-/** Normalize a resets_at value (epoch s, epoch ms, or ISO string) to epoch ms. */
 export function normalizeResetsAt(v: unknown): number | null {
   const num = z.number().finite().safeParse(v);
   if (num.success) {
@@ -37,9 +27,6 @@ const win = (w: { used_percentage: number; resets_at?: number | null }): UsageWi
   resetsAt: normalizeResetsAt(w.resets_at),
 });
 
-/** Extract the two AGGREGATE windows from statusLine stdin. null if absent.
- *  All-or-nothing on the aggregates (mirrors the /usage parser): fabricating
- *  0% for a missing window would make unmeasured read as safe. */
 export function parseStatusLineStdin(obj: unknown): UsageWindows | null {
   const parsed = RateLimitsStdinSchema.safeParse(obj);
   if (!parsed.success) return null;
@@ -48,7 +35,6 @@ export function parseStatusLineStdin(obj: unknown): UsageWindows | null {
   return { fiveHour: win(rl.five_hour), sevenDay: win(rl.seven_day) };
 }
 
-/** Extract the active model from statusLine stdin. null if absent. */
 export function parseStatusLineModel(obj: unknown): ModelInfo | null {
   const parsed = RateLimitsStdinSchema.safeParse(obj);
   if (!parsed.success) return null;
@@ -57,31 +43,16 @@ export function parseStatusLineModel(obj: unknown): ModelInfo | null {
   return { id: m?.id ?? m?.display_name ?? "", display: m?.display_name ?? m?.id ?? "" };
 }
 
-/** Lowercased word tokens of a model id or display string: "claude-opus-4-8" /
- *  "Opus 4.8" -> ["claude","opus","4","8"] / ["opus","4","8"]. Model naming
- *  drifts per release ("Fable" became "Fable 5" in 2.1.206, and id grammar has
- *  historically flipped between family-first and version-first), so gates match
- *  a family token anywhere instead of an exact string - an exact-string gate
- *  silently disabled the per-model check in the 2026-07-09/10 incidents. */
 export function familyTokens(s: string): string[] {
   return s.trim().toLowerCase().split(/[\s.-]+/).filter((t) => t.length > 0);
 }
 
-/** The switchModels family the active model belongs to, from its id OR display
- *  tokens; null when the model is not capacity-constrained. */
 export function matchedFamily(model: ModelInfo | null, families: string[]): string | null {
   if (!model) return null;
   const tokens = new Set([...familyTokens(model.id), ...familyTokens(model.display)]);
   return families.find((f) => tokens.has(f)) ?? null;
 }
 
-/** Families whose per-model weekly cap gates a switch, given the active model:
- *  the model's own family when it is capacity-constrained, none when it is a
- *  known-unconstrained model, and EVERY configured family when the model is
- *  unknown. The unknown case matters on headless boxes: a swap clears the
- *  snapshots and only an actively-rendering statusLine restores the model, so
- *  the periodic check ran model-blind for hours while the active account sat at
- *  its Fable cap (the 2026-07-12 ARM-box incident). */
 export function gatedFamilies(model: ModelInfo | null, families: string[]): string[] {
   if (!model) return families;
   const family = matchedFamily(model, families);
@@ -95,13 +66,10 @@ export const FullUsageSchema = z.object({
 });
 export type FullUsage = z.infer<typeof FullUsageSchema>;
 
-// ---- `/usage` text parsing -----------------------------------------------
-
 const MONTHS: Record<string, number> = {
   jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11,
 };
 
-/** The tz offset (wall-clock minus UTC, in ms) in `tz` at instant `utcMs`. */
 function tzOffsetMs(utcMs: number, tz: string): number {
   const parts = new Intl.DateTimeFormat("en-US", {
     timeZone: tz,
@@ -115,7 +83,6 @@ function tzOffsetMs(utcMs: number, tz: string): number {
   return asUTC - utcMs;
 }
 
-/** Interpret a wall-clock time in `tz` as an epoch (DST-correct via one refine). */
 function zonedWallToEpoch(y: number, mon: number, day: number, hour: number, min: number, tz: string): number {
   const guess = Date.UTC(y, mon, day, hour, min);
   const off1 = tzOffsetMs(guess, tz);
@@ -123,16 +90,6 @@ function zonedWallToEpoch(y: number, mon: number, day: number, hour: number, min
   return guess - off2;
 }
 
-/**
- * Parse a `/usage` reset clock like `Jul 11 at 12pm (Asia/Seoul)` or
- * `Jul 10, 3:30pm (Asia/Seoul)` to epoch ms. The day-time glue is not stable
- * across claude installs (observed on 2.1.206: ` at ` on macOS, `, ` on Linux);
- * exactly those two glues are accepted, same-line only, so a third drift shows
- * up as an unparsed clock (and the usage.reset_clock_unparsed log) instead of a
- * guessed instant. The text carries no year, so we pick the year whose resulting
- * instant is nearest `now` (resets are always days away, so the correct year
- * wins by ~360 days). Returns null if unparseable.
- */
 export function parseResetClock(clock: string, now = Date.now()): number | null {
   const m = clock.match(/\b([A-Za-z]{3,9})\s+(\d{1,2})(?:[^\S\n]+at[^\S\n]+|,[^\S\n]*)(\d{1,2})(?::(\d{2}))?\s*([ap])m\s*\(([^)]+)\)/i);
   if (!m) return null;
@@ -151,19 +108,13 @@ export function parseResetClock(clock: string, now = Date.now()): number | null
     try {
       epoch = zonedWallToEpoch(y, mon, day, hour, min, tz);
     } catch {
-      return null; // invalid tz
+      return null;
     }
     if (best === null || Math.abs(epoch - now) < Math.abs(best - now)) best = epoch;
   }
   return best;
 }
 
-/** Compact time-until-reset: the largest unit only ("6d", "2h", "45m"),
- *  floored to "1m" so a live window never reads as zero, and "" once the reset
- *  has passed (the window is simply empty again). Non-empty output always ends
- *  in a unit letter, so the statusLine's digit-leading used-percent glued
- *  after it stays parseable. Lives here (not cli/render.ts) so headless lib
- *  consumers stay off the terminal-rendering module. */
 export function fmtResetShort(epochMs: number | null | undefined, now = Date.now()): string {
   if (epochMs == null) return "";
   const dsec = Math.round((epochMs - now) / 1000);
@@ -176,99 +127,120 @@ export function fmtResetShort(epochMs: number | null | undefined, now = Date.now
   return `${Math.max(m, 1)}m`;
 }
 
-/** The reset epoch a limit result announces ("Claude AI usage limit
- *  reached|<epoch>", 10-digit seconds or 13-digit ms). Structural scan, no
- *  regex: everything after the pipe up to the first non-digit. Null when the
- *  text is a phrase-only limit with no epoch. */
-export function parseUsageLimitEpoch(input: { text: string }): number | null {
-  const marker = "usage limit reached|";
-  const at = input.text.toLowerCase().indexOf(marker);
+const TranscriptBlockSchema = z.looseObject({ type: z.string().optional(), text: z.string().optional() });
+export const TranscriptRowSchema = z.looseObject({
+  type: z.string().optional(),
+  timestamp: z.string().optional(),
+  isApiErrorMessage: z.boolean().optional(),
+  apiErrorIsTransient: z.boolean().optional(),
+  error: z.string().optional(),
+  errorDetails: z.string().optional(),
+  quotaLimits: z.looseObject({ rateLimitType: z.string().optional(), resetsAt: z.number().optional() }).optional(),
+  message: z.looseObject({ content: z.unknown().optional() }).optional(),
+});
+export type TranscriptRow = z.infer<typeof TranscriptRowSchema>;
+
+const TRANSCRIPT_TAIL_BYTES = 256 * 1024;
+
+export function readTranscriptTail(path: string, maxBytes = TRANSCRIPT_TAIL_BYTES): TranscriptRow[] {
+  let text: string;
+  try {
+    const fd = openSync(path, "r");
+    try {
+      const size = fstatSync(fd).size;
+      const start = Math.max(0, size - maxBytes);
+      const buf = Buffer.alloc(size - start);
+      readSync(fd, buf, 0, buf.length, start);
+      text = buf.toString("utf8");
+      if (start > 0) text = text.slice(text.indexOf("\n") + 1);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    return [];
+  }
+  const rows: TranscriptRow[] = [];
+  for (const line of text.split("\n")) {
+    if (line.trim() === "") continue;
+    try {
+      const parsed = TranscriptRowSchema.safeParse(JSON.parse(line));
+      if (parsed.success) rows.push(parsed.data);
+    } catch {}
+  }
+  return rows;
+}
+
+export function transcriptRowText(row: TranscriptRow): string {
+  const blocks = z.array(TranscriptBlockSchema).safeParse(row.message?.content);
+  if (!blocks.success) return "";
+  return blocks.data.filter((b) => b.type === "text").map((b) => b.text ?? "").join("\n").trim();
+}
+
+const ROW_RECENCY_MS = 60_000;
+
+const EnforcedRowSchema = z.object({
+  row: TranscriptRowSchema,
+  errorAt: z.number().nullable(),
+});
+export type EnforcedRow = z.infer<typeof EnforcedRowSchema>;
+
+export function findEnforcedRow(input: { rows: TranscriptRow[]; lastAssistantMessage: string | undefined; now: number }): EnforcedRow | null {
+  const { rows, lastAssistantMessage, now } = input;
+  for (let i = rows.length - 1; i >= 0; i--) {
+    const row = rows[i]!;
+    if (row.isApiErrorMessage !== true || row.error !== "rate_limit") continue;
+    const ts = row.timestamp ? Date.parse(row.timestamp) : Number.NaN;
+    const byContent = lastAssistantMessage != null && lastAssistantMessage !== "" && transcriptRowText(row) === lastAssistantMessage;
+    const byRecency = Number.isFinite(ts) && Math.abs(now - ts) <= ROW_RECENCY_MS;
+    if (!byContent && !byRecency) continue;
+    return { row, errorAt: Number.isFinite(ts) ? ts : null };
+  }
+  return null;
+}
+
+export const EnforcedClassSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("session"), resetsAt: z.number().nullable() }),
+  z.object({ kind: z.literal("weekly"), resetsAt: z.number().nullable() }),
+  z.object({ kind: z.literal("model"), family: z.string(), resetsAt: z.number().nullable() }),
+]);
+export type EnforcedClass = z.infer<typeof EnforcedClassSchema>;
+
+const ErrorBodySchema = z.looseObject({
+  error: z.looseObject({ type: z.string().optional(), details: z.looseObject({ error_code: z.string().optional() }).optional() }).optional(),
+});
+
+const CREDITS_GATED_FAMILIES = ["fable"];
+
+export function parseErrorBody(errorDetails: string | undefined): z.infer<typeof ErrorBodySchema> | null {
+  if (!errorDetails) return null;
+  const at = errorDetails.indexOf("{");
   if (at < 0) return null;
-  let digits = "";
-  for (const ch of input.text.slice(at + marker.length)) {
-    if (ch < "0" || ch > "9") break;
-    digits += ch;
+  try {
+    const body = ErrorBodySchema.safeParse(JSON.parse(errorDetails.slice(at)));
+    return body.success ? body.data : null;
+  } catch {
+    return null;
   }
-  // exactly the two real encodings: 10-digit seconds or 13-digit ms. An 11-
-  // or 12-digit run is malformed and must stay an unknown reset, not become
-  // a far-future one via the seconds branch.
-  if (digits.length !== 10 && digits.length !== 13) return null;
-  const n = Number(digits);
-  return digits.length === 13 ? n : n * 1000;
 }
 
-/**
- * Persist a limit observed in a turn RESULT into usage.json so the next
- * decision sees the depleted account immediately. Callers without a statusLine
- * tee (headless Agent SDK integrations) should invoke this on errored limit
- * results: `loadFreshSnapshots` skips re-probing inside the poll TTL and
- * `/usage` is fail-silent against the just-limited active token, so without
- * this write a post-limit retry re-decides off the stale pre-limit snapshot
- * and respawns the same depleted account. The session
- * window is stamped 100% with the announced reset: whichever window actually
- * tripped, the account is unusable until then, and the hard path swaps away.
- * `org` is the identity captured AT THE SPAWN BOUNDARY of the turn that
- * failed; the write happens only when that identity is known and still live,
- * so a concurrent thread's mid-turn swap can never get its fresh account
- * stamped depleted by this turn's failure (review catch, PR #18). Without a
- * same-org prior snapshot there is nothing safe to write (a synthetic weekly
- * value would flow into `account.lastUsage` and poison the picker's ranking;
- * unmeasured must not look fresh), so the observation is dropped and the
- * retry stays merely bounded.
- *
- * INTENTIONAL TRADEOFF (closing-review critic gap, 2026-07-20): the statusline
- * tee (writeUsage) is deliberately UNLOCKED - the shim stays off flock/oauth -
- * so it can interleave with this locked check-then-write. Last-writer-wins is
- * semantically safe in both orderings: a tee landing after this stamp replaces
- * it with a FRESHER live measurement (truth wins), and this stamp landing
- * after a tee replaces pre-limit figures with the observed limit the server
- * just enforced (also truth). Neither writer can write a stale fabrication
- * over the other; locking the shim to close the interleave would buy nothing.
- */
-export async function recordObservedLimit(input: { text: string; now: number; org: string | null }): Promise<void> {
-  if (!input.org) return;
-  // the whole check-then-write runs under the swap flock: a concurrent
-  // performSwap clears the snapshots and flips the live org, and a stale
-  // depleted write must not land for the wrong org right after that
-  // (review catch, PR #18).
-  await withLock(paths.lockFile, () => {
-    const live = readOAuthAccount()?.organizationUuid ?? null;
-    if (live !== input.org) return;
-    const prior = loadUsage();
-    if (!prior || prior.org !== input.org) return;
-    const resetsAt = parseUsageLimitEpoch({ text: input.text });
-    // a weekly-phrased limit exhausts the WEEKLY window: stamping only the 5h
-    // window would let the picker re-seat this account in 5h while the weekly
-    // cap stays dead for days (review catch, PR #18). Unknown-reset blocked
-    // windows self-bound at the window's own duration either way.
-    const weekly = input.text.toLowerCase().includes("weekly");
-    writeUsage({
-      fiveHour: weekly ? prior.fiveHour : { usedPercentage: 100, resetsAt },
-      sevenDay: weekly ? { usedPercentage: 100, resetsAt } : prior.sevenDay,
-      org: input.org,
-      ts: input.now,
-      model: prior.model,
-    });
-    log("usage.observed_limit", { resetsAt, weekly });
-  });
+export function classifyEnforcedLimit(row: TranscriptRow, switchModels: string[]): EnforcedClass | null {
+  const q = row.quotaLimits;
+  if (q) {
+    const resetsAt = q.resetsAt != null ? normalizeResetsAt(q.resetsAt) : null;
+    const type = q.rateLimitType ?? "";
+    if (type === "five_hour") return { kind: "session", resetsAt };
+    if (type === "seven_day") return { kind: "weekly", resetsAt };
+    const family = switchModels.find((f) => type.includes(f));
+    return family ? { kind: "model", family, resetsAt } : null;
+  }
+  if (row.apiErrorIsTransient === true) return null;
+  if (parseErrorBody(row.errorDetails)?.error?.type !== "rate_limit_error") return null;
+  const family = switchModels.find((f) => CREDITS_GATED_FAMILIES.includes(f));
+  return family ? { kind: "model", family, resetsAt: null } : null;
 }
 
-/**
- * Parse `claude -p '/usage'` .result text into all three limit kinds:
- *   Current session: N% used ... resets <clock>        → session (5h)
- *   Current week (all models): N% used ... resets ...  → weekAll (7d aggregate)
- *   Current week (<Model>): N% used ... resets ...     → perModel[<Model>]
- */
 export function parseUsageTextFull(text: string, now = Date.now()): FullUsage | null {
   if (!text) return null;
-  // The reset clock is required in full (month day[, | at ]h[:mm]am/pm (tz))
-  // inside its optional group, so the lazy bridge is forced to find it when
-  // present yet the group cleanly skips a line that has no clock. The bridge
-  // refuses to cross another "Current" so a dateless clock ("resets Jul 8.")
-  // can never steal the NEXT entry's clock or swallow that entry. The day-time
-  // glue is not stable across installs (observed on 2.1.206: ` at ` on macOS,
-  // `, ` on Linux); exactly those two are accepted, same-line only, so a third
-  // drift surfaces in the usage.reset_clock_unparsed log instead of misparsing.
   const re = /current (session|week \(([^)]+)\)):\s*(\d+)\s*%(?:(?:(?!current)[^\n])*?\bresets\s+([A-Z][a-z]{2,8}\s+\d{1,2}(?:[^\S\n]+at[^\S\n]+|,[^\S\n]*)\d{1,2}(?::\d{2})?\s*[ap]m\s*\([^)]+\)))?/gi;
   let session: UsageWindow | null = null;
   let weekAll: UsageWindow | null = null;
@@ -279,23 +251,16 @@ export function parseUsageTextFull(text: string, now = Date.now()): FullUsage |
     else if (/^all models$/i.test(m[2]!.trim())) weekAll = window;
     else perModel[m[2]!.trim()] = window;
   }
-  // All-or-nothing on the aggregates: every captured /usage output shows both
-  // rows, so a missing one is format drift, and fabricating 0% for it would
-  // make an unmeasured window read as safe (the one thing it must never do).
   if (!session || !weekAll) return null;
   return { session, weekAll, perModel };
 }
 
-/** Aggregate windows only (session→5h, week-all→7d), for the cold-start fallback. */
 export function parseUsageText(text: string, now = Date.now()): UsageWindows | null {
   const f = parseUsageTextFull(text, now);
   if (!f) return null;
   return { fiveHour: f.session, sevenDay: f.weekAll };
 }
 
-/** Env-var identity/credential overrides the claude binary honors BEFORE its
- *  keychain lookup (verified 2.1.205). A probe MUST scrub every one of these or
- *  an ambient value silently meters the wrong account. */
 export const CRED_ENV_OVERRIDES = [
   "ANTHROPIC_API_KEY",
   "ANTHROPIC_AUTH_TOKEN",
@@ -307,14 +272,7 @@ export const CRED_ENV_OVERRIDES = [
   "CLAUDE_CODE_USE_VERTEX",
 ] as const;
 
-/** One `claude -p '/usage'` invocation → parsed usage, or null if it produced no
- *  limit lines (claude prints only a local-stats footer when its own usage fetch
- *  errors/throttles) or failed to run. */
-/** A probe child that wedges (auth prompt, dead endpoint) must never block the
- *  Stop/SessionStart hooks or the status flock forever; a healthy `/usage`
- *  answers in seconds. */
 const PROBE_KILL_MS = 60_000;
-/** How long after the child's death to keep waiting for pipe EOF. */
 const PIPE_GRACE_MS = 2_000;
 
 const SpawnResultSchema = z.object({
@@ -324,14 +282,6 @@ const SpawnResultSchema = z.object({
 });
 type SpawnResult = z.infer<typeof SpawnResultSchema>;
 
-/** Spawn one bounded claude invocation (shared by the `/usage` probe and the
- *  `--force` ping). SIGKILL after PROBE_KILL_MS: claude traps SIGTERM, and a
- *  wedged child that survives the kill would keep p.exited pending and re-wedge
- *  the read race. Descendants inherit the output pipes, so EOF can lag the
- *  child's death or never arrive at all - a leaked grandchild holding the pipe
- *  wedged the 2026-07-12 probes forever, defeating the kill guard - so the
- *  reads are bounded by child-exit + grace instead of awaiting EOF
- *  unconditionally. Returns null when the pipes were withheld past the grace. */
 async function spawnClaudeBounded(
   cmd: string[],
   env: Record<string, string>,
@@ -380,33 +330,14 @@ async function probeUsageOnce(env: Record<string, string>, now: number): Promise
   } else {
     const clockLine = text.split("\n").find((l) => /^current /i.test(l) && /\bresets\b/i.test(l));
     if (clockLine && [full.session, full.weekAll, ...Object.values(full.perModel)].every((w) => w.resetsAt === null)) {
-      // Percentages parsed but every reset clock was dropped: the clock format
-      // drifted again. Log the line so the next drift is visible in the log.
       log("usage.reset_clock_unparsed", { sample: clockLine.slice(0, 120) });
     }
   }
   return full;
 }
 
-/** Escalating retry delays for the empty-footer case (usage endpoint throttled
- *  or the sampled token busy). Capped at ~7s of sleep: probeUsage runs inside
- *  Stop/SessionStart hooks and under the status flock, and the periodic `check`
- *  timer re-runs every 3 minutes anyway, owning the long-tail retry. */
 const PROBE_RETRY_DELAYS_MS = [2000, 5000];
 
-/**
- * Run `claude -p '/usage'` (free, 0 tokens) and parse all three limit kinds.
- * Pass `configDir` to sample a specific account (its CLAUDE_CONFIG_DIR); omit to
- * sample the live account. All ambient credential overrides are scrubbed so the
- * probe meters exactly the OAuth credential in the (possibly namespaced)
- * keychain item. The empty-footer case (claude's own usage call throttled) is
- * transient, so retry with backoff. Returns null if it never yields data.
- */
-/** The scrubbed env every probe/ping spawn uses. The child spawns the real
- *  claude DIRECTLY - it never legitimately passes through the wrapper again -
- *  so the depth is preset to the cap and a poisoned pin that leads back to the
- *  wrapper aborts on its first entry (the 2026-07-12 ~1800-process recursion
- *  started as exactly this probe). */
 function probeEnv(configDir?: string): Record<string, string> {
   const env: Record<string, string> = { ...process.env, TOKENMAXXING_PROBE: "1", [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH) };
   for (const k of CRED_ENV_OVERRIDES) delete env[k];
@@ -428,17 +359,6 @@ export async function probeUsage(configDir?: string, now = Date.now()): Promise<
   }
 }
 
-// ---- `--force` ping --------------------------------------------------------
-
-/** The ping is a REAL (but minimal) inference request: `/usage` is free and
- *  starts nothing, while any metered request opens the account's 5h session
- *  window at the current instant. haiku: the cheapest model (verified $1/$5 per
- *  MTok vs $3+ for every other current tier), and one with no per-model weekly
- *  cap (those exist only for Sonnet and Fable), so a ping never adds to a
- *  per-model cap the policy gates on; its dent in the aggregate 5h/7d windows
- *  is negligible. Hooks are disabled for the nested call
- *  (`--settings`, the only supported way; `--bare` would kill keychain reads)
- *  even though our own hooks already no-op on the probe env. */
 const PING_ARGS = [
   "-p", "Reply with exactly: ok",
   "--model", "haiku",
@@ -448,14 +368,6 @@ const PING_ARGS = [
 
 const PingResultSchema = z.looseObject({ is_error: z.boolean(), result: z.string().optional() });
 
-/**
- * Send one minimal metered request so the account's 5h session window starts
- * NOW instead of lying dormant until first real use. Pass `configDir` to ping a
- * parked account through its isolated dir (credential already installed); omit
- * to ping the live login. Runs from an empty scratch cwd so no project context
- * (CLAUDE.md, project settings) inflates the request. Returns null on success,
- * else the failure reason.
- */
 export async function pingSession(configDir?: string): Promise<string | null> {
   const cwd = join(paths.sampleDir, "ping-cwd");
   const fail = (reason: string): string => {

package/src/lib/worktree.ts

@@ -1,14 +1,6 @@
-// Linked-worktree detection for the statusLine. A linked worktree's root holds
-// a .git FILE (a gitdir pointer) where the main checkout has a .git directory.
-// Read the filesystem directly - never a git subprocess.
-
 import { statSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
-/** The worktree root's basename when `dir` is inside a LINKED git worktree;
- *  null in a main checkout or outside any repository. Any fs error while
- *  walking (EACCES, ENOTDIR, stale mounts) is also null: the status line must
- *  never break over an unreadable path. */
 export function worktreeName(dir: string): string | null {
   try {
     for (let cur = dir; ; cur = dirname(cur)) {

package/src/main.ts

@@ -1,13 +1,11 @@
 #!/usr/bin/env bun
-// Single multi-call binary. Behaves as the `claude` supervisor when invoked as
-// `claude` (or `__supervise`), routes hook/statusLine subcommands, and otherwise
-// dispatches the `tokenmaxxing` CLI.
 
 import { basename } from "node:path";
 import { runSupervisor } from "./entries/supervisor.ts";
 import { runStatusline } from "./entries/statusline.ts";
 import { runSubagentStatusline } from "./entries/subagentstatusline.ts";
 import { runStopHook } from "./entries/stophook.ts";
+import { runStopFailureHook } from "./entries/stopfailurehook.ts";
 import { runSessionStart } from "./entries/sessionstart.ts";
 import { cmdInit } from "./cli/init.ts";
 import { cmdAdd } from "./cli/add.ts";
@@ -27,8 +25,6 @@ import { cmdRename } from "./cli/rename.ts";
 import { cmdSwitch } from "./cli/switch.ts";
 import { cmdCheck } from "./cli/check.ts";
 import { cmdConfig } from "./cli/config.ts";
-import { cmdRelay } from "./cli/relay.ts";
-import { runRelayPermissionHook } from "./entries/relaypermission.ts";
 import { timerDeactivationHint, uninstallSupervisor } from "./lib/install.ts";
 import { c } from "./cli/render.ts";
 
@@ -49,7 +45,6 @@ function printHelp(): void {
   ${c.cyan("tokenmaxxing status --force")}  ping every account (one tiny haiku request each) so all 5h session timers start now, then sample fresh; ${c.cyan("xx --force")} works too
   ${c.cyan("tokenmaxxing watch")} [seconds]  live status: re-render every N seconds (default 120, never pings)
   ${c.cyan("tokenmaxxing config")} [get|set|unset|tidy]  inspect and edit config.json (bare = effective config with sources)
-  ${c.cyan("tokenmaxxing relay")} …  durable tmux relay for host agents (turn/decide/status/…); see ${c.cyan("relay --help")}
   ${c.cyan("tokenmaxxing doctor")}     verify the install is intact
   ${c.cyan("tokenmaxxing rename")} [--codex] <sel> <label>
   ${c.cyan("tokenmaxxing rm")} [--codex] <sel>
@@ -67,7 +62,6 @@ async function main(): Promise<number> {
   const argv0 = basename(process.argv0 || process.argv[0] || "");
   const sub = args[0];
 
-  // supervisor mode: invoked as `claude`, or explicit `__supervise`
   if (argv0 === "claude" || sub === "__supervise") {
     return runSupervisor(sub === "__supervise" ? args.slice(1) : args);
   }
@@ -75,20 +69,7 @@ async function main(): Promise<number> {
     return runCodexSupervisor({ argv: sub === "__supervise-codex" ? args.slice(1) : args });
   }
 
-  // CLI commands refuse an ambient claude store override (closing-review
-  // catch): with CLAUDE_CONFIG_DIR set, claude reads a hash-namespaced
-  // keychain item and a relocated .claude.json while this tool's identity,
-  // swap, and sampling machinery target the default store - `xx init` would
-  // silently import whatever stale login lives in the default location. The
-  // SDK's pooledSpawnEnv fails fast on exactly this; the CLI now matches.
-  // Scoped to COMMANDS only: the __-entries (hooks/statusline) and the
-  // supervisor arms above must never break a session claude itself launched
-  // with that env - sessions run under an ambient override are outside the
-  // managed envelope, like claude's bg-daemon bypass.
   if (!(sub != null && sub.startsWith("__")) && !process.env.TOKENMAXXING_PROBE) {
-    // first NONEMPTY value, secure-storage first (claude's own precedence):
-    // `??` alone let an empty CLAUDE_CONFIG_DIR mask a set SECURESTORAGE
-    // override (cubic review catch, PR #35).
     const nonEmpty = (v: string | undefined) => (v != null && v !== "" ? v : null);
     const ambient = nonEmpty(process.env.CLAUDE_SECURESTORAGE_CONFIG_DIR) ?? nonEmpty(process.env.CLAUDE_CONFIG_DIR);
     if (ambient != null) {
@@ -101,20 +82,16 @@ async function main(): Promise<number> {
     case "__statusline": return runStatusline();
     case "__subagent-statusline": return runSubagentStatusline();
     case "__stop-hook": return runStopHook();
+    case "__stop-failure-hook": return runStopFailureHook();
     case "__session-start": return runSessionStart();
     case "__codex-stop-hook": return runCodexStopHook();
-    case "__relay-permission-hook": return runRelayPermissionHook();
-    case undefined: return cmdStatus(); // bare `tokenmaxxing` / `xx` → status
-    case "--force": return cmdStatus(true); // bare `xx --force` → status --force
-    // --codex accepted anywhere, like init/add/status: the old args[1]-only
-    // check made `xx switch <sel> --codex` silently run a real CLAUDE swap
-    // (one email can hold both pools' accounts - closing-review catch).
-    case "relay": return cmdRelay(args.slice(1));
+    case undefined: return cmdStatus();
+    case "--force": return cmdStatus(true);
     case "switch": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
       return args.includes("--codex") ? cmdCodexSwitch(rest[0]) : cmdSwitch(rest[0]);
     }
-    case "check": return cmdCheck();
+    case "check": return cmdCheck(args.slice(1));
     case "config": return cmdConfig(args.slice(1));
     case "init": return args.includes("--codex") ? cmdCodexInit() : cmdInit();
     case "add": return args.includes("--codex") ? cmdCodexAdd() : cmdAdd();
@@ -123,9 +100,6 @@ async function main(): Promise<number> {
     case "status": return cmdStatus(args.includes("--force"));
     case "watch": return cmdWatch(args[1]);
     case "doctor": return cmdDoctor();
-    // --codex accepted anywhere, like switch/rename: the two pools are
-    // separate namespaces and codex accounts were otherwise unremovable
-    // (adversarial-review catch).
     case "rm": {
       const rest = args.slice(1).filter((a) => a !== "--codex");
       return args.includes("--codex") ? cmdCodexRm(rest[0]) : cmdRm(rest[0]);
@@ -133,9 +107,6 @@ async function main(): Promise<number> {
     case "rename": return cmdRename(args.slice(1));
     case "uninstall": {
       const out = uninstallSupervisor();
-      // the headline lists only what verifiably happened - claiming the timer
-      // or PATH line gone while the outcome flags say otherwise would
-      // contradict the warnings below (bugbot review catch, PR #33).
       const removed = [
         "supervisor wrapper",
         "settings entries",
@@ -160,12 +131,6 @@ async function main(): Promise<number> {
   }
 }
 
-// The CLI's error boundary: operational failures that deliberately THROW deep
-// in the libs (a locked keychain failing readItem loudly, codexinit's
-// changed-mid-init abort, corrupt state files) must reach the user as one
-// clean red line with the recovery hint the throw site wrote - not a raw
-// stack trace (bugbot review catch, PR #35). The __-entry subcommands keep
-// their own never-throw contracts and normally never reach this.
 try {
   process.exit(await main());
 } catch (e) {