agent-dag 1.23.3 → 1.25.0

package/src/server/codex-auth.mjs

@@ -0,0 +1,278 @@
+// Codex (ChatGPT) OAuth credentials: read, refresh, persist.
+//
+// Ports the flow the Codex CLI itself uses (openai/codex, crate `codex-login`)
+// so agents-deck keeps a live token instead of going dark the moment the one
+// written by `codex login` rotates server-side.
+//
+// The important subtlety: OpenAI ROTATES the refresh token, single-use. A
+// refresh whose result does not reach disk burns the credential outright —
+// the next attempt fails with `refresh_token_reused` and the user has to run
+// `codex login` again. Everything defensive in this file follows from that:
+// refreshes are serialized, the token is re-read from disk inside the lock
+// immediately before it is spent, a response that does not clearly carry a
+// new access token is never treated as success, and nothing here throws —
+// a rejected promise from a background poll would take the server down.
+import { readFile, writeFile, rename, chmod, unlink, realpath, open } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const CODEX_HOME = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+const AUTH_PATH  = join(CODEX_HOME, "auth.json");
+
+// Same client id + endpoint the Codex CLI uses (codex-rs/login/src/auth/manager.rs).
+const CLIENT_ID   = process.env.CODEX_APP_SERVER_LOGIN_CLIENT_ID ?? "app_EMoamEEZ73f0CkXaXp7hrann";
+const REFRESH_URL = process.env.CODEX_REFRESH_TOKEN_URL_OVERRIDE ?? "https://auth.openai.com/oauth/token";
+
+// Refresh once the access token is within this much of expiring. Deliberately
+// tighter than the CLI's 5 minutes: matching it would wake both processes into
+// the same window to race for the same single-use token, and the loser gets a
+// `refresh_token_reused` that reads to the user as "your login is broken".
+const EXPIRY_SKEW_MS   = 90 * 1000;
+// Fallback only, for tokens whose `exp` we cannot read.
+const MAX_TOKEN_AGE_MS = 8 * 24 * 60 * 60 * 1000;
+
+// Refresh failures that will never succeed on retry — the credential is gone
+// and only `codex login` brings it back.
+const PERMANENT_CODES = new Set([
+  "refresh_token_expired",
+  "refresh_token_reused",
+  "refresh_token_invalidated",
+  "invalid_grant",
+]);
+
+/** Decode a JWT payload. Returns null for anything that isn't a 3-part JWT. */
+export function decodeJwt(token) {
+  if (typeof token !== "string") return null;
+  const parts = token.split(".");
+  if (parts.length !== 3 || !parts[1]) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    return (payload && typeof payload === "object") ? payload : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Access-token expiry in ms, or null when the token carries no readable `exp`. */
+function expiryMs(accessToken) {
+  const exp = decodeJwt(accessToken)?.exp;
+  return typeof exp === "number" ? exp * 1000 : null;
+}
+
+async function readAuthFile() {
+  try {
+    const parsed = JSON.parse(await readFile(AUTH_PATH, "utf8"));
+    return (parsed && typeof parsed === "object") ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write auth.json back atomically: write a sibling tmp file, fsync it, then
+ * rename over the target. A reader can never observe a half-written file, and
+ * the fsync means a machine crash cannot leave an empty one behind after we
+ * have already spent the old refresh token.
+ *
+ * Resolves symlinks first — `~/.codex/auth.json` is often a link into a
+ * dotfiles repo or an encrypted volume, and renaming onto the link would
+ * replace it with a regular file, quietly detaching the user's setup.
+ *
+ * Throws on failure; the caller must treat that as "the refresh did not
+ * happen" rather than swallowing it.
+ */
+async function persistAuth(auth) {
+  const target = await realpath(AUTH_PATH).catch(() => AUTH_PATH);
+  const tmp    = `${target}.agents-deck-${process.pid}.tmp`;
+
+  let ok = false;
+  try {
+    await writeFile(tmp, JSON.stringify(auth, null, 2), { mode: 0o600 });
+    // writeFile ignores `mode` when the file already exists, so pin it again.
+    await chmod(tmp, 0o600);
+    const fd = await open(tmp, "r+");
+    try { await fd.sync(); } finally { await fd.close(); }
+    await rename(tmp, target);
+    ok = true;
+  } finally {
+    // A tmp left behind holds a live rotated refresh token in cleartext.
+    if (!ok) await unlink(tmp).catch(() => {});
+  }
+}
+
+/** True when the stored access token is expired, near-expiry, or stale. */
+function shouldRefresh(auth) {
+  const tokens = auth?.tokens;
+  if (!tokens?.refresh_token) return false;
+  if (!tokens.access_token) return true;
+
+  const exp = expiryMs(tokens.access_token);
+  if (exp != null) return exp <= Date.now() + EXPIRY_SKEW_MS;
+
+  // No readable expiry — fall back to how long ago the CLI last refreshed.
+  const last = auth.last_refresh ? Date.parse(auth.last_refresh) : NaN;
+  if (isNaN(last)) return false;
+  return last < Date.now() - MAX_TOKEN_AGE_MS;
+}
+
+/** Pull the failure code out of the several shapes the endpoint returns it in. */
+function refreshErrorCode(body) {
+  const raw = typeof body?.error === "object" ? body?.error?.code
+            : typeof body?.error === "string" ? body.error
+            : body?.code;
+  return typeof raw === "string" ? raw.toLowerCase() : null;
+}
+
+/**
+ * Spend the refresh token. Never throws — every failure is a return value,
+ * because callers include a 60s background poll whose rejection would reach
+ * the HTTP router as an unhandled rejection and kill the process.
+ */
+async function doRefresh(auth) {
+  let res, body;
+  try {
+    res = await fetch(REFRESH_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_id:     CLIENT_ID,
+        grant_type:    "refresh_token",
+        refresh_token: auth.tokens.refresh_token,
+      }),
+      signal: AbortSignal.timeout(15_000),
+    });
+    body = await res.json().catch(() => null);
+  } catch {
+    // Network error or timeout: the server may or may not have rotated the
+    // token. Nothing is written, so the next attempt retries with what we
+    // have — the only safe move when the outcome is unknown.
+    return { ok: false, reason: "refresh_failed" };
+  }
+
+  if (!res.ok) {
+    const code = refreshErrorCode(body);
+    const permanent = (code && PERMANENT_CODES.has(code)) || res.status === 401;
+    return { ok: false, reason: permanent ? "refresh_rejected" : "refresh_failed", code };
+  }
+
+  // A 2xx whose body did not survive the trip (truncated response, captive
+  // portal, proxy error page) is NOT success: writing here would persist the
+  // old, now-consumed token plus a fresh `last_refresh`, reporting a working
+  // login while guaranteeing the next call fails as `refresh_token_reused`.
+  if (typeof body?.access_token !== "string" || body.access_token === "") {
+    return { ok: false, reason: "refresh_failed", code: "no_access_token" };
+  }
+
+  // Write back only the fields that came in, leaving the rest of auth.json
+  // (OPENAI_API_KEY, auth_mode, account_id, anything unknown) untouched.
+  const next = { ...auth, tokens: { ...auth.tokens } };
+  next.tokens.access_token = body.access_token;
+  if (body.id_token)      next.tokens.id_token      = body.id_token;
+  if (body.refresh_token) next.tokens.refresh_token = body.refresh_token;
+  next.last_refresh = new Date().toISOString();
+
+  try {
+    await persistAuth(next);
+  } catch (err) {
+    // The rotated token exists server-side but never reached disk. Say so
+    // plainly — the credential on disk is now dead and only a re-login fixes
+    // it, so reporting a transient failure would just mislead.
+    console.error("agents-deck codex-auth: could not write auth.json:", err?.message ?? err);
+    return { ok: false, reason: "refresh_rejected", code: "persist_failed" };
+  }
+
+  return { ok: true, auth: next };
+}
+
+// Refreshes run strictly one at a time per process. A queue rather than a
+// shared promise: callers that arrive during a refresh must be able to make
+// their own decision afterwards (see the staleness checks below) instead of
+// inheriting a result produced before their token failed.
+let _chain = Promise.resolve();
+function serialize(fn) {
+  const run = _chain.then(fn, fn);
+  _chain = run.then(() => {}, () => {});
+  return run;
+}
+
+/**
+ * Refresh under the lock.
+ *
+ * `ifStale` — only refresh when the credentials on disk still look expiring.
+ * `staleAccessToken` — only refresh when disk still holds the token the caller
+ * saw fail. Both exist for the same reason: auth.json is re-read *inside* the
+ * lock, so a caller that queued behind another refresh discovers it already
+ * got what it needed and does not spend a second single-use token.
+ */
+function refreshCredentials({ ifStale = false, staleAccessToken = null } = {}) {
+  return serialize(async () => {
+    const auth = await readAuthFile();
+    if (!auth?.tokens?.refresh_token) return { ok: false, reason: "no_token" };
+    if (ifStale && !shouldRefresh(auth)) return { ok: true, auth };
+    if (staleAccessToken && auth.tokens.access_token !== staleAccessToken) {
+      return { ok: true, auth };  // someone else already rotated past it
+    }
+    return doRefresh(auth);
+  });
+}
+
+function identityFrom(auth, refreshed) {
+  // Claims live in the id_token, not the access token. account_id is seeded at
+  // login into tokens.account_id; the id_token claim is the fallback for
+  // credential files written before that field existed.
+  const claims = decodeJwt(auth.tokens.id_token) ?? {};
+  const oai    = claims["https://api.openai.com/auth"] ?? {};
+  return {
+    ok:          true,
+    accessToken: auth.tokens.access_token,
+    accountId:   auth.tokens.account_id ?? oai.chatgpt_account_id ?? null,
+    isFedramp:   oai.chatgpt_account_is_fedramp === true,
+    planType:    oai.chatgpt_plan_type ?? null,
+    email:       claims.email ?? null,
+    refreshed,
+  };
+}
+
+/**
+ * Current Codex credentials, refreshed if needed.
+ *
+ * Returns { ok: true, accessToken, accountId, … } or { ok: false, reason }
+ * where reason is `no_token` (never logged in) / `refresh_rejected` (re-login
+ * required) / `refresh_failed` (transient). Never throws.
+ */
+export async function getCodexAuth({ allowRefresh = true } = {}) {
+  let auth = await readAuthFile();
+
+  // An `OPENAI_API_KEY` login is a platform credential, not a ChatGPT session.
+  // Flagged rather than rejected so the caller can say so plainly instead of
+  // sending the key to chatgpt.com and reporting the resulting 401 as a bug.
+  const apiKey = typeof auth?.OPENAI_API_KEY === "string" ? auth.OPENAI_API_KEY.trim() : "";
+  if (auth?.auth_mode === "apikey" || (apiKey && !auth?.tokens?.access_token)) {
+    return { ok: true, apiKeyMode: true, accessToken: null, accountId: null };
+  }
+
+  if (!auth?.tokens?.access_token) return { ok: false, reason: "no_token" };
+
+  let refreshed = false;
+  if (allowRefresh && shouldRefresh(auth)) {
+    const r = await refreshCredentials({ ifStale: true });
+    if (!r.ok) return r;
+    refreshed = r.auth.tokens.access_token !== auth.tokens.access_token;
+    auth = r.auth;
+  }
+
+  return identityFrom(auth, refreshed);
+}
+
+/**
+ * Refresh because the backend rejected a token that looked valid locally —
+ * OpenAI revokes server-side, so the JWT's own `exp` is not the last word.
+ *
+ * Pass the access token that was rejected: if disk has already moved past it
+ * (a concurrent refresh, or the Codex CLI), this returns the newer credentials
+ * without spending another single-use refresh token.
+ */
+export async function forceCodexRefresh(rejectedAccessToken = null) {
+  const r = await refreshCredentials({ staleAccessToken: rejectedAccessToken });
+  return r.ok ? identityFrom(r.auth, true) : r;
+}

