@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/cli/provider.ts

@@ -8,9 +8,9 @@
  *   show <name>   Show provider config details (secrets masked)
  *   set-default <name>  Change the default provider
  */
-import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig } from "../config";
+import { hasOwnProvider, isValidProviderName, loadConfig, sanitizeModelCostsForDisplay, saveConfig, validateConfigCandidate } from "../config";
 import { apiKeyTransportConfigError, modelCapabilitiesConfigError, mergeModelCapabilities } from "../config/provider-validation";
-import { hasHelpFlag } from "./help";
+import { hasHelpFlag, printSubcommandUsage } from "./help";
 import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
 import { dropProviderCustomModels } from "../providers/provider-id-rewrite";
@@ -19,6 +19,16 @@ import { findLiveProxy } from "../server/proxy-liveness";
 import { syncModelsToCodex } from "../codex/sync";
 import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
 import { modelSelectionGuidance, modelSelectionNextSteps } from "./model-selection-guidance";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers-destination";
+import { providerRelativeSendPathConfigError } from "../config/provider-relative-send-path";
+import type { RuntimeApiDeps } from "./runtime-api";
+import { redactSecretArgs } from "./secret-args";
+import { projectLocalSyncResult, type LocalSyncResult } from "./local-sync-result";
+import { providerManagementConfigError } from "../server/auth-cors";
+
+export interface ProviderCommandDeps extends RuntimeApiDeps {
+  syncModels?: typeof syncModelsToCodex;
+}
 
 // ---------------------------------------------------------------------------
 // Arg helpers
