@iislee/opencodex 2.31.0 → 2.35.0

package/src/cli/storage.ts

@@ -0,0 +1,234 @@
+/**
+ * `ocx storage` — the archived-session cleanup, trash, and cleanup-policy surface (wp7).
+ *
+ * Every route here existed with no CLI caller, so reclaiming disk space was dashboard-only.
+ * Three of them delete or move operator data, and the rules for those are deliberate:
+ *
+ * 1. **Default to preview.** `ocx storage cleanup --percent N` runs the preview route and prints
+ *    what WOULD be freed, then exits 0 having mutated nothing.
+ * 2. **`--yes` is required to mutate.** There is no interactive prompt: an agent cannot answer
+ *    one, and a prompt an agent can answer is not a safety boundary.
+ * 3. **`--json` on the preview emits the candidate list**, so an agent can decide from data
+ *    rather than from a sentence.
+ *
+ * This is the opposite of the GitHub star POST, which no flag can authorize: cleanup spends the
+ * operator's DATA, which they can delegate, while starring spends their IDENTITY, which they
+ * cannot delegate to an agent.
+ */
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx storage report [--json]
+  ocx storage cleanup --percent <0-100> [--mode <quarantine|permanent>] [--yes] [--json]
+  ocx storage trash [list] [--json]
+  ocx storage trash restore <entry-id> [--yes] [--json]
+  ocx storage policy [show] [--json]
+  ocx storage policy set [--enabled <true|false>] [--percent <0-100>]
+      [--mode <quarantine|permanent>] [--schedule <startup|daily|weekly|manual>] [--json]
+  ocx storage policy run [--yes] [--json]
+
+Cleanup and restore MUTATE operator data and require --yes.
+Without --yes, cleanup prints the preview and changes nothing.`;
+
+/** The digest binds a run to the preview it was authorized against. */
+interface CleanupPreview {
+  percent?: number;
+  count?: number;
+  bytes?: number;
+  digest?: string;
+  candidates?: { relPath?: string; bytes?: number }[];
+}
+
+function mib(bytes: number | undefined): string {
+  if (typeof bytes !== "number" || !Number.isFinite(bytes)) return "unknown size";
+  return `${(bytes / 1024 / 1024).toFixed(1)} MiB`;
+}
+
+function previewLines(preview: CleanupPreview): string[] {
+  const lines = [
+    `Would remove ${preview.count ?? 0} archived session file(s), freeing ${mib(preview.bytes)}.`,
+  ];
+  for (const candidate of (preview.candidates ?? []).slice(0, 10)) {
+    lines.push(`  ${candidate.relPath ?? "(unnamed)"}  ${mib(candidate.bytes)}`);
+  }
+  const shown = Math.min((preview.candidates ?? []).length, 10);
+  if ((preview.count ?? 0) > shown) lines.push(`  … and ${(preview.count ?? 0) - shown} more`);
+  lines.push("Nothing was deleted. Re-run with --yes to apply.");
+  return lines;
+}
+
+async function cleanup(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const confirmed = takeFlag(args, "--yes");
+  const percent = takeIntegerOption(args, "--percent", { min: 0 });
+  const mode = takeOption(args, "--mode") ?? "quarantine";
+  rejectArgs(args, USAGE);
+
+  if (percent === undefined) throw new CliUsageError("--percent is required", USAGE);
+  if (percent > 100) throw new CliUsageError("--percent must be between 0 and 100", USAGE);
+  if (mode !== "quarantine" && mode !== "permanent") {
+    throw new CliUsageError("--mode must be quarantine or permanent", USAGE);
+  }
+
+  // The preview runs in BOTH paths, and not only to be friendly: the mutating route requires the
+  // digest this call returns and rejects a stale one with 409 `stale_preview`. So the confirmed
+  // path cannot skip it, which conveniently means --yes and no --yes agree on what they mean.
+  const preview = await runtimeRequest<CleanupPreview>("/api/storage/cleanup/preview", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ percent }),
+  }, deps);
+
+  if (!confirmed) {
+    printData(preview, wantsJson, previewLines(preview));
+    return;
+  }
+
+  if (!preview.digest) {
+    // Refuse rather than send an empty digest: the server would reject it, but a clear local
+    // message beats a 400 that looks like a bug in the verb.
+    throw new CliUsageError("the preview returned no digest, so the cleanup cannot be authorized", USAGE);
+  }
+
+  const result = await runtimeRequest("/api/storage/cleanup", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ percent, mode, digest: preview.digest }),
+  }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function trash(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const action = argv[0] && !argv[0].startsWith("-") ? argv[0] : "list";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+
+  if (action === "list") {
+    const args = [...rest];
+    const wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/storage/trash", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+
+  if (action !== "restore") throw new CliUsageError(`unknown trash action ${action}`, USAGE);
+
+  const args = [...rest];
+  const wantsJson = takeFlag(args, "--json");
+  const confirmed = takeFlag(args, "--yes");
+  const id = args.shift();
+  rejectArgs(args, USAGE);
+  if (!id) throw new CliUsageError("a trash entry id is required", USAGE);
+
+  // Restore moves files back and reconciles database rows, and can collide with an existing
+  // destination, so it is gated like cleanup rather than treated as a read.
+  if (!confirmed) {
+    throw new CliUsageError(`restoring ${id} modifies stored sessions; pass --yes to confirm`, USAGE);
+  }
+
+  const result = await runtimeRequest("/api/storage/trash/restore", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ id }),
+  }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function policy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const action = argv[0] && !argv[0].startsWith("-") ? argv[0] : "show";
+  const rest = argv[0] && !argv[0].startsWith("-") ? argv.slice(1) : argv;
+
+  if (action === "show") {
+    const args = [...rest];
+    const wantsJson = takeFlag(args, "--json");
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest("/api/storage/cleanup-policy", {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+
+  if (action === "set") {
+    const args = [...rest];
+    const wantsJson = takeFlag(args, "--json");
+    const enabled = takeOption(args, "--enabled");
+    const percent = takeIntegerOption(args, "--percent", { min: 0 });
+    const mode = takeOption(args, "--mode");
+    const schedule = takeOption(args, "--schedule");
+    rejectArgs(args, USAGE);
+
+    if (enabled !== undefined && enabled !== "true" && enabled !== "false") {
+      throw new CliUsageError("--enabled must be true or false", USAGE);
+    }
+    const body: Record<string, unknown> = {};
+    if (enabled !== undefined) body.enabled = enabled === "true";
+    if (percent !== undefined) body.percent = percent;
+    if (mode !== undefined) body.mode = mode;
+    if (schedule !== undefined) body.schedule = schedule;
+    if (Object.keys(body).length === 0) {
+      throw new CliUsageError("policy set needs at least one of --enabled, --percent, --mode, --schedule", USAGE);
+    }
+    // Values are NOT re-validated here beyond --enabled's shape. The server owns the mode and
+    // schedule vocabularies and returns a named 400; duplicating them is a second thing to
+    // keep in sync. `enabled` is checked because "--enabled maybe" would otherwise be sent as
+    // `false`, which is a wrong write rather than a rejected one.
+    const result = await runtimeRequest("/api/storage/cleanup-policy", {
+      method: "PUT",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    }, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+
+  if (action !== "run") throw new CliUsageError(`unknown policy action ${action}`, USAGE);
+
+  const args = [...rest];
+  const wantsJson = takeFlag(args, "--json");
+  const confirmed = takeFlag(args, "--yes");
+  rejectArgs(args, USAGE);
+  // `force: true` server-side: this run ignores the schedule and deletes now.
+  if (!confirmed) {
+    throw new CliUsageError("policy run deletes archived sessions now; pass --yes to confirm", USAGE);
+  }
+  const result = await runtimeRequest("/api/storage/cleanup-policy/run", { method: "POST" }, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+export async function handleStorageCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  const hasSub = argv[0] !== undefined && !argv[0].startsWith("-");
+  const sub = hasSub ? argv[0]! : "report";
+  const rest = hasSub ? argv.slice(1) : argv;
+  if (sub === "codex-logs") {
+    // Doctor and the Log Guard guides still document `ocx storage codex-logs …`.
+    // This module owns cleanup/trash/policy; log-guard stays on the observe handler.
+    const { handleObserveCommand } = await import("./observe");
+    return handleObserveCommand(["storage", "codex-logs", ...rest], deps);
+  }
+  return runCliAction(async () => {
+    if (sub === "report") {
+      const args = [...rest];
+      const wantsJson = takeFlag(args, "--json");
+      rejectArgs(args, USAGE);
+      const result = await runtimeRequest("/api/storage", {}, deps);
+      printData(result, wantsJson, summaryLines(result));
+    }
+    else if (sub === "cleanup") await cleanup(rest, deps);
+    else if (sub === "trash") await trash(rest, deps);
+    else if (sub === "policy") await policy(rest, deps);
+    else throw new CliUsageError(`unknown storage command ${sub}`, USAGE);
+  });
+}
+
+export const STORAGE_USAGE = USAGE;

package/src/cli/system-command.ts

@@ -17,6 +17,8 @@ const USAGE = `Usage:
   ocx system startup <health|install-service|install-shim> [--json]
   ocx system diagnostics [--json]
   ocx system sync [--json]
