@bitkyc08/opencodex 2.7.41 → 2.7.42

package/src/cli/config-command.ts

@@ -0,0 +1,145 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { getConfigPath, readConfigDiagnostics, saveConfig, validateConfigCandidate } from "../config";
+import type { OcxConfig } from "../types";
+import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx config [show] [--json] [--source]
+  ocx config get <dot.path> [--json]
+  ocx config set <dot.path> <json-or-string> [--json]
+  ocx config unset <dot.path> [--json]
+  ocx config validate [path|-] [--json]
+  ocx config export <path|->
+  ocx config import <path|-> --yes [--json]`;
+
+const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret)$/i;
+const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function redact(value: unknown, key = ""): unknown {
+  if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  if (Array.isArray(value)) return value.map(item => redact(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, redact(child, childKey)]));
+  }
+  return value;
+}
+
+function pathSegments(path: string): string[] {
+  const segments = path.split(".").map(part => part.trim()).filter(Boolean);
+  if (segments.length === 0 || segments.some(part => BLOCKED_SEGMENTS.has(part))) throw new CliUsageError("invalid config path", USAGE);
+  return segments;
+}
+
+function getPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of pathSegments(path)) {
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, segment)) throw new CliUsageError(`config path not found: ${path}`);
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function setPath(root: Record<string, unknown>, path: string, value: unknown, remove = false): void {
+  const segments = pathSegments(path);
+  let current = root;
+  for (const segment of segments.slice(0, -1)) {
+    const next = current[segment];
+    if (!next || typeof next !== "object" || Array.isArray(next)) throw new CliUsageError(`config parent path not found: ${segment}`, USAGE);
+    current = next as Record<string, unknown>;
+  }
+  const leaf = segments.at(-1)!;
+  if (remove && !Object.hasOwn(current, leaf)) throw new CliUsageError(`config path not found: ${path}`);
+  if (remove) delete current[leaf];
+  else current[leaf] = value;
+}
+
+function parseValue(raw: string): unknown {
+  try { return JSON.parse(raw); }
+  catch { return raw; }
+}
+
+function loadInput(path: string): unknown {
+  const raw = path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8");
+  try { return JSON.parse(raw); }
+  catch { throw new CliUsageError(`invalid JSON in ${path}`); }
+}
+
+function validate(value: unknown): OcxConfig {
+  const result = validateConfigCandidate(value);
+  if (!result.ok) throw new CliUsageError(result.error);
+  return result.config;
+}
+
+export async function handleConfigCommand(argv: string[]): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "show").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+    if (action === "show") {
+      const source = takeFlag(args, "--source");
+      rejectArgs(args, USAGE);
+      const diagnostics = readConfigDiagnostics();
+      const config = redact(diagnostics.config);
+      const result = source ? { config, source: diagnostics.source, error: diagnostics.error, warnings: diagnostics.warnings ?? [] } : config;
+      printData(result, true);
+      return;
+    }
+    if (action === "get") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("config path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const value = redact(getPath(readConfigDiagnostics().config, path), path.split(".").at(-1));
+      if (wantsJson || typeof value === "object") console.log(JSON.stringify(value, null, 2));
+      else console.log(String(value));
+      return;
+    }
+    if (action === "set" || action === "unset") {
+      const path = args.shift();
+      const raw = action === "set" ? args.shift() : undefined;
+      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError("config path and value are required", USAGE);
+      rejectArgs(args, USAGE);
+      const candidate = structuredClone(readConfigDiagnostics().config) as unknown as Record<string, unknown>;
+      setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
+      const config = validate(candidate);
+      const savedValue = action === "unset" ? null : getPath(config, path);
+      saveConfig(config);
+      printData({ ok: true, path, value: redact(savedValue, path.split(".").at(-1)) }, wantsJson,
+        [`${action === "unset" ? "Unset" : "Set"} ${path}.`]);
+      return;
+    }
+    if (action === "validate") {
+      const path = args.shift();
+      rejectArgs(args, USAGE);
+      const result = path ? validateConfigCandidate(loadInput(path)) : (() => {
+        const diagnostics = readConfigDiagnostics();
+        return diagnostics.error ? { ok: false as const, error: diagnostics.error } : { ok: true as const, config: diagnostics.config };
+      })();
+      printData(result.ok ? { ok: true, source: path ?? getConfigPath() } : result, wantsJson,
+        [result.ok ? "Config is valid." : `Config is invalid: ${result.error}`]);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+    if (action === "export") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("export path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const content = `${JSON.stringify(readConfigDiagnostics().config, null, 2)}\n`;
+      if (path === "-") process.stdout.write(content);
+      else { writeFileSync(path, content, { encoding: "utf8", mode: 0o600 }); console.log(`Exported config to ${path}.`); }
+      return;
+    }
+    if (action === "import") {
+      const path = args.shift();
+      const yes = takeFlag(args, "--yes");
+      if (!path) throw new CliUsageError("import path is required", USAGE);
+      if (!yes) throw new CliUsageError("import requires --yes", USAGE);
+      rejectArgs(args, USAGE);
+      saveConfig(validate(loadInput(path)));
+      printData({ ok: true, source: path }, wantsJson, [`Imported config from ${path}. Restart or run ocx sync if needed.`]);
+      return;
+    }
+    throw new CliUsageError(`unknown config command ${action}`, USAGE);
+  });
+}
+
+export const CONFIG_USAGE = USAGE;

package/src/cli/debug.ts

@@ -2,7 +2,7 @@ import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
 import { DEBUG_ENV, type DebugSettingsView } from "../lib/debug-settings";
 import { runningProxyUpdateHeaders } from "../oauth/login-cli";
 
-type DebugScope = "provider" | "usage" | "injection";
+type DebugScope = "provider" | "usage" | "injection" | "claude";
 
 async function requireLiveProxy() {
   const live = await findLiveProxy();
@@ -54,10 +54,14 @@ function printScopeStatus(scope: DebugScope, view: DebugSettingsView): void {
     console.log(`Usage debug: ${view.usage ? "ON" : "off"}`);
     console.log(`  env=${view.env.usage ? "on" : "off"}, runtime=${view.runtimeOverride.usage === undefined ? "env/default" : view.runtimeOverride.usage ? "on" : "off"}`);
     console.log("  Tail: ocx debug usage logs [-f] (via running proxy API)");
-  } else {
+  } else if (scope === "injection") {
     console.log(`Injection debug: ${view.injection ? "ON" : "off"}`);
     console.log(`  env=${view.env.injection ? "on" : "off"}, runtime=${view.runtimeOverride.injection === undefined ? "env/default" : view.runtimeOverride.injection ? "on" : "off"}`);
     console.log("  Lines appear on the proxy console when multi-agent guidance is injected.");
+  } else {
+    console.log(`Claude inbound debug: ${view.claude ? "ON" : "off"}`);
+    console.log(`  env=${view.env.claude ? "on" : "off"}, runtime=${view.runtimeOverride.claude === undefined ? "env/default" : view.runtimeOverride.claude ? "on" : "off"}`);
+    console.log("  View: ocx observe claude-inbound");
   }
 }
 
@@ -142,7 +146,10 @@ async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Prom
 
   if (action === "on" || action === "off") {
     const enabled = action === "on";
-    const body = scope === "provider" ? { debug: enabled } : scope === "usage" ? { usage: enabled } : { injection: enabled };
+    const body = scope === "provider" ? { debug: enabled }
+      : scope === "usage" ? { usage: enabled }
+        : scope === "injection" ? { injection: enabled }
+          : { claude: enabled };
     printScopeStatus(scope, await putDebugSettings(body));
     console.log(`\n${scope} debug is now ${enabled ? "enabled" : "disabled"}.`);
     return;
@@ -161,8 +168,10 @@ async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Prom
   }
 
   if (action === "logs") {
-    if (scope === "injection") {
-      console.error("Injection debug has no buffered log stream; lines print on the proxy console.");
+    if (scope === "injection" || scope === "claude") {
+      console.error(scope === "claude"
+        ? "Use: ocx observe claude-inbound"
+        : "Injection debug has no buffered log stream; use: ocx observe injection");
       process.exit(1);
     }
     const follow = actionArgv.slice(1).some(arg => arg === "-f" || arg === "--follow");
@@ -171,8 +180,8 @@ async function handleScopeCommand(scope: DebugScope, actionArgv: string[]): Prom
     return;
   }
 
-  console.error(scope === "injection"
-    ? "Usage: ocx debug injection on|off|status|reset"
+  console.error(scope === "injection" || scope === "claude"
+    ? `Usage: ocx debug ${scope} on|off|status|reset`
     : `Usage: ocx debug ${scope} on|off|status|reset|logs [-f]`);
   process.exit(1);
 }
@@ -183,17 +192,19 @@ function printTopLevelHelp(): void {
   console.log("  ocx debug provider on|off|status|reset|logs [-f]");
   console.log("  ocx debug usage on|off|status|reset|logs [-f]");
   console.log("  ocx debug injection on|off|status|reset");
+  console.log("  ocx debug claude on|off|status|reset");
   console.log("");
   console.log("Env defaults on start:");
   console.log("  provider → OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)");
   console.log(`  usage    → ${DEBUG_ENV.usage}=1`);
   console.log(`  injection→ ${DEBUG_ENV.injection}=1`);
+  console.log(`  claude   → ${DEBUG_ENV.claude}=1`);
 }
 
 export async function handleDebugCommand(argv: string[]): Promise<void> {
   const sub = (argv[0] ?? "").trim().toLowerCase();
 
-  if (sub === "provider" || sub === "usage" || sub === "injection") {
+  if (sub === "provider" || sub === "usage" || sub === "injection" || sub === "claude") {
     await handleScopeCommand(sub, argv.slice(1));
     return;
   }
@@ -205,6 +216,7 @@ export async function handleDebugCommand(argv: string[]): Promise<void> {
       console.log(`  provider → OCX_DEBUG = ${envDebugEnabled() ? "on" : "off"}`);
       console.log(`  usage    → ${DEBUG_ENV.usage} = ${process.env[DEBUG_ENV.usage] === "1" ? "on" : "off"}`);
       console.log(`  injection→ ${DEBUG_ENV.injection} = ${process.env[DEBUG_ENV.injection] === "1" ? "on" : "off"}`);
+      console.log(`  claude   → ${DEBUG_ENV.claude} = ${process.env[DEBUG_ENV.claude] === "1" ? "on" : "off"}`);
       console.log("");
     }
     printTopLevelHelp();

package/src/cli/doctor.ts

@@ -480,10 +480,14 @@ export type ServiceMemoryData = {
   platform: string;
   rss: number;
   heapUsed: number;
+  external: number;
+  arrayBuffers: number;
+  observedBytes?: number;
+  observedMetric?: MemoryMetric;
   jscHeap: { heapSize: number } | null;
   streamMode: string;
   eagerRelay: { useEagerRelay: boolean; reason: string } | null;
-  watchdog: { warnThresholdBytes: number; lastWarnAt: number | null } | null;
+  watchdog: { warnThresholdBytes: number; lastWarnAt: number | null; observedBytes?: number; observedMetric?: MemoryMetric } | null;
 };
 
 export type ServiceMemoryReport =
@@ -493,6 +497,19 @@ export type ServiceMemoryReport =
 
 const SERVICE_MEMORY_TIMEOUT_MS = 2000;
 const DEFAULT_MEMORY_THRESHOLD_BYTES = 4 * 1024 ** 3;
+type MemoryMetric = "rss" | "external" | "arrayBuffers";
+
+function observedMemory(data: { rss: number; external?: number; arrayBuffers?: number }): {
+  bytes: number;
+  metric: MemoryMetric;
+} {
+  const values: Array<{ metric: MemoryMetric; bytes: number }> = [
+    { metric: "rss", bytes: data.rss },
+    { metric: "external", bytes: data.external ?? 0 },
+    { metric: "arrayBuffers", bytes: data.arrayBuffers ?? 0 },
+  ];
+  return values.reduce((best, next) => next.bytes > best.bytes ? next : best, values[0]);
+}
 
 export async function fetchServiceMemory(
   host: string,
@@ -519,13 +536,26 @@ export async function fetchServiceMemory(
         platform: typeof body.platform === "string" ? body.platform : "unknown",
         rss: body.rss,
         heapUsed: typeof body.heapUsed === "number" ? body.heapUsed : 0,
+        external: typeof body.external === "number" ? body.external : 0,
+        arrayBuffers: typeof body.arrayBuffers === "number" ? body.arrayBuffers : 0,
+        observedBytes: typeof body.observedBytes === "number" ? body.observedBytes : undefined,
+        observedMetric: body.observedMetric === "rss" || body.observedMetric === "external" || body.observedMetric === "arrayBuffers"
+          ? body.observedMetric
+          : undefined,
         jscHeap: body.jscHeap && typeof body.jscHeap.heapSize === "number" ? { heapSize: body.jscHeap.heapSize } : null,
         streamMode: typeof body.streamMode === "string" ? body.streamMode : "auto",
         eagerRelay: body.eagerRelay && typeof body.eagerRelay.reason === "string"
           ? { useEagerRelay: body.eagerRelay.useEagerRelay === true, reason: body.eagerRelay.reason }
           : null,
         watchdog: body.watchdog && typeof body.watchdog.warnThresholdBytes === "number"
-          ? { warnThresholdBytes: body.watchdog.warnThresholdBytes, lastWarnAt: body.watchdog.lastWarnAt ?? null }
+          ? {
+            warnThresholdBytes: body.watchdog.warnThresholdBytes,
+            lastWarnAt: body.watchdog.lastWarnAt ?? null,
+            observedBytes: typeof body.watchdog.observedBytes === "number" ? body.watchdog.observedBytes : undefined,
+            observedMetric: body.watchdog.observedMetric === "rss" || body.watchdog.observedMetric === "external" || body.watchdog.observedMetric === "arrayBuffers"
+              ? body.watchdog.observedMetric
+              : undefined,
+          }
           : null,
       },
     };
@@ -550,22 +580,29 @@ export function formatServiceMemoryLines(report: ServiceMemoryReport): string[]
   }
   const d = report.data;
   lines.push(`  ok     service pid ${d.pid}: Bun ${d.bunVersion} on ${d.platform}`);
-  lines.push(`         rss=${mb(d.rss)}, heapUsed=${mb(d.heapUsed)}${d.jscHeap ? `, jscHeap=${mb(d.jscHeap.heapSize)}` : ""}`);
+  const observed = observedMemory(d);
+  const observedBytes = d.observedBytes ?? d.watchdog?.observedBytes ?? observed.bytes;
+  const observedMetric = d.observedMetric ?? d.watchdog?.observedMetric ?? observed.metric;
+  lines.push(`         rss=${mb(d.rss)}, external=${mb(d.external)}, arrayBuffers=${mb(d.arrayBuffers)}, heapUsed=${mb(d.heapUsed)}${d.jscHeap ? `, jscHeap=${mb(d.jscHeap.heapSize)}` : ""}`);
+  lines.push(`         observed=${mb(observedBytes)} (${observedMetric})`);
   lines.push(`         streamMode=${d.streamMode}${d.eagerRelay ? ` (eager relay: ${d.eagerRelay.useEagerRelay ? "on" : "off"}, ${d.eagerRelay.reason})` : ""}`);
   if (d.watchdog) {
     lines.push(`         watchdog threshold=${mb(d.watchdog.warnThresholdBytes)}${d.watchdog.lastWarnAt ? `, last warn ${new Date(d.watchdog.lastWarnAt).toISOString()}` : ", no warnings"}`);
   }
-  // Interpretation rule (devlog 040): reuse the watchdog's own threshold so
-  // doctor and watchdog never disagree about "high"; jsShare discriminates
-  // JS-heap growth from native runtime growth (the #314 shape).
+  // Interpretation rule: reuse the watchdog threshold and the same max-of
+  // observed memory counters, so doctor and watchdog never disagree about
+  // "high". RSS/working-set can under-report committed retention on Windows, and
+  // Bun 1.3.14 heap counters are not standalone leak proof.
   const threshold = d.watchdog?.warnThresholdBytes ?? DEFAULT_MEMORY_THRESHOLD_BYTES;
   const jsShare = d.rss > 0 ? Math.max(d.heapUsed, d.jscHeap?.heapSize ?? 0) / d.rss : 0;
-  if (d.rss < threshold) {
+  if (observedBytes < threshold) {
     lines.push("         memory usage looks normal");
+  } else if (observedMetric !== "rss") {
+    lines.push(`  !!     high observed memory via ${observedMetric}; Windows RSS/working-set counters may be blind. See docs: troubleshooting/windows-memory`);
   } else if (jsShare < 0.25) {
     lines.push("  !!     high RSS with a small JS heap — native-side growth (Bun runtime buffers/handles). See docs: troubleshooting/windows-memory");
   } else if (jsShare >= 0.5) {
-    lines.push("  !!     high RSS dominated by the JS heap — likely an opencodex bug; please report it");
+    lines.push("  !!     high RSS with large JS/JSC counters — possible JS-side retention; compare responseState/external samples before filing an app leak");
   } else {
     lines.push("  !!     high RSS, indeterminate split — capture two doctor runs over time to see the trend");
   }

package/src/cli/help.ts

@@ -12,6 +12,7 @@ type HelpEntry = {
 
 const helpEntries: Record<string, HelpEntry> = {
   init: { usage: "ocx init", summary: "Interactive setup for providers and Codex config injection." },
+  setup: { usage: "ocx setup", summary: "Interactive setup for providers and Codex config injection (alias of init)." },
   start: { usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
   stop: { usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
   restore: {
@@ -64,8 +65,8 @@ const helpEntries: Record<string, HelpEntry> = {
   status: { usage: "ocx status", summary: "Check proxy server status." },
   doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
   debug: {
-    usage: "ocx debug [provider on|off|status|reset|logs [-f]|usage on|off|status|reset|logs [-f]]",
-    summary: "Show or toggle runtime provider debug logging on the running proxy.",
+    usage: "ocx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>",
+    summary: "Show or toggle runtime provider, usage, injection, and Claude debug capture.",
     details: [
       "Provider: ocx debug provider on | off | status | reset | logs [-f]",
       "Usage JSONL: ocx debug usage on | off | status | reset | logs [-f]",
@@ -80,16 +81,16 @@ const helpEntries: Record<string, HelpEntry> = {
     summary: "Update opencodex. Preview installs stay on the preview tag unless overridden.",
   },
   provider: {
-    usage: "ocx provider <list|add|remove|show|set-default>",
+    usage: "ocx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
     summary: "Non-interactive provider management.",
     details: [
-      "Subcommands: list, add <name>, remove <name>, show <name>, set-default <name>",
+      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
       "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
       "Run `ocx provider --help` for full usage and examples.",
     ],
   },
   account: {
-    usage: "ocx account <list|current|use|refresh|auto-switch|remove|add-key> ...",
+    usage: "ocx account <list|current|use|refresh|auto-switch|login|reauth|code|cancel|remove|add-key|reset-credits> ...",
     summary: "List and switch provider accounts and API-key pools (GUI parity).",
     details: [
       "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
@@ -99,11 +100,13 @@ const helpEntries: Record<string, HelpEntry> = {
       "auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.",
       "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
       "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+      "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
+      "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
       "Codex pool switches apply to new sessions; running threads keep their account.",
     ],
   },
   models: {
-    usage: "ocx models [list] [--provider <name>] [--json] | add <provider> <modelId> [opts] | remove <id|provider/modelId> [--yes] | list-custom [--json]",
+    usage: "ocx models <list|live|add|edit|remove|enable|disable|provider|selected|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).",
@@ -116,6 +119,47 @@ const helpEntries: Record<string, HelpEntry> = {
       "Changes apply immediately to a running proxy (catalog sync).",
     ],
   },
+  model: {
+    usage: "ocx model <subcommand>",
+    summary: "Alias of ocx models.",
+  },
+  combo: {
+    usage: "ocx combo <list|show|set|remove> ...",
+    summary: "Manage combo failover and round-robin virtual models.",
+    details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
+  },
+  route: {
+    usage: "ocx route combo <list|show|set|remove> ...",
+    summary: "Manage routing features; combo is currently the supported routing resource.",
+  },
+  agent: {
+    usage: "ocx agent <status|injection|effort|subagents|fallback|sidecar> ...",
+    summary: "Manage headless multi-agent, roster, effort, injection, and sidecar settings.",
+  },
+  observe: {
+    usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
+    summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
+  },
+  logs: { usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
+  usage: { usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]", summary: "Alias of ocx observe usage." },
+  storage: { usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
+  memory: { usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
+  access: {
+    usage: "ocx access <key|endpoints|models|test> ...",
+    summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
+  },
+  "api-key": { usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
+  grok: { usage: "ocx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
+  integration: { usage: "ocx integration <claude|grok> ...", summary: "Manage supported client integrations." },
+  system: {
+    usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
+    summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
+  },
+  config: {
+    usage: "ocx config <show|get|set|unset|validate|export|import> ...",
+    summary: "Inspect and safely modify validated OpenCodex configuration.",
+    details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
+  },
   claude: {
     usage: "ocx claude [claude args...]",
     summary: "Launch Claude Code wired to the proxy (env injection + gateway model discovery).",
@@ -136,6 +180,8 @@ const helpEntries: Record<string, HelpEntry> = {
       "Families: opus, fable, sonnet, haiku. New routes start in opus.",
       "`none` is valid only when that family is empty.",
       "Legacy apply flags remain supported: --static, --hybrid, --discovery-only.",
+      "",
+      "Claude Code settings: ocx claude config <status|set> ...",
     ],
   },
   restart: {
@@ -174,7 +220,7 @@ export function printUsage(): void {
   console.log(`opencodex (ocx) — Universal provider proxy for Codex
 
 Usage:
-  ocx init                    Interactive setup (provider + Codex config injection)
+  ocx setup                   Interactive setup (alias: init)
   ocx start [--port <port>]   Start the proxy server (auto-syncs models to Codex)
   ocx stop                    Stop the proxy AND restore native Codex (plain codex works again)
   ocx restore                 Restore native Codex without stopping (alias: eject)
@@ -190,18 +236,24 @@ Usage:
   ocx sync-cache              Refresh Codex's model cache from the active catalog
   ocx status                  Check proxy server status
   ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
-  ocx debug [provider|usage ...]
-                              provider/usage on|off|status|reset|logs [-f]
-  ocx login <provider>        OAuth login (xai) — opens browser, stores token in ~/.opencodex/auth.json
+  ocx debug <scope>           provider/usage/injection/claude on|off|status|reset
+  ocx login <provider>        OAuth or API-key provider login
   ocx logout <provider>       Remove a stored OAuth login
   ocx gui                     Open the opencodex dashboard
   ocx update [--tag <tag>]    Update opencodex (keeps preview installs on @preview)
   ocx restart                  Stop and restart the proxy
   ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|threads)
   ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
-  ocx provider <sub>          Manage providers (list|add|remove|show|set-default)
-  ocx account <sub>           Accounts/keys (list|current|use|refresh|auto-switch|remove|add-key)
-  ocx models <sub>            List models; manage custom models (add|remove|list-custom)
+  ocx provider <sub>          Providers, connectivity, quota, and selected models
+  ocx account <sub>           Accounts, login/reauth, key pools, and quota controls
+  ocx models <sub>            Live/custom models, visibility, context, and shadow calls
+  ocx combo <sub>             Combo failover/round-robin routing
+  ocx agent <sub>             Subagents, injection, effort caps, and sidecars
+  ocx observe <sub>           Logs, usage, storage, memory, and debug data
+  ocx access <sub>            External API keys and endpoint information
+  ocx grok <sub>              Grok Build model selection and apply
+  ocx system <sub>            Runtime settings, startup, sync, and updates
+  ocx config <sub>            Validated configuration show/get/set/import/export
   ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
   ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
   ocx help [command]          Show help

