tokenmaxxing 0.11.0 → 0.13.0

package/src/lib/codexpick.ts

@@ -0,0 +1,106 @@
+// Choose the codex account to switch TO. Same policy as the claude picker:
+// among usable accounts (no reauth, no window at/over its screening bar that
+// has not reset), take the one furthest behind its own weekly pace (highest
+// pacePressure), because weekly allowance is forfeited at a fixed per-account
+// reset. Windows are duration-classified (isSessionWindow), never assumed:
+// codex's 5h window is absent on current Plus/Pro plans (July 2026), so the
+// weekly aggregate may be the only bar there is.
+
+import { sortBy } from "es-toolkit";
+import { nextWeeklyReset } from "./picker.ts";
+import { isSessionWindow, weeklyWindowOf } from "./codexusage.ts";
+import type { CodexAccount, CodexWindow, Thresholds } from "./types.ts";
+
+function liveUsed(input: { window: CodexWindow; now: number }): number {
+  const { window, now } = input;
+  return window.resetsAt != null && window.resetsAt <= now ? 0 : window.usedPercentage;
+}
+
+function allWindows(account: CodexAccount): CodexWindow[] {
+  const usage = account.lastUsage;
+  if (!usage) return [];
+  return [...usage.aggregate, ...Object.values(usage.perLimit).flat()];
+}
+
+function barFor(input: { window: CodexWindow; thresholds: Thresholds }): number {
+  return isSessionWindow({ window: input.window }) ? input.thresholds.session : input.thresholds.weekly;
+}
+
+/** A window at/over its bar whose reset has not passed blocks the account. */
+export function isCodexExhausted(input: { account: CodexAccount; thresholds: Thresholds; now: number }): boolean {
+  const { account, thresholds, now } = input;
+  return allWindows(account).some(
+    (window) => liveUsed({ window, now }) >= barFor({ window, thresholds }),
+  );
+}
+
+/** Forward pace pressure on the weekly aggregate: the burn rate the remaining
+ *  weekly quota demands before its reset forfeits it. No sampled weekly window
+ *  or no reset anchor ranks last (0): unmeasured must not look urgent. */
+export function codexPacePressure(input: { account: CodexAccount; now: number }): number {
+  const { account, now } = input;
+  const weekly = account.lastUsage ? weeklyWindowOf({ aggregate: account.lastUsage.aggregate }) : null;
+  if (!weekly) return 0;
+  const reset = nextWeeklyReset(weekly.resetsAt, now);
+  if (reset == null) return 0;
+  return Math.max(0, 100 - liveUsed({ window: weekly, now })) / Math.max(1, reset - now);
+}
+
+function weeklyExpiryOf(input: { account: CodexAccount; now: number }): number {
+  const { account, now } = input;
+  const weekly = account.lastUsage ? weeklyWindowOf({ aggregate: account.lastUsage.aggregate }) : null;
+  return nextWeeklyReset(weekly?.resetsAt ?? null, now) ?? Number.POSITIVE_INFINITY;
+}
+
+const codexSwapPreference = (now: number) => [
+  (account: CodexAccount) => -codexPacePressure({ account, now }),
+  (account: CodexAccount) => weeklyExpiryOf({ account, now }),
+];
+
+export function pickBestCodex(input: {
+  accounts: CodexAccount[];
+  thresholds: Thresholds;
+  now: number;
+  currentAccountId: string | null;
+}): CodexAccount | null {
+  const { accounts, thresholds, now, currentAccountId } = input;
+  const usable = accounts.filter(
+    (account) =>
+      account.accountId !== currentAccountId &&
+      account.needsReauth !== true &&
+      !isCodexExhausted({ account, thresholds, now }),
+  );
+  return sortBy(usable, codexSwapPreference(now))[0] ?? null;
+}
+
+/** A codex greedy swap is a SIGTERM + respawn of a live session (codex cannot
+ *  hot-adopt), and engagement is chronic on plans whose only window is weekly:
+ *  without a margin, every hair of pace-pressure drift would visibly restart
+ *  the user's session. The challenger must beat the incumbent by this factor
+ *  (adversarial review catch, 2026-07-16); a crossed bar bypasses the margin
+ *  entirely via the hard path. */
+export const CODEX_SWAP_IMPROVEMENT = 1.2;
+
+/** Greedy idempotence, mirroring picker.currentWins with the respawn-cost
+ *  margin: the active account keeps its seat while usable unless a challenger
+ *  beats its pace pressure by CODEX_SWAP_IMPROVEMENT. */
+export function codexCurrentWins(input: {
+  active: CodexAccount | null;
+  accounts: CodexAccount[];
+  thresholds: Thresholds;
+  now: number;
+}): boolean {
+  const { active, accounts, thresholds, now } = input;
+  if (!active || active.needsReauth === true || isCodexExhausted({ account: active, thresholds, now })) return false;
+  const best = pickBestCodex({ accounts, thresholds, now, currentAccountId: null });
+  if (best == null || best.accountId === active.accountId) return true;
+  return codexPacePressure({ account: best, now }) <= codexPacePressure({ account: active, now }) * CODEX_SWAP_IMPROVEMENT;
+}
+
+/** True once any window is at/over the greedy engagement floor: with no 5h
+ *  window on current codex plans, the floor reads against every window class
+ *  rather than the session window alone. */
+export function isCodexEngaged(input: { account: CodexAccount; floor: number; now: number }): boolean {
+  const { account, floor, now } = input;
+  return allWindows(account).some((window) => liveUsed({ window, now }) >= floor);
+}

