@bitkyc08/opencodex 2.7.41 → 2.7.42

package/src/adapters/openai-responses.ts

@@ -219,6 +219,28 @@ function stripDisabledReasoningSummaries(
   };
 }
 
+/**
+ * Normalize only the delivery enum Codex already emitted. Do not inject a field into callers that
+ * did not request summaries, and leave every unconfigured provider/model byte-for-byte unchanged.
+ */
+function normalizeConfiguredReasoningSummaryDelivery(
+  body: unknown,
+  provider: OcxProviderConfig,
+  modelId: string,
+): unknown {
+  const delivery = modelRecordValue(provider.modelReasoningSummaryDelivery, modelId);
+  if (delivery === undefined || !isPlainObject(body) || !isPlainObject(body.stream_options)) return body;
+  if (!Object.hasOwn(body.stream_options, "reasoning_summary_delivery")) return body;
+  if (body.stream_options.reasoning_summary_delivery === delivery) return body;
+  return {
+    ...body,
+    stream_options: {
+      ...body.stream_options,
+      reasoning_summary_delivery: delivery,
+    },
+  };
+}
+
 /**
  * Comprehensive Spark compatibility layer. codex-rs emits five tool types (function,
  * namespace, tool_search, web_search, custom) plus extensions (defer_loading,
@@ -496,26 +518,81 @@ const HOSTED_TOOL_NAME_CONFLICTS: ReadonlyArray<{ hostedType: string; namePrefix
  * HOSTED_TOOL_NAME_CONFLICTS). Only applies on the API-key platform path: the ChatGPT backend
  * ("forward" mode) accepts the pair, and stripping there would disable native imagegen. No-op
  * (returns the original reference) when nothing matches.
+ *
+ * Codex Desktop Responses Lite requests do not always use top-level `body.tools`; they may place
+ * the same declarations in `body.input[]` entries of type `additional_tools`. The platform validates
+ * these containers as one tool namespace, so conflict detection must span all of them. The function
+ * uses copy-on-write semantics and preserves the original request reference when nothing is removed.
  */
 function stripConflictingHostedTools(body: unknown): unknown {
-  if (!isPlainObject(body) || !Array.isArray(body.tools)) return body;
-  const allTools = body.tools;
+  if (!isPlainObject(body)) return body;
+
+  // Collect every tool container in the request. Traditional HTTP/SSE requests use top-level
+  // `tools`, while Responses Lite may carry the same declarations in `additional_tools` entries.
+  const toolGroups: unknown[][] = [];
+  if (Array.isArray(body.tools)) toolGroups.push(body.tools);
+  if (Array.isArray(body.input)) {
+    for (const item of body.input) {
+      if (isPlainObject(item) && item.type === "additional_tools" && Array.isArray(item.tools)) {
+        toolGroups.push(item.tools);
+      }
+    }
+  }
+  if (toolGroups.length === 0) return body;
 
-  const conflicting = HOSTED_TOOL_NAME_CONFLICTS.filter(c =>
-    allTools.some(t => {
+  // Detect conflicts across containers because the client namespace and the hosted tool may be
+  // declared in different groups while still sharing one platform-validated namespace.
+  const conflicting = HOSTED_TOOL_NAME_CONFLICTS.filter(c => toolGroups.some(group =>
+    group.some(t => {
       if (!isPlainObject(t) || typeof t.name !== "string") return false;
       if (t.type === "namespace") return t.name === c.namePrefix;
       return t.name === c.namePrefix || t.name.startsWith(`${c.namePrefix}.`);
     }),
-  );
+  ));
   if (conflicting.length === 0) return body;
 
-  const tools = allTools.filter(t => {
-    const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
-    if (!type) return true;
-    return !conflicting.some(c => c.hostedType === type);
-  });
-  return tools.length === allTools.length ? body : { ...body, tools };
+  // Allocate a replacement only when a hosted tool is removed. Preserve malformed entries,
+  // unrelated tools, and future tool types so this compatibility rule remains narrowly scoped.
+  const stripGroup = (tools: unknown[]): unknown[] => {
+    const filtered = tools.filter(t => {
+      const type = isPlainObject(t) && typeof t.type === "string" ? t.type : undefined;
+      if (!type) return true;
+      return !conflicting.some(c => c.hostedType === type);
+    });
+    return filtered.length === tools.length ? tools : filtered;
+  };
+
+  let changed = false;
+  let tools = body.tools;
+  if (Array.isArray(body.tools)) {
+    tools = stripGroup(body.tools);
+    changed ||= tools !== body.tools;
+  }
+
+  let input = body.input;
+  if (Array.isArray(body.input)) {
+    let nestedChanged = false;
+    const mappedInput = body.input.map(item => {
+      if (!isPlainObject(item) || item.type !== "additional_tools" || !Array.isArray(item.tools)) {
+        return item;
+      }
+      const nestedTools = stripGroup(item.tools);
+      if (nestedTools === item.tools) return item;
+      nestedChanged = true;
+      return { ...item, tools: nestedTools };
+    });
+    if (nestedChanged) {
+      input = mappedInput;
+      changed = true;
+    }
+  }
+
+  if (!changed) return body;
+  return {
+    ...body,
+    ...(Array.isArray(body.tools) ? { tools } : {}),
+    ...(Array.isArray(body.input) ? { input } : {}),
+  };
 }
 
 /**
@@ -674,12 +751,13 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
       if (parsed._compactionRequest === true && !isCanonicalOpenAiForwardProvider(provider)) {
         outBody = buildRoutedCompactionBody(outBody);
       }
+      const sanitizedBody = stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody)))))));
       return {
         url,
         method: "POST",
         headers,
         body: JSON.stringify(stripDisabledReasoningSummaries(
-          stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody))))))),
+          normalizeConfiguredReasoningSummaryDelivery(sanitizedBody, provider, parsed.modelId),
           provider,
           parsed.modelId,
         )),

package/src/bridge.ts

@@ -133,8 +133,18 @@ export function bridgeToResponsesSSE(
      * from this callback instead of re-parsing the bridged SSE.
      */
     onUsage?: (usage: OcxUsage | undefined) => void;
+    /**
+     * Test seam for the wire/stall beat loop. Production omits this and uses the
+     * global timers; injecting here must not change scheduling semantics.
+     */
+    timers?: {
+      setInterval: (handler: () => void, ms: number) => unknown;
+      clearInterval: (id: unknown) => void;
+    };
   },
 ): ReadableStream<Uint8Array> {
+  const setBeatInterval = options?.timers?.setInterval ?? ((handler: () => void, ms: number) => setInterval(handler, ms));
+  const clearBeatInterval = options?.timers?.clearInterval ?? ((id: unknown) => clearInterval(id as ReturnType<typeof setInterval>));
   // Freeform/custom tools (apply_patch) carry their body in `input`; the model is given a
   // function with `{input:string}`, so unwrap it here when relaying back as a custom_tool_call.
   const freeformInput = (args: string): string => {
@@ -189,17 +199,19 @@ export function bridgeToResponsesSSE(
   };
   // RC3 keep-alive: Codex's idle timer is timeout(idle_timeout, stream.next()) over an
   // eventsource_stream; ANY received event re-arms it, while an unknown type is ignored
-  // (responses.rs `_ => Ok(None)`). We emit a real, parser-ignored `response.heartbeat` only during
-  // upstream silence so a stalled routed provider never trips "idle timeout waiting for SSE".
-  let activity = false;
-  let beat: ReturnType<typeof setInterval> | undefined;
+  // (responses.rs `_ => Ok(None)`). Emit a parser-ignored `response.heartbeat` whenever the
+  // *wire* has been silent, even if invisible adapter heartbeats are still flowing (web-search
+  // buffering + raw-byte progress). Upstream activity only resets the stall watchdog.
+  let upstreamActivity = false;
+  let wireActivity = false;
+  let beat: unknown;
   let controller: ReadableStreamDefaultController<Uint8Array>;
   let emittedFrames = 0;
   let gated = false;
   let stepping = false;
   const emit = (name: string, data: Record<string, unknown>) => {
         if (closed) return;
-        activity = true;
+        wireActivity = true;
         try {
           controller.enqueue(encoder.encode(sseEvent(name, { type: name, sequence_number: seq++, ...data })));
           emittedFrames++;
@@ -302,8 +314,12 @@ export function bridgeToResponsesSSE(
         return anns;
       };
 
-      const closeCurrentMessage = () => {
+      const closeCurrentMessage = (inferredPhase?: OcxMessagePhase) => {
         if (!currentMsg) return;
+        // Chat Completions has no message-phase field. Keep its live item provisional, then
+        // classify it only when the next adapter event proves whether this text led into more
+        // work or completed the turn. Explicit adapter phases always outrank this inference.
+        const phase = currentMsg.phase ?? inferredPhase;
         // Bind any pending web-search citations to this assistant message (then they clear).
         const annotations = takeWebAnnotations();
         // Finalize the text part (Responses protocol). Without these .done events Codex never
@@ -318,7 +334,7 @@ export function bridgeToResponsesSSE(
         const item = {
           type: "message", id: currentMsg.itemId, status: "completed", role: "assistant",
           content: [{ type: "output_text", text: currentMsg.text, annotations }],
-          ...(currentMsg.phase ? { phase: currentMsg.phase } : {}),
+          ...(phase ? { phase } : {}),
         };
         emit("response.output_item.done", { output_index: currentMsg.outputIndex, item });
         finishedItems.push(item as OutputItem);
@@ -478,7 +494,9 @@ export function bridgeToResponsesSSE(
           if (next.done) { upstreamDone = true; break; }
           const event = next.value;
           let terminalEvent = false;
-          activity = true;
+          // Invisible adapter heartbeats (and buffered web-search progress) count as upstream
+          // liveness only — they must not suppress wire keepalives that re-arm Codex idle timers.
+          upstreamActivity = true;
           stallTicks = 0;
           reportFirstOutput(event);
           // Compaction turns emit ONLY the synthetic compaction item + response.completed. The
@@ -494,7 +512,7 @@ export function bridgeToResponsesSSE(
             case "assistant_boundary": {
               // A guarded continuation starts a fresh assistant output item while keeping the
               // intermediate, suspicious text in the same Responses turn.
-              if (currentMsg) closeCurrentMessage();
+              if (currentMsg) closeCurrentMessage("commentary");
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
@@ -507,7 +525,11 @@ export function bridgeToResponsesSSE(
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
-              if (currentMsg && currentMsg.phase !== event.phase) closeCurrentMessage();
+              // Only flush on an explicit phase change. A later delta that omits `phase` must
+              // keep appending to the current message rather than wiping the earlier phase.
+              if (currentMsg && event.phase !== undefined && currentMsg.phase !== event.phase) {
+                closeCurrentMessage("commentary");
+              }
               if (!currentMsg) {
                 const itemId = `msg_${uuid()}`;
                 const item = {
@@ -531,7 +553,7 @@ export function bridgeToResponsesSSE(
             }
             case "thinking_delta": {
               if (options?.hideThinkingSummary) { hiddenThinkingText += event.thinking; break; }
-              if (currentMsg) closeCurrentMessage();
+              if (currentMsg) closeCurrentMessage("commentary");
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
               if (currentToolCall) closeCurrentToolCall();
@@ -566,7 +588,7 @@ export function bridgeToResponsesSSE(
             }
             case "reasoning_raw_delta": {
               if (options?.hideThinkingSummary) { hiddenRawReasoningText += event.text; break; }
-              if (currentMsg) closeCurrentMessage();
+              if (currentMsg) closeCurrentMessage("commentary");
               if (currentReasoning) closeCurrentReasoning();
               if (currentToolCall) closeCurrentToolCall();
               if (!currentRawReasoning) {
@@ -583,7 +605,7 @@ export function bridgeToResponsesSSE(
               break;
             }
             case "tool_call_start": {
-              if (currentMsg) closeCurrentMessage();
+              if (currentMsg) closeCurrentMessage("commentary");
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
@@ -638,7 +660,7 @@ export function bridgeToResponsesSSE(
               // Open the native search cell so Codex shows the "Searching the web" spinner WHILE the
               // sidecar runs. Close any other open item first, allocate this item's output index, and
               // hold it open until the matching `web_search_call_end` (or a terminal close).
-              if (currentMsg) closeCurrentMessage();
+              if (currentMsg) closeCurrentMessage("commentary");
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
@@ -675,7 +697,7 @@ export function bridgeToResponsesSSE(
               break;
             }
             case "done": {
-              if (currentMsg) closeCurrentMessage();
+              if (currentMsg) closeCurrentMessage(event.stopReason ? undefined : "final_answer");
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
@@ -801,7 +823,7 @@ export function bridgeToResponsesSSE(
         stepping = false;
         return;
       }
-      if (beat) { clearInterval(beat); beat = undefined; }
+      if (beat !== undefined) { clearBeatInterval(beat); beat = undefined; }
 
       if (!terminated) {
         // The adapter generator ended without an explicit done/error event. Mark as incomplete
@@ -840,10 +862,12 @@ export function bridgeToResponsesSSE(
         // The default ReadableStream strategy has HWM=1. Once one event's frames fill that
         // queue, pull stepping pauses; no custom FIFO or queuing strategy is layered on top.
         gated = true;
-        beat = setInterval(() => {
+        beat = setBeatInterval(() => {
           if (closed || gated) return;
-          if (activity) { activity = false; stallTicks = 0; return; }
-          if (++stallTicks >= maxStallTicks) {
+          if (upstreamActivity) {
+            upstreamActivity = false;
+            stallTicks = 0;
+          } else if (++stallTicks >= maxStallTicks) {
             if (currentMsg) closeCurrentMessage();
             if (currentReasoning) closeCurrentReasoning();
             if (currentRawReasoning) closeCurrentRawReasoning();
@@ -861,12 +885,17 @@ export function bridgeToResponsesSSE(
             terminated = true;
             returnIterator();
             emitDone();
-            if (beat) clearInterval(beat);
+            if (beat !== undefined) clearBeatInterval(beat);
             beat = undefined;
             try { controller.close(); } catch { /* already closed */ }
             closed = true;
             return;
           }
+          // Wire silence is independent of upstream adapter heartbeats.
+          if (wireActivity) {
+            wireActivity = false;
+            return;
+          }
           try {
             controller.enqueue(heartbeatFrame);
             emittedFrames++;
@@ -887,14 +916,14 @@ export function bridgeToResponsesSSE(
     cancel() {
       // Client (Codex) disconnected. Stop emitting and let the caller abort the upstream fetch so a
       // cancelled turn does not leak the upstream stream or keep draining tokens (RC2).
-      clientCancelled = true;
-      closed = true;
-      if (beat) clearInterval(beat);
-      onCancel?.();
-      returnIterator();
-    },
-  });
-}
+        clientCancelled = true;
+        closed = true;
+        if (beat !== undefined) clearBeatInterval(beat);
+        onCancel?.();
+        returnIterator();
+      },
+    });
+  }
 
 export function buildResponseJSON(
   events: AdapterEvent[],
@@ -918,6 +947,7 @@ export function buildResponseJSON(
   let incompleteEvent: Extract<AdapterEvent, { type: "incomplete" }> | undefined;
   let endTurn: boolean | undefined;
   let stopReason: string | undefined;
+  let cleanDone = false;
   let compactionText = "";
 
   let currentText = "";
@@ -941,8 +971,9 @@ export function buildResponseJSON(
     try { const o = JSON.parse(args); return o && typeof o === "object" ? o : {}; } catch { return {}; }
   };
 
-  const flushText = () => {
+  const flushText = (inferredPhase?: OcxMessagePhase) => {
     if (!currentText) return;
+    const phase = currentTextPhase ?? inferredPhase;
     const annotations = pendingWebSources.map(s => ({
       type: "url_citation", url: s.url, ...(s.title ? { title: s.title } : {}), start_index: 0, end_index: 0,
     }));
@@ -950,7 +981,7 @@ export function buildResponseJSON(
     output.push({
       type: "message", id: `msg_${uuid()}`, role: "assistant", status: "completed",
       content: [{ type: "output_text", text: currentText, annotations }],
-      ...(currentTextPhase ? { phase: currentTextPhase } : {}),
+      ...(phase ? { phase } : {}),
     });
     currentText = "";
     currentTextPhase = undefined;
@@ -1025,13 +1056,15 @@ export function buildResponseJSON(
   for (const e of events) {
     switch (e.type) {
       case "assistant_boundary":
-        flushText();
+        flushText("commentary");
         flushSummaryReasoning();
         flushRawReasoning();
         flushToolCall();
         break;
       case "text_delta":
-        if (currentText && currentTextPhase !== e.phase) flushText();
+        // Only flush on an explicit phase change. A later delta that omits `phase` must keep
+        // appending under the previously established phase.
+        if (currentText && e.phase !== undefined && currentTextPhase !== e.phase) flushText("commentary");
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentRawReasoning) flushRawReasoning();
         if (currentToolCallId) flushToolCall();
@@ -1039,12 +1072,12 @@ export function buildResponseJSON(
         // bridgeToResponsesSSE); it ships only inside the synthetic compaction item below.
         if (options?.compaction) compactionText += e.text;
         else {
-          currentTextPhase = e.phase;
+          if (e.phase !== undefined) currentTextPhase = e.phase;
           currentText += e.text;
         }
         break;
       case "thinking_delta":
-        if (currentText) flushText();
+        if (currentText) flushText("commentary");
         if (currentRawReasoning) flushRawReasoning();
         if (currentToolCallId) flushToolCall();
         currentSummaryReasoning += e.thinking;
@@ -1059,13 +1092,13 @@ export function buildResponseJSON(
         batchRedacted.push(e.data);
         break;
       case "reasoning_raw_delta":
-        if (currentText) flushText();
+        if (currentText) flushText("commentary");
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentToolCallId) flushToolCall();
         currentRawReasoning += e.text;
         break;
       case "tool_call_start":
-        if (currentText) flushText();
+        if (currentText) flushText("commentary");
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentRawReasoning) flushRawReasoning();
         flushToolCall();
@@ -1084,7 +1117,7 @@ export function buildResponseJSON(
         // single finalized item, emitted on `end`. Begin is a no-op here.
         break;
       case "web_search_call_end":
-        if (currentText) flushText();
+        if (currentText) flushText("commentary");
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentRawReasoning) flushRawReasoning();
         flushToolCall();
@@ -1112,25 +1145,33 @@ export function buildResponseJSON(
       case "done":
         usage = e.usage;
         endTurn = e.endTurn;
+        cleanDone = e.stopReason === undefined;
         if (e.providerState) options?.onProviderState?.(e.providerState);
-        if (e.stopReason === "max_tokens") stopReason = "max_tokens";
+        // Match streaming: max_tokens and content_filter both terminate as incomplete.
+        if (e.stopReason === "max_tokens" || e.stopReason === "content_filter") stopReason = e.stopReason;
         break;
     }
   }
-  flushText();
+  flushText(cleanDone && !errorEvent && !incompleteEvent ? "final_answer" : undefined);
   flushSummaryReasoning();
   flushRawReasoning();
   flushToolCall();
   // A truncated turn must never be installed as replacement history: emit the
   // compaction item only when the turn actually completed (#422).
-  if (options?.compaction && !errorEvent && !incompleteEvent && stopReason !== "max_tokens") {
+  if (
+    options?.compaction
+    && !errorEvent
+    && !incompleteEvent
+    && stopReason !== "max_tokens"
+    && stopReason !== "content_filter"
+  ) {
     output.push({ type: "compaction", id: `cmp_${uuid()}`, encrypted_content: encodeCompactionSummary(compactionText) });
   }
 
   const failure = errorEvent ? adapterFailureFromEvent(errorEvent) : undefined;
   const status = errorEvent
     ? "failed"
-    : incompleteEvent || stopReason === "max_tokens"
+    : incompleteEvent || stopReason === "max_tokens" || stopReason === "content_filter"
       ? "incomplete"
       : "completed";
   options?.onUsage?.(incompleteEvent?.usage ?? usage);
@@ -1150,6 +1191,8 @@ export function buildResponseJSON(
       },
     } : stopReason === "max_tokens" ? {
       incomplete_details: { reason: "max_output_tokens" },
+    } : stopReason === "content_filter" ? {
+      incomplete_details: { reason: "content_filter" },
     } : {}),
     usage: responsesUsage(incompleteEvent?.usage ?? usage),
   };
@@ -1159,7 +1202,7 @@ export function formatErrorResponse(
   status: number,
   type: string,
   message: string,
-  options?: { code?: string | null },
+  options?: { code?: string | null; retryAfter?: string | null },
 ): Response {
   const error = classifyError(status, type, message);
   if (isCyberPolicyCode(options?.code)) {
@@ -1167,8 +1210,13 @@ export function formatErrorResponse(
     error.type = "invalid_request_error";
   }
   const finalStatus = error.code === CYBER_POLICY_ERROR_CODE ? 400 : status;
+  const headers = new Headers({ "Content-Type": "application/json" });
+  const retryAfter = options?.retryAfter?.trim();
+  if (retryAfter && retryAfter.length > 0 && retryAfter.length <= 128) {
+    headers.set("Retry-After", retryAfter);
+  }
   return new Response(JSON.stringify({ error }), {
     status: finalStatus,
-    headers: { "Content-Type": "application/json" },
+    headers,
   });
 }

package/src/claude/desktop-3p-paths.ts

@@ -0,0 +1,84 @@
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+
+/**
+ * Claude Desktop's own configLibrary location, ported from the shipped app bundle.
+ *
+ * Desktop assembles the directory name at runtime, which is why searching the
+ * bundle for the literal "Claude-3p" finds almost nothing (app.asar, v1.18286.0):
+ *
+ *   const Bu = "-3p", zW = "Claude", ND = `${zW}${Bu}`;
+ *   function GE(){
+ *     if (process.env.CLAUDE_USER_DATA_DIR) return app.getPath("userData");
+ *     if (process.platform === "win32" && process.env.LOCALAPPDATA) return join(process.env.LOCALAPPDATA, ND);
+ *     const t = app.getPath("userData");
+ *     return t.endsWith(Bu) ? t : `${t}${Bu}`;
+ *   }
+ *   function mD(){ return join(GE(), "configLibrary") }
+ *
+ * So `Claude-3p` is Desktop's correct default, not a mistake to "fix" — but the
+ * first two branches were missing here, which is what GitHub #539 actually hit.
+ *
+ * Resolution is a pure function of (env, platform, home) so tests can exercise the
+ * win32 branch on any host: stubbing `process.platform` does NOT propagate to
+ * `os.platform()` under Bun, so a platform-sniffing implementation would be
+ * untestable in this repo.
+ */
+const SUFFIX = "-3p";
+const APP_DIR = `Claude${SUFFIX}`;
+
+function joinForPlatform(platform: NodeJS.Platform, ...parts: string[]): string {
+  return platform === "win32" ? win32.join(...parts) : posix.join(...parts);
+}
+
+export interface DesktopPathInputs {
+  env: Record<string, string | undefined>;
+  platform: NodeJS.Platform;
+  home: string;
+}
+
+/** Electron `app.getPath("userData")`: per-platform appData + productName ("Claude"). */
+export function resolveElectronUserData(inputs: DesktopPathInputs): string {
+  const { env, platform, home } = inputs;
+  if (platform === "win32") {
+    const appData = env.APPDATA?.trim();
+    return appData ? win32.join(appData, "Claude") : win32.join(home, "AppData", "Roaming", "Claude");
+  }
+  if (platform === "darwin") return posix.join(home, "Library", "Application Support", "Claude");
+  const xdg = env.XDG_CONFIG_HOME?.trim();
+  return xdg ? posix.join(xdg, "Claude") : posix.join(home, ".config", "Claude");
+}
+
+/** Desktop's userData root, mirroring `GE()` branch for branch. */
+export function resolveUserDataDir(inputs: DesktopPathInputs): string {
+  const explicit = inputs.env.CLAUDE_USER_DATA_DIR?.trim();
+  // Desktop calls app.setPath("userData", CLAUDE_USER_DATA_DIR) at startup, so this
+  // path is used verbatim — notably WITHOUT the "-3p" suffix.
+  if (explicit) return explicit;
+
+  if (inputs.platform === "win32") {
+    const localAppData = inputs.env.LOCALAPPDATA?.trim();
+    if (localAppData) return win32.join(localAppData, APP_DIR);
+  }
+
+  const root = resolveElectronUserData(inputs);
+  // Concatenated, not joined: "Claude-3p" is one path component.
+  return root.endsWith(SUFFIX) ? root : `${root}${SUFFIX}`;
+}
+
+/**
+ * The directory opencodex writes its 3P profile into.
+ *
+ * OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR wins over every other branch and is returned
+ * verbatim (no `join`), because tests point it straight at a temp directory.
+ */
+export function resolveConfigLibraryDir(inputs: DesktopPathInputs): string {
+  const override = inputs.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR?.trim();
+  if (override) return override;
+  return joinForPlatform(inputs.platform, resolveUserDataDir(inputs), "configLibrary");
+}
+
+/** Runtime wrapper. Keep it thin: all branching lives in the pure functions above. */
+export function claudeDesktopConfigLibraryDir(): string {
+  return resolveConfigLibraryDir({ env: process.env, platform: process.platform, home: homedir() });
+}

package/src/claude/desktop-3p.ts

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
 import type { OcxClaudeDesktopProfile } from "../types";
+import { claudeDesktopConfigLibraryDir, resolveConfigLibraryDir } from "./desktop-3p-paths";
 import {
   reconcileDesktopProfile,
   renderDesktopProfile,
@@ -49,6 +50,33 @@ export interface Desktop3pRoutedModel {
  */
 export const DESKTOP_SUPPORTS_1M_THRESHOLD = 1_000_000;
 
+export interface Desktop3pConfigLibraryOptions {
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  homeDir?: string;
+}
+
+/**
+ * Resolve the config library from the same user-data root Claude Desktop uses. Keeping this in one
+ * helper prevents the writer and dashboard status probe from agreeing on a path Desktop never reads.
+ *
+ * The resolution itself lives in `./desktop-3p-paths`, which ports Claude Desktop's own `GE()`
+ * branch for branch — including the `-3p` suffix the app appends to its userData root. Dropping
+ * that suffix points us at a directory Desktop never reads (GitHub #539).
+ */
+export function resolveDesktop3pConfigLibraryPath(
+  options: Desktop3pConfigLibraryOptions = {},
+): string {
+  if (options.env === undefined && options.platform === undefined && options.homeDir === undefined) {
+    return claudeDesktopConfigLibraryDir();
+  }
+  return resolveConfigLibraryDir({
+    env: options.env ?? process.env,
+    platform: options.platform ?? process.platform,
+    home: options.homeDir ?? homedir(),
+  });
+}
+
 /** CLI arg parsing for `ocx claude desktop` mode flags (mutually exclusive). */
 export function parseDesktop3pModeArgs(flags: string[]): { mode: Desktop3pConfigMode } | { error: string } {
   const known = new Map<string, Desktop3pConfigMode>([
@@ -308,8 +336,7 @@ export function writeDesktop3pConfig(
   mode: Desktop3pConfigMode = "static",
   profile?: OcxClaudeDesktopProfile,
 ): { written: boolean; path: string; reason?: string; fingerprint?: string } {
-  const libraryPath = process.env.OPENCODEX_CLAUDE_DESKTOP_CONFIG_DIR?.trim()
-    || join(homedir(), "Library", "Application Support", "Claude-3p", "configLibrary");
+  const libraryPath = resolveDesktop3pConfigLibraryPath();
   const metadataPath = join(libraryPath, "_meta.json");
   let configPath = libraryPath;