@bitkyc08/opencodex 2.83.0 → 2.84.0

package/src/claude/intercept/connect-proxy.ts

@@ -113,12 +113,19 @@ export function isLoopbackTarget(host: string): boolean {
   return /^(0x[0-9a-f]+|\d+)(\.(0x[0-9a-f]+|\d+))*$/.test(host);
 }
 
-function respond(socket: Socket, status: number, reason: string, headers: Readonly<Record<string, string>> = {}): void {
+function respond(
+  socket: Socket, status: number, reason: string, headers: Readonly<Record<string, string>> = {}, body = "",
+): void {
   if (socket.destroyed) return;
   const extra = Object.entries(headers).map(([name, value]) => `${name}: ${value}\r\n`).join("");
-  socket.end(`HTTP/1.1 ${status} ${reason}\r\n${extra}Connection: close\r\nContent-Length: 0\r\n\r\n`);
+  const type = body ? "Content-Type: text/plain; charset=utf-8\r\n" : "";
+  socket.end(`HTTP/1.1 ${status} ${reason}\r\n${extra}${type}Connection: close\r\nContent-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`);
 }
 
+// Plain proxied HTTP (often loopback MCP traffic missing a NO_PROXY bypass) lands here; say why.
+const CONNECT_ONLY_BODY = "OpenCodex Claude intercept proxy accepts only CONNECT tunnels. "
+  + "Exclude this host via NO_PROXY (loopback and unspecified hosts: 127.0.0.1,localhost,::1,0.0.0.0).\n";
+
 function splice(client: Socket, upstream: Socket, pending: Uint8Array): void {
   const teardown = () => {
     client.destroy();
@@ -173,7 +180,7 @@ function handleConnection(socket: Socket, options: ResolvedConnectProxyOptions):
     // Bytes after the head belong to the tunnel (a client may pipeline its TLS ClientHello).
     let pending = head.subarray(end + 4);
     if (!target) {
-      respond(socket, 405, "Method Not Allowed");
+      respond(socket, 405, "Method Not Allowed", { Allow: "CONNECT" }, CONNECT_ONLY_BODY);
       return;
     }
     if (options.authToken !== undefined) {

package/src/claude/intercept/picker-ca-persistence.ts

@@ -22,6 +22,7 @@ export function canonicalPickerConfigDir(configDir: string): string {
 /** Public records still cannot follow symlinks or accept oversized/malformed recovery data. */
 function readState(path: string, configId: string, initialization: boolean): Initialization | AuthorityMetadata | null {
   // BigInt stats: a Windows file ID exceeds 2^53, so Number ino loses low bits and two files can compare equal.
+  // Refuse zero identity or metadata changes between the path snapshot and opened descriptor.
   let expected: BigIntStats;
   try { expected = lstatSync(path, { bigint: true }); }
   catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw new Error("picker_ca_metadata_unsafe"); }
@@ -31,7 +32,8 @@ function readState(path: string, configId: string, initialization: boolean): Ini
   catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return null; throw new Error("picker_ca_metadata_unsafe"); }
   try {
     const stat = fstatSync(fd, { bigint: true });
-    if (stat.dev !== expected.dev || stat.ino !== expected.ino) throw new Error("picker_ca_metadata_unsafe");
+    if (stat.dev !== expected.dev || stat.ino !== expected.ino || stat.ino === 0n
+      || stat.ctimeNs !== expected.ctimeNs) throw new Error("picker_ca_metadata_unsafe");
     if (!stat.isFile() || stat.nlink !== 1n || stat.size > BigInt(MAX_PUBLIC_STATE_BYTES)
       || (process.platform !== "win32" && stat.uid !== BigInt(process.getuid!()))) throw new Error();
     const bytes = Buffer.alloc(MAX_PUBLIC_STATE_BYTES + 1);

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/cli/account-api.ts

@@ -137,6 +137,7 @@ export async function apiJson(
   body?: unknown,
   options: { signal?: AbortSignal; redirect?: RequestRedirect } = {},
 ): Promise<ApiResult> {
+  if (baseUrl === LINK_HOME_BASE) return linkHomeApiJson(deps, method, path);
   const fetchImpl = deps.fetchImpl ?? fetch;
   try {
     const res = await fetchImpl(`${baseUrl}${path}`, {
@@ -163,9 +164,73 @@ export async function resolveBaseUrl(deps: AccountDeps): Promise<string | null>
   if (deps.baseUrl) return deps.baseUrl;
   const live = await findLiveProxy();
   if (!live) return null;
+  if (live.role === "client") {
+    const { readLinkChildContext } = await import("./link-child");
+    if (readLinkChildContext()) return LINK_HOME_BASE;
+  }
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
+/**
+ * Remote Link Child (#6957): account reads come from the Home over the link, and every account
+ * change is refused with the Child refusal. The marker is never a URL and never reaches fetch.
+ */
+export const LINK_HOME_BASE = "ocx-link-home:";
+
+async function linkHomeApiJson(deps: AccountDeps, method: string, path: string): Promise<ApiResult> {
+  const { readLinkChildContext, linkChildReadable, linkChildRefusal, readLinkHomeJson } = await import("./link-child");
+  const link = readLinkChildContext();
+  if (!link) return { status: 503, json: { error: "The Remote Link connection changed while the command ran; retry." } };
+  const pathname = new URL(path, "http://cli.invalid").pathname;
+  if (!linkChildReadable(method, path)) {
+    return { status: 403, json: { error: linkChildRefusal(link, `${method} ${pathname}`) } };
+  }
+  try {
+    const { status, body } = await readLinkHomeJson(link, path, deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {});
+    return { status, json: (body && typeof body === "object" ? body : { error: String(body ?? "") }) as Record<string, unknown> };
+  } catch (error) {
+    return { status: 503, json: { error: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+/**
+ * The config account commands classify providers against. On a Remote Link Child the local
+ * providers are inactive, so the Home's `/api/providers` projection (presence flags only) takes
+ * their place. Anywhere else the local config is returned. When the Home cannot be read the
+ * result is an error: classifying against the inactive local providers would answer for the
+ * wrong machine.
+ */
+export async function accountClassificationConfig(
+  deps: AccountDeps,
+  local: OcxConfig,
+): Promise<{ config: OcxConfig } | { error: string }> {
+  if (deps.baseUrl) return { config: local };
+  const { readLinkChildContext, readLinkHomeJson } = await import("./link-child");
+  const link = readLinkChildContext();
+  if (!link) return { config: local };
+  const unavailable = (detail: string) => ({ error: `Could not read the provider list from ${link.homePhrase} over Remote Link (${link.linkId}): ${detail}.` });
+  try {
+    const { status, body } = await readLinkHomeJson(link, "/api/providers", deps.fetchImpl ? { fetchImpl: deps.fetchImpl } : {});
+    if (status !== 200) {
+      // Keep the Home's own sentence (for example the upgrade instruction an older Home yields).
+      const message = body && typeof body === "object" && typeof (body as { error?: unknown }).error === "string"
+        ? (body as { error: string }).error : null;
+      return unavailable(message ?? `the Home answered HTTP ${status}`);
+    }
+    if (!Array.isArray(body)) return unavailable("the Home returned an unreadable provider list");
+    const providers: Record<string, unknown> = {};
+    for (const row of body) {
+      if (!row || typeof row !== "object" || typeof (row as { name?: unknown }).name !== "string") continue;
+      const { name, hasApiKey, ...rest } = row as Record<string, unknown> & { name: string };
+      // A placeholder marks presence for classification; no credential value crosses the link.
+      providers[name] = { ...rest, ...(hasApiKey === true ? { apiKey: "home-credential" } : {}) };
+    }
+    return { config: { ...local, providers: providers as OcxConfig["providers"] } };
+  } catch (error) {
+    return { error: error instanceof Error ? error.message : String(error) };
+  }
+}
+
 export function proxyUnreachable(transportError?: string): number {
   console.error("Proxy not reachable. Start it with 'ocx start' or 'ocx ensure'.");
   // Naming the transport cause distinguishes "nothing is listening" from a refused

package/src/cli/account-auth.ts

@@ -441,6 +441,18 @@ async function resetCredits(argv: string[], deps: RuntimeApiDeps): Promise<void>
   printData(result, wantsJson);
 }
 
+/** Codes that leave a coupon operation unconfirmed: the caller must keep its operationId. */
+const UNCONFIRMED_COUPON_CODES: ReadonlySet<string> = new Set([
+  "attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed",
+  "redeem_failed", "attempt_mark_failed", "operation_token_mismatch",
+]);
+/** Pre-dispatch ledger refusals: unconfirmed when anchored to an operation, never a settled code. */
+const LEDGER_REFUSAL_CODES: ReadonlySet<string> = new Set(["ledger_unavailable", "capacity"]);
+/** The only codes the ledger records as a definitive outcome; any other settled code is unconfirmed. */
+const DEFINITIVE_SETTLED_CODES: ReadonlySet<string> = new Set([
+  "redeemed", "auth_failed", "fetch_resets_failed", "no_coupons_available", "coupon_unavailable", "token_unresolved",
+]);
+
 async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   // The account id is optional here (the server falls back to the selected xAI
@@ -467,6 +479,7 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
   rejectArgs(args, USAGE);
   const accountId = rawId ? (rawId === "main" ? "__main__" : rawId) : undefined;
   const effectiveOperationId = consume ? operationId ?? crypto.randomUUID() : undefined;
+  const unconfirmed = () => new RuntimeApiError(`Coupon redemption outcome is unconfirmed. Preserve --operation-id ${effectiveOperationId}; reuse it to inspect this attempt and do not create a replacement operation.`, 503, null);
   let result: unknown;
   try {
     result = consume
@@ -476,15 +489,26 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
       : await runtimeRequest(`/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`, {}, deps);
   } catch (error) {
     const apiError = error instanceof RuntimeApiError ? error : undefined;
-    const body = apiError?.body as { error?: { code?: string } } | null | undefined;
+    const body = apiError?.body as { operationId?: unknown; error?: { code?: string } } | null | undefined;
     const code = body && typeof body === "object" ? body.error?.code : undefined;
+    const carriesOperation = !!body && typeof body === "object" && typeof body.operationId === "string";
     if (consume && (!apiError || (!apiError.code && (
-      (!code && apiError.status >= 500) || ["attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed", "redeem_failed"].includes(code ?? "")
+      (!code && apiError.status >= 500) || UNCONFIRMED_COUPON_CODES.has(code ?? "")
+      || (LEDGER_REFUSAL_CODES.has(code ?? "") && carriesOperation)
     )))) {
       throw new RuntimeApiError(`Coupon redemption outcome is unconfirmed. Preserve --operation-id ${effectiveOperationId}; reuse it to inspect this attempt and do not create a replacement operation.`, apiError?.status ?? 503, apiError?.body ?? null);
     }
     throw error;
   }
+  if (consume) {
+    // A 200 can replay a recorded refusal; only "redeemed" is a successful spend.
+    const settled = result && typeof result === "object" ? (result as { code?: unknown }).code : undefined;
+    if (typeof settled !== "string" || !DEFINITIVE_SETTLED_CODES.has(settled)) throw unconfirmed();
+    if (settled !== "redeemed") {
+      printData(result, wantsJson);
+      throw new RuntimeApiError(`Coupon was not redeemed (${settled}).`, 409, result);
+    }
+  }
   printData(result, wantsJson);
 }