@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/server/responses/codex-ws-exchange.ts

@@ -11,7 +11,9 @@ import type { CodexWsSession } from "./codex-ws-session";
 import { UPGRADE_DEADLINE_MS, CODEX_WS_LIVENESS_PING_INTERVAL_MS, CODEX_WS_RESPONSE_PRELUDE_TIMEOUT_MS, MAX_CODEX_WS_FRAME_BYTES,
   MAX_CODEX_WS_QUEUE_BYTES, markCodexWsResponse, markCodexWsPreludeProjection, normalizeResponsesWsRelayEvent, closedBeforeTerminalMessage,
   codexWsCreateFrameExceedsLimit, codexWsFailureDetail, codexWsPreResponseFailure, markCodexWsStage, codexWsOcxVersion,
-  markCodexWsSocketDeath, type CodexWsFailureStage, type CodexWsStageRecord } from "./codex-ws-wire";
+  markCodexWsSocketDeath, codexWsWrapperStatus, isCodexWsTerminalEvent, type CodexWsFailureStage, type CodexWsStageRecord,
+  type CodexWsTerminalEvent, codexWsPreOutputRefusalStatus, isEmptyCodexWsLifecycleEvent, codexWsFrameResponseIds,
+  markCodexWsPreOutputRefusal, type CodexWsPreOutputRefusalHold } from "./codex-ws-wire";
 
 interface ExchangeOptions {
   nativeControl?: NativeResponseControl;
@@ -26,6 +28,13 @@ interface ExchangeOptions {
   onPhysicalDispatch?: () => void;
   /** Bun version string the caller gated on; stamped onto the stage record. */
   bunVersion?: string;
+  /**
+   * Opt-in (#6969): how long empty lifecycle frames may be held so an authoritative upstream
+   * refusal that follows them, before any output, can settle as a replayable gateway status instead
+   * of a committed 200. Absent or zero keeps the exchange exactly as it was. Ignored on native
+   * control exchanges and on transports without the metadata channel.
+   */
+  preOutputRefusalHold?: CodexWsPreOutputRefusalHold;
 }
 
 const HTTP_HEADER_TOKEN = /^[!#$%&'*+.^_`|~0-9a-z-]+$/i;
@@ -75,6 +84,8 @@ function rejectionHeaders(source: Record<string, unknown>, prelude: Headers): He
  * responses_websocket.rs accepts status/status_code and scalar header values;
  * unlike its native client, this relay converts only precommit 4xx. Returning a
  * post-send 5xx or fetch rejection could cause the outer retry wrapper to resend.
+ * The one 5xx exception is the opt-in pre-output refusal below (#6969): a structured upstream
+ * refusal with nothing relayed but empty lifecycle frames, which the caller may replay.
  */
 function wrappedRejectionResponse(payload: Record<string, unknown>, prelude: Headers): Response | null {
   if (payload.type !== "error" || payload.stream_id !== undefined) return null;
@@ -92,9 +103,20 @@ function wrappedRejectionResponse(payload: Record<string, unknown>, prelude: Hea
   }), { status, headers });
 }
 
+/** The client-facing error of a pre-output refusal projection, from the refusal's own error object. */
+function refusalErrorBody(source: unknown): Record<string, string> {
+  const error = record(source) ? source : {};
+  return {
+    type: typeof error.type === "string" ? error.type : "server_error",
+    ...(typeof error.code === "string" ? { code: error.code } : {}),
+    message: typeof error.message === "string" ? error.message : "Upstream declined the request before any output",
+  };
+}
+
 /** The sole SSE exchange state machine for both one-shot and retained sockets. */
 export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
-  const { session, url, init, prepared, sseFallback, onQuota, beforeDispatch, bunVersion, nativeControl, beforeContinuation } = options;
+  const { session, url, init, prepared, sseFallback, onQuota, beforeDispatch, bunVersion, nativeControl, beforeContinuation,
+    preOutputRefusalHold } = options;
   const { frameText, headers } = prepared;
   const signal = init.signal ?? undefined;
   return new Promise<Response>((resolve, reject) => {
@@ -120,6 +142,9 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     // Numeric close code for the durable stage record; the reason string stays
     // out of it on purpose (#4191 content-free contract).
     let closeCode: number | null = null;
+    // #6740: which terminal frame the upstream itself sent, before any synthetic tail.
+    let terminalEvent: CodexWsTerminalEvent | null = null;
+    let terminalErrorStatus: number | null = null;
     let controller: ReadableStreamDefaultController<Uint8Array> | null = null;
     const encoder = new TextEncoder();
     const metadata = url === CODEX_RESPONSES_HTTP_URL ? new CodexWsMetadata(onQuota) : null;
@@ -135,6 +160,18 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
     // The resolved 200, retained so a later body failure can replace its
     // success-shaped stage record with the failure-shaped one (#4191).
     let committedResponse: Response | null = null;
+    // #6969: the pre-output refusal hold. While it is open, empty lifecycle frames are queued on the
+    // not-yet-exposed stream without resolving it. Every settle other than an eligible refusal
+    // commits first (deferredCommit), so the outcome is exactly what the exchange produced before.
+    const holdEnabled = (preOutputRefusalHold?.maxMs ?? 0) > 0 && metadata !== null && !nativeControl;
+    // Drops for good on any identity the exchange cannot tie to one response: a stream id, two
+    // different ids in one frame, or an id that differs from the first one seen. Independent of
+    // socket reuse, so a cold one-shot socket is held to the same rule as a pooled one.
+    let refusalEligible = holdEnabled;
+    let refusalResponseId: string | null = null;
+    let heldHeaders: Headers | null = null;
+    let deferredCommit = false;
+    let holdTimer: ReturnType<typeof setTimeout> | undefined;
     const stream = new ReadableStream<Uint8Array>({
       start(c) { controller = c; },
       cancel() {
@@ -149,6 +186,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       clearTimeout(upgradeTimer);
       clearTimeout(silenceTimer);
       clearTimeout(pingTimer);
+      clearTimeout(holdTimer);
       signal?.removeEventListener("abort", onAbort);
       metadata?.finish();
       correlation?.finish();
@@ -200,14 +238,20 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       reused: session.reused,
       ocxVersion: codexWsOcxVersion(),
       bunVersion: bunVersion ?? "unknown",
+      terminalEvent,
+      terminalErrorStatus,
     });
 
     const commitResponse = () => {
       if (responseCommitted) return;
       responseCommitted = true;
+      deferredCommit = false;
+      clearTimeout(holdTimer);
       clearTimeout(silenceTimer);
       clearTimeout(pingTimer);
-      const responseHeaders = metadata?.snapshot() ?? new Headers();
+      // A held preamble froze the prelude headers at the first Responses event, which is the moment
+      // they were frozen before the hold existed.
+      const responseHeaders = heldHeaders ? new Headers(heldHeaders) : metadata?.snapshot() ?? new Headers();
       responseHeaders.set("content-type", "text/event-stream; charset=utf-8");
       const response = new Response(stream, { status: 200, headers: responseHeaders });
       metadata?.commit();
@@ -218,9 +262,73 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       resolve(response);
     };
 
+    /**
+     * Open the hold at the first empty lifecycle frame: freeze the prelude and bound the wait by
+     * both the hold's own maximum and its absolute end. False when no time is left, so the frame
+     * commits exactly as it would without the hold.
+     */
+    const beginHold = (): boolean => {
+      if (heldHeaders) return true;
+      if (!metadata || !preOutputRefusalHold) return false;
+      const waitMs = Math.min(preOutputRefusalHold.maxMs, preOutputRefusalHold.until - Date.now());
+      if (waitMs <= 0) return false;
+      heldHeaders = metadata.snapshot();
+      metadata.commit();
+      holdTimer = setTimeout(() => {
+        if (!terminal && !responseCommitted) commitResponse();
+      }, waitMs);
+      return true;
+    };
+
+    const noteRefusalIdentity = (payload: Record<string, unknown>) => {
+      const ids = codexWsFrameResponseIds(payload);
+      if (payload.stream_id !== undefined || ids === null || ids.length > 1) {
+        refusalEligible = false;
+        return;
+      }
+      const id = ids[0];
+      if (id === undefined) return;
+      if (refusalResponseId === null) refusalResponseId = id;
+      else if (id !== refusalResponseId) refusalEligible = false;
+    };
+
+    /**
+     * Settle an authoritative pre-output refusal (#6969) as the gateway status the upstream stated,
+     * without the non-replayable marker: nothing but empty lifecycle frames was relayed, and the
+     * upstream ended that response itself. The caller's transient ladder and pool move may send the
+     * turn again; if neither does, the registered restore hands the client the original stream,
+     * which is already complete on `stream`.
+     */
+    const resolveRefusal = (status: number, payload: Record<string, unknown>, headers: Headers, prelude: Headers) => {
+      responseCommitted = true;
+      deferredCommit = false;
+      clearTimeout(holdTimer);
+      const stage = stageRecord(null);
+      const source = payload.type === "error"
+        ? payload.error
+        : record(payload.response) ? payload.response.error : undefined;
+      const projection = new Response(JSON.stringify({ error: refusalErrorBody(source) }), { status, headers });
+      markCodexWsPreludeProjection(projection);
+      markCodexWsStage(projection, stage);
+      const observed = Boolean(metadata && onQuota);
+      markCodexWsPreOutputRefusal(projection, () => {
+        const restoredHeaders = new Headers(prelude);
+        restoredHeaders.set("content-type", "text/event-stream; charset=utf-8");
+        const restored = new Response(stream, { status: 200, headers: restoredHeaders });
+        markCodexWsResponse(restored, observed);
+        // The same record object, so the attempt that adopted it keeps reading one stage.
+        markCodexWsStage(restored, stage);
+        return restored;
+      });
+      resolve(projection);
+    };
+
     const failStream = (error: unknown, status: 502 | 504 = 502, { socketDied = false } = {}) => {
       if (terminal) return;
       terminal = true;
+      // A held preamble or refusal was a commit deferred, not avoided: settle as the committed
+      // body failure it would have been, never as a new pre-response gateway status.
+      if (deferredCommit) commitResponse();
       if (sent && !responseCommitted && metadata) {
         // Nothing has been promised to the client yet, so the honest answer is a gateway
         // status, not a 200 whose body then fails. The frame may already be executing
@@ -305,7 +413,7 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
         reject(reason);
         return;
       }
-      if (!responseCommitted && metadata) {
+      if (!responseCommitted && metadata && !deferredCommit) {
         // Sent, unacknowledged. The proxy's own connect deadline is an origin-silence
         // verdict and settles like one; a caller abort is the caller's decision, so the
         // exchange rejects with that reason and disposing the socket cancels the turn.
@@ -497,16 +605,23 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
       }
       if (!controlFrame && !type.startsWith("response.") && type !== "error") return;
       let steeringEnded = false;
+      let refusalStatus: number | undefined;
+      let refusalHeaders: Headers | undefined;
+      let refusalPrelude: Headers | undefined;
       if (!controlFrame) {
         firstResponseAt ??= Date.now();
         try {
           if (nativeControl) steeringEnded = nativeControl.observe(normalized.payload);
           else correlation?.accept(normalized.payload);
         } catch (error) { failStream(error); return; }
+        const holdOpen = refusalEligible && sent && !responseCommitted;
+        if (holdOpen) noteRefusalIdentity(normalized.payload);
         // Correlation must run first: a reused socket's foreign-stream error settles as a
         // non-replayable 502 above, never as the refused-create 4xx projection below, which
         // is the one status family that could authorize an account replay.
-        if (metadata && sent && !responseCommitted && type === "error") {
+        // Only before anything was held: after an empty preamble a 4xx frame keeps today's
+        // in-body delivery, so a held 429 can never become a quota rotation it was not before.
+        if (metadata && sent && !responseCommitted && !deferredCommit && type === "error") {
           let rejection: Response | null;
           try { rejection = wrappedRejectionResponse(normalized.payload, metadata.snapshot()); }
           catch (error) { failStream(error); return; }
@@ -520,7 +635,30 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
             return;
           }
         }
-        commitResponse();
+        let holdFrame = false;
+        if (holdOpen && refusalEligible) {
+          refusalStatus = codexWsPreOutputRefusalStatus(normalized.payload);
+          if (refusalStatus !== undefined) {
+            // Built before anything settles: a refusal whose metadata cannot be projected within the
+            // header bounds is delivered the way it was before, in the committed body.
+            try {
+              refusalPrelude = heldHeaders ?? metadata?.snapshot() ?? new Headers();
+              const declared = normalized.payload.headers;
+              refusalHeaders = rejectionHeaders(record(declared) ? declared : {}, refusalPrelude);
+            } catch {
+              refusalStatus = undefined;
+            }
+          }
+          holdFrame = refusalStatus === undefined && isEmptyCodexWsLifecycleEvent(normalized.payload) && beginHold();
+        }
+        if (refusalStatus === undefined && !holdFrame) commitResponse();
+        else deferredCommit = true;
+        // Record the terminal the upstream sent as soon as it is accepted, before the relay-size and
+        // queue checks below: a body failure that follows is still an exchange that received it.
+        if (!nativeControl && isCodexWsTerminalEvent(type)) {
+          terminalEvent = type;
+          terminalErrorStatus = type === "error" ? (codexWsWrapperStatus(normalized.payload) ?? null) : null;
+        }
       }
       const prefix = encoder.encode(`event: ${type}\ndata: `);
       const suffix = encoder.encode("\n\n");
@@ -558,6 +696,9 @@ export function codexWsExchange(options: ExchangeOptions): Promise<Response> {
           markCodexWsStage(committedResponse, stageRecord(null));
         }
         session.release(completedId);
+        if (refusalStatus !== undefined && refusalHeaders && refusalPrelude && !responseCommitted) {
+          resolveRefusal(refusalStatus, normalized.payload, refusalHeaders, refusalPrelude);
+        }
       }
     };
 

package/src/server/responses/codex-ws-wire.ts

@@ -1,9 +1,11 @@
 import { MAX_CLIENT_SSE_FRAME_BYTES } from "../sse-frame-buffer";
 import {
+  isTransientUpstreamStatus,
   markResponseNonReplayable,
   UPSTREAM_CLOSED_BEFORE_RESPONSE_CODE,
   UPSTREAM_NO_RESPONSE_CODE,
 } from "../../lib/upstream-retry";
+import { isRateLimitOrQuotaFailureMessage, recognizedUpstreamError } from "../../lib/errors";
 import type { RequestFailureCause, RequestFailureStage } from "../../lib/request-failure-model";
 import { packageVersion } from "../../lib/package-version";
 // If the 101 never arrives (network black hole), give SSE a chance well before
@@ -107,8 +109,209 @@ export type CodexWsStageRecord = Omit<CodexWsFailureStage, "requestBytes"> & {
   ocxVersion: string;
   /** Bun runtime version the exchange gated on. */
   bunVersion: string;
+  /**
+   * Normalized type of the Responses terminal frame that ended a plain exchange, as the upstream
+   * sent it and before any tail this proxy synthesizes (#6740). It is what separates an upstream
+   * `error` frame from a genuine `response.failed` when both reach a row as the same synthetic 502.
+   * Null when no terminal frame arrived, and on native-control exchanges, which can end on an
+   * acknowledgement instead. Records written before it existed read as null.
+   */
+  terminalEvent: CodexWsTerminalEvent | null;
+  /** Wrapper status of a terminal `error` frame ({@link codexWsWrapperStatus}); null otherwise. */
+  terminalErrorStatus: number | null;
 };
 
+/** The frames a plain exchange ends on, closed so a stage record can never carry free text. */
+export const CODEX_WS_TERMINAL_EVENTS = [
+  "response.completed",
+  "response.failed",
+  "response.incomplete",
+  "error",
+] as const;
+export type CodexWsTerminalEvent = typeof CODEX_WS_TERMINAL_EVENTS[number];
+
+export function isCodexWsTerminalEvent(value: unknown): value is CodexWsTerminalEvent {
+  return typeof value === "string" && (CODEX_WS_TERMINAL_EVENTS as readonly string[]).includes(value);
+}
+
+/**
+ * The HTTP status a Codex WebSocket `error` frame states on its wrapper, or undefined.
+ *
+ * The backend wraps a failure as `{type:"error", status|status_code, error}` and the native client
+ * turns that status into an HTTP error of the same status
+ * (codex-rs/codex-api/src/endpoint/responses_websocket.rs map_wrapped_websocket_error_event). Only
+ * that contract is read: a top-level integer in 100..599 under exactly one of the two aliases, the
+ * same rule the pre-commit rejection projection applies.
+ */
+export function codexWsWrapperStatus(payload: Record<string, unknown>): number | undefined {
+  if (payload.type !== "error") return undefined;
+  const hasStatus = Object.hasOwn(payload, "status");
+  if (hasStatus === Object.hasOwn(payload, "status_code")) return undefined;
+  const status = hasStatus ? payload.status : payload.status_code;
+  return typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599
+    ? status
+    : undefined;
+}
+
+function plainRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+/** An absent or empty `output` array; anything else may already be visible to the client. */
+function emptyOutput(response: Record<string, unknown>): boolean {
+  const output = response.output;
+  return output === undefined || (Array.isArray(output) && output.length === 0);
+}
+
+/**
+ * Upper bound on how long an exchange may hold empty lifecycle frames while it waits to see
+ * whether the upstream refuses the turn before any output (#6969).
+ *
+ * Field rows put 97.5% of authoritative refusals within 5 s of the first Responses event and
+ * 98.2% within 10 s, with nothing gained after that.
+ */
+export const CODEX_WS_PRE_OUTPUT_REFUSAL_HOLD_MAX_MS = 10_000;
+
+/**
+ * The hold one send may use: at most `maxMs` from the first empty lifecycle frame, and never past
+ * `until`, an absolute time.
+ */
+export interface CodexWsPreOutputRefusalHold {
+  maxMs: number;
+  until: number;
+}
+
+/**
+ * The hold for a send starting now. The caller's header deadline (`connectTimeoutMs`) starts no
+ * earlier than this, so ending every hold by half of it means a held turn always commits well before
+ * that deadline could abort it, however late the first lifecycle frame arrives.
+ */
+export function codexWsPreOutputRefusalHold(connectMs: number, now = Date.now()): CodexWsPreOutputRefusalHold {
+  const half = Math.max(0, Math.floor(connectMs / 2));
+  return { maxMs: Math.min(CODEX_WS_PRE_OUTPUT_REFUSAL_HOLD_MAX_MS, half), until: now + half };
+}
+
+/**
+ * A lifecycle frame that commits nothing the client could see or act on (#6969): created,
+ * in-progress or queued, carrying a response object whose output is absent or empty. A snapshot
+ * with any output item, an unknown event, or a frame addressed to another stream is not one.
+ */
+export function isEmptyCodexWsLifecycleEvent(payload: Record<string, unknown>): boolean {
+  if (payload.type !== "response.created" && payload.type !== "response.in_progress"
+    && payload.type !== "response.queued") return false;
+  if (payload.stream_id !== undefined) return false;
+  return plainRecord(payload.response) && emptyOutput(payload.response);
+}
+
+const QUOTA_REFUSAL_IDENTITIES: ReadonlySet<string> = new Set(["usage_limit_reached", "usage_not_included"]);
+
+/** Quota and rate-limit identities keep their own routing: every `rate_limit*` and `*quota*` name. */
+function quotaRefusalIdentity(value: string): boolean {
+  const name = value.toLowerCase();
+  return QUOTA_REFUSAL_IDENTITIES.has(name) || name.startsWith("rate_limit") || name.includes("quota");
+}
+
+/**
+ * The status of an authoritative upstream refusal that ended a turn before any output (#6969),
+ * or undefined.
+ *
+ * Only structured evidence counts: a bare `error` frame's single wrapper status (the alias the
+ * native client turns into an HTTP error of that status, see {@link codexWsWrapperStatus}), or,
+ * with no wrapper alias at all, the recognized overload class; and a `response.failed` with an
+ * empty output whose error is the recognized overload class. The status must be a transient
+ * gateway status. Message wording never authorizes anything here; it can only veto, so a 5xx whose
+ * error names quota or a rate limit keeps the routing it has today.
+ */
+export function codexWsPreOutputRefusalStatus(payload: Record<string, unknown>): number | undefined {
+  if (payload.stream_id !== undefined) return undefined;
+  let error: unknown;
+  let status: number | undefined;
+  if (payload.type === "error") {
+    error = payload.error;
+    if (error !== undefined && !plainRecord(error)) return undefined;
+    const statedAlias = Object.hasOwn(payload, "status") || Object.hasOwn(payload, "status_code");
+    status = codexWsWrapperStatus(payload);
+    // A malformed or doubled alias is not evidence of anything.
+    if (statedAlias && status === undefined) return undefined;
+    if (status === undefined && plainRecord(error)) status = recognizedUpstreamError(error)?.httpStatus;
+  } else if (payload.type === "response.failed") {
+    const response = payload.response;
+    if (!plainRecord(response) || !emptyOutput(response)) return undefined;
+    error = response.error;
+    if (!plainRecord(error)) return undefined;
+    status = recognizedUpstreamError(error)?.httpStatus;
+  } else {
+    return undefined;
+  }
+  if (status === undefined || !isTransientUpstreamStatus(status)) return undefined;
+  if (plainRecord(error)) {
+    const { code, type, message } = error;
+    if ([code, type, message].some(value => value != null && typeof value !== "string")) return undefined;
+    if (typeof code === "string" && quotaRefusalIdentity(code)) return undefined;
+    if (typeof type === "string" && quotaRefusalIdentity(type)) return undefined;
+    if (typeof message === "string" && isRateLimitOrQuotaFailureMessage(message)) return undefined;
+  }
+  return status;
+}
+
+/**
+ * The response ids a frame names, for the exchange's replay-eligibility latch (#6969): the nested
+ * `response.id` and the top-level `response_id`. Null when a present id is not a string, which the
+ * latch treats as a conflict.
+ */
+export function codexWsFrameResponseIds(payload: Record<string, unknown>): string[] | null {
+  const ids: string[] = [];
+  const nested = plainRecord(payload.response) ? payload.response.id : undefined;
+  for (const value of [nested, payload.response_id]) {
+    if (value === undefined) continue;
+    if (typeof value !== "string") return null;
+    if (!ids.includes(value)) ids.push(value);
+  }
+  return ids;
+}
+
+interface PreOutputRefusalRecord {
+  restore: (() => Response) | null;
+  outcomeRecorded: boolean;
+}
+
+const preOutputRefusals = new WeakMap<Response, PreOutputRefusalRecord>();
+
+/**
+ * Register a pre-output refusal projection (#6969): a replayable gateway status standing in for a
+ * WebSocket exchange whose upstream refused the turn before any output. `restore` rebuilds the
+ * 200 event stream the client would have received without the projection.
+ */
+export function markCodexWsPreOutputRefusal(projection: Response, restore: () => Response): void {
+  preOutputRefusals.set(projection, { restore, outcomeRecorded: false });
+}
+
+export function isCodexWsPreOutputRefusal(response: Response): boolean {
+  return preOutputRefusals.has(response);
+}
+
+/** Record that this projection's account outcome was written, so no later owner writes it again. */
+export function noteCodexWsPreOutputRefusalOutcome(response: Response): void {
+  const record = preOutputRefusals.get(response);
+  if (record) record.outcomeRecorded = true;
+}
+
+export function codexWsPreOutputRefusalOutcomeRecorded(response: Response): boolean {
+  return preOutputRefusals.get(response)?.outcomeRecorded === true;
+}
+
+/**
+ * The response the client should receive in place of a projection no recovery replaced: the
+ * original event stream, byte for byte. Single use; any other response is returned unchanged.
+ */
+export function restoreCodexWsPreOutputRefusal(response: Response): Response {
+  const record = preOutputRefusals.get(response);
+  const restore = record?.restore;
+  if (!record || !restore) return response;
+  record.restore = null;
+  return restore();
+}
+
 const codexWsStageByResponse = new WeakMap<Response, CodexWsStageRecord>();
 
 export function markCodexWsStage(response: Response, record: CodexWsStageRecord): void {

package/src/server/responses/collaboration.ts

@@ -9,6 +9,8 @@ import {
 import { parseRequest } from "../../responses/parser";
 import { externalTaskInputContent } from "../../responses/task-input";
 import { MULTI_AGENT_MODE_HINT_RECOMMENDATION } from "../../codex/multi-agent-mode-policy";
+import { analyzeCodeModeExec } from "./code-mode-collab-surface";
+import { deferredV1Evidence } from "./deferred-collab-surface";
 import { buildCompactV1Output, COMPACT_PROMPT, decodeCompactionSummary, extractCompactUserMessages } from "../../responses/compaction";
 import { FORWARD_HEADERS, sanitizeReasoningInputContent } from "../../adapters/openai-responses";
 import { expandPreviousResponseInput, previousResponseProviderState, rememberResponseState } from "../../responses/state";
@@ -316,26 +318,53 @@ export function isV1CollabSurface(parsed: OcxParsedRequest): boolean {
 
 
 export function collabSurface(parsed: OcxParsedRequest): "v1" | "v2" | null {
+  const direct = directCollabSurface(parsed.context.tools);
+  // #6844: code-mode-only turns nest the collaboration tools inside `exec`, and tool-search turns
+  // defer them entirely. A rendered V1 listing or the deferred-namespace fragment can each infer V1;
+  // neither ever yields v2, overrides a different direct surface, or survives a rendered foreign
+  // collaboration claim.
+  const codeMode = analyzeCodeModeExec(parsed.context.tools);
+  if (codeMode.renderedV1 && codeMode.foreignCollabClaim) return null;
+  const inferredV1 = codeMode.renderedV1 || deferredV1Evidence(parsed, codeMode);
+  if (!inferredV1) return direct.surface;
+  if (codeMode.foreignCollabClaim) return null;
+  return !direct.sawNativeCollabTool || direct.surface === "v1" ? "v1" : null;
+}
+
+function directCollabSurface(tools: OcxParsedRequest["context"]["tools"]): {
+  surface: "v1" | "v2" | null;
+  sawNativeCollabTool: boolean;
+} {
   let namespacedSpawn = false;
   let flatSpawn = false;
   let v1Only = false;
   let v2Only = false;
-  for (const t of parsed.context.tools ?? []) {
+  // Collaboration-named direct tools outside an MCP namespace; an MCP server's own send_message or
+  // spawn_agent says nothing about the native surface, matching the nested check.
+  let sawNativeCollabTool = false;
+  for (const t of tools ?? []) {
+    const native = !t.namespace?.startsWith("mcp__");
     if (t.name === "spawn_agent") {
       if (t.namespace) namespacedSpawn = true;
       else flatSpawn = true;
+      if (native) sawNativeCollabTool = true;
     } else if (t.name === "send_input" || t.name === "resume_agent" || t.name === "close_agent") {
       v1Only = true;
+      if (native) sawNativeCollabTool = true;
     } else if (t.name === "send_message" || t.name === "followup_task" || t.name === "interrupt_agent" || t.name === "list_agents") {
       v2Only = true;
+      if (native) sawNativeCollabTool = true;
     }
   }
-  if (!namespacedSpawn && !flatSpawn) return null; // no spawn_agent -> no collab surface
-  if (namespacedSpawn && flatSpawn) return null;   // contradictory spawn shapes
-  if (v1Only && v2Only) return null;               // contradictory companions
-  if (v1Only) return "v1";
-  if (v2Only) return "v2";
-  return namespacedSpawn ? "v1" : "v2"; // companionless fallbacks (legacy defaults)
+  const surface = (): "v1" | "v2" | null => {
+    if (!namespacedSpawn && !flatSpawn) return null; // no spawn_agent -> no collab surface
+    if (namespacedSpawn && flatSpawn) return null;   // contradictory spawn shapes
+    if (v1Only && v2Only) return null;               // contradictory companions
+    if (v1Only) return "v1";
+    if (v2Only) return "v2";
+    return namespacedSpawn ? "v1" : "v2"; // companionless fallbacks (legacy defaults)
+  };
+  return { surface: surface(), sawNativeCollabTool };
 }