@bitkyc08/opencodex 2.86.0 → 2.87.0

package/src/bridge/response-json.ts

@@ -1,3 +1,4 @@
+import { anthropicProgressItems } from "../responses/anthropic-progress";
 import type {
   AdapterEvent,
   OcxMessagePhase,
@@ -67,6 +68,8 @@ export function buildResponseJSON(
     if (options?.translatorBudget && options.recordBufferedDelivery !== false) {
       attemptDeliveryRecorder(budget)?.noteBufferedDelivery(body);
     }
+    if (body.status === "completed" && options?.compaction
+      && !events.some(event => event.type === "done" && event.compactionEncryptedContent)) options.compactionRetention?.commit();
     return body;
   } finally {
     for (const event of events) {
@@ -98,6 +101,7 @@ function buildResponseJSONWithBudget(
     toolSearchToolNames?: Set<string>;
     /** Remote compaction v2 turn — append one synthetic compaction output item (see bridgeToResponsesSSE). */
     compaction?: boolean;
+    compactionRetention?: { encode(summary: string): string; commit(): void };
     onProviderState?: (state: OcxProviderContinuationState) => void;
     /** Raw adapter-reported usage before wire normalization (see bridgeToResponsesSSE onUsage). */
     onUsage?: (usage: OcxUsage | undefined) => void;
@@ -386,6 +390,16 @@ function buildResponseJSONWithBudget(
         flushToolCall();
         break;
       case "text_delta":
+        if (options?.compaction && e.anthropicThinkingSignature) break;
+        if (e.anthropicThinkingSignature) {
+          rawReasoningForNextToolCall = "";
+          flushText("commentary");
+          flushSummaryReasoning();
+          flushRawReasoning();
+          flushToolCall();
+          for (const item of anthropicProgressItems(e.text, e.anthropicThinkingSignature, budget)) pushOutput(item as OutputItem);
+          break;
+        }
         // Only flush on an explicit phase change. A later delta that omits `phase` must keep
         // appending under the previously established phase.
         if (currentText.bytes > 0 && e.phase !== undefined && currentTextPhase !== e.phase) flushText("commentary");
@@ -533,8 +547,9 @@ function buildResponseJSONWithBudget(
         const safeSources = safeWebSearchSources(e.sources);
         pushOutput({
           type: "web_search_call", id: `ws_${uuid()}`, status: e.status ?? "completed",
-          action: webSearchAction(e.queries),
+          action: webSearchAction(e.queries, e.fetch),
           ...(safeSources.length > 0 ? { sources: safeSources } : {}),
+          ...(e.fetch ? { fetch_result: e.fetch.result } : {}),
         });
         if (safeSources.length > 0) {
           for (const source of safeSources) {
@@ -616,7 +631,7 @@ function buildResponseJSONWithBudget(
   ) {
    const item = {
       type: "compaction", id: `cmp_${uuid()}`,
-      encrypted_content: compactionEncryptedContent ?? encodeCompactionSummary(joinChunks(batchCompaction)),
+      encrypted_content: compactionEncryptedContent ?? (options?.compactionRetention?.encode(joinChunks(batchCompaction)) ?? encodeCompactionSummary(joinChunks(batchCompaction))),
     };
     pushOutput(item, compactionEncryptedContent ? 0 : batchCompaction.bytes);
   }
@@ -646,7 +661,7 @@ function buildResponseJSONWithBudget(
       : errorEvent?.retryable !== undefined ? { retryable: errorEvent.retryable } : {}),
     ...(incompleteEvent ? {
       incomplete_details: {
-        reason: incompleteEvent.reason,
+        reason: truncationReasonFor(incompleteEvent.reason) ?? incompleteEvent.reason,
         ...(incompleteEvent.message ? { message: incompleteEvent.message } : {}),
         ...(incompleteEvent.retryable !== undefined ? { retryable: incompleteEvent.retryable } : {}),
       },

package/src/bridge/sse.ts

@@ -1,3 +1,4 @@
+import { anthropicProgressItems } from "../responses/anthropic-progress";
 import type {
   AdapterEvent,
   OcxMessagePhase,
@@ -12,7 +13,7 @@ import {
   classifyError,
   cyberPolicyErrorType,
   CYBER_POLICY_ERROR_CODE,
-  isCyberPolicyCode,
+  isTerminalRefusalCode,
   type OcxErrorPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
@@ -50,6 +51,7 @@ import {
 } from "../lib/translator-budget";
 import { adapterFailureFromEvent, emptyChunks, joinChunks, ownedBudgetAbandonedMs, responsesUsage, toolCallArgumentsCouldBeJson, toolCallArgumentsUsable, uuid, webSearchAction } from "./internal";
 import type { OutputItem, StringChunks } from "./internal";
+import { terminalRefusalFailure } from "./terminal-refusal";
 
 function sseEvent(name: string, data: Record<string, unknown>): string {
   return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
@@ -88,6 +90,7 @@ export function bridgeToResponsesSSE(
      * response.completed — codex-rs collect_compaction_output requires exactly one.
      */
     compaction?: boolean;
+    compactionRetention?: { encode(summary: string): string; commit(): void };
     /** One-shot: first non-empty text/thinking/raw-reasoning/tool-input delta observed. */
     onFirstOutput?: () => void;
     onTerminal?: (status: ResponsesTerminalStatus) => void;
@@ -120,6 +123,12 @@ export function bridgeToResponsesSSE(
      * would reach the client under the invented name instead of the normalized one.
      */
     enforceDeclaredToolNames?: boolean;
+    /**
+     * Deliver a non-retryable upstream refusal as `response.failed` with a terminal-refusal code
+     * instead of `response.incomplete` (see `./terminal-refusal`). Set only for the Responses
+     * inbound wire: the chat and Anthropic encoders read the incomplete to report a filter stop.
+     */
+    terminalRefusalAsFailed?: boolean;
     /** Declared parameter schema per tool name; repairs integral-float integer args (#1611). */
     toolParameterSchemas?: ReadonlyMap<string, Record<string, unknown>>;
     /**
@@ -676,12 +685,15 @@ export function bridgeToResponsesSSE(
       // leaves a "Searching the web" spinner spinning forever.
       // `sources` rides on the done item (additive field; codex-rs serde ignores unknown fields) so
       // downstream translators (claude outbound) can fill web_search_tool_result content.
-      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[]) => {
+      // `fetch` (Anthropic's server-side web_fetch) makes the cell a page open and rides its result
+      // verbatim as `fetch_result`, for the same claude outbound translator.
+      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[], fetch?: { url: string; result: unknown }) => {
         if (!currentWebSearch) return;
         const item = {
           type: "web_search_call", id: currentWebSearch.itemId, status,
-          action: webSearchAction(queries),
+          action: webSearchAction(queries, fetch),
           ...(sources && sources.length > 0 ? { sources } : {}),
+          ...(fetch ? { fetch_result: fetch.result } : {}),
         };
         emit("response.output_item.done", { output_index: currentWebSearch.outputIndex, item });
         retainFinishedItem(item as OutputItem);
@@ -841,6 +853,7 @@ export function bridgeToResponsesSSE(
           // its compaction UI renders nothing mid-turn, so nothing is lost visually.
           if (options?.compaction) {
             if (event.type === "text_delta") {
+              if (event.anthropicThinkingSignature) continue;
               compaction = appendString(
                 compaction,
                 event.text,
@@ -871,6 +884,29 @@ export function bridgeToResponsesSSE(
               break;
             }
             case "text_delta": {
+              if (event.anthropicThinkingSignature) {
+                rawReasoningForNextToolCall = "";
+                closeCurrentMessage("commentary");
+                closeCurrentReasoning();
+                closeCurrentRawReasoning();
+                flushHiddenRawReasoning();
+                flushHiddenReasoningEnvelope();
+                if (currentToolCall) closeCurrentToolCall();
+                for (const item of anthropicProgressItems(event.text, event.anthropicThinkingSignature, budget)) {
+                  emit("response.output_item.added", { output_index: outputIndex, item: { ...item, ...(item.type === "message" ? { status: "in_progress", content: [] } : {}) } });
+                  if (item.type === "message") {
+                    const part = item.content![0];
+                    emit("response.content_part.added", { item_id: item.id, output_index: outputIndex, content_index: 0, part: { ...part, text: "" } });
+                    emit("response.output_text.delta", { item_id: item.id, output_index: outputIndex, content_index: 0, delta: event.text });
+                    emit("response.output_text.done", { item_id: item.id, output_index: outputIndex, content_index: 0, text: event.text });
+                    emit("response.content_part.done", { item_id: item.id, output_index: outputIndex, content_index: 0, part });
+                  }
+                  emit("response.output_item.done", { output_index: outputIndex, item });
+                  retainFinishedItem(item as OutputItem);
+                  outputIndex++;
+                }
+                break;
+              }
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
@@ -1195,7 +1231,7 @@ export function bridgeToResponsesSSE(
                 currentWebSearch = { itemId: wsItemId2, eventId: event.id, outputIndex };
               }
               const safeSources = safeWebSearchSources(event.sources);
-              closeCurrentWebSearch(event.status ?? "completed", event.queries, safeSources);
+              closeCurrentWebSearch(event.status ?? "completed", event.queries, safeSources, event.fetch);
               // Queue this search's sources for the next assistant message (dedup by URL).
               if (safeSources.length > 0) {
                 for (const source of safeSources) {
@@ -1233,7 +1269,7 @@ export function bridgeToResponsesSSE(
                 // Exactly one compaction item per turn; codex-rs takes the first and fatals on 0.
                 const item = {
                   type: "compaction", id: `cmp_${uuid()}`,
-                  encrypted_content: event.compactionEncryptedContent ?? encodeCompactionSummary(joinChunks(compaction)),
+                  encrypted_content: event.compactionEncryptedContent ?? (options?.compactionRetention?.encode(joinChunks(compaction)) ?? encodeCompactionSummary(joinChunks(compaction))),
                 };
                 emit("response.output_item.done", { output_index: outputIndex, item });
                 retainFinishedItem(item as OutputItem, event.compactionEncryptedContent ? 0 : compaction.bytes);
@@ -1271,6 +1307,7 @@ export function bridgeToResponsesSSE(
                 emit("response.completed", {
                   response,
                 });
+                if (!closed && !terminated && options?.compaction && !event.compactionEncryptedContent) options.compactionRetention?.commit();
                 reportTerminal("completed");
               }
               terminalEvent = true;
@@ -1287,12 +1324,25 @@ export function bridgeToResponsesSSE(
               flushHiddenReasoningEnvelope();
               options?.onUsage?.(event.usage);
               await awaitThoughtSignatureDurability();
+              const refusal = options?.terminalRefusalAsFailed ? terminalRefusalFailure(event) : undefined;
+              if (refusal) {
+                emit("response.failed", {
+                  response: {
+                    ...responseSnapshot("failed", finishedItems, event.endTurn),
+                    usage: responsesUsage(event.usage),
+                    ...refusal,
+                  },
+                });
+                reportTerminal("failed");
+                terminalEvent = true;
+                break;
+              }
               emit("response.incomplete", {
                 response: {
                   ...responseSnapshot("incomplete", finishedItems, event.endTurn),
                   usage: responsesUsage(event.usage),
                   incomplete_details: {
-                    reason: event.reason,
+                    reason: truncationReasonFor(event.reason) ?? event.reason,
                     ...(event.message ? { message: event.message } : {}),
                     ...(event.retryable !== undefined ? { retryable: event.retryable } : {}),
                   },
@@ -1325,7 +1375,7 @@ export function bridgeToResponsesSSE(
                   ...(event.usage ? { usage: responsesUsage(event.usage) } : {}),
                   error: failure.error,
                   last_error: failure.error,
-                  ...(isCyberPolicyCode(failure.error.code)
+                  ...(isTerminalRefusalCode(failure.error.code)
                     ? { retryable: false }
                     : event.retryable !== undefined ? { retryable: event.retryable } : {}),
                 },
@@ -1366,7 +1416,7 @@ export function bridgeToResponsesSSE(
               ...responseSnapshot("failed", finishedItems),
               error: failure,
               last_error: failure,
-              ...(isCyberPolicyCode(failure.code) ? { retryable: false } : {}),
+              ...(isTerminalRefusalCode(failure.code) ? { retryable: false } : {}),
             },
           });
           reportTerminal("failed");

package/src/bridge/terminal-refusal.ts

@@ -0,0 +1,59 @@
+import type { AdapterEvent } from "../types";
+import type { OcxErrorPayload } from "../lib/errors";
+import { redactSecretString } from "../lib/redact";
+
+/**
+ * The terminal-refusal code Codex ends a turn on. It is a member of `TERMINAL_REFUSAL_CODES`
+ * in `src/lib/errors.ts`, and the one that says "this prompt, as sent, is refused" without
+ * claiming a specific policy family the upstream never named.
+ */
+const TERMINAL_REFUSAL_FAILED_CODE = "invalid_prompt";
+
+interface TerminalRefusalFailure {
+  error: OcxErrorPayload;
+  last_error: OcxErrorPayload;
+  retryable: false;
+}
+
+/**
+ * Client-visible copy: what happened, and that resending the same context cannot help. It points
+ * at a new conversation rather than a new turn, because a later turn replays the refused context.
+ */
+function terminalRefusalMessage(detail: string | undefined): string {
+  const reason = detail?.trim() ? ` (${redactSecretString(detail.trim())})` : "";
+  return `The upstream model refused this request${reason}. `
+    + "Retrying with the same conversation context will not succeed; change the request or start a new conversation.";
+}
+
+/**
+ * An adapter `incomplete` that is a non-retryable upstream refusal: a content filter carrying an
+ * explicit `retryable: false` verdict. A filter without the verdict, an output cap, a stall and an
+ * adapter EOF do not qualify. The sidecar loops read this too: a refused iteration ends the turn,
+ * so a sidecar call it carried is neither run nor answered with another model request.
+ */
+export function isTerminalRefusalIncomplete(event: AdapterEvent | undefined): boolean {
+  return event?.type === "incomplete" && event.reason === "content_filter" && event.retryable === false;
+}
+
+/**
+ * `response.failed` fields for an adapter `incomplete` that is a non-retryable upstream refusal
+ * (#4312), or `undefined` when the event is anything else. The Anthropic and Kiro adapters are
+ * the ones that emit it today.
+ *
+ * codex-rs maps every `response.incomplete` to a retryable stream error and never reads
+ * `incomplete_details.retryable`, so a refusal delivered that way is re-sent through the whole
+ * stream retry budget. It only ends the turn on `response.failed` carrying a terminal-refusal
+ * `error.code`. Only an explicit `retryable: false` content filter qualifies: a filter without
+ * the verdict, an output cap, a stall and an adapter EOF stay `response.incomplete`.
+ */
+export function terminalRefusalFailure(
+  event: Extract<AdapterEvent, { type: "incomplete" }>,
+): TerminalRefusalFailure | undefined {
+  if (!isTerminalRefusalIncomplete(event)) return undefined;
+  const error: OcxErrorPayload = {
+    type: "invalid_request_error",
+    code: TERMINAL_REFUSAL_FAILED_CODE,
+    message: terminalRefusalMessage(event.message),
+  };
+  return { error, last_error: error, retryable: false };
+}

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

@@ -1,4 +1,4 @@
-import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, type BigIntStats } from "node:fs";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync, type BigIntStats } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { claudeDesktopConfigLibraryDir, resolveConfigLibraryDir } from "./desktop-3p-paths";
@@ -84,9 +84,20 @@ export function readDesktopLibraryText(path: string): string {
   return readDesktopLibraryBytes(path).toString("utf8");
 }
 
+/** Only an absent directory entry is optional; dangling links and failed reads still refuse. */
+export function readOptionalDesktopLibraryBytes(path: string): Buffer | undefined {
+  try { return readDesktopLibraryBytes(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+/** Read optional verified metadata; a present file must contain an entries array. */
 export function parseMetadata(path: string): Desktop3pMetadata {
-  if (!existsSync(path)) return { entries: [] };
-  const parsed = JSON.parse(readDesktopLibraryText(path)) as Partial<Desktop3pMetadata>;
+  const bytes = readOptionalDesktopLibraryBytes(path);
+  if (bytes === undefined) return { entries: [] };
+  const parsed = JSON.parse(bytes.toString("utf8")) as Partial<Desktop3pMetadata>;
   if (!Array.isArray(parsed.entries)) throw new Error("Claude Desktop 3P _meta.json has no entries array");
   return { ...parsed, entries: parsed.entries };
 }
@@ -120,11 +131,25 @@ export const OPENCODEX_DESKTOP_PROFILE_KEYS = new Set([
   "inferenceModels",
 ]);
 
-export function readDesktopProfileForeignKeys(path: string): Record<string, unknown> {
-  if (!existsSync(path)) return {};
-  const parsed = JSON.parse(readDesktopLibraryText(path)) as unknown;
+export interface DesktopProfileSnapshot {
+  /** Verified bytes of the existing profile; undefined only when the entry is absent. */
+  bytes?: Buffer;
+  foreign: Record<string, unknown>;
+}
+
+/** Capture verified bytes for key preservation, backup and rollback; publication revalidates them. */
+export function readDesktopProfileSnapshot(path: string): DesktopProfileSnapshot {
+  const bytes = readOptionalDesktopLibraryBytes(path);
+  if (bytes === undefined) return { foreign: {} };
+  const parsed = JSON.parse(bytes.toString("utf8")) as unknown;
   if (!isRecord(parsed)) throw new Error("Claude Desktop 3P profile is not a JSON object");
-  return Object.fromEntries(
+  const foreign = Object.fromEntries(
     Object.entries(parsed).filter(([key]) => !OPENCODEX_DESKTOP_PROFILE_KEYS.has(key)),
   );
+  return { bytes, foreign };
+}
+
+/** Preserve settings outside the gateway-owned keys from a verified profile. */
+export function readDesktopProfileForeignKeys(path: string): Record<string, unknown> {
+  return readDesktopProfileSnapshot(path).foreign;
 }

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

@@ -5,15 +5,16 @@ import { applyRemoteDesktopStore, inspectRemoteDesktopCleanup, restoreRemoteDesk
 import { canonicalDirectory } from "./desktop-remote-store-io";
 import {
   resolveDesktop3pConfigLibraryPath, parseMetadata, SAFE_DESKTOP_PROFILE_ID, isRecord,
-  isOwnedDesktopEntry, isOwnedDesktopGatewayEntry, profilePath, readDesktopProfileForeignKeys, readDesktopLibraryText, readDesktopLibraryBytes,
+  isOwnedDesktopEntry, isOwnedDesktopGatewayEntry, profilePath, readDesktopProfileSnapshot, readDesktopLibraryText, readDesktopLibraryBytes,
+  readOptionalDesktopLibraryBytes,
   type Desktop3pConfigLibraryOptions, type Desktop3pMetadata, type Desktop3pMetadataEntry,
 } from "./desktop-3p-library";
 export { resolveDesktop3pConfigLibraryPath, type Desktop3pConfigLibraryOptions } from "./desktop-3p-library";
 import { createHash, randomUUID } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, lstatSync, unlinkSync } from "node:fs";
+import { existsSync, mkdirSync, lstatSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { atomicWriteFile, readConfigDiagnostics, withConfigMutationLockSync } from "../config";
-import { atomicWriteFileNoFollow } from "../config/atomic-write";
+import { atomicWriteFileNoFollow, atomicWriteFileStreamed } from "../config/atomic-write";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import type { OcxClaudeDesktopProfile } from "../types";
 import {
@@ -800,6 +801,7 @@ function desktopRefreshPathsSafe(libraryPath: string, configPath?: string): bool
   } catch { return false; }
 }
 
+/** Publish a gateway profile from a verified snapshot, rolling it back if metadata fails. */
 function writeDesktop3pConfigWithGenerator(
   generate: () => object,
   refreshOnly?: { requiredId: string; expectedFingerprint: string; admit: () => boolean },
@@ -828,8 +830,8 @@ function writeDesktop3pConfigWithGenerator(
       : [...metadata.entries, entry];
 
     const generated = generate();
-    const preserved = readDesktopProfileForeignKeys(configPath);
-    const configJson = JSON.stringify({ ...preserved, ...generated }, null, 2) + "\n";
+    const previous = readDesktopProfileSnapshot(configPath);
+    const configJson = JSON.stringify({ ...previous.foreign, ...generated }, null, 2) + "\n";
     const fingerprint = createHash("sha256").update(configJson).digest("hex").slice(0, 16);
     if (refreshOnly) {
       atomicWriteFileNoFollow(configPath, configJson, undefined, {
@@ -847,12 +849,31 @@ function writeDesktop3pConfigWithGenerator(
       });
       return { written: true, path: configPath, fingerprint };
     }
-    const { backupPath } = atomicReplaceDesktopConfig(configPath, configJson);
+    atomicReplaceDesktopConfig(configPath, configJson, previous.bytes);
     try {
       atomicWriteFile(metadataPath, JSON.stringify({ ...metadata, appliedId: id, entries }, null, 2) + "\n");
     } catch (metaError) {
-      // Rollback: restore the backed-up config if metadata write fails.
-      if (backupPath && existsSync(backupPath)) copyFileSync(backupPath, configPath);
+      // Roll back from the verified bytes in memory: reopening the backup could meet a swapped
+      // entry and leave the new profile beside the old metadata. A profile this call created is
+      // unreferenced once metadata failed, so remove it rather than orphan one per retry.
+      // Rollback is ownership-aware: it acts only while the live profile still holds the bytes
+      // this call published, checked by the same comparison that guarded publication.
+      const base = metaError instanceof Error ? metaError.message : String(metaError);
+      const published = Buffer.from(configJson);
+      let owned = false;
+      const stillOwned = () => { owned = false; assertDesktopProfileUnchanged(configPath, published); owned = true; };
+      try {
+        stillOwned();
+        if (previous.bytes !== undefined) writeDesktopConfigBytes(configPath, previous.bytes, stillOwned);
+        else unlinkSync(configPath);
+      } catch (rollbackError) {
+        if (!owned) {
+          // Another writer replaced the profile after publication; its bytes win over our rollback.
+          throw new Error(`${base} (profile rollback skipped: profile changed after publish)`, { cause: metaError });
+        }
+        const detail = rollbackError instanceof Error ? rollbackError.message : String(rollbackError);
+        throw new AggregateError([metaError, rollbackError], `${base} (profile rollback also failed: ${detail})`, { cause: metaError });
+      }
       throw metaError;
     }
     return { written: true, path: configPath, fingerprint };
@@ -862,14 +883,35 @@ function writeDesktop3pConfigWithGenerator(
   }
 }
 
-/** Backup an existing owned config then atomically replace it. Exported for failure-path tests. */
+/**
+ * Compare the live profile with the caller's verified bytes before backup and before replacement.
+ * Refuse drift without retrying; backup and rollback continue to use the original verified bytes.
+ * `previous` is undefined only for an absent profile, which leaves any older backup alone.
+ * Exported for failure-path tests.
+ */
 export function atomicReplaceDesktopConfig(
   path: string,
   content: string,
-  writer: (path: string, content: string) => void = atomicWriteFile,
+  previous: Buffer | undefined,
+  writer: typeof atomicWriteFileNoFollow = atomicWriteFileNoFollow,
 ): { backupPath?: string } {
+  const validateBeforeRename = () => assertDesktopProfileUnchanged(path, previous);
+  validateBeforeRename();
   const backupPath = `${path}.bak`;
-  if (existsSync(path)) copyFileSync(path, backupPath);
-  writer(path, content);
-  return existsSync(backupPath) ? { backupPath } : {};
+  if (previous !== undefined) writeDesktopConfigBytes(backupPath, previous);
+  writer(path, content, undefined, { validateBeforeRename });
+  return previous === undefined ? {} : { backupPath };
+}
+
+/** Single compare-and-swap check: the live profile must still hold `expected` (undefined = absent). */
+function assertDesktopProfileUnchanged(path: string, expected: Buffer | undefined): void {
+  const current = readOptionalDesktopLibraryBytes(path);
+  if (expected === undefined ? current !== undefined : current === undefined || !expected.equals(current)) {
+    throw new Error("desktop_profile_changed");
+  }
+}
+
+/** Publish the verified bytes without reopening the source or decoding its backup contents. */
+function writeDesktopConfigBytes(path: string, bytes: Buffer, validateBeforeRename?: () => void): void {
+  atomicWriteFileStreamed(path, descriptor => { writeFileSync(descriptor, bytes); }, validateBeforeRename ? { validateBeforeRename } : {});
 }

package/src/claude/desktop-first-party.ts

@@ -25,7 +25,7 @@ import type { OcxConfig } from "../types";
 import { claudeConfigDir } from "./auth-detect";
 import { inspectDesktop3pConfigLibrary } from "./desktop-3p";
 import { claudeInterceptCaCertPath, ensureLocalInterceptCa } from "./intercept/local-ca";
-import { claudeInterceptEnabled, claudeInterceptProxyPort } from "./intercept/runtime";
+import { claudeInterceptEnabled, claudeInterceptProxyPort } from "./intercept/port-policy";
 import { ensureClaudeInterceptProxyToken, readClaudeInterceptProxyToken } from "./intercept/proxy-auth";
 import {
   applyClaudeInterceptSettings,

package/src/claude/desktop-picker-platform.ts

@@ -0,0 +1,4 @@
+/** Platforms with a Desktop egress profile and an OS trust adapter for the picker. */
+export function supportsDesktopPicker(platform: NodeJS.Platform = process.platform): boolean {
+  return platform === "darwin" || platform === "win32";
+}

package/src/claude/desktop-picker.ts

@@ -23,6 +23,7 @@ import {
   type DesktopPickerProfileOptions,
 } from "./desktop-picker-profile";
 import { resolveClaudeDesktopMode, observeClaudeDesktopMode } from "./desktop-first-party";
+import { supportsDesktopPicker } from "./desktop-picker-platform";
 
 /** Desktop no longer selects the picker profile, so removing the CA's trust cannot strand it. */
 function profileReleased(profile: DesktopPickerProfileInspection): boolean {
@@ -77,6 +78,8 @@ export interface DesktopPickerControllerDeps {
   persistPreference: (value: boolean) => boolean;
   /** Bound picker CONNECT proxy port (Desktop's egress), or null when it is not running. */
   proxyPort: () => number | null;
+  /** Bind a dormant relay on explicit enable, under the controller's mutation lock. */
+  ensureProxy?: () => Promise<void>;
   configDir: string;
   persistentAuthority?: { store?: PickerCaStore };
   security?: SecurityRunner;
@@ -91,7 +94,7 @@ function profileOptions(deps: DesktopPickerControllerDeps): DesktopPickerProfile
 }
 
 function statusReasonForConfig(config: OcxConfig, platform: NodeJS.Platform, proxyBound: boolean): DesktopPickerReason {
-  if (platform !== "darwin") return "unsupported_platform";
+  if (!supportsDesktopPicker(platform)) return "unsupported_platform";
   if (resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) !== "first-party") return "not_first_party";
   if (!claudeDesktopIntegrationEnabled(config)) return "integration_off";
   if (config.claudeCode?.intercept?.picker === false) return "disabled";
@@ -101,11 +104,11 @@ function statusReasonForConfig(config: OcxConfig, platform: NodeJS.Platform, pro
 
 function emptyStatus(config: OcxConfig, platform: NodeJS.Platform, reason: DesktopPickerReason): DesktopPickerStatus {
   return {
-    desired: platform === "darwin"
+    desired: supportsDesktopPicker(platform)
       && claudeDesktopIntegrationEnabled(config)
       && resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) === "first-party"
       && config.claudeCode?.intercept?.picker !== false,
-    supported: platform === "darwin",
+    supported: supportsDesktopPicker(platform),
     trust: "unknown",
     profile: "absent",
     listenerReady: false,
@@ -142,7 +145,7 @@ export function createDesktopPickerController(deps: DesktopPickerControllerDeps)
     const trust = trustOverride ?? runtime.trust;
     const effective = runtime.effective && profileCurrent && trust === "trusted";
     let reason: DesktopPickerReason;
-    if (platform !== "darwin") reason = "unsupported_platform";
+    if (!supportsDesktopPicker(platform)) reason = "unsupported_platform";
     else if (!runtime.desired) reason = statusReasonForConfig(deps.readConfig(), platform, deps.proxyPort() !== null);
     else if (deps.proxyPort() === null) reason = "proxy_unavailable";
     else if (trust !== "trusted") reason = "trust_pending";
@@ -178,7 +181,7 @@ export function createDesktopPickerController(deps: DesktopPickerControllerDeps)
 
   async function untrustCurrentCa(): Promise<boolean> {
     const caPath = pickerCaCertPath(deps.configDir);
-    if (platform !== "darwin" || !existsSync(caPath)) return true;
+    if (!supportsDesktopPicker(platform) || !existsSync(caPath)) return true;
     try {
       const sha1 = pickerCaFingerprints(readFileSync(caPath, "utf8")).sha1;
       return (await untrustPickerCa(caPath, sha1, deps.security, platform)).ok;
@@ -207,11 +210,11 @@ export function createDesktopPickerController(deps: DesktopPickerControllerDeps)
       return withTrustFailure({ ...runtimeStatus(observedTrust), reason }, trustFailed);
     };
     const check = (config: OcxConfig, includePreference: boolean): DesktopPickerReason | null => {
-      if (platform !== "darwin") return "unsupported_platform";
+      if (!supportsDesktopPicker(platform)) return "unsupported_platform";
       if (resolveClaudeDesktopMode(config, observeClaudeDesktopMode(config)) !== "first-party") return "mode_not_committed";
       if (!claudeDesktopIntegrationEnabled(config)) return "integration_off";
       if (includePreference && config.claudeCode?.intercept?.picker === false) return "disabled";
-      if (deps.proxyPort() === null) return "proxy_unavailable";
+      if (deps.proxyPort() === null && !deps.ensureProxy) return "proxy_unavailable";
       return null;
     };
 
@@ -224,6 +227,10 @@ export function createDesktopPickerController(deps: DesktopPickerControllerDeps)
     }
     const second = check(deps.readConfig(), true);
     if (second) return refuse(second);
+    if (deps.proxyPort() === null) {
+      try { await deps.ensureProxy?.(); } catch { return refuse("proxy_unavailable"); }
+    }
+    if (deps.proxyPort() === null) return refuse("proxy_unavailable");
 
     let caPath: string;
     let caSha1: string;
@@ -336,7 +343,7 @@ export async function removeDesktopPickerArtifacts(options: { configDir?: string
     return { ok: false, residual };
   }
   const caPath = pickerCaCertPath(configDir);
-  if (platform === "darwin" && existsSync(caPath)) {
+  if (supportsDesktopPicker(platform) && existsSync(caPath)) {
     try {
       const sha1 = pickerCaFingerprints(readFileSync(caPath, "utf8")).sha1;
       if (!(await untrustPickerCa(caPath, sha1, options.security, platform)).ok) residual.push("trust");