package/src/server/codex-quota.mjs

@@ -1,111 +1,321 @@
-// Fetches Codex/ChatGPT quota percentages from chatgpt.com/backend-api/wham/usage.
-// Auth: reads access_token from ~/.codex/auth.json (written by the Codex CLI login).
-// Returns the same shape as Claude quota so the UI can use identical QuotaBar components.
+// Fetches Codex/ChatGPT quota from the same endpoint the Codex CLI uses.
+// Auth (including token refresh) lives in codex-auth.mjs.
+//
+// The response is deliberately parsed defensively: OpenAI ships new plan
+// types, new limit families and new numeric encodings without warning, and a
+// menu-bar-style readout is worth more when it degrades to "some lanes" than
+// when one unrecognised field blanks the whole panel. So every section is
+// optional, unknown values pass through verbatim, and a `partial` flag tells
+// the UI when something was dropped instead of silently showing less.
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import { getCodexAuth, forceCodexRefresh } from "./codex-auth.mjs";
 
-const CODEX_HOME = process.env.CODEX_HOME ?? join(homedir(), ".codex");
-const AUTH_PATH   = join(CODEX_HOME, "auth.json");
-const WHAM_URL    = "https://chatgpt.com/backend-api/wham/usage";
+const CODEX_HOME  = process.env.CODEX_HOME ?? join(homedir(), ".codex");
+const CONFIG_PATH = join(CODEX_HOME, "config.toml");
+const DEFAULT_BASE = "https://chatgpt.com/backend-api";
 
