@bitkyc08/opencodex 2.82.0 → 2.84.0

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

@@ -6,6 +6,7 @@ import { warnIfCodexCatalogRefreshPending } from "./account-catalog-refresh";
 import { isCodexResetCreditOperationId } from "../codex/reset-credit-recovery";
 import { BROWSER_LAUNCH_FAILED_NOTICE } from "../lib/browser-launch-notice";
 import {
+  RuntimeApiError,
   CliUsageError,
   printData,
   readSecretLine,
@@ -440,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
@@ -465,18 +478,37 @@ async function grokResetCoupons(argv: string[], deps: RuntimeApiDeps): Promise<v
   }
   rejectArgs(args, USAGE);
   const accountId = rawId ? (rawId === "main" ? "__main__" : rawId) : undefined;
-  const result = consume
-    ? await runtimeRequest("/api/grok/reset-coupons/consume", {
-      method: "POST",
-      // Spread, not `operationId: undefined`: the server distinguishes an absent
-      // key from a caller who asked for a stable idempotency identity.
-      body: JSON.stringify({ accountId, tokenId, ...(operationId === undefined ? {} : { operationId }) }),
-    }, deps)
-    : await runtimeRequest(
-      `/api/grok/reset-coupons${accountId ? `?accountId=${encodeURIComponent(accountId)}` : ""}`,
-      {},
-      deps,
-    );
+  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
+      ? await runtimeRequest("/api/grok/reset-coupons/consume", {
+        method: "POST", body: JSON.stringify({ accountId, tokenId, operationId: effectiveOperationId }),
+      }, deps)
+      : 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 { 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) || 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);
 }
 

package/src/cli/account.ts

@@ -21,7 +21,7 @@ import {
   cmdRoutes,
   cmdStrategy,
 } from "./account-extended";
