fix(live): validate upstream sideband handshake before upgrade

docs-site/src/content/docs/reference/proxy-formats.md

@@ -24,6 +24,30 @@ should select among several targets.
 
 Credential-bearing model, image, video, and search requests do not automatically follow HTTP redirects, including same-origin redirects. Configure the final upstream API URL instead of a redirecting alias. A redirect does not cause the server to resend credentials or the request body to its destination. The response owner retains its existing error or relay behavior; native Responses and compact routes can return the original 3xx and `Location` to the client. Client redirect behavior is separate from this server transport policy.
 
+## Empty search answers
+
+After hosted search, a clean but empty forced-answer pass receives one additional answer
+attempt with tools removed and existing results retained. This can incur another model
+request. A second empty answer fails; malformed calls and provider refusal or truncation
+outcomes are preserved without this retry.
+
+## Cursor context overflow
+
+Cursor's first bare context overflow is surfaced to the client. Later eligible requests
+with a stable client thread may recover with up to three conversation remints per retained
+scope. The in-memory allowance expires after one idle hour, eviction, or restart. Requests
+without a stable thread, isolated helpers, tool-result resumes, partial output, compaction
+and quota errors do not use this recovery. Continued eligible overflows keep the existing
+allowance active even after it is exhausted; they do not replenish it. This does not infer whether a task is making progress.
+
+## Live sideband connection failures
+
+The proxy completes the upstream live sideband handshake before accepting the client
+WebSocket. An upstream rejection fails the upgrade with 502; a ten-second handshake timeout
+returns 504, and client cancellation returns 499. Bun does not expose the exact upstream handshake status, so an upstream 404/410
+cannot currently be forwarded precisely. A successful connection preserves the initial session
+frames in order. This handshake policy is separate from the Responses WebSocket transport.
+
 ## Endpoint overview
 
 | Client surface | Endpoint | Successful non-stream result | Successful stream or socket result |

scripts/test-layout/layout.json

@@ -550,6 +550,7 @@
     "crash-guard.test.ts": "service",
     "credential-redirect-guard.test.ts": "lib",
     "cursor-adapter.test.ts": "providers/cursor",
+    "cursor-continuity-retention.test.ts": "providers/cursor",
     "cursor-arg-normalize.test.ts": "providers/cursor",
     "cursor-blob-integrity.test.ts": "providers/cursor",
     "cursor-blob.test.ts": "providers/cursor",

src/adapters/cursor.ts

@@ -3,7 +3,7 @@ import type { AdapterEvent, OcxProviderConfig } from "../types";
 import type { ProviderAdapter } from "./base";
 import { isTranslatorBudgetExceededError } from "../lib/translator-budget";
 import { cursorExecDeniedMessage, cursorRequestDeclaresFullAccess } from "./cursor/exec-policy";
-import { isCursorBenignCancelError, isCursorInvalidArgumentError, isCursorRootEnvelopeError, safeCursorErrorMessage, type CursorSizeContext } from "./cursor/cursor-errors";
+import { isCursorBenignCancelError, isCursorInvalidArgumentError, isCursorOverflowRemintCandidate, isCursorRootEnvelopeError, safeCursorErrorMessage, type CursorSizeContext } from "./cursor/cursor-errors";
 import { cursorCheckpointModelAffinityId, inferCursorContextWindow, isCursorExternalWireModel } from "./cursor/discovery";
 import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
 import { mapCursorServerMessage } from "./cursor/message-mapper";
@@ -31,7 +31,14 @@ import { debugProviderDiagnostic } from "../lib/debug";
 import { isDebugEnabled } from "../lib/debug-settings";
 import { createAdapterTierMetadata } from "../providers/fastwire";
 import { estimateTokens } from "../lib/token-estimate";
-import { rememberCursorThreadConversation } from "./cursor/thread-continuity";
+import {
+  cursorOverflowRemintScopeKey,
+  markCursorOverflowSurfaced,
+  recordCursorOverflowRemint,
+  rememberCursorThreadConversation,
+  shouldSkipCursorOverflowRemint,
+  shouldSurfaceCursorOverflowFirst,
+} from "./cursor/thread-continuity";
 import { runCursorTurnWithRetry } from "./cursor/transport-retry";
 import { cursorRequestHasShellAlias, cursorRequestUsesCodeMode } from "./cursor/tool-definitions";
 import {
@@ -399,84 +406,108 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
           );
         };
 