-let _cache    = null;
-let _cacheAt  = 0;
+let _cache   = null;
+let _cacheAt = 0;
 const CACHE_MS = 60_000;
 
-async function readAccessToken() {
+// ── base URL ───────────────────────────────────────────────────────────────
+// `chatgpt_base_url` in config.toml can point at a proxy, and the path style
+// follows from its shape exactly as in the CLI: a /backend-api base speaks
+// /wham/*, anything else speaks /api/codex/*.
+async function readBaseUrl() {
+  let raw = null;
   try {
-    const raw  = await readFile(AUTH_PATH, "utf8");
-    const auth = JSON.parse(raw);
-    return auth?.tokens?.access_token ?? null;
-  } catch {
-    return null;
+    const text = await readFile(CONFIG_PATH, "utf8");
+    for (const line of text.split("\n")) {
+      const m = line.replace(/#.*$/, "").match(/^\s*chatgpt_base_url\s*=\s*(.+?)\s*$/);
+      if (m) { raw = m[1].replace(/^["']|["']$/g, "").trim(); break; }
+    }
+  } catch { /* no config.toml — use the default */ }
+
+  let base = (raw || DEFAULT_BASE).replace(/\/+$/, "");
+  if (/^https:\/\/(chatgpt\.com|chat\.openai\.com)/.test(base) && !base.includes("/backend-api")) {
+    base += "/backend-api";
+  }
+  return base;
+}
+
+function usagePath(base)        { return base.includes("/backend-api") ? "/wham/usage" : "/api/codex/usage"; }
+function resetCreditsPath(base) { return base.includes("/backend-api") ? "/wham/rate-limit-reset-credits" : "/api/codex/rate-limit-reset-credits"; }
+
+// ── lenient field readers ──────────────────────────────────────────────────
+// Team and enterprise payloads send numbers as strings ("limit": "1000"), and
+// reset timestamps answer to three different spellings depending on which
+// sub-object you are in.
+function num(v) {
+  if (typeof v === "number") return Number.isFinite(v) ? v : null;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    return Number.isFinite(n) ? n : null;
   }
+  return null;
+}
+function resetAt(o) {
+  return num(o?.resets_at) ?? num(o?.resetsAt) ?? num(o?.reset_at) ?? null;
 }
 
-// Format a unix timestamp into "Jun 18, 4:09pm" style (same as claude quota output).
+/** "Jun 18, 4:09pm" — matches the Claude quota formatting so both read alike. */
 function fmtReset(unixSec) {
   if (!unixSec) return null;
-  const d = new Date(unixSec * 1000);
-  return d.toLocaleString("en-US", {
-    month: "short",
-    day:   "numeric",
-    hour:  "numeric",
-    minute: "2-digit",
-    hour12: true,
+  return new Date(unixSec * 1000).toLocaleString("en-US", {
+    month: "short", day: "numeric", hour: "numeric", minute: "2-digit", hour12: true,
   }).replace(",", "").toLowerCase().replace(/\s+am/, "am").replace(/\s+pm/, "pm");
 }
 
-export async function fetchCodexQuota({ force = false } = {}) {
-  const now = Date.now();
-  if (!force && _cache && now - _cacheAt < CACHE_MS) return _cache;
+// ── window classification ──────────────────────────────────────────────────
+// Slot position is NOT the lane. Free plans return a weekly window in the
+// primary slot, and a 30-day lane can arrive in either slot — labelling by
+// slot is how a weekly cap ends up displayed as a 5-hour one. Duration is the
+// only trustworthy signal.
+const HOUR = 3600;
+function laneFor(windowSec) {
+  if (windowSec == null || windowSec <= 0) return { key: "unknown", label: "Rate limit", rank: 9 };
+  if (windowSec <= 6 * HOUR)       return { key: "session", label: `${Math.round(windowSec / HOUR)}-hour window`, rank: 0 };
+  if (windowSec <= 8 * 24 * HOUR)  return { key: "weekly",  label: "7-day window",  rank: 1 };
+  return { key: "monthly", label: "30-day window", rank: 2 };
+}
+
+/** One rate-limit lane, or null when the window carries no usable reading. */
+function toWindow(w, idFallback) {
+  const pct = num(w?.used_percent ?? w?.usedPercent);
+  if (pct == null) return null;
+  const windowSec = num(w?.limit_window_seconds ?? w?.limitWindowSeconds);
+  const lane      = laneFor(windowSec);
+  const reset     = resetAt(w);
+  return {
+    id:         idFallback ? `${idFallback}-${lane.key}` : lane.key,
+    key:        lane.key,
+    label:      lane.label,
+    rank:       lane.rank,
+    pct,                                   // never clamped — over-quota is real information
+    windowSec:  windowSec ?? null,
+    resetAt:    reset,
+    reset:      fmtReset(reset),
+  };
+}
+
+/** Both slots of a rate_limit object, ordered by lane rather than by slot. */
+function windowsFrom(rl, idPrefix) {
+  return [toWindow(rl?.primary_window, idPrefix), toWindow(rl?.secondary_window, idPrefix)]
+    .filter(Boolean)
+    .sort((a, b) => a.rank - b.rank);
+}
 
-  const token = await readAccessToken();
-  if (!token) {
-    const r = { ok: false, reason: "no_token", fetchedAt: now };
-    _cache = r; _cacheAt = now;
-    return r;
+// ── spend control / monthly credit limit ───────────────────────────────────
+// Three places can carry it, in this precedence. Whichever answers first wins.
+function creditLimitFrom(data) {
+  const src = data?.individual_limit
+           ?? data?.rate_limit?.individual_limit
+           ?? data?.spend_control?.individual_limit;
+  const limit = num(src?.limit);
+  if (!limit || limit <= 0) return null;
+
+  const remainingPct = num(src?.remaining_percent ?? src?.remainingPercent);
+  const used = num(src?.used) ?? (remainingPct != null ? limit * Math.max(0, Math.min(100, 100 - remainingPct)) / 100 : 0);
+  const pct  = remainingPct != null ? Math.max(0, Math.min(100, 100 - remainingPct)) : (used / limit) * 100;
+  const reset = resetAt(src);
+
+  return {
+    limit,
+    used,
+    usedPct:   pct,
+    remaining: num(src?.remaining) ?? Math.max(0, limit - used),
+    source:    src?.source ?? null,
+    resetAt:   reset,
+    reset:     fmtReset(reset),
+  };
+}
+
+// ── plan labels ────────────────────────────────────────────────────────────
+// OpenAI's marketing names, since "pro" alone tells the user nothing about
+// which of the two Pro tiers they are on.
+const PLAN_LABELS = { pro: "Pro 20x", prolite: "Pro 5x", pro_lite: "Pro 5x", "pro-lite": "Pro 5x" };
+function planLabel(plan) {
+  if (!plan || typeof plan !== "string") return null;
+  const k = plan.toLowerCase().replace(/\s+/g, "_");
+  if (PLAN_LABELS[k]) return PLAN_LABELS[k];
+  if (k === "k12" || k === "cbp") return k.toUpperCase();
+  return k.split(/[_-]/).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join(" ");
+}
+
+// ── extra limit families (Codex Spark and friends) ────────────────────────
+// `additional_rate_limits` is an ARRAY of {limit_name, metered_feature,
+// rate_limit}, not a map. Decoded element-wise so one malformed entry costs
+// only itself.
+function extraLimits(data) {
+  const arr = data?.additional_rate_limits;
+  if (!Array.isArray(arr)) return { extras: [], damaged: arr != null };
+
+  const extras = [];
+  let damaged = false;
+  for (const entry of arr) {
+    try {
+      const slug = String(entry?.metered_feature ?? entry?.limit_name ?? "extra")
+        .toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      const title = entry?.limit_name ?? entry?.metered_feature ?? "Codex extra limit";
+      for (const w of windowsFrom(entry?.rate_limit, slug)) {
+        extras.push({ ...w, label: `${title} · ${w.label}`, family: slug });
+      }
+    } catch { damaged = true; }
   }
+  return { extras, damaged };
+}
+
+// ── fetch ──────────────────────────────────────────────────────────────────
+function authHeaders(auth, { accountIdHeader = "ChatGPT-Account-Id", extra = {} } = {}) {
+  const h = {
+    "Authorization": `Bearer ${auth.accessToken}`,
+    "Accept":        "application/json",
+    "User-Agent":    "codex-cli",
+    ...extra,
+  };
+  if (auth.accountId) h[accountIdHeader] = auth.accountId;
+  if (auth.isFedramp) h["X-OpenAI-Fedramp"] = "true";
+  return h;
+}
 
-  let result;
+/**
+ * Reset credits ("one free rate limit reset" grants). Best-effort and short-
+ * timeout: it is a nice-to-have next to the gauges, never a reason to fail
+ * the quota read. Read-only — we never redeem.
+ */
+async function fetchResetCredits(base, auth) {
   try {
-    const res = await fetch(WHAM_URL, {
-      headers: {
-        "Authorization": `Bearer ${token}`,
-        "Content-Type":  "application/json",
-        "User-Agent":    "Mozilla/5.0 (compatible; agents-deck)",
-      },
-      signal: AbortSignal.timeout(12_000),
+    const res = await fetch(base + resetCreditsPath(base), {
+      // This endpoint alone wants the uppercase-ID spelling and the beta
+      // headers; sending the wham/usage set here returns nothing useful.
+      headers: authHeaders(auth, {
+        accountIdHeader: "ChatGPT-Account-ID",
+        extra: { "OpenAI-Beta": "codex-1", "originator": "Codex Desktop" },
+      }),
+      signal: AbortSignal.timeout(5_000),
     });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const count = num(body?.available_count);
+    if (count == null || count < 0) return null;
+    const next = (body?.credits ?? [])
+      .filter(c => c?.status === "available" && c?.expires_at)
+      .map(c => Date.parse(c.expires_at))
+      .filter(t => !isNaN(t))
+      .sort((a, b) => a - b)[0] ?? null;
+    return { availableCount: count, nextExpiryAt: next };
+  } catch { return null; }
+}
 
-    if (!res.ok) {
-      const r = { ok: false, reason: `http_${res.status}`, fetchedAt: now };
-      _cache = r; _cacheAt = now;
-      return r;
+async function requestUsage(base, auth) {
+  return fetch(base + usagePath(base), {
+    headers: authHeaders(auth),
+    // Quota is per-account state; a cached response is how one account's
+    // gauges end up shown for another.
+    cache: "no-store",
+    signal: AbortSignal.timeout(12_000),
+  });
+}
+
+// One outstanding fetch at a time. Several browser tabs mounting at once
+// otherwise each force their own round trip — and each one is another chance
+// to race over the single-use refresh token.
+let _inflight = null;
+
+export function fetchCodexQuota({ force = false } = {}) {
+  if (!force && _cache && Date.now() - _cacheAt < CACHE_MS) return Promise.resolve(_cache);
+  _inflight ??= doFetchCodexQuota().finally(() => { _inflight = null; });
+  return _inflight;
+}
+
+async function doFetchCodexQuota() {
+  const started = Date.now();
+  // Stamped at completion, not at entry: the two calls below can take up to
+  // 17s between them, and a cache entry that is already stale on arrival
+  // shortens the effective TTL for no reason.
+  const finish = (r) => { _cache = r; _cacheAt = Date.now(); return r; };
+  const fail   = (reason) => finish({ ok: false, reason, fetchedAt: started });
+
+  let auth, base, res;
+  try {
+    auth = await getCodexAuth();
+    if (!auth.ok) return fail(auth.reason);
+
+    // An API key in auth.json is a platform credential, not a ChatGPT session —
+    // sending it here only produces a confusing 401.
+    if (auth.apiKeyMode) return fail("api_key_mode");
+
+    base = await readBaseUrl();
+    res  = await requestUsage(base, auth);
+
+    // The JWT's own `exp` is not the last word: OpenAI revokes server-side, so
+    // a token that looks valid locally can still come back expired. One forced
+    // refresh + retry turns that from "bar goes dark" into a hiccup.
+    //
+    // 401 only. A 403 from chatgpt.com is usually a bot check or a blocked
+    // egress IP rather than a bad token, and rotating a single-use credential
+    // once a minute against a network-layer block is how a working login gets
+    // destroyed.
+    if (res.status === 401) {
+      const refreshed = await forceCodexRefresh(auth.accessToken);
+      if (!refreshed.ok) return fail(refreshed.reason);
+      auth = refreshed;
+      res  = await requestUsage(base, auth);
     }
 
-    const data = await res.json();
-    const rl   = data?.rate_limit;
-    const pw   = rl?.primary_window;    // 5-hour session window
-    const sw   = rl?.secondary_window;  // 7-day weekly window
-
-    const creds = data?.credits;
-    result = {
-      ok:                  true,
-      limitReached:        rl?.limit_reached ?? false,
-      session5hPct:        pw?.used_percent        ?? null,
-      session5hReset:      pw?.reset_at ? fmtReset(pw.reset_at) : null,
-      session5hResetAt:    pw?.reset_at             ?? null,  // unix seconds
-      session5hWindowSec:  pw?.limit_window_seconds ?? 18000,
-      week7dPct:           sw?.used_percent        ?? null,
-      week7dReset:         sw?.reset_at ? fmtReset(sw.reset_at) : null,
-      week7dResetAt:       sw?.reset_at             ?? null,  // unix seconds
-      week7dWindowSec:     sw?.limit_window_seconds ?? 604800,
-      // credits (ChatGPT Plus top-up credits if any)
-      creditsBalance:      creds?.has_credits ? creds.balance : null,
-      creditsUnlimited:    creds?.unlimited   ?? false,
-      planType:            data?.plan_type    ?? null,
-      fetchedAt:           now,
-    };
-
-    // Additional model-specific limits (e.g. Codex Spark)
-    const extra = rl?.additional_rate_limits;
-    if (extra && typeof extra === "object") {
-      for (const [key, win] of Object.entries(extra)) {
-        if (win?.used_percent != null) {
-          result[`extra_${key}_pct`]   = win.used_percent;
-          if (win.reset_at) result[`extra_${key}_reset`] = fmtReset(win.reset_at);
-        }
-      }
+    if (!res.ok) {
+      return fail(res.status === 401 ? "refresh_rejected" : `http_${res.status}`);
     }
   } catch (err) {
     console.error("agents-deck codex-quota: fetch failed:", err?.message ?? err);
-    result = { ok: false, reason: "fetch_error", fetchedAt: now };
+    return fail("fetch_error");
   }
 
-  _cache = result;
-  _cacheAt = now;
-  return result;
+  let data;
+  try { data = await res.json(); }
+  catch { return fail("decode_error"); }
+
+  const rl              = data?.rate_limit;
+  const windows         = windowsFrom(rl);
+  const { extras, damaged } = extraLimits(data);
+  const creditsRaw      = data?.credits;
+  const balance         = num(creditsRaw?.balance);
+
+  const result = {
+    ok:           true,
+    limitReached: rl?.limit_reached ?? false,
+    allowed:      rl?.allowed ?? true,
+
+    // Lanes, already ordered session → weekly → monthly and labelled by the
+    // window duration the API actually reported.
+    windows,
+    extraWindows: extras,
+
+    plan:      data?.plan_type ?? auth.planType ?? null,
+    planLabel: planLabel(data?.plan_type ?? auth.planType),
+    email:     data?.email ?? auth.email ?? null,
+
+    creditsBalance:   balance != null && balance > 0 ? String(creditsRaw.balance) : null,
+    creditsUnlimited: creditsRaw?.unlimited === true,
+    overageReached:   creditsRaw?.overage_limit_reached === true,
+    creditLimit:      creditLimitFrom(data),
+
+    spendControlReached: data?.spend_control?.reached === true,
+    reachedType:         data?.rate_limit_reached_type?.type ?? data?.rate_limit_reached_type ?? null,
+    promo:               data?.promo?.message ?? null,
+
+    // True when something in the payload did not decode — the UI says "partial"
+    // rather than pretending the missing lanes do not exist.
+    partial:   damaged || windows.length === 0,
+    refreshed: auth.refreshed === true,
+    fetchedAt: started,
+  };
+
+  result.resetCredits = await fetchResetCredits(base, auth);
+
+  return finish(result);
 }
 
 export function invalidateCodexQuotaCache() {