@makerbi/remodex 1.5.2 → 1.5.4

package/bin/remodex.js

@@ -37,11 +37,29 @@ const defaultDeps = {
 };
 
 if (require.main === module) {
-  void main();
+  void runCli();
 }
 
 // ─── ENTRY POINT ─────────────────────────────────────────────
 
+// Runs the CLI process and turns expected configuration failures into readable terminal output.
+async function runCli({
+  mainImpl = main,
+  consoleImpl = console,
+  exitImpl = process.exit,
+} = {}) {
+  try {
+    await mainImpl();
+  } catch (error) {
+    const rawMessage = error && typeof error.message === "string"
+      ? error.message.trim()
+      : String(error || "Command failed");
+    const message = rawMessage || "Command failed";
+    consoleImpl.error(message.startsWith("[remodex]") ? message : `[remodex] ${message}`);
+    exitImpl(1);
+  }
+}
+
 async function main({
   argv = process.argv,
   platform = process.platform,
@@ -351,4 +369,5 @@ module.exports = {
   isVersionCommand,
   main,
   parseCliArgs,
+  runCli,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@makerbi/remodex",
-  "version": "1.5.2",
+  "version": "1.5.4",
   "description": "Local bridge between Codex and the Remodex mobile app. Run `remodex up` to start.",
   "repository": {
     "type": "git",
@@ -9,8 +9,8 @@
   },
   "main": "src/index.js",
   "bin": {
-    "remodex": "./bin/remodex.js",
-    "remodex-jsonl-diagnose": "./bin/remodex-jsonl-diagnose.js"
+    "remodex": "bin/remodex.js",
+    "remodex-jsonl-diagnose": "bin/remodex-jsonl-diagnose.js"
   },
   "files": [
     "bin/",

package/src/bridge-status.js

@@ -0,0 +1,121 @@
+// FILE: bridge-status.js
+// Purpose: Owns bridge status publishing and stale-relay heartbeat downgrades.
+// Layer: CLI service helper
+// Exports: createBridgeStatusPublisher, buildHeartbeatBridgeStatus, hasRelayConnectionGoneStale
+// Depends on: timers
+
+const BRIDGE_STATUS_HEARTBEAT_INTERVAL_MS = 5_000;
+// Keep the watchdog above the relay heartbeat cadence so quiet healthy sockets survive idle gaps.
+const RELAY_WATCHDOG_STALE_AFTER_MS = 70_000;
+const STALE_RELAY_STATUS_MESSAGE = "Relay heartbeat stalled; reconnect pending.";
+
+// Wraps daemon status publication so bridge.js does not own heartbeat bookkeeping.
+function createBridgeStatusPublisher({
+  onBridgeStatus = null,
+  getCodexLaunchState = () => undefined,
+  heartbeatIntervalMs = BRIDGE_STATUS_HEARTBEAT_INTERVAL_MS,
+  now = () => Date.now(),
+} = {}) {
+  let lastPublishedBridgeStatus = null;
+  let heartbeatTimer = null;
+
+  function publish(status) {
+    const nextStatus = {
+      ...status,
+      codexLaunchState: getCodexLaunchState(),
+    };
+    lastPublishedBridgeStatus = nextStatus;
+    onBridgeStatus?.(nextStatus);
+  }
+
+  function startHeartbeat({
+    shouldPublish = () => true,
+    getLastRelayActivityAt = () => 0,
+  } = {}) {
+    if (heartbeatTimer) {
+      return;
+    }
+
+    heartbeatTimer = setInterval(() => {
+      if (!lastPublishedBridgeStatus || !shouldPublish()) {
+        return;
+      }
+
+      onBridgeStatus?.(buildHeartbeatBridgeStatus(
+        lastPublishedBridgeStatus,
+        getLastRelayActivityAt(),
+        { now: now() }
+      ));
+    }, heartbeatIntervalMs);
+    heartbeatTimer.unref?.();
+  }
+
+  function stopHeartbeat() {
+    if (!heartbeatTimer) {
+      return;
+    }
+
+    clearInterval(heartbeatTimer);
+    heartbeatTimer = null;
+  }
+
+  return {
+    latest() {
+      return lastPublishedBridgeStatus;
+    },
+    publish,
+    startHeartbeat,
+    stopHeartbeat,
+  };
+}
+
+// Treats silent relay sockets as stale so the daemon can self-heal after sleep/wake.
+function hasRelayConnectionGoneStale(
+  lastActivityAt,
+  {
+    now = Date.now(),
+    staleAfterMs = RELAY_WATCHDOG_STALE_AFTER_MS,
+  } = {}
+) {
+  return Number.isFinite(lastActivityAt)
+    && Number.isFinite(now)
+    && now - lastActivityAt >= staleAfterMs;
+}
+
+// Keeps persisted daemon status honest by downgrading stale "connected" snapshots.
+function buildHeartbeatBridgeStatus(
+  status,
+  lastActivityAt,
+  {
+    now = Date.now(),
+    staleAfterMs = RELAY_WATCHDOG_STALE_AFTER_MS,
+    staleMessage = STALE_RELAY_STATUS_MESSAGE,
+  } = {}
+) {
+  if (!status || typeof status !== "object") {
+    return status;
+  }
+
+  if (status.connectionStatus !== "connected") {
+    return status;
+  }
+
+  if (!hasRelayConnectionGoneStale(lastActivityAt, { now, staleAfterMs })) {
+    return status;
+  }
+
+  return {
+    ...status,
+    connectionStatus: "disconnected",
+    lastError: staleMessage,
+  };
+}
+
+module.exports = {
+  BRIDGE_STATUS_HEARTBEAT_INTERVAL_MS,
+  RELAY_WATCHDOG_STALE_AFTER_MS,
+  STALE_RELAY_STATUS_MESSAGE,
+  buildHeartbeatBridgeStatus,
+  createBridgeStatusPublisher,
+  hasRelayConnectionGoneStale,
+};

package/src/bridge.js

@@ -2,7 +2,7 @@
 // Purpose: Runs Codex locally, bridges relay traffic, and coordinates desktop refreshes for Codex.app.
 // Layer: CLI service
 // Exports: startBridge
-// Depends on: ws, crypto, os, ./codex-home, ./qr, ./codex-desktop-refresher, ./codex-transport, ./rollout-watch, ./voice-handler, ./ios-app-compatibility
+// Depends on: ws, crypto, os, ./bridge-status, ./codex-desktop-refresher, ./codex-transport, ./rollout-watch, ./voice-handler
 
 const WebSocket = require("ws");
 const { randomBytes, randomUUID } = require("crypto");
@@ -14,6 +14,11 @@ const {
   CodexDesktopRefresher,
   readBridgeConfig,
 } = require("./codex-desktop-refresher");
+const {
+  buildHeartbeatBridgeStatus,
+  createBridgeStatusPublisher,
+  hasRelayConnectionGoneStale,
+} = require("./bridge-status");
 const { createCodexTransport } = require("./codex-transport");
 const {
   createThreadRolloutActivityWatcher,
@@ -62,10 +67,6 @@ const {
 
 const execFileAsync = promisify(execFile);
 const RELAY_WATCHDOG_PING_INTERVAL_MS = 10_000;
-// Keep the watchdog above the relay heartbeat cadence so quiet healthy sockets survive idle gaps.
-const RELAY_WATCHDOG_STALE_AFTER_MS = 70_000;
-const BRIDGE_STATUS_HEARTBEAT_INTERVAL_MS = 5_000;
-const STALE_RELAY_STATUS_MESSAGE = "Relay heartbeat stalled; reconnect pending.";
 const CLOSE_CODE_INVALID_RELAY_REQUEST = 4000;
 const CLOSE_CODE_REPLACED_BY_NEW_MAC = 4001;
 const CLOSE_CODE_MAC_UNAUTHORIZED = 4005;
@@ -77,6 +78,9 @@ const RELAY_TURNS_LIST_TARGET_BUDGET_MS = 5_500;
 const RELAY_TURNS_LIST_BUDGET_RESERVE_MS = 1_000;
 const RELAY_TURNS_LIST_MAX_INITIAL_LIMIT = 5;
 const RELAY_TURNS_LIST_SAFE_RETRY_LIMIT = 5;
+const MODELS_WITHOUT_REASONING_SUMMARY = new Set([
+  "gpt-5.3-codex-spark",
+]);
 const RELAY_TURNS_LIST_RESULT_KEYS = ["data", "items", "turns"];
 const RELAY_TURNS_LIST_PAGINATION_RESULT_KEYS = [
   "nextCursor",
@@ -176,9 +180,7 @@ function startBridge({
   let reconnectAttempt = 0;
   let reconnectTimer = null;
   let relayWatchdogTimer = null;
-  let statusHeartbeatTimer = null;
   let lastRelayActivityAt = 0;
-  let lastPublishedBridgeStatus = null;
   let lastConnectionStatus = null;
   let lastConnectionError = "";
   let codexLaunchState = config.codexEndpoint ? "connected" : "starting";
@@ -254,7 +256,14 @@ function startBridge({
     sendCodexRequest,
     logPrefix: "[remodex]",
   });
-  startBridgeStatusHeartbeat();
+  const bridgeStatusPublisher = createBridgeStatusPublisher({
+    onBridgeStatus,
+    getCodexLaunchState: () => codexLaunchState,
+  });
+  bridgeStatusPublisher.startHeartbeat({
+    shouldPublish: () => !isShuttingDown,
+    getLastRelayActivityAt: () => lastRelayActivityAt,
+  });
   publishBridgeStatus({
     state: "starting",
     connectionStatus: "starting",
@@ -275,7 +284,7 @@ function startBridge({
     } else {
       console.error("[remodex] Failed to start `codex app-server`.");
       console.error(`[remodex] Launch command: ${codex.describe()}`);
-      console.error("[remodex] Make sure the Codex CLI is installed and that the launcher works on this OS.");
+      console.error("[remodex] Make sure the Codex CLI is installed, authenticated, and launchable on this OS.");
     }
     console.error(error.message);
     process.exit(1);
@@ -283,6 +292,7 @@ function startBridge({
   // Marks the local Codex runtime as launchable before relay/network recovery updates.
   codex.onStarted(() => {
     codexLaunchState = "connected";
+    const lastPublishedBridgeStatus = bridgeStatusPublisher.latest();
     if (!lastPublishedBridgeStatus) {
       return;
     }
@@ -299,31 +309,6 @@ function startBridge({
     reconnectTimer = null;
   }
 
-  // Periodically rewrites the latest bridge snapshot so CLI status does not stay frozen.
-  function startBridgeStatusHeartbeat() {
-    if (statusHeartbeatTimer) {
-      return;
-    }
-
-    statusHeartbeatTimer = setInterval(() => {
-      if (!lastPublishedBridgeStatus || isShuttingDown) {
-        return;
-      }
-
-      onBridgeStatus?.(buildHeartbeatBridgeStatus(lastPublishedBridgeStatus, lastRelayActivityAt));
-    }, BRIDGE_STATUS_HEARTBEAT_INTERVAL_MS);
-    statusHeartbeatTimer.unref?.();
-  }
-
-  function clearBridgeStatusHeartbeat() {
-    if (!statusHeartbeatTimer) {
-      return;
-    }
-
-    clearInterval(statusHeartbeatTimer);
-    statusHeartbeatTimer = null;
-  }
-
   // Tracks relay liveness locally so sleep/wake zombie sockets can be force-reconnected.
   function markRelayActivity() {
     lastRelayActivityAt = Date.now();
@@ -402,7 +387,8 @@ function startBridge({
         bridgeWakeAssertion.stop();
         clearReconnectTimer();
         clearRelayWatchdog();
-        clearBridgeStatusHeartbeat();
+        bridgeStatusPublisher.stopHeartbeat();
+        closeExtraRelayChannels();
       }, {
         exitCode: closeCode === CLOSE_CODE_MAC_UNAUTHORIZED ? 1 : 0,
       });
@@ -582,8 +568,10 @@ function startBridge({
 
       const nextSocket = new WebSocket(extraRelaySessionUrl, {
         headers: {
+          "User-Agent": buildRelayUserAgentHeader(),
           "x-role": "mac",
           "x-notification-secret": notificationSecret,
+          ...buildRelayAccessTokenHeaders(config),
           ...buildMacRegistrationHeaders(deviceState, extraPairingSession),
         },
       });
@@ -675,16 +663,23 @@ function startBridge({
   });
 
   codex.onClose(() => {
+    const wasShuttingDown = isShuttingDown;
     clearRelayWatchdog();
-    clearBridgeStatusHeartbeat();
-    const lastError = lastConnectionError || "";
+    bridgeStatusPublisher.stopHeartbeat();
+    const lastError = wasShuttingDown
+      ? ""
+      : (lastConnectionError || "Codex transport closed unexpectedly.");
     logConnectionStatus("disconnected", lastError);
     publishBridgeStatus({
-      state: "stopped",
+      state: wasShuttingDown ? "stopped" : "error",
       connectionStatus: "disconnected",
       pid: process.pid,
       lastError,
     });
+    if (!wasShuttingDown) {
+      console.error(`[remodex] ${lastError}`);
+      process.exitCode = 1;
+    }
     isShuttingDown = true;
     bridgeWakeAssertion.stop();
     clearReconnectTimer();
@@ -706,7 +701,7 @@ function startBridge({
     bridgeWakeAssertion.stop();
     clearReconnectTimer();
     clearRelayWatchdog();
-    clearBridgeStatusHeartbeat();
+    bridgeStatusPublisher.stopHeartbeat();
     closeExtraRelayChannels();
   }));
   process.on("SIGTERM", () => shutdown(codex, () => socket, () => {
@@ -714,7 +709,7 @@ function startBridge({
     bridgeWakeAssertion.stop();
     clearReconnectTimer();
     clearRelayWatchdog();
-    clearBridgeStatusHeartbeat();
+    bridgeStatusPublisher.stopHeartbeat();
     closeExtraRelayChannels();
   }));
 
@@ -767,9 +762,10 @@ function startBridge({
     if (handleBridgeManagedThreadTurnsListRequest(rawMessage, sendResponse)) {
       return;
     }
-    const codexMessage = prepareCodexForwardMessage(rawMessage, relayChannel);
+    const codexRequest = disableUnsupportedReasoningSummaryForTurnStart(rawMessage);
+    const codexMessage = prepareCodexForwardMessage(codexRequest, relayChannel);
     rememberForwardedRequestMethod(codexMessage);
-    rememberThreadFromMessage("phone", rawMessage);
+    rememberThreadFromMessage("phone", codexMessage);
     mirrorUserMessageToPeerDevices(rawMessage, relayChannel);
     codex.send(codexMessage);
   }
@@ -1578,12 +1574,7 @@ function startBridge({
   }
 
   function publishBridgeStatus(status) {
-    const nextStatus = {
-      ...status,
-      codexLaunchState,
-    };
-    lastPublishedBridgeStatus = nextStatus;
-    onBridgeStatus?.(nextStatus);
+    bridgeStatusPublisher.publish(status);
   }
 
   // Refreshes the relay's trusted-mac index after the QR bootstrap locks in a phone identity.
@@ -1825,6 +1816,41 @@ function buildRelayCloseStatusError(closeCode, closeReason = "") {
     : `Relay closed the connection (${closeCode}).`;
 }
 
+// Forces app-server summary generation off for models whose Responses API calls
+// reject reasoning.summary, while leaving the phone-facing runtime choice intact.
+function disableUnsupportedReasoningSummaryForTurnStart(rawMessage) {
+  const parsed = parseBridgeJSON(rawMessage);
+  if (!parsed || parsed.method !== "turn/start") {
+    return rawMessage;
+  }
+
+  const params = parsed.params && typeof parsed.params === "object" && !Array.isArray(parsed.params)
+    ? parsed.params
+    : null;
+  if (!params || params.summary === "none") {
+    return rawMessage;
+  }
+
+  const model = readTurnStartModel(params);
+  if (!MODELS_WITHOUT_REASONING_SUMMARY.has(model)) {
+    return rawMessage;
+  }
+
+  return JSON.stringify({
+    ...parsed,
+    params: {
+      ...params,
+      summary: "none",
+    },
+  });
+}
+
+function readTurnStartModel(params) {
+  return normalizeNonEmptyString(params?.model).toLowerCase()
+    || normalizeNonEmptyString(params?.collaborationMode?.settings?.model).toLowerCase()
+    || normalizeNonEmptyString(params?.collaboration_mode?.settings?.model).toLowerCase();
+}
+
 function extractBridgeMessageContext(rawMessage) {
   let parsed = null;
   try {
@@ -3167,48 +3193,6 @@ function truncateRelayTextTail(value, maxChars) {
   return `…\n${tail}`;
 }
 
-// Treats silent relay sockets as stale so the daemon can self-heal after sleep/wake.
-function hasRelayConnectionGoneStale(
-  lastActivityAt,
-  {
-    now = Date.now(),
-    staleAfterMs = RELAY_WATCHDOG_STALE_AFTER_MS,
-  } = {}
-) {
-  return Number.isFinite(lastActivityAt)
-    && Number.isFinite(now)
-    && now - lastActivityAt >= staleAfterMs;
-}
-
-// Keeps persisted daemon status honest by downgrading stale "connected" snapshots.
-function buildHeartbeatBridgeStatus(
-  status,
-  lastActivityAt,
-  {
-    now = Date.now(),
-    staleAfterMs = RELAY_WATCHDOG_STALE_AFTER_MS,
-    staleMessage = STALE_RELAY_STATUS_MESSAGE,
-  } = {}
-) {
-  if (!status || typeof status !== "object") {
-    return status;
-  }
-
-  if (status.connectionStatus !== "connected") {
-    return status;
-  }
-
-  if (!hasRelayConnectionGoneStale(lastActivityAt, { now, staleAfterMs })) {
-    return status;
-  }
-
-  return {
-    ...status,
-    connectionStatus: "disconnected",
-    lastError: staleMessage,
-  };
-}
-
 function persistBridgePreferences(
   {
     keepMacAwakeEnabled,
@@ -3230,6 +3214,7 @@ module.exports = {
   buildRelayAccessTokenHeaders,
   buildRelayUserAgentHeader,
   createMacOSBridgeWakeAssertion,
+  disableUnsupportedReasoningSummaryForTurnStart,
   fetchAdaptiveThreadTurnsListForRelay,
   hasRelayConnectionGoneStale,
   isTerminalRelayCloseCode,

package/src/codex-transport.js

@@ -254,7 +254,32 @@ function shutdownCodexProcess(codex) {
 function createCodexCloseError({ code, signal, stderrBuffer, launchDescription }) {
   const details = stderrBuffer.trim();
   const reason = details || `Process exited with code ${code}${signal ? ` (signal: ${signal})` : ""}.`;
-  return new Error(`Codex launcher ${launchDescription} failed: ${reason}`);
+  return new Error(formatCodexLaunchFailure({
+    launchDescription,
+    reason,
+  }));
+}
+
+// Turns common Codex auth/config failures into recovery guidance without handling secrets in Remodex.
+function formatCodexLaunchFailure({ launchDescription, reason }) {
+  const message = `Codex launcher ${launchDescription} failed: ${reason}`;
+  const missingEnvVar = extractMissingEnvironmentVariable(reason);
+  if (!missingEnvVar) {
+    return message;
+  }
+
+  const guidance = [
+    `Codex is asking for ${missingEnvVar}, which usually means your Codex config forces API-key auth or a custom provider env var.`,
+    "Remodex does not store or forward OpenAI API keys.",
+    "Recommended fix: run `codex login` on this Mac, then restart Remodex.",
+    "If you intentionally use API-key auth, run `printenv OPENAI_API_KEY | codex login --with-api-key` or make that env var available to the Remodex daemon yourself.",
+  ];
+  return `${message}\n${guidance.join("\n")}`;
+}
+
+function extractMissingEnvironmentVariable(reason) {
+  const match = String(reason || "").match(/Missing environment variable:\s*`?([A-Za-z_][A-Za-z0-9_]*)`?/i);
+  return match ? match[1] : "";
 }
 
 function appendOutputBuffer(buffer, chunk) {
@@ -350,4 +375,6 @@ function createListenerBag() {
 module.exports = {
   createCodexLaunchPlans,
   createCodexTransport,
+  extractMissingEnvironmentVariable,
+  formatCodexLaunchFailure,
 };

package/src/desktop-ipc-action-follower.js

@@ -16,12 +16,14 @@ const ACTION_METHODS = new Set([
   "item/commandExecution/requestApproval",
   "item/fileChange/requestApproval",
   "item/fileRead/requestApproval",
+  "item/permissions/requestApproval",
   "item/tool/requestUserInput",
 ]);
 const REPLY_METHOD_BY_ACTION_METHOD = new Map([
   ["item/commandExecution/requestApproval", "thread-follower-command-approval-decision"],
   ["item/fileChange/requestApproval", "thread-follower-file-approval-decision"],
   ["item/fileRead/requestApproval", "thread-follower-file-approval-decision"],
+  ["item/permissions/requestApproval", "thread-follower-file-approval-decision"],
   ["item/tool/requestUserInput", "thread-follower-submit-user-input"],
 ]);
 const METHOD_VERSION_BY_NAME = new Map([
@@ -483,7 +485,7 @@ function desktopFollowerPayloadForResponse(route, responseMessage) {
     };
   }
 
-  const decision = readString(responseMessage?.result?.decision);
+  const decision = desktopApprovalDecisionForResponse(route.method, responseMessage?.result);
   if (!APPROVAL_DECISIONS.has(decision)) {
     return null;
   }
@@ -498,6 +500,47 @@ function desktopFollowerPayloadForResponse(route, responseMessage) {
   };
 }
 
+function desktopApprovalDecisionForResponse(method, result) {
+  const explicitDecision = readString(result?.decision);
+  if (explicitDecision) {
+    return explicitDecision;
+  }
+
+  if (method !== "item/permissions/requestApproval") {
+    return "";
+  }
+
+  // Permission approvals use a grant payload on app-server, while Desktop IPC
+  // currently exposes only decision-style follower replies.
+  return hasGrantedPermission(result?.permissions) ? "accept" : "decline";
+}
+
+function hasGrantedPermission(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  if (Object.keys(value).length === 0) {
+    return false;
+  }
+
+  return Object.values(value).some((entry) => {
+    if (entry == null) {
+      return false;
+    }
+    if (typeof entry === "boolean") {
+      return entry;
+    }
+    if (Array.isArray(entry)) {
+      return entry.length > 0;
+    }
+    if (typeof entry === "object") {
+      return Object.keys(entry).length > 0;
+    }
+    return true;
+  });
+}
+
 function projectPendingDesktopActions(threadId, conversationState) {
   const requests = Array.isArray(conversationState?.requests) ? conversationState.requests : [];
   return requests

package/src/macos-launch-agent.js

@@ -255,8 +255,7 @@ function printMacOSBridgeServiceStatus(options = {}) {
 
 function printMacOSBridgePairingQr({ pairingSession = null, env = process.env, fsImpl = fs } = {}) {
   const nextPairingSession = pairingSession || readPairingSession({ env, fsImpl });
-  const pairingPayload = nextPairingSession?.pairingPayload;
-  if (!pairingPayload) {
+  if (!nextPairingSession?.pairingPayload) {
     throw new Error("The macOS bridge service did not publish a pairing payload yet.");
   }
 
@@ -351,7 +350,11 @@ async function waitForFreshPairingSession({
   while (Date.now() <= deadline) {
     const pairingSession = readPairingSession({ env, fsImpl });
     const createdAt = Date.parse(pairingSession?.createdAt || "");
-    if (pairingSession?.pairingPayload && Number.isFinite(createdAt) && createdAt >= startedAt) {
+    if (
+      pairingSession?.pairingPayload
+      && Number.isFinite(createdAt)
+      && createdAt >= startedAt
+    ) {
       return pairingSession;
     }
     await sleep(intervalMs);

package/src/secure-transport.js

@@ -364,7 +364,10 @@ function createBridgeSecureTransport({
         pendingHandshake.phoneIdentityPublicKey
       );
       if (previousTrustedPhonePublicKey !== pendingHandshake.phoneIdentityPublicKey) {
-        onTrustedPhoneUpdate?.(currentDeviceState);
+        onTrustedPhoneUpdate?.(currentDeviceState, {
+          phoneDeviceId: pendingHandshake.phoneDeviceId,
+          phoneIdentityPublicKey: pendingHandshake.phoneIdentityPublicKey,
+        });
       }
     }
     if (pendingHandshake.handshakeMode === HANDSHAKE_MODE_QR_BOOTSTRAP) {

package/src/session-jsonl-history.js

@@ -36,6 +36,7 @@ function parseSessionJsonlTurns(content, { threadId = "" } = {}) {
   const turnsById = new Map();
   let activeTurnId = "";
   let sessionThreadId = normalizeString(threadId);
+  const skippedCallIds = new Set();
 
   const lines = String(content || "").split(/\r?\n/);
   for (let index = 0; index < lines.length; index += 1) {
@@ -110,6 +111,9 @@ function parseSessionJsonlTurns(content, { threadId = "" } = {}) {
       if (!payload) {
         continue;
       }
+      if (shouldSkipResponseItemForHistory(payload, skippedCallIds)) {
+        continue;
+      }
       const turn = ensureTurn(
         turns,
         turnsById,
@@ -169,6 +173,67 @@ function normalizeResponseItemForHistory(payload, lineNumber) {
   return item;
 }
 
+// Filters desktop transcript internals that are stored as response items but are not chat history.
+function shouldSkipResponseItemForHistory(payload, skippedCallIds) {
+  const type = normalizeHistoryItemType(payload.type);
+  const callId = normalizeString(payload.call_id) || normalizeString(payload.callId);
+
+  if (type === "tool_call_output" && callId && skippedCallIds.has(callId)) {
+    return true;
+  }
+
+  if (type === "tool_call" && isSubagentOrchestrationCall(payload)) {
+    if (callId) {
+      skippedCallIds.add(callId);
+    }
+    return true;
+  }
+
+  if (type !== "message") {
+    return false;
+  }
+
+  const role = normalizeString(payload.role).toLowerCase();
+  if (role && role !== "user" && role !== "assistant") {
+    return true;
+  }
+
+  if (role === "user" && isSubagentNotificationMessage(payload)) {
+    return true;
+  }
+
+  return false;
+}
+
+function isSubagentOrchestrationCall(payload) {
+  const name = normalizeString(payload.name).toLowerCase();
+  return name === "spawn_agent"
+    || name === "wait_agent"
+    || name === "send_input"
+    || name === "resume_agent"
+    || name === "close_agent";
+}
+
+function isSubagentNotificationMessage(payload) {
+  const text = responseItemMessageText(payload).trimStart();
+  return text.startsWith("<subagent_notification>");
+}
+
+function responseItemMessageText(payload) {
+  const directText = normalizeString(payload.text) || normalizeString(payload.message);
+  if (directText) {
+    return directText;
+  }
+
+  const content = Array.isArray(payload.content) ? payload.content : [];
+  return content
+    .map((item) => objectValue(item))
+    .filter(Boolean)
+    .map((item) => normalizeString(item.text) || normalizeString(objectValue(item.data)?.text))
+    .filter(Boolean)
+    .join("\n");
+}
+
 function normalizeHistoryItemType(rawType) {
   const normalized = normalizeString(rawType).toLowerCase().replace(/[\s_-]+/g, "");
   if (!normalized) {