@iislee/opencodex 2.11.0 → 2.35.0

package/src/codex/prompt-lock.ts

@@ -0,0 +1,143 @@
+/**
+ * prompt-lock.ts — advisory cross-process lock for prompt-layer mutations.
+ *
+ * An in-process mutex only serialises browser tabs behind one service. A CLI
+ * invocation, a second service, or a stale process can all reach the same
+ * files, so the lock lives on disk.
+ *
+ * STALE TAKEOVER IS A RENAME, NOT AN UNLINK. Naive breaking is racy: A judges
+ * the lock stale, B removes it and acquires its own, then A unlinks *B's live
+ * lock* and both proceed. Unlinking a path you did not verify is the bug. Here
+ * the contender renames the observed stale lock to a token-quarantined name —
+ * an atomic operation exactly one contender can win — and only the winner
+ * creates the real lock.
+ *
+ * RELEASE ONLY DELETES A LOCK WHOSE TOKEN IS STILL OURS. A mismatch means we
+ * were superseded, and deleting it would hand the critical section to two
+ * writers at once.
+ *
+ * This does NOT cover Codex, which knows nothing about our lock. That residual
+ * is handled by the per-target byte checks in the write path, and the rename
+ * window itself is documented as irreducible from user space.
+ */
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+
+const FILE_MODE = 0o600;
+
+/** A lock younger than this is respected even if its pid looks gone. */
+export const STALE_AFTER_MS = 10_000;
+
+export interface LockRecord {
+  token: string;
+  pid: number;
+  acquiredAt: number;
+}
+
+export interface LockHandle {
+  path: string;
+  token: string;
+}
+
+export type AcquireResult =
+  | { ok: true; handle: LockHandle }
+  | { ok: false; error: "locked" };
+
+export interface LockDeps {
+  /** Injectable so tests can simulate a live or dead owner. */
+  isProcessAlive: (pid: number) => boolean;
+  now: () => number;
+}
+
+const defaultDeps: LockDeps = {
+  isProcessAlive: pid => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // EPERM means it exists but belongs to another user.
+      return (error as NodeJS.ErrnoException).code === "EPERM";
+    }
+  },
+  now: () => Date.now(),
+};
+
+function readRecord(path: string): LockRecord | null {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as LockRecord;
+    if (typeof parsed?.token !== "string" || typeof parsed?.pid !== "number") return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/** True when the holder is gone AND the lock is older than the grace window. */
+function isStale(record: LockRecord | null, deps: LockDeps): boolean {
+  if (record === null) return true; // unparseable: treat as debris
+  if (deps.isProcessAlive(record.pid)) return false;
+  return deps.now() - record.acquiredAt > STALE_AFTER_MS;
+}
+
+/**
+ * One attempt. The caller decides whether to retry — a loser must go back to
+ * re-reading the lock rather than assuming its quarantine still applies.
+ */
+export function tryAcquire(path: string, deps: LockDeps = defaultDeps): AcquireResult {
+  const token = randomBytes(8).toString("hex");
+  const record: LockRecord = { token, pid: process.pid, acquiredAt: deps.now() };
+  const body = JSON.stringify(record);
+
+  try {
+    writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+    return { ok: true, handle: { path, token } };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+  }
+
+  if (!isStale(readRecord(path), deps)) return { ok: false, error: "locked" };
+
+  // Quarantine by rename: atomic, and exactly one contender wins it.
+  const quarantine = `${path}.stale-${token}`;
+  try {
+    renameSync(path, quarantine);
+  } catch {
+    // Someone else won the rename, or the owner released between our checks.
+    // Either way we do NOT touch the path — retry from the top.
+    return { ok: false, error: "locked" };
+  }
+
+  try {
+    writeFileSync(path, body, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
+  } catch (error) {
+    // A successor acquired the real lock between our rename and this create.
+    // Its lock is live and is not ours to remove.
+    try { unlinkSync(quarantine); } catch { /* debris */ }
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return { ok: false, error: "locked" };
+    throw error;
+  }
+
+  try { unlinkSync(quarantine); } catch { /* debris */ }
+  return { ok: true, handle: { path, token } };
+}
+
+/**
+ * Release. Deletes nothing unless the on-disk token is still ours; returns false
+ * when we were superseded, which the caller surfaces as `write_superseded`.
+ */
+export function release(handle: LockHandle): boolean {
+  const record = readRecord(handle.path);
+  if (record === null || record.token !== handle.token) return false;
+  try {
+    unlinkSync(handle.path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** True when the on-disk lock is still the one this handle acquired. */
+export function stillHeld(handle: LockHandle): boolean {
+  if (!existsSync(handle.path)) return false;
+  return readRecord(handle.path)?.token === handle.token;
+}

package/src/codex/prompt-text-probe.ts

@@ -0,0 +1,238 @@
+/**
+ * Reading the prompt text Codex actually assembles.
+ *
+ * The read-only dialog used to say Codex "does not expose" a layer's text. That
+ * was wrong: Codex is open source and ships `codex debug prompt-input`, which
+ * renders the model-visible input list as JSON. Reading it is the difference
+ * between describing a layer and showing it.
+ *
+ * What this does NOT cover, stated rather than implied:
+ *
+ * - `base-instructions` is absent. `prompt_debug.rs` returns `prompt.input` and
+ *   discards `base_instructions`, so the base prompt never appears here.
+ * - World-state sections are DIFF-rendered (`add_section` registers state, it does
+ *   not emit text). A section that renders nothing on a first turn is missing
+ *   from this output even though its layer exists.
+ * - The output reflects the invoking directory and the current config, not a
+ *   universal prompt.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { resolveCodexHomeDir } from "./home";
+
+/**
+ * Layer id -> the tag Codex actually renders it under.
+ *
+ * Every entry here was read off live `codex debug prompt-input` output across the
+ * feature flags that enable each section. None is inferred from the Rust section
+ * `ID` constants: those are identifiers for diffing, not wrapper tags, and an
+ * earlier guess from them mapped `permissions` to the wrong name while the real
+ * tag - `permissions instructions`, with a space - went unmatched.
+ *
+ * A layer absent from this map is reported as unsupported, never as silent.
+ */
+const LAYER_SECTION_TAGS: Record<string, string> = {
+  skills: "skills_instructions",
+  apps: "apps_instructions",
+  plugins: "plugins_instructions",
+  environment: "environment_context",
+  permissions: "permissions instructions",
+  // Synthetic: the project doc carries no tag of its own (see extractSections).
+  "agents-md": "__agents_md",
+};
+
+/**
+ * Inventory ids with no confirmed tag in the rendered output. They are listed
+ * explicitly rather than left missing: an absent entry made the dialog report a
+ * successful probe as unavailable.
+ */
+const UNMAPPED_LAYER_IDS = [
+  "model-switch",
+  "context-window-guidance",
+  "environments-instructions",
+  "tools",
+  "multi-agent-mode",
+  // Confirmed absent from live output under their own feature flags, so the
+  // previous `personality` / `realtime` guesses reported these as silent when the
+  // truth is that this extractor has no verified tag for them.
+  "personality",
+  "realtime",
+  "collaboration",
+  // The Rust source names a <git_attribution> marker pair, but a world-state section is
+  // DIFF-rendered: it emits nothing on a turn where its state has not changed. Live
+  // `codex debug prompt-input` (codex-cli 0.145.0, 32978 bytes) showed no such block and
+  // no attribution text. Listing the id here reports "not exposed" honestly instead of
+  // claiming a tag this extractor has never actually matched - the same mistake the
+  // header above records for permissions.
+  "git-attribution",
+] as const;
+
+export interface LayerText {
+  /** Rendered text, when this layer produced a section on the probed turn. */
+  text: string | null;
+  /** Why the text is absent, when it is. */
+  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unavailable";
+  bytes: number;
+  /** For `empty-source`: the file that exists but has nothing in it. */
+  sourcePath?: string;
+}
+
+export interface PromptTextProbe {
+  ok: boolean;
+  /** The Codex home the probe reported on. */
+  codexHome: string;
+  layers: Record<string, LayerText>;
+  detail?: string;
+}
+
+function resolveCodexBinary(): string | null {
+  const candidates = [
+    join(homedir(), ".codex/packages/standalone/current/bin/codex"),
+    join(homedir(), ".local/bin/codex"),
+    "/usr/local/bin/codex",
+    "/opt/homebrew/bin/codex",
+  ];
+  return candidates.find(path => existsSync(path)) ?? null;
+}
+
+/** 8 MiB is far above any real prompt and far below anything that hurts the server. */
+const MAX_PROBE_OUTPUT_BYTES = 8 * 1024 * 1024;
+
+function runProbe(binary: string, cwd: string, timeoutMs: number): Promise<string | null> {
+  return new Promise(resolve => {
+    // A probe must never hang OR balloon the management API: it is bounded in
+    // time AND in bytes, and every failure degrades to "unavailable" rather than
+    // an error page.
+    const child = spawn(binary, ["debug", "prompt-input"], {
+      cwd,
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const chunks: Buffer[] = [];
+    let size = 0;
+    let settled = false;
+    // One settlement path: a timeout that resolved before `close` used to leave
+    // the child streaming into a buffer nobody would ever read.
+    const settle = (value: string | null) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      child.stdout?.destroy();
+      if (child.exitCode === null && child.signalCode === null) child.kill("SIGKILL");
+      resolve(value);
+    };
+    const timer = setTimeout(() => settle(null), timeoutMs);
+    child.stdout?.on("data", (chunk: Buffer) => {
+      size += chunk.length;
+      if (size > MAX_PROBE_OUTPUT_BYTES) { settle(null); return; }
+      chunks.push(chunk);
+    });
+    child.on("error", () => settle(null));
+    child.on("close", code => {
+      // Decode once, at the end: `String(chunk)` per chunk corrupts any UTF-8
+      // character that straddles a chunk boundary.
+      settle(code === 0 ? Buffer.concat(chunks).toString("utf8") : null);
+    });
+  });
+}
+
+/** Pull every `<tag>...</tag>` section out of the rendered developer messages. */
+function extractSections(raw: string): Map<string, string> {
+  const sections = new Map<string, string>();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return sections;
+  }
+  if (!Array.isArray(parsed)) return sections;
+  for (const item of parsed) {
+    const content = (item as { content?: unknown }).content;
+    if (!Array.isArray(content)) continue;
+    const text = content.map(part => String((part as { text?: unknown }).text ?? "")).join("");
+    // Tag names are NOT all snake_case: Codex renders `<permissions instructions>`
+    // with a space. A `[a-z_]+` pattern silently skipped it, and the layer was
+    // reported as "sent nothing" while its text sat right there.
+    for (const match of text.matchAll(/<([a-zA-Z_][a-zA-Z0-9_ -]*)>([\s\S]*?)<\/\1>/g)) {
+      sections.set(match[1]!, match[2]!.trim());
+    }
+    // AGENTS.md is NOT tagged: it arrives as a plain `# AGENTS.md instructions
+    // for <path>` block among the tagged sections. Matching only on tags would
+    // report the layer as unrendered while its text sits in the same message.
+    //
+    // Bounded at both ends. Capturing to end-of-message swept up any unrelated
+    // untagged prose that happened to follow, and stripping tag-shaped blocks
+    // first also deleted XML-like text the user had written INSIDE their own
+    // AGENTS.md. Codex wraps the body in <INSTRUCTIONS>, so that is the boundary.
+    // No line anchor: the block is concatenated directly onto the previous
+    // section's closing tag, so requiring a newline before it never matched.
+    const projectDoc = /# AGENTS\.md instructions for [^\n]*\n+<INSTRUCTIONS>\n?([\s\S]*?)\n?<\/INSTRUCTIONS>/.exec(text);
+    if (projectDoc) sections.set("__agents_md", projectDoc[1]!.trim());
+  }
+  return sections;
+}
+
+/** Test seam: the extraction is the part worth pinning, not the spawn. */
+export const extractSectionsForTests = extractSections;
+
+/**
+ * Probe once and map every known layer to its rendered text.
+ *
+ * `cwd` matters: AGENTS.md and environment context are directory-dependent, so a
+ * probe from the wrong place would describe a prompt the user never sees.
+ */
+export async function probePromptText(timeoutMs = 15_000): Promise<PromptTextProbe> {
+  // The probe runs in CODEX_HOME, never in a caller-supplied directory. A `cwd`
+  // parameter let an authenticated request read any readable folder's AGENTS.md,
+  // and it also described a prompt that depends on where Codex happened to run.
+  // The global home is the one context this page can honestly report on.
+  const codexHome = resolveCodexHomeDir();
+  const binary = resolveCodexBinary();
+  if (!binary) {
+    return { ok: false, codexHome, layers: {}, detail: "codex binary not found" };
+  }
+  const raw = await runProbe(binary, codexHome, timeoutMs);
+  if (raw === null) {
+    return { ok: false, codexHome, layers: {}, detail: "codex debug prompt-input failed" };
+  }
+  const sections = extractSections(raw);
+  if (sections.size === 0) {
+    // Zero sections from a zero-exit probe means the output did not parse, which
+    // is a failed read - not fifteen layers that each chose to send nothing.
+    return { ok: false, codexHome, layers: {}, detail: "prompt output could not be parsed" };
+  }
+  const layers: Record<string, LayerText> = {};
+  for (const [layerId, tag] of Object.entries(LAYER_SECTION_TAGS)) {
+    const text = sections.get(tag) ?? null;
+    layers[layerId] = text === null
+      // Registered but not rendered on this turn, which is an ordinary state for
+      // a diff-rendered section rather than an error.
+      ? { text: null, reason: "not-rendered", bytes: 0 }
+      : { text, reason: "ok", bytes: Buffer.byteLength(text, "utf8") };
+  }
+
+  // A file that exists and is empty is not the same as a layer that chose to send
+  // nothing. Reporting "sent nothing" for an empty AGENTS.md tells the user their
+  // layer is idle when the real answer is that the file they wrote is blank.
+  const agentsMdPath = join(codexHome, "AGENTS.md");
+  if (layers["agents-md"]?.reason === "not-rendered" && existsSync(agentsMdPath)) {
+    try {
+      if (statSync(agentsMdPath).size === 0) {
+        layers["agents-md"] = { text: null, reason: "empty-source", bytes: 0, sourcePath: agentsMdPath };
+      }
+    } catch {
+      // An unreadable file stays "not-rendered": we cannot claim it is empty.
+    }
+  }
+  // The base prompt travels outside prompt.input and cannot be read this way.
+  layers["base-instructions"] = { text: null, reason: "not-exposed", bytes: 0 };
+
+  // Layers whose rendered tag we have not confirmed against live output. Leaving
+  // them absent made the GUI fall through to "unavailable", which claims the probe
+  // failed when it succeeded. Saying we have no mapping is the smaller claim.
+  for (const id of UNMAPPED_LAYER_IDS) {
+    layers[id] ??= { text: null, reason: "not-exposed", bytes: 0 };
+  }
+  return { ok: true, codexHome, layers };
+}

package/src/codex/quota-rejection.ts

@@ -0,0 +1,298 @@
+import { readBoundedResponseBody } from "../lib/bounded-body";
+
+const RESET_ELIGIBLE_CODE_VALUES = [
+  "usage_limit_exceeded",
+  "insufficient_quota",
+] as const;
+
+export type CodexResetEligibleExhaustionCode =
+  (typeof RESET_ELIGIBLE_CODE_VALUES)[number];
+
+export type CodexPreStreamRejectionKind =
+  | "reset-eligible-exhaustion"
+  | "generic-rate-limit"
+  | "unverified-billing-or-quota"
+  | "transient-server-error"
+  | "authentication-error"
+  | "permission-error"
+  | "other";
+
+export interface CodexPreStreamRejection {
+  kind: CodexPreStreamRejectionKind;
+  status: number;
+  alternateRetryEligible: boolean;
+  resetCreditEligible: boolean;
+  semanticCode?: CodexResetEligibleExhaustionCode;
+  /**
+   * Structured denial evidence for a 403. Present only when the upstream body names a
+   * workspace/entitlement denial, which proves the CREDENTIAL is valid and the account
+   * simply lacks access here (#1789). Status alone can never set this.
+   */
+  denial?: "workspace" | "entitlement";
+}
+
+/**
+ * Upstream codes that identify a WORKSPACE denial rather than a bad credential.
+ *
+ * #1789: a K12 account whose credential validates and whose WHAM usage returns 200 still
+ * gets 403 `codex_workspace_access_denied` on a routed prompt. Treating that as a credential
+ * failure tells the user to re-authenticate a credential that is already valid, and the loop
+ * repeats forever.
+ */
+const WORKSPACE_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "codex_workspace_access_denied",
+  "workspace_access_denied",
+]);
+
+const ENTITLEMENT_DENIAL_CODES: ReadonlySet<string> = new Set([
+  "codex_entitlement_missing",
+  "entitlement_missing",
+]);
+
+/** Read a structured denial code out of a 403 body. Fails closed to undefined. */
+async function denialFromResponse(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<"workspace" | "entitlement" | undefined> {
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    if (isUnsafeJsonDocument(body.text)) return undefined;
+    const payload = JSON.parse(body.text) as unknown;
+    const code = structuredDenialCode(payload);
+    if (code === undefined) return undefined;
+    if (WORKSPACE_DENIAL_CODES.has(code)) return "workspace";
+    if (ENTITLEMENT_DENIAL_CODES.has(code)) return "entitlement";
+    return undefined;
+  } catch {
+    // Same fail-closed rule as the exhaustion classifier: an unreadable body must not
+    // downgrade a credential failure into a workspace one.
+    return undefined;
+  }
+}
+
+function ownStringField(container: Record<string, unknown>, field: string): string | undefined {
+  const descriptor = Object.getOwnPropertyDescriptor(container, field);
+  return descriptor && "value" in descriptor && typeof descriptor.value === "string"
+    ? descriptor.value
+    : undefined;
+}
+
+/** Own-property `code` lookup at the top level or under `error` / `detail`. No coercion or accessors. */
+function structuredDenialCode(payload: unknown): string | undefined {
+  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const record = payload as Record<string, unknown>;
+  const direct = ownStringField(record, "code");
+  if (direct !== undefined) return direct;
+
+  for (const field of ["error", "detail"] as const) {
+    const descriptor = Object.getOwnPropertyDescriptor(record, field);
+    if (!descriptor || !("value" in descriptor)) continue;
+    const nested = descriptor.value;
+    if (nested === null || typeof nested !== "object" || Array.isArray(nested)) continue;
+    const code = ownStringField(nested as Record<string, unknown>, "code");
+    if (code !== undefined) return code;
+  }
+  return undefined;
+}
+
+const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);
+
+const TRANSIENT_SERVER_STATUSES = new Set([500, 502, 503, 504, 520, 521, 522]);
+const JSON_NUMBER_PATTERN = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
+
+function rejection(
+  status: number,
+  kind: CodexPreStreamRejectionKind,
+  options: {
+    alternateRetryEligible?: boolean;
+    semanticCode?: CodexResetEligibleExhaustionCode;
+  } = {},
+): CodexPreStreamRejection {
+  return {
+    kind,
+    status,
+    alternateRetryEligible: options.alternateRetryEligible === true,
+    resetCreditEligible: options.semanticCode !== undefined,
+    ...(options.semanticCode ? { semanticCode: options.semanticCode } : {}),
+  };
+}
+
+function hasOwnField(container: Record<string, unknown>, field: string): boolean {
+  return Object.prototype.hasOwnProperty.call(container, field);
+}
+
+type JsonScanResult = {
+  next: number;
+  duplicate: boolean;
+};
+
+function skipJsonWhitespace(text: string, index: number): number {
+  while (index < text.length && /[\t\n\r ]/.test(text[index] ?? "")) index += 1;
+  return index;
+}
+
+function scanJsonStringEnd(text: string, index: number): number {
+  if (text[index] !== '"') throw new SyntaxError("expected JSON string");
+  for (let cursor = index + 1; cursor < text.length; cursor += 1) {
+    const char = text[cursor];
+    if (char === '"') return cursor + 1;
+    if (char === "\\") cursor += 1;
+  }
+  throw new SyntaxError("unterminated JSON string");
+}
+
+function scanJsonValue(text: string, index: number): JsonScanResult {
+  const start = skipJsonWhitespace(text, index);
+  if (text[start] === "{") return scanJsonObject(text, start);
+  if (text[start] === "[") return scanJsonArray(text, start);
+  if (text[start] === '"') return { next: scanJsonStringEnd(text, start), duplicate: false };
+
+  for (const literal of ["true", "false", "null"]) {
+    if (text.startsWith(literal, start)) {
+      return { next: start + literal.length, duplicate: false };
+    }
+  }
+  JSON_NUMBER_PATTERN.lastIndex = start;
+  const number = JSON_NUMBER_PATTERN.exec(text);
+  if (!number) throw new SyntaxError("expected JSON value");
+  return { next: start + number[0].length, duplicate: false };
+}
+
+function scanJsonObject(text: string, index: number): JsonScanResult {
+  const keys = new Set<string>();
+  let duplicate = false;
+  let cursor = skipJsonWhitespace(text, index + 1);
+  if (text[cursor] === "}") return { next: cursor + 1, duplicate: false };
+
+  while (cursor < text.length) {
+    const keyEnd = scanJsonStringEnd(text, cursor);
+    const key = JSON.parse(text.slice(cursor, keyEnd)) as unknown;
+    if (typeof key !== "string") throw new SyntaxError("invalid JSON object key");
+    if (keys.has(key)) duplicate = true;
+    keys.add(key);
+
+    cursor = skipJsonWhitespace(text, keyEnd);
+    if (text[cursor] !== ":") throw new SyntaxError("expected JSON object colon");
+    const value = scanJsonValue(text, cursor + 1);
+    duplicate ||= value.duplicate;
+    cursor = skipJsonWhitespace(text, value.next);
+    if (text[cursor] === "}") return { next: cursor + 1, duplicate };
+    if (text[cursor] !== ",") throw new SyntaxError("expected JSON object separator");
+    cursor = skipJsonWhitespace(text, cursor + 1);
+  }
+  throw new SyntaxError("unterminated JSON object");
+}
+
+function scanJsonArray(text: string, index: number): JsonScanResult {
+  let duplicate = false;
+  let cursor = skipJsonWhitespace(text, index + 1);
+  if (text[cursor] === "]") return { next: cursor + 1, duplicate: false };
+
+  while (cursor < text.length) {
+    const value = scanJsonValue(text, cursor);
+    duplicate ||= value.duplicate;
+    cursor = skipJsonWhitespace(text, value.next);
+    if (text[cursor] === "]") return { next: cursor + 1, duplicate };
+    if (text[cursor] !== ",") throw new SyntaxError("expected JSON array separator");
+    cursor = skipJsonWhitespace(text, cursor + 1);
+  }
+  throw new SyntaxError("unterminated JSON array");
+}
+
+function isUnsafeJsonDocument(text: string): boolean {
+  try {
+    const result = scanJsonValue(text, 0);
+    return result.duplicate || skipJsonWhitespace(text, result.next) !== text.length;
+  } catch {
+    // Scanner disagreement is untrusted input, just like JSON.parse failure.
+    return true;
+  }
+}
+
+function exactResetEligibleCode(
+  container: Record<string, unknown>,
+): CodexResetEligibleExhaustionCode | undefined {
+  const hasCode = hasOwnField(container, "code");
+  const hasType = hasOwnField(container, "type");
+  if (!hasCode && !hasType) return undefined;
+
+  const code = hasCode ? container.code : undefined;
+  const type = hasType ? container.type : undefined;
+  if ((hasCode && typeof code !== "string") || (hasType && typeof type !== "string")) {
+    return undefined;
+  }
+  if (hasCode && hasType && code !== type) return undefined;
+
+  const value = hasCode ? code : type;
+  if (typeof value !== "string") return undefined;
+  return RESET_ELIGIBLE_CODES.has(value as CodexResetEligibleExhaustionCode)
+    ? value as CodexResetEligibleExhaustionCode
+    : undefined;
+}
+
+function structuredResetEligibleCode(payload: unknown): CodexResetEligibleExhaustionCode | undefined {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
+  const root = payload as Record<string, unknown>;
+  const hasRootDiscriminator = hasOwnField(root, "code") || hasOwnField(root, "type");
+
+  if (!hasOwnField(root, "error")) return exactResetEligibleCode(root);
+  if (hasRootDiscriminator) return undefined;
+
+  const nested = root.error;
+  if (!nested || typeof nested !== "object" || Array.isArray(nested)) return undefined;
+  return exactResetEligibleCode(nested as Record<string, unknown>);
+}
+
+async function resetEligibleCodeFromResponse(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<CodexResetEligibleExhaustionCode | undefined> {
+  try {
+    const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    const payload = JSON.parse(body.text) as unknown;
+    // JSON.parse silently keeps the last duplicate key, making contradictory
+    // payloads order-dependent. Reject any duplicate at any object depth.
+    if (isUnsafeJsonDocument(body.text)) return undefined;
+    return structuredResetEligibleCode(payload);
+  } catch {
+    // Classification must fail closed. A malformed, oversized, consumed, or
+    // cancelled body cannot authorize an irreversible reset-credit operation.
+    return undefined;
+  }
+}
+
+/**
+ * Classify an upstream Codex rejection before any response event is exposed.
+ *
+ * Only an exact structured exhaustion code on HTTP 429/402 is reset-eligible.
+ * Status alone and message text are intentionally insufficient. The broad
+ * alternate-account retry remains eligible for 429/402 to preserve #584.
+ */
+export async function classifyCodexPreStreamRejection(
+  response: Response,
+  options: { signal?: AbortSignal } = {},
+): Promise<CodexPreStreamRejection> {
+  const status = response.status;
+  if (status === 401) return rejection(status, "authentication-error");
+  if (status === 403) {
+    const denial = await denialFromResponse(response, options.signal);
+    return { ...rejection(status, "permission-error"), ...(denial ? { denial } : {}) };
+  }
+  if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error");
+  if (status !== 429 && status !== 402) return rejection(status, "other");
+
+  const semanticCode = await resetEligibleCodeFromResponse(response, options.signal);
+  if (semanticCode) {
+    return rejection(status, "reset-eligible-exhaustion", {
+      alternateRetryEligible: true,
+      semanticCode,
+    });
+  }
+  return rejection(
+    status,
+    status === 429 ? "generic-rate-limit" : "unverified-billing-or-quota",
+    { alternateRetryEligible: true },
+  );
+}