@iislee/opencodex 2.31.0 → 2.35.0

package/src/cli/models-runtime.ts

@@ -22,6 +22,10 @@ const USAGE = `Usage:
   ocx models <enable|disable> <provider/model|native-model> [--native] [--json]
   ocx models provider <name> <on|off> [--json]
   ocx models selected <provider> [--set <id,id...>|--clear] [--json]
+  ocx models preset show [--provider <name>] [--json]
+  ocx models preset apply <provider> [--all] [--json]
+  ocx models new-policy [on|off] [--provider <name>] [--json]
+  ocx models new-arrivals [--json]
   ocx models context <status|value <tokens> [--set-all]|provider <name> on [--value <tokens>]|provider <name> off|all <on|off>> [--json]
   ocx models shadow <status|set> [model|-] [--enabled <on|off>] [--json]`;
 
@@ -162,6 +166,94 @@ async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`${provider}: ${models.length ? models.join(", ") : "all models"}`]);
 }
 
+
+interface ModelPresetView {
+  mode: string;
+  appliedVersion?: number;
+  availableVersion: number;
+  presetIds: string[];
+  presetCount: number;
+  totalCount: number;
+  fallback?: string;
+}
+
+function presetLine(name: string, view: ModelPresetView): string {
+  const parts = [`${name}: mode=${view.mode}`];
+  if (view.appliedVersion !== undefined && view.appliedVersion !== view.availableVersion) {
+    parts.push(`applied v${view.appliedVersion}, available v${view.availableVersion}`);
+  } else {
+    parts.push(`preset v${view.availableVersion}`);
+  }
+  parts.push(`(${view.presetCount} of ${view.totalCount} models)`);
+  if (view.fallback) parts.push(`fallback=${view.fallback}`);
+  return parts.join(" ");
+}
+
+async function preset(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const action = (args.shift() ?? "show").toLowerCase();
+  const wantsJson = takeFlag(args, "--json");
+  if (action === "show") {
+    const only = takeOption(args, "--provider")?.trim();
+    rejectArgs(args, USAGE);
+    const result = await runtimeRequest<{ providers?: Record<string, ModelPresetView> }>("/api/model-presets", {}, deps);
+    const providers = result.providers ?? {};
+    const entries = Object.entries(providers).filter(([name]) => !only || name === only);
+    const lines = entries.length > 0
+      ? entries.map(([name, view]) => presetLine(name, view))
+      // A provider with no shipped preset is not an error: it simply has nothing to curate.
+      : [only ? `${only}: no model preset is shipped for this provider` : "no providers have a shipped model preset"];
+    printData(only ? providers[only] ?? {} : result, wantsJson, lines);
+    return;
+  }
+  if (action !== "apply") throw new CliUsageError(`unknown preset action '${action}'`, USAGE);
+  const provider = args.shift()?.trim();
+  const all = takeFlag(args, "--all");
+  if (!provider) throw new CliUsageError("provider is required", USAGE);
+  rejectArgs(args, USAGE);
+  const mode = all ? "all" : "preset";
+  const result = await runtimeRequest<{ selected?: string[]; fallback?: string; appliedVersion?: number }>(
+    "/api/model-presets",
+    { method: "PUT", body: JSON.stringify({ provider, mode }) },
+    deps,
+  );
+  const selectedIds = result.selected ?? [];
+  const line = result.fallback === "preset-empty"
+    // Never silently narrow to nothing: empty means ALL, so a zero-match preset keeps what was
+    // there and says so.
+    ? `${provider}: preset matched no models — selection unchanged (fallback to all)`
+    : all
+      ? `${provider}: showing all models (allowlist cleared)`
+      : `${provider}: preset v${result.appliedVersion ?? "?"} applied — ${selectedIds.length} models selected`;
+  printData(result, wantsJson, [line]);
+}
+
+async function newPolicy(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const state = args[0] && !args[0].startsWith("--") ? args.shift()!.toLowerCase() : undefined;
+  const provider = takeOption(args, "--provider")?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (state !== undefined && state !== "on" && state !== "off") throw new CliUsageError("new policy must be on or off", USAGE);
+  rejectArgs(args, USAGE);
+  if (!state) {
+    const result = await runtimeRequest<{ policy: string; providers: Record<string, string> }>("/api/model-discovery", {}, deps);
+    const value = provider ? result.providers[provider] ?? "inherit" : result.policy;
+    printData(provider ? { provider, policy: value } : result, wantsJson, [`${provider ?? "global"}: ${value}`]);
+    return;
+  }
+  const result = await runtimeRequest<{ baselineBootstrapped?: boolean }>("/api/model-discovery", {
+    method: "PUT", body: JSON.stringify({ policy: state, provider: provider ?? null }),
+  }, deps);
+  printData(result, wantsJson, [`${provider ?? "global"}: ${state}${result.baselineBootstrapped ? " (current models recorded as known)" : ""}`]);
+}
+
+async function newArrivals(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv]; const wantsJson = takeFlag(args, "--json"); rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ recentArrivals: Record<string, Array<{ id: string; at: string; state: string }>> }>("/api/model-discovery", {}, deps);
+  const lines = Object.entries(result.recentArrivals).flatMap(([provider, rows]) => rows.map(row => `${provider}/${row.id}  [${row.state}]  ${row.at}`));
+  printData(result.recentArrivals, wantsJson, lines.length ? lines : ["no recent model arrivals"]);
+}
+
 async function context(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const args = [...argv];
   const action = (args.shift() ?? "status").toLowerCase();
@@ -236,6 +328,9 @@ export async function handleModelsRuntimeCommand(sub: string, argv: string[], de
   else if (sub === "disable") action = () => visibility(false, argv, deps);
   else if (sub === "provider") action = () => providerVisibility(argv, deps);
   else if (sub === "selected") action = () => selected(argv, deps);
+  else if (sub === "preset") action = () => preset(argv, deps);
+  else if (sub === "new-policy") action = () => newPolicy(argv, deps);
+  else if (sub === "new-arrivals") action = () => newArrivals(argv, deps);
   else if (sub === "context") action = () => context(argv, deps);
   else if (sub === "shadow") action = () => shadow(argv, deps);
   if (!action) return null;

package/src/cli/models.ts

@@ -5,8 +5,13 @@ import { randomUUID } from "node:crypto";
 import { createInterface } from "node:readline/promises";
 import { syncModelsToCodex } from "../codex/sync";
 import { hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
-import { canonicalizeReasoningEfforts, isDeclaredReasoningEffort, modelRecordValue } from "../reasoning-effort";
-import { encodedModelIdCollides, routedSlug, slugEquals } from "../providers/slug-codec";
+import {
+  canonicalizeReasoningEfforts,
+  configuredReasoningEfforts,
+  isDeclaredReasoningEffort,
+  modelRecordValue,
+} from "../reasoning-effort";
+import { encodedModelIdCollides, resolveSlugSelection, routedSlug } from "../providers/slug-codec";
 import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { modelInList, type OcxConfig, type OcxCustomModel } from "../types";
@@ -91,7 +96,6 @@ function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[]
     const seen = new Set<string>();
     const contextWindows = prov.modelContextWindows ?? {};
     const inputModalities = prov.modelInputModalities ?? {};
-    const reasoningEfforts = prov.modelReasoningEfforts ?? {};
     const globalContext = prov.contextWindow ?? null;
 
     const addModel = (model: string, isDefault: boolean) => {
@@ -107,7 +111,13 @@ function collectModels(config: OcxConfig, providerFilter?: string): ModelEntry[]
       // an exact `gpt-oss:120b` entry that lists "image", and the proxy rejects the image.
       const noVision = modelInList(prov.noVisionModels, model);
       const modalities = noVision ? ["text"] : (modelRecordValue(inputModalities, model) ?? null);
-      const efforts = modelRecordValue(reasoningEfforts, model) ?? prov.reasoningEfforts ?? null;
+      // Same reason, for the ladder: `configuredReasoningEfforts` is what the catalog
+      // (`provider-fetch`) and the effort cap (`effort-policy`) resolve through, and it
+      // does three things this expression did not — it returns [] for a noReasoningModels
+      // match, drops levels Codex does not declare, and re-adds tiers the wire map proves
+      // the model emits. Restating two of its five lines here reported a ladder the proxy
+      // strips, and unsanitized junk as a supported level.
+      const efforts = configuredReasoningEfforts(prov, model) ?? null;
 
       entries.push({
         provider: provName,
@@ -267,11 +277,17 @@ async function handleCustomRemove(args: string[]): Promise<void> {
 
   const config = loadConfig();
   const existing = config.customModels ?? [];
-  const matchingIndexes = existing.flatMap((model, index) => (
-    target.includes("/")
-      ? slugEquals(target, model.provider, model.modelId)
-      : model.id === target
-  ) ? [index] : []);
+  // Slug matching goes through the shared resolver so this command sees the same collision
+  // class catalog filtering and persisted sync see (#2491). `slugEquals` compares the raw and
+  // encoded spellings of ONE id, so a selector written in the native slash form matched only
+  // that row while the dash form matched both — the two relations disagreed on the same
+  // config. Removal stays exact-or-refuse: an ambiguous selector still aborts below, which is
+  // the right default for a destructive command.
+  const matchingIndexes = existing.flatMap((model, index) => {
+    if (!target.includes("/")) return model.id === target ? [index] : [];
+    const resolved = resolveSlugSelection(model.provider, target, [model.modelId]);
+    return resolved.matched.length > 0 ? [index] : [];
+  });
   if (matchingIndexes.length === 0) fail(`custom model "${target}" not found`);
   if (matchingIndexes.length > 1) {
     fail(`custom model selector "${target}" is ambiguous; use the custom model id`);
@@ -412,7 +428,7 @@ export async function handleModels(args: string[]): Promise<void> {
     handleCustomList(rest);
     return;
   }
-  if (["live", "edit", "enable", "disable", "provider", "selected", "context", "shadow"].includes(subcommand ?? "")) {
+  if (["live", "edit", "enable", "disable", "provider", "selected", "preset", "context", "shadow"].includes(subcommand ?? "")) {
     const { handleModelsRuntimeCommand } = await import("./models-runtime");
     const code = await handleModelsRuntimeCommand(subcommand!, rest);
     if (code !== null) process.exitCode = code;

package/src/cli/observe.ts

@@ -10,14 +10,17 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { formatUsageReport } from "./usage-report";
+import { USAGE_RANGES, USAGE_SURFACES } from "../usage/summary";
 
 const USAGE = `Usage:
   ocx observe logs [--provider <name>] [--model <id>] [--status <code>]
-      [--limit <n>] [--follow] [--json|--jsonl]
+      [--conversation <id>] [--limit <n>] [--follow] [--json|--jsonl]
   ocx logs explain <request-id> [--json]
   ocx logs rebuild-index
   ocx logs index-status
-  ocx observe usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]
+  ocx observe usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>]
+      [--provider <name>] [--model <id>] [--json]
   ocx observe storage [codex-logs [status|protect|unprotect|repair|compact] [--mode <compat|quiet>]] [--json]
   ocx observe memory [--json]
   ocx observe debug [--json]
@@ -47,7 +50,12 @@ function formatLog(row: LogEntry): string {
   const route = [row.provider, row.model].filter(Boolean).join("/");
   const status = row.status ?? row.statusCode ?? "?";
   const duration = row.durationMs !== undefined ? `${String(row.durationMs)}ms` : "";
-  return [time, String(status), route, duration].filter(Boolean).join("  ");
+  // The conversation id is shown because a conversation FILTER whose output never names the
+  // conversation is hard to trust: an empty result and a wrong-id result look identical (#2704).
+  const conversation = typeof row.conversationId === "string" && row.conversationId.length > 0
+    ? `conv=${row.conversationId}`
+    : "";
+  return [time, String(status), route, duration, conversation].filter(Boolean).join("  ");
 }
 
 async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
@@ -58,13 +66,16 @@ async function logs(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const provider = takeOption(args, "--provider");
   const model = takeOption(args, "--model");
   const status = takeOption(args, "--status");
+  // Both spellings, because the server accepts both (`request-log.ts:1032`) and an operator
+  // should not have to remember which one this surface wanted.
+  const conversationId = takeOption(args, "--conversation") ?? takeOption(args, "--conversationId");
   const limit = takeIntegerOption(args, "--limit", { min: 1 }) ?? 200;
   rejectArgs(args, USAGE);
   if (wantsJson && wantsJsonl) throw new CliUsageError("--json and --jsonl cannot be combined", USAGE);
   if (follow && wantsJson) throw new CliUsageError("--follow uses --jsonl, not --json", USAGE);
   let seen = new Set<string>();
   do {
-    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, limit })}`, {}, deps);
+    const data = await runtimeRequest(`/api/logs${query({ provider, model, status, conversationId, limit })}`, {}, deps);
     const rows = logRows(data);
     if (!follow && wantsJson) printData(data, true);
     else {
@@ -131,11 +142,23 @@ async function usage(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const wantsJson = takeFlag(args, "--json");
   const range = takeOption(args, "--range") ?? "30d";
   const surface = takeOption(args, "--surface") ?? "all";
-  if (!["7d", "30d", "all"].includes(range)) throw new CliUsageError("--range must be 7d, 30d, or all", USAGE);
-  if (!["all", "codex", "claude", "grok"].includes(surface)) throw new CliUsageError("--surface must be all, codex, claude, or grok", USAGE);
+  const provider = takeOption(args, "--provider");
+  const model = takeOption(args, "--model");
+  // `1d` is accepted here as well as server-side so the CLI does not reject an
+  // alias the API would have understood.
+  const ranges = [...USAGE_RANGES, "1d"];
+  if (!ranges.includes(range)) throw new CliUsageError(`--range must be one of ${USAGE_RANGES.join(", ")} (1d aliases today)`, USAGE);
+  if (!USAGE_SURFACES.includes(surface as (typeof USAGE_SURFACES)[number])) {
+    throw new CliUsageError(`--surface must be one of ${USAGE_SURFACES.join(", ")}`, USAGE);
+  }
   rejectArgs(args, USAGE);
-  const result = await runtimeRequest(`/api/usage${query({ range, surface })}`, {}, deps);
-  printData(result, wantsJson, summaryLines(result));
+  const result = await runtimeRequest(`/api/usage${query({ range, surface, provider, model })}`, {}, deps);
+  // Built only when it will be printed: JavaScript evaluates arguments before
+  // the call, so passing formatUsageReport(...) inline would run the human
+  // renderer during --json and let its assumptions affect a path that is meant
+  // to bypass it entirely.
+  if (wantsJson) printData(result, true);
+  else printData(result, false, formatUsageReport(result as Parameters<typeof formatUsageReport>[0]));
 }
 
 async function simple(path: string, argv: string[], deps: RuntimeApiDeps): Promise<void> {

package/src/cli/provider-runtime.ts

@@ -11,6 +11,13 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { providerQuotaLine } from "./account-extended";
+import type { ProviderQuotaReportDto } from "./account-api";
+
+interface ProviderQuotasDto {
+  generatedAt?: number;
+  reports?: ProviderQuotaReportDto[];
+}
 
 const USAGE = `Usage:
   ocx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->]
@@ -107,8 +114,15 @@ async function quota(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const wantsJson = takeFlag(args, "--json");
   const refresh = takeFlag(args, "--refresh");
   rejectArgs(args, USAGE);
-  const result = await runtimeRequest(`/api/provider-quotas${refresh ? "?refresh=1" : ""}`, {}, deps);
-  printData(result, wantsJson, summaryLines(result));
+  const result = await runtimeRequest<ProviderQuotasDto>(`/api/provider-quotas${refresh ? "?refresh=1" : ""}`, {}, deps);
+  // `summaryLines` is a depth-1 flattener: it renders a non-scalar array as "N item(s)", which
+  // collapsed the whole report to a count and made the command useless for its stated purpose
+  // (#2565). Render one line per report with the same formatter `ocx account refresh` uses.
+  const reports = Array.isArray(result?.reports) ? result.reports : [];
+  const lines = reports.length > 0
+    ? reports.map(report => providerQuotaLine(report.provider, report))
+    : ["no quota reports available"];
+  printData(result, wantsJson, lines);
 }
 
 async function presets(argv: string[], deps: RuntimeApiDeps): Promise<void> {

package/src/cli/provider.ts

@@ -8,7 +8,8 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { apiKeyTransportConfigError, hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { apiKeyTransportConfigError } from "../config/provider-validation";
 import { hasHelpFlag } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";

package/src/cli/registry.ts

@@ -36,8 +36,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "recover-history",
-    usage: "ocx recover-history --legacy-openai",
-    summary: "Explicitly recover pre-backup syncResumeHistory rows.",
+    usage: "ocx recover-history --legacy-openai --yes",
+    summary: "Force all user-message opencodex rows to OpenAI for legacy recovery.",
   },
   {
     name: "uninstall",
@@ -88,20 +88,22 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "ensure", usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
   {
     name: "sync",
-    usage: "ocx sync [--restart-codex]",
+    usage: "ocx sync [--restart-codex] [--restart-desktop-app]",
     summary: "Fetch provider models and inject them into Codex config.",
     details: [
       "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
       "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+      "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
     ],
   },
   {
     name: "sync-cache",
-    usage: "ocx sync-cache [--restart-codex]",
+    usage: "ocx sync-cache [--restart-codex] [--restart-desktop-app]",
     summary: "Refresh Codex's model cache from the active catalog.",
     details: [
       "Warns when Codex app-server processes still hold an in-memory model list.",
       "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+      "--restart-desktop-app (Windows only, opt-in) fully restarts the Codex desktop app so its model picker re-reads the catalog. Never implied by --restart-codex: it ends live conversations.",
     ],
   },
   { name: "status", usage: "ocx status", summary: "Check proxy server status." },
@@ -162,10 +164,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "A selection-order change applies from the next unbound request and never moves a bound thread.",
     ],
   },
+  {
+    name: "alias",
+    usage: "ocx alias <list|set|rm|defaults> ...",
+    summary: "Manage short provider and model names.",
+  },
   {
     name: "models",
     aliases: ["model"],
-    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|context|shadow> ...",
+    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|preset|context|shadow> ...",
     summary: "List models and manage custom (manually registered) models.",
     details: [
       "List available models from static config with no subcommand (liveModels may add more at runtime).",
@@ -205,13 +212,29 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
     summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
   },
+  {
+    name: "inspect",
+    usage: "ocx inspect <config|catalog|routing-analytics|pacing|key-providers|codex-prompt|client-config|star|windows-tray> ...",
+    summary: "Read effective config, catalog, analytics, pacing, and the generated client-config snippet.",
+    details: [
+      "`inspect star` reads the repository star status only. Starring uses your GitHub identity and is available from the dashboard alone.",
+    ],
+  },
   { name: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
   {
     name: "usage",
-    usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]",
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--json]",
     summary: "Alias of ocx observe usage.",
   },
-  { name: "storage", usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
+  {
+    name: "storage",
+    usage: "ocx storage <report|cleanup|trash|policy> ...",
+    summary: "Storage report, archived-session cleanup, trash restore, and the cleanup policy.",
+    details: [
+      "A bare `ocx storage` prints the report, as it did when this was an alias of `observe storage`.",
+      "`cleanup` previews by default and only deletes under --yes; `trash restore` and `policy run` also require --yes.",
+    ],
+  },
   { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
   {
     name: "access",
@@ -221,8 +244,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "api-key", usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "export",
-    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime> [--json] [--out <path>] [--force]",
-    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent) wired to the running proxy.",
+    usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|cline> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (OpenCode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code, DeepSeek Harness, MiniMax Code, ZCode, Prime Agent, Cline) wired to the running proxy.",
     details: [
       "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
       "--out <path> writes the native config there and refuses to replace an existing file without --force.",
@@ -235,7 +258,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     usage: "ocx grok <status|exclude|include|set|clear|apply> ...",
     summary: "Manage and apply the Grok Build model fence.",
   },
-  { name: "integration", usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
+  {
+    name: "integration",
+    usage: "ocx integration <claude|grok|client|native> ...",
+    summary: "Manage supported client integrations, and the native client toggles.",
+    details: [
+      "`native` shows or flips the native Claude/Claude Desktop/Codex/Grok toggles; the other subcommands manage the reversible file integrations.",
+    ],
+  },
   {
     name: "system",
     usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
@@ -342,6 +372,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
     details: ["Use --json for structured output: {ok, pid, port}."],
   },
+  {
+    name: "capabilities",
+    usage: "ocx capabilities [--json] [--mutating-only] [--route <path>]",
+    summary: "List the declared CLI capabilities and the management routes they drive.",
+    details: [
+      "The machine-readable surface index: start here when driving ocx programmatically instead of parsing help text.",
+      "--route <path> answers the inverse question: which commands drive this management route.",
+    ],
+  },
   {
     name: "ready",
     usage: "ocx ready [--json] [--wait [--timeout <seconds>]]",

package/src/cli/runtime-api.ts

@@ -47,15 +47,37 @@ export async function runtimeBaseUrl(deps: RuntimeApiDeps = {}): Promise<string>
   return `http://${probeHostname(live.hostname)}:${live.port}`;
 }
 
+function stringField(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/**
+ * Compose the operator-facing message from a management error body.
+ *
+ * The server states WHY a request was refused under `reason` and WHAT TO DO under
+ * `hint` (see management-auth.ts, which sets both on a 503 when the management plane
+ * is unavailable). Both were dropped here, so a fenced management plane was
+ * indistinguishable from a generic failure and an operator had no way to tell a port
+ * collision from an ACL refusal from a stopped proxy (#2698).
+ */
 function responseMessage(body: unknown, status: number): string {
-  if (body && typeof body === "object") {
-    const record = body as Record<string, unknown>;
-    for (const key of ["error", "message", "detail"]) {
-      if (typeof record[key] === "string" && record[key]) return record[key];
-    }
-  }
   if (typeof body === "string" && body.trim()) return body.trim().slice(0, 400);
-  return `Management request failed (${status})`;
+  if (!body || typeof body !== "object") return `Management request failed (${status})`;
+  const record = body as Record<string, unknown>;
+  let primary: string | undefined;
+  for (const key of ["error", "message", "detail"]) {
+    primary = stringField(record, key);
+    if (primary) break;
+  }
+  const parts = [primary ?? `Management request failed (${status})`];
+  const reason = stringField(record, "reason");
+  // A body of {ok:false, reason:"…"} with no `error` key used to degrade to the
+  // generic line, discarding the only actionable field.
+  if (reason && reason !== primary) parts.push(`reason: ${reason}`);
+  const hint = stringField(record, "hint");
+  if (hint && hint !== primary) parts.push(`hint: ${hint}`);
+  return parts.join("\n").slice(0, 1200);
 }
 
 export async function runtimeRequest<T = unknown>(
@@ -94,6 +116,28 @@ export function takeFlag(args: string[], flag: string): boolean {
   return true;
 }
 
+/** Unicode dashes that copy-paste and IME input substitute for ASCII `-`. */
+const DASH_CLASS = /[\u2010-\u2015\u2212]/g;
+
+/**
+ * True for `--json`, `--json=true`, `-json`, and Unicode-dash spellings.
+ * Matching only the exact token `--json` is the same defect logout had: each
+ * spelling that slips through is a silent success (or, for doctor, prose on
+ * stdout after the caller asked for JSON).
+ */
+export function isJsonOption(arg: string): boolean {
+  const body = arg.replace(DASH_CLASS, "-").replace(/^-+/, "");
+  return body === "json" || body.startsWith("json=");
+}
+
+/** Remove one JSON-request spelling from `args`. Returns whether one was present. */
+export function takeJsonFlag(args: string[]): boolean {
+  const index = args.findIndex(isJsonOption);
+  if (index === -1) return false;
+  args.splice(index, 1);
+  return true;
+}
+
 export function takeOption(args: string[], flag: string): string | undefined {
   const index = args.indexOf(flag);
   if (index === -1) return undefined;

package/src/cli/status.ts

@@ -1,5 +1,6 @@
 import { durableBunRuntime } from "../lib/bun-runtime";
-import { codexAutoStartEnabled, getConfigPath, getPidPath, readConfigDiagnostics, readPid, readRuntimePort, type RuntimePortState } from "../config";
+import { codexAutoStartEnabled, getConfigPath, readConfigDiagnostics } from "../config";
+import { getPidPath, readPid, readRuntimePort, type RuntimePortState } from "../config/process-state";
 import { diagnoseCodexBundledPlugins, type CodexPluginsDiagnostic } from "../codex/plugins-doctor";
 import { findLiveProxy, isOpencodexHealthz, probeHostname } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
@@ -9,6 +10,8 @@ import { collectStartupHealth, type StartupHealth } from "../codex/autostart-hea
 import { getCodexRoutingKind } from "../codex/inject";
 import { diagnoseCodexShim } from "../codex/shim";
 import { displayCodexRuntimePath, effortClampAppliesToRuntime, loadLastEffortClamp, resolveCodexRuntime } from "../codex/runtime";
+import { packageVersion } from "./help";
+import { computeVersionSkew, type VersionSkew } from "./version-skew";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "../codex/home";
 import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status";
@@ -69,6 +72,13 @@ export type CliStatusJson = {
     };
   };
   codexHome: OrcaCodexHomeDiagnostic;
+  /**
+   * This CLI's version against the running proxy's (#2701).
+   *
+   * Additive and optional-by-value, so `schemaVersion` stays 1: an existing consumer that
+   * ignores the key is unaffected, and `proxyVersion` is null when nothing is live.
+   */
+  versionSkew: VersionSkew;
 };
 
 export type CliStatusView = {
@@ -117,6 +127,29 @@ export function proxyHealthFailureReason(error: unknown, signal: AbortSignal): "
     : "unreachable";
 }
 
+/**
+ * `ocx status` greens on process liveness alone, so a proxy that answers
+ * /healthz reads healthy even when Codex is not pointed at it and every routed
+ * request goes to OpenAI instead (#2411). The proxy line is not wrong — the
+ * listener really is up — so it keeps its check, and this supplies the signal
+ * that was missing rather than corrupting the one that was already honest.
+ *
+ * Only `native` warns. `custom-local` and `unknown` are also "this proxy is
+ * unused", but startupHealthSummary already renders both as AT RISK with a
+ * remedy command, and `custom-remote` is a deliberate operator choice. Warning
+ * on all four would teach operators to skip the line that matters.
+ */
+export function unusedProxyWarningLines(input: {
+  proxyUp: boolean;
+  routingKind: StartupHealth["routingKind"];
+}): string[] {
+  if (!input.proxyUp || input.routingKind !== "native") return [];
+  return [
+    "⚠️  Codex routing is native — the running proxy is unused.",
+    "   Codex requests go to OpenAI, not this proxy. Re-point with: ocx start",
+  ];
+}
+
 async function checkProxyHealth(target: ListenTarget): Promise<HealthCheck> {
   const url = target.healthUrl;
   const controller = new AbortController();
@@ -156,6 +189,9 @@ export async function collectStatus(): Promise<CliStatusView> {
   const pidFile = readPid();
   // Preserve an authoritative null from orphan/legacy liveness — do not restore pidFile.
   const pid = resolveStatusPid(live, pidFile);
+  // No extra request: findLiveProxy's identity probe already parsed and validated the
+  // healthz body, so the version came back with the liveness result.
+  const versionSkew = computeVersionSkew(packageVersion(), live?.version);
   const listen = live
     ? {
       port: live.port,
@@ -323,6 +359,10 @@ export async function collectStatus(): Promise<CliStatusView> {
       codexPlugins,
       codexRuntime,
       codexHome,
+      // Own field rather than a line in `codexRuntime.warning`: a stale ocx on PATH is a
+      // fact about this install, not about the Codex runtime, and filing it there would
+      // print it under the wrong heading (#2701).
+      versionSkew,
     },
   };
 }