+  ocx system codex-app-server [--json]
+  ocx system codex-restart --yes [--json]
   ocx system update check [--channel <latest|preview>] [--json]
   ocx system update run [--channel <latest|preview>] [--restart <on|off>] --yes [--json]
   ocx system update status <job-id> [--json]`;
@@ -104,6 +106,20 @@ export async function handleSystemCommand(argv: string[], deps: RuntimeApiDeps =
     } else if (sub === "sync") {
       const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
       printData(await runtimeRequest("/api/sync", { method: "POST" }, deps), wantsJson);
+    } else if (sub === "codex-app-server") {
+      // The GUI reads this state directly (gui/src/codex-app-server-state.ts). Without a verb
+      // an agent could not see whether the Codex app-server was reachable at all.
+      const args = [...rest]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
+      printData(await runtimeRequest("/api/system/codex-app-server", {}, deps), wantsJson);
+    } else if (sub === "codex-restart") {
+      // --yes required: this restarts the user's running Codex app-server, so it is exactly the
+      // class of action that must not happen because an agent guessed a subcommand.
+      const args = [...rest];
+      const wantsJson = takeFlag(args, "--json");
+      const yes = takeFlag(args, "--yes");
+      if (!yes) throw new CliUsageError("system codex-restart requires --yes", USAGE);
+      rejectArgs(args, USAGE);
+      printData(await runtimeRequest("/api/system/codex-restart", { method: "POST" }, deps), wantsJson, ["Codex app-server restart requested."]);
     } else if (sub === "update") await update(rest, deps);
     else throw new CliUsageError(`unknown system command ${sub}`, USAGE);
   });

package/src/cli/system-restart-client.ts

@@ -1,4 +1,4 @@
-import { readRuntimePort } from "../config";
+import { readRuntimePort } from "../config/process-state";
 import {
   LOCAL_ATTESTATION_CHALLENGE_HEADER,
   LOCAL_ATTESTATION_PROOF_HEADER,

package/src/cli/usage-report.ts

@@ -0,0 +1,184 @@
+/**
+ * Human rendering for `ocx usage`.
+ *
+ * Kept out of `observe.ts` and away from the shared `summaryLines()` helper on
+ * purpose. `summaryLines()` is a generic depth-1 flattener shared with
+ * storage/memory/debug/claude-inbound/injection; it renders any array as
+ * "N item(s)", which is why every per-model and per-provider cost the server
+ * computes used to vanish before reaching the terminal. Deepening it would
+ * change five unrelated commands.
+ *
+ * Formatting follows the existing CLI house style: dynamic `padEnd` columns
+ * (as in `formatAccountTable`), plain text, no ANSI colour.
+ */
+
+interface CostRow {
+  provider: string;
+  model?: string;
+  requests: number;
+  totalTokens: number;
+  estimatedCostUsd?: number;
+}
+
+interface UsageReportInput {
+  range?: string;
+  surface?: string;
+  since?: number | null;
+  summary?: {
+    requests?: number;
+    totalTokens?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    estimatedCostUsd?: number;
+    unpricedRequests?: number;
+    unmeteredRequests?: number;
+  };
+  models?: CostRow[];
+  providers?: CostRow[];
+  days?: { date: string; requests: number; totalTokens: number; estimatedCostUsd?: number }[];
+  filter?: { provider: string | null; model: string | null; matched: boolean; comboOverlap: boolean };
+  /**
+   * Per-account totals the API already returns and the CLI discarded (#2700).
+   *
+   * Withheld by the server -- sent as `[]` -- whenever a provider or model filter is active,
+   * because account rows are not provider-partitioned in a way the projection could honestly
+   * re-derive (summary.ts, reasoned around :865-872). An empty array therefore means two very
+   * different things, and the renderer must say which.
+   */
+  accounts?: {
+    accountLogLabel: string;
+    ambiguous?: boolean;
+    requests: number;
+    totalTokens: number;
+    estimatedCostUsd?: number;
+  }[];
+}
+
+const MAX_MODEL_ROWS = 10;
+
+function terminalText(value: string): string {
+  return value.replace(/[\x00-\x1f\x7f-\x9f]/g, character => {
+    const code = character.charCodeAt(0);
+    return code <= 0x7f
+      ? `\\x${code.toString(16).padStart(2, "0")}`
+      : `\\u${code.toString(16).padStart(4, "0")}`;
+  });
+}
+
+function count(value: number | undefined): string {
+  return (value ?? 0).toLocaleString("en-US");
+}
+
+/**
+ * Matches the dashboard's `~$` with four fraction digits. Estimates below a
+ * hundredth of a cent still read as a number rather than collapsing to $0.00,
+ * which matters when a single request is being inspected.
+ */
+function usd(value: number | undefined): string {
+  if (typeof value !== "number" || !Number.isFinite(value)) return "—";
+  return `~$${value.toFixed(4)}`;
+}
+
+function table(header: string[], rows: string[][]): string[] {
+  if (rows.length === 0) return [];
+  header = header.map(terminalText);
+  rows = rows.map(row => row.map(terminalText));
+  const widths = header.map((h, i) => Math.max(h.length, ...rows.map(r => (r[i] ?? "").length)));
+  const line = (cols: string[]): string => cols.map((c, i) => (c ?? "").padEnd(widths[i]!)).join("  ").trimEnd();
+  return [line(header), ...rows.map(line)];
+}
+
+function describeScope(data: UsageReportInput): string {
+  const parts = [`Usage — ${data.range ?? "?"}`];
+  if (data.surface && data.surface !== "all") parts.push(`surface=${data.surface}`);
+  if (data.filter?.provider) parts.push(`provider=${data.filter.provider}`);
+  if (data.filter?.model) parts.push(`model=${data.filter.model}`);
+  return terminalText(parts.join(", "));
+}
+
+export function formatUsageReport(data: UsageReportInput): string[] {
+  const summary = data.summary ?? {};
+  const lines: string[] = [describeScope(data), ""];
+
+  if (data.filter && !data.filter.matched) {
+    const what = [data.filter.provider && `provider "${data.filter.provider}"`, data.filter.model && `model "${data.filter.model}"`]
+      .filter(Boolean).join(" and ");
+    lines.push(`No usage recorded for ${terminalText(what)} in this range.`);
+    lines.push("Check the spelling against `ocx usage --json`, or widen --range.");
+    return lines;
+  }
+
+  const tokenSplit = [
+    summary.inputTokens !== undefined ? `in ${count(summary.inputTokens)}` : null,
+    summary.outputTokens !== undefined ? `out ${count(summary.outputTokens)}` : null,
+    summary.cachedInputTokens ? `cached ${count(summary.cachedInputTokens)}` : null,
+  ].filter(Boolean).join(" / ");
+
+  lines.push(`Requests   ${count(summary.requests)}`);
+  lines.push(`Tokens     ${count(summary.totalTokens)}${tokenSplit ? `  (${tokenSplit})` : ""}`);
+  lines.push(`Est. cost  ${usd(summary.estimatedCostUsd)}    API list-price equivalent (this range)`);
+
+  const unpriced = summary.unpricedRequests ?? 0;
+  const unmetered = summary.unmeteredRequests ?? 0;
+  if (unpriced > 0 || unmetered > 0) {
+    // Spelled out because a $0 total is ambiguous otherwise: it can mean "no
+    // spend" or "no price row matched", and those are very different answers.
+    lines.push(`           ${count(unpriced)} unpriced, ${count(unmetered)} unmetered excluded from ~$`);
+  }
+
+  const providers = (data.providers ?? []).filter(row => row.requests > 0);
+  if (providers.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      providers.map(row => [row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+  }
+
+  // Per-account spend (#2700). The two empty cases are distinguished deliberately: printing an
+  // empty table under a filter would repeat the silently-wrong-output defect this unit removes,
+  // because "what did this provider cost me per account" is the most natural way to ask and the
+  // server cannot answer it honestly.
+  const accountFilterActive = Boolean(data.filter?.provider || data.filter?.model);
+  const accounts = (data.accounts ?? []).filter(row => row.requests > 0);
+  if (accountFilterActive) {
+    lines.push("");
+    lines.push("ACCOUNT: not reported under a provider or model filter; run without filters for per-account totals.");
+  } else if (accounts.length > 0) {
+    lines.push("");
+    lines.push(...table(
+      ["ACCOUNT", "REQUESTS", "TOKENS", "EST. COST"],
+      accounts.map(row => [
+        // An ambiguous row aggregates several accounts, so reading it as one account draws the
+        // wrong conclusion. Mark it rather than presenting it as a single identity.
+        row.ambiguous ? `${terminalText(row.accountLogLabel)} (ambiguous)` : terminalText(row.accountLogLabel),
+        count(row.requests),
+        count(row.totalTokens),
+        usd(row.estimatedCostUsd),
+      ]),
+    ));
+  }
+
+  const models = (data.models ?? []).filter(row => row.requests > 0);
+  if (models.length > 0) {
+    lines.push("");
+    const shown = models.slice(0, MAX_MODEL_ROWS);
+    lines.push(...table(
+      ["MODEL", "PROVIDER", "REQUESTS", "TOKENS", "EST. COST"],
+      shown.map(row => [row.model ?? "-", row.provider, count(row.requests), count(row.totalTokens), usd(row.estimatedCostUsd)]),
+    ));
+    if (models.length > shown.length) {
+      lines.push(`... ${models.length - shown.length} more (use --json)`);
+    }
+  }
+
+  if (data.filter?.comboOverlap) {
+    lines.push("");
+    lines.push("Some requests ran as combos, so per-model request counts can overlap. Cost does not.");
+  }
+
+  lines.push("");
+  lines.push("Not a billing receipt. Subscription usage or provider credits may apply instead.");
+  return lines;
+}

package/src/cli/v2.ts

@@ -15,7 +15,7 @@ import { dirname } from "node:path";
 import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
-import { loadConfig, saveConfig } from "../config";
+import { deleteConfigTopLevelKey, loadConfig, saveConfig } from "../config";
 import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
 
 export interface V2CliDeps {
@@ -88,18 +88,24 @@ function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
 
 export function v2StatusLine(enabled: boolean): string {
   return enabled
-    ? "multi_agent_v2: ON — v2 multi-agent surface active"
-    : "multi_agent_v2: OFF — v1 multi-agent surface (default install)";
+    ? "multi_agent_v2: ON — global V2 override active"
+    : "multi_agent_v2: OFF — model catalog pins and defaults decide the surface";
 }
 
-export function multiAgentModeLine(mode: string): string {
+export function multiAgentModeLine(mode: string, keepNativeChatGptOnV1 = false): string {
   switch (mode) {
     case "v1": return "multi_agent_mode: v1 — ALL models forced to v1 surface (upstream pins overridden)";
-    case "v2": return "multi_agent_mode: v2 — ALL models forced to v2 surface (upstream pins overridden)";
+    case "v2": return keepNativeChatGptOnV1
+      ? "multi_agent_mode: v2 hybrid — ChatGPT-native models use v1; routed models use v2"
+      : "multi_agent_mode: v2 — ALL models forced to v2 surface (upstream pins overridden)";
     default: return "multi_agent_mode: default — upstream model pins respected (sol/terra=v2, luna=v1, rest=codex flag)";
   }
 }
 
+function requiresGlobalV2Disabled(multiAgentMode: string | undefined, keepNativeChatGptOnV1: boolean): boolean {
+  return multiAgentMode === "v2" && keepNativeChatGptOnV1;
+}
+
 export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: () => Promise<number | undefined>): Promise<number> {
   const log = deps.log ?? console;
   const isEnabled = deps.isEnabled ?? isMultiAgentV2Enabled;
@@ -109,9 +115,13 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
   if (verb === "status") {
     log.log(v2StatusLine(isEnabled()));
     const cfg = loadConfig();
-    log.log(multiAgentModeLine(cfg.multiAgentMode ?? "default"));
+    const mode = cfg.multiAgentMode ?? "default";
+    const keepNativeV1 = cfg.keepNativeChatGptOnV1 === true;
+    log.log(multiAgentModeLine(mode, keepNativeV1));
     log.log(cfg.keepNativeChatGptOnV1 === true
-      ? "keep_native_chatgpt_on_v1: ON — ChatGPT-native rows stay v1 when mode is v2"
+      ? requiresGlobalV2Disabled(mode, keepNativeV1) && isEnabled()
+        ? "keep_native_chatgpt_on_v1: CONFLICT — global multi_agent_v2 overrides the native v1 catalog pin; run 'ocx v2 keep-native-v1 on' to reconcile"
+        : "keep_native_chatgpt_on_v1: ON — global V2 override is off; ChatGPT-native rows use v1 and routed rows use v2 when mode is v2"
       : "keep_native_chatgpt_on_v1: OFF");
     const threads = getLogicalMaxThreads();
     log.log(`max_threads: ${threads ?? "(unset — codex default)"}`);
@@ -186,14 +196,14 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     }
     const cfg = loadConfig();
     if (modeArg !== "default") {
-      const target = modeArg === "v2";
+      const target = modeArg === "v2" && cfg.keepNativeChatGptOnV1 !== true;
       const transition = transitionMultiAgentV2(target, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
       if (!transition.ok) {
         log.error(`multi-agent mode transition failed: ${transition.error}`);
         return 1;
       }
     }
-    if (modeArg === "default") delete cfg.multiAgentMode;
+    if (modeArg === "default") deleteConfigTopLevelKey(cfg, "multiAgentMode");
     else cfg.multiAgentMode = modeArg as "v1" | "v2";
     saveConfig(cfg);
     try {
@@ -216,8 +226,15 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     const cfg = loadConfig();
     const next = flag === "on";
     const already = cfg.keepNativeChatGptOnV1 === true === next;
+    if (next && requiresGlobalV2Disabled(cfg.multiAgentMode, true)) {
+      const transition = transitionMultiAgentV2(false, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
+      if (!transition.ok) {
+        log.error(`keep-native-v1 transition failed: ${transition.error}`);
+        return 1;
+      }
+    }
     if (next) cfg.keepNativeChatGptOnV1 = true;
-    else delete cfg.keepNativeChatGptOnV1;
+    else deleteConfigTopLevelKey(cfg, "keepNativeChatGptOnV1");
     saveConfig(cfg);
     try {
       const sync = deps.sync ?? (await import("../codex/sync")).syncModelsToCodex;
@@ -243,6 +260,13 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
   }
 
   const want = verb === "on";
+  if (want) {
+    const cfg = loadConfig();
+    if (requiresGlobalV2Disabled(cfg.multiAgentMode, cfg.keepNativeChatGptOnV1 === true)) {
+      log.error("v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first.");
+      return 1;
+    }
+  }
   const transition = transitionMultiAgentV2(want, enabled => runCodexFeatures(enabled ? "enable" : "disable", deps));
   if (!transition.ok) {
     log.error(`codex features ${want ? "enable" : "disable"} multi_agent_v2 failed: ${transition.error}`);

package/src/cli/version-skew.ts

@@ -0,0 +1,46 @@
+/**
+ * CLI-versus-proxy version skew (#2701).
+ *
+ * The reported failure: `ocx` on PATH is an older install than the running proxy, so its
+ * help describes commands the proxy does not have and its output describes a different
+ * build. Nothing surfaced that, because the CLI never compared the two.
+ *
+ * Kept in its own module rather than inside `status.ts` so `doctor` can reuse the exact
+ * comparison instead of reimplementing it -- two diagnostics disagreeing about whether an
+ * install is stale would be worse than neither reporting it.
+ */
+
+/** Placeholder versions that mean "unknown", not "different". */
+const PLACEHOLDERS = new Set(["unknown", "0.0.0"]);
+
+export interface VersionSkew {
+  readonly cliVersion: string;
+  /** Version the live proxy reported, or null when nothing is live or it reported none. */
+  readonly proxyVersion: string | null;
+  readonly skewed: boolean;
+  /** Operator-facing explanation; null when there is nothing to report. */
+  readonly warning: string | null;
+}
+
+/**
+ * Compare the running CLI against the live proxy.
+ *
+ * Suppressed rather than reported when either side is a placeholder. `packageVersion()`
+ * answers `"unknown"` when `package.json` carries no string version, and the server's
+ * `VERSION` falls back to `"0.0.0"` when it cannot resolve its own package -- comparing
+ * against either would report skew that says nothing about the install. A false stale-CLI
+ * warning would send an operator to reinstall a healthy setup.
+ */
+export function computeVersionSkew(cliVersion: string, proxyVersion: string | undefined): VersionSkew {
+  const proxy = proxyVersion ?? null;
+  if (proxy === null || PLACEHOLDERS.has(proxy) || PLACEHOLDERS.has(cliVersion) || proxy === cliVersion) {
+    return { cliVersion, proxyVersion: proxy, skewed: false, warning: null };
+  }
+  return {
+    cliVersion,
+    proxyVersion: proxy,
+    skewed: true,
+    warning: `CLI ${cliVersion} does not match the running proxy ${proxy} — this ocx on PATH is stale. `
+      + "Its help and features describe a different build. Reinstall, or run the proxy's own binary.",
+  };
+}