-        try {
-          await runOnce(request);
-        } catch (err) {
-          const outputGuardRetryText =
-            err instanceof CursorToolResultEchoError
-              ? CURSOR_ECHO_RETRY_CONTINUATION_TEXT
-              : err instanceof CursorRoutingCommentaryError
-                ? CURSOR_ROUTING_COMMENTARY_RETRY_TEXT
-                : undefined;
-          // One-shot corrective retry for guarded external output (devlog 260826 gap-10/11).
-          // The quarantine guarantees no client-visible delta escaped, so a fresh-conversation
-          // retry is safe. A second rejection propagates as an error rather than looping.
-          if (
-            outputGuardRetryText
-            && !emittedOutput
-            && !replayUnsafe
-            && !incoming.abortSignal?.aborted
-          ) {
-            debugProviderDiagnostic(
-              "cursor",
-              err instanceof CursorToolResultEchoError
-                ? "envelope-echo-retry"
-                : "routing-commentary-retry",
-              {
-              wireModel: request.modelId,
-              conversationHash: request.conversationId.slice(0, 16),
-              },
+        const remintConversationId = (failedConversationId: string) => {
+          lastTransport = undefined;
+          _parsed._cursorConversationId = undefined;
+          const next = createCursorRequest(_parsed, { forceFreshConversation: true });
+          rekeyContextUsage(failedConversationId, next.conversationId);
+          _parsed._cursorConversationId = next.conversationId;
+          // Persist recovery for store:false clients that send any stable Cursor thread owner, so
+          // the next turn does not recompute the stale deterministic thread hash. Isolated helper /
+          // compaction turns must not park their throwaway id under the parent or Desktop owner.
+          const threadOwner = cursorClientThreadOwner(_parsed);
+          if (threadOwner && _parsed._cursorIsolateConversation !== true) {
+            rememberCursorThreadConversation(
+              threadOwner,
+              next.conversationId,
+              _parsed._cursorIdentityScope,
             );
-            const echoedConversationId = request.conversationId;
-            lastTransport = undefined;
-            _parsed._cursorConversationId = undefined;
-            request = {
-              ...createCursorRequest(_parsed, { forceFreshConversation: true }),
-              echoRetryContinuationText: outputGuardRetryText,
-            };
-            rekeyContextUsage(echoedConversationId, request.conversationId);
-            _parsed._cursorConversationId = request.conversationId;
-            const echoThreadOwner = cursorClientThreadOwner(_parsed);
-            if (echoThreadOwner && _parsed._cursorIsolateConversation !== true) {
-              rememberCursorThreadConversation(
-                echoThreadOwner,
-                request.conversationId,
-                _parsed._cursorIdentityScope,
-              );
-            }
+          }
+          return next;
+        };
+
+        for (;;) {
+          try {
             await runOnce(request);
-          } else {
-            // One-shot fallback for external-model Connect invalid_argument before any
-            // non-heartbeat output. Retries apply only to safe plain-user turns; tool-result
-            // resumes, local exec/MCP side effects, and already-emitted output fail closed.
+            break;
+          } catch (err) {
+            const outputGuardRetryText =
+              err instanceof CursorToolResultEchoError
+                ? CURSOR_ECHO_RETRY_CONTINUATION_TEXT
+                : err instanceof CursorRoutingCommentaryError
+                  ? CURSOR_ROUTING_COMMENTARY_RETRY_TEXT
+                  : undefined;
+            // One-shot corrective retry for guarded external output (devlog 260826 gap-10/11).
+            // The quarantine guarantees no client-visible delta escaped, so a fresh-conversation
+            // retry is safe. A second rejection propagates as an error rather than looping.
             if (
-              !isCursorInvalidArgumentError(err)
-              || !isCursorExternalWireModel(request.modelId)
-              || lastRawIsToolResult
-              || emittedOutput
-              || replayUnsafe
-              || incoming.abortSignal?.aborted
+              outputGuardRetryText
+              && !emittedOutput
+              && !replayUnsafe
+              && !incoming.abortSignal?.aborted
             ) {
-              throw err;
-            }
-            const failedConversationId = request.conversationId;
-            lastTransport = undefined;
-            _parsed._cursorConversationId = undefined;
-            request = createCursorRequest(_parsed, { forceFreshConversation: true });
-            rekeyContextUsage(failedConversationId, request.conversationId);
-            _parsed._cursorConversationId = request.conversationId;
-            // Persist recovery for store:false clients that send any stable Cursor thread owner, so
-            // the next turn does not recompute the stale deterministic thread hash. Isolated helper /
-            // compaction turns must not park their throwaway id under the parent or Desktop owner.
-            const threadOwner = cursorClientThreadOwner(_parsed);
-            if (threadOwner && _parsed._cursorIsolateConversation !== true) {
-              rememberCursorThreadConversation(
-                threadOwner,
-                request.conversationId,
+              debugProviderDiagnostic(
+                "cursor",
+                err instanceof CursorToolResultEchoError
+                  ? "envelope-echo-retry"
+                  : "routing-commentary-retry",
+                {
+                wireModel: request.modelId,
+                conversationHash: request.conversationId.slice(0, 16),
+                },
+              );
+              const echoedConversationId = request.conversationId;
+              request = {
+                ...remintConversationId(echoedConversationId),
+                echoRetryContinuationText: outputGuardRetryText,
+              };
+              await runOnce(request);
+              break;
+            } else {
+              const overflowRemintSafe =
+                !lastRawIsToolResult
+                && !emittedOutput
+                && !replayUnsafe
+                && _parsed._cursorIsolateConversation !== true
+                && request.contextUsageStoreCheckpoints !== false
+                && !incoming.abortSignal?.aborted;
+              const overflowScopeKey = cursorOverflowRemintScopeKey(
+                cursorClientThreadOwner(_parsed),
                 _parsed._cursorIdentityScope,
               );
+              if (
+                overflowScopeKey
+                && overflowRemintSafe
+                && isCursorOverflowRemintCandidate(err, requestSizeContext)
+              ) {
+                if (shouldSkipCursorOverflowRemint(overflowScopeKey)) throw err;
+                if (shouldSurfaceCursorOverflowFirst(overflowScopeKey)) {
+                  markCursorOverflowSurfaced(overflowScopeKey);
+                  throw err;
+                }
+                if (!recordCursorOverflowRemint(overflowScopeKey)) throw err;
+                if (inheritedCheckpointRef) invalidateCursorCheckpoint(inheritedCheckpointRef);
+                request = remintConversationId(request.conversationId);
+                continue;
+              }
+
+              // One-shot fallback for external-model Connect invalid_argument before any
+              // non-heartbeat output. Retries apply only to safe plain-user turns; tool-result
+              // resumes, local exec/MCP side effects, and already-emitted output fail closed.
+              if (
+                !isCursorInvalidArgumentError(err)
+                || !isCursorExternalWireModel(request.modelId)
+                || lastRawIsToolResult
+                || emittedOutput
+                || replayUnsafe
+                || incoming.abortSignal?.aborted
+              ) {
+                throw err;
+              }
+              request = remintConversationId(request.conversationId);
+              await runOnce(request);
+              break;
             }
-            await runOnce(request);
           }
         }
         if (

src/adapters/cursor/cursor-errors.ts

@@ -191,6 +191,18 @@ function bareReLooksLikeOverflow(context?: CursorSizeContext): boolean {
   return estimatedInputTokens >= OVERFLOW_MIN_FRACTION * contextWindow;
 }
 
+/**
+ * True when a transport error is the bare 0-token resource_exhausted overflow shape
+ * (not quota/rate) that should surface for Codex compact or remint on later hits.
+ */
+export function isCursorOverflowRemintCandidate(err: unknown, sizeContext?: CursorSizeContext): boolean {
+  const message = errorMessage(err);
+  if (!message) return false;
+  const lower = message.toLowerCase();
+  if (!isCursorZeroTokenResourceExhausted(lower)) return false;
+  return classifyCursorError(message, sizeContext) === "Cursor context limit exceeded";
+}
+
 export function isCursorZeroTokenResourceExhausted(lowerMessage: string): boolean {
   if (!lowerMessage.includes("resource_exhausted") && !lowerMessage.includes("resource exhausted")) return false;
   // Any explicit quota/rate cue wins: this is a real 429.

src/adapters/cursor/thread-continuity.ts

@@ -65,3 +65,96 @@ export function lookupCursorThreadConversation(
 export function clearCursorThreadContinuityForTests(): void {
   overrides.clear();
 }
+
+/** Max conversation-id remints after the first surfaced overflow per retained scope. */
+export const CURSOR_OVERFLOW_REMINT_MAX = 3;
+export const CURSOR_OVERFLOW_REMINT_TTL_MS = 60 * 60 * 1000;
+export const CURSOR_OVERFLOW_REMINT_MAX_ENTRIES = 2_048;
+
+type OverflowRemintState = {
+  surfaced: boolean;
+  remintCount: number;
+  skip: boolean;
+  updatedAt: number;
+};
+
+const overflowRemintByScope = new Map<string, OverflowRemintState>();
+
+function pruneOverflowRemints(at: number): void {
+  for (const [scopeKey, entry] of overflowRemintByScope) {
+    if (at - entry.updatedAt > CURSOR_OVERFLOW_REMINT_TTL_MS) overflowRemintByScope.delete(scopeKey);
+  }
+  while (overflowRemintByScope.size > CURSOR_OVERFLOW_REMINT_MAX_ENTRIES) {
+    const oldest = overflowRemintByScope.keys().next().value;
+    if (oldest === undefined) break;
+    overflowRemintByScope.delete(oldest);
+  }
+}
+
+function overflowRemintEntry(scopeKey: string): OverflowRemintState {
+  const at = now();
+  pruneOverflowRemints(at);
+  const existing = overflowRemintByScope.get(scopeKey);
+  if (existing) {
+    existing.updatedAt = at;
+    overflowRemintByScope.delete(scopeKey);
+    overflowRemintByScope.set(scopeKey, existing);
+    return existing;
+  }
+  const fresh: OverflowRemintState = { surfaced: false, remintCount: 0, skip: false, updatedAt: at };
+  overflowRemintByScope.set(scopeKey, fresh);
+  pruneOverflowRemints(at);
+  return fresh;
+}
+
+/** Stable client-thread ownership survives conversation remints; wire ids alone do not. */
+export function cursorOverflowRemintScopeKey(
+  threadOwner: string | undefined,
+  identityScope?: string,
+): string | null {
+  if (!threadOwner) return null;
+  return `overflow\0${cursorThreadScopeKey(threadOwner, identityScope)}`;
+}
+
+/** True until the first overflow for this scope has been surfaced for Codex compact. */
+export function shouldSurfaceCursorOverflowFirst(scopeKey: string): boolean {
+  pruneOverflowRemints(now());
+  return overflowRemintByScope.get(scopeKey)?.surfaced !== true;
+}
+
+export function markCursorOverflowSurfaced(scopeKey: string): void {
+  const entry = overflowRemintEntry(scopeKey);
+  entry.surfaced = true;
+}
+
+export function shouldSkipCursorOverflowRemint(scopeKey: string): boolean {
+  const at = now();
+  pruneOverflowRemints(at);
+  const entry = overflowRemintByScope.get(scopeKey);
+  if (entry) {
+    entry.updatedAt = at;
+    overflowRemintByScope.delete(scopeKey);
+    overflowRemintByScope.set(scopeKey, entry);
+  }
+  return entry?.skip === true || (entry?.remintCount ?? 0) >= CURSOR_OVERFLOW_REMINT_MAX;
+}
+
+/** Record one overflow remint; returns false when the cap is exhausted. */
+export function recordCursorOverflowRemint(scopeKey: string): boolean {
+  const entry = overflowRemintEntry(scopeKey);
+  if (entry.skip || entry.remintCount >= CURSOR_OVERFLOW_REMINT_MAX) {
+    entry.skip = true;
+    return false;
+  }
+  entry.remintCount += 1;
+  return true;
+}
+
+export function clearCursorOverflowRemintForTests(): void {
+  overflowRemintByScope.clear();
+}
+
+export function cursorOverflowRemintCountForTests(): number {
+  pruneOverflowRemints(now());
+  return overflowRemintByScope.size;
+}