@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/claude/intercept/picker-listener.ts

@@ -34,6 +34,11 @@ export interface PickerListenerOptions {
   maxEncodedBytes?: number;
   /** Test seam: concurrent upstream requests; production uses PICKER_MAX_ACTIVE_UPSTREAMS. */
   maxActiveUpstreams?: number;
+  /**
+   * Test seam: arms the drop of a connection whose backend ended, after PICKER_ABANDONED_INPUT_LINGER_MS;
+   * returns a cancel function. Production uses a timer.
+   */
+  scheduleAbandonedInputDrop?: (drop: () => void, ms: number) => () => void;
   log?: (line: string) => void;
 }
 export interface PickerListenerHandle { port: number; close(): Promise<void> }
@@ -51,6 +56,12 @@ export const PICKER_MAX_ACTIVE_UPSTREAMS = 256;
 export const PICKER_MAX_CONCURRENT_STREAMS = 100;
 /** A connection that has not sent a complete ClientHello by then is dropped. */
 const CLIENT_HELLO_TIMEOUT_MS = 10_000;
+/**
+ * Once the backend has ended a connection and its reply has been flushed, input the client still
+ * sends is discarded for at most this long before the connection is dropped. A cooperative client
+ * closes as soon as it reads a Connection: close reply; this only bounds one that keeps uploading.
+ */
+export const PICKER_ABANDONED_INPUT_LINGER_MS = 30_000;
 
 const HOP_HEADERS = new Set([
   "connection", "keep-alive", "proxy-connection", "proxy-authenticate", "proxy-authorization",
@@ -152,6 +163,10 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
   const upstream = options.upstream ?? { host: "claude.ai", port: 443, servername: "claude.ai" };
   const cap = options.maxEncodedBytes ?? BOOTSTRAP_MAX_ENCODED_BYTES;
   const maxActiveUpstreams = options.maxActiveUpstreams ?? PICKER_MAX_ACTIVE_UPSTREAMS;
+  const scheduleAbandonedInputDrop = options.scheduleAbandonedInputDrop ?? ((drop: () => void, ms: number) => {
+    const timer = setTimeout(drop, ms);
+    return () => clearTimeout(timer);
+  });
   let activeUpstreams = 0;
   const upgrades = new Set<Duplex>();
   const spliced = new Set<Socket>();
@@ -205,8 +220,18 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
         } else req.destroy();
       }
     };
