@bitkyc08/opencodex 2.57.0 → 2.59.0

package/src/cli/account-extended.ts

@@ -925,12 +925,32 @@ async function poolSetting(
     if (response.status !== 200) return apiError(response.json, `failed to read ${label}`, response.status);
     const strategy = response.json[transport.strategyKey];
     const sticky = response.json[transport.stickyKey];
+    const autoSwitchThreshold = typeof response.json.autoSwitchThreshold === "number"
+      ? response.json.autoSwitchThreshold
+      : undefined;
     if (wantsJson) {
       // Pool-neutral key names: the two routes spell the same two settings differently, and a
       // `--json` consumer should not have to branch on which pool answered.
-      console.log(JSON.stringify({ ok: true, provider: name, strategy, stickyLimit: sticky }, null, 2));
+      const payload: Record<string, unknown> = { ok: true, provider: name, strategy, stickyLimit: sticky };
+      if (autoSwitchThreshold !== undefined) {
+        payload.autoSwitchThreshold = autoSwitchThreshold;
+      }
+      console.log(JSON.stringify(payload, null, 2));
     } else {
-      console.log(`${name}: ${label} is ${String(field === "strategy" ? strategy : sticky)}`);
+      if (field === "strategy" && autoSwitchThreshold !== undefined) {
+        const thresholdSummary = strategy === "round-robin"
+          ? "threshold not used"
+          : autoSwitchThreshold > 0
+          ? (strategy === "fill-first"
+              ? `drain at ${autoSwitchThreshold}%`
+              : strategy === "reset-first"
+              ? `nearest reset below ${autoSwitchThreshold}%`
+              : `switch at ${autoSwitchThreshold}%`)
+          : "proactive switching off";
+        console.log(`${name}: ${label} is ${String(strategy)} (${thresholdSummary})`);
+      } else {
+        console.log(`${name}: ${label} is ${String(field === "strategy" ? strategy : sticky)}`);
+      }
     }
     return 0;
   }

package/src/cli/account-orca-import.ts

@@ -0,0 +1,63 @@
+import type { importOrcaAccounts } from "../codex/orca-import";
+
+const USAGE = "Usage: ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]";
+
+export interface OrcaImportCommandDeps {
+  importAccounts?: typeof importOrcaAccounts;
+}
+
+/** Local-only: never sends source paths or credentials to a management listener. */
+export async function cmdOrcaImport(args: string[], deps: OrcaImportCommandDeps = {}): Promise<number> {
+  let sourceDir: string | undefined;
+  let registryPath: string | undefined;
+  let apply = false;
+  const wantsJson = args.includes("--json");
+  const seen = new Set<string>();
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index]!;
+    if (seen.has(arg) || !["--source", "--registry", "--apply", "--json"].includes(arg)) {
+      console.error(USAGE);
+      return 1;
+    }
+    seen.add(arg);
+    if (arg === "--source" || arg === "--registry") {
+      const value = args[++index];
+      if (!value || value.startsWith("--")) {
+        console.error(USAGE);
+        return 1;
+      }
+      if (arg === "--source") sourceDir = value;
+      else registryPath = value;
+    } else if (arg === "--apply") apply = true;
+  }
+  if (!sourceDir || !registryPath) {
+    console.error(USAGE);
+    return 1;
+  }
+  try {
+    const run = deps.importAccounts ?? (await import("../codex/orca-import")).importOrcaAccounts;
+    const result = await run({ sourceDir, registryPath, apply });
+    if (wantsJson) console.log(JSON.stringify({
+      mode: result.mode, discovered: result.discovered, eligible: result.eligible,
+      imported: result.imported, duplicates: result.duplicates, invalid: result.invalid,
+      invalidReasons: result.invalidReasons,
+    }));
+    else {
+      console.log(`Orca: ${result.discovered} discovered, ${result.eligible} eligible, ${result.imported} imported, ${result.duplicates} duplicates, ${result.invalid} invalid.`);
+      if (result.invalid > 0) {
+        const reasons = Object.entries(result.invalidReasons).map(([reason, count]) => `${reason}=${count}`).join(", ");
+        console.log(`Invalid reasons: ${reasons}`);
+      }
+      console.log(apply
+        ? "Start the proxy and use Refresh quotas in Codex Auth to validate new accounts. Orca retains refresh ownership."
+        : "Preview only. Stop the proxy before repeating with --apply. Orca authentication files stay read-only.");
+    }
+    return result.invalid > 0 && result.eligible === 0 ? 1 : 0;
+  } catch {
+    // Filesystem/JSON exceptions may contain source paths or token fragments.
+    const error = "Orca import failed. Check the source, destination config, and stopped proxy; no successful completion is confirmed.";
+    if (wantsJson) console.log(JSON.stringify({ error: "orca_import_failed" }));
+    else console.error(error);
+    return 1;
+  }
+}

