@iislee/opencodex 2.11.0 → 2.35.0

package/src/lib/state-store-registrations.ts

@@ -34,7 +34,8 @@ import { sweepExpiredAnthropicRoutingHealth } from "../oauth/anthropic-routing";
 import { listLiveOAuthAccountKeys, reconcileOAuthReauthState } from "../oauth/store";
 import { reconcileGuardianBackoff } from "../oauth/token-guardian";
 import { sweepExpiredApiKeyCooldowns } from "../providers/key-failover";
-import { sweepExpiredResponseStates } from "../responses/state";
+import { reconcileProviderRequestPacing } from "../providers/request-pacing";
+import { sweepAbandonedResponseStateTemps, sweepExpiredResponseStates } from "../responses/state";
 import { sweepExpiredAntigravityReplay } from "../adapters/google-antigravity-replay";
 import { reconcileProviderAccountQuotaRows } from "../providers/quota";
 import { reconcileRouterWarningMemos } from "../router";
@@ -75,6 +76,7 @@ export function buildGenerationContext(): GenerationContext {
 export const STATE_STORE_REGISTRATIONS = [
   { name: "subagent-model-health", sweepExpired: sweepExpiredSubagentModelHealth },
   { name: "api-key-cooldowns", sweepExpired: sweepExpiredApiKeyCooldowns },
+  { name: "provider-request-pacing", reconcileGeneration: reconcileProviderRequestPacing },
   {
     name: "combo-target-cooldowns",
     sweepExpired: sweepExpiredComboTargetCooldowns,
@@ -82,7 +84,13 @@ export const STATE_STORE_REGISTRATIONS = [
   },
   { name: "anthropic-routing-health", sweepExpired: sweepExpiredAnthropicRoutingHealth },
   { name: "xai-refresh-verdicts", sweepExpired: sweepExpiredXaiPermanentFailureVerdicts },
-  { name: "responses-continuation", sweepExpired: sweepExpiredResponseStates },
+  {
+    name: "responses-continuation",
+    sweepExpired: sweepExpiredResponseStates,
+    // Disk reclaim rides the liveness tick, not the TTL tick: sweepExpiredOnWrite puts
+    // sweepExpired on hot write paths, where a directory scan does not belong.
+    sweepLiveness: sweepAbandonedResponseStateTemps,
+  },
   { name: "antigravity-replay", sweepExpired: sweepExpiredAntigravityReplay },
   { name: "config-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileConfigWarningMemos(context.generation) },
   { name: "catalog-warning-memos", reconcileGeneration: (context: GenerationContext) => reconcileCatalogWarningMemos(context.generation) },

package/src/lib/system-restart-contract.ts

@@ -0,0 +1,73 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { isLocalAttestationSecret } from "./local-management-attestation";
+
+export const SYSTEM_RESTART_METHOD = "POST";
+export const SYSTEM_RESTART_PATH = "/api/system/restart";
+export const SYSTEM_RESTART_CAPABILITY_VERSION = "v1";
+export const SYSTEM_RESTART_EXPECTED_PID_HEADER = "x-opencodex-restart-expected-pid";
+export const SYSTEM_RESTART_NONCE_HEADER = "x-opencodex-restart-nonce";
+export const SYSTEM_RESTART_CAPABILITY_HEADER = "x-opencodex-restart-capability";
+
+/** Fixed drain and replacement budgets shared by the server, CLI, and tray. */
+export const MEMORY_DRAIN_RESTART_MS = 60_000;
+export const REPLACEMENT_READY_TIMEOUT_MS = 70_000;
+
+const BASE64URL_256 = /^[A-Za-z0-9_-]{43}$/;
+
+export type ExpectedSystemRestartPid =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "present"; pid: number };
+
+export function parseExpectedSystemRestartPid(value: string | null): ExpectedSystemRestartPid {
+  if (value === null) return { kind: "absent" };
+  if (!/^[1-9]\d*$/.test(value)) return { kind: "invalid" };
+  const pid = Number(value);
+  return Number.isSafeInteger(pid) ? { kind: "present", pid } : { kind: "invalid" };
+}
+
+function restartCapabilityPayload(
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!BASE64URL_256.test(nonce)) return null;
+  if (method !== SYSTEM_RESTART_METHOD || path !== SYSTEM_RESTART_PATH) return null;
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+  return `opencodex-system-restart-v1\n${nonce}\n${method}\n${path}\n${pid}\n${port}`;
+}
+
+/** Process-scoped, operation-only authorization. It is not a reusable management credential. */
+export function createSystemRestartCapability(
+  secret: string,
+  nonce: string,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+): string | null {
+  if (!isLocalAttestationSecret(secret)) return null;
+  const payload = restartCapabilityPayload(nonce, method, path, pid, port);
+  if (!payload) return null;
+  return createHmac("sha256", secret).update(payload).digest("base64url");
+}
+
+export function verifySystemRestartCapability(
+  secret: string,
+  nonce: string | null,
+  method: string,
+  path: string,
+  pid: number,
+  port: number,
+  capability: string | null,
+): boolean {
+  if (!nonce || !capability || !BASE64URL_256.test(capability)) return false;
+  const expected = createSystemRestartCapability(secret, nonce, method, path, pid, port);
+  if (!expected) return false;
+  const expectedBytes = Buffer.from(expected);
+  const actualBytes = Buffer.from(capability);
+  return expectedBytes.length === actualBytes.length && timingSafeEqual(expectedBytes, actualBytes);
+}

package/src/lib/token-estimate.ts

@@ -55,15 +55,32 @@ function cjkRatio(text: string): number {
   return sampled === 0 ? 0 : cjk / sampled;
 }
 
+/**
+ * Cap an estimated token count at a model's context window (codex-router PR #140).
+ *
+ * A request the provider answered cannot have exceeded the window, so the estimate is never
+ * allowed to claim it did: the estimate only ever substitutes a reported-zero (or missing)
+ * input count, and a value above the window would be provably false. Positive or missing
+ * reported counts are never rewritten here — this bounds the heuristic estimate itself.
+ * Non-positive or non-integer windows (unknown model) leave the estimate untouched.
+ */
+export function capEstimateAtContextWindow(estimate: number, contextWindow: number | undefined): number {
+  return typeof contextWindow === "number" && Number.isInteger(contextWindow) && contextWindow > 0
+    ? Math.min(estimate, contextWindow)
+    : estimate;
+}
+
 /**
  * Estimate the token count of a text blob. Pure and deterministic.
  * Returns 0 for empty/whitespace-free-empty input; otherwise ceil(length / ratio), min 1.
+ * When `contextWindow` is a positive integer the estimate is capped at it: a request the
+ * provider answered cannot have exceeded the window, so the estimate must not claim it did.
  */
-export function estimateTokens(text: string, modelId?: string): number {
+export function estimateTokens(text: string, modelId?: string, contextWindow?: number): number {
   if (!text) return 0;
   const len = text.length;
   if (len === 0) return 0;
   let ratio = charsPerToken(modelId);
   if (cjkRatio(text) > CJK_RATIO_THRESHOLD) ratio = Math.min(ratio, CJK_CHARS_PER_TOKEN);
-  return Math.max(1, Math.ceil(len / ratio));
+  return capEstimateAtContextWindow(Math.max(1, Math.ceil(len / ratio)), contextWindow);
 }

package/src/lib/tool-argument-integers.ts

@@ -0,0 +1,253 @@
+// Schema-aware repair for tool arguments whose serialized representation disagrees
+// with the declared schema in a way that has exactly one faithful reading.
+//
+// Case 1 — integer fields arriving as integral floats (issue #1611).
+//
+// Grok serializes integer tool-call arguments through a float representation, so
+// `yield_time_ms: 120000` leaves the provider as `120000.0`. Codex declares those
+// fields as Rust integer types, so it rejects the call BEFORE running the tool:
+//
+//   failed to parse function arguments: invalid type: floating point `120000.0`, expected u64
+//
+// That is a hard failure, not a degradation — the model gets no result and retries
+// the same float. Nothing on the routed path reconciled argument values against the
+// declared schema, so the `.0` passed straight through.
+//
+// The boundary this file draws is INTENT, not convenience:
+//   - an integral float in an integer-typed field is a representation artifact, and
+//     `120000.0` has exactly one integer reading, so it is repaired;
+//   - `1.5` in an integer field is a genuine disagreement with the schema and is left
+//     alone so it still fails, rather than being truncated into a plausible lie.
+//
+// Case 2 — string fields arriving as bare integers (issue #1938).
+//
+// Cursor-served models emit `{"cell_id": 4}` where the schema declares
+// `{"type": "string"}`. Codex rejects the call before the tool runs (invalid type:
+// integer `4`, expected a string), and the model never self-corrects, so every such
+// call is a hard failure loop. A safely-integral JSON number in a string-declared
+// field has exactly one faithful string reading (`4` -> `"4"`), so it is repaired
+// under the same intent boundary:
+//   - only when the field declares `string` and no numeric type (a
+//     `["integer","string"]` union accepts the number as-is and is left alone);
+//   - a non-integral number (`4.5`) in a string field is a genuine disagreement and
+//     is left alone so it still fails;
+//   - beyond 2^53-1 the parsed value may differ from the serialized text, so the
+//     original bytes stay.
+//
+// Anything without a declared `integer`/`string` type is never touched.
+
+/** JSON Schema subset we need; provider tool schemas are untrusted input. */
+type SchemaNode = Record<string, unknown>;
+
+function asSchema(value: unknown): SchemaNode | undefined {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as SchemaNode
+    : undefined;
+}
+
+/** True when the node declares `integer`, including `["integer","null"]` unions. */
+function declaresInteger(schema: SchemaNode): boolean {
+  const type = schema.type;
+  if (type === "integer") return true;
+  return Array.isArray(type) && type.includes("integer");
+}
+
+/** True when the node declares `string`, including `["string","null"]` unions. */
+function declaresString(schema: SchemaNode): boolean {
+  const type = schema.type;
+  if (type === "string") return true;
+  return Array.isArray(type) && type.includes("string");
+}
+
+// Issue #2316: Codex advertises `multi_agent_v1__wait_agent`'s `timeout_ms` as a JSON
+// Schema `number`, but its Rust runtime deserializes the field as `u64` and rejects
+// `120000.0` with "invalid type: floating point `120000.0`, expected u64" before the
+// tool ever runs. The schema lookup is not the problem — the error text comes from
+// Codex's own deserializer, so the call reached it — the problem is that `number`
+// alone never authorizes the integral-float repair below.
+//
+// This allowlist is deliberately one field wide. It names only what has a live
+// reproduction against a real `u64`, because the repair is only unambiguous for a
+// field that cannot legitimately hold a fraction. Generic names (`start`, `end`,
+// `priority`, `port`) would silently rewrite a third-party tool's fractional value,
+// so a new entry needs its own evidence, not a plausible-sounding name.
+//
+// Cursor's sibling `yield_time_ms` (src/adapters/cursor/tool-definitions.ts) is also
+// declared `number`; it is NOT included here because no rejection has been captured
+// against it. It gets its own change when it gets its own reproduction.
+const U64_NUMBER_FIELDS = new Set(["timeout_ms"]);
+
+// Issue #2443 / #2451: Codex Desktop's bare `wait` tool has the same schema/runtime
+// split for `yield_time_ms` and `max_tokens`. Scope these names to that bare tool so a
+// third-party or namespaced tool can still use fractional values legitimately.
+// #2448 allowlisted the hyphenated `yield-time_ms`; live Grok 4.6 calls and the
+// advertised wait schema both use the underscore form, so that name is the one
+// with a captured u64 rejection. Cursor still uses the same underscore name on a
+// namespaced tool; the wait-only map keeps that path byte-identical.
+const U64_NUMBER_FIELDS_BY_TOOL = new Map<string, ReadonlySet<string>>([
+  ["wait", new Set(["yield_time_ms", "max_tokens"])],
+]);
+
+/** True when the node accepts a JSON number (`integer` or `number`), so a numeric
+ * value is already schema-valid and must not be rewritten into a string. */
+function declaresNumeric(schema: SchemaNode): boolean {
+  const type = schema.type;
+  if (type === "integer" || type === "number") return true;
+  return Array.isArray(type) && (type.includes("integer") || type.includes("number"));
+}
+
+/**
+ * Resolve a local `$ref` (`#/$defs/Foo`, `#/definitions/Foo`).
+ *
+ * Only same-document refs are followed: a remote ref is not fetchable here, and a
+ * schema we cannot resolve must leave its values untouched rather than guessed at.
+ */
+function resolveRef(schema: SchemaNode, root: SchemaNode, seen: Set<string>): SchemaNode | undefined {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/")) return schema;
+  if (seen.has(ref)) return undefined; // cyclic $ref: stop rather than recurse forever
+  seen.add(ref);
+  let node: unknown = root;
+  for (const rawSegment of ref.slice(2).split("/")) {
+    const segment = rawSegment.replace(/~1/g, "/").replace(/~0/g, "~");
+    const current = asSchema(node);
+    if (!current) return undefined;
+    node = current[segment];
+  }
+  const resolved = asSchema(node);
+  return resolved ? resolveRef(resolved, root, seen) : undefined;
+}
+
+/** Composition keywords whose branches may carry the integer declaration. */
+const COMPOSITION_KEYS = ["anyOf", "oneOf", "allOf"] as const;
+
+function compositionBranches(schema: SchemaNode): SchemaNode[] {
+  const branches: SchemaNode[] = [];
+  for (const key of COMPOSITION_KEYS) {
+    const value = schema[key];
+    if (!Array.isArray(value)) continue;
+    for (const branch of value) {
+      const node = asSchema(branch);
+      if (node) branches.push(node);
+    }
+  }
+  return branches;
+}
+
+/**
+ * A JS number can only represent integers exactly up to 2^53-1. Beyond that a
+ * rewrite would emit a silently different value, so the original text stays.
+ */
+function safelyIntegral(value: number): boolean {
+  return Number.isInteger(value) && Math.abs(value) <= Number.MAX_SAFE_INTEGER;
+}
+
+interface CoerceResult {
+  value: unknown;
+  changed: boolean;
+}
+
+function coerceValue(
+  value: unknown,
+  schema: SchemaNode | undefined,
+  root: SchemaNode,
+  depth: number,
+  toolName?: string,
+  propertyName?: string,
+): CoerceResult {
+  // A hostile or deeply nested schema must not blow the stack.
+  if (depth > 64) return { value, changed: false };
+  const resolved = schema ? resolveRef(schema, root, new Set()) : undefined;
+
+  if (typeof value === "number") {
+    if (!resolved) return { value, changed: false };
+    const branches = compositionBranches(resolved);
+    // #2316: a known Codex-native u64 field counts as integer-declared even when the
+    // advertised schema says `number`, but only when the field really is numeric —
+    // an allowlisted name over a string-typed field is a disagreement, not a repair.
+    const nativeU64Field = propertyName !== undefined
+      && (
+        U64_NUMBER_FIELDS.has(propertyName)
+        || U64_NUMBER_FIELDS_BY_TOOL.get(toolName ?? "")?.has(propertyName) === true
+      );
+    const nativeU64Declared = nativeU64Field
+      && (declaresNumeric(resolved) || branches.some(declaresNumeric));
+    const integerDeclared = declaresInteger(resolved)
+      || branches.some(declaresInteger)
+      || nativeU64Declared;
+    if (!integerDeclared && safelyIntegral(value)) {
+      // Issue #1938: a bare integer in a string-only field has exactly one faithful
+      // string reading. A field that also accepts a numeric type keeps the number.
+      const stringDeclared = declaresString(resolved) || branches.some(declaresString);
+      const numericDeclared = declaresNumeric(resolved) || branches.some(declaresNumeric);
+      if (stringDeclared && !numericDeclared) {
+        return { value: String(value), changed: true };
+      }
+    }
+    // Not an integer field, already an integer, non-integral, or unrepresentable:
+    // in every one of those cases the received value is the right thing to keep.
+    if (!integerDeclared || !safelyIntegral(value)) return { value, changed: false };
+    // `120000.0` and `120000` are the same JS number; the difference is only in the
+    // serialized text, which is repaired by re-stringifying the parsed value.
+    return { value, changed: true };
+  }
+
+  if (Array.isArray(value)) {
+    const itemSchema = resolved ? asSchema(resolved.items) : undefined;
+    let changed = false;
+    const next = value.map(entry => {
+      // Array items have no property name of their own; passing the array's key would
+      // let `timeout_ms: [1.5]` inherit the allowlist. Items are judged by schema only.
+      const result = coerceValue(entry, itemSchema, root, depth + 1, toolName);
+      if (result.changed) changed = true;
+      return result.value;
+    });
+    return changed ? { value: next, changed } : { value, changed: false };
+  }
+
+  const object = asSchema(value);
+  if (!object) return { value, changed: false };
+
+  const properties = resolved ? asSchema(resolved.properties) : undefined;
+  const additional = resolved ? asSchema(resolved.additionalProperties) : undefined;
+  let changed = false;
+  const next: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(object)) {
+    const childSchema = asSchema(properties?.[key]) ?? additional;
+    const result = coerceValue(entry, childSchema, root, depth + 1, toolName, key);
+    if (result.changed) changed = true;
+    next[key] = result.value;
+  }
+  return changed ? { value: next, changed } : { value, changed: false };
+}
+
+/**
+ * Repair integral floats in a tool-call arguments STRING against the tool's declared
+ * parameter schema.
+ *
+ * Returns the original string unchanged when there is no schema, the payload does not
+ * parse, or nothing needed repair — so an unaffected call keeps its exact bytes and
+ * this stays a no-op for every provider that already emits real integers.
+ */
+export function coerceIntegerToolArguments(
+  args: string,
+  parameters: Record<string, unknown> | undefined,
+  toolName?: string,
+): string {
+  if (!parameters || !args) return args;
+  // Cheap reject: a payload with no digit cannot need either repair (integral-float
+  // -> integer, or bare-integer -> string).
+  if (!/\d/.test(args)) return args;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(args);
+  } catch {
+    // Malformed or still-streaming arguments are not this function's problem; the
+    // existing paths already handle them.
+    return args;
+  }
+  const root = parameters as SchemaNode;
+  const result = coerceValue(parsed, root, root, 0, toolName);
+  if (!result.changed) return args;
+  return JSON.stringify(result.value);
+}

package/src/lib/translator-budget.ts

@@ -71,6 +71,40 @@ export interface TranslatorBudget {
 
 const retainedEventOwnership = new WeakMap<object, { budget: TranslatorBudget; bytes: number }>();
 
+/**
+ * Charge one event appended to an incrementally materialized adapter-event batch.
+ * The newest event owns the closing array bracket; moving that byte from the old
+ * tail keeps in-order release accounting equal to the still-retained JSON array.
+ */
+export function retainTranslatedEvent<T extends object>(
+  event: T,
+  budget: TranslatorBudget,
+  previousTail?: object,
+): void {
+  if (retainedEventOwnership.has(event)) {
+    throw new Error("translated event is already retained");
+  }
+  if (previousTail === event) {
+    throw new Error("incremental translated event tail must be a distinct object");
+  }
+  const previousOwnership = previousTail === undefined
+    ? undefined
+    : retainedEventOwnership.get(previousTail);
+  if (
+    previousTail !== undefined
+    && (!previousOwnership || previousOwnership.budget !== budget || previousOwnership.bytes < 2)
+  ) {
+    throw new Error("incremental translated event tail is not retained by this budget");
+  }
+
+  const serializedBytes = Buffer.byteLength(JSON.stringify(event));
+  budget.chargeRetained(serializedBytes + (previousTail === undefined ? 2 : 1), {
+    kind: "retained_collectors",
+  });
+  if (previousOwnership) previousOwnership.bytes -= 1;
+  retainedEventOwnership.set(event, { budget, bytes: serializedBytes + 2 });
+}
+
 /**
  * Charge a materialized adapter-event batch and attach its lease to the events themselves.
  * A copied event array (for example terminal-guard collection) preserves the event objects, so
@@ -315,6 +349,16 @@ export function translatorObservedOverflowCount(): number {
   return aggregateOverflows;
 }
 
+/** Test-only: proves owned default budgets are disposed on every stream-death path. */
+export function translatorLiveBudgetCountForTests(): number {
+  return liveBudgets.size;
+}
+
+/** Test-only: proves no charge survives against a disposed budget (cancel race). */
+export function translatorAggregateCurrentBytesForTests(): number {
+  return aggregateCurrentBytes;
+}
+
 /** Clears process-wide translator diagnostics and disposes leaked test budgets. */
 export function resetTranslatorAggregateForTests(): void {
   for (const budget of liveBudgets) budget.dispose();

package/src/lib/upstream-http-version.ts

@@ -0,0 +1,57 @@
+import type { OcxProviderConfig, UpstreamHttpVersion } from "../types";
+
+/** True when a provider explicitly selected the HTTP/1.1 compatibility path. */
+export function isPinnedHttp1(version: UpstreamHttpVersion | undefined): boolean {
+  return version === "http1.1" || version === "h1";
+}
+
+/**
+ * Bun's fetch accepts a non-standard `protocol` init to pin the HTTP version
+ * (BunFetchRequestInit.protocol). The DOM lib types do not include it, so the
+ * value is represented through a RequestInit cast at this shared boundary.
+ */
+const UPSTREAM_HTTP_VERSION_PROTOCOL: Record<Exclude<UpstreamHttpVersion, "auto">, string> = {
+  "http1.1": "http1.1",
+  h1: "h1",
+  http2: "http2",
+  h2: "h2",
+};
+
+/** Raised before I/O when a fixed Bun HTTP-version pin cannot apply to the target URL. */
+export class UpstreamHttpVersionTargetError extends Error {
+  readonly code = "upstream_http_version_target";
+
+  constructor(readonly observedProtocol: string) {
+    super(`upstream HTTP version pin requires an HTTPS target (received ${observedProtocol})`);
+    this.name = "UpstreamHttpVersionTargetError";
+  }
+}
+
+/** Attach Bun's `protocol` pin for one explicit version value. */
+export function withUpstreamHttpVersionValue(
+  input: Parameters<typeof globalThis.fetch>[0],
+  init: RequestInit | undefined,
+  version: UpstreamHttpVersion | undefined,
+): RequestInit | undefined {
+  if (!version || version === "auto") return init;
+  // Bun's protocol pin requires an https: target. An explicit fixed-version request must fail
+  // locally when the pin cannot be honored instead of silently negotiating another transport.
+  const target = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  let targetUrl: URL;
+  try {
+    targetUrl = new URL(target);
+  } catch {
+    throw new UpstreamHttpVersionTargetError("unparseable");
+  }
+  if (targetUrl.protocol !== "https:") throw new UpstreamHttpVersionTargetError(targetUrl.protocol);
+  return { ...(init ?? {}), protocol: UPSTREAM_HTTP_VERSION_PROTOCOL[version] } as RequestInit;
+}
+
+/** Attach Bun's `protocol` pin when the provider opted into a fixed HTTP version. */
+export function withUpstreamHttpVersion(
+  input: Parameters<typeof globalThis.fetch>[0],
+  init: RequestInit | undefined,
+  provider: Pick<OcxProviderConfig, "upstreamHttpVersion">,
+): RequestInit | undefined {
+  return withUpstreamHttpVersionValue(input, init, provider.upstreamHttpVersion);
+}

package/src/lib/upstream-reachability.ts

@@ -0,0 +1,95 @@
+/**
+ * Classification of upstream fetch rejections that occur before any request
+ * bytes can reach the origin: DNS resolution failure and TCP connect refusal.
+ *
+ * Issue #914: these failures are machine/network-wide, not account-specific —
+ * every Codex pool account shares the provider host, so rotating accounts
+ * cannot repair them. The transport layer previously mapped every non-timeout
+ * rejection to `connect_error`, and at `upstreamFailoverThreshold` that streak
+ * soft-avoided a healthy account and cleared thread affinity.
+ *
+ * Bun collapses DNS failure and TCP refusal into one label class
+ * (`ConnectionRefused` / `FailedToOpenSocket`, errno 0); Node's undici emits
+ * the classic `ECONNREFUSED` / `ENOTFOUND` / `EAI_AGAIN` / `ENETUNREACH` /
+ * `ENETDOWN` / `EHOSTUNREACH` shapes. Both shapes are matched here, on `code`
+ * values only, through a bounded cause chain. Message substrings are never
+ * trusted (a message-only match is a negative case), and labels that can also
+ * appear after the origin saw the credential — `ECONNRESET`, `EPIPE`, TLS
+ * errors, unknown shapes — deliberately stay outside the set.
+ *
+ * Classifier semantics extracted from PR #966 (Yuxin-Qiao) with attribution;
+ * sidecar blast radius intentionally not inherited.
+ *
+ * MUST stay a leaf module: imports nothing from server.ts or adapters.
+ */
+
+import { RequestPacingQueueOverloadError } from "../providers/request-pacing";
+import { UpstreamRetryEvidenceError } from "./upstream-retry";
+
+export const PRE_CONNECT_REACHABILITY_CODES = new Set([
+  // Bun: DNS failure and TCP refusal share this class.
+  "ConnectionRefused",
+  "FailedToOpenSocket",
+  // Node undici / classic Node shapes.
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ENETUNREACH",
+  "ENETDOWN",
+  "EHOSTUNREACH",
+]);
+
+/** Upper bound on how far `cause` chains are inspected. */
+export const MAX_REACHABILITY_CAUSE_DEPTH = 3;
+
+/**
+ * True when the rejection (or a bounded `cause` of it) carries a proven
+ * pre-connection reachability code. Never matches message text.
+ */
+export function isPreConnectReachabilityError(err: unknown): boolean {
+  let current: unknown = err;
+  const seen = new Set<unknown>();
+  for (let depth = 0; depth < MAX_REACHABILITY_CAUSE_DEPTH; depth++) {
+    if (!(current instanceof Error) || seen.has(current)) return false;
+    seen.add(current);
+    const code = (current as { code?: unknown }).code;
+    if (typeof code === "string" && PRE_CONNECT_REACHABILITY_CODES.has(code)) return true;
+    current = current.cause;
+  }
+  return false;
+}
+
+export type TransportFailureKind = "timeout" | "connect_neutral" | "connect_error";
+
+/**
+ * Shared transport rejection classification for Codex pool upstream sends.
+ * Timeouts keep their existing identity (account-transient); proven pre-connect
+ * reachability failures become account-neutral; everything else (ECONNRESET,
+ * EPIPE, TLS, unknown shapes) keeps the existing `connect_error`
+ * account-attributed behavior.
+ */
+export function classifyTransportFailureKind(err: unknown): TransportFailureKind {
+  // A local pacing admission failure happened before transport classification and must
+  // remain a client-visible overload, not account or host health evidence.
+  if (err instanceof RequestPacingQueueOverloadError) throw err;
+  const evidence = err instanceof UpstreamRetryEvidenceError ? err : undefined;
+  const rejection = evidence ? evidence.cause : err;
+  if (rejection instanceof Error && rejection.name === "TimeoutError") return "timeout";
+  if (isPreConnectReachabilityError(rejection)) {
+    // A transient upstream response (5xx) or a credential-visible connection
+    // reset before the rejection proves the host and credential path were
+    // reached: the failure is account-attributable, never the pre-connection
+    // neutral class (issue #914 review).
+    if (evidence && (evidence.transientStatuses.length > 0 || evidence.resetSeen)) return "connect_error";
+    return "connect_neutral";
+  }
+  return "connect_error";
+}
+
+/** Stable `code` carried by a transport rejection, when there is one. */
+export function transportErrorCode(err: unknown): string | undefined {
+  const rejection = err instanceof UpstreamRetryEvidenceError ? err.cause : err;
+  if (!(rejection instanceof Error)) return undefined;
+  const code = (rejection as { code?: unknown }).code;
+  return typeof code === "string" && code !== "" ? code : undefined;
+}