tokenmaxxing 0.12.0 → 0.13.0

package/src/entries/codexsupervisor.ts

@@ -0,0 +1,150 @@
+// 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, rmSync } from "node:fs";
+import { join } from "node:path";
+import { codexPaths, paths } from "../lib/paths.ts";
+import { LOOP_DIAGNOSIS, MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, WRAP_RATE_MAX, WRAP_RATE_WINDOW_MS, wrapDepth, wrapperEntryRateTripped } from "../lib/claudebin.ts";
+import { resolveRealCodex } from "../lib/codexbin.ts";
+import { clearCodexPresence, writeCodexPresence } from "../lib/codexpresence.ts";
+import { liveCodexAccountId } from "../lib/codexsample.ts";
+import { saveTermios, restoreTermios } from "../lib/tty.ts";
+import { CodexRespawnMarkerSchema } from "../lib/types.ts";
+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",
+  "apply", "archive", "delete", "unarchive", "cloud", "exec-server", "features", "help",
+]);
+
+const PASSTHROUGH_FLAGS = new Set(["--version", "-V", "--help", "-h"]);
+
+/** 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",
+]);
+
+export function shouldManageCodex(input: { argv: string[] }): boolean {
+  if (process.env.TOKENMAXXING_PROBE) return false;
+  let firstPositional: string | null = null;
+  for (let i = 0; i < input.argv.length; i++) {
+    const arg = input.argv[i]!;
+    if (PASSTHROUGH_FLAGS.has(arg)) return false;
+    if (VALUE_TAKING_ROOT_FLAGS.has(arg)) {
+      i++;
+      continue;
+    }
+    if (!arg.startsWith("-") && firstPositional === null) firstPositional = arg;
+  }
+  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();
+  if (depth >= MAX_WRAP_DEPTH) {
+    console.error(
+      `tokenmaxxing: ${LOOP_DIAGNOSIS} (depth ${depth}) - codexBin in ${paths.configJson} does not launch the real codex binary. Fix codexBin, then run \`tokenmaxxing doctor\`.`,
+    );
+    log("codexsupervisor.loop_abort", { depth });
+    return 1;
+  }
+  if (wrapperEntryRateTripped(Date.now())) {
+    console.error(
+      `tokenmaxxing: ${LOOP_DIAGNOSIS} (over ${WRAP_RATE_MAX} wrapper entries in ${WRAP_RATE_WINDOW_MS / 1000}s) - codexBin in ${paths.configJson} does not launch the real codex binary. Fix codexBin, then run \`tokenmaxxing doctor\`.`,
+    );
+    log("codexsupervisor.rate_abort", { max: WRAP_RATE_MAX });
+    return 1;
+  }
+
+  const real = resolveRealCodex();
+  const childEnv = { ...process.env, [WRAP_DEPTH_ENV]: String(depth + 1) };
+
+  if (!shouldManageCodex({ argv })) {
+    const p = Bun.spawn([real, ...argv], { stdin: "inherit", stdout: "inherit", stderr: "inherit", env: childEnv });
+    await p.exited;
+    return p.exitCode ?? (p.signalCode ? 1 : 0);
+  }
+
+  const supervisorId = crypto.randomUUID();
+  mkdirSync(codexPaths.respawnDir, { recursive: true });
+  const marker = join(codexPaths.respawnDir, supervisorId);
+  const savedTermios = saveTermios();
+
+  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.
+    const spawnAccountId = liveCodexAccountId();
+    if (spawnAccountId) writeCodexPresence({ supervisorId, accountId: spawnAccountId });
+
+    const child = Bun.spawn([real, ...launchArgs], {
+      stdin: "inherit",
+      stdout: "inherit",
+      stderr: "inherit",
+      env: { ...childEnv, [CODEX_SUPERVISOR_ID_ENV]: supervisorId },
+    });
+
+    let done = false;
+    const markerWatch = (async () => {
+      while (!done) {
+        if (await Bun.file(marker).exists()) return true;
+        await Bun.sleep(150);
+      }
+      return false;
+    })();
+    const exited = child.exited.then(() => {
+      done = true;
+      return "exit";
+    });
+    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
+    }
+    await child.exited;
+    done = true;
+    await markerWatch.catch(() => false);
+    restoreTermios(savedTermios);
+
+    if (existsSync(marker)) {
+      const payload = CodexRespawnMarkerSchema.parse(await Bun.file(marker).json());
+      rmSync(marker, { force: true });
+      respawns++;
+      process.stdout.write(`\n\x1b[36m↻ tokenmaxxing: switched codex to ${payload.account} - resuming...\x1b[0m\n`);
+      launchArgs = payload.sessionId ? ["resume", payload.sessionId] : ["resume", "--last"];
+      continue;
+    }
+    clearCodexPresence({ supervisorId });
+    log("codexsupervisor.exit", { supervisorId: supervisorId.slice(0, 8), respawns, code: child.exitCode, signal: child.signalCode });
+    return child.exitCode ?? (child.signalCode ? 1 : 0);
+  }
+}

package/src/lib/codexauth.ts

@@ -0,0 +1,122 @@
+// Read/write codex credential blobs ($CODEX_HOME/auth.json and parked copies)
+// and decode the id_token's identity claims. Codex has NO cross-process lock on
+// auth.json (its refresh serialization is an in-process semaphore, verified
+// rust-v0.144.5 manager.rs), so every mutation here runs under tokenmaxxing's
+// own codex flock, held by the caller.
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { writeFileAtomic } from "./atomic.ts";
+import { codexPaths } from "./paths.ts";
+import { CodexAuthJsonSchema, type CodexAuthJson } from "./types.ts";
+
+function isEnoent(e: unknown): boolean {
+  return e instanceof Error && "code" in e && e.code === "ENOENT";
+}
+
+/** auth.json at an explicit path (the live file, or an onboard dir's), or null
+ *  when absent. Throws on a present-but-unparsable file: that is drift to
+ *  surface, not to paper over. */
+export function readCodexAuthAt(input: { path: string }): CodexAuthJson | null {
+  let raw: string;
+  try {
+    raw = readFileSync(input.path, "utf8");
+  } catch (e) {
+    if (isEnoent(e)) return null;
+    throw e;
+  }
+  return CodexAuthJsonSchema.parse(JSON.parse(raw));
+}
+
+/** The live auth.json, or null when codex has no login here. */
+export function readLiveCodexAuth(): CodexAuthJson | null {
+  return readCodexAuthAt({ path: codexPaths.authJson });
+}
+
+export function writeLiveCodexAuth(input: { auth: CodexAuthJson }): void {
+  writeFileAtomic(codexPaths.authJson, JSON.stringify(CodexAuthJsonSchema.parse(input.auth), null, 2), 0o600);
+}
+
+function parkedPath(input: { credFile: string }): string {
+  return join(codexPaths.credsDir, `${input.credFile}.json`);
+}
+
+export function readParkedCodexAuth(input: { credFile: string }): CodexAuthJson | null {
+  let raw: string;
+  try {
+    raw = readFileSync(parkedPath(input), "utf8");
+  } catch (e) {
+    if (isEnoent(e)) return null;
+    throw e;
+  }
+  return CodexAuthJsonSchema.parse(JSON.parse(raw));
+}
+
+export function writeParkedCodexAuth(input: { credFile: string; auth: CodexAuthJson }): void {
+  writeFileAtomic(parkedPath(input), JSON.stringify(CodexAuthJsonSchema.parse(input.auth), null, 2), 0o600);
+}
+
+/** Identity claims inside the id_token JWT payload (verified against a live
+ *  0.144.4 token: the chatgpt fields sit under the api.openai.com/auth claim). */
+const IdClaimsSchema = z.looseObject({
+  email: z.string().optional(),
+  "https://api.openai.com/auth": z
+    .looseObject({
+      chatgpt_account_id: z.string().optional(),
+      chatgpt_plan_type: z.string().optional(),
+    })
+    .optional(),
+});
+
+const JwtNumericClaimsSchema = z.looseObject({ exp: z.number().optional() });
+
+function decodeJwtPayload(input: { jwt: string }): unknown {
+  const segments = input.jwt.split(".");
+  if (segments.length !== 3) throw new Error("not a JWT: expected three dot-separated segments");
+  const payload = Buffer.from(segments[1]!, "base64url").toString("utf8");
+  return JSON.parse(payload);
+}
+
+const CodexIdentitySchema = z.object({
+  accountId: z.string(),
+  email: z.string().nullable(),
+  planType: z.string().nullable(),
+});
+export type CodexIdentity = z.infer<typeof CodexIdentitySchema>;
+
+/**
+ * The blob's own identity, from its token material alone (no network): the
+ * explicit tokens.account_id, else the id_token's chatgpt_account_id claim.
+ * Parking MUST key on this (or the usage endpoint's echo of it), never on a
+ * stored label - labels drift, tokens cannot lie.
+ */
+export function codexIdentityOf(input: { auth: CodexAuthJson }): CodexIdentity {
+  const { auth } = input;
+  const claims = IdClaimsSchema.parse(decodeJwtPayload({ jwt: auth.tokens.id_token }));
+  const authClaims = claims["https://api.openai.com/auth"];
+  const accountId = auth.tokens.account_id ?? authClaims?.chatgpt_account_id;
+  if (!accountId) {
+    throw new Error("codex credential carries no account id (neither tokens.account_id nor the id_token claim)");
+  }
+  return CodexIdentitySchema.parse({
+    accountId,
+    email: claims.email ?? null,
+    planType: authClaims?.chatgpt_plan_type ?? null,
+  });
+}
+
+/** True when the access token is within `skewMs` of its JWT exp (or exp is
+ *  unreadable). Codex's own proactive refresh margin is 5 minutes; matching it
+ *  means we never install a token codex would immediately refresh. */
+export function isCodexAccessExpiring(input: { auth: CodexAuthJson; skewMs?: number; now?: number }): boolean {
+  const { auth, skewMs = 300_000, now = Date.now() } = input;
+  let exp: number | undefined;
+  try {
+    exp = JwtNumericClaimsSchema.parse(decodeJwtPayload({ jwt: auth.tokens.access_token })).exp;
+  } catch {
+    return true;
+  }
+  if (exp == null) return true;
+  return exp * 1000 - now <= skewMs;
+}