package/src/cli/account.ts

@@ -57,6 +57,7 @@ const ACCOUNT_USAGE = `Usage:
   ocx account clear-cooldown <provider> <account-id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]
   ocx account import <provider> --format <format> (--file <path>|--stdin) [--json]
+  ocx account import-orca --source <orca-data-directory> --registry <orca-data.json> [--apply] [--json]
   ocx account login <provider> [--id <account-id>] [--reauth] [--code -] [--no-wait] [--json]
   ocx account code <provider> [--flow <flow-id>] [--json]   (reads the code from stdin)
   ocx account cancel <provider> [--flow <flow-id>] [--json]
@@ -323,13 +324,36 @@ async function cmdUse(rest: string[], deps: AccountDeps): Promise<number> {
   if (res.status === 0) return proxyUnreachable(res.transportError);
   if (res.status !== 200) return apiError(res.json, `failed to switch ${name}`, res.status);
 
-  if (wantsJson) console.log(JSON.stringify({ ok: true, provider: name, type: c.type, activeId }, null, 2));
-  else console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
+  // The route reports this only when routing would drop the pin it just recorded, so an
+  // absent field means the pin survives (#4521).
+  const pinDrainReason = typeof res.json.pinDrainReason === "string" ? res.json.pinDrainReason : undefined;
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      ok: true,
+      provider: name,
+      type: c.type,
+      activeId,
+      ...(pinDrainReason !== undefined ? { pinDrained: true, pinDrainReason } : {}),
+    }, null, 2));
+  } else {
+    console.log(`${name}: active ${c.type === "api-key" ? "key" : "account"} is now ${displayId(activeId)}`);
+  }
   if (c.type === "codex") {
     console.error("Takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.");
     const active = await apiJson(deps, baseUrl, "GET", "/api/codex-auth/active");
-    if (active.status === 200 && typeof active.json.autoSwitchThreshold === "number" && active.json.autoSwitchThreshold > 0) {
-      console.error(`Note: auto-switch (threshold ${active.json.autoSwitchThreshold}%) may override this pin.`);
+    const threshold = active.status === 200 && typeof active.json.autoSwitchThreshold === "number"
+      ? active.json.autoSwitchThreshold
+      : undefined;
+    if (pinDrainReason !== undefined) {
+      // "may override" is the right caveat for a pin that is currently fine and could be
+      // overtaken later. It is the wrong sentence for one the next request will discard, and
+      // printing only that is what left the operator believing the account was pinned.
+      const because = pinDrainReason === "quota_threshold"
+        ? `is at or above the auto-switch threshold${threshold !== undefined ? ` (${threshold}%)` : ""}`
+        : `cannot currently be selected (${pinDrainReason})`;
+      console.error(`Note: ${displayId(activeId)} ${because}, so routing releases this pin on its next request.`);
+    } else if (threshold !== undefined && threshold > 0) {
+      console.error(`Note: auto-switch (threshold ${threshold}%) may override this pin.`);
     }
   }
   return 0;
@@ -360,6 +384,10 @@ export async function cmdAccount(args: string[], deps: AccountDeps = {}): Promis
     if (sub === "clear-cooldown") return await cmdClearCooldown(rest, deps);
     if (sub === "add-key") return await cmdAddKey(rest, deps);
     if (sub === "import") return await cmdImport(rest, deps);
+    if (sub === "import-orca") {
+      const { cmdOrcaImport } = await import("./account-orca-import");
+      return await cmdOrcaImport(rest);
+    }
     if (sub === "main") {
       const { cmdNativeMainAccount } = await import("./account-main");
       return await cmdNativeMainAccount(rest, deps);

package/src/cli/capabilities.ts

@@ -360,6 +360,25 @@ export const CAPABILITIES: readonly Capability[] = [
       "`--quota` shows cached Codex windows (including 5h); `--refresh` bypasses the server TTL.",
     ],
   },
+  {
+    command: ["account", "import-orca"],
+    summary: "Preview or register read-only links to Orca-managed Codex accounts without another login.",
+    routes: [],
+    flags: [
+      { name: "--source", value: "string", required: true, summary: "Orca data directory containing codex-accounts." },
+      { name: "--registry", value: "string", required: true, summary: "The chosen Orca profile's orca-data.json account registry." },
+      { name: "--apply", value: "boolean", summary: "Register new accounts; requires a stopped proxy. Default is preview." },
+      { name: "--json", value: "boolean", summary: "Emit counts and fixed invalid-reason codes without credentials or source paths." },
+    ],
+    mutates: true,
+    json: "envelope",
+    details: [
+      "Local files only; never copies refresh tokens or changes Orca authentication files.",
+      "Skips existing ChatGPT identities. New accounts remain pending until dashboard validation.",
+      "Orca must keep the source login available and refreshed; a missing or expired source fails closed.",
+      "Mixed eligible and invalid entries exit successfully; an all-invalid result exits nonzero.",
+    ],
+  },
   {
     command: ["account", "refresh"],
     summary: "Refresh account quotas without model validation; pending Codex accounts require dashboard consent.",
@@ -708,6 +727,27 @@ export const CAPABILITIES: readonly Capability[] = [
       "Does not execute Codex or npm, install or repair software, control a process, or write configuration or cache state.",
     ],
   },
+  {
+    command: ["system", "codex-cli-update", "attest"],
+    summary: "Observe the selected or explicitly named Windows npm Codex installation files without enabling updates.",
+    routes: [],
+    flags: [
+      { name: "--candidate", value: "string", summary: "Absolute npm codex.cmd or package bin/codex.js path; all four paths are all-or-none." },
+      { name: "--npm-prefix", value: "string", summary: "Absolute prefix containing node_modules/@openai/codex." },
+      { name: "--npm-cli", value: "string", summary: "Absolute node_modules/npm/bin/npm-cli.js path." },
+      { name: "--node", value: "string", summary: "Absolute node.exe path; observed, never executed." },
+      { name: "--json", value: "boolean", summary: "Emit the path-free installation identity observation." },
+    ],
+    mutates: false,
+    json: "envelope",
+    details: [
+      "Opt-in Windows x64 local-volume inspection using held native file handles; refuses reparse points, active writers and unsupported layouts.",
+      "Without explicit paths, the proof-bound launcher snapshot identifies the selected candidate: the configured CODEX_CLI_PATH or the first codex on the captured PATH, with an OpenCodex wrapper resolving to its codex.opencodex-real backing. Discovery only proposes paths; the held-handle observation remains the authority.",
+      "Success binds observed file identities and bytes, not selected-runtime admission or installer ownership.",
+      "selectionAttested, managed and applyAllowed remain false. The digest is an observation, not a durable update permit.",
+      "Does not run the named Codex/npm/Node files, query a registry, install software, control processes or persist state.",
+    ],
+  },
   {
     command: ["system", "codex-restart"],
     summary: "Restart the Codex desktop app and app-servers.",

package/src/cli/claude.ts

@@ -11,7 +11,7 @@ import { spawn } from "node:child_process";
 import { loadConfig } from "../config";
 import { injectClaudeAgentDefs } from "../claude/agents-inject";
 import { CLAUDE_ALIAS_PREFIX_V1, CLAUDE_ALIAS_PREFIX_V2 } from "../claude/alias";
-import { effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
+import { claudeToolSearchEnv, effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
 import { claudeConfigDir, refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
 import { commandInvocation } from "../lib/win-exec";
 import { isProxyAdmissionSecret } from "../server/auth-cors";
@@ -357,6 +357,22 @@ export function buildClaudeEnv(
   if (config.claudeCode?.alwaysEnableEffort === true) {
     setDefault("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
   }
+  // Tool-search deferral (#4838). Claude Code disables MCP tool deferral whenever
+  // ANTHROPIC_BASE_URL is not a first-party Anthropic host — keyed on the host, not
+  // the model — so every routed session inlines all MCP tool schemas. Its own log
+  // line states the precondition: "Set ENABLE_TOOL_SEARCH=true (or auto / auto:N)
+  // if your proxy forwards tool_reference blocks."
+  //
+  // We forward them on the native Anthropic passthrough route only. A translated
+  // route cannot honour the shape: deferred tools still carry input_schema on the
+  // wire (deferral is a server-side context optimisation, not a smaller request),
+  // toolsToResponses drops the tool_search server tool and ignores defer_loading,
+  // and compatibility.ts lists tool_search/tool_reference/deferred_tools as
+  // unsupported. Turning it on there leaves the routed provider holding every
+  // schema while Claude Code stops counting them and stops compacting, which is
+  // worse than the problem. So this stays opt-in per config rather than
+  // unconditional, and setDefault keeps an operator's own export.
+  setDefault("ENABLE_TOOL_SEARCH", claudeToolSearchEnv(config.claudeCode?.toolSearch));
   // Context-window override: the official pair — MAX_CONTEXT_TOKENS alone is ignored
   // for recognized claude-shaped ids unless DISABLE_COMPACT=1 rides along (devlog 135).
   const maxCtx = config.claudeCode?.maxContextTokens;
@@ -542,6 +558,18 @@ export function claudeLaunchPreflight(
     : { kind: "native", notice: CLAUDE_NATIVE_ROUTING_OFF };
 }
 
+/**
+ * Levers a native (non-routed) launch must shed. The loop below deletes them
+ * unconditionally, because each one either points Claude Code at a gateway that
+ * is not there or asserts host ownership that a native session does not have.
+ *
+ * ENABLE_TOOL_SEARCH is deliberately NOT in this list (#4838). It is the only
+ * one of these whose value is meaningful to a native session: natively the base
+ * URL is first-party, where deferral is already Claude Code's default and the
+ * variable is the user's own tuning knob (auto:N, force). Stripping it would
+ * delete a preference that works, to protect a session that does not need
+ * protecting.
+ */
 const NATIVE_STRIPPED_LEVERS = [
   "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY",
   "CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST",

package/src/cli/codex-cli-update.ts

@@ -3,18 +3,53 @@ import {
   type CodexCliInstallProvenanceDeps,
   type CodexCliInstallReport,
 } from "../codex/cli-install-provenance";
+import type {
+  CodexCliInstallationIdentityInput,
+  CodexCliInstallationIdentityReport,
+} from "../codex/cli-installation-identity";
+import type {
+  CodexCliInstallationSnapshot,
+  CodexCliInstallationTargetDerivation,
+} from "../codex/cli-installation-targets";
 import { CliUsageError, isJsonOption, printData, runCliAction } from "./runtime-api";
 import { trustedNodeLauncherContext } from "./launcher-context";
 
 export const CODEX_CLI_UPDATE_USAGE = `Usage:
-  ocx system codex-cli-update check [--json]`;
+  ocx system codex-cli-update check [--json]
+  ocx system codex-cli-update attest [--json]
+  ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]`;
 
 export type ParsedCodexCliUpdateArgs = Readonly<{
   json: boolean;
+}> | Readonly<{
+  json: boolean;
+  attest: CodexCliInstallationIdentityInput | "selected";
 }>;
 
 export interface CodexCliUpdateCommandDeps {
   readonly inspectInstall?: (deps: CodexCliInstallProvenanceDeps) => Promise<CodexCliInstallReport>;
+  readonly inspectIdentity?: (input: CodexCliInstallationIdentityInput) => Promise<CodexCliInstallationIdentityReport>;
+  readonly deriveInstallationInput?: (
+    snapshot: CodexCliInstallationSnapshot,
+  ) => CodexCliInstallationTargetDerivation;
+}
+
+function identitySummary(report: CodexCliInstallationIdentityReport): string[] {
+  return [
+    `status: ${report.status}`,
+    `reason: ${report.reason}`,
+    `candidate-source: ${report.candidateSource}`,
+    `installation-identity-observed: ${report.installationIdentityObserved ? "yes" : "no"}`,
+    `selection-attested: ${report.selectionAttested ? "yes" : "no"}`,
+    `managed: ${report.managed ? "yes" : "no"}`,
+    `apply-allowed: ${report.applyAllowed ? "yes" : "no"}`,
+    `package-version: ${report.packageVersion ?? "unavailable"}`,
+    `npm-version: ${report.npmVersion ?? "unavailable"}`,
+    `identity-digest: ${report.identityDigest ?? "unavailable"}`,
+    `proof: ${report.proof ?? "unavailable"}`,
+    `toolchain: ${report.toolchain}`,
+    "scope: installation identity only; runtime selection and update ownership are not attested",
+  ];
 }
 
 function installSummary(report: CodexCliInstallReport): string[] {
@@ -47,8 +82,38 @@ export function parseCodexCliUpdateArgs(argv: readonly string[]): ParsedCodexCli
     }
     positional.push(token);
   }
