@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/integrations/writer.ts

@@ -11,12 +11,14 @@
  */
 import { homedir } from "node:os";
 import { createClineIO, ClineTransactionError } from "./cline-io";
-import { parseClineDocument, serializeClineDocument, preserveClineSelection } from "./cline-document";
+import { serializeClineDocument, preserveClineSelection } from "./cline-document";
 import { dirname } from "node:path";
 import { EXPORT_CLIENTS, type ExportModel, type ManagedContribution } from "../clients/config-export";
 import { shouldInjectApiAuthHeader } from "../codex/inject";
+import { detachedConfigSnapshot } from "../config/admitted-identity";
+import { copyPlainData } from "../lib/plain-data";
 import type { OcxConfig } from "../types";
-import { PARSE_FAILED, defaultIntegrationIO, loadTarget, parseConfig, type IntegrationIO } from "./config-io";
+import { defaultIntegrationIO, loadTarget, type IntegrationIO } from "./config-io";
 import {
   fingerprint,
   canonicalContribution,
@@ -31,11 +33,12 @@ import {
 } from "./ownership-policy";
 import { AmbiguousSelectorError, createdContainerPaths, mergeContribution, removeFragments } from "./merge";
 import { INTEGRATION_CLIENTS, isLoopbackOnly, resolveIntegrationPaths, type IntegrationClientId } from "./registry";
-import { classifyIntegration, exportContextOf } from "./state";
+import { exportContextOf } from "./state";
 import type { IntegrationState } from "./state";
 import { serializeDocument, UnserializableValueError } from "./serialize";
 import { ClientPathError } from "../clients/config-export";
 import { matchesOperationResult, newOpId, type JournalEntry } from "./journal";
+import { observeIntegration, type IntegrationWriteInput, type RefusalReason } from "./mutation-plan";
 import { createIntegrationStateStore, type IntegrationStateStore } from "./store";
 import {
   patchYamlFragmentSource,
@@ -62,14 +65,12 @@ function yamlRefusalReason(
 }
 import { withIntegrationWriterLock, type IntegrationWriterLockSeams } from "./writer-lock";
 
-export type RefusalReason =
-  | "not_installed"
-  | "conflict"
-  | "unsafe"
-  | "non_loopback"
-  | "drift_requires_confirm"
-  | "snapshot_expired"
-  | "write_failed";
+/**
+ * Owned by the planner so a plan can report a refusal without depending on the writer, and
+ * re-exported here because this module was its original home and every caller imports it from
+ * the writer.
+ */
+export type { IntegrationWriteInput, RefusalReason };
 
 export interface WriteOk {
   ok: true;
@@ -94,19 +95,6 @@ export interface WriteRefused {
 
 export type WriteOutcome = WriteOk | WriteRefused;
 
-export interface IntegrationWriteInput {
-  clientId: IntegrationClientId;
-  models: readonly ExportModel[];
-  config: OcxConfig;
-  port: number;
-  env?: NodeJS.ProcessEnv;
-  home?: string;
-  store?: IntegrationStateStore;
-  io?: IntegrationIO;
-  /** Frozen once by the async coordinator; synchronous callers may omit it. */
-  resolvedPaths?: { configPath: string; detectDir: string };
-}
-
 export interface IntegrationRestoreInput extends IntegrationWriteInput {
   opId: string;
   confirmDrift?: boolean;
@@ -227,76 +215,20 @@ function sourcePreservingFragmentValue(
   return fragment?.value;
 }
 
-/** Shared preflight: detect, gate, read, parse and classify. */
+/**
+ * Mutation's view of the shared observation.
+ *
+ * The read, parse and classify live in the planner so a preview and the mutation it authorizes
+ * cannot disagree. Mutation keeps the effects a preview must not have: pending-prune maintenance
+ * and Cline transaction recovery both write. Translating the planner's refusal into WriteRefused
+ * here keeps the planner free of any dependency on this module's result type.
+ */
 function preflight(input: IntegrationWriteInput) {
-  const store = input.store ?? createIntegrationStateStore();
-  let io = input.io ?? defaultIntegrationIO(store);
-  const clientId = input.clientId;
-  const spec = INTEGRATION_CLIENTS[clientId];
-  const exportSpec = EXPORT_CLIENTS[clientId];
-  /*
-   * Resolution itself can refuse: a relative OPENCLAW_* selector is rejected
-   * because we cannot know the gateway's working directory. That is a refusal
-   * about the user's configuration, not an internal fault, so it must not
-   * escape as an exception — the collection route would answer 500 for the
-   * whole Integrations page because one client is misconfigured.
-   */
-  let configPath: string;
-  let detectDir: string;
-  try {
-    /*
-     * Resolve the PAIR, never one half.
-     *
-     * The coordinated path hands us a frozen pair, but applyIntegration,
-     * refreshIntegration and disableIntegration are public and may be called
-     * without one. Resolving configPath here and detectDir separately later let
-     * an Aside account switch land between the two, so a direct apply could
-     * verify account 1 was installed and then write account 0's catalog.
-     */
-    const resolved = input.resolvedPaths ?? resolveIntegrationPaths(clientId, input.env, input.home);
-    configPath = resolved.configPath;
-    detectDir = resolved.detectDir;
-    if (clientId === "cline") io = createClineIO(io, configPath, store, true);
-  } catch (error) {
-    if (error instanceof ClineTransactionError) {
-      return { failed: { ...refuse(clientId, "unsafe", "unsafe", error.message, error.snapshotPath), residual: true } } as const;
-    }
-    if (!(error instanceof ClientPathError)) throw error;
-    return { failed: refuse(clientId, "unsafe", "unsafe", error.message) } as const;
-  }
-  store.retryPendingPrunes();
-
-  const target = loadTarget(io, configPath);
-  if (!target.ok) {
-    return {
-      failed: refuse(clientId, "unsafe", "unsafe",
-        target.why === "read-failed"
-          ? `${configPath} exists but could not be read`
-          : `${configPath} is not a regular file`),
-    } as const;
-  }
-  const before = target.before;
-  const parsed = clientId === "cline" ? parseClineDocument(before) : parseConfig(before, exportSpec.format);
-  if (parsed === PARSE_FAILED) {
-    return { failed: refuse(clientId, "unsafe", "unsafe",
-      `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
-  }
-  const contribution = exportSpec.buildContribution(exportContextOf(input));
-  // A record proves ownership of the file it was written FOR. Matching only by
-  // client id let a record for one home authorize a write to another whose
-  // bytes happened to hash the same — which deleted a config we never touched.
-  const stored = store.readRecords()[clientId] ?? null;
-  const record = stored && stored.clientId === clientId && stored.configPath === configPath
-    ? stored
-    : null;
-  // `configPath`/`clientId` are load-bearing, not decoration: a record proves
-  // ownership of ONE file, and the writer mutates whatever path resolves NOW.
-  // Without them a record written for another home directory would grant
-  // ownership here and disable would delete fragments it never wrote.
-  const classified = classifyIntegration({
-    fileText: before, fileIsRegular: true, parsed, record, contribution, configPath, clientId,
-  });
-  return { failed: undefined, store, io, clientId, spec, exportSpec, configPath, detectDir, before, parsed, contribution, record, classified } as const;
+  const observed = observeIntegration(input, { maintenance: true, recover: true });
+  if (!observed.failed) return observed;
+  const { reason, state, message, snapshotPath, residual } = observed.failed;
+  const refused = refuse(input.clientId, reason, state, message, snapshotPath);
+  return { failed: residual ? { ...refused, residual: true } : refused } as const;
 }
 
 /**
@@ -748,6 +680,15 @@ export function restoreIntegration(input: IntegrationRestoreInput): WriteOutcome
 
 export interface CoordinatedIntegrationOptions {
   lockSeams?: IntegrationWriterLockSeams;
+  /**
+   * Checked after the input is frozen and the writer lock is held, before any side effect.
+   *
+   * A confirmation is a statement about state the operator was shown. Checking it out here, where
+   * the lock already excludes cooperating writers, is what makes it a decision about the same
+   * state the mutation is about to change rather than about state from a moment earlier. A
+   * non-null result refuses without writing anything.
+   */
+  revalidate?: (frozen: IntegrationWriteInput) => Promise<WriteOutcome | null>;
 }
 
 /** Freeze all mutable resolution seams before the first lock await. */
@@ -759,6 +700,16 @@ type FrozenIntegrationInput = IntegrationWriteInput & {
   resolvedPaths: { configPath: string; detectDir: string };
 };
 
+/**
+ * An input this write cannot hold still.
+ *
+ * A coordinated write checks a plan and then writes a document from the same input, with an await
+ * in between. Anything it cannot copy would have to be read from the caller's object twice, and
+ * the second read is not the one that was checked. Refusing is bounded and says so; carrying the
+ * reference and calling it a frozen input would not be.
+ */
+class UncopyableIntegrationInputError extends Error {}
+
 function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegrationInput {
   const env = { ...(input.env ?? process.env) };
   const home = input.home ?? homedir();
@@ -773,7 +724,23 @@ function freezeIntegrationInput(input: IntegrationWriteInput): FrozenIntegration
   const resolvedPaths = input.resolvedPaths
     ? { ...input.resolvedPaths }
     : resolveIntegrationPaths(input.clientId, env, home);
-  return { ...input, env, home, store, io, resolvedPaths };
+  /*
+   * The configuration and the roster are seams like the others, and they were the two still held
+   * by reference. A coordinated write plans from this input, awaits the writer lock and a
+   * revalidation, and only then serializes the document from it. A management route editing the
+   * live configuration, or a caller editing the model objects it passed in, would have been
+   * checked in one state and written from another, which is the substitution the fingerprint
+   * exists to prevent. Copying both here gives the plan and the document one input.
+   */
+  const config = detachedConfigSnapshot(input.config);
+  if (config === null) {
+    throw new UncopyableIntegrationInputError("the proxy configuration could not be captured for this write");
+  }
+  const models = copyPlainData(input.models);
+  if (!models.ok) {
+    throw new UncopyableIntegrationInputError("the model roster could not be captured for this write");
+  }
+  return { ...input, config, models: models.value, env, home, store, io, resolvedPaths };
 }
 
 function tryFreezeIntegrationInput(input: IntegrationWriteInput):
@@ -782,6 +749,9 @@ function tryFreezeIntegrationInput(input: IntegrationWriteInput):
   try {
     return { ok: true, value: freezeIntegrationInput(input) };
   } catch (error) {
+    if (error instanceof UncopyableIntegrationInputError) {
+      return { ok: false, refusal: refuse(input.clientId, "unsafe", "unsafe", error.message) };
+    }
     if (!(error instanceof ClientPathError)) throw error;
     return {
       ok: false,
@@ -799,15 +769,22 @@ async function coordinatedWrite(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
-  if (!spec.writerLock) return operation(frozen);
+  if (!spec.writerLock) {
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? operation(frozen);
+  }
 
   // An absent client home is not created merely to acquire a sibling lock.
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
-    return operation(frozen);
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? operation(frozen);
   }
   return withIntegrationWriterLock(
     frozen.resolvedPaths.configPath,
-    async () => operation(frozen),
+    async () => {
+      const refused = await options?.revalidate?.(frozen);
+      return refused ?? operation(frozen);
+    },
     options?.lockSeams,
     spec.writerLock.suffix,
   );
@@ -849,7 +826,11 @@ export async function restoreIntegrationCoordinated(
   if (!prepared.ok) return prepared.refusal;
   const frozen = prepared.value;
   const spec = INTEGRATION_CLIENTS[frozen.clientId];
-  if (!spec.writerLock) return restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  const run = () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift });
+  if (!spec.writerLock) {
+    const refused = await options?.revalidate?.(frozen);
+    return refused ?? run();
+  }
   if (frozen.io.statKind(frozen.resolvedPaths.detectDir) !== "dir") {
     return refuse(
       frozen.clientId,
@@ -860,7 +841,12 @@ export async function restoreIntegrationCoordinated(
   }
   return withIntegrationWriterLock(
     frozen.resolvedPaths.configPath,
-    async () => restoreIntegration({ ...frozen, opId: input.opId, confirmDrift: input.confirmDrift }),
+    async () => {
+      // An undo is bound like any other confirmation, and this is the only place where that check
+      // happens with the lock held and before the snapshot, the write and the journal row.
+      const refused = await options?.revalidate?.(frozen);
+      return refused ?? run();
+    },
     options?.lockSeams,
     spec.writerLock.suffix,
   );

package/src/lab/live/transport.ts

@@ -104,6 +104,10 @@ export function classifyTransportError(error: unknown): { classification: Failur
     case "network_blocked": return { classification: "network_failure", secondaryCode: code };
     case "region_blocked": return { classification: "region_blocked", secondaryCode: code };
     case "provider_transient": return { classification: "provider_transient", secondaryCode: code };
+    // A response this transport cannot read is an upstream protocol failure. It is deterministic
+    // rather than transient, and attributing it to the harness would blame the runner for what
+    // the peer sent.
+    case "unreadable_response": return { classification: "protocol_failure", secondaryCode: code };
     case "connect_timeout": case "first_byte_timeout": case "total_timeout":
       return { classification: "timeout", secondaryCode: code };
     case "inactivity_timeout":

package/src/lab/live/types.ts

@@ -89,6 +89,11 @@ export type TransportErrorCode =
   | "output_byte_limit"
   | "output_token_limit"
   | "tool_call_limit"
+  // The peer answered, and the answer cannot be read: a content coding this transport cannot
+  // undo, or coded bytes that did not decode. Neither is a timeout, a budget, or a fault of
+  // the harness, so none of those codes describes it and every one of them would send an
+  // operator looking in the wrong place.
+  | "unreadable_response"
   | "artifact_byte_limit"
   | "memory_limit"
   | "child_process_limit"

package/src/lab/subject/behavior-fingerprint.ts

@@ -9,7 +9,7 @@ const CLOSED_KEYS = new Set([
   "limits.contextWindow", "limits.maxInputTokens", "limits.maxOutputTokens",
   "modalities.input",
   "sampling.omitTemperature", "sampling.omitTopP", "sampling.omitPenalties",
-  "reasoning.supported", "reasoning.efforts", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
+  "reasoning.supported", "reasoning.efforts", "reasoning.effortsAuthoritative", "reasoning.defaultEffort", "reasoning.effortMap", "reasoning.wireFormat",
   "reasoning.summaryMode", "reasoning.replayMode", "reasoning.splitMode", "reasoning.toggleMode", "reasoning.budgetMode",
   "tools.choiceRestrictions", "tools.parallel", "tools.hostedPreference", "tools.customFreeform", "tools.builtinNameEscaping",
   "cache.forwarding", "cache.retention", "anthropic.eofPolicy", "openai-chat.eofPolicy",

package/src/lib/admin-secrets.ts

@@ -1,4 +1,4 @@
-import { timingSafeEqual } from "node:crypto";
+import { createHmac, timingSafeEqual } from "node:crypto";
 import { lstatSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getConfigDir } from "../config";
@@ -27,6 +27,14 @@ export function configuredAdminToken(configDir = getConfigDir(), env: NodeJS.Pro
 
 export const ADMIN_TOKEN_PREFIX = "ocx_admin_";
 
+/**
+ * Derive the bearer used by the OpenCode launcher for its one management read.
+ * A listener that captures this value cannot recover or replay the administrator token.
+ */
+export function opencodeCatalogToken(adminToken: string): string {
+  return `ocx_catalog_${createHmac("sha256", adminToken).update("opencode:/api/models:v1").digest("base64url")}`;
+}
+
 function secretTextEquals(left: string, right: string): boolean {
   const a = Buffer.from(left);
   const b = Buffer.from(right);

package/src/lib/bounded-body.ts

@@ -129,9 +129,11 @@ export async function readBoundedResponseBytes(
 	options: BoundedBytesOptions,
 ): Promise<BoundedBytesResult> {
 	const signal = options.signal;
-	if (signal?.aborted) throw signal.reason;
-
 	const body = response.body;
+	if (signal?.aborted) {
+		if (body) cancelBodyWithoutWaiting(body, signal.reason);
+		throw signal.reason;
+	}
 	if (!body) return { bytes: new Uint8Array(0), oversized: false };
 
 	const reader = body.getReader();

package/src/lib/debug-log-buffer.ts

@@ -9,7 +9,12 @@ export interface DebugLogEntry {
 
 const MAX_LINES = 2_000;
 const MAX_DEBUG_SUBSCRIBERS = 64;
-const MAX_DEBUG_LINE_BYTES = 16 * 1024;
+/**
+ * Per-line retention cap. Exported because a producer of a long structured line has to budget
+ * BELOW it: this buffer truncates at a byte boundary, so a JSON line cut here stops being
+ * parseable while its retained prefix still reads as complete.
+ */
+export const MAX_DEBUG_LINE_BYTES = 16 * 1024;
 const buffer: DebugLogEntry[] = [];
 interface DebugSubscriberRegistration { lease: AdmissionLease }
 const listeners = new Map<(entry: DebugLogEntry) => void, DebugSubscriberRegistration>();

package/src/lib/debug.ts

@@ -29,3 +29,26 @@ export function debugProviderDiagnostic(adapter: string, event: string, details:
     /* diagnostics must never affect request handling */
   }
 }
+
+/**
+ * The same diagnostic for details that are expensive to compute or read live request state.
+ *
+ * The eager form takes an already-built object, so the build runs in ARGUMENT position: outside
+ * this module's gate, and outside its try/catch. For a projection that walks a whole request
+ * that is wrong twice over — it pays the walk while debug is off, and a throw inside it reaches
+ * the caller, which for an adapter means a built request becomes a rejected one and a send that
+ * would have happened does not. Pass the builder instead: it runs only when debug is on, and a
+ * throw inside it is swallowed exactly like a throw in the emit.
+ */
+export function debugProviderDiagnosticLazy(
+  adapter: string,
+  event: string,
+  details: () => Record<string, unknown>,
+): void {
+  if (!isDebugEnabled()) return;
+  try {
+    emitDebugLine(`[ocx:${adapter}:${event}] ${JSON.stringify(redactSecrets(details()))}`);
+  } catch {
+    /* diagnostics must never affect request handling */
+  }
+}

package/src/lib/destination-policy.ts

@@ -240,6 +240,43 @@ function registryAllowsPrivateNetwork(name: string): boolean {
   return getProviderRegistryEntry(name)?.allowPrivateNetworkByDefault === true;
 }
 
+function normalizedCanonicalEndpoint(value: string): string | null {
+  try {
+    const parsed = new URL(value.trim());
+    if (parsed.username || parsed.password || parsed.hash) return null;
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return parsed.toString().replace(/\/$/, "");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Config-time Fake-IP allowance for the one overridable OAuth provider whose canonical
+ * Google endpoint is known to sit behind Clash/Mihomo transparent DNS in the field.
+ *
+ * Antigravity permits a custom base URL, so provider identity alone is not authority:
+ * adapter, auth mode, and the normalized final base URL must still match the registry seed.
+ * Custom destinations therefore keep the ordinary fail-closed SSRF policy.
+ */
+function registryAllowsBenchmarkDnsAtWriteTime(
+  name: string,
+  provider: Pick<OcxProviderConfig, "baseUrl"> & Partial<Pick<OcxProviderConfig, "adapter" | "authMode">>,
+): boolean {
+  if (name !== "google-antigravity") return false;
+  const entry = getProviderRegistryEntry(name);
+  if (
+    !entry
+    || entry.authKind !== "oauth"
+    || entry.allowBaseUrlOverride !== true
+    || provider.adapter !== entry.adapter
+    || provider.authMode !== "oauth"
+  ) return false;
+  const configured = normalizedCanonicalEndpoint(provider.baseUrl);
+  const canonical = normalizedCanonicalEndpoint(entry.baseUrl);
+  return configured !== null && configured === canonical;
+}
+
 /**
  * OAuth registry entries that opt into `allowBaseUrlOverride` send bearer credentials to a
  * user-configured endpoint (review findings, PR #2109 / PR #2110): a cleartext `http:`
@@ -328,13 +365,16 @@ export function assertProviderDestinationAllowed(name: string, provider: Pick<Oc
  * advisory and must not hard-fail offline startups. DNS rebinding after validation is
  * a recorded residual for this loopback proxy (devlog 260712_pr_batch_landing 000).
  *
- * `allowBenchmarkAddresses` is only for the exact canonical ChatGPT Codex seed under
- * Clash fake-IP DNS (198.18.0.0/15). Every other non-public answer — including mixed
- * benchmark + private/metadata sets — still fails.
+ * `allowBenchmarkAddresses` remains the explicit caller opt-in used by canonical ChatGPT
+ * Codex. Canonical Google Antigravity receives the same 198.18.0.0/15 DNS-answer exception
+ * only when its adapter/auth/base URL still match the registry seed. Every other non-public
+ * answer — including custom Antigravity destinations and mixed benchmark + private/metadata
+ * sets — still fails.
  */
 export async function providerDestinationResolvedError(
   name: string,
-  provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">,
+  provider: Pick<OcxProviderConfig, "baseUrl" | "allowPrivateNetwork">
+    & Partial<Pick<OcxProviderConfig, "adapter" | "authMode">>,
   options?: { allowBenchmarkAddresses?: boolean },
 ): Promise<string | null> {
   const syncError = providerDestinationConfigError(name, provider);
@@ -349,6 +389,8 @@ export async function providerDestinationResolvedError(
     return null; // literals and localhost are fully handled by the sync path
   }
   if (providerAllowsPrivateNetwork(name, provider)) return null;
+  const allowBenchmarkAddresses = options?.allowBenchmarkAddresses === true
+    || registryAllowsBenchmarkDnsAtWriteTime(name, provider);
   let addresses: { address: string }[];
   try {
     addresses = await lookup(hostname, { all: true, verbatim: true });
@@ -360,7 +402,7 @@ export async function providerDestinationResolvedError(
     const assessment = ipKind === 4 ? classifyIpv4(address) : ipKind === 6 ? classifyIpv6(normalizeHostname(address)) : null;
     if (!assessment || assessment.kind === "public") continue;
     // Clash fake-IP only: 198.18/19 benchmark detail. Mixed dangerous sets still reject.
-    if (options?.allowBenchmarkAddresses && isBenchmarkDnsAnswer(address, assessment)) {
+    if (allowBenchmarkAddresses && isBenchmarkDnsAnswer(address, assessment)) {
       continue;
     }
     if (assessment.kind === "metadata") return `baseUrl hostname ${hostname} resolves to a blocked metadata endpoint (${address})`;
@@ -492,4 +534,4 @@ export async function resolvePublicAddresses(
  */
 export async function assertUrlResolvesPublic(url: string): Promise<void> {
   await resolvePublicAddresses(url);
-}
+}

package/src/lib/errors.ts

@@ -1,3 +1,5 @@
+import { parseRetryAfterFromMessage } from "./retry-delay";
+
 export interface OcxErrorPayload {
   message: string;
   type: string;
@@ -72,6 +74,75 @@ export function isCyberPolicyMessage(text: string): boolean {
   return false;
 }
 
+/**
+ * Refusal codes Codex ends a turn on.
+ *
+ * Its Responses parser classifies a `response.failed` terminal by `error.code`
+ * alone (codex-rs/codex-api/src/sse/responses.rs:423-462). These four become a
+ * fatal `ApiError` the client reports instead of reconnecting. A code outside
+ * this set is never read as a refusal: `server_is_overloaded` and `slow_down`
+ * take the overload arm, `rate_limit_exceeded` takes the rate-limit arm, and
+ * everything else falls through to `ApiError::Retryable` and is reconnected up
+ * to `stream_max_retries`.
+ *
+ * Deliberately scoped to content refusals. `insufficient_quota` and
+ * `context_length_exceeded` are terminal for Codex too, but they are separate
+ * failure families this proxy already classifies through its own quota and
+ * context paths, and pulling them in here would change their retry behavior
+ * with no evidence asking for it.
+ */
+const TERMINAL_REFUSAL_CODES = new Set<string>([
+  CYBER_POLICY_ERROR_CODE,
+  "misalignment_policy_violation",
+  "invalid_prompt",
+  "bio_policy",
+]);
+
+/** True when an upstream error code is a refusal the client must not retry. */
+export function isTerminalRefusalCode(code: string | null | undefined): boolean {
+  return typeof code === "string" && TERMINAL_REFUSAL_CODES.has(code);
+}
+
+/** Stand-in copy for a refusal the upstream sent without a message of its own. */
+export const TERMINAL_REFUSAL_FALLBACK_MESSAGE = "The upstream refused this request.";
+
+/** Readable copy for a refusal code, used when the upstream carried no message. */
+export function terminalRefusalFallbackMessage(code: string): string {
+  return code === CYBER_POLICY_ERROR_CODE
+    ? CYBER_POLICY_FALLBACK_MESSAGE
+    : TERMINAL_REFUSAL_FALLBACK_MESSAGE;
+}
+
+/**
+ * Name the refusal code behind upstream safety copy when the structured code
+ * was not carried on the wire.
+ *
+ * Same discipline as {@link isCyberPolicyMessage}: whole distinctive phrases
+ * only. A loose match here is the mirror-image defect — it would end a turn
+ * that a genuine transient failure would have retried successfully — so a
+ * message that merely mentions safety or blocking does not qualify. Callers
+ * must consult this only when the upstream carried no structured code at all,
+ * so that a transport failure quoting a refusal in its diagnostic text cannot
+ * be promoted past the verdict the upstream actually gave.
+ *
+ * Copy provenance: "limited access to this content for safety reasons" is the
+ * prefix Codex itself matches (tui/src/chatwidget/turn_runtime.rs:8-15) and
+ * pairs with `invalid_prompt` in its parser fixture (sse/responses.rs:1358-1366),
+ * which also pairs "flagged for possible biological risk" with `bio_policy`.
+ * "blocked by our safety systems" is the copy reported in #5176; pairing it
+ * with `invalid_prompt` is an inference from the two verified pairings above,
+ * not something the upstream source states.
+ */
+export function safetyRefusalCodeFromMessage(text: string): string | undefined {
+  const lower = String(text ?? "").toLowerCase();
+  if (lower.includes("flagged for possible biological risk")) return "bio_policy";
+  if (
+    lower.includes("blocked by our safety systems")
+    || lower.includes("limited access to this content for safety reasons")
+  ) return "invalid_prompt";
+  return undefined;
+}
+
 function isSubscriptionGateMessage(text: string): boolean {
   return (
     text.includes("requires a subscription") ||
@@ -185,6 +256,16 @@ export function isClientClosedMessage(text: string): boolean {
   );
 }
 
+/**
+ * Ambiguous-reset refusal wording owned by this proxy (src/lib/upstream-retry.ts):
+ * the upstream connection closed before any response arrived, so the request may
+ * already have been processed and automatic replay was stopped. Matched narrowly
+ * so a provider-sent message is never relabeled by it.
+ */
+export function isUpstreamResetReplayRefusedMessage(text: string): boolean {
+  return text.toLowerCase().includes("connection closed before a response was received");
+}
+
 export function classifyError(status: number, type: string, message: string): OcxErrorPayload {
   const text = message.toLowerCase();
   if (type === "previous_response_not_found") {
@@ -376,21 +457,7 @@ export function isRateLimitOrQuotaFailureMessage(message: string): boolean {
   return normalized.toLowerCase().includes("usage limit");
 }
 
-/** Best-effort parse of a retry delay embedded in an upstream error message. */
-export function parseRetryAfterFromMessage(message: string): number | undefined {
-  const patterns = [
-    /try again in (\d+(?:\.\d+)?)\s*s(?:ec(?:ond)?s?)?/i,
-    /retry after (\d+(?:\.\d+)?)\s*s(?:ec(?:ond)?s?)?/i,
-    /retry[- ]after[:\s]+(\d+)/i,
-  ];
-  for (const pattern of patterns) {
-    const match = message.match(pattern);
-    if (!match?.[1]) continue;
-    const seconds = Number.parseFloat(match[1]);
-    if (Number.isFinite(seconds) && seconds > 0) return Math.ceil(seconds);
-  }
-  return undefined;
-}
+export { parseRetryAfterFromMessage };
 
 /** Infer HTTP status from adapter terminal error text (provider-agnostic keyword matching). */
 export function inferHttpStatusFromAdapterMessage(message: string): number {

package/src/lib/http-response-semantics.ts

@@ -0,0 +1,57 @@
+/**
+ * Response rules both raw outbound transports have to apply themselves.
+ *
+ * `fetch` applies them below the Response constructor. `src/lib/pinned-http.ts` and
+ * `src/lib/socks5-fetch.ts` assemble a Response from a socket instead, so each one answers the
+ * same questions on its own — and a rule written twice is a rule that drifts. It already had:
+ * the SOCKS helper excluded 204 and the pinned helper excluded nothing, so the same no-content
+ * upstream answer behaved differently depending on which transport carried the request.
+ */
+
+/**
+ * Statuses the Fetch specification defines as null-body.
+ *
+ * `new Response(body, { status })` throws a TypeError for a non-null body on any of these, so a
+ * transport that attaches its stream unconditionally converts a valid no-content answer into a
+ * construction failure. There are no body bytes to wait for either, so a transport that streams
+ * one of these holds the caller until the peer closes a connection it is entitled to keep alive.
+ *
+ * 101 and 103 are null-body statuses too, but neither is a final Response status these helpers
+ * support. 103 and every other informational head is consumed while looking for the final one,
+ * and 101 hands the connection to a protocol neither helper speaks, which is outside what they
+ * construct a Response for at all. The three below are the statuses these transports actually
+ * have to answer for.
+ *
+ * https://fetch.spec.whatwg.org/#null-body-status
+ */
+export function isNullBodyStatus(status: number): boolean {
+  return status === 204 || status === 205 || status === 304;
+}
+
+/** What a transport must do with the coding a response declares. */
+export type ContentCoding =
+  | { kind: "identity" }
+  | { kind: "decodable"; format: "gzip" | "deflate" }
+  | { kind: "unsupported"; coding: string };
+
+/**
+ * Classify the `content-encoding` a raw transport received.
+ *
+ * `fetch` undoes a content-coding below the Response constructor. A transport that assembles a
+ * body from a socket hands the coded bytes to whatever reads them instead: `response.json()`
+ * throws a SyntaxError on the gzip magic number and an SSE reader sees noise rather than frames.
+ * Only `gzip` and `deflate` can be undone with `DecompressionStream`, so anything else is
+ * reported as unsupported and each transport refuses it under its own error type rather than
+ * surfacing bytes no caller can parse.
+ *
+ * This reads the coding the response actually carries and nothing else. A caller whose
+ * `accept-encoding` names a coding this code cannot undo is not the problem; what the peer
+ * chose to send is.
+ */
+export function classifyContentCoding(headers: Headers): ContentCoding {
+  const coding = (headers.get("content-encoding") ?? "").trim().toLowerCase();
+  if (coding === "" || coding === "identity") return { kind: "identity" };
+  if (coding === "gzip" || coding === "x-gzip") return { kind: "decodable", format: "gzip" };
+  if (coding === "deflate") return { kind: "decodable", format: "deflate" };
+  return { kind: "unsupported", coding };
+}