@bitkyc08/opencodex 2.84.0 → 2.87.0

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/chat/inbound.ts

@@ -36,7 +36,7 @@ export function assertChatCompletionsRoutingBody(raw: unknown): asserts raw is C
 const OUTPUT_CONFIG_EFFORTS = new Set(["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"]);
 const OUTPUT_CONFIG_SUMMARIES = new Set(["auto", "concise", "detailed", "none"]);
 
-function contentToText(content: unknown): string {
+export function contentToText(content: unknown): string {
   if (typeof content === "string") return content;
   if (!Array.isArray(content)) return "";
   const parts: string[] = [];
@@ -62,7 +62,7 @@ const imageUrlFromPart = chatImageUrlFromPart;
  * understanding is requested by (#3271). The object form is the only one that
  * can carry it — `video_url` as a bare string has nowhere to put it.
  */
-function videoFromPart(part: Rec): { url: string; processing?: string } | null {
+export function videoFromPart(part: Rec): { url: string; processing?: string } | null {
   if (part.type !== "video_url") return null;
   const videoUrl = part.video_url;
   if (typeof videoUrl === "string" && videoUrl.length > 0) return { url: videoUrl };
@@ -123,7 +123,7 @@ function userContentToBlocks(content: unknown): Rec[] {
  * was dropped in silence (#5212). A part with no inline bytes is still not translatable and is
  * left to the untranslated-media refusal, which runs before this loop.
  */
-function fileFromPart(part: Rec): Rec | null {
+export function fileFromPart(part: Rec): Rec | null {
   if (part.type !== "file" && part.type !== "input_file") return null;
   const file = isRec(part.file) ? part.file : part;
   const fileData = file.file_data;
@@ -143,7 +143,7 @@ function fileFromPart(part: Rec): Rec | null {
  * Only representable plaintext is read. No signature, encrypted payload or
  * provider-issued item id is reconstructed — see the reasoning item built below.
  */
-function assistantReasoningText(msg: Rec): string | undefined {
+export function assistantReasoningText(msg: Rec): string | undefined {
   if (typeof msg.reasoning_content === "string" && msg.reasoning_content.length > 0) {
     return msg.reasoning_content;
   }
@@ -601,6 +601,32 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
     ...(legacyFunctionsToResponses(raw.functions) ?? []),
   ];
   if (tools.length > 0) body.tools = tools;
+  applyChatSettings(raw, body);
+  return body;
+}
+
+/**
+ * The request settings of a Chat body as a Responses body with no conversation: `input` is
+ * empty and there are no `instructions` or `tools`. The Antigravity direct lane hands this to
+ * the Responses core so routing, effort policy, tier and logging keep reading the fields they
+ * read today, while the conversation is decoded straight into the IR
+ * (`src/protocols/codecs/chat-ir.ts`). Field order and validation are the bridge body's own:
+ * both are built by `applyChatSettings`.
+ */
+export function chatSettingsToResponsesBody(raw: unknown): Rec {
+  assertChatCompletionsRoutingBody(raw);
+  const body: Rec = {
+    model: raw.model,
+    input: [],
+    stream: raw.stream === true,
+    store: false,
+  };
+  applyChatSettings(raw, body);
+  return body;
+}
+
+/** Everything after the conversation and tool catalog: choice, limits, sampling, reasoning, format. */
+function applyChatSettings(raw: ChatCompletionsRoutingBody, body: Rec): void {
   if (raw.tool_choice !== undefined) toolChoiceToResponses(raw.tool_choice, body);
   else legacyFunctionChoiceToResponses(raw.function_call, body);
 
@@ -637,6 +663,4 @@ export function chatCompletionsToResponsesBody(raw: unknown): Rec {
 
   const text = responseFormatToText(raw.response_format);
   if (text) body.text = text;
-
-  return body;
 }

package/src/chat/outbound.ts

@@ -19,6 +19,7 @@ import {
   CYBER_POLICY_ERROR_CODE,
   isCyberPolicyCode,
   isCyberPolicyMessage,
+  UNDECLARED_TOOL_CALL_ERROR_CODE,
 } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
 import { createSseBlockBuffer, sseDataPayload } from "../server/sse-payload-rewrite";
@@ -196,6 +197,10 @@ export function chatCompletionsStreamErrorPayload(
   } else if (isCyberPolicyCode(details?.code) || classified.code === CYBER_POLICY_ERROR_CODE) {
     classified.code = CYBER_POLICY_ERROR_CODE;
     classified.type = cyberPolicyErrorType(details?.type);
+  } else if (details?.code === UNDECLARED_TOOL_CALL_ERROR_CODE) {
+    // The guard's deterministic refusal keeps its wire identity past classifyError's
+    // generic 5xx remap — same code the buffered Chat error and the SSE frame carry.
+    classified.code = UNDECLARED_TOOL_CALL_ERROR_CODE;
   } else if (details?.code !== undefined && details.code !== null && !classified.code) {
     classified.code = details.code;
   }

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

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync } 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";
@@ -44,9 +44,60 @@ export interface Desktop3pMetadata {
 
 export const DESKTOP_PICKER_ENTRY_NAME = "opencodex-picker";
 
+/** A path that no longer names the observed file was swapped; a same-path failure keeps its own errno. */
+function pathStillNamesExpectedFile(path: string, expected: BigIntStats): boolean {
+  try {
+    const now = lstatSync(path, { bigint: true });
+    return now.isFile() && now.dev === expected.dev && now.ino === expected.ino
+      && now.ctimeNs === expected.ctimeNs;
+  } catch { return false; }
+}
+
+/** Read regular config files only; a path swap must not turn an observation into a FIFO wait. */
+export function readDesktopLibraryBytes(path: string): Buffer {
+  const expected = lstatSync(path, { bigint: true });
+  if (!expected.isFile()) throw new Error("desktop_config_not_regular");
+  // POSIX open of a FIFO can itself block, before fstat is possible. Windows has no POSIX
+  // FIFO entry; retain descriptor identity validation there without unsupported open flags.
+  const flags = constants.O_RDONLY | (process.platform === "win32" ? 0 : constants.O_NONBLOCK | constants.O_NOFOLLOW);
+  let fd: number;
+  try {
+    fd = openSync(path, flags);
+  } catch (error) {
+    // A swap can fail at open — ELOOP on a symlink, ENXIO on a socket — before fstat can
+    // classify it. Re-observing the path reports every swap as the documented refusal.
+    if (pathStillNamesExpectedFile(path, expected)) throw error;
+    throw new Error("desktop_config_not_regular");
+  }
+  try {
+    const opened = fstatSync(fd, { bigint: true });
+    if (!opened.isFile() || opened.dev !== expected.dev || opened.ino !== expected.ino
+      || opened.ctimeNs !== expected.ctimeNs) throw new Error("desktop_config_not_regular");
+    return readFileSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Text decoding stays identical to node:fs readFileSync(path, "utf8"). */
+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(readFileSync(path, "utf8")) 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 };
 }
@@ -80,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(readFileSync(path, "utf8")) 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,21 +5,23 @@ import { applyRemoteDesktopStore, inspectRemoteDesktopCleanup, restoreRemoteDesk
 import { canonicalDirectory } from "./desktop-remote-store-io";
 import {
   resolveDesktop3pConfigLibraryPath, parseMetadata, SAFE_DESKTOP_PROFILE_ID, isRecord,
-  isOwnedDesktopEntry, isOwnedDesktopGatewayEntry, profilePath, readDesktopProfileForeignKeys,
+  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, readFileSync, 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 {
   reconcileDesktopProfile,
   renderDesktopProfile,
   validDateAlias,
+  legacyDesktopProfileWireAlias,
   type DesktopProfileModel,
 } from "./desktop-profile";
 import { nativeOpenAiContextWindow, type NativeContextLimitsInput } from "../codex/catalog";
@@ -223,7 +225,7 @@ function collectDesktop3pModels(
         ...(model.supports1m ? { supports1m: true, prefer1m: true } : {}),
       });
     }
-    // Hash aliases from both pre-profile generations are compatibility-only and can
+    // Previous profile IDs and both hash generations are compatibility-only and can
     // collide. Bind them in stable route order so changing a family default or
     // rendered ordering can never silently rebind an old Desktop id.
     for (const model of [...rendered].sort((a, b) => a.route.localeCompare(b.route))) {
@@ -231,7 +233,8 @@ function collectDesktop3pModels(
       const providerEnd = model.route.indexOf("/");
       const provider = model.route.slice(0, providerEnd);
       const id = model.route.slice(providerEnd + 1);
-      for (const legacy of [desktop3pAlias(provider, id), legacyDesktop3pAlias(provider, id)]) {
+      const storedAlias = reconciled.assignments[model.route]!.alias;
+      for (const legacy of [legacyDesktopProfileWireAlias(storedAlias), desktop3pAlias(provider, id), legacyDesktop3pAlias(provider, id)]) {
         if (realAnthropicIds.has(legacy)) {
           console.warn(`[opencodex] Claude Desktop legacy alias ${legacy} for ${model.route} conflicts with a real Anthropic model; ignoring the alias`);
           continue;
@@ -360,6 +363,11 @@ export function isKnownDesktop3pModelId(id: string): boolean {
   return desktop3pRegistry.has(id) || desktop3pRealAnthropicIds.has(id);
 }
 
+/** Real catalog IDs retain identity even when their spelling resembles an alias. */
+export function isRealDesktop3pModelId(id: string): boolean {
+  return desktop3pRealAnthropicIds.has(id);
+}
+
 /** Only missing IDs in the emitted Desktop namespaces are managed-alias errors. */
 export function isUnresolvedDesktop3pAlias(id: string): boolean {
   if (isKnownDesktop3pModelId(id)) return false;
@@ -369,7 +377,7 @@ export function isUnresolvedDesktop3pAlias(id: string): boolean {
   if (isKnownDesktop3pModelId(base)) return false;
   return validDateAlias(base)
     || /^claude-opus-4-(?:8-)?[a-z][a-z0-9]{2}$/.test(base)
-    || /^claude-opus-4-8-p[0-9a-z]{3}$/.test(base);
+    || /^claude-(?:opus-4-8|fable-5)-p[0-9a-z]{3}$/.test(base);
 }
 
 /** Alias selected by the installed profile registry, falling back to the legacy hash shape. */
@@ -377,6 +385,13 @@ export function activeDesktop3pAlias(provider: string, modelId: string): string
   return desktop3pAliasesByRoute.get(`${provider}/${modelId}`) ?? desktop3pAlias(provider, modelId);
 }
 
+/** Discovery cannot offer a skipped alias or one owned by a different route. */
+export function resolvableDesktop3pAlias(provider: string, modelId: string): string | undefined {
+  if (provider === "anthropic" && modelId.startsWith("claude-")) return modelId;
+  const alias = activeDesktop3pAlias(provider, modelId);
+  return resolveDesktop3pAlias(alias) === `${provider}/${modelId}` ? alias : undefined;
+}
+
 /**
  * Generate the complete Claude Desktop 3P gateway config.
  *
@@ -476,7 +491,7 @@ export function inspectDesktop3pConfigLibrary(
   let profile: Record<string, unknown>;
   let fingerprint: string;
   try {
-    const source = readFileSync(selectedProfilePath, "utf8");
+    const source = readDesktopLibraryText(selectedProfilePath);
     const parsed = JSON.parse(source) as unknown;
     if (!isRecord(parsed)) return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
     profile = parsed;
@@ -709,7 +724,7 @@ export function writeDesktop3pConfig(
         const metadata = parseMetadata(join(inspected.libraryPath, "_meta.json"));
         if (!isOwnedDesktopGatewayEntry(metadata.entries.find(entry => entry.id === inspected.appliedId))) return refused;
         try {
-          const selected = JSON.parse(readFileSync(inspected.selectedProfilePath, "utf8")) as Record<string, unknown>;
+          const selected = JSON.parse(readDesktopLibraryText(inspected.selectedProfilePath)) as Record<string, unknown>;
           mode = selected.modelDiscoveryEnabled !== true ? "static"
             : Array.isArray(selected.inferenceModels) ? "hybrid" : "discovery";
         } catch { return refused; }
@@ -786,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 },
@@ -814,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, {
@@ -825,7 +841,7 @@ function writeDesktop3pConfigWithGenerator(
             const freshMetadata = parseMetadata(metadataPath);
             if (freshMetadata.appliedId !== refreshOnly.requiredId
               || !isOwnedDesktopGatewayEntry(freshMetadata.entries.find(entry => entry.id === refreshOnly.requiredId))
-              || createHash("sha256").update(readFileSync(configPath)).digest("hex").slice(0, 16) !== refreshOnly.expectedFingerprint) {
+              || createHash("sha256").update(readDesktopLibraryBytes(configPath)).digest("hex").slice(0, 16) !== refreshOnly.expectedFingerprint) {
               throw new Error();
             }
           } catch { throw new Error("desktop_refresh_only_skipped"); }
@@ -833,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 };
@@ -848,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";
+}