package/src/lib/codexbin.ts

@@ -0,0 +1,64 @@
+// Resolve the REAL codex binary (never our shim on PATH). Same guarantees as
+// claudebin.ts: a configured-but-missing pin fails fast instead of degrading
+// to a scan, and anything that realpath-resolves into our binDir is refused
+// (spawning it as codex would recurse through the codex supervisor).
+
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { LOOP_DIAGNOSIS, MAX_WRAP_DEPTH, WRAP_DEPTH_ENV, pointsBackAtUs } from "./claudebin.ts";
+import { loadConfig } from "./state.ts";
+import { paths } from "./paths.ts";
+
+/** First PATH entry with a `codex` that is not us. null when PATH has none. */
+export function scanPathForCodex(): string | null {
+  for (const d of (process.env.PATH ?? "").split(":")) {
+    if (!d) continue;
+    const cand = join(d, "codex");
+    try {
+      if (existsSync(cand) && statSync(cand).isFile() && !pointsBackAtUs(cand)) return cand;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+export function resolveRealCodex(): string {
+  const cfg = loadConfig();
+  if (cfg.codexBin) {
+    if (!existsSync(cfg.codexBin)) {
+      throw new Error(`configured codexBin does not exist: ${cfg.codexBin} - fix config.json`);
+    }
+    if (pointsBackAtUs(cfg.codexBin)) {
+      throw new Error(
+        `configured codexBin (${cfg.codexBin}) is tokenmaxxing's own wrapper - spawning it recurses. Point codexBin at the real codex binary in ${paths.configJson}`,
+      );
+    }
+    return cfg.codexBin;
+  }
+  const scanned = scanPathForCodex();
+  if (scanned) return scanned;
+  throw new Error("could not locate the real `codex` binary (set codexBin in config.json)");
+}
+
+/** Behavioral check used by `init --codex` before pinning: the binary must
+ *  answer `--version` identifying itself as codex, without re-entering our
+ *  wrapper (depth preset to the cap kills a poisoned pin on first entry).
+ *  Returns null when the binary passes, else the failure detail. */
+export function verifyRealCodex(input: { bin: string }): string | null {
+  const env = { ...process.env, [WRAP_DEPTH_ENV]: String(MAX_WRAP_DEPTH), TOKENMAXXING_PROBE: "1" };
+  let p: ReturnType<typeof Bun.spawnSync>;
+  try {
+    p = Bun.spawnSync([input.bin, "--version"], { env, stdout: "pipe", stderr: "pipe", timeout: 15_000, killSignal: "SIGKILL" });
+  } catch (e) {
+    return e instanceof Error ? e.message : String(e);
+  }
+  const outText = (p.stdout?.toString() ?? "").trim();
+  const err = (p.stderr?.toString() ?? "").trim();
+  if (p.exitCode === 0) {
+    if (outText.toLowerCase().includes("codex")) return null;
+    return `--version output does not identify codex: "${outText.slice(0, 80)}"`;
+  }
+  if (err.includes(LOOP_DIAGNOSIS)) return "it leads back into the tokenmaxxing wrapper (recursion)";
+  return `--version exited ${p.exitCode ?? "on signal/timeout"}: ${(err || outText).slice(0, 160)}`;
+}

package/src/lib/codexdecide.ts

@@ -0,0 +1,157 @@
+// Shared codex switch decision, used by the codex Stop hook and `xx switch
+// --codex`. Same policy as decide.ts, reshaped for codex mechanics: usage
+// comes from the free direct GET (no statusLine tee exists), the greedy floor
+// reads against every window class (current codex plans have no 5h window:
+// the weekly aggregate is primary, verified live 2026-07-16), and there is no
+// depleted pre-park (a swap only lands where a window is usable NOW; a
+// depleted pool stays put and recovers when a cached reset passes).
+
+import { z } from "zod";
+import { withLock } from "./lock.ts";
+import { codexPaths } from "./paths.ts";
+import { loadConfig } from "./state.ts";
+import { loadCodexAccounts, loadCodexLastSwapAt, saveCodexAccounts } from "./codexstate.ts";
+import { codexCurrentWins, isCodexEngaged, isCodexExhausted, pickBestCodex } from "./codexpick.ts";
+import { performCodexSwap } from "./codexswap.ts";
+import { CodexInvalidGrantError, refreshCodexAuth } from "./codexoauth.ts";
+import { fetchCodexUsage } from "./codexusage.ts";
+import { isCodexAccessExpiring, readLiveCodexAuth, writeLiveCodexAuth, writeParkedCodexAuth } from "./codexauth.ts";
+import { liveCodexAccountId } from "./codexsample.ts";
+import { targetableCodexAccounts } from "./codexpresence.ts";
+import { effectiveBars } from "./picker.ts";
+import { log } from "./log.ts";
+import { CodexAccountSchema } from "./types.ts";
+
+const CodexSwapDecisionSchema = z.object({
+  swapped: z.boolean(),
+  account: CodexAccountSchema.nullable(),
+  reason: z.string(),
+});
+export type CodexSwapDecision = z.infer<typeof CodexSwapDecisionSchema>;
+
+const POST_SWAP_COOLDOWN_MS = 45_000;
+
+/**
+ * Sample the LIVE credential's usage and stamp it onto its TRUE owner in the
+ * pool (the usage read echoes the token's own account id: labels drift, the
+ * token cannot lie). Refreshes the live blob first when it is near expiry,
+ * persisting the rotation to both the live file and the owner's parked copy.
+ * Returns the owner, or null when the live credential is absent or unpooled.
+ */
+async function sampleLiveOntoOwner(input: { now: number }): Promise<string | null> {
+  const { now } = input;
+  let live = readLiveCodexAuth();
+  if (!live) return null;
+
+  if (isCodexAccessExpiring({ auth: live, now })) {
+    live = await refreshCodexAuth({ auth: live, now });
+    writeLiveCodexAuth({ auth: live });
+  }
+  const usage = await fetchCodexUsage({ auth: live });
+
+  const index = loadCodexAccounts();
+  const owner = index.accounts.find((account) => account.accountId === usage.accountId);
+  if (!owner) return null;
+  writeParkedCodexAuth({ credFile: owner.credFile, auth: live });
+  owner.lastUsage = { aggregate: usage.aggregate, perLimit: usage.perLimit };
+  owner.lastUsageAt = now;
+  if (usage.email != null) owner.email = usage.email;
+  if (usage.planType != null) owner.planType = usage.planType;
+  saveCodexAccounts({ index });
+  return owner.accountId;
+}
+
+export async function evaluateAndMaybeSwapCodex(input: { now?: number }): Promise<CodexSwapDecision> {
+  const now = input.now ?? Date.now();
+  const lastSwapAt = loadCodexLastSwapAt();
+  if (lastSwapAt != null && now - lastSwapAt < POST_SWAP_COOLDOWN_MS) {
+    return { swapped: false, account: null, reason: "post-swap-cooldown" };
+  }
+
+  const cfg = loadConfig();
+  const bars = effectiveBars(cfg);
+
+  return withLock(codexPaths.lockFile, async () => {
+    let index = loadCodexAccounts();
+    if (index.accounts.length === 0) return { swapped: false, account: null, reason: "no-pool" };
+
+    // The current account is ALWAYS the live auth.json's own identity: the
+    // stored activeAccountId label drifts (manual `codex login`, a crash
+    // before saveCodexAccounts), and trusting it once let the decision target
+    // the RUNNING account (adversarial review catch, 2026-07-16). A live
+    // identity outside the pool is the org-guard analog: do nothing, a swap
+    // over an unknown credential could destroy its only copy.
+    const activeId = liveCodexAccountId();
+    if (activeId == null || !index.accounts.some((account) => account.accountId === activeId)) {
+      return { swapped: false, account: null, reason: "live-credential-not-in-pool" };
+    }
+
+    // Freshness: re-sample the live credential once its owner's cached
+    // snapshot ages past the poll TTL (there is no push feed in between).
+    const activeEntry = index.accounts.find((account) => account.accountId === activeId);
+    const stale = activeEntry?.lastUsageAt == null || now - activeEntry.lastUsageAt > cfg.policy.usagePollTtlMs;
+    if (stale) {
+      const sampledId = await sampleLiveOntoOwner({ now });
+      if (sampledId == null) {
+        return { swapped: false, account: null, reason: "live-credential-not-in-pool" };
+      }
+      index = loadCodexAccounts();
+    }
+
+    const active = index.accounts.find((account) => account.accountId === activeId) ?? null;
+    if (!active) return { swapped: false, account: null, reason: "no-active-account" };
+
+    const engaged =
+      isCodexEngaged({ account: active, floor: cfg.policy.greedySessionFloor, now }) ||
+      isCodexExhausted({ account: active, thresholds: bars, now });
+    if (!engaged) return { swapped: false, account: null, reason: "under-threshold-or-stale" };
+
+    // Greedy path: engaged but under every bar. Swap only onto an account
+    // that beats the seat by the respawn-cost margin, never onto one RUNNING
+    // in another session (presence files); re-rank after a dead grant
+    // (performCodexSwap persists needs-reauth before throwing, so the loop
+    // terminates).
+    if (!isCodexExhausted({ account: active, thresholds: bars, now })) {
+      while (true) {
+        const current = loadCodexAccounts();
+        const candidates = targetableCodexAccounts({ accounts: current.accounts, activeAccountId: activeId });
+        const cur = candidates.find((account) => account.accountId === activeId) ?? null;
+        if (codexCurrentWins({ active: cur, accounts: candidates, thresholds: bars, now })) {
+          return { swapped: false, account: null, reason: "current-best" };
+        }
+        const best = pickBestCodex({ accounts: candidates, thresholds: bars, now, currentAccountId: activeId });
+        if (!best) return { swapped: false, account: null, reason: "no-usable-target" };
+        try {
+          await performCodexSwap({ target: best });
+        } catch (e) {
+          if (e instanceof CodexInvalidGrantError) continue;
+          throw e;
+        }
+        log("codexdecide.greedy_swap", { account: best.accountId.slice(0, 8) });
+        return { swapped: true, account: best, reason: "swapped" };
+      }
+    }
+
+    // Hard path: a bar is crossed. Land on the best usable candidate, walking
+    // past dead grants; a fully depleted pool stays put (no pre-park: nothing
+    // can pause a codex session for a countdown yet).
+    const tried = new Set<string>();
+    while (true) {
+      const current = loadCodexAccounts();
+      const candidates = targetableCodexAccounts({ accounts: current.accounts, activeAccountId: activeId }).filter(
+        (account) => !tried.has(account.accountId),
+      );
+      const best = pickBestCodex({ accounts: candidates, thresholds: bars, now, currentAccountId: activeId });
+      if (!best) return { swapped: false, account: null, reason: "all-depleted" };
+      tried.add(best.accountId);
+      try {
+        await performCodexSwap({ target: best });
+      } catch (e) {
+        if (e instanceof CodexInvalidGrantError) continue;
+        throw e;
+      }
+      log("codexdecide.hard_swap", { account: best.accountId.slice(0, 8) });
+      return { swapped: true, account: best, reason: "swapped" };
+    }
+  });
+}

package/src/lib/codexoauth.ts

@@ -0,0 +1,99 @@
+// The one OAuth call tokenmaxxing makes for codex: the refresh_token grant.
+// Verified against openai/codex rust-v0.144.5 (login/src/auth/manager.rs):
+// POST auth.openai.com/oauth/token, JSON body {client_id, grant_type,
+// refresh_token}, no auth headers. The server ROTATES the refresh token and
+// punishes reuse of a superseded one (refresh_token_reused), so every rotation
+// must be persisted back into the blob it came from immediately.
+
+import { z } from "zod";
+import { http, safeErrorDetail } from "./http.ts";
+import { CodexAuthJsonSchema, type CodexAuthJson } from "./types.ts";
+
+const EnvOverrideSchema = z.string().min(1).optional().catch(undefined);
+const TOKEN_URL = EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_TOKEN_URL) ?? "https://auth.openai.com/oauth/token";
+const CLIENT_ID = EnvOverrideSchema.parse(process.env.TOKENMAXXING_CODEX_CLIENT_ID) ?? "app_EMoamEEZ73f0CkXaXp7hrann";
+
+/** Refresh token dead, superseded, or revoked: mark needs-reauth and move on. */
+export class CodexInvalidGrantError extends Error {
+  constructor(detail: string) {
+    super(`codex invalid grant: ${detail}`);
+    this.name = "CodexInvalidGrantError";
+  }
+}
+
+/** The refresh could not run (endpoint unreachable, throttled, drifted body):
+ *  an operational miss to retry later, NOT a dead grant and NOT a bug. */
+export class CodexRefreshFailedError extends Error {
+  constructor(detail: string) {
+    super(`codex token refresh failed: ${detail}`);
+    this.name = "CodexRefreshFailedError";
+  }
+}
+
+const CodexRefreshResponseSchema = z.looseObject({
+  id_token: z.string().optional(),
+  access_token: z.string(),
+  refresh_token: z.string().optional(),
+});
+
+const DEAD_GRANT_MARKERS = [
+  "invalid_grant",
+  "refresh_token_reused",
+  "refresh_token_expired",
+  "refresh_token_invalidated",
+];
+
+/**
+ * Exchange the blob's refresh token for fresh tokens. Returns a NEW auth.json
+ * value with rotated token material and last_refresh restamped; every sibling
+ * field rides along verbatim. Throws CodexInvalidGrantError on a dead grant.
+ * Error paths only ever surface response-body snippets, never request headers.
+ */
+export async function refreshCodexAuth(input: { auth: CodexAuthJson; now?: number }): Promise<CodexAuthJson> {
+  const { auth, now = Date.now() } = input;
+  let res: Response;
+  try {
+    res = await http.post(TOKEN_URL, {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_id: CLIENT_ID,
+        grant_type: "refresh_token",
+        refresh_token: auth.tokens.refresh_token,
+      }),
+    });
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    throw new CodexRefreshFailedError(`endpoint unreachable: ${message}`);
+  }
+
+  const text = await res.text();
+  if (!res.ok) {
+    const detail = safeErrorDetail({ text });
+    if (DEAD_GRANT_MARKERS.some((marker) => text.includes(marker))) {
+      throw new CodexInvalidGrantError(detail);
+    }
+    throw new CodexRefreshFailedError(`HTTP ${res.status}: ${detail}`);
+  }
+
+  const parsed = CodexRefreshResponseSchema.safeParse((() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })());
+  if (!parsed.success) {
+    throw new CodexRefreshFailedError("endpoint returned an unexpected body shape (withheld: may carry tokens)");
+  }
+
+  return CodexAuthJsonSchema.parse({
+    ...auth,
+    tokens: {
+      ...auth.tokens,
+      access_token: parsed.data.access_token,
+      refresh_token: parsed.data.refresh_token ?? auth.tokens.refresh_token,
+      id_token: parsed.data.id_token ?? auth.tokens.id_token,
+    },
+    last_refresh: new Date(now).toISOString(),
+  });
+}