@yansigit/opencodex 2.31.0

package/src/codex/warmup.ts

@@ -0,0 +1,298 @@
+import { readBoundedResponseBody } from "../lib/bounded-body";
+
+export class CodexWarmupError extends Error {
+  code: "http_status" | "missing_body" | "stream_failed" | "stream_incomplete" | "stream_error" | "stream_too_large" | "invalid_sse" | "no_terminal" | "transport";
+  status?: number;
+
+  constructor(
+    code: CodexWarmupError["code"],
+    message = "Codex warmup failed",
+    options: { status?: number; cause?: unknown } = {},
+  ) {
+    super(message);
+    this.name = "CodexWarmupError";
+    this.code = code;
+    this.status = options.status;
+    if (options.cause !== undefined) this.cause = options.cause;
+  }
+}
+
+export interface CodexWarmupOptions {
+  accessToken: string;
+  chatgptAccountId: string;
+  model?: string;
+  timeoutMs?: number;
+}
+
+const CODEX_RESPONSES_URL = "https://chatgpt.com/backend-api/codex/responses";
+const DEFAULT_MODEL = "gpt-5.4-mini";
+const FALLBACK_MODELS = ["gpt-5.5"];
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 0x7fff_ffff;
+const MAX_ERROR_BODY_BYTES = 2048;
+const MAX_WARMUP_STREAM_BYTES = 1024 * 1024;
+
+/** Bound and release an upstream error body without exposing provider-controlled text. */
+async function drainErrorBody(res: Response, signal: AbortSignal): Promise<void> {
+  try {
+    await readBoundedResponseBody(res, {
+      signal,
+      maxBytes: MAX_ERROR_BODY_BYTES,
+      fatalUtf8: true,
+    });
+  } catch (error) {
+    if (signal.aborted) {
+      throw new CodexWarmupError("transport", "Codex warmup request failed", {
+        cause: error,
+      });
+    }
+    // The bounded reader owns cancellation for oversized, invalid, or stalled bodies.
+  }
+}
+
+function safeWarmupReason(err: unknown): string {
+  if (err instanceof CodexWarmupError) {
+    return err.status ? `${err.code}:${err.status}` : err.code;
+  }
+  return "transport";
+}
+
+export function codexWarmupFailureReason(err: unknown): string {
+  return safeWarmupReason(err);
+}
+
+function eventTypeFromData(data: unknown): string | undefined {
+  if (!data || typeof data !== "object") return undefined;
+  const record = data as Record<string, unknown>;
+  return typeof record.type === "string" ? record.type : undefined;
+}
+
+function parseSseFrame(frame: string): unknown | null {
+  const dataLines = frame
+    .split(/\r?\n/)
+    .filter(line => line.startsWith("data:"))
+    .map(line => line.slice(5).trimStart());
+  if (dataLines.length === 0) return null;
+  const data = dataLines.join("\n").trim();
+  if (!data || data === "[DONE]") return null;
+  try {
+    return JSON.parse(data) as unknown;
+  } catch (err) {
+    throw new CodexWarmupError("invalid_sse", "Codex warmup received invalid SSE", { cause: err });
+  }
+}
+
+async function drainWarmupSse(body: ReadableStream<Uint8Array>, signal: AbortSignal): Promise<void> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = new Uint8Array(Math.min(MAX_WARMUP_STREAM_BYTES, 64 * 1024));
+  let bufferedBytes = 0;
+  let scanOffset = 0;
+  let bytesRead = 0;
+  const abortError = () => new CodexWarmupError("transport", "Codex warmup request failed", {
+    cause: signal.reason,
+  });
+  const cancelReader = () => {
+    try {
+      void reader.cancel(signal.reason).catch(() => {});
+    } catch {
+      // Some custom stream implementations throw synchronously from cancel().
+    }
+  };
+  // Fetch implementations usually error the response body when their signal is
+  // aborted, but a ReadableStream is not intrinsically coupled to that signal.
+  // Race only the currently pending read against a removable abort listener;
+  // Bun 1.3 can leave read() parked until a custom source's cancel promise
+  // settles, while a shared never-settled race promise would retain one handler
+  // per chunk. Cancellation remains best-effort and is never awaited.
+  const readWithSignal = (): Promise<Awaited<ReturnType<typeof reader.read>>> => {
+    if (signal.aborted) {
+      cancelReader();
+      return Promise.reject(abortError());
+    }
+    const read = reader.read();
+    void read.catch(() => {});
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (action: () => void) => {
+        if (settled) return;
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        action();
+      };
+      const onAbort = () => {
+        cancelReader();
+        finish(() => reject(abortError()));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      if (signal.aborted) {
+        onAbort();
+        return;
+      }
+      read.then(
+        result => finish(() => resolve(result)),
+        error => finish(() => reject(error)),
+      );
+    });
+  };
+  const ensureCapacity = (requiredBytes: number) => {
+    if (requiredBytes <= buffer.byteLength) return;
+    const grown = new Uint8Array(Math.min(
+      MAX_WARMUP_STREAM_BYTES,
+      Math.max(requiredBytes, buffer.byteLength * 2),
+    ));
+    grown.set(buffer.subarray(0, bufferedBytes));
+    buffer = grown;
+  };
+  const findFrameDelimiter = (start: number): { index: number; length: 2 | 3 | 4 } | undefined => {
+    for (let index = start; index < bufferedBytes - 1; index += 1) {
+      const firstLength = buffer[index] === 10
+        ? 1
+        : buffer[index] === 13 && buffer[index + 1] === 10 ? 2 : 0;
+      if (firstLength === 0) continue;
+      const secondStart = index + firstLength;
+      const secondLength = buffer[secondStart] === 10
+        ? 1
+        : buffer[secondStart] === 13 && buffer[secondStart + 1] === 10 ? 2 : 0;
+      if (secondLength > 0) return { index, length: (firstLength + secondLength) as 2 | 3 | 4 };
+    }
+    return undefined;
+  };
+  const acceptFrame = (frame: Uint8Array): boolean => {
+    const parsed = parseSseFrame(decoder.decode(frame));
+    const type = eventTypeFromData(parsed);
+    if (type === "response.completed") return true;
+    if (type === "response.failed") throw new CodexWarmupError("stream_failed");
+    if (type === "response.incomplete") throw new CodexWarmupError("stream_incomplete");
+    if (type === "error") throw new CodexWarmupError("stream_error");
+    return false;
+  };
+
+  try {
+    if (signal.aborted) throw abortError();
+    for (;;) {
+      const { done, value } = await readWithSignal();
+      if (signal.aborted) throw abortError();
+      if (done) break;
+      if (value.byteLength > MAX_WARMUP_STREAM_BYTES - bytesRead) {
+        throw new CodexWarmupError("stream_too_large", "Codex warmup stream exceeded the size limit");
+      }
+      bytesRead += value.byteLength;
+      ensureCapacity(bufferedBytes + value.byteLength);
+      buffer.set(value, bufferedBytes);
+      bufferedBytes += value.byteLength;
+
+      let consumedBytes = 0;
+      for (;;) {
+        const delimiter = findFrameDelimiter(scanOffset);
+        if (!delimiter) {
+          // A delimiter can start at most three bytes before the next chunk.
+          scanOffset = Math.max(consumedBytes, bufferedBytes - 3);
+          break;
+        }
+        if (acceptFrame(buffer.subarray(consumedBytes, delimiter.index))) return;
+        consumedBytes = delimiter.index + delimiter.length;
+        scanOffset = consumedBytes;
+      }
+      if (consumedBytes > 0) {
+        buffer.copyWithin(0, consumedBytes, bufferedBytes);
+        bufferedBytes -= consumedBytes;
+        scanOffset = Math.max(0, scanOffset - consumedBytes);
+      }
+    }
+
+    if (bufferedBytes > 0 && acceptFrame(buffer.subarray(0, bufferedBytes))) return;
+
+    throw new CodexWarmupError("no_terminal", "Codex warmup ended before completion");
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // A hostile cancel promise may keep the final read locked after timeout.
+    }
+  }
+}
+
+async function tryWarmup(options: CodexWarmupOptions, model: string): Promise<void> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > MAX_TIMEOUT_MS) {
+    throw new CodexWarmupError("transport", "Codex warmup request failed", {
+      cause: new RangeError("Codex warmup timeout is outside the supported range"),
+    });
+  }
+  // Bun 1.3 can leave AbortSignal.timeout() dormant while a custom response
+  // stream has a pending read. A ref'ed timer and explicit controller make the
+  // same deadline cover response headers and the full success/error body.
+  const deadline = new AbortController();
+  const signal = deadline.signal;
+  const timer = setTimeout(() => {
+    deadline.abort(new DOMException("Codex warmup timed out", "TimeoutError"));
+  }, timeoutMs);
+
+  try {
+    let res: Response;
+    try {
+      res = await fetch(CODEX_RESPONSES_URL, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${options.accessToken}`,
+          "ChatGPT-Account-Id": options.chatgptAccountId,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          model,
+          instructions: "Reply with OK.",
+          input: [{ type: "message", role: "user", content: [{ type: "input_text", text: "hi" }] }],
+          stream: true,
+          store: false,
+        }),
+        signal,
+      });
+    } catch (err) {
+      throw new CodexWarmupError("transport", "Codex warmup request failed", { cause: err });
+    }
+
+    if (!res.ok) {
+      await drainErrorBody(res, signal);
+      throw new CodexWarmupError("http_status", "Codex warmup was rejected", {
+        status: res.status,
+      });
+    }
+    const body = res.body;
+    if (!body) throw new CodexWarmupError("missing_body");
+
+    try {
+      await drainWarmupSse(body, signal);
+    } finally {
+      try {
+        void body.cancel().catch(() => {});
+      } catch {
+        // Some custom stream implementations throw synchronously from cancel().
+      }
+    }
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function warmCodexAccount(options: CodexWarmupOptions): Promise<void> {
+  const primaryModel = options.model?.trim() || DEFAULT_MODEL;
+  try {
+    await tryWarmup(options, primaryModel);
+    return;
+  } catch (err) {
+    // Retry with fallback models on 400 (model may not be available for this account).
+    if (!(err instanceof CodexWarmupError) || err.status !== 400) throw err;
+    let lastErr = err;
+    for (const fallback of FALLBACK_MODELS) {
+      if (fallback === primaryModel) continue;
+      try {
+        await tryWarmup(options, fallback);
+        return;
+      } catch (retryErr) {
+        if (retryErr instanceof CodexWarmupError) lastErr = retryErr;
+      }
+    }
+    throw lastErr;
+  }
+}

package/src/codex/websocket-registry.ts

@@ -0,0 +1,100 @@
+import type { ServerWebSocket } from "bun";
+import type { WsData } from "../server/ws-bridge";
+import { createAdmissionGate, type AdmissionMetrics, type AdmissionReservation } from "../lib/admission";
+
+export const MAX_TRACKED_CODEX_WEBSOCKETS = 128;
+const websocketGate = createAdmissionGate("codex_websockets", MAX_TRACKED_CODEX_WEBSOCKETS);
+
+export function tryReserveCodexWebSocket(): AdmissionReservation<ServerWebSocket<WsData>> | null {
+  const gateLease = websocketGate.tryAcquire();
+  if (!gateLease) return null;
+  let socket: ServerWebSocket<WsData> | undefined;
+  let active = true;
+  return {
+    bind(value) {
+      if (!active) return;
+      socket = value;
+    },
+    release() {
+      if (!active) return;
+      active = false;
+      socket = undefined;
+      gateLease.release();
+    },
+  };
+}
+
+export function codexWebSocketAdmissionMetrics(): AdmissionMetrics {
+  return websocketGate.metrics();
+}
+
+const socketsByAccount = new Map<string, Set<ServerWebSocket<WsData>>>();
+
+function trackedAccountId(ws: ServerWebSocket<WsData>): string | null {
+  const ctx = ws.data.authContext;
+  return ctx?.kind === "pool" || ctx?.kind === "main-pool" ? ctx.accountId : null;
+}
+
+function addSocketForAccount(accountId: string | null, ws: ServerWebSocket<WsData>): void {
+  if (!accountId) return;
+  let sockets = socketsByAccount.get(accountId);
+  if (!sockets) {
+    sockets = new Set();
+    socketsByAccount.set(accountId, sockets);
+  }
+  sockets.add(ws);
+}
+
+function removeSocketForAccount(accountId: string | null, ws: ServerWebSocket<WsData>): void {
+  if (!accountId) return;
+  const sockets = socketsByAccount.get(accountId);
+  if (!sockets) return;
+  sockets.delete(ws);
+  if (sockets.size === 0) socketsByAccount.delete(accountId);
+}
+
+export function registerCodexWebSocket(ws: ServerWebSocket<WsData>): void {
+  addSocketForAccount(trackedAccountId(ws), ws);
+}
+
+export function unregisterCodexWebSocket(ws: ServerWebSocket<WsData>): void {
+  removeSocketForAccount(trackedAccountId(ws), ws);
+}
+
+export function updateCodexWebSocketAuthContext(
+  ws: ServerWebSocket<WsData>,
+  authContext: WsData["authContext"],
+): void {
+  const before = trackedAccountId(ws);
+  removeSocketForAccount(before, ws);
+  ws.data.authContext = authContext;
+  addSocketForAccount(trackedAccountId(ws), ws);
+}
+
+export function invalidateCodexWebSocketsForAccount(accountId: string): number {
+  const sockets = socketsByAccount.get(accountId);
+  if (!sockets) return 0;
+  const snapshot = [...sockets];
+  socketsByAccount.delete(accountId);
+  for (const ws of snapshot) {
+    try {
+      ws.data.cancel?.();
+    } catch {
+      /* ignore cancel callbacks during invalidation */
+    }
+    try {
+      ws.close(4001, "Codex account invalidated");
+    } catch {
+      /* socket may already be closing */
+    }
+  }
+  return snapshot.length;
+}
+
+export function getTrackedCodexWebSocketCountForAccount(accountId: string): number {
+  return socketsByAccount.get(accountId)?.size ?? 0;
+}
+
+export function clearCodexWebSocketRegistry(): void {
+  socketsByAccount.clear();
+}

package/src/codex/write-coordination.ts

@@ -0,0 +1,114 @@
+/**
+ * The witness a native Codex write is coordinated by.
+ *
+ * NOT an `AdmissionSnapshot`, and the difference is the whole reason this file
+ * exists. `admitCodexWrite` refuses before it constructs a snapshot unless
+ * ownership is `owned` (`admission.ts`), so every snapshot it produces carries
+ * `owned` — the field cannot hold `unknown` at all. Reusing that type here would
+ * have meant one of two untruths: either the call becomes gated on ownership,
+ * which refuses Codex injection on every Windows machine and on Linux without a
+ * reachable user bus, or a hand-built snapshot claims an admission that never
+ * happened.
+ *
+ * So this type authorizes THE WRITE, not the DECISION to write. Deciding whether
+ * a write should happen at all is admission's job and belongs to its own phase,
+ * behind the Windows definition-chain walk.
+ *
+ * What the id covers, and why it is the OUTPUT rather than the inputs: the bytes
+ * `injectCodexConfig` emits depend on the port, the resolved catalog path, the
+ * hostname, websocket mode, legacy mode and the managed sub-agent defaults. An
+ * enumeration of those was already incomplete once. Hashing the computed
+ * candidate bytes closes the class instead of the instance — an input that
+ * changes the output changes the id whether or not anyone remembered to list it.
+ */
+import { createHash } from "node:crypto";
+
+export interface CodexWriteCandidate {
+  /** The exact string about to replace `config.toml`. */
+  readonly configBytes: string;
+  /** The exact string about to replace the profile. */
+  readonly profileBytes: string;
+  /** The RESOLVED catalog path, never the raw option. */
+  readonly catalogPath: string | null;
+}
+
+export interface CodexWriteEvidence {
+  /** sha256 of the `config.toml` bytes this operation read as its input. */
+  readonly nativeInputIdentity: string;
+  /** Digest of the persisted OpenCodex config these bytes were derived from. */
+  readonly persistedIdentity: string;
+  /** Generation as observed before the lock; `present:false` means no coordinator yet. */
+  readonly generation: Readonly<{ present: boolean; value: number }>;
+  /** Content identity of the journal, or a stable marker for absence. */
+  readonly journalIdentity: string;
+  readonly canonicalTargets: Readonly<{
+    config: string;
+    profile: string;
+    journal: string;
+  }>;
+}
+
+export interface CodexWriteCoordination {
+  readonly candidate: CodexWriteCandidate;
+  readonly evidence: CodexWriteEvidence;
+  /**
+   * Recorded context, deliberately OUTSIDE `comparisonId`.
+   *
+   * The lock compares one id and nothing else, so a field that is copied rather
+   * than re-observed detects no drift by being in it — it would only match
+   * itself. Ownership is not re-observed under the lock (that would mean running
+   * a service-manager subprocess while N and C are held), so it travels as
+   * something the operation SAW, not as something the comparison PROVES.
+   */
+  readonly observedOwnership: "owned" | "foreign" | "unknown";
+  readonly comparisonId: string;
+}
+
+/**
+ * Collapse a generation to one token.
+ *
+ * Absent and present-zero are the same authority — no cooperating write has
+ * committed — and they cannot be observed the same way: before the lock only
+ * absence is visible, and inside it only the committed zero is. Without this
+ * they never match and every first write refuses.
+ */
+function generationToken(generation: CodexWriteEvidence["generation"]): string {
+  const { present, value } = generation;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`A config generation must be a non-negative safe integer, got ${String(value)}.`);
+  }
+  return present && value > 0 ? `gen:${value}` : "gen:0";
+}
+
+export function hashCodexWriteCoordination(
+  candidate: CodexWriteCandidate,
+  evidence: CodexWriteEvidence,
+): string {
+  return createHash("sha256")
+    .update(JSON.stringify([
+      // The output, hashed directly. Two operations that intend different bytes
+      // cannot share an id, however they came to differ.
+      createHash("sha256").update(candidate.configBytes).digest("hex"),
+      createHash("sha256").update(candidate.profileBytes).digest("hex"),
+      candidate.catalogPath,
+      evidence.nativeInputIdentity,
+      evidence.persistedIdentity,
+      generationToken(evidence.generation),
+      evidence.journalIdentity,
+      evidence.canonicalTargets,
+    ]))
+    .digest("hex");
+}
+
+export function codexWriteCoordination(
+  candidate: CodexWriteCandidate,
+  evidence: CodexWriteEvidence,
+  observedOwnership: CodexWriteCoordination["observedOwnership"],
+): CodexWriteCoordination {
+  return {
+    candidate,
+    evidence,
+    observedOwnership,
+    comparisonId: hashCodexWriteCoordination(candidate, evidence),
+  };
+}

package/src/combos/failover.ts

@@ -0,0 +1,160 @@
+import { classifyError, isCyberPolicyCode } from "../lib/errors";
+import type { OcxComboTarget } from "../types";
+import { targetKey } from "./types";
+import {
+  captureConfigGeneration,
+  sweepExpiredOnWrite,
+  type GenerationContext,
+} from "../lib/state-store-sweeper";
+
+interface TargetCooldown {
+  cooldownUntil: number;
+}
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 10 * 60_000;
+
+/** Map<`${comboId}\0${provider/model}`, TargetCooldown> */
+const targetCooldowns = new Map<string, TargetCooldown>();
+let lastReconciledGeneration = 0;
+let liveComboTargets = new Set<string>();
+
+function cooldownMapKey(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+): string {
+  return `${comboId}\0${targetKey(target)}`;
+}
+
+export function parseRetryAfterMs(
+  value: string | null | undefined,
+  now = Date.now(),
+): number | undefined {
+  const text = value?.trim();
+  if (!text) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+    }
+  }
+  const timestamp = Date.parse(text);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const delay = timestamp - now;
+  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+}
+
+export function isComboTargetInCooldown(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  now = Date.now(),
+): boolean {
+  const key = cooldownMapKey(comboId, target);
+  const entry = targetCooldowns.get(key);
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    targetCooldowns.delete(key);
+    return false;
+  }
+  return true;
+}
+
+export function coolComboTarget(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  options?: { retryAfter?: string | null; now?: number; cooldownMs?: number; writerGeneration?: number },
+): void {
+  const now = options?.now ?? Date.now();
+  const writerGeneration = options?.writerGeneration ?? captureConfigGeneration();
+  const ownerKey = `${comboId}::${targetKey(target)}`;
+  if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return;
+  const cooldownMs = options?.cooldownMs
+    ?? parseRetryAfterMs(options?.retryAfter, now)
+    ?? DEFAULT_COOLDOWN_MS;
+  targetCooldowns.set(cooldownMapKey(comboId, target), {
+    cooldownUntil: now + Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS),
+  });
+  sweepExpiredOnWrite(now);
+}
+
+export function reconcileComboTargetCooldowns(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  liveComboTargets = new Set(context.comboTargets);
+  lastReconciledGeneration = context.generation;
+  return 0;
+}
+
+export function sweepExpiredComboTargetCooldowns(now = Date.now()): number {
+  let removed = 0;
+  for (const [key, cooldown] of targetCooldowns) {
+    if (cooldown.cooldownUntil > now) continue;
+    targetCooldowns.delete(key);
+    removed += 1;
+  }
+  return removed;
+}
+
+export function clearComboTargetCooldowns(comboId?: string): void {
+  if (comboId === undefined) {
+    targetCooldowns.clear();
+    liveComboTargets.clear();
+    lastReconciledGeneration = 0;
+    return;
+  }
+  const prefix = `${comboId}\0`;
+  for (const key of targetCooldowns.keys()) {
+    if (key.startsWith(prefix)) targetCooldowns.delete(key);
+  }
+}
+
+export type ComboFailureDecision = "hop" | "stop";
+
+export function comboFailureDecision(
+  status: number,
+  message: string,
+  options?: { code?: string | null },
+): ComboFailureDecision {
+  if (status === 499) return "stop";
+  if (message.toLowerCase().includes("origin_rejected")) return "stop";
+  // Cyber policy is a hard non-retryable refusal — honor structured code even when
+  // classificationText was truncated before the JSON code field.
+  if (isCyberPolicyCode(options?.code)) return "stop";
+  const error = classifyError(status, "upstream_error", message);
+  if (isCyberPolicyCode(error.code)) return "stop";
+  // A local input-admission refusal (#1524) says "this candidate cannot fit the request",
+  // not "the request is impossible": the next candidate may have a larger context window.
+  //
+  // This MUST be tested before the generic stop list below. Our own refusal message says
+  // "context window" -- that is what it refuses on -- and the classifier remaps that phrase,
+  // so checking the stop list first swallowed the signal and ended the chain. An UPSTREAM
+  // `context_length_exceeded` carries no admission code and still falls through to stop.
+  //
+  // Matched on the STRUCTURED code only, which classifyError now preserves for our own
+  // refusal. A raw substring test would additionally let any upstream override a terminal
+  // verdict by echoing the token in prose we do not control.
+  //
+  // Precise about what this is NOT: an upstream can still SET this code deliberately, since
+  // both extractors read the upstream error object. That is bounded rather than dangerous --
+  // an upstream already controls other hop signals (429, 5xx), and traversal is finite: policy
+  // tries each candidate once via `tried`, and combo excludes each attempted target. So this is
+  // structured-code-only, not provably local.
+  if (options?.code === "input_admission_refused" || error.code === "input_admission_refused") {
+    return "hop";
+  }
+  if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
+    return "stop";
+  }
+  if ([401, 403, 404, 408, 429].includes(status) || status >= 500) return "hop";
+  if ([
+    "permission_denied",
+    "subscription_required",
+    "invalid_api_key",
+    "insufficient_quota",
+    "rate_limit_exceeded",
+    "server_is_overloaded",
+    "upstream_server_error",
+  ].includes(error.code ?? "")) {
+    return "hop";
+  }
+  return "stop";
+}