package/src/lib/codexpresence.ts

@@ -0,0 +1,77 @@
+// Which codex accounts are RUNNING right now. Codex cannot hot-swap, so a swap
+// respawns only the session whose Stop hook decided it; sibling supervised
+// sessions keep running on whatever account they started with, rotating that
+// account's token live. Such an account is a landmine for the rest of the
+// pool: its parked copy is superseded (refresh trips reuse punishment) and
+// installing it as live would yank the running session's grant. Supervisors
+// therefore declare their session's account in a presence file at every
+// (re)spawn; the picker refuses to target present accounts and the sampler
+// refuses to refresh their parked blobs. Staleness is PID-based: a presence
+// whose supervisor died is ignored and cleaned up.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { codexPaths } from "./paths.ts";
+import { writeFileAtomic } from "./atomic.ts";
+
+const PresenceSchema = z.object({
+  accountId: z.string(),
+  pid: z.number(),
+  ts: z.number(),
+});
+
+export function writeCodexPresence(input: { supervisorId: string; accountId: string }): void {
+  mkdirSync(codexPaths.presenceDir, { recursive: true });
+  writeFileAtomic(
+    join(codexPaths.presenceDir, input.supervisorId),
+    JSON.stringify(PresenceSchema.parse({ accountId: input.accountId, pid: process.pid, ts: Date.now() })),
+  );
+}
+
+export function clearCodexPresence(input: { supervisorId: string }): void {
+  rmSync(join(codexPaths.presenceDir, input.supervisorId), { force: true });
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Account ids with a LIVING supervisor. Dead supervisors' files are removed. */
+export function presentCodexAccountIds(): Set<string> {
+  const present = new Set<string>();
+  if (!existsSync(codexPaths.presenceDir)) return present;
+  for (const name of readdirSync(codexPaths.presenceDir)) {
+    const file = join(codexPaths.presenceDir, name);
+    const parsed = PresenceSchema.safeParse((() => {
+      try {
+        return JSON.parse(readFileSync(file, "utf8"));
+      } catch {
+        return null;
+      }
+    })());
+    if (!parsed.success || !pidAlive(parsed.data.pid)) {
+      rmSync(file, { force: true });
+      continue;
+    }
+    present.add(parsed.data.accountId);
+  }
+  return present;
+}
+
+/** The accounts a swap may target: running accounts are off limits, except the
+ *  seat itself (it is ranked as the incumbent, never installed over itself). */
+export function targetableCodexAccounts<T extends { accountId: string }>(input: {
+  accounts: T[];
+  activeAccountId: string | null;
+}): T[] {
+  const present = presentCodexAccountIds();
+  return input.accounts.filter(
+    (account) => account.accountId === input.activeAccountId || !present.has(account.accountId),
+  );
+}

package/src/lib/codexsample.ts

@@ -0,0 +1,62 @@
+// Per-account codex usage sampling for status/ls. The ACTIVE account (the live
+// auth.json's own identity, never the possibly-drifted label) samples through
+// the LIVE blob: its parked copy goes stale as the running codex rotates
+// tokens, and refreshing a superseded parked refresh token would trip the
+// server's reuse punishment and kill the grant family. Parked accounts sample
+// through their parked blobs (their owners are not running, so rotation on
+// refresh is safe) and every rotation is persisted back immediately.
+//
+// Caller holds the codex flock: refresh writes must not interleave with a swap.
+
+import { codexIdentityOf, isCodexAccessExpiring, readLiveCodexAuth, readParkedCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
+import { CodexInvalidGrantError, CodexRefreshFailedError, refreshCodexAuth } from "./codexoauth.ts";
+import { CodexUsageReadError, fetchCodexUsage } from "./codexusage.ts";
+import { presentCodexAccountIds } from "./codexpresence.ts";
+import type { CodexAccount, CodexUsage } from "./types.ts";
+import { z } from "zod";
+
+const CodexSampleOutcomeSchema = z.union([
+  z.object({ ok: z.literal(true), usage: z.custom<CodexUsage>() }),
+  z.object({ ok: z.literal(false), reason: z.string(), deadGrant: z.boolean() }),
+]);
+export type CodexSampleOutcome = z.infer<typeof CodexSampleOutcomeSchema>;
+
+/** The live credential's own account id, or null when absent/unreadable. */
+export function liveCodexAccountId(): string | null {
+  const live = readLiveCodexAuth();
+  if (!live) return null;
+  return codexIdentityOf({ auth: live }).accountId;
+}
+
+export async function sampleCodexAccount(input: { account: CodexAccount; liveAccountId: string | null; now?: number }): Promise<CodexSampleOutcome> {
+  const { account, liveAccountId, now = Date.now() } = input;
+  const isLive = liveAccountId != null && account.accountId === liveAccountId;
+  try {
+    let auth = isLive ? readLiveCodexAuth() : readParkedCodexAuth({ credFile: account.credFile });
+    if (!auth) return { ok: false, reason: isLive ? "live auth.json vanished" : "no parked credential", deadGrant: false };
+    if (isCodexAccessExpiring({ auth, now })) {
+      // A parked blob whose account is RUNNING in another supervised session
+      // is superseded by that session's live rotations: refreshing it would
+      // trip the server's reuse punishment and kill the running session's
+      // grant family. Skip the refresh and report a miss instead.
+      if (!isLive && presentCodexAccountIds().has(account.accountId)) {
+        return { ok: false, reason: "running in a live codex session (parked token refresh unsafe)", deadGrant: false };
+      }
+      auth = await refreshCodexAuth({ auth, now });
+      if (isLive) writeLiveCodexAuth({ auth });
+      writeParkedCodexAuth({ credFile: account.credFile, auth });
+    }
+    const usage = await fetchCodexUsage({ auth });
+    return { ok: true, usage };
+  } catch (e) {
+    // Only the EXPECTED operational failures become a sample miss; parse and
+    // filesystem errors keep propagating (they are drift or bugs to surface).
+    if (e instanceof CodexInvalidGrantError) {
+      return { ok: false, reason: e.message, deadGrant: true };
+    }
+    if (e instanceof CodexRefreshFailedError || e instanceof CodexUsageReadError) {
+      return { ok: false, reason: e.message, deadGrant: false };
+    }
+    throw e;
+  }
+}

package/src/lib/codexstate.ts

@@ -0,0 +1,29 @@
+// codex-accounts.json + codex-lastswap.json persistence. Parallel to the
+// claude files in state.ts, deliberately a separate file pair: claude and
+// codex accounts have different shapes and swap independently, so neither
+// index can clobber the other. Absent files are the empty state; a file that
+// exists but fails to parse THROWS (a fabricated empty pool would silently
+// orphan parked credentials).
+
+import { existsSync, readFileSync } from "node:fs";
+import { writeFileAtomic } from "./atomic.ts";
+import { codexPaths } from "./paths.ts";
+import { CodexAccountsIndexSchema, LastSwapSchema, type CodexAccountsIndex } from "./types.ts";
+
+export function loadCodexAccounts(): CodexAccountsIndex {
+  if (!existsSync(codexPaths.accountsJson)) return { version: 1, activeAccountId: null, accounts: [] };
+  return CodexAccountsIndexSchema.parse(JSON.parse(readFileSync(codexPaths.accountsJson, "utf8")));
+}
+
+export function saveCodexAccounts(input: { index: CodexAccountsIndex }): void {
+  writeFileAtomic(codexPaths.accountsJson, JSON.stringify(CodexAccountsIndexSchema.parse(input.index), null, 2) + "\n");
+}
+
+export function loadCodexLastSwapAt(): number | null {
+  if (!existsSync(codexPaths.lastSwapJson)) return null;
+  return LastSwapSchema.parse(JSON.parse(readFileSync(codexPaths.lastSwapJson, "utf8"))).ts;
+}
+
+export function saveCodexLastSwapAt(input: { ts: number }): void {
+  writeFileAtomic(codexPaths.lastSwapJson, JSON.stringify(LastSwapSchema.parse({ ts: input.ts })));
+}

package/src/lib/codexswap.ts

@@ -0,0 +1,93 @@
+// The codex account-switch sequence. Runs under tokenmaxxing's codex flock
+// (held by the caller). Codex itself has NO cross-process lock on auth.json
+// (verified rust-v0.144.5: refresh serialization is an in-process semaphore),
+// so this flock only serializes tokenmaxxing actors; a RUNNING codex can still
+// refresh-write the live file concurrently. The sequence therefore keeps the
+// harvest-install window as short as possible, and the Stop-hook trigger fires
+// only at an idle turn boundary where the running codex has just finished
+// using (and refreshing, if needed) its token.
+//
+//   refresh target's parked blob (network, validates the grant, rotates)
+//   harvest live auth.json verbatim under its OWN identity (labels drift,
+//     the id_token cannot lie; an unknown live identity refuses the swap)
+//   install the refreshed target as the whole live auth.json
+//   persist the rotation into the target's parked blob
+//   commit activeAccountId in the same critical section
+
+import { codexIdentityOf, readLiveCodexAuth, readParkedCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
+import { CodexInvalidGrantError, refreshCodexAuth } from "./codexoauth.ts";
+import { loadCodexAccounts, saveCodexAccounts, saveCodexLastSwapAt } from "./codexstate.ts";
+import { log } from "./log.ts";
+import type { CodexAccount } from "./types.ts";
+
+export async function performCodexSwap(input: { target: CodexAccount }): Promise<void> {
+  const { target } = input;
+  const index = loadCodexAccounts();
+
+  const parked = readParkedCodexAuth({ credFile: target.credFile });
+  if (!parked) throw new Error(`no parked codex credential for ${target.label}`);
+
+  // Resolve the live credential's owner BEFORE touching the network: a refused
+  // swap must refuse with the target's parked token still valid. The refresh
+  // rotates it server-side, and codex punishes reuse of the superseded one, so
+  // rotating first and then throwing would kill the target's grant family
+  // (adversarial review catch, 2026-07-16).
+  const live = readLiveCodexAuth();
+  let liveOwner = null;
+  if (live) {
+    const liveIdentity = codexIdentityOf({ auth: live });
+    // Backstop against a drifted caller: installing the LIVE account over
+    // itself would refresh its superseded parked token (reuse punishment kills
+    // the grant family) and rotate the token out from under a running session.
+    if (liveIdentity.accountId === target.accountId) {
+      throw new Error(
+        `${target.label} is already the live codex credential - refusing to swap an account onto itself`,
+      );
+    }
+    liveOwner = index.accounts.find((account) => account.accountId === liveIdentity.accountId) ?? null;
+    if (!liveOwner) {
+      throw new Error(
+        `live codex credential belongs to ${liveIdentity.email ?? liveIdentity.accountId.slice(0, 8)}, which is not in the pool - refusing to swap over it; import it first with \`tokenmaxxing add --codex\``,
+      );
+    }
+    if (liveOwner.accountId !== index.activeAccountId) {
+      log("codexswap.harvest_drift", {
+        labeled: index.activeAccountId?.slice(0, 8) ?? null,
+        actual: liveOwner.accountId.slice(0, 8),
+      });
+    }
+  }
+
+  let fresh;
+  try {
+    fresh = await refreshCodexAuth({ auth: parked });
+  } catch (e) {
+    if (e instanceof CodexInvalidGrantError) {
+      const entry = index.accounts.find((account) => account.accountId === target.accountId);
+      if (entry) {
+        entry.needsReauth = true;
+        saveCodexAccounts({ index });
+      }
+      log("codexswap.invalid_grant", { account: target.accountId.slice(0, 8) });
+    }
+    throw e;
+  }
+  // The rotation exists server-side from this instant: persist it before ANY
+  // later step can fail, or a crash strands the parked file on the superseded
+  // (reuse-punished) refresh token.
+  writeParkedCodexAuth({ credFile: target.credFile, auth: fresh });
+
+  if (live && liveOwner) {
+    writeParkedCodexAuth({ credFile: liveOwner.credFile, auth: live });
+    log("codexswap.harvest", { account: liveOwner.accountId.slice(0, 8) });
+  }
+
+  writeLiveCodexAuth({ auth: fresh });
+  index.activeAccountId = target.accountId;
+  const entry = index.accounts.find((account) => account.accountId === target.accountId);
+  if (entry) entry.needsReauth = false;
+  saveCodexAccounts({ index });
+  saveCodexLastSwapAt({ ts: Date.now() });
+  log("codexswap.done", { account: target.accountId.slice(0, 8), label: target.label });
+}
+

package/src/lib/codexusage.ts

@@ -0,0 +1,135 @@
+// The free codex usage read (user decision 2026-07-16: the direct GET, the same
+// HTTP call the codex CLI makes for its own /status). One authed GET returns
+// BOTH the token's true identity (account_id/email/plan: the codex analog of
+// the claude roles endpoint) and every rate-limit window. No inference runs and
+// no session window starts.
+//
+// Response shape pinned against a live read 2026-07-16: windows carry
+// used_percent + reset_at (epoch SECONDS) + limit_window_seconds, the weekly
+// window is PRIMARY on plans whose 5h window was removed (July 2026), and
+// per-model caps arrive as additional_rate_limits[] rows keyed by limit_name.
+// Classification is therefore duration-driven, never position-driven.
+
+import { z } from "zod";
+import { http, safeErrorDetail } from "./http.ts";
+import { CodexUsageSchema, type CodexAuthJson, type CodexUsage, type CodexWindow } from "./types.ts";
+import { codexIdentityOf } from "./codexauth.ts";
+
+const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
+const USAGE_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_USAGE_URL) ?? "https://chatgpt.com/backend-api/wham/usage";
+
+/** The usage read could not complete (endpoint unreachable, HTTP failure,
+ *  drifted body): an operational miss to fall back on cached figures for,
+ *  NOT a bug to swallow. */
+export class CodexUsageReadError extends Error {
+  constructor(detail: string) {
+    super(`codex usage read failed: ${detail}`);
+    this.name = "CodexUsageReadError";
+  }
+}
+
+const WireWindowSchema = z.looseObject({
+  used_percent: z.number(),
+  limit_window_seconds: z.number().nullish(),
+  reset_at: z.number().nullish(),
+});
+
+const WireRateLimitSchema = z.looseObject({
+  primary_window: WireWindowSchema.nullish(),
+  secondary_window: WireWindowSchema.nullish(),
+});
+
+const WireUsageSchema = z.looseObject({
+  account_id: z.string(),
+  email: z.string().nullish(),
+  plan_type: z.string().nullish(),
+  rate_limit: WireRateLimitSchema.nullish(),
+  additional_rate_limits: z
+    .array(z.looseObject({ limit_name: z.string(), rate_limit: WireRateLimitSchema.nullish() }))
+    .nullish(),
+});
+
+function toWindows(rateLimit: z.infer<typeof WireRateLimitSchema> | null | undefined): CodexWindow[] {
+  const out: CodexWindow[] = [];
+  for (const wire of [rateLimit?.primary_window, rateLimit?.secondary_window]) {
+    if (wire == null) continue;
+    out.push({
+      usedPercentage: wire.used_percent,
+      resetsAt: wire.reset_at != null ? wire.reset_at * 1000 : null,
+      windowSeconds: wire.limit_window_seconds ?? null,
+    });
+  }
+  return out;
+}
+
+/**
+ * One free usage read for the credential in `auth`. Throws on HTTP failure
+ * (401 included: the caller decides whether to refresh and retry); error
+ * text carries only a response-body snippet, never request headers.
+ */
+export async function fetchCodexUsage(input: { auth: CodexAuthJson }): Promise<CodexUsage> {
+  const { auth } = input;
+  const identity = codexIdentityOf({ auth });
+  let res: Response;
+  try {
+    res = await http.get(USAGE_URL, {
+      headers: {
+        Authorization: `Bearer ${auth.tokens.access_token}`,
+        "ChatGPT-Account-Id": identity.accountId,
+        "User-Agent": "codex-cli",
+      },
+    });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new CodexUsageReadError(`endpoint unreachable: ${message}`);
+  }
+  const text = await res.text();
+  if (!res.ok) {
+    throw new CodexUsageReadError(`HTTP ${res.status}: ${safeErrorDetail({ text })}`);
+  }
+  const parsed = WireUsageSchema.safeParse((() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })());
+  if (!parsed.success) {
+    throw new CodexUsageReadError("endpoint returned an unexpected body shape (withheld)");
+  }
+  const wire = parsed.data;
+
+  const perLimit: Record<string, CodexWindow[]> = {};
+  for (const row of wire.additional_rate_limits ?? []) {
+    const windows = toWindows(row.rate_limit);
+    if (windows.length > 0) perLimit[row.limit_name] = windows;
+  }
+
+  return CodexUsageSchema.parse({
+    accountId: wire.account_id,
+    email: wire.email ?? null,
+    planType: wire.plan_type ?? null,
+    aggregate: toWindows(wire.rate_limit),
+    perLimit,
+  });
+}
+
+const SESSION_WINDOW_MAX_S = 6 * 3600;
+
+/** A window's screening bar: short windows (5h-class) screen at the session
+ *  bar, everything else (weekly aggregates and per-model caps) at the weekly
+ *  bar. An unknown duration is treated as weekly: the strictest reading. */
+export function isSessionWindow(input: { window: CodexWindow }): boolean {
+  const seconds = input.window.windowSeconds;
+  return seconds != null && seconds <= SESSION_WINDOW_MAX_S;
+}
+
+/** The account's weekly aggregate window: the longest-duration aggregate row. */
+export function weeklyWindowOf(input: { aggregate: CodexWindow[] }): CodexWindow | null {
+  let best: CodexWindow | null = null;
+  for (const window of input.aggregate) {
+    if (isSessionWindow({ window })) continue;
+    if (best == null || (window.windowSeconds ?? 0) > (best.windowSeconds ?? 0)) best = window;
+  }
+  return best;
+}

package/src/lib/http.ts

@@ -4,6 +4,32 @@
 // so callers read the body and shape their own fail-fast error; retry still runs.
 
 import ky from "ky";
+import { z } from "zod";
+
+/** The error-shape fields OAuth/usage endpoints legitimately explain themselves
+ *  with. Error bodies are NEVER surfaced raw: a token endpoint's failure body
+ *  can echo request material, so anything outside this allowlist is dropped. */
+const ErrorBodySchema = z.looseObject({
+  error: z.string().optional(),
+  error_description: z.string().optional(),
+  detail: z.string().optional(),
+  message: z.string().optional(),
+});
+
+/** Allowlisted, token-safe rendering of an HTTP error body. */
+export function safeErrorDetail(input: { text: string }): string {
+  const parsed = ErrorBodySchema.safeParse((() => {
+    try {
+      return JSON.parse(input.text);
+    } catch {
+      return null;
+    }
+  })());
+  if (!parsed.success) return "(unparsable error body withheld)";
+  const fields = [parsed.data.error, parsed.data.error_description, parsed.data.detail, parsed.data.message];
+  const detail = fields.filter((field): field is string => field != null && field.length > 0).join(": ");
+  return detail.length > 0 ? detail.slice(0, 200) : "(no error detail)";
+}
 
 export const http = ky.create({
   timeout: 15_000,

package/src/lib/install.ts

@@ -6,7 +6,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSy
 import { basename, dirname, join } from "node:path";
 import { escape } from "es-toolkit";
 import { z } from "zod";
-import { HOME, paths } from "./paths.ts";
+import { codexPaths, HOME, paths } from "./paths.ts";
 import { writeFileAtomic } from "./atomic.ts";
 import { installedBin, installSettings, uninstallSettings } from "./settings.ts";
 import { resolveRealClaude } from "./claudebin.ts";
@@ -56,6 +56,70 @@ export function installSupervisor(): InstallOutcome {
   };
 }
 
+// ---- codex supervisor + Stop hook -------------------------------------------
+
+/** Codex hook declarations we merge into. Loose everywhere: every other event
+ *  and every foreign Stop entry rides along verbatim. */
+const CodexHooksFileSchema = z.looseObject({
+  Stop: z.array(z.looseObject({ hooks: z.array(z.looseObject({ command: z.string().optional() })).default([]) })).default([]),
+});
+
+const CODEX_STOP_HOOK_SUBCOMMAND = "__codex-stop-hook";
+
+function codexStopHookCommand(): string {
+  // Quoted like the claude shim commands: an install path with a space would
+  // otherwise mis-split and the hook would silently never run.
+  return `${JSON.stringify(installedBin())} ${CODEX_STOP_HOOK_SUBCOMMAND}`;
+}
+
+/** Idempotently install the tokenmaxxing Stop entry in ~/.codex/hooks.json,
+ *  preserving every other declaration. Codex skips new hooks until the user
+ *  trusts them via /hooks (trust is recorded against the hook's hash), so the
+ *  caller must surface that step. */
+export function installCodexStopHook(): void {
+  const current = existsSync(codexPaths.hooksJson)
+    ? CodexHooksFileSchema.parse(JSON.parse(readFileSync(codexPaths.hooksJson, "utf8")))
+    : CodexHooksFileSchema.parse({});
+  const foreign = current.Stop.filter(
+    (group) => !group.hooks.some((hook) => hook.command?.includes(CODEX_STOP_HOOK_SUBCOMMAND)),
+  );
+  const next = {
+    ...current,
+    Stop: [
+      ...foreign,
+      { hooks: [{ type: "command", command: codexStopHookCommand(), timeout: 120, statusMessage: "tokenmaxxing switch check" }] },
+    ],
+  };
+  mkdirSync(codexPaths.home, { recursive: true });
+  writeFileAtomic(codexPaths.hooksJson, JSON.stringify(next, null, 2) + "\n");
+}
+
+export function uninstallCodexStopHook(): void {
+  if (!existsSync(codexPaths.hooksJson)) return;
+  const current = CodexHooksFileSchema.parse(JSON.parse(readFileSync(codexPaths.hooksJson, "utf8")));
+  const next = {
+    ...current,
+    Stop: current.Stop.filter((group) => !group.hooks.some((hook) => hook.command?.includes(CODEX_STOP_HOOK_SUBCOMMAND))),
+  };
+  writeFileAtomic(codexPaths.hooksJson, JSON.stringify(next, null, 2) + "\n");
+}
+
+export function codexSupervisorLink(): string {
+  return join(paths.binDir, "codex");
+}
+
+/** The on-PATH `codex` wrapper + the Stop hook declaration. */
+export function installCodexSupervisor(): void {
+  mkdirSync(paths.binDir, { recursive: true });
+  writeFileAtomic(codexSupervisorLink(), `#!/bin/sh\nexec ${JSON.stringify(installedBin())} __supervise-codex "$@"\n`, 0o755);
+  installCodexStopHook();
+}
+
+export function uninstallCodexSupervisor(): void {
+  uninstallCodexStopHook();
+  if (existsSync(codexSupervisorLink())) rmSync(codexSupervisorLink(), { force: true });
+}
+
 // ---- periodic `check` timer ------------------------------------------------
 // The hooks evaluate only at turn boundaries; one long agentic turn can burn a
 // window from healthy to depleted with zero boundaries (2026-07-10 incident).
@@ -243,6 +307,7 @@ export function findClaudeShadowers(rcText: string): ShellShadower[] {
 export function uninstallSupervisor(): void {
   uninstallSettings();
   uninstallCheckTimer();
+  uninstallCodexSupervisor();
   for (const f of [paths.supervisorLink, join(paths.binDir, "xx"), installedBin()]) {
     if (existsSync(f)) rmSync(f, { force: true });
   }