+    // An HTTP/1.1 reply sent while the upload is unfinished advertises Connection: close. Bun 1.4.3
+    // ends such a response with socket.destroySoon() before our finish listeners run, which resets
+    // the splice before the reply reaches the client; keep it a graceful FIN that discards input.
+    // Only that closing socket is changed, and destroy() stays available for errors and shutdown.
+    const closesUnfinishedUpload = () => !h2 && uploading && !req.complete;
+    const keepClosingReplyIntact = () => {
+      const socket = req.socket;
+      socket.destroySoon = () => { req.resume(); socket.end(); return socket; };
+    };
     // Refusals answer with an empty response and a fixed log line that carries no request data.
     const refuse = (status: 400 | 503) => {
+      if (closesUnfinishedUpload()) keepClosingReplyIntact();
       // Do not leave a refused, still-uploading stream behind after delivering its empty reply.
       if (uploading && !req.complete) {
         req.once("error", () => res.destroy());
@@ -236,6 +261,7 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
       if (clientGone) return;
       if (res.headersSent) res.destroy();
       else {
+        if (closesUnfinishedUpload()) keepClosingReplyIntact();
         res.writeHead(502, { "Content-Length": "0", ...(!h2 && uploading && !req.complete ? { Connection: "close" } : {}) });
         res.end(); log(502);
       }
@@ -260,7 +286,10 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
           // HTTP/2 has no reason phrase; its compat writeHead takes the same flat raw header array.
           if (h2) (relayRes as Http2ServerResponse).writeHead(status, raw as unknown as Record<string, string>);
           else {
-            if (uploading && !req.complete) raw.push("Connection", "close");
+            if (uploading && !req.complete) {
+              keepClosingReplyIntact();
+              raw.push("Connection", "close");
+            }
             res.writeHead(status, upRes.statusMessage, raw);
           }
           log(status);
@@ -438,6 +467,8 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
       const offersH2 = clientHelloOffersH2(head);
       if (offersH2 === null) return;
       client.off("data", onData);
+      // Keep reading an aborted upload after the backend reply FIN.
+      client.allowHalfOpen = true;
       // Paused, a FIN or later bytes wait in the readable buffer and follow `head` once piped.
       client.pause();
       clearTimeout(deadline);
@@ -450,6 +481,23 @@ export async function startPickerListener(options: PickerListenerOptions): Promi
       // its peer (reset, dial failure) tears the peer down instead of leaving it open.
       inner.once("close", () => { spliced.delete(inner); if (!client.writableEnded) client.destroy(); });
       client.once("close", () => { if (!inner.writableEnded) inner.destroy(); });
+      // The backend reply ended; discard ciphertext still coming from the aborted upload.
+      // Unpipe before resuming, so backpressure cannot hide the peer FIN. The discard is bounded
+      // from the moment the reply has been flushed to the socket (finish), never before, so the
+      // drop cannot cut a reply still being written; finish is not peer receipt, so a peer that
+      // also stops reading for the whole budget can lose unread bytes. A peer that keeps sending
+      // past the budget is dropped instead of holding the connection until shutdown (#6984).
+      inner.once("end", () => {
+        client.unpipe(inner);
+        client.resume();
+        const linger = () => {
+          if (client.destroyed) return;
+          const cancel = scheduleAbandonedInputDrop(() => client.destroy(), PICKER_ABANDONED_INPUT_LINGER_MS);
+          client.once("close", cancel);
+        };
+        if (client.writableFinished) linger();
+        else client.once("finish", linger);
+      });
       inner.once("connect", () => {
         inner.setNoDelay(true);
         client.setNoDelay(true);

package/src/claude/intercept/settings-no-proxy.ts

@@ -0,0 +1,146 @@
+import { readFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFile } from "../../config/atomic-write";
+import { assertNotRealClaudeConfigUnderTest } from "../../lib/test-home-guard";
+
+/**
+ * The loopback bypass opencodex keeps in Claude Code's settings env (#6936), and the receipt
+ * that proves which part of `NO_PROXY` opencodex wrote.
+ *
+ * `NO_PROXY` is shared with the user, so a value alone cannot say which entries are ours. Apply
+ * records `{ hadKey, previous, written }` in `<claudeConfigDir>/opencodex-no-proxy.json` and
+ * removal restores `previous` only while `NO_PROXY` still equals `written`; anything else is
+ * preserved. The receipt lives exactly as long as the ownership episode that wrote it: an apply
+ * that starts a new episode, and every removal, invalidates it first and fails closed when it
+ * cannot. It holds only `NO_PROXY` values, never the proxy token.
+ */
+
+/**
+ * Local hosts Claude Code must reach directly, in the order opencodex appends them. The proxy
+ * refuses every loopback and unspecified target (connect-proxy.ts isLoopbackTarget); these are the
+ * forms a NO_PROXY entry can name. `localhost` also covers `*.localhost` because Claude Code's
+ * client suffix-matches entries. Other 127/8 addresses cannot be listed (NO_PROXY has no CIDR) and
+ * need their own entry; the proxy's 405 body says so.
+ */
+export const CLAUDE_INTERCEPT_LOOPBACK_NO_PROXY = ["127.0.0.1", "localhost", "::1", "0.0.0.0"] as const;
+
+export const NO_PROXY_RECEIPT_FILE = "opencodex-no-proxy.json";
+
+export interface NoProxyReceipt {
+  version: 1;
+  /** Whether settings env held a NO_PROXY key before the apply. */
+  hadKey: boolean;
+  /** The value before the apply (null when the key was absent or held null). */
+  previous: string | null;
+  /** The value the apply wrote. */
+  written: string;
+}
+
+/** Canonical index of a loopback bypass entry, or -1. `[::1]` is the bracketed form of `::1`. */
+function loopbackEntryIndex(entry: string): number {
+  const normalized = entry.trim().toLowerCase();
+  return CLAUDE_INTERCEPT_LOOPBACK_NO_PROXY.indexOf(
+    (normalized === "[::1]" ? "::1" : normalized) as typeof CLAUDE_INTERCEPT_LOOPBACK_NO_PROXY[number],
+  );
+}
+
+function noProxyEntries(value: string): string[] {
+  return value.split(/[,\s]+/).filter(entry => entry.length > 0);
+}
+
+/** True when the value already sends every loopback host around the proxy. */
+export function noProxyCoversLoopback(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const entries = noProxyEntries(value);
+  if (entries.includes("*")) return true;
+  const present = new Set(entries.map(loopbackEntryIndex));
+  return CLAUDE_INTERCEPT_LOOPBACK_NO_PROXY.every((_, index) => present.has(index));
+}
+
+/** A NO_PROXY value opencodex can extend: absent, null, or a string. */
+export function noProxyMergeable(value: unknown): boolean {
+  return value === undefined || value === null || typeof value === "string";
+}
+
+/**
+ * The NO_PROXY value apply writes, or null when nothing needs writing: the value already covers
+ * loopback, or it is not one opencodex can extend.
+ */
+export function mergeClaudeInterceptNoProxy(current: unknown): string | null {
+  if (!noProxyMergeable(current) || noProxyCoversLoopback(current)) return null;
+  const base = typeof current === "string" ? current : "";
+  const present = new Set(noProxyEntries(base).map(loopbackEntryIndex));
+  const missing = CLAUDE_INTERCEPT_LOOPBACK_NO_PROXY.filter((_, index) => !present.has(index));
+  const trimmed = base.replace(/[,\s]+$/, "");
+  return trimmed.length === 0 ? missing.join(",") : `${trimmed},${missing.join(",")}`;
+}
+
+export function noProxyReceiptPath(configDir: string): string {
+  return join(configDir, NO_PROXY_RECEIPT_FILE);
+}
+
+interface ReceiptIo {
+  write(path: string, content: string): void;
+  unlink(path: string): void;
+}
+
+const defaultReceiptIo: ReceiptIo = {
+  write: (path, content) => atomicWriteFile(path, content),
+  unlink: path => unlinkSync(path),
+};
+let receiptIo: ReceiptIo = defaultReceiptIo;
+
+/** Replace receipt write/unlink in tests; the real-home guard still runs. Returns a restore. */
+export function setNoProxyReceiptIoForTests(io: Partial<ReceiptIo>): () => void {
+  const before = receiptIo;
+  receiptIo = { ...defaultReceiptIo, ...io };
+  return () => { receiptIo = before; };
+}
+
+/** The receipt, or null when it is missing or malformed (both mean: no provenance). */
+export function readNoProxyReceipt(configDir: string): NoProxyReceipt | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(noProxyReceiptPath(configDir), "utf8"));
+  } catch { // no-excuse-ok: catch -- a missing or corrupt receipt is the no-provenance state.
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const receipt = parsed as Record<string, unknown>;
+  if (receipt.version !== 1 || typeof receipt.hadKey !== "boolean" || typeof receipt.written !== "string") return null;
+  if (receipt.previous !== null && typeof receipt.previous !== "string") return null;
+  return { version: 1, hadKey: receipt.hadKey, previous: receipt.previous, written: receipt.written };
+}
+
+/** Raw receipt bytes for rollback capture, or null when there is no readable file. */
+export function readNoProxyReceiptBytes(configDir: string): string | null {
+  try {
+    return readFileSync(noProxyReceiptPath(configDir), "utf8");
+  } catch { // no-excuse-ok: catch -- an unreadable receipt is captured as absent.
+    return null;
+  }
+}
+
+/** Delete the receipt. Returns false when it exists but could not be removed. */
+export function invalidateNoProxyReceipt(configDir: string): boolean {
+  const path = noProxyReceiptPath(configDir);
+  // Guard first and outside the catch, so a refusal is visible and nothing is touched.
+  assertNotRealClaudeConfigUnderTest(configDir, path);
+  try {
+    receiptIo.unlink(path);
+    return true;
+  } catch (error) { // no-excuse-ok: catch -- ENOENT is success; anything else is reported to the caller.
+    return (error as NodeJS.ErrnoException).code === "ENOENT";
+  }
+}
+
+/** Write raw receipt bytes. Throws on failure; callers decide whether that is fatal. */
+export function writeNoProxyReceiptBytes(configDir: string, content: string): void {
+  const path = noProxyReceiptPath(configDir);
+  assertNotRealClaudeConfigUnderTest(configDir, path);
+  receiptIo.write(path, content);
+}
+
+export function serializeNoProxyReceipt(receipt: NoProxyReceipt): string {
+  return `${JSON.stringify(receipt, null, 2)}\n`;
+}

package/src/claude/intercept/settings.ts

@@ -4,6 +4,19 @@ import { atomicWriteFile } from "../../config/atomic-write";
 import { assertNotRealClaudeConfigUnderTest } from "../../lib/test-home-guard";
 import { claudeConfigDir } from "../auth-detect";
 import { invalidateClaudeCodeServedCatalog } from "./cli-catalog";
+import {
+  invalidateNoProxyReceipt,
+  mergeClaudeInterceptNoProxy,
+  noProxyCoversLoopback,
+  noProxyMergeable,
+  noProxyReceiptPath,
+  readNoProxyReceipt,
+  readNoProxyReceiptBytes,
+  serializeNoProxyReceipt,
+  writeNoProxyReceiptBytes,
+} from "./settings-no-proxy";
+
+export { CLAUDE_INTERCEPT_LOOPBACK_NO_PROXY, mergeClaudeInterceptNoProxy } from "./settings-no-proxy";
 
 /**
  * Claude Code `settings.json` env block for intercept mode.
@@ -16,9 +29,21 @@ import { invalidateClaudeCodeServedCatalog } from "./cli-catalog";
  *   env.HTTPS_PROXY         = http://opencodex:<token>@127.0.0.1:<proxy port>
  *   env.NODE_EXTRA_CA_CERTS = <configDir>/claude-intercept/ca.pem
  *
+ * A third key keeps loopback off that proxy. Claude Code otherwise sends local HTTP MCP traffic
+ * (`POST http://127.0.0.1:<port>/mcp`) through it, and the proxy only tunnels CONNECT to
+ * non-loopback hosts, so every loopback MCP server failed with a 405 (#6936):
+ *
+ *   env.NO_PROXY            = <user entries>,127.0.0.1,localhost,::1,0.0.0.0
+ *
  * Ownership is tracked by value, never by a marker key. The CA path is the anchor: it lives
  * under opencodex's own config directory, so only a block whose `NODE_EXTRA_CA_CERTS` names
  * that file is treated as ours. A user's own proxy or CA setting is left alone.
+ *
+ * `NO_PROXY` is shared with the user. Apply appends only the missing loopback entries and leaves
+ * a covering value (including `*`) alone; removal puts back exactly what was there before, using
+ * the receipt described in ./settings-no-proxy.ts, and otherwise preserves the current value.
+ * A non-string `NO_PROXY` other than null is not one opencodex can extend: the block stays stale
+ * and apply refuses with `foreign_env` instead of rewriting it.
  */
 
 export const CLAUDE_INTERCEPT_MANAGED_ENV = ["HTTPS_PROXY", "NODE_EXTRA_CA_CERTS"] as const;
@@ -79,6 +104,11 @@ function isOwnedCaPath(value: unknown, ownedCaPath: string): value is string {
   return typeof value === "string" && value.trim() === ownedCaPath;
 }
 
+function setOrDelete(env: Record<string, unknown>, key: string, value: unknown): void {
+  if (value === undefined) delete env[key];
+  else env[key] = value;
+}
+
 /** Classify the current settings env against the values this router would write. */
 export function inspectClaudeInterceptSettings(
   expected: ClaudeInterceptEnv,
@@ -91,7 +121,11 @@ export function inspectClaudeInterceptSettings(
   const proxy = env.HTTPS_PROXY;
   const ca = env.NODE_EXTRA_CA_CERTS;
   if (proxy === undefined && ca === undefined) return { kind: "absent" };
-  if (proxy === expected.HTTPS_PROXY && ca === expected.NODE_EXTRA_CA_CERTS) return { kind: "applied", env: expected };
+  // An owned block that still routes loopback into the proxy is stale, so the startup migrate
+  // and every reconcile repair installs written before the bypass existed.
+  if (proxy === expected.HTTPS_PROXY && ca === expected.NODE_EXTRA_CA_CERTS && noProxyCoversLoopback(env.NO_PROXY)) {
+    return { kind: "applied", env: expected };
+  }
   const caOurs = isOwnedCaPath(ca, expected.NODE_EXTRA_CA_CERTS);
   const proxyOurs = proxy === undefined || isClaudeInterceptProxyUrl(proxy);
   if (caOurs && proxyOurs) {
@@ -112,13 +146,28 @@ export function inspectClaudeInterceptSettings(
   };
 }
 
-function writeSettings(path: string, doc: SettingsDoc): void {
+const defaultPersist = (path: string, content: string): void => atomicWriteFile(path, content);
+let persistFile = defaultPersist;
+
+/** Replace the settings.json write in tests; the real-home guard still runs first. Returns a restore. */
+export function setClaudeSettingsPersistForTests(persist: (path: string, content: string) => void): () => void {
+  const before = persistFile;
+  persistFile = persist;
+  return () => { persistFile = before; };
+}
+
+/** Commit settings.json. Once this returns, the file on disk holds the new document. */
+function persistSettings(path: string, doc: SettingsDoc): void {
   // An armed test process must not rewrite the real Claude settings.json (#6775).
   assertNotRealClaudeConfigUnderTest(dirname(path), path);
   mkdirSync(dirname(path), { recursive: true });
   // The managed env embeds the proxy token, so the file must stay owner-only:
   // atomicWriteFile applies the real NTFS ACL on Windows where chmod is a no-op.
-  atomicWriteFile(path, `${JSON.stringify(doc, null, 2)}\n`);
+  persistFile(path, `${JSON.stringify(doc, null, 2)}\n`);
+}
+
+function writeSettings(path: string, doc: SettingsDoc): void {
+  persistSettings(path, doc);
   // Whether Claude Code reaches the proxy just changed, so its cached /model list is stale.
   invalidateClaudeCodeServedCatalog(dirname(path));
 }
@@ -137,20 +186,31 @@ export function captureClaudeInterceptSettingsRollback(
   const before = readSettings(path);
   if ("error" in before && before.error !== "missing") return () => false;
   const previous = "doc" in before ? { ...envRecord(before.doc) } : {};
+  const previousReceipt = readNoProxyReceiptBytes(configDir);
+  // What apply writes over the captured value; rollback restores NO_PROXY only while it still
+  // holds exactly that, so a user edit made after the apply survives. The receipt is restored
+  // with it, because it describes that value.
+  const appliedNoProxy = mergeClaudeInterceptNoProxy(previous.NO_PROXY) ?? previous.NO_PROXY;
   return () => {
     try {
+      assertNotRealClaudeConfigUnderTest(configDir, path, noProxyReceiptPath(configDir));
       const target = typeof expected === "function" ? expected() : expected;
       const current = readSettings(path);
       if (!("doc" in current)) return false;
       const env = envRecord(current.doc);
       if (CLAUDE_INTERCEPT_MANAGED_ENV.some(key => env[key] !== target[key])) return false;
       for (const key of CLAUDE_INTERCEPT_MANAGED_ENV) {
-        if (previous[key] === undefined) delete env[key];
-        else env[key] = previous[key];
+        setOrDelete(env, key, previous[key]);
       }
+      const restoreNoProxy = env.NO_PROXY === appliedNoProxy;
+      if (restoreNoProxy) setOrDelete(env, "NO_PROXY", previous.NO_PROXY);
       if (Object.keys(env).length === 0) delete current.doc.env;
       else current.doc.env = env;
       writeSettings(path, current.doc);
+      if (restoreNoProxy) {
+        if (previousReceipt === null) return invalidateNoProxyReceipt(configDir);
+        writeNoProxyReceiptBytes(configDir, previousReceipt);
+      }
       return true;
     } catch { return false; }
   };
@@ -158,7 +218,8 @@ export function captureClaudeInterceptSettingsRollback(
 
 /**
  * Write the intercept env into `settings.json`. Refuses when a managed key already holds a
- * value opencodex did not write (a user-configured corporate proxy, for instance).
+ * value opencodex did not write (a user-configured corporate proxy, for instance), or when
+ * NO_PROXY holds a non-string value opencodex cannot extend.
  */
 export function applyClaudeInterceptSettings(
   env: ClaudeInterceptEnv,
@@ -171,8 +232,21 @@ export function applyClaudeInterceptSettings(
   if (state.kind === "applied") return { ok: true, changed: false, path };
   const read = readSettings(path);
   const doc: SettingsDoc = "doc" in read ? read.doc : {};
-  doc.env = { ...envRecord(doc), ...env };
+  const current = envRecord(doc);
+  if (!noProxyMergeable(current.NO_PROXY)) return { ok: false, reason: "foreign_env", path };
+  const noProxy = mergeClaudeInterceptNoProxy(current.NO_PROXY);
+  // A new ownership episode, or a new NO_PROXY value, makes any existing receipt describe the
+  // wrong value. Drop it before writing, and write nothing when it cannot be dropped.
+  if ((state.kind === "absent" || noProxy !== null) && !invalidateNoProxyReceipt(configDir)) {
+    return { ok: false, reason: "unreadable", path: noProxyReceiptPath(configDir) };
+  }
+  doc.env = { ...current, ...env, ...(noProxy === null ? {} : { NO_PROXY: noProxy }) };
   writeSettings(path, doc);
+  if (noProxy !== null) {
+    const receipt = { version: 1 as const, hadKey: "NO_PROXY" in current, previous: typeof current.NO_PROXY === "string" ? current.NO_PROXY : null, written: noProxy };
+    // Without a receipt, removal keeps the appended entries: the harmless direction.
+    try { writeNoProxyReceiptBytes(configDir, serializeNoProxyReceipt(receipt)); } catch { /* no provenance */ }
+  }
   return { ok: true, changed: true, path };
 }
 
@@ -195,7 +269,11 @@ export function migrateClaudeInterceptSettings(
   return applyClaudeInterceptSettings(env, configDir);
 }
 
-/** Remove the managed keys, but only the values opencodex owns. */
+/**
+ * Remove the managed keys and put NO_PROXY back as it was, but only the values opencodex owns.
+ * The receipt is dropped before the settings write; when that fails nothing is changed, so a
+ * receipt can never outlive the episode it describes.
+ */
 export function removeClaudeInterceptSettings(
   ownedCaPath: string,
   configDir = claudeConfigDir(),
@@ -207,10 +285,24 @@ export function removeClaudeInterceptSettings(
   }
   const env = envRecord(read.doc);
   if (!isOwnedCaPath(env.NODE_EXTRA_CA_CERTS, ownedCaPath)) return { ok: true, changed: false, path };
+  const receipt = readNoProxyReceipt(configDir);
+  const receiptBytes = readNoProxyReceiptBytes(configDir);
   delete env.NODE_EXTRA_CA_CERTS;
   if (isClaudeInterceptProxyUrl(env.HTTPS_PROXY)) delete env.HTTPS_PROXY;
+  if (receipt && env.NO_PROXY === receipt.written) setOrDelete(env, "NO_PROXY", receipt.hadKey ? receipt.previous : undefined);
+  if (!invalidateNoProxyReceipt(configDir)) return { ok: false, reason: "unreadable", path: noProxyReceiptPath(configDir) };
   if (Object.keys(env).length === 0) delete read.doc.env;
   else read.doc.env = env;
-  writeSettings(path, read.doc);
+  try {
+    persistSettings(path, read.doc);
+  } catch (error) {
+    // A removal that was not committed has not ended the episode, so its receipt stays valid. Only the
+    // persist step is covered: once settings.json changed, the receipt must not come back.
+    if (receiptBytes !== null) {
+      try { writeNoProxyReceiptBytes(configDir, receiptBytes); } catch { /* keep the original error */ }
+    }
+    throw error;
+  }
+  invalidateClaudeCodeServedCatalog(dirname(path));
   return { ok: true, changed: true, path };
 }

package/src/claude/model-default-settings.ts

@@ -0,0 +1,154 @@
+import { createHash, randomUUID } from "node:crypto";
+import { linkSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, renameSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteFileNoFollow } from "../config/atomic-write";
+import { hardenSecretDir, hardenSecretPath } from "../lib/windows-secret-acl";
+import { assertNotRealClaudeConfigUnderTest } from "../lib/test-home-guard";
+import { claudeConfigDir } from "./auth-detect";
+import { claudeTierDisplayName, type ClaudeTierModels } from "./context-windows";
+
+const tiers = ["opus", "sonnet", "haiku", "fable"] as const;
+
+function readSettings(path: string): { raw: string; exists: boolean; doc: Record<string, unknown>; env: Record<string, unknown> } {
+  let raw = "";
+  let exists = false;
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024) throw new Error("settings_unreadable");
+    raw = readFileSync(path, "utf8");
+    exists = true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw new Error("settings_unreadable");
+  }
+  let doc: Record<string, unknown>;
+  try {
+    const parsed: unknown = exists ? JSON.parse(raw) : {};
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error();
+    doc = parsed as Record<string, unknown>;
+    if (doc.env !== undefined && (!doc.env || typeof doc.env !== "object" || Array.isArray(doc.env))) throw new Error();
+  } catch { throw new Error("settings_unreadable"); }
+  return { raw, exists, doc, env: (doc.env ?? {}) as Record<string, unknown> };
+}
+
+function snapshotFingerprint(current: ReturnType<typeof readSettings>, models: ClaudeTierModels | undefined) {
+  const target = selectedEnv(models, current.env);
+  return createHash("sha256").update(JSON.stringify([current.exists, current.raw, target])).digest("hex");
+}
+
+/** Test seams for edits at publication boundaries; never configured through the API. */
+export interface ModelDefaultWriteHooks {
+  beforeCapture?: () => void;
+  beforePublish?: () => void;
+}
+
+export class ModelDefaultsRecoveryError extends Error {
+  constructor(readonly backupPath: string, options?: ErrorOptions) {
+    super("settings_recovery_required", options);
+  }
+}
+
+/** Unset tiers stay untouched; only a label matching its current alias is managed. */
+function selectedEnv(models: ClaudeTierModels | undefined, current: Record<string, unknown>): Record<string, string | null> {
+  const env: Record<string, string | null> = {};
+  for (const tier of tiers) {
+    const slot = `ANTHROPIC_DEFAULT_${tier.toUpperCase()}_MODEL`;
+    const name = `${slot}_NAME`;
+    const value = models?.[tier]?.trim();
+    if (!value) continue;
+    env[slot] = value;
+    const previous = typeof current[slot] === "string" ? claudeTierDisplayName(current[slot]) : undefined;
+    const managed = previous !== undefined && current[name] === previous;
+    // Custom (including empty/non-string) labels are user-owned. Exact pairing
+    // follows the launcher label convention; the name alone proves no ownership.
+    if (!Object.hasOwn(current, name) || managed) {
+      const label = claudeTierDisplayName(value);
+      if (label !== undefined) env[name] = label;
+      else if (managed) env[name] = null;
+    }
+  }
+  return env;
+}
+
+export function previewClaudeModelDefaults(models: ClaudeTierModels | undefined, configDir = claudeConfigDir()) {
+  const path = join(configDir, "settings.json");
+  const current = readSettings(path);
+  const target = selectedEnv(models, current.env);
+  const changes = Object.entries(target).filter(([key, value]) => current.env[key] !== value)
+    // The existing preview wire shape uses an empty replacement for label removal.
+    .map(([key, value]) => ({ key, before: typeof current.env[key] === "string" ? current.env[key] as string : null, after: value ?? "" }));
+  const fingerprint = snapshotFingerprint(current, models);
+  return { path, fingerprint, changes };
+}
+
+export function applyClaudeModelDefaults(
+  models: ClaudeTierModels | undefined,
+  fingerprint: string,
+  configDir = claudeConfigDir(),
+  backupDir = join(configDir, "model-default-backups"),
+  hooks: ModelDefaultWriteHooks = {},
+) {
+  const preview = previewClaudeModelDefaults(models, configDir);
+  if (preview.fingerprint !== fingerprint) throw new Error("settings_changed");
+  if (!preview.changes.length) return { changed: false, path: preview.path };
+  assertNotRealClaudeConfigUnderTest(configDir, preview.path);
+  const current = readSettings(preview.path);
+  const check = snapshotFingerprint(current, models);
+  if (check !== fingerprint) throw new Error("settings_changed");
+  mkdirSync(configDir, { recursive: true });
+  mkdirSync(backupDir, { recursive: true, mode: 0o700 });
+  const recoveryDir = mkdtempSync(join(backupDir, "apply-"));
+  if (process.platform === "win32") hardenSecretDir(recoveryDir, { required: true });
+  const backupPath = join(recoveryDir, "settings.json");
+  const staged = join(configDir, `.model-defaults-${randomUUID()}.tmp`);
+  let captured = false;
+  let published = false;
+  try {
+    const env = { ...current.env };
+    for (const [key, value] of Object.entries(selectedEnv(models, current.env))) {
+      if (value === null) delete env[key];
+      else env[key] = value;
+    }
+    current.doc.env = env;
+    atomicWriteFileNoFollow(staged, `${JSON.stringify(current.doc, null, 2)}\n`);
+    // Verify same-volume exclusive publication before moving the shared file.
+    const probe = join(recoveryDir, "link-probe");
+    linkSync(staged, probe);
+    unlinkSync(probe);
+    hooks.beforeCapture?.();
+    if (current.exists) {
+      // Move the actual destination, not a stale in-memory copy. A same-filesystem
+      // move captures late edits; cross-device failures leave the original alone.
+      try { renameSync(preview.path, backupPath); } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error("settings_changed");
+        throw error;
+      }
+      captured = true;
+      const capturedEntry = lstatSync(backupPath);
+      if (!capturedEntry.isFile() || capturedEntry.isSymbolicLink()) throw new Error("settings_changed");
+      if (process.platform === "win32") hardenSecretPath(backupPath, { required: true });
+      if (snapshotFingerprint(readSettings(backupPath), models) !== fingerprint) throw new Error("settings_changed");
+    }
+    hooks.beforePublish?.();
+    // A hard-link publish is exclusive on POSIX and Windows: never replace a
+    // document created by another writer during the brief move-aside interval.
+    try { linkSync(staged, preview.path); } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error("settings_changed");
+      throw error;
+    }
+    published = true;
+    return { changed: true, path: preview.path, ...(captured ? { backupPath } : {}) };
+  } catch (error) {
+    if (captured && !published) {
+      try { linkSync(backupPath, preview.path); } catch (restoreError) {
+        // A newer destination wins. Retain the captured document privately;
+        // never delete the winner or overwrite it as an automatic rollback.
+        throw new ModelDefaultsRecoveryError(backupPath, { cause: restoreError });
+      }
+    }
+    throw error;
+  } finally {
+    // The private stage is also present at the destination after successful
+    // linking; cleanup failure must not turn a committed apply into failure.
+    try { unlinkSync(staged); } catch { /* private residue, no shared-file cleanup */ }
+  }
+}

package/src/claude/model-info.ts

@@ -103,19 +103,19 @@ function modelInfo(id: string, displayName: string, ladder: readonly string[], i
 
 /**
  * Which id family the discovery list carries (devlog 050): Claude Code (CLI)
- * gets readable `claude-ocx-*` ids; Claude Desktop keeps the hashed
- * `claude-opus-4-8-<code>` family its 3P config was written with. Both families
+ * gets readable `ocx-claude-*` ids; Claude Desktop keeps its profile's
+ * `claude-fable-5-p<code>` ids (legacy no-profile callers use hash aliases). Both families
  * decode in resolveInboundModel regardless of the style served here.
  */
 export type AnthropicIdStyle = "desktop3p" | "readable";
 
-/** Build the full anthropic-flavor discovery list (ids are Desktop 3P aliases). */
+/** Build discovery rows; a Desktop resolver can return undefined to withhold an unbound ID. */
 export function buildAnthropicModelInfos(
   nativeSlugs: readonly string[],
   routedModels: readonly CatalogModel[],
   auto: AutoContextMode = AUTO_CONTEXT_OFF,
   idStyle: AnthropicIdStyle = "desktop3p",
-  aliasForRoute: (provider: string, modelId: string) => string = desktop3pAlias,
+  aliasForRoute: (provider: string, modelId: string) => string | undefined = desktop3pAlias,
   nativeContextCap?: NativeContextLimitsInput,
   fastMode?: boolean,
   // Presence is the feature gate: the caller passes undefined when `fastRows` is off, so a
@@ -144,7 +144,7 @@ export function buildAnthropicModelInfos(
         ? claudeCodeAlias(m.provider, listed)
         : aliasForRoute(m.provider, m.id);
     }),
-  ]);
+  ].filter((id): id is string => typeof id === "string" && id.length > 0));
   // [1m] picker variant (devlog 260712 B1; widened in devlog/_plan/261009_claude_1m_default/020):
   // Claude Code accounts exactly 1M for ids carrying the marker (2.1.207 binary: /\[1m\]/i -> 1e6,
   // compaction preserved). A discovery client may lack CLAUDE_CODE_AUTO_COMPACT_WINDOW, so the
@@ -201,7 +201,7 @@ export function buildAnthropicModelInfos(
   };
   for (const slug of nativeSlugs) {
     const id = idStyle === "readable" ? claudeCodeNativeAlias(slug) : aliasForRoute("native", slug);
-    if (seen.has(id)) continue;
+    if (!id || seen.has(id)) continue;
     seen.add(id);
     const nativeWindow = nativeOpenAiContextWindow(slug, nativeContextCap);
     const nativeMaxInput = nativeOpenAiMaxInputTokens(slug, nativeContextCap);
@@ -228,7 +228,7 @@ export function buildAnthropicModelInfos(
     const id = idStyle === "readable"
       ? claudeCodeAlias(m.provider, listedModelId)
       : aliasForRoute(m.provider, m.id);
-    if (seen.has(id)) continue;
+    if (!id || seen.has(id)) continue;
     seen.add(id);
     const groupStart = out.length;
     const ladder = Array.isArray(m.reasoningEfforts) ? m.reasoningEfforts : [];