@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/adapters/cursor/live-transport.ts

@@ -87,7 +87,7 @@ import {
   type BackgroundShellTerminationReport,
 } from "./native-exec-shell";
 import type { CursorClientMessage, CursorRunRequest, CursorServerMessage } from "./types";
-import type { CursorTransport, CursorTransportFactoryInput } from "./transport";
+import type { CursorStreamHealthClock, CursorTransport, CursorTransportFactoryInput } from "./transport";
 import { CursorHttp1BidiConnection } from "./http1-bidi";
 import { isPinnedHttp1 } from "../../lib/upstream-http-version";
 
@@ -107,6 +107,16 @@ const CURSOR_STREAM_SILENCE_FAIL_MS = 30_000;
  * Reset on every decoded frame that is not liveness-only.
  */
 const CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS = 90_000;
+/**
+ * The production T04 clock. The watchdog reads time and schedules its one timer through this
+ * object so a test can supply a clock it advances by hand; nothing else about the transport's
+ * timers moves with it.
+ */
+const REAL_STREAM_HEALTH_CLOCK: CursorStreamHealthClock = {
+  now: () => Date.now(),
+  setTimeout: (callback, ms) => setTimeout(callback, ms),
+  clearTimeout: timer => clearTimeout(timer),
+};
 /**
  * After `turnEnded` is decoded, the application turn is complete. A server that keeps
  * HTTP/2 open past this point cannot hold the turn hostage (senpi #1062): we close our side
@@ -494,6 +504,8 @@ class LiveCursorTransport implements CursorTransport {
   private lastInboundFrameAt = 0;
   private lastMeaningfulFrameAt = 0;
   private streamHealthFail?: (error: Error) => void;
+  /** Time source for the T04 watchdog only; the globals unless a test injects one. */
+  private readonly streamHealthClock: CursorStreamHealthClock;
   private committed = false;
   private expectedClose = false;
   /**
@@ -542,6 +554,7 @@ class LiveCursorTransport implements CursorTransport {
     // so the transport-level race test can drive it deterministically.
     this.clientToolFinalizeGraceMs = input.clientToolFinalizeGraceMs ?? CLIENT_TOOL_FINALIZE_GRACE_MS;
     this.activeClientToolFinalizeGraceMs = this.clientToolFinalizeGraceMs;
+    this.streamHealthClock = input.streamHealthClock ?? REAL_STREAM_HEALTH_CLOCK;
     // Desktop (computer-use / record-screen) executors are available even with no MCP servers.
     this.desktopDeps = desktopDepsFromConfig(input.provider.desktopExecutor);
     this.execContext = {
@@ -847,7 +860,7 @@ class LiveCursorTransport implements CursorTransport {
 
   private clearStreamHealthTimer(): void {
     if (this.streamHealthTimer) {
-      clearTimeout(this.streamHealthTimer);
+      this.streamHealthClock.clearTimeout(this.streamHealthTimer);
       this.streamHealthTimer = undefined;
     }
     this.streamHealthFail = undefined;
@@ -858,24 +871,28 @@ class LiveCursorTransport implements CursorTransport {
    * failAndClear; the timer owns nothing else. Never armed before the first decoded
    * frame (the first-frame timer covers dial + first response), and disarmed by
    * every settle / expected-close path alongside the other timers.
+   *
+   * Both clocks and the timer go through `streamHealthClock`, which is the globals in
+   * production. The `elapsedMs` diagnostic below deliberately stays on the wall clock,
+   * because `turnStartedAt` is stamped there and the pair has to subtract coherently.
    */
   private armStreamHealthTimer(fail: (error: Error) => void): void {
-    if (this.streamHealthTimer) clearTimeout(this.streamHealthTimer);
+    if (this.streamHealthTimer) this.streamHealthClock.clearTimeout(this.streamHealthTimer);
     if (this.expectedClose) return;
     this.streamHealthFail = fail;
     const silenceMs = this.input.streamSilenceFailMs ?? CURSOR_STREAM_SILENCE_FAIL_MS;
     const heartbeatOnlyMs = this.input.streamHeartbeatOnlyFailMs ?? CURSOR_STREAM_HEARTBEAT_ONLY_FAIL_MS;
-    const now = Date.now();
+    const now = this.streamHealthClock.now();
     const deadline = Math.min(
       this.lastInboundFrameAt + silenceMs,
       this.lastMeaningfulFrameAt + heartbeatOnlyMs,
     );
-    this.streamHealthTimer = setTimeout(() => {
+    this.streamHealthTimer = this.streamHealthClock.setTimeout(() => {
       this.streamHealthTimer = undefined;
       const failFn = this.streamHealthFail;
       if (!failFn || this.expectedClose) return;
-      const stalledFor = Date.now() - this.lastInboundFrameAt;
-      const meaningfulStalledFor = Date.now() - this.lastMeaningfulFrameAt;
+      const stalledFor = this.streamHealthClock.now() - this.lastInboundFrameAt;
+      const meaningfulStalledFor = this.streamHealthClock.now() - this.lastMeaningfulFrameAt;
       if (stalledFor < silenceMs && meaningfulStalledFor < heartbeatOnlyMs) {
         // A frame landed between arming and firing — re-arm for the fresh deadline.
         this.armStreamHealthTimer(failFn);
@@ -906,7 +923,7 @@ class LiveCursorTransport implements CursorTransport {
    * heartbeat-only threshold.
    */
   private noteInboundFrame(livenessOnly: boolean): void {
-    const now = Date.now();
+    const now = this.streamHealthClock.now();
     this.lastInboundFrameAt = now;
     if (!livenessOnly) this.lastMeaningfulFrameAt = now;
     if (this.streamHealthFail) this.armStreamHealthTimer(this.streamHealthFail);
@@ -1288,7 +1305,7 @@ class LiveCursorTransport implements CursorTransport {
       const decodedUpdate = decoded.message.case === "interactionUpdate" ? decoded.message.value.message?.case : undefined;
       const livenessOnly = decodedUpdate === "heartbeat" || decoded.message.case === "conversationCheckpointUpdate";
       if (!this.streamHealthFail) {
-        const now = Date.now();
+        const now = this.streamHealthClock.now();
         this.lastInboundFrameAt = now;
         this.lastMeaningfulFrameAt = now;
         this.streamHealthFail = failAndClear;

package/src/adapters/cursor/message-mapper.ts

@@ -46,7 +46,8 @@ export function mapCursorServerMessage(
       state.writeClient(cursorExecResult(message.requestId, message.execCase));
       return [];
     case "local_side_effect":
-      // Internal retry-safety signal only; keep the bridge alive without producing protocol output.
-      return [{ type: "heartbeat" }];
+      // Internal retry-safety signal only; keep the bridge alive without producing protocol output,
+      // while preventing server-level failover from replaying the completed local operation.
+      return [{ type: "heartbeat", replayUnsafe: true }];
   }
 }

package/src/adapters/cursor/protobuf-request.ts

@@ -6,6 +6,7 @@ import { namespacedToolName } from "../../types";
 import type { CursorRunRequest } from "./types";
 import { decodeCursorCallId } from "./call-id";
 import { cursorNeedsExternalToolContinuation, isCursorExternalWireModel } from "./discovery";
+import { stripAssistantEchoedToolEnvelope } from "./envelope-echo";
 import { normalizeCursorToolResultText } from "./tool-result-normalize";
 import { debugProviderDiagnostic } from "../../lib/debug";
 import {
@@ -208,11 +209,13 @@ function assistantRootText(
   message: Extract<OcxMessage, { role: "assistant" }>,
   includeThinking: boolean,
 ): string {
-  if (typeof message.content === "string") return message.content;
-  return message.content
-    .map(part => (part.type === "text" ? part.text : includeThinking && part.type === "thinking" ? part.thinking : undefined))
-    .filter((value): value is string => typeof value === "string" && value.length > 0)
-    .join("\n");
+  const raw = typeof message.content === "string"
+    ? message.content
+    : message.content
+      .map(part => (part.type === "text" ? part.text : includeThinking && part.type === "thinking" ? part.thinking : undefined))
+      .filter((value): value is string => typeof value === "string" && value.length > 0)
+      .join("\n");
+  return stripAssistantEchoedToolEnvelope(raw);
 }
 
 // Cursor builds the actual model prompt from rootPromptMessagesJson (turns[] is UI/display metadata),

package/src/adapters/cursor/request-builder.ts

@@ -340,7 +340,13 @@ export function cursorConversationIdFromClientThread(threadId: string, identityS
 
 /**
  * Resolve the Cursor conversation id for this turn.
- * Priority: force-fresh → isolate helper → remembered → client thread owner → random.
+ * Priority: force-fresh → isolate helper → thread remint override → stored conversation id
+ * → client thread hash → random.
+ *
+ * The remint override must beat a stored `_cursorConversationId`. Only the remint path writes
+ * the thread store (cursor.ts), so a stored id that disagrees with it is the pre-remint value,
+ * and preferring it let a second Responses chain in the same Codex thread keep resuming the
+ * conversation the previous turn just rotated away from.
  * Never use OpenAI Responses `previous_response_id` (resp_*) or shared `prompt_cache_key`
  * (cache-cohort fingerprint, not conversation ownership).
  */
@@ -351,11 +357,16 @@ export function resolveCursorConversationId(
 ): string {
   if (options.forceFreshConversation === true) return generatedCursorConversationId();
   if (parsed._cursorIsolateConversation === true) return generatedCursorConversationId();
-  if (parsed._cursorConversationId) return parsed._cursorConversationId;
   const threadId = cursorClientThreadOwner(parsed);
-  if (threadId) {
+  // A compaction turn carries its own conversation id and must not be pulled onto the parent's
+  // thread override. It is isolated in effect without ever setting the isolate flag, which is why
+  // the override check has to exclude it explicitly rather than rely on that flag.
+  if (threadId && parsed._compactionRequest !== true) {
     const recovered = lookupCursorThreadConversation(threadId, parsed._cursorIdentityScope);
     if (recovered) return recovered;
+  }
+  if (parsed._cursorConversationId) return parsed._cursorConversationId;
+  if (threadId) {
     return cursorConversationIdFromClientThread(`thread:${threadId}`, parsed._cursorIdentityScope);
   }
   return generatedCursorConversationId();
@@ -465,7 +476,13 @@ function resolveCursorCheckpoint(
   if (cursorCheckpointModelAffinityId(snapshot.modelId) !== cursorCheckpointModelAffinityId(request.modelId)) {
     return { reason: "model_changed" };
   }
-  if (parsed.context.messages.at(-1)?.role !== "toolResult" && cursorState?.checkpointUsable === false) {
+  // The continuation state only exists on the ref path; a ref-less prefix hit carries
+  // the suspension on the snapshot itself, or a non-toolResult request could resume
+  // bytes upstream serialized mid-tool-call.
+  if (
+    parsed.context.messages.at(-1)?.role !== "toolResult"
+    && (snapshot.toolSuspended === true || cursorState?.checkpointUsable === false)
+  ) {
     return { reason: "trailing_tool_result" };
   }
   const lineage = lineageMismatch(parsed, snapshot);

package/src/adapters/cursor/thread-continuity.ts

@@ -169,21 +169,65 @@ type IncompleteToolRemintState = {
   updatedAt: number;
 };
 
-const incompleteToolRemintByScope = new Map<string, IncompleteToolRemintState>();
+/**
+ * One bounded next-turn remint allowance, keyed by retained thread scope.
+ *
+ * Each recovery reason owns its own instance. Sharing one budget would let a cheap, frequent
+ * failure spend the allowance that a rarer, more expensive recovery depends on.
+ */
+function createCursorRemintBudget(max: number, ttlMs: number, maxEntries: number) {
+  const byScope = new Map<string, IncompleteToolRemintState>();
 
-function pruneIncompleteToolRemints(at: number): void {
-  for (const [scopeKey, entry] of incompleteToolRemintByScope) {
-    if (at - entry.updatedAt > CURSOR_INCOMPLETE_TOOL_REMINT_TTL_MS) {
-      incompleteToolRemintByScope.delete(scopeKey);
+  const prune = (at: number): void => {
+    for (const [scopeKey, entry] of byScope) {
+      if (at - entry.updatedAt > ttlMs) byScope.delete(scopeKey);
     }
-  }
-  while (incompleteToolRemintByScope.size > CURSOR_INCOMPLETE_TOOL_REMINT_MAX_ENTRIES) {
-    const oldest = incompleteToolRemintByScope.keys().next().value;
-    if (oldest === undefined) break;
-    incompleteToolRemintByScope.delete(oldest);
-  }
+    while (byScope.size > maxEntries) {
+      const oldest = byScope.keys().next().value;
+      if (oldest === undefined) break;
+      byScope.delete(oldest);
+    }
+  };
+
+  return {
+    /** Record one remint; returns false when this budget is exhausted. */
+    record(scopeKey: string): boolean {
+      const at = now();
+      prune(at);
+      const existing = byScope.get(scopeKey);
+      if (existing && existing.remintCount >= max) {
+        existing.updatedAt = at;
+        byScope.delete(scopeKey);
+        byScope.set(scopeKey, existing);
+        return false;
+      }
+      const entry = existing ?? { remintCount: 0, updatedAt: at };
+      entry.remintCount += 1;
+      entry.updatedAt = at;
+      byScope.delete(scopeKey);
+      byScope.set(scopeKey, entry);
+      prune(at);
+      return true;
+    },
+    clear(scopeKey: string): void {
+      byScope.delete(scopeKey);
+    },
+    clearForTests(): void {
+      byScope.clear();
+    },
+    countForTests(): number {
+      prune(now());
+      return byScope.size;
+    },
+  };
 }
 
+const incompleteToolRemintBudget = createCursorRemintBudget(
+  CURSOR_INCOMPLETE_TOOL_REMINT_MAX,
+  CURSOR_INCOMPLETE_TOOL_REMINT_TTL_MS,
+  CURSOR_INCOMPLETE_TOOL_REMINT_MAX_ENTRIES,
+);
+
 /** Incomplete-tool and overflow recovery share ownership scope, but keep independent budgets. */
 export function cursorIncompleteToolRemintScopeKey(
   threadOwner: string | undefined,
@@ -194,34 +238,64 @@ export function cursorIncompleteToolRemintScopeKey(
 
 /** Record one incomplete-tool remint; returns false when the independent cap is exhausted. */
 export function recordCursorIncompleteToolRemint(scopeKey: string): boolean {
-  const at = now();
-  pruneIncompleteToolRemints(at);
-  const existing = incompleteToolRemintByScope.get(scopeKey);
-  if (existing && existing.remintCount >= CURSOR_INCOMPLETE_TOOL_REMINT_MAX) {
-    existing.updatedAt = at;
-    incompleteToolRemintByScope.delete(scopeKey);
-    incompleteToolRemintByScope.set(scopeKey, existing);
-    return false;
-  }
-  const entry = existing ?? { remintCount: 0, updatedAt: at };
-  entry.remintCount += 1;
-  entry.updatedAt = at;
-  incompleteToolRemintByScope.delete(scopeKey);
-  incompleteToolRemintByScope.set(scopeKey, entry);
-  pruneIncompleteToolRemints(at);
-  return true;
+  return incompleteToolRemintBudget.record(scopeKey);
 }
 
 /** A clean turn replenishes this recovery without changing the overflow retry budget. */
 export function clearCursorIncompleteToolRemint(scopeKey: string): void {
-  incompleteToolRemintByScope.delete(scopeKey);
+  incompleteToolRemintBudget.clear(scopeKey);
 }
 
 export function clearCursorIncompleteToolRemintForTests(): void {
-  incompleteToolRemintByScope.clear();
+  incompleteToolRemintBudget.clearForTests();
 }
 
 export function cursorIncompleteToolRemintCountForTests(): number {
-  pruneIncompleteToolRemints(now());
-  return incompleteToolRemintByScope.size;
+  return incompleteToolRemintBudget.countForTests();
+}
+
+/**
+ * Max next-turn rotations after a MID-STREAM envelope echo, per retained scope.
+ *
+ * Deliberately a separate budget from the incomplete-tool allowance. A mid-stream echo is a
+ * cheap, repeatable formatting failure, while an incomplete client-tool stream is a rarer
+ * structural one; on a shared counter a model that echoes every turn would spend the budget
+ * that incomplete-tool recovery depends on. Bounding it at all is the point: the echo has
+ * already reached the client and cannot be quarantined, so without a cap a persistently
+ * echoing model would remint the conversation on every single turn, forever.
+ */
+export const CURSOR_ENVELOPE_ECHO_REMINT_MAX = 3;
+export const CURSOR_ENVELOPE_ECHO_REMINT_TTL_MS = CURSOR_OVERFLOW_REMINT_TTL_MS;
+export const CURSOR_ENVELOPE_ECHO_REMINT_MAX_ENTRIES = CURSOR_OVERFLOW_REMINT_MAX_ENTRIES;
+
+const envelopeEchoRemintBudget = createCursorRemintBudget(
+  CURSOR_ENVELOPE_ECHO_REMINT_MAX,
+  CURSOR_ENVELOPE_ECHO_REMINT_TTL_MS,
+  CURSOR_ENVELOPE_ECHO_REMINT_MAX_ENTRIES,
+);
+
+/** Echo recovery shares ownership scope with overflow and incomplete-tool, budget apart. */
+export function cursorEnvelopeEchoRemintScopeKey(
+  threadOwner: string | undefined,
+  identityScope?: string,
+): string | null {
+  return cursorOverflowRemintScopeKey(threadOwner, identityScope);
+}
+
+/** Record one envelope-echo remint; returns false when the independent cap is exhausted. */
+export function recordCursorEnvelopeEchoRemint(scopeKey: string): boolean {
+  return envelopeEchoRemintBudget.record(scopeKey);
+}
+
+/** A turn that completed without an echo replenishes only this budget. */
+export function clearCursorEnvelopeEchoRemint(scopeKey: string): void {
+  envelopeEchoRemintBudget.clear(scopeKey);
+}
+
+export function clearCursorEnvelopeEchoRemintForTests(): void {
+  envelopeEchoRemintBudget.clearForTests();
+}
+
+export function cursorEnvelopeEchoRemintCountForTests(): number {
+  return envelopeEchoRemintBudget.countForTests();
 }

package/src/adapters/cursor/tool-guidance.ts

@@ -4,13 +4,14 @@ import { CODEX_SHELL_BRIDGE_TOOL_NAMES, CODEX_TOOL_SEARCH_TOOL, CODEX_UNIFIED_EX
 
 export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE =
   'Shell commands use the Codex shell bridge tool shown in this turn\'s catalog (`shell_command` or `exec_command`) with JSON arguments like {"cmd":"..."}. The long `mcp_opencodex-responses_*` display name is the same tool. Prefer it over Cursor-native Shell.';
-const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
+const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS", "Write"] as const;
 const NEIGHBOR_AGENT_TOOL_ALIASES: Record<(typeof NEIGHBOR_AGENT_TOOL_NAMES)[number], readonly string[]> = {
   Read: ["read", "read_file"],
   Grep: ["grep"],
   Glob: ["glob", "find"],
   Bash: ["bash", "shell"],
   LS: ["ls"],
+  Write: ["write", "write_file"],
 };
 
 export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
@@ -22,7 +23,7 @@ export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
   "The Cursor bridge may suspend after the first returned bridge tool call, so emit sibling calls together before any result is needed.",
   "If parallel emission is unavailable, continue with separate shell-bridge calls until the requested count has returned.",
   "Do not use `tool_search`, external MCP, or resource discovery just to pad the count unless explicitly asked.",
-  "Do not suggest or switch to neighboring-agent tools such as `Grep`, `Read`, `Glob`, `Bash`, or `LS` unless this turn's catalog lists those exact names or an equivalent listed client tool.",
+  "Do not suggest or switch to neighboring-agent tools such as `Grep`, `Read`, `Glob`, `Bash`, `LS`, or `Write` unless this turn's catalog lists those exact names or an equivalent listed client tool.",
 ].join(" ");
 
 
@@ -190,7 +191,7 @@ export function buildCursorToolGuidanceSystemNote(
       ? CODE_MODE_RESULT_ECHO_SENTENCE + " There is no `require`, no `module`, and no filesystem or network globals; reach the host only through the nested helpers. " + CODE_MODE_HOST_CONTRACT_SENTENCE
       : undefined,
     codeMode
-      ? "NEVER attempt Cursor-native Shell, Read, Grep, List, or any tool absent from the catalog — they are not executed in this environment and every probe wastes a turn. The exec code cell (with its nested helpers) is the ONLY execution surface; go to it directly on the FIRST attempt and do not narrate switching surfaces."
+      ? "NEVER attempt Cursor-native Shell, Read, Grep, List, Write, or any tool absent from the catalog — they are not executed in this environment and every probe wastes a turn. The exec code cell (with its nested helpers) is the ONLY execution surface; go to it directly on the FIRST attempt and do not narrate switching surfaces."
       : undefined,
     hasBareExec
       ? `${shellBridgeLabel} is the Codex Responses shell bridge for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool. \`shell_command\` and \`exec_command\` are aliases of the same bridge.`
@@ -199,7 +200,7 @@ export function buildCursorToolGuidanceSystemNote(
       ? "Your tool list may display it under a longer `mcp_opencodex-responses_shell_command` / `mcp_opencodex-responses_exec_command` name; those are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
       : undefined,
     hasBareExec
-      ? `NEVER attempt Cursor-native Shell, Read, Grep, List, or any tool not in the catalog above — they are not executed locally in this environment and every attempt wastes a turn and can stall the session. ${shellBridgeLabel} is the ONLY shell surface; go to it directly on the FIRST attempt, never as a fallback after probing a native tool. Do not narrate switching surfaces ("native is blocked, using the bridge instead") — there is exactly one surface.`
+      ? `NEVER attempt Cursor-native Shell, Read, Grep, List, Write, or any tool not in the catalog above — they are not executed locally in this environment and every attempt wastes a turn and can stall the session. ${shellBridgeLabel} is the ONLY shell surface; go to it directly on the FIRST attempt, never as a fallback after probing a native tool. Do not narrate switching surfaces ("native is blocked, using the bridge instead") — there is exactly one surface.`
       : undefined,
     hasBareExec
       ? "Tool-selection commentary is forbidden: for any shell, read, grep, list, or file operation, your FIRST visible action is the bridge call itself — never a sentence about which tool you will use, which tool was redirected, or switching surfaces. Words like 차단/전환/blocked/switching must not appear in your output for tool-routing reasons."

package/src/adapters/cursor/transport.ts

@@ -55,6 +55,25 @@ export interface CursorTransportFactoryInput {
    * client thread. Distinct from the per-transport native-exec/shell owner.
    */
   sessionId?: string;
+  /**
+   * Test-only clock for the T04 inbound stream-health watchdog. Production omits it and the
+   * transport uses the global timers; injecting here must not change scheduling semantics.
+   *
+   * It exists because the watchdog's contract — a meaningful frame re-arms both deadlines — can
+   * only be asserted against real timers by keeping a synthetic server delivering frames faster
+   * than the silence budget for several multiples of it. That is an assertion about how busy the
+   * machine is, and it failed in the unsharded macOS lane for exactly that reason while the
+   * watchdog was working correctly. With the clock injected, virtual time advances only where
+   * the test says it does, so no amount of runner contention can expire a deadline.
+   */
+  streamHealthClock?: CursorStreamHealthClock;
+}
+
+/** The three time primitives the T04 watchdog uses. Production binds all three to the globals. */
+export interface CursorStreamHealthClock {
+  now(): number;
+  setTimeout(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
+  clearTimeout(timer: ReturnType<typeof setTimeout>): void;
 }
 
 export type CursorTransportFactory = (input: CursorTransportFactoryInput) => CursorTransport;

package/src/adapters/cursor.ts

@@ -34,9 +34,12 @@ import { estimateTokens } from "../lib/token-estimate";
 import {
   clearCursorIncompleteToolRemint,
   cursorIncompleteToolRemintScopeKey,
+  clearCursorEnvelopeEchoRemint,
+  cursorEnvelopeEchoRemintScopeKey,
   cursorOverflowRemintScopeKey,
   markCursorOverflowSurfaced,
   recordCursorIncompleteToolRemint,
+  recordCursorEnvelopeEchoRemint,
   recordCursorOverflowRemint,
   rememberCursorThreadConversation,
   shouldSkipCursorOverflowRemint,
@@ -206,6 +209,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         let lastTransport: { captured?: Uint8Array } | undefined;
         let emittedClientTool = false;
         let sawIncompleteToolCall = false;
+        let sawMidstreamEnvelopeEcho = false;
         // Ordering proof for tool-suspended checkpoints: true only when the newest captured
         // checkpoint bytes arrived AFTER the turn emitted a client tool call, i.e. upstream
         // serialized its suspended-on-tool-call state. Only that snapshot can safely resume
@@ -250,6 +254,7 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
             coveredMessageCount,
             prefixDigest: cursorCoveredPrefixDigest(_parsed, coveredMessageCount),
             systemDigest: cursorInstructionDigest(_parsed),
+            toolSuspended: toolSuspendedCommit,
           });
           if (!checkpointRef) return;
           if (previousRef && previousRef !== checkpointRef) invalidateCursorCheckpoint(previousRef);
@@ -259,7 +264,8 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
               ...(_parsed._providerContinuation?.cursor ?? {}),
               conversationId: activeRequest.conversationId,
               // A tool-suspended checkpoint is only usable by the immediate trailing-toolResult
-              // continuation; the request-builder guard keys on checkpointUsable=false for that.
+              // continuation; the request-builder guard keys on this checkpointUsable=false and
+              // the snapshot's persisted toolSuspended flag for that.
               checkpointUsable: !toolSuspendedCommit,
               checkpointRef,
             },
@@ -390,7 +396,9 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
                 }
                 if (event.type !== "heartbeat") emittedOutput = true;
                 if (event.type === "done") {
-                  for (const finding of midstreamObserver?.findings() ?? []) {
+                  const midstreamFindings = midstreamObserver?.findings() ?? [];
+                  if (midstreamFindings.length > 0) sawMidstreamEnvelopeEcho = true;
+                  for (const finding of midstreamFindings) {
                     debugProviderDiagnostic("cursor", "midstream-envelope-echo", {
                       wireModel: activeRequest.modelId,
                       conversationHash: activeRequest.conversationId.slice(0, 16),
@@ -564,6 +572,41 @@ export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAda
         } else if (!sawIncompleteToolCall && completedNormally && incompleteToolRemintScopeKey) {
           clearCursorIncompleteToolRemint(incompleteToolRemintScopeKey);
         }
+        // A mid-stream envelope echo has ALREADY reached the client — the prefix sniffer only
+        // watches the first bytes of a turn, and grok-4.6 writes a real sentence before pasting
+        // the envelope. It cannot be quarantined, so the recovery is the same as the
+        // incomplete-tool case: leave this turn alone and rotate the next turn's id, otherwise
+        // the stored echo is replayed and primes the model to echo again.
+        //
+        // Its own budget, not the incomplete-tool one: echoing is cheap and repeatable while an
+        // incomplete client-tool stream is rare and structural, so a shared counter would let a
+        // persistently echoing model spend the allowance the other recovery needs. Skipped when
+        // the incomplete-tool arm already reminted this turn — one rotation is enough.
+        const envelopeEchoRemintScopeKey =
+          _parsed._cursorIsolateConversation !== true
+          && request.contextUsageStoreCheckpoints !== false
+            ? cursorEnvelopeEchoRemintScopeKey(
+                cursorClientThreadOwner(_parsed),
+                _parsed._cursorIdentityScope,
+              )
+            : null;
+        if (sawMidstreamEnvelopeEcho && !sawIncompleteToolCall && envelopeEchoRemintScopeKey) {
+          if (recordCursorEnvelopeEchoRemint(envelopeEchoRemintScopeKey)) {
+            if (inheritedCheckpointRef) invalidateCursorCheckpoint(inheritedCheckpointRef);
+            debugProviderDiagnostic("cursor", "midstream-envelope-echo-remint", {
+              wireModel: request.modelId,
+              conversationHash: request.conversationId.slice(0, 16),
+            });
+            remintConversationId(request.conversationId);
+          } else {
+            debugProviderDiagnostic("cursor", "midstream-envelope-echo-remint-exhausted", {
+              wireModel: request.modelId,
+              conversationHash: request.conversationId.slice(0, 16),
+            });
+          }
+        } else if (!sawMidstreamEnvelopeEcho && completedNormally && envelopeEchoRemintScopeKey) {
+          clearCursorEnvelopeEchoRemint(envelopeEchoRemintScopeKey);
+        }
         if (
           request.checkpointInvalidationReason
           && request.checkpointInvalidationReason !== "missing_ref"

package/src/adapters/devin/cloud-direct/chat.ts

@@ -35,7 +35,7 @@ import {
 } from './wire.js';
 import { buildMetadata } from './metadata.js';
 import { getCachedUserJwt } from './auth.js';
-import { getCachedCatalog, ModelNotAvailableError } from './catalog.js';
+import { getCachedCatalog, ModelNotAvailableError, type CacheEntry } from './catalog.js';
 import { anySignal, cancelBodyOnAbort } from '../../../lib/abort.js';
 import { resolveDevinApiBaseUrl } from '../../../oauth/devin/api-base.js';
 
@@ -1046,8 +1046,17 @@ export interface CloudChatRequest {
   completionOpts?: BuildArgs['completionOpts'];
   /** Override request_type (default = 5, CASCADE). */
   requestType?: number;
+  /**
+   * Catalog the caller already resolved this turn. An explicit `null`
+   * records a failed lookup: the pre-flight below then skips its own fetch
+   * instead of paying a second catalog timeout on the same turn. Omit the
+   * field to let the pre-flight perform its own cached lookup.
+   */
+  catalog?: CacheEntry | null;
   /** Abort signal — closes the fetch stream. */
   signal?: AbortSignal;
+  /** Executor for the inference POST only; catalog and JWT RPCs retain their own transport. */
+  executor?: typeof globalThis.fetch;
 }
 
 export class CloudChatError extends Error {
@@ -1140,7 +1149,9 @@ export async function* streamChatEvents(req: CloudChatRequest): AsyncGenerator<C
   // error and the trailer-error path below enriches the message in-place.
   // Treat an empty catalog (schema drift / unexpected response) as "no catalog"
   // so chat passes through instead of failing every request.
-  const catalog = await getCachedCatalog(req.apiKey, host, req.signal).catch(() => null);
+  const catalog = req.catalog !== undefined
+    ? req.catalog
+    : await getCachedCatalog(req.apiKey, host, req.signal).catch(() => null);
   if (catalog && catalog.byUid.size > 0) {
     const entry = catalog.byUid.get(req.modelUid);
     if (!entry) {
@@ -1207,7 +1218,7 @@ export async function* streamChatEvents(req: CloudChatRequest): AsyncGenerator<C
 
   let resp: Response;
   try {
-    resp = await fetch(`${host}/exa.api_server_pb.ApiServerService/GetChatMessage`, {
+    resp = await (req.executor ?? globalThis.fetch)(`${host}/exa.api_server_pb.ApiServerService/GetChatMessage`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/connect+proto',

package/src/adapters/devin/cloud-direct/index.ts

@@ -49,6 +49,13 @@ export {
   type ToolDef,
 } from './chat.js';
 
+export {
+  streamChatEventsWithResetRetry,
+  STATED_RESET_MAX_REPLAYS,
+  STATED_RESET_MAX_WAIT_MS,
+  type StatedResetRetryOptions,
+} from './stated-reset-retry.js';
+
 export {
   mintUserJwt,
   getCachedUserJwt,