@bitkyc08/opencodex 2.86.0 → 2.88.0

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

@@ -1,5 +1,6 @@
 import {
   inspectCodexCliInstall,
+  observeCodexCliSelectedCommand,
   type CodexCliInstallProvenanceDeps,
   type CodexCliInstallReport,
 } from "../codex/cli-install-provenance";
@@ -11,20 +12,29 @@ import type {
   CodexCliInstallationSnapshot,
   CodexCliInstallationTargetDerivation,
 } from "../codex/cli-installation-targets";
+import {
+  createCodexCliUpdatePlan,
+  type CodexCliUpdateChannel,
+  type CodexCliUpdatePlan,
+  type CodexCliUpdatePlanDeps,
+} from "../codex/cli-update-plan";
+import {
+  type ResolveCodexRuntimeDeps,
+  type ResolveCodexRuntimeResult,
+} from "../codex/runtime";
 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 attest [--json]
-  ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]`;
+  ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]
+  ocx system codex-cli-update plan [--channel latest] [--json]`;
 
-export type ParsedCodexCliUpdateArgs = Readonly<{
-  json: boolean;
-}> | Readonly<{
-  json: boolean;
-  attest: CodexCliInstallationIdentityInput | "selected";
-}>;
+export type ParsedCodexCliUpdateArgs =
+  | Readonly<{ action: "check"; json: boolean }>
+  | Readonly<{ action: "plan"; json: boolean; channel: CodexCliUpdateChannel }>
+  | Readonly<{ json: boolean; attest: CodexCliInstallationIdentityInput | "selected" }>;
 
 export interface CodexCliUpdateCommandDeps {
   readonly inspectInstall?: (deps: CodexCliInstallProvenanceDeps) => Promise<CodexCliInstallReport>;
@@ -32,6 +42,8 @@ export interface CodexCliUpdateCommandDeps {
   readonly deriveInstallationInput?: (
     snapshot: CodexCliInstallationSnapshot,
   ) => Promise<CodexCliInstallationTargetDerivation>;
+  readonly createPlan?: (deps: CodexCliUpdatePlanDeps) => Promise<CodexCliUpdatePlan>;
+  readonly resolveSelectedRuntime?: (deps: ResolveCodexRuntimeDeps) => ResolveCodexRuntimeResult;
 }
 
 function identitySummary(report: CodexCliInstallationIdentityReport): string[] {
@@ -68,24 +80,60 @@ function installSummary(report: CodexCliInstallReport): string[] {
   ];
 }
 
+function planSummary(plan: CodexCliUpdatePlan): string[] {
+  const lines = [
+    `applicable: ${plan.applicable ? "yes" : "no"}`,
+    `reason: ${plan.refusal ?? "none"}`,
+    `provenance: ${plan.provenance}`,
+    `installed-version: ${plan.installedVersion ?? "unavailable"}`,
+    `version-evidence: ${plan.versionEvidence}`,
+    `channel: ${plan.channel}`,
+    `target-version: ${plan.targetVersion ?? "unresolved"}`,
+    `target-integrity: ${plan.targetIntegrity ?? "unresolved"}`,
+    `session: ${plan.session.state}${plan.session.matches === null ? "" : ` (${plan.session.matches})`}`,
+  ];
+  if (plan.planId) lines.push(`plan: ${plan.planId}`);
+  if (plan.command) lines.push(`command: ${plan.command.join(" ")} (indicative — a future apply phase verifies the packed tarball and installs the verified file)`);
+  return lines;
+}
+
+/**
+ * Read ``--name value`` and ``--name=value`` alike; both spellings reach this CLI. */
+function optionValue(tokens: readonly string[], index: number, name: string): { value: string; next: number } {
+  const token = tokens[index]!;
+  const inline = `--${name}=`;
+  if (token.startsWith(inline)) {
+    const value = token.slice(inline.length);
+    if (!value) throw new CliUsageError(`--${name} requires a value`, CODEX_CLI_UPDATE_USAGE);
+    return { value, next: index + 1 };
+  }
+  const value = tokens[index + 1];
+  if (value === undefined) throw new CliUsageError(`--${name} requires a value`, CODEX_CLI_UPDATE_USAGE);
+  return { value, next: index + 2 };
+}
+
+function isOption(token: string, name: string): boolean {
+  return token === `--${name}` || token.startsWith(`--${name}=`);
+}
+
 export function parseCodexCliUpdateArgs(argv: readonly string[]): ParsedCodexCliUpdateArgs {
   // `--json` is accepted in any argv position CLI-wide, so remove it before positional
-  // validation. Requiring `check` at index 0 first would reject `--json check`, which
+  // validation. Requiring the action at index 0 first would reject `--json check`, which
   // automation that puts output flags ahead of the subcommand legitimately produces.
   let json = false;
-  const positional: string[] = [];
+  const rest: string[] = [];
   for (const token of argv) {
     if (isJsonOption(token)) {
       if (json) throw new CliUsageError("--json may be specified only once", CODEX_CLI_UPDATE_USAGE);
       json = true;
       continue;
     }
-    positional.push(token);
+    rest.push(token);
   }
-  if (positional[0] === "attest") {
+  if (rest[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) {
+    if (rest.length === 1) {
       return Object.freeze({ json, attest: "selected" as const });
     }
     const options = new Map<string, keyof CodexCliInstallationIdentityInput>([
@@ -93,12 +141,12 @@ export function parseCodexCliUpdateArgs(argv: readonly string[]): ParsedCodexCli
       ["--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]!);
+    for (let index = 1; index < rest.length; index += 2) {
+      const key = options.get(rest[index]!);
       if (!key || input[key] !== undefined) {
         throw new CliUsageError("unsupported or duplicate attest option", CODEX_CLI_UPDATE_USAGE);
       }
-      const value = positional[index + 1];
+      const value = rest[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);
@@ -112,13 +160,78 @@ export function parseCodexCliUpdateArgs(argv: readonly string[]): ParsedCodexCli
       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 or attest", CODEX_CLI_UPDATE_USAGE);
+  const action = rest[0];
+  if (action !== "check" && action !== "plan") {
+    throw new CliUsageError("codex-cli-update action must be check, attest or plan", CODEX_CLI_UPDATE_USAGE);
+  }
+
+  if (action === "check") {
+    if (rest.length > 1) throw new CliUsageError("unsupported codex-cli-update argument", CODEX_CLI_UPDATE_USAGE);
+    return Object.freeze({ action, json });
   }
-  if (positional.length > 1) {
-    throw new CliUsageError("unsupported codex-cli-update argument", CODEX_CLI_UPDATE_USAGE);
+
+  if (action === "plan") {
+    let channel: CodexCliUpdateChannel = "latest";
+    let seen = false;
+    let index = 1;
+    while (index < rest.length) {
+      const token = rest[index]!;
+      if (!isOption(token, "channel")) {
+        throw new CliUsageError("unsupported codex-cli-update argument", CODEX_CLI_UPDATE_USAGE);
+      }
+      if (seen) throw new CliUsageError("--channel may be specified only once", CODEX_CLI_UPDATE_USAGE);
+      const read = optionValue(rest, index, "channel");
+      // Only the stable channel is offered. A preview channel would need its own
+      // provenance story before it may install anything on the operator's behalf.
+      if (read.value !== "latest") throw new CliUsageError("--channel must be latest", CODEX_CLI_UPDATE_USAGE);
+      channel = read.value;
+      seen = true;
+      index = read.next;
+    }
+    return Object.freeze({ action, json, channel });
   }
-  return Object.freeze({ json });
+
+  // Unreachable: the action check above already rejected every other verb, but the
+  // fallthrough keeps the parser total for the type checker.
+  throw new CliUsageError("unsupported codex-cli-update action", CODEX_CLI_UPDATE_USAGE);
+}
+
+/**
+ * Inspection inputs for this one-shot CLI process.
+ *
+ * The published Node launcher supplies a proof-bound snapshot of configured candidate
+ * evidence, not selected-runtime admission. A direct Bun or source launch has no such
+ * proof, so nothing ambient or persisted is inspected at all.
+ */
+function inspectionDeps(commandDeps: CodexCliUpdateCommandDeps): CodexCliInstallProvenanceDeps {
+  const trusted = trustedNodeLauncherContext()?.codexCliInspectionEnv;
+  if (!trusted || trusted.managerRoots === null) return { env: { PATH: "" }, configDir: "." };
+  // Attestation also requires the runtime resolver to pick the snapshot's
+  // candidate. probeVersion: false keeps this read-only — no codex --version
+  // executes on a check/plan path — while still refusing attestation when the
+  // resolver would settle on a different executable.
+  const selectedCommand = observeCodexCliSelectedCommand({
+    env: {
+      CODEX_CLI_PATH: trusted.codexCliPath ?? undefined,
+      PATH: trusted.path ?? undefined,
+      PATHEXT: trusted.pathExt ?? undefined,
+    },
+    configDir: trusted.configDir,
+  }, commandDeps.resolveSelectedRuntime);
+  return {
+    env: {
+      ...trusted.managerRoots,
+      CODEX_CLI_PATH: trusted.codexCliPath ?? undefined,
+      PATH: trusted.path ?? undefined,
+      PATHEXT: trusted.pathExt ?? undefined,
+    },
+    configDir: trusted.configDir,
+    // The snapshot is proof-bound to the launcher, but the report may only attest
+    // the environment candidate when the resolver picks the same canonical path —
+    // managed requires both.
+    selectionAttested: true,
+    selectedCommand,
+  };
 }
 
 export async function handleCodexCliUpdateCommand(
@@ -136,7 +249,9 @@ export async function handleCodexCliUpdateCommand(
     }
     throw error;
   }
-  return runCliAction(async () => {
+  // A refusal or an unapplied update is a legitimate answer rather than a crash, so the
+  // outcome exit code is decided here and only a thrown error is left to runCliAction.
+  const code = await runCliAction(async () => {
     if ("attest" in parsed) {
       let report: CodexCliInstallationIdentityReport;
       try {
@@ -167,25 +282,20 @@ export async function handleCodexCliUpdateCommand(
       printData(report, parsed.json, identitySummary(report));
       return;
     }
-    const trustedInspectionEnv = trustedNodeLauncherContext()?.codexCliInspectionEnv;
-    const inspectionDeps: CodexCliInstallProvenanceDeps = trustedInspectionEnv
-      && trustedInspectionEnv.managerRoots !== null ? {
-      env: {
-        ...trustedInspectionEnv.managerRoots,
-        CODEX_CLI_PATH: trustedInspectionEnv.codexCliPath ?? undefined,
-        PATH: trustedInspectionEnv.path ?? undefined,
-        PATHEXT: trustedInspectionEnv.pathExt ?? undefined,
-      },
-      configDir: trustedInspectionEnv.configDir,
-      // This is a fresh one-shot CLI process. Its proof-bound launcher snapshot
-      // supplies configured candidate evidence, not selected-runtime admission.
-    } : {
-      // Direct Bun/source launches have no pre-dotenv proof. Do not inspect
-      // ambient or persisted candidate state at all.
-      env: { PATH: "" },
-      configDir: ".",
-    };
-    const report = await (deps.inspectInstall ?? inspectCodexCliInstall)(inspectionDeps);
-    printData(report, parsed.json, installSummary(report));
+    if (parsed.action === "check") {
+      const report = await (deps.inspectInstall ?? inspectCodexCliInstall)(inspectionDeps(deps));
+      printData(report, parsed.json, installSummary(report));
+      return;
+    }
+    if (parsed.action === "plan") {
+      const plan = await (deps.createPlan ?? createCodexCliUpdatePlan)({
+        channel: parsed.channel,
+        inspectionDeps: inspectionDeps(deps),
+        inspect: deps.inspectInstall,
+      });
+      printData(plan, parsed.json, planSummary(plan));
+      return;
+    }
   });
+  return code;
 }

package/src/cli/codex-provider.ts

@@ -0,0 +1,44 @@
+import { allowCodexProviderRouting, approvedCodexProviders, previewCodexProviderConsent, restoreApprovedCodexProviders } from "../codex/provider-routing";
+import { interactiveConfirm } from "./interactive-confirm";
+import { terminalSafeError, terminalSafeText } from "./runtime-api";
+
+export const CODEX_PROVIDER_USAGE = "Usage: ocx codex-provider <status|allow <id> [--yes]|revoke <id>>";
+
+export async function handleCodexProviderCommand(args: string[]): Promise<number> {
+  const [verb, id, flag] = args;
+  if (verb === "status" && args.length === 1) {
+    console.log(JSON.stringify({ approvedProviders: approvedCodexProviders() }));
+    return 0;
+  }
+  if ((verb !== "allow" && verb !== "revoke") || !id || args.length > 3
+    || (flag !== undefined && (verb !== "allow" || flag !== "--yes"))) {
+    console.error(CODEX_PROVIDER_USAGE);
+    return 1;
+  }
+  try {
+    if (verb === "revoke") {
+      restoreApprovedCodexProviders(id);
+      console.log(`Routing consent revoked for ${terminalSafeText(id)}; any unchanged managed URL was restored.`);
+      return 0;
+    }
+    const expected = previewCodexProviderConsent(id);
+    console.log(`OpenCodex will manage only base_url for Codex provider ${terminalSafeText(id)} in the selected CODEX_HOME.`);
+    console.log("Start/sync will route it to the local proxy; stop/restore will restore its original URL. Provider identity, transport settings and history stay unchanged.");
+    if (flag !== "--yes") {
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.error("Explicit consent required: use an interactive terminal or pass --yes with the exact provider ID.");
+        return 1;
+      }
+      if (!await interactiveConfirm({ question: "Allow this provider's routing to be managed?", defaultYes: false })) {
+        console.log("Cancelled; no consent or routing changes were saved.");
+        return 0;
+      }
+    }
+    allowCodexProviderRouting(id, expected);
+    console.log("Consent saved. Run ocx start or ocx sync to apply routing; use ocx codex-provider revoke <id> to undo consent.");
+    return 0;
+  } catch (error) {
+    console.error(terminalSafeError(error));
+    return 1;
+  }
+}

package/src/cli/combo-input.ts

@@ -8,8 +8,9 @@ type ComboInput = {
   imageInput?: "auto" | "disabled";
   reasoningEffortMode?: "strict" | "adaptive";
   nativeAlias?: boolean;
+  allowMeteredTargets?: boolean;
 };
-const TARGET_KEYS = new Set(["provider", "model", "weight", "reasoningEfforts", "modelProfile", "lastResort"]);
+const TARGET_KEYS = new Set(["provider", "model", "weight", "reasoningEfforts", "modelProfile", "lastResort", "metered"]);
 
 export function parseComboTargets(value: unknown): Array<Record<string, unknown>> {
   if (!Array.isArray(value) || value.length === 0) throw new CliUsageError("Targets input must be a nonempty array");
@@ -41,6 +42,9 @@ export function parseComboTargets(value: unknown): Array<Record<string, unknown>
     if (Object.hasOwn(target, "lastResort") && typeof target.lastResort !== "boolean") {
       throw new CliUsageError("Target lastResort must be a boolean");
     }
+    if (Object.hasOwn(target, "metered") && typeof target.metered !== "boolean") {
+      throw new CliUsageError("Target metered must be a boolean");
+    }
     // Preserve raw slashes, target order, explicit false and omitted metadata.
     return { ...target };
   });
@@ -70,6 +74,10 @@ export async function prepareComboInput(args: string[], deps: RuntimeApiDeps = {
   const image = takeOptionWithSyntax(args, "--image-input")?.value;
   const reasoning = takeOptionWithSyntax(args, "--reasoning-effort-mode")?.value;
   const nativeAlias = takeNativeAlias(args);
+  const metered = takeOptionWithSyntax(args, "--allow-metered-targets")?.value;
+  if (metered !== undefined && metered !== "on" && metered !== "off") {
+    throw new CliUsageError("--allow-metered-targets must be on or off");
+  }
   if (file !== undefined && args.some(arg => arg === "--targets" || arg.startsWith("--targets="))) {
     throw new CliUsageError("--targets-file cannot be combined with --targets");
   }
@@ -84,5 +92,6 @@ export async function prepareComboInput(args: string[], deps: RuntimeApiDeps = {
     ...(image === undefined ? {} : { imageInput: image }),
     ...(reasoning === undefined ? {} : { reasoningEffortMode: reasoning }),
     ...(nativeAlias === undefined ? {} : { nativeAlias }),
+    ...(metered === undefined ? {} : { allowMeteredTargets: metered === "on" }),
   };
 }

package/src/cli/combo-result.ts

@@ -33,7 +33,7 @@ function publicCombo(value: unknown): Record<string, unknown> {
     } else if (Object.hasOwn(RANGES, key)) {
       const [min, max] = RANGES[key]!;
       if (typeof child !== "number" || !Number.isSafeInteger(child) || child < min || child > max) invalid();
-    } else if (key === "nativeAlias") {
+    } else if (key === "nativeAlias" || key === "allowMeteredTargets") {
       if (typeof child !== "boolean") invalid();
     } else invalid();
     result[key] = child;

package/src/cli/combo.ts

@@ -23,7 +23,7 @@ const USAGE = `Usage:
       [--strategy <failover|round-robin|random|least-used|reset-window|jev>] [--sticky <1-100|->]
       [--effort <low|medium|high|xhigh|max|ultra|->] [--effort-mode <fallback|force|->]
       (force overrides valid client effort and can increase cost/latency) [--alias <name|->]
-      [--native-alias [on|off]] [--display-name <label|->]
+      [--native-alias [on|off]] [--allow-metered-targets <on|off>] [--display-name <label|->]
       [--image-input <auto|disabled>] [--reasoning-effort-mode <strict|adaptive>]
       [--decision-provider <provider|-> | --decision-model <route|->] [--decision-timeout <ms|->]
       (jev only; the provider must be a configured jev-decision row)
@@ -160,6 +160,7 @@ async function set(argv: string[], deps: RuntimeApiDeps): Promise<number> {
   if (effortMode !== undefined) combo.defaultEffortMode = effortMode === "-" ? "fallback" : effortMode;
   if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
   if (additional.nativeAlias !== undefined) combo.nativeAlias = additional.nativeAlias;
+  if (additional.allowMeteredTargets !== undefined) combo.allowMeteredTargets = additional.allowMeteredTargets;
   if (additional.imageInput !== undefined) combo.imageInput = additional.imageInput;
   if (additional.reasoningEffortMode !== undefined) combo.reasoningEffortMode = additional.reasoningEffortMode;
   if (displayName !== undefined) combo.displayName = displayName === "-" ? "" : displayName;

package/src/cli/cross-home-owner.ts

@@ -14,6 +14,7 @@ import { readClientConnectionState } from "../client/state";
 import { findManagedRegion, resolveGrokHome } from "../grok/inject";
 import { providerTableString } from "../codex/injected-marker";
 import { isLocalAttestationSecret } from "../lib/local-management-attestation";
+import { isProtectedHomeUnderTest } from "../lib/test-home-guard";
 import { readOwnerRegistry } from "../config/owner-registry";
 import {
   classifyHealthz,
@@ -25,6 +26,7 @@ import {
 } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
 import type { RuntimePortState } from "../config/process-state";
+import { loopbackFamilyAvailability } from "./loopback-family";
 
 const MAX_HINT_BYTES = 256 * 1024;
 // Far above any real Grok config; discovery must not stall startup when Grok sync is off.
@@ -127,13 +129,19 @@ function loopbackPort(raw: string | null): number | null {
   }
 }
 
+type CrossHomeOwnerOptions = {
+  homeDir?: string;
+  io?: LivenessIo;
+  loopbackAvailabilityFn?: typeof loopbackFamilyAvailability;
+};
+
 /** Returns only a different process with an identity-checked /healthz response. */
-export async function findCrossHomeOwner(options: { homeDir?: string; io?: LivenessIo } = {}): Promise<number | null> {
+export async function findCrossHomeOwner(options: CrossHomeOwnerOptions = {}): Promise<number | null> {
   const verdict = await findCrossHomeOwnerDetailed(options);
   return verdict.kind === "owner" ? verdict.port : null;
 }
 
-export async function findCrossHomeOwnerDetailed(options: { homeDir?: string; io?: LivenessIo } = {}): Promise<CrossHomeOwnerVerdict> {
+export async function findCrossHomeOwnerDetailed(options: CrossHomeOwnerOptions = {}): Promise<CrossHomeOwnerVerdict> {
   const io = options.io ?? {};
   const nowFn = io.nowFn ?? Date.now;
   const timeoutMs = io.timeoutMs ?? START_OWNERSHIP_LIVENESS.timeoutMs ?? 1_500;
@@ -160,7 +168,7 @@ export async function findCrossHomeOwnerDetailed(options: { homeDir?: string; io
   };
 
   const defaultHome = join(options.homeDir ?? homedir(), ".opencodex");
-  recordHome(defaultHome);
+  if (options.homeDir !== undefined || !isProtectedHomeUnderTest(defaultHome)) recordHome(defaultHome);
   // The shared registry is what lets one custom home find another: every runtime
   // that published a runtime record registered its home beside the shared clients.
   const registry = readOwnerRegistry();
@@ -204,6 +212,8 @@ export async function findCrossHomeOwnerDetailed(options: { homeDir?: string; io
   }
 
   const queue = [...candidates];
+  const availability = new Map<string, ReturnType<typeof loopbackFamilyAvailability>>();
+  const checkAvailability = options.loopbackAvailabilityFn ?? loopbackFamilyAvailability;
   const probed = new Set<number>();
   for (const port of queue) {
     if (probed.has(port)) continue;
@@ -224,6 +234,11 @@ export async function findCrossHomeOwnerDetailed(options: { homeDir?: string; io
         noteIndeterminate(port, "ownership discovery ran out of its shared time budget");
         break;
       }
+      // Disabled loopback IPv6 can route ::1 off-host and time out. An ephemeral
+      // local bind proves address absence without treating an available family's
+      // timeout as empty. Unknown bind failures retain the existing probes.
+      if (!availability.has(hostname)) availability.set(hostname, checkAvailability(hostname));
+      if (availability.get(hostname) === "unavailable") continue;
       const identity = await proxyIdentityAt(port, { hostname }, probeIo);
       if (identity === null) {
         // A null identity is not "free": distinguish a unanimous connect refusal
@@ -291,33 +306,35 @@ export async function findCrossHomeOwnerDetailed(options: { homeDir?: string; io
 }
 
 /** Mark this process before any shared-client write when another home owns the clients. */
-export async function markCrossHomeSibling(): Promise<boolean> {
-  const verdict = await findCrossHomeOwnerDetailed();
+export async function markCrossHomeSibling(
+  options: Parameters<typeof findCrossHomeOwnerDetailed>[0] = {},
+): Promise<boolean> {
+  const verdict = await findCrossHomeOwnerDetailed(options);
   if (verdict.kind === "none") return false;
-  if (verdict.port === null) throw new Error("Shared-client owner could not be located; refusing startup before any shared-client write.");
   if (verdict.kind === "indeterminate") {
-    // Fail closed: an owner the reader could not verify still owns the shared
-    // writes. Marking the best port hint keeps every sibling gate engaged even
-    // while the answer stays unproven (#6198).
-    console.warn(
-      "A shared-client owner could not be verified (" + verdict.reason + "); "
-      + "treating this instance as a sibling so Codex, Grok and Claude configs are left alone.",
+    // A missed probe is not proof of a sibling topology. Refuse before publication
+    // so the service can retry discovery without freezing uncertainty for its lifetime.
+    throw new Error(
+      `Shared-client owner could not be verified (${verdict.reason}); `
+      + "refusing startup before any shared-client write. Retry startup after discovery recovers.",
     );
   }
-  const port = verdict.port;
-  markSiblingStart(port);
+  markSiblingStart(verdict.port);
   return true;
 }
 
 /** A live proxy in this home can publish its sibling owner even while that owner is down. */
-export async function markLiveHomeSibling(live: { pid: number | null; port: number }): Promise<boolean> {
+export async function markLiveHomeSibling(
+  live: { pid: number | null; port: number },
+  options: Parameters<typeof findCrossHomeOwnerDetailed>[0] = {},
+): Promise<boolean> {
   const runtime = readRuntimePort();
   if (live.pid !== null && runtime?.pid === live.pid && runtime.port === live.port
     && runtime.siblingOfPort !== undefined && runtime.siblingOfPort !== live.port) {
     markSiblingStart(runtime.siblingOfPort);
     return true;
   }
-  const verdict = await findCrossHomeOwnerDetailed();
+  const verdict = await findCrossHomeOwnerDetailed(options);
   if (verdict.kind === "none" || verdict.port === live.port) return false;
   if (verdict.port === null) throw new Error("Shared-client owner could not be located; refusing startup before any shared-client write.");
   markSiblingStart(verdict.port);

package/src/cli/dispatch.ts

@@ -370,19 +370,32 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   login: async deps => {
     const loginArgs = deps.args.slice(1);
+    // `--headless` is the only flag this command takes; the provider is the first bare word, so
+    // `ocx login --headless anthropic` and `ocx login anthropic --headless` mean the same thing.
+    // It is deliberately not `--code`: that name carries a secret value everywhere else in the
+    // CLI (`ocx account login <provider> --code <value>`) and its operand is scrubbed from stderr.
+    const codeMode = loginArgs.includes("--headless");
+    const positional = loginArgs.filter(arg => !arg.startsWith("--"));
     // 'ocx login codex' is the command people type first, and until now it answered with
     // the full provider wall because the Codex pool lives behind 'ocx account login'.
     // Route the three Codex spellings to that flow instead of making the user discover
     // a second noun. Everything else stays on the local OAuth/API-key path.
     const { isCodexAccountLoginName, handleAccountAuthCommand } = await import("./account-auth");
-    if (isCodexAccountLoginName(loginArgs[0] ?? "")) {
+    if (isCodexAccountLoginName(positional[0] ?? "")) {
+      // `--headless` is the OAuth code-display mode, which Codex does not have; account-auth
+      // would reject the flag as an unexpected argument. Codex's headless path is the device-code
+      // login, so point there instead.
+      if (codeMode) {
+        console.error("Codex has no code-display login. For a headless host use: ocx account login codex --device");
+        return 1;
+      }
       // null means "unknown subcommand", which "login" never is; the coalesce exists because
       // the shared signature serves callers that do pass an unknown one.
       const code = await handleAccountAuthCommand("login", loginArgs, { findLiveProxy: deps.findLiveProxy });
       return code ?? 1;
     }
     const { handleLogin } = await import("../oauth/login-cli");
-    await handleLogin(loginArgs[0]);
+    await handleLogin(positional[0], {}, { codeMode });
     return 0;
   },
   logout: async deps => {
@@ -461,11 +474,15 @@ const commandRunners: Record<string, CommandRunner> = {
       code = 1;
       console.error("Codex sync did not complete. Fix the reported Codex config issue and retry.");
     }
-    // Only warn/restart when a catalog or models_cache write actually happened. This is
+    // Catalog/model-cache writes retain their warning/restart handling. This is
     // deliberately not an `else`: refreshCodexModelCatalog runs before injectCodexConfig,
     // so a sync can fail (`ok: false`) after the catalog was already rewritten — which is
     // exactly when a long-lived app-server is holding the stale list.
-    if (synced.catalogWritten || synced.cacheSynced) {
+    // A configuration-only change also needs a reload, but only when explicitly
+    // requested. A successful no-op or refused write is never restart authority.
+    const requestedConfigRestart = (restartScope.appServers || restartScope.desktopApp)
+      && synced.ok && synced.configChanged === true;
+    if (synced.catalogWritten || synced.cacheSynced || requestedConfigRestart) {
       await handleRestartScopeAfterWrite(restartScope, console);
     }
     // `ocx sync` is a direct CLI path; it does not call the management
@@ -945,6 +962,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleLabCommand } = await import("./lab");
     return await handleLabCommand(deps.args.slice(1));
   },
+  "codex-provider": async deps => {
+    const { handleCodexProviderCommand } = await import("./codex-provider");
+    return await handleCodexProviderCommand(deps.args.slice(1));
+  },
   chatgpt: async deps => {
     const { handleChatgptCommand } = await import("./chatgpt-command");
     return await handleChatgptCommand(deps.args.slice(1));

package/src/cli/doctor.ts

@@ -1160,6 +1160,11 @@ async function fetchExposedModelIds(live: LiveProxy, fetchFn: ExposedModelsFetch
       if (id.length === 0) continue;
       if (id.length > EXPOSED_MODEL_ID_MAX_LENGTH) return null;
       ids.add(id);
+      const nativeId = (row as { native_id?: unknown }).native_id;
+      if (nativeId !== undefined) {
+        if (typeof nativeId !== "string" || nativeId.length > EXPOSED_MODEL_ID_MAX_LENGTH) return null;
+        if (nativeId.length > 0) ids.add(nativeId);
+      }
     }
     return ids;
   } catch {
@@ -1467,7 +1472,7 @@ export async function runDoctor(args: string[] = []): Promise<void> {
 
   // Observe-only and warning-level: a bypassed Desktop first-party install still serves the
   // CLI and every non-Desktop client, so this never records a doctor failure.
-  const desktopSystemProxyLines = formatDesktopSystemProxyLines(collectDesktopSystemProxy(doctorConfig));
+  const desktopSystemProxyLines = formatDesktopSystemProxyLines(await collectDesktopSystemProxy(doctorConfig));
   if (desktopSystemProxyLines.length > 0) {
     console.log("\nClaude Desktop first-party vs Windows system proxy");
     for (const line of desktopSystemProxyLines) console.log(line);