@minhspark/codex-mcp-bridge 1.21.5 → 1.21.6

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-mcp-bridge",
-  "version": "1.21.5",
+  "version": "1.21.6",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh"

package/CHANGELOG.md

@@ -4,6 +4,19 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [SemVer](ht
 
 ## [Unreleased]
 
+## [1.21.6] - 2026-10-12
+
+### Fixed
+
+- Continue observing a delivered Desktop task through bounded `read_thread` snapshots when the `wait_threads` renderer stops returning results after relay recovery. Preserve the original deadline, access checks, and authoritative reply validation without resending the prompt (#122, #123).
+- Keep native requests capped at 128 KiB while accepting responses up to 8 MiB on both relay hops. Reject larger responses explicitly, trim internal metadata reads, omit tool output from default transcript reads, and bound the serialized MCP read result (#123).
+- Identify failed rollout validation checks and record byte offsets in bounded diagnostics without exposing reply contents. Validation requirements remain unchanged; unsupported rollout sequences still fail closed pending concrete evidence (#123).
+
+### Upgrade notes
+
+- Update both the bridge and native relay companion. Default Desktop transcript reads omit tool outputs and cap each included item at 2,000 characters; use an exact `turnId` for authoritative assistant response inspection.
+- Native frames above 8 MiB, rollout files above 16 MiB, and authoritative replies above 1 MiB remain explicit limits.
+
 ## [1.21.5] - 2026-10-11
 
 ### Fixed

package/README.md

@@ -4,7 +4,7 @@
 
 <h1 align="center">codex-mcp-bridge</h1>
 
-Local Desktop handoff guides: [daily workflow and directory verification](docs/daily-handoffs.md), [new-machine setup and permissions](docs/new-machine-setup.md), and [project onboarding](docs/project-onboarding.md).
+Local Desktop handoff guides: [daily workflow and directory verification](docs/daily-handoffs.md), [Windows setup](docs/new-windows-setup.md), [macOS setup](docs/new-macos-setup.md), and [project onboarding](docs/project-onboarding.md).
 
 [![npm](https://img.shields.io/npm/v/@minhspark/codex-mcp-bridge?logo=npm&color=CB3837)](https://www.npmjs.com/package/@minhspark/codex-mcp-bridge)
 [![npm downloads](https://raw.githubusercontent.com/buidangminh23/codex-mcp-bridge/analytics/stats-npm-downloads.svg)](https://www.npmjs.com/package/@minhspark/codex-mcp-bridge)

package/docs/daily-handoffs.md

@@ -3,7 +3,7 @@
 Install the messaging MCP entries first. Local Card Bridge Desktop is optional
 and is needed only for automatic task-card startup and its settings UI. Neither
 component uploads an entire local project. For initial installation see
-[new-machine setup](new-machine-setup.md); for grants see
+[Windows setup](new-windows-setup.md) or [macOS setup](new-macos-setup.md); for grants see
 [project onboarding](project-onboarding.md).
 
 Workspace trust, project authorization and host tool permission are separate.

package/docs/new-macos-setup.md

@@ -0,0 +1,67 @@
+# New macOS setup
+
+Connect Claude Desktop's **Code tab** and Codex Desktop through local MCP
+processes and sockets. Both apps still authenticate with their providers and
+use hosted models; local bridge transport does not mean offline inference.
+
+## Local installation: required steps
+
+The [ChatGPT plugin setup](../README.md#chatgpt-plugin) uses a hosted Sites
+connector. For a local Desktop installation, use the following path instead:
+
+1. Install and sign in to Codex Desktop and Claude Desktop under the same macOS
+   user. Have Node.js 22+, npm, the Codex CLI, and the Claude Code CLI available.
+   Save the intended local project in Codex Desktop and open it in Claude's
+   Code tab.
+2. Follow [macOS installation](../README.md#macos-terminal) to install the bridge
+   and register the native relay and reverse bridge. Keep bootstrap enabled on
+   the first relay install. Do not use the ChatGPT plugin pairing instructions,
+   run `codex-sites-connector`, or configure a hosted endpoint.
+3. Follow [Claude Code registration](../README.md#register-claude-code) for the
+   forward bridge. Use the intended project directories for
+   `CODEX_BRIDGE_ALLOWED_ROOTS`, rather than the example's entire home directory;
+   macOS separates multiple roots with `:`. Preserve an existing entry's
+   custom settings.
+4. Add [native relay pipe forwarding](../README.md#native-relay-pipe-forwarding)
+   to the existing relay entry. Forward `CODEX_APP_TOOLS_PIPE_PATH` by name,
+   not its temporary value. The relay needs the trusted app-bundled Node runtime
+   selected by the installer; do not substitute an arbitrary Homebrew/nvm Node.
+5. Reconnect the affected MCP servers in the actual Desktop Code conversations,
+   or restart the affected app after active work finishes. Complete
+   [installation verification](../README.md#verify-the-installation), including
+   a message and reply in each direction.
+
+There are three registrations: `codex-bridge` in Claude Code, and
+`claude-bridge` plus `codex-native-relay` in Codex Desktop. The relay is transport
+plumbing, not a third agent. Ordinary Claude chat has a separate MCP registry;
+adding a server there does not register it in the Code tab.
+
+## Restricted local configuration
+
+Local transport does not require Full Access. Keep the intended sandbox,
+approval reviewer, and project restrictions. Before running installers, check
+for `$CODEX_HOME/bridge-full-access.enabled` (normally
+`~/.codex/bridge-full-access.enabled`): a saved opt-in makes them enable Full
+Access even without `--full-access`. Resolve that existing opt-in deliberately
+before installing; `CODEX_BRIDGE_ENFORCE_FULL_ACCESS=0` does not disable it.
+
+For a restricted Codex setup, these are top-level configuration settings,
+before any `[table]`:
+
+```toml
+approval_policy = "on-request"
+approvals_reviewer = "auto_review"
+sandbox_mode = "workspace-write"
+```
+
+Verify the active Desktop task uses the intended restrictions; defaults alone
+are not evidence of its effective permissions. To suppress optional reporting,
+set `CODEX_BRIDGE_TELEMETRY=0` in all three MCP registrations' environments;
+see [telemetry controls](../README.md#optional-active-install-statistics).
+
+For workspace trust, shared project grants, and optional messaging automation,
+use [project onboarding](project-onboarding.md). For target selection,
+permission mismatches, and uncertain deliveries, use
+[daily Desktop handoffs](daily-handoffs.md) and the
+[technical reference](https://github.com/buidangminh23/codex-mcp-bridge/blob/main/REFERENCE.md). Tool discovery or a connected socket
+alone does not establish a completed exchange.

package/docs/{new-machine-setup.md → new-windows-setup.md}

@@ -1,4 +1,4 @@
-# New-machine setup and initial permissions
+# New Windows setup and initial permissions
 
 This is a Windows local Desktop source-install guide, not evidence of testing
 on a second machine. Use a pinned source revision containing these scripts;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhspark/codex-mcp-bridge",
-  "version": "1.21.5",
+  "version": "1.21.6",
   "description": "Two-way MCP bridge between Claude and Codex: prompts into a live Codex thread, messages into a running Claude Code session.",
   "keywords": [
     "mcp",
@@ -48,7 +48,8 @@
     "LICENSE",
     "CHANGELOG.md",
     "docs/daily-handoffs.md",
-    "docs/new-machine-setup.md",
+    "docs/new-windows-setup.md",
+    "docs/new-macos-setup.md",
     "docs/project-onboarding.md",
     "docs/desktop-handoff-design.md"
   ],

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "codex-mcp-bridge",
-  "version": "1.21.5",
+  "version": "1.21.6",
   "description": "Connect ChatGPT to your own Codex Desktop projects and conversations.",
   "author": {
     "name": "Bui Dang Minh",

package/scripts/install-native-relay.mjs

@@ -23,7 +23,7 @@ import { enableCodexFullAccess, fullAccessEnabled } from "../src/codex-full-acce
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.21.6";
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const entry = path.join(root, "src", "mcp-supervisor.mjs");
 const entryArgs = ["native-relay-companion.mjs"];

package/src/claude-bridge.mjs

@@ -29,7 +29,7 @@ import { registerProjectOnboardingTools } from "./project-onboarding-tools.mjs";
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.21.6";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const FORWARD_MIN_INTERVAL_MS = 5000;
 const FORWARD_MAX_PER_SESSION = 50;

package/src/codex-native-response.mjs

@@ -21,6 +21,15 @@ function unavailable(reason) {
   return { status: "unavailable", reason: reason?.message ?? String(reason) };
 }
 
+function validationError(message, check, fields = {}) {
+  const details = Object.entries({ check, ...fields }).map(([key, value]) => `${key}=${value}`).join("; ");
+  return new Error(`${message} [${details}]`);
+}
+
+function recordOffsets(entries) {
+  return entries.slice(0, 3).map(({ start }) => start).join(",") || "none";
+}
+
 function configuredSessions(env) {
   const configuredHome = env.CODEX_HOME || path.join(env.HOME || env.USERPROFILE || os.homedir(), ".codex");
   if (!path.isAbsolute(configuredHome)) throw new Error("The configured Codex home must be absolute");
@@ -165,23 +174,29 @@ function recordBelongsToTurn(entry, threadId, turnId) {
   const metadata = object(payload.internal_chat_message_metadata_passthrough) ? payload.internal_chat_message_metadata_passthrough : {};
   const turnFields = [payload.turn_id, payload.root_turn_id, metadata.turn_id, metadata.root_turn_id].filter((value) => value !== undefined);
   if (!turnFields.includes(turnId)) return false;
-  if (turnFields.some((value) => value !== turnId)) throw new Error("The native response contains contradictory turn identity");
+  if (turnFields.some((value) => value !== turnId)) throw validationError("The native response contains contradictory turn identity", "turn_identity", { recordByte: entry.start });
   const threadFields = [payload.thread_id, metadata.thread_id].filter((value) => value !== undefined);
-  if (threadFields.some((value) => value !== threadId)) throw new Error("The native response contains contradictory task identity");
+  if (threadFields.some((value) => value !== threadId)) throw validationError("The native response contains contradictory task identity", "task_identity", { recordByte: entry.start });
   return true;
 }
 
-function responseItemText(payload) {
-  if (!Array.isArray(payload.content) || payload.content.some((item) => !object(item) || item.type !== "output_text" || typeof item.text !== "string")) {
-    throw new Error("The native final response contains unsupported content");
+function responseItemText(entry) {
+  const { payload } = entry.record;
+  const invalidPart = Array.isArray(payload.content)
+    ? payload.content.findIndex((item) => !object(item) || item.type !== "output_text" || typeof item.text !== "string") : "not_array";
+  if (invalidPart !== -1) {
+    throw validationError("The native final response contains unsupported content", "response_content", { responseItemByte: entry.start, contentPart: invalidPart });
   }
   return payload.content.map((item) => item.text).join("");
 }
 
-function completedEventText(item) {
+function completedEventText(entry) {
+  const item = entry.record.payload.item;
   if (!object(item) || item.type !== "AgentMessage" || item.phase !== "final_answer") return null;
-  if (!Array.isArray(item.content) || item.content.some((part) => !object(part) || part.type !== "Text" || typeof part.text !== "string")) {
-    throw new Error("The native completed assistant item contains unsupported content");
+  const invalidPart = Array.isArray(item.content)
+    ? item.content.findIndex((part) => !object(part) || part.type !== "Text" || typeof part.text !== "string") : "not_array";
+  if (invalidPart !== -1) {
+    throw validationError("The native completed assistant item contains unsupported content", "completed_content", { completedEventByte: entry.start, contentPart: invalidPart });
   }
   return item.content.map((part) => part.text).join("");
 }
@@ -193,10 +208,16 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch }
   const completions = turns.filter(({ record }) => record.type === "event_msg" && COMPLETED.has(record.payload.type));
   const failures = turns.filter(({ record }) => record.type === "event_msg" &&
     (FAILED.has(record.payload.type) || record.payload.error || ["failed", "aborted", "interrupted"].includes(record.payload.status)));
-  if (failures.length || starts.length !== 1 || contexts.length !== 1 || completions.length !== 1 ||
-      canonicalDirectory(contexts[0].record.payload.cwd, "The observed turn workspace") !== cwd ||
-      starts[0].start >= contexts[0].start || contexts[0].start >= completions[0].start) {
-    throw new Error("The native turn lifecycle is missing, ambiguous, failed, or out of order");
+  const lifecycleError = (check, fields) => validationError("The native turn lifecycle is missing, ambiguous, failed, or out of order", check, fields);
+  if (failures.length) throw lifecycleError("lifecycle_failure", { count: failures.length, eventBytes: recordOffsets(failures) });
+  for (const [kind, entries] of [["start", starts], ["context", contexts], ["completion", completions]]) {
+    if (entries.length !== 1) throw lifecycleError(`lifecycle_${kind}_count`, { count: entries.length, recordBytes: recordOffsets(entries) });
+  }
+  if (canonicalDirectory(contexts[0].record.payload.cwd, "The observed turn workspace") !== cwd) {
+    throw lifecycleError("lifecycle_workspace", { contextByte: contexts[0].start });
+  }
+  if (starts[0].start >= contexts[0].start || contexts[0].start >= completions[0].start) {
+    throw lifecycleError("lifecycle_order", { startByte: starts[0].start, contextByte: contexts[0].start, completionByte: completions[0].start });
   }
 
   let dispatch = null;
@@ -205,47 +226,66 @@ function inspectTurnRecords(records, threadId, turnId, cwd, { requireDispatch }
       record.payload.namespace === "codex_app" && record.payload.name === (requireDispatch.operation ?? "send_message_to_thread"));
     if (dispatches.length !== 1 || !requireDispatch.outputs.includes(dispatches[0].record.payload.output) ||
         contexts[0].start >= dispatches[0].start || dispatches[0].start >= completions[0].start) {
-      throw new Error("The newly observed turn is not correlated to the exact native dispatch");
+      throw validationError("The newly observed turn is not correlated to the exact native dispatch", "dispatch_correlation", {
+        count: dispatches.length, dispatchBytes: recordOffsets(dispatches), contextByte: contexts[0].start, completionByte: completions[0].start,
+      });
     }
     dispatch = dispatches[0];
   }
 
   const allAssistantEntries = turns.filter(({ record }) => record.type === "response_item" && record.payload.type === "message" && record.payload.role === "assistant");
   const finalEntries = allAssistantEntries.filter(({ record }) => record.payload.phase === "final_answer");
-  if (!finalEntries.length && allAssistantEntries.length) throw new Error("The completed native turn has assistant items but no final assistant reply");
+  if (!finalEntries.length && allAssistantEntries.length) throw validationError("The completed native turn has assistant items but no final assistant reply", "missing_final_phase", {
+    count: allAssistantEntries.length, responseItemBytes: recordOffsets(allAssistantEntries),
+  });
   const assistantItems = [];
-  const ids = new Set();
+  const ids = new Map();
   for (const entry of finalEntries) {
     const { payload } = entry.record;
     if (typeof payload.id !== "string" || !payload.id.trim() || ids.has(payload.id) ||
         entry.start <= (dispatch?.start ?? contexts[0].start) || entry.start >= completions[0].start) {
-      throw new Error("The native final response item identity is missing, duplicated, or out of order");
+      const check = typeof payload.id !== "string" || !payload.id.trim() ? "response_item_id_missing" : ids.has(payload.id) ? "response_item_id_duplicate" : "response_item_order";
+      throw validationError("The native final response item identity is missing, duplicated, or out of order", check, {
+        responseItemByte: entry.start, previousItemByte: ids.get(payload.id)?.start ?? "none",
+        afterByte: dispatch?.start ?? contexts[0].start, completionByte: completions[0].start,
+      });
     }
-    ids.add(payload.id);
-    const text = responseItemText(payload);
-    if (!text.trim()) throw new Error("The native final response item is empty");
+    ids.set(payload.id, entry);
+    const text = responseItemText(entry);
+    if (!text.trim()) throw validationError("The native final response item is empty", "response_item_empty", { responseItemByte: entry.start });
     assistantItems.push({ id: payload.id, text });
   }
 
   const eventItems = new Map();
-  for (const { record, start } of turns) {
+  for (const entry of turns) {
+    const { record, start } = entry;
     if (record.type !== "event_msg" || record.payload.type !== "item_completed") continue;
     const eventItem = record.payload.item;
     if (ids.has(eventItem?.id) && (eventItem.type !== "AgentMessage" || eventItem.phase !== "final_answer")) {
-      throw new Error("The native assistant item representations conflict in type or phase");
+      throw validationError("The native assistant item representations conflict in type or phase", "assistant_representation_type_phase", {
+        responseItemByte: ids.get(eventItem.id).start, completedEventByte: start,
+      });
     }
-    const text = completedEventText(record.payload.item);
+    const text = completedEventText(entry);
     if (text === null) continue;
     const id = record.payload.item.id;
     if (typeof id !== "string" || !id.trim() || eventItems.has(id) || start <= contexts[0].start || start >= completions[0].start) {
-      throw new Error("The native completed assistant item identity is missing, duplicated, or out of order");
+      const check = typeof id !== "string" || !id.trim() ? "completed_item_id_missing" : eventItems.has(id) ? "completed_item_id_duplicate" : "completed_item_order";
+      throw validationError("The native completed assistant item identity is missing, duplicated, or out of order", check, {
+        completedEventByte: start, previousEventByte: eventItems.get(id)?.start ?? "none",
+        contextByte: contexts[0].start, completionByte: completions[0].start,
+      });
     }
-    eventItems.set(id, text);
+    eventItems.set(id, { text, start });
   }
   for (const item of assistantItems) {
-    if (eventItems.has(item.id) && eventItems.get(item.id) !== item.text) throw new Error("The native assistant item representations conflict");
+    if (eventItems.has(item.id) && eventItems.get(item.id).text !== item.text) throw validationError("The native assistant item representations conflict", "assistant_representation_text", {
+      responseItemByte: ids.get(item.id).start, completedEventByte: eventItems.get(item.id).start,
+    });
+  }
+  for (const [id, event] of eventItems) {
+    if (!ids.has(id)) throw validationError("The native completed assistant item has no matching authoritative response item", "authoritative_response_missing", { completedEventByte: event.start });
   }
-  if ([...eventItems.keys()].some((id) => !ids.has(id))) throw new Error("The native completed assistant item has no matching authoritative response item");
 
   const text = assistantItems.map((item) => item.text).join("\n\n");
   if (Buffer.byteLength(text, "utf8") > MAX_REPLY_BYTES) throw new Error("The native final response exceeds the bounded reply limit");

package/src/index.mjs

@@ -39,7 +39,7 @@ import { PROJECT_SETUP_TOOLS, registerProjectOnboardingTools } from "./project-o
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.21.6";
 void import("./telemetry.mjs").then(({ startUsageReporting }) => startUsageReporting({ version: VERSION })).catch(() => {});
 const log = (msg) => process.stderr.write(`[codex-mcp-bridge] ${msg}\n`);
 
@@ -875,8 +875,12 @@ registerTool(
           return textResult(JSON.stringify(response, null, 2), response.status === "unavailable");
         }
         await desktopTasks.inspect(threadId, undefined, { deadline });
-        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10) }, { deadline });
-        return textResult(JSON.stringify(response, null, 2));
+        const response = await desktopTasks.request("read_thread", { threadId, hostId: "local", turnLimit: Math.min(limit ?? 10, 10), includeOutputs: false, maxOutputCharsPerItem: 2000 }, { deadline });
+        const result = textResult(JSON.stringify(response, null, 2));
+        if (Buffer.byteLength(JSON.stringify(result), "utf8") > 8 * 1024 * 1024) {
+          return textResult("DESKTOP_READ_RESPONSE_TOO_LARGE: The formatted Desktop read exceeds 8 MiB. Read fewer turns with limit: 1 or select a specific turnId.", true);
+        }
+        return result;
       }
       await assertThreadAccess(threadId);
       const res = await client.call("thread/read", { threadId, includeTurns: true });

package/src/native-relay-companion.mjs

@@ -9,6 +9,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 import {
   MAX_FRAME_BYTES,
+  MAX_RESPONSE_FRAME_BYTES,
   NATIVE_DISPATCH_METHOD,
   NativeToolsClient,
   NativeRelayError,
@@ -36,7 +37,7 @@ import { NativeCreationReceipts, creationIdValid } from "./native-creation-recei
 
 exitForVersionRequest(import.meta.url);
 
-const VERSION = "1.21.5";
+const VERSION = "1.21.6";
 const log = (msg) => process.stderr.write(`[native-relay] ${msg}\n`);
 
 function errorResponse(code, message, sent) {
@@ -102,7 +103,7 @@ export function createNativeScopeAuthorizer({ dispatchDesktop, env = process.env
   };
   const threadFor = async (executorThreadId, threadId, accountContext, projects) => {
     if (typeof threadId !== "string" || !threadId) fail("Operation has no target task");
-    const result = await call(executorThreadId, "read_thread", { threadId, hostId: "local", turnLimit: 1 }, accountContext);
+    const result = await call(executorThreadId, "read_thread", { threadId, hostId: "local", turnLimit: 1, includeOutputs: false, maxOutputCharsPerItem: 1 }, accountContext);
     return validateThread(result?.thread, threadId, projects);
   };
   const targetIds = (operation, args, targetThreadId) => {
@@ -613,7 +614,12 @@ export class RelaySocketServer {
 
   #reply(socket, response) {
     if (socket.destroyed) return;
-    socket.end(`${JSON.stringify(response)}\n`);
+    const frame = `${JSON.stringify(response)}\n`;
+    if (Buffer.byteLength(frame, "utf8") > MAX_RESPONSE_FRAME_BYTES) {
+      socket.end(`${JSON.stringify(errorResponse("RELAY_RESPONSE_TOO_LARGE", `The native relay response exceeds ${MAX_RESPONSE_FRAME_BYTES} bytes; reduce the requested turns or outputs`))}\n`);
+      return;
+    }
+    socket.end(frame);
   }
 
   stop() {

package/src/native-relay.mjs

@@ -39,13 +39,8 @@ export const NATIVE_DISPATCH_METHOD = "tools/call";
 export const RELAY_PROTOCOL_VERSION = 1;
 export const ACCOUNT_RELAY_PROTOCOL_VERSION = 2;
 
-/**
- * A relay frame carries one chat message, so a megabyte-scale line is either a
- * bug or something trying to make the companion buffer without limit. The cap
- * is applied on both halves: the client refuses to send an oversized message,
- * and the companion refuses to accumulate one.
- */
 export const MAX_FRAME_BYTES = 128 * 1024;
+export const MAX_RESPONSE_FRAME_BYTES = 8 * 1024 * 1024;
 
 const DEFAULT_TIMEOUT_MS = 30000;
 const RELAY_SOCKET_NAME = "native-relay.sock";
@@ -617,7 +612,11 @@ export class NativeToolsClient {
         buffer = Buffer.concat([buffer, chunk]);
         while (buffer.length >= 4) {
           const length = buffer.readUInt32LE(0);
-          if (!length || length > MAX_FRAME_BYTES) {
+          if (length > MAX_RESPONSE_FRAME_BYTES) {
+            fail(new NativeRelayError(`Codex Desktop native response exceeds ${MAX_RESPONSE_FRAME_BYTES} bytes; reduce the requested turns or outputs`, "NATIVE_RESPONSE_TOO_LARGE"));
+            return;
+          }
+          if (!length) {
             fail(new NativeRelayError("Invalid Codex Desktop native frame length", "NATIVE_BAD_RESPONSE"));
             return;
           }
@@ -885,16 +884,19 @@ export class NativeDesktopRelay {
         })();
       });
       socket.on("data", (chunk) => {
-        buffer = Buffer.concat([buffer, chunk]);
-        if (buffer.length > MAX_FRAME_BYTES) {
+        if (settled) return;
+        const newline = chunk.indexOf(10);
+        const frameChunk = newline < 0 ? chunk : chunk.subarray(0, newline + 1);
+        if (buffer.length + frameChunk.length > MAX_RESPONSE_FRAME_BYTES) {
           finish(
             reject,
-            new NativeRelayError("The Codex Desktop relay answered with an oversized frame", "RELAY_BAD_RESPONSE", {
+            new NativeRelayError(`The Codex Desktop relay response exceeds ${MAX_RESPONSE_FRAME_BYTES} bytes; reduce the requested turns or outputs`, "RELAY_RESPONSE_TOO_LARGE", {
               reachedCompanion: true,
             }),
           );
           return;
         }
+        buffer = Buffer.concat([buffer, frameChunk]);
         const index = buffer.indexOf(10);
         if (index < 0) return;
         try {

package/src/rollout-segments.mjs

@@ -37,7 +37,7 @@ export function findRolloutSegments(sessions, threadId) {
       }
     }
   }
-  if (!matches.length) throw new Error("No rollout matches the calling Codex task");
+  if (!matches.length) throw new Error(`No rollout matches the calling Codex task [check=rollout_discovery; directoriesScanned=${directories}; entriesScanned=${entries}; layout=sessions/YYYY/MM/DD/rollout-*-taskId[_continuationId].jsonl]`);
   return matches.sort();
 }
 

package/src/thread-delivery.mjs

@@ -27,6 +27,13 @@ export const NATIVE_BACKEND = "codex-desktop-native";
 export const APP_SERVER_BACKEND = "app-server";
 export const DESKTOP_TOOL_BUDGET_MS = 40000;
 const RELEASE_STATUSES = new Set(["completed", "interrupted", "failed"]);
+const METADATA_READ_OPTIONS = { includeOutputs: false, maxOutputCharsPerItem: 1 };
+
+function unavailableWaitRenderer(error) {
+  const cause = error.cause ?? error;
+  return cause.code === "NATIVE_DISPATCH_FAILED" &&
+    /^(Codex app tool request failed\.?|The app tool call ended before producing a result\.?)$/.test(cause.message);
+}
 
 function sameAccountContext(expected, current) {
   return Boolean(expected && current && ["claude", "codex"].every((provider) =>
@@ -194,7 +201,7 @@ export class DesktopTaskDelivery {
     let response;
     try {
       this.security.assertThread(receipt.threadId, cwd);
-      response = await this.request("read_thread", { threadId: receipt.threadId, hostId: "local", turnLimit: 1 }, { deadline });
+      response = await this.request("read_thread", { threadId: receipt.threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline });
     } catch (err) {
       throw new Error(`Existing Desktop task ${receipt.threadId} could not be verified. No prompt was resent and no duplicate task was created: ${err.message}`, { cause: err });
     }
@@ -364,7 +371,7 @@ export class DesktopTaskDelivery {
   }
 
   async #inspectMetadata(threadId, cwd, { deadline } = {}) {
-    const envelope = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1 }, { deadline, includeRelayContext: true });
+    const envelope = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline, includeRelayContext: true });
     const response = envelope.result;
     const thread = response?.thread;
     if (thread?.id !== threadId || thread.hostId !== "local" || !thread.cwd) throw new Error("Desktop did not confirm the task's local workspace.");
@@ -471,23 +478,41 @@ export class DesktopTaskDelivery {
     const startedAt = this.now();
     let cursor;
     let turnId = null;
+    let readSnapshots = false;
+    const readSnapshot = async () => {
+      const result = await this.request("read_thread", { threadId, hostId: "local", turnLimit: 1, ...METADATA_READ_OPTIONS }, { deadline: startedAt + timeoutMs });
+      const thread = result?.thread;
+      if (thread?.id !== threadId || thread.hostId !== "local" || !thread.cwd) throw new Error("Desktop did not confirm the observed task's local workspace.");
+      this.security.assertCwd(thread.cwd);
+      this.security.assertThread(threadId, thread.cwd);
+      this.senderProjectScope(thread.cwd);
+      if (responseObservation?.expectedCwd && realpathSync.native(thread.cwd) !== responseObservation.expectedCwd) throw new Error("The selected native task workspace changed during observation");
+      return { polls: [{ thread, latestTurn: result.turns?.[0] ?? null }] };
+    };
     const expired = () => ({ threadId, turnId, status: "timeout", text: "", responseStatus: "unavailable", assistantItems: [], replySha256: null, activity: [], errors: [], durationMs: this.now() - startedAt });
     for (;;) {
       if (this.now() - startedAt >= timeoutMs) return expired();
       let response;
       try {
-        response = await this.request("wait_threads", {
+        response = readSnapshots ? await readSnapshot() : await this.request("wait_threads", {
           targets: [{ threadId, hostId: "local", ...(cursor ? { afterCursor: cursor } : {}) }], timeoutMs: 0,
         }, { deadline: startedAt + timeoutMs });
       } catch (err) {
         if (this.now() - startedAt >= timeoutMs) return expired();
-        throw err;
+        if (readSnapshots || !unavailableWaitRenderer(err)) throw err;
+        readSnapshots = true;
+        try {
+          response = await readSnapshot();
+        } catch (readError) {
+          if (this.now() - startedAt >= timeoutMs) return expired();
+          throw readError;
+        }
       }
       const poll = response?.polls?.find((item) => item.thread?.id === threadId && item.thread?.hostId === "local");
       if (response?.errors?.length || !poll) throw new Error(`Could not observe task ${threadId}; it may still be running. Read it before retrying: ${JSON.stringify(response)}`);
       cursor = poll.cursor;
       const turn = poll.latestTurn;
-      const threadStatus = poll.thread.status?.type;
+      const threadStatus = typeof poll.thread.status === "string" ? poll.thread.status : poll.thread.status?.type;
       if (["systemError", "waitingOnApproval", "waitingOnUserInput"].includes(threadStatus)) {
         return { threadId, turnId: turn?.id !== previousTurnId ? turn?.id ?? null : null, status: threadStatus, text: "", activity: [], errors: [], durationMs: this.now() - startedAt };
       }