@@ -42,11 +52,13 @@ function consumeFlagValue(args: string[], flag: string): string | undefined {
 /** Reject any leftover args (unknown flags or trailing values). */
 function rejectUnknownArgs(args: string[], usage: string): void {
   if (args.length === 0) return;
-  const unknown = args.filter(a => a.startsWith("-"));
+  const shown = redactSecretArgs(args);
+  // Flags plus redaction markers only: a stray positional may be a credential operand.
+  const unknown = shown.filter(a => a.startsWith("-") || a === "<redacted>");
   if (unknown.length > 0) {
     console.error(`Unknown flag(s): ${unknown.join(", ")}`);
   } else {
-    console.error(`Unexpected argument(s): ${args.join(", ")}`);
+    console.error(`Unexpected argument(s): ${shown.join(", ")}`);
   }
   console.error(usage);
   process.exit(1);
@@ -70,6 +82,16 @@ function validateAndSave(config: ReturnType<typeof loadConfig>): void {
     console.error(`Error: defaultProvider "${config.defaultProvider}" does not exist in providers. Aborting.`);
     process.exit(1);
   }
+  const result = validateConfigCandidate(config);
+  if (!result.ok) {
+    console.error(`Error: ${result.error}`);
+    if (result.error.includes("set allowPrivateNetwork:true")) {
+      console.error("For an intentionally local provider, add --allow-private-network.");
+    } else {
+      console.error("Nothing was saved. Fix the setting named above; if this command did not set it, run ocx config validate and repair it with ocx config set/unset.");
+    }
+    process.exit(1);
+  }
   saveConfig(config);
 }
 
@@ -139,9 +161,9 @@ function handleList(args: string[]): void {
 // provider add
 // ---------------------------------------------------------------------------
 
-const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
+const ADD_USAGE = "Usage: ocx provider add <name> [--adapter <adapter>] [--base-url <url>] [--responses-path <path>] [--auth-mode <key|forward|oauth|local>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--json] [--sync | --live]";
 
-async function handleAdd(args: string[]): Promise<void> {
+async function handleAdd(args: string[], deps: ProviderCommandDeps): Promise<void> {
   const name = args[0];
   if (!name || name.startsWith("-")) {
     console.error(ADD_USAGE);
@@ -164,6 +186,8 @@ async function handleAdd(args: string[]): Promise<void> {
   const adapter = consumeFlagValue(restArgs, "--adapter");
   const baseUrl = consumeFlagValue(restArgs, "--base-url");
   const defaultModel = consumeFlagValue(restArgs, "--default-model");
+  const responsesPath = consumeFlagValue(restArgs, "--responses-path");
+  const authMode = consumeFlagValue(restArgs, "--auth-mode");
   const googleToolSchemaPolicy = consumeFlagValue(restArgs, "--google-tool-schema-policy");
   const textOnly = consumeFlag(restArgs, "--text-only");
   const capabilityModel = consumeFlagValue(restArgs, "--model");
@@ -173,6 +197,12 @@ async function handleAdd(args: string[]): Promise<void> {
     process.exit(1);
   }
 
+  const pathError = providerRelativeSendPathConfigError("responsesPath", responsesPath);
+  if (pathError || (authMode !== undefined && !["key", "forward", "oauth", "local"].includes(authMode))) {
+    console.error(pathError ? `Error: ${pathError}.` : "Error: --auth-mode must be key, forward, oauth, or local.");
+    process.exit(1);
+  }
+
   const config = loadConfig();
 
   const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
@@ -192,9 +222,9 @@ async function handleAdd(args: string[]): Promise<void> {
   if (registryEntry) {
     provConfig = providerConfigSeed(registryEntry);
     if (apiKey) {
-      if (registryEntry.authKind === "forward") {
+      if ((authMode ?? registryEntry.authKind) === "forward") {
         console.warn(`Warning: provider "${name}" uses ChatGPT login (forward auth); --api-key is ignored.`);
-      } else if (registryEntry.authKind === "oauth") {
+      } else if ((authMode ?? registryEntry.authKind) === "oauth") {
         console.warn(`Warning: provider "${name}" uses OAuth auth; --api-key is ignored. Run: ocx login ${name}`);
       } else {
         provConfig.apiKey = apiKey;
@@ -217,6 +247,15 @@ async function handleAdd(args: string[]): Promise<void> {
     };
   }
 
+  if (responsesPath !== undefined) provConfig.responsesPath = responsesPath;
+  if (authMode !== undefined) provConfig.authMode = authMode as OcxProviderConfig["authMode"];
+  if (name === "openai" && (authMode !== undefined || responsesPath !== undefined)
+    && !isCanonicalOpenAiForwardProvider(provConfig)) {
+    console.error("Error: Canonical OpenAI must keep its built-in forward destination and authentication. Use a separate provider name for a custom endpoint.");
+    process.exitCode = 2;
+    return;
+  }
+
   if (apiKeyTransport !== undefined) {
     if (apiKeyTransport !== "x-api-key" && apiKeyTransport !== "bearer") {
       console.error('Error: --api-key-transport must be "x-api-key" or "bearer".');
@@ -259,9 +298,6 @@ async function handleAdd(args: string[]): Promise<void> {
     if (error) { console.error(`Error: ${error}.`); process.exit(1); }
     provConfig.modelCapabilities = mergeModelCapabilities(provConfig.modelCapabilities, declaration);
   }
-  const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
-  initializeProviderModelSelection(name, provConfig, existingProvider, config);
-  config.providers[name] = provConfig;
   // A --force overwrite rotates the key/endpoint but must not drop a
   // user-configured price overlay (same rule as the /api/providers path and
   // the login paths); there is no explicit clear/replace flag yet.
@@ -269,10 +305,38 @@ async function handleAdd(args: string[]): Promise<void> {
     provConfig.modelCosts = existingProvider.modelCosts;
   }
   if (allowPrivateNetwork) provConfig.allowPrivateNetwork = true;
+  // New auth/path overrides use the management owner's completed-row contract.
+  // Validate overrides before registration state changes; the full candidate is
+  // validated again by validateAndSave for every local save.
+  if ((authMode !== undefined || responsesPath !== undefined)
+    && providerManagementConfigError(name, provConfig)) {
+    console.error("Error: Invalid provider configuration. Authentication, destination and provider options must satisfy the provider's management rules.");
+    process.exitCode = 2;
+    return;
+  }
+  const { initializeProviderModelSelection } = await import("../providers/initial-model-selection");
+  initializeProviderModelSelection(name, provConfig, existingProvider, config);
+  config.providers[name] = provConfig;
   if (setDefault) config.defaultProvider = name;
 
   validateAndSave(config);
 
+  let sync: LocalSyncResult | undefined;
+  if (wantsSync) {
+    try {
+      const live = await (deps.findLiveProxy ?? findLiveProxy)();
+      if (!live) sync = { status: "not-running", ok: false };
+      else {
+        const result = await (deps.syncModels ?? syncModelsToCodex)(live.port, config, null);
+        sync = projectLocalSyncResult(result);
+      }
+    } catch {
+      // Dependency errors can contain keys, paths or request details. Keep a fixed outcome.
+      sync = { status: "failed", ok: false };
+    }
+    if (!sync.ok || sync.status === "refused") process.exitCode = 1;
+  }
+  const synced = sync?.status === "applied" && sync.ok;
   if (wantsJson) {
     console.log(JSON.stringify({
       action: "added",
@@ -283,26 +347,13 @@ async function handleAdd(args: string[]): Promise<void> {
       defaultModel: provConfig.defaultModel ?? null,
       isDefault: config.defaultProvider === name,
       source: registryEntry ? "registry" : "custom",
-      needsSync: true,
+      needsSync: !synced,
+      ...(sync ? { sync } : {}),
     }, null, 2));
     return;
   }
 
-  let codexSyncSkipped = false;
-  if (wantsSync) {
-    const live = await findLiveProxy();
-    if (live) {
-      const synced = await syncModelsToCodex(live.port).catch(e => {
-        console.error(`Warning: sync failed: ${e instanceof Error ? e.message : String(e)}`);
-        return null;
-      });
-      if (synced?.status === "skipped") {
-        codexSyncSkipped = true;
-        console.log("Provider saved; Codex integration is OFF, so Codex sync was skipped.");
-      }
-    }
-  }
-
+  if (sync?.warning) console.log(`   Warning: ${sync.warning}`);
   const registryLabel = registryEntry ? ` (${registryEntry.label})` : "";
   console.log(`✅ Provider "${name}"${registryLabel} added.`);
   for (const line of modelSelectionGuidance(name)) console.log(line);
@@ -315,10 +366,15 @@ async function handleAdd(args: string[]): Promise<void> {
     console.log(`   Set API key with: ocx provider add ${name} --api-key <key> --force`);
     console.log(`   Or set env var: ${envKey}`);
   }
-  if (wantsSync && !codexSyncSkipped) {
-    console.log(`   Models synced to Codex.`);
-  } else {
-    console.log(`   Apply to Codex: ocx sync`);
+  if (synced) console.log("   Models synced to Codex.");
+  else {
+    if (sync) {
+      console.log(sync.configApplied && !sync.ok
+        ? "   Provider saved; sync remains incomplete despite config injection."
+        : `   Provider saved; client sync outcome: ${sync.status}.`);
+      if (sync.catalog && !sync.catalog.converged) console.log("   Model catalog did not converge; inspect the target before retrying.");
+    }
+    console.log("   Apply to Codex: ocx sync");
   }
 }
 
@@ -472,49 +528,45 @@ function handleSetDefault(args: string[]): void {
 // Router (F2 fix: handle help flags internally, like service/codex-shim)
 // ---------------------------------------------------------------------------
 
-const PROVIDER_USAGE = `Usage: ocx provider <subcommand>
-
-Subcommands:
-  list                  List configured and available providers
-  add <name>            Add a provider (registry or custom)
-  edit <name>           Edit live provider fields
-  test <name>           Test the provider's upstream model endpoint
-  remove <name>         Remove a configured provider
-  show <name>           Show provider config details
-  set-default <name>    Change the default provider
-  selected <name>       Show or set the provider model allowlist
-  quota                 Show provider quota reports
-  resets                Show recently detected quota resets
-  presets               List GUI provider presets
-  account-mode <mode>   Set OpenAI Codex pool/direct mode
-
-Examples:
-  ocx provider list
-  ocx provider list --jsonl
-  ocx provider add anthropic --api-key sk-ant-...
-  ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1
-  ocx provider show anthropic --json
-  ocx provider set-default anthropic
-  ocx provider edit xai --xai-chat on   # opt Grok 4.5/4.6 into Chat Completions
-  ocx provider edit xai --xai-chat off  # use Responses again
-  ocx provider remove my-ollama`;
-
-export async function handleProviderCommand(args: string[]): Promise<void> {
+
+export async function handleProviderCommand(args: string[], deps: ProviderCommandDeps = {}): Promise<void> {
   const sub = args[0];
 
   if (!sub || sub === "help" || hasHelpFlag(args)) {
-    console.log(PROVIDER_USAGE);
+    printSubcommandUsage("provider");
     process.exit(0);
   }
 
   const subArgs = args.slice(1);
+  const liveArgs = subArgs.filter(arg => arg === "--live" || arg.startsWith("--live="));
+  if (liveArgs.length) {
+    if (liveArgs.length !== 1 || liveArgs[0] !== "--live" || !["add", "remove", "set-default"].includes(sub)) {
+      console.error("Error: --live is a single boolean flag for provider add, remove, or set-default.");
+      process.exitCode = 2;
+      return;
+    }
+    subArgs.splice(subArgs.indexOf("--live"), 1);
+    const { handleProviderLifecycleRuntimeCommand } = await import("./provider-lifecycle-runtime");
+    process.exitCode = await handleProviderLifecycleRuntimeCommand(sub as "add" | "remove" | "set-default", subArgs, deps);
+    return;
+  }
+  if (sub === "snapshot" || sub === "apply") {
+    const { handleProviderBatchCommand } = await import("./provider-batch");
+    process.exitCode = await handleProviderBatchCommand(sub, subArgs, deps);
+    return;
+  }
+  if (sub === "pacing") {
+    const { handleProviderPacingCommand } = await import("./provider-settings");
+    process.exitCode = await handleProviderPacingCommand(subArgs, deps);
+    return;
+  }
 
   switch (sub) {
     case "list":
       handleList(subArgs);
       break;
     case "add":
-      await handleAdd(subArgs);
+      await handleAdd(subArgs, deps);
       break;
     case "remove":
       handleRemove(subArgs);
@@ -527,13 +579,13 @@ export async function handleProviderCommand(args: string[]): Promise<void> {
       break;
     default: {
       const { handleProviderRuntimeCommand } = await import("./provider-runtime");
-      const code = await handleProviderRuntimeCommand(sub, subArgs);
+      const code = await handleProviderRuntimeCommand(sub, subArgs, deps);
       if (code !== null) {
         process.exitCode = code;
         break;
       }
-      console.error(`Unknown provider subcommand: ${sub}`);
-      console.error(PROVIDER_USAGE);
+      console.error(`Unknown provider subcommand: ${redactSecretArgs([sub ?? ""])[0]}`);
+      printSubcommandUsage("provider", undefined, { write: console.error });
       process.exit(1);
     }
   }

package/src/cli/registry.ts

@@ -144,18 +144,19 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "Port: ocx link port [--json]",
       "Issue: ocx link issue --alias <alias> --tunnel-port <port> [--json]",
       "Status: ocx link status [--json]",
-      "Revoke: ocx link revoke --link-id <id> [--json]",
+      "Revoke: ocx link revoke --link-id <id> [--force --yes] [--json]",
       "Issue, status, and revoke use the running proxy's loopback management API and admin token.",
     ],
   },
   {
     name: "remote-workspace",
-    usage: "ocx remote-workspace <pair|agent|status>",
-    summary: "Pair this OCX-only computer with a hub and run its remote workspace executor.",
+    usage: "ocx remote-workspace <pair|agent|status|hub>",
+    summary: "Manage this workspace executor or inspect the selected Hub.",
     details: [
       "Pair: ocx remote-workspace pair <hub-url> --pairing-code-stdin --root <absolute-path> [--toolchain-root <absolute-directory>] [--executor-helper <absolute-file>] [--name <device-name>]",
       "Agent: ocx remote-workspace agent",
       "Status: ocx remote-workspace status [--json]",
+      "Hub: ocx remote-workspace hub <status|runtimes|sessions> [--json]",
       "Codex, Claude Code, Pi, provider logins, and API keys remain on the hub; only workspace tools execute here.",
     ],
   },
@@ -275,12 +276,42 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "provider",
-    usage: "ocx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
+    usage: "ocx provider <subcommand>",
     summary: "Non-interactive provider management.",
     details: [
-      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
+      "Subcommands:",
+      "  list                  List configured and available providers",
+      "  add <name>            Add a provider (registry or custom)",
+      "  edit <name>           Edit live provider fields",
+      "  pacing <name>         Read/edit live request pacing rules",
+      "  snapshot              Read a non-secret provider editor baseline",
+      "  apply                 Apply edited providers with baseline conflict checks",
+      "  test <name>           Test the provider's upstream model endpoint",
+      "  remove <name>         Remove a configured provider",
+      "  show <name>           Show provider config details",
+      "  set-default <name>    Change the default provider",
+      "  add/remove/set-default support --live; live removal also requires --yes.",
+      "  selected <name>       Show or set the provider model allowlist",
+      "  quota                 Show provider quota reports",
+      "  resets                Show recently detected quota resets",
+      "  presets               List GUI provider presets",
+      "  account-mode <mode>   Set OpenAI Codex pool/direct mode",
+      "",
+      "Examples:",
+      "  ocx provider list",
+      "  ocx provider list --jsonl",
+      "  ocx provider presets --json",
+      "  ocx provider add anthropic --api-key <key>",
+      "  ocx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1",
+      "  ocx provider show anthropic --json",
+      "  ocx provider pacing anthropic --json",
+      "  ocx provider snapshot --json",
+      "  ocx provider set-default anthropic",
+      "  ocx provider edit xai --xai-chat on   # opt Grok 4.5/4.6 into Chat Completions",
+      "  ocx provider edit xai --xai-chat off  # use Responses again",
+      "  ocx provider remove my-ollama",
+      "",
       "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
-      "Run `ocx provider --help` for full usage and examples.",
     ],
   },
   {
@@ -296,6 +327,11 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.",
       "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.",
+      "pool <provider>          Read/edit runtime-supported pool policy.",
+      "credits openai ...       Explicit paid-credit-after-limit policy; separate from displaying balances.",
+      "quota-activation openai  Enable/disable one account reset-window refresh policy.",
+      "anthropic-reset-grants   Read grant status only; consumption remains in the dashboard.",
+      "login supports explicit browser/add-account options only for applicable flows; human verification remains required.",
       "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.",
       "grok-reset-coupons [<id>] [--consume --yes] Inspect or redeem Grok reset coupons.",
@@ -316,6 +352,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     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).",
+      "add/remove support --live for the selected proxy; live or JSON removal requires --yes.",
+      "Local add/remove JSON reports saved state and opportunistic sync; no proxy keeps the save successful/pending.",
+      "display-name <provider/raw-model> --set <label> or --clear changes an exact upstream model label.",
+      "order status/set/reset manages routed picker order; reset native-inclusive saved order before replacement.",
       "add: register a model the provider catalog does not advertise yet.",
       "  --display-name <name>     Human label (no slashes).",
       "  --context-window <tokens> e.g. 200000.",
@@ -333,12 +373,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "companion",
-    usage: "ocx companion <show|set|reset> ...",
-    summary: "Inspect and configure menu-bar and widget companion usage settings.",
+    usage: "ocx companion <show|set|reset|usage|timeline> ...",
+    summary: "Inspect companion settings, filtered usage and timeline, or change preferences.",
     details: [
       "ocx companion and ocx companion show read settings; use --json for machine-readable output.",
       "ocx companion set accepts one or more key=value assignments; values are parsed as JSON when possible.",
       "ocx companion reset restores the default settings.",
+      "ocx companion usage reads today and 30-day totals with saved model/provider filters; unavailable ranges return partial output and exit 1.",
+      "ocx companion timeline reads buckets; --model selects models and --hide-provider excludes providers.",
     ],
   },
   {
@@ -349,8 +391,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "route",
-    usage: "ocx route combo <list|show|set|remove> ...",
-    summary: "Manage routing features; combo is currently the supported routing resource.",
+    usage: "ocx route <combo|policy> <subcommand>",
+    summary: "Manage combo routing and routing profiles.",
   },
   {
     name: "effort",
@@ -383,11 +425,11 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "`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: "logs", usage: "ocx logs [filters] [--follow] [--json|--jsonl|--events]", summary: "Read or follow request logs." },
   {
     name: "usage",
-    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.",
+    usage: "ocx usage [--range <today|1d|7d|30d|all>] [--surface <all|codex|claude|grok>] [--provider <name>] [--model <id>] [--api-key-id <id>] [--search <text>] [--json]",
+    summary: "Report token usage and estimated cost (alias of ocx observe usage).",
   },
   {
     name: "storage",
@@ -401,14 +443,17 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   { name: "memory", usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
   {
     name: "access",
-    usage: "ocx access <key|endpoints|models|test> ...",
+    usage: "ocx access <key|endpoints|models|test|audio> ...",
     summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
     details: [
       "Key rotation start uses POST /api/keys/rotate and returns the replacement secret once.",
       "Commit uses POST /api/keys/rotate/commit; abort uses DELETE /api/keys/rotate with the returned rotation id.",
+      "key rename changes a masked key's name without clearing its scopes.",
+      "test --api-key-stdin uses one supplied data key; it never substitutes management or enrolled credentials.",
+      "audio transcribe/live-check use explicit piped key input and may use provider quota; authorize the operation first.",
     ],
   },
-  { name: "api-key", usage: "ocx api-key <list|create|rotate|remove> ...", summary: "Alias of ocx access key." },
+  { name: "api-key", usage: "ocx api-key <list|get|create|set|rename|rotate|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "api",
     usage: "ocx api <protocols|explain|policy> ...",
@@ -444,14 +489,18 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     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.",
+      "client preview shows a proposed change; enable/disable/restore accept an optional --plan-fingerprint.",
+      "client history remove requires --yes; client sync --client aside refreshes managed Aside profiles.",
+      "native cursor status/local-installer are reads; installer lookup does not install anything.",
     ],
   },
   {
     name: "system",
-    usage: "ocx system <status|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...",
+    usage: "ocx system <status|health|settings|startup|diagnostics|sync|codex-app-server|codex-restart|update|codex-cli-update> ...",
     summary: "Manage headless runtime settings, startup, sync, diagnostics, OpenCodex updates, and read-only Codex CLI inspection.",
     details: [
       "system update manages OpenCodex itself.",
+      "system health reads authenticated service and spend-ledger diagnostics; root health remains liveness.",
       "ocx system codex-cli-update check [--json]",
       "ocx system codex-cli-update attest [--json]",
       "ocx system codex-cli-update attest --candidate <absolute-path> --npm-prefix <absolute-path> --npm-cli <absolute-path> --node <absolute-path> [--json]",
@@ -460,9 +509,14 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "config",
-    usage: "ocx config <show|get|set|unset|validate|export|import> ...",
+    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."],
+    details: [
+      "show is the default: ocx config [show] [--json] [--source]. Flags alone also display the local configuration without a running proxy.",
+      "--json may precede an explicit action without changing which action runs.",
+      "--source is only supported for show and includes diagnostic source, error, and warning fields.",
+      "Secrets are masked by show/get. Import requires --yes and validates before writing.",
+    ],
   },
   {
     name: "claude",
@@ -487,6 +541,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "  ocx claude desktop default <family> <route|none>",
       "  ocx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
       "  ocx claude desktop import <path> [--apply]         Validate and import JSON",
+      "  ocx claude desktop profile show [--json]           Read the running proxy's profile",
+      "  ocx claude desktop profile import <file|-> [--json] Save the running profile without applying",
       "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.",
@@ -503,7 +559,7 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "and `providers.opencodex` blocks injected through OpenCode's inline runtime layer",
       "(`OPENCODE_CONFIG_CONTENT`). Any existing inline config in the environment is preserved",
       "and only `provider.opencodex` and `providers.opencodex` are overwritten for this launch.",
-      "Only the V2 block (`providers.opencodex`) carries the reasoning-effort variants.",
+      "V1 receives reasoning-effort variant maps; V2 receives native variant arrays for the same declared choices and defaults.",
       "Global/project opencode.json may be read to warn about an existing provider.opencodex or",
       "providers.opencodex override; on-disk files are never modified.",
       "Routed models appear in the model picker as opencodex/<provider>/<model>.",
@@ -536,8 +592,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     summary: "Connect ZCode (Z.ai desktop client) to the proxy via its managed provider.",
     details: [
       "Alias of ocx integration client <sub> --client zcode.",
-      "enable writes the managed provider.opencodex block into ~/.zcode/v2/config.json; disable removes only that block.",
-      "ZCode 3.14 moved its providers to ~/.zcode/v2/provider_config.json; where that file exists, enable is refused because the write cannot reach the client.",
+      "enable manages ~/.zcode/v2/provider_config.json with schemaVersion 1; if the store is absent, it writes the legacy provider.opencodex block into ~/.zcode/v2/config.json.",
+      "A surviving owned legacy block prevents switching stores. Run `ocx zcode disable` before enabling the current store. Unknown store schemas are refused.",
       "ZCode reads its config at startup — restart ZCode after enable/disable.",
       "Select OpenCodex Proxy/<provider>/<model> from ZCode's model picker.",
     ],
@@ -545,7 +601,13 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   {
     name: "restart",
     usage: "ocx restart",
-    summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
+    summary: "Request a graceful restart of the verified running proxy, preserving routing.",
+    details: [
+      "If no proxy is running, use the normal `ocx ensure` start policy, including the Codex autostart setting.",
+      "Unverifiable running targets are refused without a stop/start fallback.",
+      "Restarting an older proxy from this newer CLI requires standalone macOS/Linux proxies; supervised, shared, foreground, or unverifiable targets are refused.",
+      "For a service-managed update, run `ocx service restart`; for a desktop-managed update, restart through the OpenCodex desktop app.",
+    ],
   },
   {
     name: "v2",
@@ -604,8 +666,8 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   {
     name: "lab",
-    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
-    summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
+    usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog|production-signals|public|automation|run> [options] [--json]",
+    summary: "Inspect local Compatibility Lab evidence and explicitly control automation.",
     details: [
       "status                Projection availability, schema versions, and row counts.",
       "verdicts              Paginated derived compatibility verdicts with filters.",
@@ -614,6 +676,10 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
       "events                Event history; event <id> returns one safe typed event.",
       "artifacts             Artifact metadata only (no content download).",
       "catalog               Packaged protocol/live scenario catalog metadata.",
+      "production-signals    Local passive routing evidence for a subject.",
+      "public                Preview/export local evidence; verify/import a bundle.",
+      "automation            Read status/runs or explicitly enable/disable local policy.",
+      "run                   Explicit manual scenario; live probes can consume quota.",
       "Reads never rebuild the projection, trigger probes, or require the proxy.",
     ],
   },

package/src/cli/remote-workspace-hub.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { REMOTE_WORKSPACE_CAPABILITIES, isRemoteWorkspaceToolName } from "../remote-control/workspace-tools";
+import { runCatalogAction } from "./catalog-command-result";
+import { CliUsageError, RuntimeApiError, printData, rejectArgs, runtimeRequest, takeFlag, type RuntimeApiDeps } from "./runtime-api";
+
+export const REMOTE_WORKSPACE_HUB_USAGE = "Usage: ocx remote-workspace hub [status|runtimes|sessions] [--json]";
+const UNAVAILABLE = "Remote Workspace requires Hub mode and OCX_REMOTE_WORKSPACE_ENABLED=1. Run this command on the intended Hub.";
+const identity = z.string().min(1);
+const capabilities = z.array(z.enum(REMOTE_WORKSPACE_CAPABILITIES));
+const root = z.object({ id: identity, label: z.string() });
+const device = z.object({
+  id: identity, name: z.string(), platform: z.string(), capabilities, roots: z.array(root),
+  online: z.boolean(), createdAt: z.string(), lastSeenAt: z.string().nullable(),
+});
+const availability = z.object({ available: z.boolean(), version: z.string().optional(), reason: z.string().optional() });
+const runtimes = z.object({ codex: availability, claude: availability, pi: availability });
+const event = z.object({ sequence: z.number().int().nonnegative(), at: z.string(),
+  type: z.enum(["status", "assistant", "tool", "error"]), text: z.string() });
+const session = z.object({
+  id: identity, profile: z.enum(["codex", "claude", "pi"]), accessMode: z.enum(["read-only", "workspace"]),
+  deviceId: identity, deviceName: z.string(), rootId: identity, rootLabel: z.string(), capabilities,
+  tools: z.array(z.custom<string>(isRemoteWorkspaceToolName)), threadId: z.string().nullable(),
+  resumable: z.boolean(), status: z.enum(["starting", "ready", "running", "waiting_for_executor", "failed", "stopped"]),
+  createdAt: z.string(), updatedAt: z.string(), events: z.array(event),
+});
+const sessions = z.array(session);
+const status = z.object({ available: z.literal(true), devices: z.array(device), runtimes, sessions });
+const unavailable = z.object({ available: z.literal(false), reason: z.string(),
+  devices: z.array(z.unknown()).length(0), runtimes: z.object({}).strict(), sessions: z.array(z.unknown()).length(0) });
+
+/** Hub observations use management admission; executor pairing and session writes remain separate. */
+export async function handleRemoteWorkspaceHubCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCatalogAction(async () => {
+    const args = [...argv];
+    const wantsJson = takeFlag(args, "--json");
+    const action = args.shift() ?? "status";
+    rejectArgs(args, REMOTE_WORKSPACE_HUB_USAGE);
+    if (!["status", "runtimes", "sessions"].includes(action)) {
+      throw new CliUsageError("Expected Hub status, runtimes or sessions", REMOTE_WORKSPACE_HUB_USAGE);
+    }
+    const path = `/api/remote-workspace${action === "status" ? "" : `/${action}`}`;
+    let raw: unknown;
+    try {
+      raw = await runtimeRequest(path, { redirect: "error" }, deps);
+    } catch (error) {
+      // The inner owner can refuse after activation changed; the outer owner uses a 200 observation.
+      if (error instanceof RuntimeApiError && error.status === 409) {
+        console.error(`Error: ${UNAVAILABLE}`);
+        return 5;
+      }
+      throw error;
+    }
+    if (unavailable.safeParse(raw).success) {
+      printData({ available: false, reason: UNAVAILABLE, devices: [], runtimes: {}, sessions: [] }, wantsJson, [UNAVAILABLE]);
+      return 1;
+    }
+    if (action === "status") {
+      const parsed = status.safeParse(raw);
+      if (!parsed.success) throw new Error("Invalid Hub observation");
+      const data = parsed.data;
+      printData(data, wantsJson, [
+        `Remote Workspace Hub: ${data.devices.length} device(s), ${data.sessions.length} session(s).`,
+        ...data.devices.map(row => `${row.id}  ${row.name}: ${row.online ? "online" : "offline"} (${row.roots.length} workspace root(s))`),
+        ...(data.devices.length ? [] : ["No paired devices. Pair a device from the Hub dashboard."]),
+        ...Object.entries(data.runtimes).map(([name, row]) => `${name}: ${row.available ? "available" : "unavailable"}${row.version ? ` (${row.version})` : ""}`),
+      ]);
+      return 0;
+    }
+    if (action === "runtimes") {
+      const parsed = z.object({ runtimes }).safeParse(raw);
+      if (!parsed.success) throw new Error("Invalid runtime observation");
+      printData(parsed.data, wantsJson, Object.entries(parsed.data.runtimes).map(([name, row]) =>
+        `${name}: ${row.available ? "available" : "unavailable"}${row.version ? ` (${row.version})` : ""}${row.reason ? ` — ${row.reason}` : ""}`));
+      return 0;
+    }
+    const parsed = z.object({ sessions }).safeParse(raw);
+    if (!parsed.success) throw new Error("Invalid session observation");
+    printData(parsed.data, wantsJson, parsed.data.sessions.length
+      ? parsed.data.sessions.map(row => `${row.id}  ${row.profile}: ${row.status} (${row.deviceName} / ${row.rootLabel}, ${row.accessMode})`)
+      : ["No Remote Workspace sessions. Create a session from the Hub dashboard."]);
+    return 0;
+  });
+}