+  if (positional[0] === "attest") {
+    // No options: attest the selected candidate identified from the proof-bound
+    // launcher snapshot. The four explicit paths remain all-or-none.
+    if (positional.length === 1) {
+      return Object.freeze({ json, attest: "selected" as const });
+    }
+    const options = new Map<string, keyof CodexCliInstallationIdentityInput>([
+      ["--candidate", "candidate"], ["--npm-prefix", "npmPrefix"],
+      ["--npm-cli", "npmCli"], ["--node", "node"],
+    ]);
+    const input: Partial<Record<keyof CodexCliInstallationIdentityInput, string>> = {};
+    for (let index = 1; index < positional.length; index += 2) {
+      const key = options.get(positional[index]!);
+      if (!key || input[key] !== undefined) {
+        throw new CliUsageError("unsupported or duplicate attest option", CODEX_CLI_UPDATE_USAGE);
+      }
+      const value = positional[index + 1];
+      if (!value || !value.trim() || /[\0\r\n]/.test(value)
+        || !(value.startsWith("/") || /^[a-z]:[\\/]/i.test(value))) {
+        throw new CliUsageError("attest options require explicit absolute paths", CODEX_CLI_UPDATE_USAGE);
+      }
+      input[key] = value;
+    }
+    if (!input.candidate || !input.npmPrefix || !input.npmCli || !input.node) {
+      throw new CliUsageError("attest requires --candidate, --npm-prefix, --npm-cli and --node", CODEX_CLI_UPDATE_USAGE);
+    }
+    return Object.freeze({ json, attest: Object.freeze({
+      candidate: input.candidate, npmPrefix: input.npmPrefix, npmCli: input.npmCli, node: input.node,
+    }) });
+  }
   if (positional[0] !== "check") {
-    throw new CliUsageError("codex-cli-update action must be check", CODEX_CLI_UPDATE_USAGE);
+    throw new CliUsageError("codex-cli-update action must be check or attest", CODEX_CLI_UPDATE_USAGE);
   }
   if (positional.length > 1) {
     throw new CliUsageError("unsupported codex-cli-update argument", CODEX_CLI_UPDATE_USAGE);
@@ -72,6 +137,36 @@ export async function handleCodexCliUpdateCommand(
     throw error;
   }
   return runCliAction(async () => {
+    if ("attest" in parsed) {
+      let report: CodexCliInstallationIdentityReport;
+      try {
+        const identityModule = await import("../codex/cli-installation-identity");
+        const inspectIdentity = deps.inspectIdentity ?? identityModule.inspectCodexCliInstallationIdentity;
+        if (parsed.attest === "selected") {
+          // The proof-bound launcher snapshot is the only trusted source for the
+          // selected candidate; a direct Bun/source launch has none and refuses.
+          const snapshot = trustedNodeLauncherContext()?.codexCliInspectionEnv;
+          const derive = deps.deriveInstallationInput
+            ?? (await import("../codex/cli-installation-targets")).deriveCodexCliInstallationInput;
+          const derived = derive({
+            codexCliPath: snapshot?.codexCliPath ?? null,
+            path: snapshot?.path ?? null,
+            pathExt: snapshot?.pathExt ?? null,
+          });
+          report = derived.kind === "derived"
+            ? await inspectIdentity(derived.input)
+            : identityModule.codexCliInstallationRefusal(derived.reason, "selected");
+        } else {
+          report = await inspectIdentity(parsed.attest);
+        }
+      } catch {
+        // Filesystem/native errors can contain the explicit private paths. The
+        // read-only inspector normally returns a refusal; unexpected errors stay redacted.
+        throw new Error("Installation identity inspection failed");
+      }
+      printData(report, parsed.json, identitySummary(report));
+      return;
+    }
     const trustedInspectionEnv = trustedNodeLauncherContext()?.codexCliInspectionEnv;
     const inspectionDeps: CodexCliInstallProvenanceDeps = trustedInspectionEnv
       && trustedInspectionEnv.managerRoots !== null ? {

package/src/cli/config-command.ts

@@ -4,7 +4,7 @@ import { getConfigPath, mutatePersistedConfig, readConfigDiagnostics, sanitizeMo
 import { VISION_REASONING_EFFORTS, isVisionReasoningEffort } from "../reasoning-effort";
 import type { OcxConfig } from "../types";
 import { normalizeVisionReasoningForModel } from "../vision/reasoning";
-import type { ClientConnectionStatus } from "./connect";
+import type { ServiceApiTokenState } from "../lib/service-secrets";
 import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
 
 const USAGE = `Usage:
@@ -38,9 +38,8 @@ const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
  * `client` block, which is the same defect in miniature: the presence of configuration is not
  * evidence that the connection works, and a machine whose data-plane token was revoked, rotated
  * away or deleted would have been labelled `connected: true` while it could not reach the hub at
- * all. `collectClientConnectionStatus` is the one reader that knows — it compares the token file's
- * fingerprint against the connection record — so the caller passes its answer in and this stays
- * pure and testable.
+ * all. The read-only projection compares the bounded token file's fingerprint against the
+ * connection record, and passes that answer in so this formatter stays pure and testable.
  *
  * Synthetic and NOT persisted, for two reasons. `clientConnectionSchema` is `.strict()`, so a
  * `client.note` field would not validate; and persisted prose drifts from the behaviour it
@@ -49,7 +48,7 @@ const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
  */
 export function remoteHubConfigNote(
   config: OcxConfig,
-  readConnection: () => Pick<ClientConnectionStatus, "state" | "reason" | "token">,
+  readConnection: () => RemoteHubConnectionObservation,
 ): { connected: boolean; origin: string; note: string } | null {
   if (config.runtimeRole !== "client" || !config.client) return null;
   // A thunk, so a standalone or hub install pays nothing: the guard above returns first and the
@@ -67,6 +66,36 @@ export function remoteHubConfigNote(
   return { connected, origin: config.client.serverUrl, note };
 }
 
+export type RemoteHubConnectionObservation = {
+  state: "disconnected" | "connected" | "invalid" | "mismatched";
+  reason?: string;
+  token: "owned" | "missing" | "changed" | "unsafe";
+};
+
+export function remoteHubConnectionFromTokenState(
+  config: Pick<OcxConfig, "client">,
+  tokenState: ServiceApiTokenState,
+): RemoteHubConnectionObservation {
+  const token = tokenState.kind === "absent"
+    ? "missing"
+    : tokenState.kind === "unsafe"
+      ? "unsafe"
+      : tokenState.fingerprint === config.client?.tokenFingerprint ? "owned" : "changed";
+  return { state: "connected", token };
+}
+
+async function readRemoteHubConfigNote(config: OcxConfig): Promise<ReturnType<typeof remoteHubConfigNote>> {
+  if (config.runtimeRole !== "client" || !config.client) return null;
+  // This display command needs only connection ownership, not lifecycle recovery, catalog
+  // readiness, or any write-capable connect machinery. Keep the read on the bounded token
+  // observer so a cold `config show` never imports the full connect command graph.
+  const { readServiceApiTokenState } = await import("../lib/service-secrets");
+  return remoteHubConfigNote(
+    config,
+    () => remoteHubConnectionFromTokenState(config, readServiceApiTokenState()),
+  );
+}
+
 function redact(value: unknown, key = ""): unknown {
   if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
   // `client.priorCatalog` is the base64 catalog snapshot connect took before overwriting the
@@ -168,19 +197,7 @@ export async function handleConfigCommand(argv: string[]): Promise<number> {
       rejectArgs(args, USAGE);
       const diagnostics = readConfigDiagnostics();
       const redacted = redact(diagnostics.config);
-      // Imported here rather than at module scope: `./connect` pulls the whole client lifecycle
-      // in, and `ocx config get/set` has no use for it.
-      const { collectClientConnectionStatus } = await import("./connect");
-      // The readiness probe is declined explicitly. `collectClientConnectionStatus` observes the
-      // local Codex ladder for a connected client, and observing it spawns `codex debug models`
-      // under a 45s budget. `ocx config show` reads only `state`, `reason` and `token` from the
-      // result, so paying for a subprocess here would buy nothing and would quietly turn a
-      // read-only config dump into a runtime probe. Returning no ladder resolves readiness to
-      // `unverified`, which is the honest answer for a caller that never asked.
-      const note = remoteHubConfigNote(
-        diagnostics.config,
-        () => collectClientConnectionStatus(undefined, undefined, { supportedEfforts: () => null }),
-      );
+      const note = await readRemoteHubConfigNote(diagnostics.config);
       // First key, not last: it has to be read before the empty `providers` map that misled a
       // reader into concluding nothing was configured anywhere.
       const config = note && redacted && typeof redacted === "object" && !Array.isArray(redacted)

package/src/cli/dispatch.ts

@@ -24,7 +24,7 @@ import {
 } from "../codex/desired-state";
 import { syncModelsToCodex } from "../codex/sync";
 import { collectOrcaCodexHomeDiagnostic } from "../codex/home";
-import { restoreNativeCodexAsync } from "../codex/inject";
+import { restoreNativeCodexAsync, type CodexNativeRestoreResult } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
 import { handleRestartScopeAfterWrite, readRestartScope, type RestartScope } from "./restart-scope";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
@@ -106,6 +106,7 @@ const commandRunners: Record<string, CommandRunner> = {
   restore: async deps => {
     const restoreArgs = deps.args.slice(1);
     const restoreJson = takeFlag(restoreArgs, "--json");
+    const removeProviderTable = takeFlag(restoreArgs, "--remove-codex-provider-table");
     if (restoreArgs[0] === "back") {
       // Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
       // lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
@@ -146,6 +147,9 @@ const commandRunners: Record<string, CommandRunner> = {
       const target = collectOrcaCodexHomeDiagnostic();
       return emitBack(true, `Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`, 0);
     }
+    if (removeProviderTable && !restoreJson) {
+      console.log("⚠️  Removing [model_providers.opencodex] means conversations already tagged opencodex will stop opening.");
+    }
     const desired = setIntegrationEnabled("codex", false);
     if (!desired.ok) {
       if (restoreJson) {
@@ -191,9 +195,9 @@ const commandRunners: Record<string, CommandRunner> = {
         return grokCode;
       }
     }
-    let r: { success: boolean; message: string };
+    let r: CodexNativeRestoreResult | Pick<CodexNativeRestoreResult, "success" | "message">;
     try {
-      r = await restoreNativeCodexAsync({ revalidateDesiredState: true });
+      r = await restoreNativeCodexAsync({ revalidateDesiredState: true, removeProviderTable });
     } catch (err) {
       r = { success: false, message: err instanceof Error ? err.message : String(err) };
     }
@@ -232,7 +236,16 @@ const commandRunners: Record<string, CommandRunner> = {
       code = 1;
     }
     if (r.success) {
-      console.log("Codex integration is OFF and plain `codex` now runs natively. Switch back with: ocx restore back");
+      const retained = "retainedCodexProviderTable" in r ? r.retainedCodexProviderTable : undefined;
+      if (retained) {
+        console.log("Codex integration is OFF and plain `codex` now runs natively.");
+        console.log("The following lines remain in $CODEX_HOME/config.toml because conversations already tagged opencodex resolve their provider only through this table:");
+        console.log(retained.lines.join("\n"));
+        console.log(`Follow-up: ${retained.followUp}`);
+        console.log("Switch back with: ocx restore back");
+      } else {
+        console.log("Codex integration is OFF and plain `codex` now runs natively. Switch back with: ocx restore back");
+      }
       console.log(`Note: ${OCX_NATIVE_REPLAY_RECOVERY_NOTE}`);
     } else {
       console.error("Plain `codex` was not fully restored. Inspect $CODEX_HOME/config.toml before using native Codex.");
@@ -952,6 +965,60 @@ export function decideStartWithLiveOwner(input: {
   return input.ocxService === "1" ? "service-stay-out" : "refuse";
 }
 
+/** What `chooseListenPort` does when the preferred port stayed busy through prefer-retry. */
+export type BusyPreferredPortDecision =
+  | "hop"
+  | "refuse-live-proxy"
+  | "service-stay-out"
+  | "refuse-unidentified-holder";
+
+/**
+ * Pure decision for a soft `start` whose preferred port is busy and whose only remaining
+ * option is an ephemeral port.
+ *
+ * The hop exists so a first start is not defeated by a port this machine happens to be
+ * using. What it must never be is a silent answer to "someone is already here": a start
+ * that hops takes over this home's pid and runtime-port records and re-points Codex at
+ * itself, so hopping past a live opencodex leaves two proxies running and the editor
+ * talking to the one the user did not mean (#5004). The hop path never asked who held the
+ * port, and `findLiveProxy` returning null — a stale record, a probe that lost a race, a
+ * loopback family split — was enough to reach it.
+ *
+ * So the decision is made from the holder's own answer rather than from this home's
+ * bookkeeping, and both outcomes stop the start. An opencodex answer is the duplicate this
+ * closes. A holder that does not answer as opencodex is deliberately NOT called foreign:
+ * an identity probe returns the same nothing for a foreign server, an unreachable one, and
+ * one that lost a race, so all the start can honestly say is that the port it was told to
+ * use is taken by something it could not identify — and moving to an arbitrary port is the
+ * one response that hides that from the user while re-pointing Codex. An explicit
+ * `--port` never reaches here (`findAvailablePort` refuses the fallback instead), and a
+ * configured port of 0 is a request for an ephemeral port, not a collision.
+ *
+ * Service-wrapper context keeps the semantics `decideStartWithLiveOwner` gives it: a
+ * healthy proxy on the port means the port is served, and the wrapper's
+ * `if %ERRORLEVEL% NEQ 0` loop must see a zero exit rather than respawn every 5 seconds.
+ */
+export function decideBusyPreferredPort(input: {
+  preferredPort: number;
+  selectedPort: number;
+  hardPin: boolean;
+  holderIsOpencodex: boolean;
+  ocxService: string | undefined;
+}): BusyPreferredPortDecision {
+  // Port 0 (or an unusable preference) asked the OS to choose; nothing was taken away.
+  if (input.preferredPort <= 0) return "hop";
+  // The preferred port was obtained — no hop happened, nothing to decide.
+  if (input.selectedPort === input.preferredPort) return "hop";
+  // Defensive: a hard pin cannot reach a different port, and if it ever did, the pin is
+  // the user's explicit instruction and not something to answer with a refusal here.
+  if (input.hardPin) return "hop";
+  if (input.holderIsOpencodex) {
+    // Same sentinel rule as decideStartWithLiveOwner: only the exact "1" is service context.
+    return input.ocxService === "1" ? "service-stay-out" : "refuse-live-proxy";
+  }
+  return "refuse-unidentified-holder";
+}
+
 export function resolveDispatchCommand(command: string | undefined): string | undefined {
   if (command === undefined) return undefined;
   if (Object.prototype.hasOwnProperty.call(commandRunners, command)) return command;