-import { apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
+import { accountClassificationConfig, apiError, apiJson, classifyAccount, fetchRows, proxyUnreachable, resolveBaseUrl, type AccountDeps, type AccountRow, type AccountType, type ApiResult }
   from "./account-api";
 
 export { classifyAccount } from "./account-api";
@@ -199,7 +199,12 @@ async function cmdList(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const baseUrl = await resolveBaseUrl(deps);
   if (!baseUrl) return proxyUnreachable();
 
@@ -289,7 +294,12 @@ async function cmdCurrent(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const c = classifyAccount(config, name);
   if ("error" in c) {
     console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
@@ -332,7 +342,20 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  // #6957: an account change on a link Child is refused before any Home read.
+  if (!deps.baseUrl) {
+    const refusal = (await import("./link-child")).linkChildProviderChangeRefusal("ocx account use");
+    if (refusal) {
+      console.error(`Error: ${refusal}`);
+      return 1;
+    }
+  }
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const c = classifyAccount(config, name);
   if ("error" in c) {
     console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);
@@ -392,7 +415,20 @@ async function cmdClear(rest: string[], deps: AccountDeps): Promise<number> {
     console.error(ACCOUNT_USAGE);
     return 1;
   }
-  const config = deps.loadConfigImpl?.() ?? loadConfig();
+  // #6957: an account change on a link Child is refused before any Home read.
+  if (!deps.baseUrl) {
+    const refusal = (await import("./link-child")).linkChildProviderChangeRefusal("ocx account clear");
+    if (refusal) {
+      console.error(`Error: ${refusal}`);
+      return 1;
+    }
+  }
+  const classification = await accountClassificationConfig(deps, deps.loadConfigImpl?.() ?? loadConfig());
+  if ("error" in classification) {
+    console.error(`Error: ${classification.error}`);
+    return 1;
+  }
+  const config = classification.config;
   const c = classifyAccount(config, name);
   if ("error" in c) {
     console.error(`Error: ${c.error}. Known candidates: ${candidateNames(config)}`);

package/src/cli/capabilities-access-remote.ts

@@ -2,6 +2,14 @@ import type { Capability } from "./capability-types";
 
 /** Verified existing handlers only; local operations never claim management routes. */
 export const ACCESS_REMOTE_CAPABILITIES: readonly Capability[] = [
+  {
+    command: ["hub", "disable"], summary: "Return a hub to standalone in one validated config write.",
+    usage: "ocx hub disable [--revoke-clients --client-key <id> ...] [--json]",
+    routes: [],
+    flags: [{ name: "--revoke-clients", value: "boolean", summary: "Revoke only explicitly selected saved client key IDs." }, { name: "--client-key", value: "string", summary: "Exact saved key ID to revoke; repeatable, requires --revoke-clients." }, { name: "--json", value: "boolean", summary: "Emit the result and restart guidance as JSON." }],
+    mutates: true, json: "envelope",
+    details: ["Removes hub, unauthenticatedLoopbackListener, runtimeRole and hostname atomically after validation; non-hub roles refuse without changes.", "Existing keys have no verified client origin. Names never select keys; --revoke-clients requires exact --client-key IDs when keys exist. Unselected keys remain.", "Prints only safe key metadata, never plaintext keys or pending rotations. Restart advice is informational; the running proxy and external publishing are unchanged."],
+  },
   {
     command: ["access", "key"], summary: "Manage API access keys and inspect masked metadata.",
     usage: "ocx access key list [--json]",

package/src/cli/capabilities-base.ts

@@ -26,6 +26,8 @@ export const CAPABILITIES: readonly Capability[] = [
     bannerLines: ["ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)"],
     details: ["Default off; launch requires chatgptDesktop.appServerShim: true. Restore removes the generated launcher."],
   },
+  {"command": ["link","probe"],"summary": "Probe an SSH host fingerprint and OpenCodex version without trusting it.","routes": [{"method": "POST","path": "/api/link/probe"}],"flags": [{"name": "--json","value": "boolean","summary": "Emit alias, fingerprint, key type and version as JSON."}],"mutates": true,"json": "payload","usage": "ocx link probe <alias> [--json]","details": ["Requires loopback admin authority on the Home. Stores only a temporary pending offer; does not persist host trust or issue a link key."]},
+  {"command": ["link","add"],"summary": "Connect an SSH Child to this Home after confirming its fingerprint.","routes": [{"method": "POST","path": "/api/link/probe"},{"method": "POST","path": "/api/link/confirm-host"},{"method": "POST","path": "/api/link/apply"}],"flags": [{"name": "--expect-fingerprint","value": "string","summary": "Exact SHA256 host fingerprint; required without an interactive TTY."},{"name": "--json","value": "boolean","summary": "Emit the verified link result as JSON."}],"mutates": true,"json": "payload","usage": "ocx link add <alias> [--expect-fingerprint SHA256:…] [--json]","details": ["Requires loopback admin authority on the Home. Without a fingerprint, requires a TTY and explicit yes after showing the offered fingerprint. Never prints the link key.","Preflights bound Child restart support and curl, connects, restarts once and verifies a fresh authenticated catalog relay before success. Post-connect failures can leave Child config; run ocx disconnect and ocx restart there before retrying."]},
   {
     command: ["link","port"],
     summary: "Allocate a free loopback port for a remote home link.",
@@ -65,6 +67,16 @@ export const CAPABILITIES: readonly Capability[] = [
     details: ["Requires a valid link ID and loopback admin authority. Explicit force additionally requires --yes.","Ordinary revoke always emits {linkId} JSON; forced revoke has human output or a JSON cleanup receipt. Already-revoked link_not_found is idempotent success.","Ordinary revoke retains its no-body and idempotent behavior. Forced success reports remoteCleanup:skipped from invocation intent; already-missing link reports unverified. Neither proves the remote client disconnected.","If forced cleanup was needed, run ocx disconnect on the remote client. No new enrollment, SSH trust or credential action is implied."],
     usage: "ocx link revoke --link-id <id> [--force --yes] [--json]",
   },
+  {
+    command: ["link","reconnect"],
+    summary: "Restart a Home-initiated link's SSH tunnel now.",
+    routes: [{"method":"POST","path":"/api/link/{id}/reconnect"}],
+    flags: [{"name":"--link-id","value":"string","required":true,"summary":"Home-initiated link id whose tunnel to restart."},{"name":"--json","value":"boolean","summary":"Emit the restarted link id as JSON."}],
+    mutates: true,
+    json: "envelope",
+    usage: "ocx link reconnect --link-id <id> [--json]",
+    details: ["Requires a valid link ID and loopback admin authority. Stops the current ssh child, clears any backoff or failed state and starts a fresh attempt; read ocx link status for the outcome.","A Child-initiated link is refused with link_not_home_initiated: its own computer owns and retries that tunnel.","Always emits {linkId} JSON."],
+  },
   {
     command: ["remote-workspace","pair"],
     summary: "Enroll this executor with one Hub using a one-time code from stdin and locally approved roots.",
@@ -717,7 +729,7 @@ export const CAPABILITIES: readonly Capability[] = [
     flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--effort","value":"string","summary":"set: also write the role's reasoning effort."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
     mutates: true,
     json: "payload",
-    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
+    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model and effort."],
     usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--effort <level>] [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
   },
   {