package/src/cli/index.ts

@@ -94,6 +94,21 @@ async function waitForProxy(timeoutMs = 8_000): Promise<LiveProxy | null> {
   return null;
 }
 
+/**
+ * A Grok fence sync that throws is best-effort by design — it must never block startup.
+ * Reporting nothing, however, is what lets a STALE fence survive: `~/.grok/config.toml`
+ * keeps naming whatever port the last successful sync wrote, and once that listener is
+ * gone every grok turn retries against a refused connection while our own log stays
+ * silent (2026-07-27 field report: 8 entries pinned to a dead 127.0.0.1:4179).
+ * So say what failed and name the single command that repairs it.
+ */
+function grokSyncFailureMessage(err: unknown): string {
+  const detail = err instanceof Error ? err.message : String(err);
+  return `Grok Build config sync failed: ${detail}. `
+    + "~/.grok/config.toml may still point at a previous proxy port — "
+    + "run 'ocx ensure' (or apply from the dashboard's Grok page) to repoint it.";
+}
+
 /** Argv for detached `start`, optionally hard-pinning the listen port. */
 function startArgv(port?: number): string[] {
   const args = [process.argv[1], "start"];
@@ -273,7 +288,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   // Auto-install .zshrc hook (idempotent — skips if already present).
   installShellHook();
 
-  await maybeShowStarPrompt(); // once-only [Y/n] GitHub-star prompt on first interactive start
+  await maybeShowStarPrompt(); // once-only [y/N] GitHub-star prompt on first interactive start
   await syncModelsToCodex(port).catch(() => {});
   if (!currentExternalCodexModelProvider() && !shouldInjectApiAuthHeader(config) && config.syncResumeHistory !== false) {
     historyGuardian = startHistoryMigrationGuardian();
@@ -299,7 +314,14 @@ async function handleStart(options: { block?: boolean } = {}) {
     const r = await syncGrokConfig(port, config, config.hostname ? { hostname: config.hostname } : {});
     if (r.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
     else if (!r.ok) console.error(`⚠️  ${r.message}`);
-  } catch { /* best-effort — grok integration must never block startup */ }
+  } catch (err) {
+    // Best-effort: grok integration must never block startup. But swallowing the error
+    // silently is how a stale fence survives unnoticed — ~/.grok/config.toml keeps
+    // pointing at whatever port the LAST successful sync wrote, and if that listener is
+    // gone every grok turn retries against a refused connection with nothing in our log
+    // to explain it. Name the failure and the one command that repairs it.
+    console.error(`⚠️  ${grokSyncFailureMessage(err)}`);
+  }
   if (options.block ?? true) {
     setInterval(() => {}, 60_000);
     await new Promise<void>(() => {});
@@ -327,7 +349,7 @@ async function handleEnsure() {
         const g = await syncGrokConfig(live.port, config, live.hostname ? { hostname: live.hostname } : {});
         if (g.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
         else if (!g.ok) console.error(`⚠️  ${g.message}`);
-      } catch { /* best-effort */ }
+      } catch (err) { console.error(`⚠️  ${grokSyncFailureMessage(err)}`); }
       console.log(`✅ Proxy running on port ${live.port}`);
       return;
     }
@@ -354,7 +376,7 @@ async function handleEnsure() {
     const g = await syncGrokConfig(port, config, config.hostname ? { hostname: config.hostname } : {});
     if (g.changed) console.log("   + Grok Build config updated (~/.grok/config.toml)");
     else if (!g.ok) console.error(`⚠️  ${g.message}`);
-  } catch { /* best-effort */ }
+  } catch (err) { console.error(`⚠️  ${grokSyncFailureMessage(err)}`); }
   // Always sync the LIVE port: after a fallback-port start, config.port still names the
   // busy preferred port — syncing that would point Codex at a dead listener.
   await syncModelsToCodex(port).catch(e => {
@@ -666,7 +688,8 @@ function handleRecoverHistory() {
 }
 
 switch (command) {
-  case "init": {
+  case "init":
+  case "setup": {
     const { runInit } = await import("./init");
     await runInit();
     break;
@@ -889,9 +912,82 @@ switch (command) {
     process.exitCode = await cmdAccount(args.slice(1));
     break;
   }
-  case "models": {
+  case "models":
+  case "model": {
     const { handleModels } = await import("./models");
-    handleModels(args.slice(1));
+    await handleModels(args.slice(1));
+    break;
+  }
+  case "combo": {
+    const { handleComboCommand } = await import("./combo");
+    process.exitCode = await handleComboCommand(args.slice(1));
+    break;
+  }
+  case "route": {
+    if (args[1] !== "combo") {
+      console.error("Usage: ocx route combo <subcommand>");
+      process.exitCode = 2;
+      break;
+    }
+    const { handleComboCommand } = await import("./combo");
+    process.exitCode = await handleComboCommand(args.slice(2));
+    break;
+  }
+  case "agent": {
+    const { handleAgentCommand } = await import("./agent");
+    process.exitCode = await handleAgentCommand(args.slice(1));
+    break;
+  }
+  case "observe": {
+    const { handleObserveCommand } = await import("./observe");
+    process.exitCode = await handleObserveCommand(args.slice(1));
+    break;
+  }
+  case "logs":
+  case "usage":
+  case "storage":
+  case "memory": {
+    const { handleObserveCommand } = await import("./observe");
+    process.exitCode = await handleObserveCommand([command, ...args.slice(1)]);
+    break;
+  }
+  case "access": {
+    const { handleAccessCommand } = await import("./access");
+    process.exitCode = await handleAccessCommand(args.slice(1));
+    break;
+  }
+  case "api-key": {
+    const { handleAccessCommand } = await import("./access");
+    process.exitCode = await handleAccessCommand(["key", ...args.slice(1)]);
+    break;
+  }
+  case "grok": {
+    const { handleGrokCommand } = await import("./integrations");
+    process.exitCode = await handleGrokCommand(args.slice(1));
+    break;
+  }
+  case "integration": {
+    const integration = args[1];
+    if (integration === "grok") {
+      const { handleGrokCommand } = await import("./integrations");
+      process.exitCode = await handleGrokCommand(args.slice(2));
+    } else if (integration === "claude") {
+      const { handleClaudeConfigCommand } = await import("./integrations");
+      process.exitCode = await handleClaudeConfigCommand(args.slice(2));
+    } else {
+      console.error("Usage: ocx integration <claude|grok> <subcommand>");
+      process.exitCode = 2;
+    }
+    break;
+  }
+  case "system": {
+    const { handleSystemCommand } = await import("./system-command");
+    process.exitCode = await handleSystemCommand(args.slice(1));
+    break;
+  }
+  case "config": {
+    const { handleConfigCommand } = await import("./config-command");
+    process.exitCode = await handleConfigCommand(args.slice(1));
     break;
   }
   case "claude": {
@@ -903,6 +999,11 @@ switch (command) {
       if (exitCode !== 0) process.exit(exitCode);
       break;
     }
+    if (args[1] === "config") {
+      const { handleClaudeConfigCommand } = await import("./integrations");
+      process.exitCode = await handleClaudeConfigCommand(args.slice(2));
+      break;
+    }
     process.exit(await cmdClaude(args.slice(1)));
   }
     case "help":