@bitkyc08/opencodex 2.86.0 → 2.88.0

package/src/bridge/sse.ts

@@ -1,5 +1,7 @@
+import { anthropicProgressItems } from "../responses/anthropic-progress";
 import type {
   AdapterEvent,
+  AnthropicServerBlocks,
   OcxMessagePhase,
   OcxProviderContinuationState,
   OcxProviderOpaqueToolCallMetadata,
@@ -12,7 +14,7 @@ import {
   classifyError,
   cyberPolicyErrorType,
   CYBER_POLICY_ERROR_CODE,
-  isCyberPolicyCode,
+  isTerminalRefusalCode,
   type OcxErrorPayload,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
@@ -50,6 +52,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 +91,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 +124,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 +686,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 }[]) => {
+      // `anthropic` (Anthropic's server-side call) rides verbatim as `anthropic_blocks`, for the same
+      // claude outbound translator; a web_fetch makes the cell a page open.
+      const closeCurrentWebSearch = (status: "completed" | "failed", queries: string[], sources?: { url: string; title?: string }[], anthropic?: AnthropicServerBlocks) => {
         if (!currentWebSearch) return;
         const item = {
           type: "web_search_call", id: currentWebSearch.itemId, status,
-          action: webSearchAction(queries),
+          action: webSearchAction(queries, anthropic),
           ...(sources && sources.length > 0 ? { sources } : {}),
+          ...(anthropic ? { anthropic_blocks: anthropic } : {}),
         };
         emit("response.output_item.done", { output_index: currentWebSearch.outputIndex, item });
         retainFinishedItem(item as OutputItem);
@@ -841,6 +854,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 +885,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 +1232,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.anthropic);
               // Queue this search's sources for the next assistant message (dedup by URL).
               if (safeSources.length > 0) {
                 for (const source of safeSources) {
@@ -1233,7 +1270,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 +1308,7 @@ export function bridgeToResponsesSSE(
                 emit("response.completed", {
                   response,
                 });
+                if (!closed && !terminated && options?.compaction && !event.compactionEncryptedContent) options.compactionRetention?.commit();
                 reportTerminal("completed");
               }
               terminalEvent = true;
@@ -1287,12 +1325,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 +1376,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 +1417,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");

package/src/claude/desktop-system-proxy.ts

@@ -1,4 +1,6 @@
 import type { OcxConfig } from "../types";
+import { connect } from "node:net";
+import { directLocalHttpFetch } from "../server/direct-local-http";
 import {
   readWindowsProxyBypassRegistry,
   readWindowsSystemProxy,
@@ -8,6 +10,7 @@ import {
 } from "../lib/windows-system-proxy";
 import { inspectDesktopFirstParty, observeClaudeDesktopMode } from "./desktop-first-party";
 import { desktopFirstPartyDesired } from "./first-party-settings";
+import { inspectDesktopPickerProfile, type DesktopPickerProfileInspection } from "./desktop-picker-profile";
 
 /**
  * Whether the Windows system proxy silently bypasses Desktop first-party mode.
@@ -17,7 +20,8 @@ import { desktopFirstPartyDesired } from "./first-party-settings";
  * as `HTTPS_PROXY`/`HTTP_PROXY`. That inherited value takes precedence over the `env` block
  * OpenCodex writes into the user's `~/.claude/settings.json` (only Claude Code managed settings
  * override it), so Code-tab traffic goes to the system proxy and never reaches the intercept.
- * Routed subagent models then fail, and nothing else reports why. A system proxy such as Clash or
+ * A selected picker profile with an available fixed egress relay takes precedence instead.
+ * Otherwise routed subagent models fail. A system proxy such as Clash or
  * v2rayN, with no bypass for the API host, is the common case.
  *
  * Observe-only: this reads the registry and never changes it. A PAC script and WPAD automatic
@@ -123,6 +127,39 @@ export interface DesktopSystemProxyDeps {
   firstPartyState?: () => DesktopFirstPartySettingsState;
   readSystemProxy?: () => WindowsSystemProxyResult;
   readBypass?: () => WindowsProxyBypassValues | null;
+  inspectPickerProfile?: () => DesktopPickerProfileInspection;
+  pickerRelayAvailable?: (proxyUrl: string) => boolean | Promise<boolean>;
+}
+
+/** Observe the selected endpoint even in a separate doctor process or a blind-only recovery relay. */
+async function livePickerRelayAvailable(proxyUrl: string): Promise<boolean> {
+  const port = /^http:\/\/127\.0\.0\.1:([1-9][0-9]{0,4})$/.exec(proxyUrl)?.[1];
+  if (!port || Number(port) > 65535) return false;
+  try {
+    // A listening TCP socket alone is not evidence of an OpenCodex CONNECT relay.
+    const response = await directLocalHttpFetch(proxyUrl, { signal: AbortSignal.timeout(1_000) });
+    if (response.status !== 405 || response.headers.get("allow") !== "CONNECT"
+      || !(await response.text()).startsWith("OpenCodex Claude intercept proxy accepts only CONNECT tunnels.")) return false;
+    // The main intercept proxy has the same HTTP response but requires credentials the Desktop
+    // profile cannot send. A loopback CONNECT is denied before dialing or choosing any tunnel;
+    // 403 proves unauthenticated admission, whereas the credential-bearing proxy returns 407.
+    return await new Promise<boolean>(resolve => {
+      const socket = connect({ host: "127.0.0.1", port: Number(port) });
+      const finish = (available: boolean) => { clearTimeout(timer); socket.destroy(); resolve(available); };
+      const timer = setTimeout(() => finish(false), 1_000);
+      let head = "";
+      socket.once("error", () => finish(false));
+      socket.once("close", () => finish(false));
+      socket.once("connect", () => socket.write("CONNECT 127.0.0.1:1 HTTP/1.1\r\nHost: 127.0.0.1:1\r\n\r\n"));
+      socket.on("data", bytes => {
+        head += bytes.toString("latin1");
+        if (head.includes("\r\n\r\n")) finish(/^HTTP\/1\.[01] 403 Forbidden\r\n/.test(head));
+        else if (head.length > 8 * 1024) finish(false);
+      });
+    });
+  } catch { // no-excuse-ok: catch -- failed relay probes retain the registry diagnostic.
+    return false;
+  }
 }
 
 function liveFirstPartyState(
@@ -137,15 +174,24 @@ function liveFirstPartyState(
   }
 }
 
-/** Reads the live state. Registry reads run only on Windows with a Desktop first-party env. */
-export function collectDesktopSystemProxy(
+/** Registry reads run only on Windows with a Desktop first-party env and no verified picker relay. */
+export async function collectDesktopSystemProxy(
   config: Pick<OcxConfig, "claudeCode" | "clientIntegrations" | "port" | "runtimeRole">,
   deps: DesktopSystemProxyDeps = {},
-): DesktopSystemProxyAssessment {
+): Promise<DesktopSystemProxyAssessment> {
   const platform = deps.platform ?? process.platform;
   if (platform !== "win32") return { kind: "not-applicable" };
   const firstParty = (deps.firstPartyState ?? (() => liveFirstPartyState(config)))();
   if (firstParty === "off") return { kind: "not-applicable" };
+  if (firstParty === "applied" && config.claudeCode?.intercept?.picker !== false) {
+    try {
+      const profile = (deps.inspectPickerProfile ?? (() => inspectDesktopPickerProfile({ platform })))();
+      if (profile.kind === "applied" && await (deps.pickerRelayAvailable ?? livePickerRelayAvailable)(profile.proxyUrl)) {
+        return { kind: "not-applicable" };
+      }
+    } catch { // no-excuse-ok: catch -- missing profile/relay evidence must not hide a registry conflict.
+    }
+  }
   return assessDesktopSystemProxy({
     platform,
     firstParty,