@bitkyc08/opencodex 2.39.0 → 2.40.0

package/src/cli/help.ts

@@ -38,6 +38,8 @@ Usage:
   ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
   ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
   ocx ensure                  Ensure the proxy is running and Codex config/cache are current
+  ocx connect <url>           Connect this machine to a remote OpenCodex hub (credential via stdin)
+  ocx disconnect              Restore local state and clear the hub connection
   ocx sync [--restart-codex]  Fetch models from providers and inject into Codex config
   ocx sync-cache [--restart-codex]
                               Refresh Codex's model cache from the active catalog
@@ -50,7 +52,8 @@ Usage:
   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 gui [pair --origin <browser-origin> [--json]]
+                              Open the dashboard or create a single-use remote pairing grant
   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|keep-native-v1|threads|mode-hint)

package/src/cli/index.ts

@@ -9,6 +9,7 @@ import {
   runCodexHistoryJob,
 } from "../codex/history-job";
 import { reconcileJournal } from "../codex/journal";
+import { inspectClientRotationRecoveryGate, readClientConnectionState } from "../client/state";
 import {
   codexAutoStartEnabled,
   getConfigDir,
@@ -48,7 +49,7 @@ import {
 } from "./tray-proxy";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
-import { dispatchCommand } from "./dispatch";
+import { dispatchCommand , decideStartWithLiveOwner } from "./dispatch";
 import { findAvailablePort, isAddrInUse, PortUnavailableError, shouldPersistSelectedPort, waitForPortAvailable } from "../server/ports";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { createReadinessGate } from "../server/readiness";
@@ -58,7 +59,6 @@ import { isProcessAlive, ProxyOwnershipRefusedError, stopProxy } from "../lib/pr
 import { loadServiceTokenFromFile } from "../lib/service-secrets";
 import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
 import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
-import { drainAndShutdown, isRecyclingForExit, startServer } from "../server";
 import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
 import { startTokenGuardian } from "../oauth/token-guardian";
@@ -149,7 +149,10 @@ function startArgv(port?: number): string[] {
   return selfLaunchArgv(args);
 }
 
-async function chooseListenPort(requestedPort?: number): Promise<number> {
+async function chooseListenPort(
+  requestedPort?: number,
+  options: { sibling?: boolean } = {},
+): Promise<number> {
   const config = loadConfig();
   const preferred = requestedPort ?? config.port ?? 10100;
   const hardPin = requestedPort !== undefined && requestedPort > 0;
@@ -197,7 +200,7 @@ async function chooseListenPort(requestedPort?: number): Promise<number> {
     if (preferred > 0 && selected !== preferred) {
       console.log(`⚠️  Port ${preferred} is busy; starting opencodex on ${selected}.`);
     }
-    if (shouldPersistSelectedPort(config.port, selected, preferred)) {
+    if (shouldPersistSelectedPort(config.port, selected, preferred, options)) {
       config.port = selected;
       saveConfig(config);
     }
@@ -224,7 +227,12 @@ async function findProxyOwnerBeforeJournalRecovery(
   // The probe established that the snapshotted owner is stale. Compare before
   // deleting so a concurrent start that rewrote the PID file keeps its state.
   removePidIfValueIs(pidSnapshot);
-  if (!currentExternalCodexModelProvider()) reconcileJournal();
+  if (!currentExternalCodexModelProvider()) {
+    const clientState = readClientConnectionState();
+    reconcileJournal(clientState.kind === "connected"
+      ? { activeClientApiKeyId: clientState.value.apiKeyId }
+      : undefined);
+  }
   return { live: null, pidSnapshot };
 }
 
@@ -248,20 +256,52 @@ async function handleStart(options: { block?: boolean } = {}) {
   // shutdown then left no runtime record for discovery at all. `handleEnsure`
   // already passes this; `handleStart` is the path that did not.
   const owner = await findProxyOwnerBeforeJournalRecovery({ probeConfiguredPort: true });
+  let siblingStart = false;
   if (owner.live) {
-    // Service-wrapper context (opencodex-service.cmd `:loop`): a healthy proxy from
-    // ANY source means the requested port is already served. Exit 0 so the wrapper's
-    // `if %ERRORLEVEL% NEQ 0` retry loop terminates instead of respawning every 5s
-    // against a listener it can never claim (observed as an endless
-    // "Proxy already running" service.log loop).
-    // Only the exact "1" sentinel takes this path — the same check syncCleanup
-    // uses — so an env value like "0" or "false" cannot bypass the conflict error.
-    if (process.env.OCX_SERVICE === "1") {
+    // Rationale and the full decision table live on `decideStartWithLiveOwner`.
+    const decision = decideStartWithLiveOwner({
+      livePort: owner.live.port,
+      requestedPort,
+      ocxService: process.env.OCX_SERVICE,
+    });
+    if (decision === "service-stay-out") {
+      // Service-wrapper context (opencodex-service.cmd `:loop`): a healthy proxy from
+      // ANY source means the requested port is already served. Exit 0 so the wrapper's
+      // `if %ERRORLEVEL% NEQ 0` retry loop terminates instead of respawning every 5s
+      // against a listener it can never claim (observed as an endless
+      // "Proxy already running" service.log loop).
       console.log(`Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}); service wrapper staying out of the way.`);
       process.exit(0);
     }
-    console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
-    process.exit(1);
+    if (decision === "refuse") {
+      console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+      process.exit(1);
+    }
+    // Sibling path. Honest about the side effects it shares with any start in this home:
+    // the new instance takes over this home's ocx.pid / runtime-port.json while it runs,
+    // and re-points this home's Codex config at the new port when injection applies.
+    // What it must NOT do is persist its port into config.port: the configured-port
+    // proxy is still the owner of this home, and a later `ocx service` reads config.port
+    // to bake the service (observed: a probe on 10198 left the service pinned there).
+    siblingStart = true;
+    console.warn(
+      `Proxy already running on port ${owner.live.port}; starting a second instance on requested port ${requestedPort}. `
+      + `The new instance takes over this home's pid/runtime records and Codex config while it runs.`,
+    );
+  }
+
+  const clientState = readClientConnectionState();
+  if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
+    throw new Error(`client startup refused: ${clientState.reason}`);
+  }
+  const rotationGate = inspectClientRotationRecoveryGate(clientState);
+  if (clientState.kind === "connected") {
+    if (rotationGate.kind === "recovery-required" || rotationGate.kind === "unsafe") {
+      throw new Error(`client startup refused: ${rotationGate.reason}`);
+    }
+    const { startClientRuntime } = await import("../client/runtime");
+    await startClientRuntime({ port: requestedPort, block: options.block });
+    return;
   }
 
   // Interactive-only update prompt. Must run BEFORE we bind a port / write a
@@ -272,7 +312,8 @@ async function handleStart(options: { block?: boolean } = {}) {
   // Port selection is check-then-bind: a concurrent `ocx start`/`ensure` can win the port
   // between the probe and Bun.serve. Soft starts may re-pick; hard-pinned `--port` retries
   // the same port only (never hop — that was the remaining PR #152 gap).
-  let port = await chooseListenPort(requestedPort);
+  let port = await chooseListenPort(requestedPort, { sibling: siblingStart });
+  const { drainAndShutdown, isRecyclingForExit, startServer } = await import("../server");
   // One private readiness gate for this startServer invocation, captured by the
   // listener's closure. handleStart owns it and transitions it after the
   // post-startup sync settles. A second startServer in the same process would
@@ -301,7 +342,7 @@ async function handleStart(options: { block?: boolean } = {}) {
         continue;
       }
       console.log(`⚠️  Port ${port} was taken while starting; picking another...`);
-      port = await chooseListenPort(requestedPort);
+      port = await chooseListenPort(requestedPort, { sibling: siblingStart });
     }
   }
   // A single request's streaming error must never crash the daemon serving every
@@ -737,6 +778,7 @@ async function handleStop() {
   // restart-window wait; launchd, systemd and WinSW are down when they say so.
   let schedulerCanRespawn = false;
   let stoppedService = false;
+  let nativeRestoreHandledByProxy = false;
   // An ownership mismatch means the service manager was never even contacted: the installed
   // service is still live and will respawn the proxy. Tearing down SHARED state in that
   // situation (native Codex config, the Grok fence) removes config out from under a running
@@ -785,17 +827,22 @@ async function handleStop() {
    * guessed one fails closed into manual recovery rather than letting a later probe read
    * "the configured port refuses" as proof that the right proxy is down.
    */
-  const stopWithDeferral = async (pid: number, discovered?: { hostname: string; port: number } | null): Promise<void> => {
+  const stopWithDeferral = async (pid: number, discovered?: { hostname: string; port: number } | null): Promise<boolean> => {
     // Resolve ONCE. Reading the runtime record twice let the receipt name the configured
     // guess while the request went to a runtime endpoint that appeared in between.
     const exact = discovered ?? endpointOf(readRuntimePort(pid));
     claimTeardown(exact ?? configuredEndpoint(), exact ? "exact" : "guessed");
-    await stopProxy(pid, {
+    const graceful = await stopProxy(pid, {
       deferSharedTeardownNonce: teardownNonce,
       // Only an exact endpoint may direct the request; the configured fallback is a guess
       // good enough to record an obligation against, not to POST a stop to.
       runtimeEndpoint: exact ?? undefined,
     });
+    // A valid receipt means the proxy deferred shared teardown to this process. If the
+    // receipt could not be written, the proxy restores it itself and the caller must not
+    // attempt a second restore after a graceful stop. A hard-kill always leaves restore
+    // to this process.
+    return graceful && !teardownNonce;
   };
   try {
     const serviceStop = stopServiceIfInstalledDetailed();
@@ -838,7 +885,7 @@ async function handleStop() {
       // verification below, so a survivor does not get its client config pulled first.
       // The receipt goes down first — the proxy honours the deferral only when it can
       // see one, so an unrecordable claim degrades to the child doing its own teardown.
-      await stopWithDeferral(pid);
+      nativeRestoreHandledByProxy = await stopWithDeferral(pid);
       console.log(`✅ Proxy (PID ${pid}) stopped.`);
       removePid(pid);
       removeRuntimePort(pid);
@@ -868,7 +915,10 @@ async function handleStop() {
       try {
         // The probe already found where it answers, and on this path the runtime record is
         // typically what went missing in the first place.
-        await stopWithDeferral(live.pid, { hostname: live.hostname ?? "127.0.0.1", port: live.port });
+        nativeRestoreHandledByProxy = await stopWithDeferral(
+          live.pid,
+          { hostname: live.hostname ?? "127.0.0.1", port: live.port },
+        );
         console.log(`✅ Proxy (PID ${live.pid}) stopped.`);
       } catch (err) {
         stopFailed = true;
@@ -986,7 +1036,7 @@ async function handleStop() {
       console.error("   The obligation is preserved; retry once the proxy is confirmed stopped.");
     }
   }
-  const restoreBlocked = ownershipBlocked || inheritedBlocks;
+  const restoreBlocked = ownershipBlocked || inheritedBlocks || nativeRestoreHandledByProxy;
   if (!restoreBlocked) {
     if (recoveredNonces.length > 0) {
       // A previous deferred stop died before restoring, and the probe says its endpoint is
@@ -1294,6 +1344,10 @@ async function handleStatus() {
   console.log(`   Runtime: ${status.json.paths.runtime}`);
   console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}`);
   console.log(`   Default provider: ${status.json.defaultProvider}`);
+  console.log(`   Remote hub: ${status.json.connection.state}${status.json.connection.serverUrl ? ` (${status.json.connection.serverUrl})` : ""}`);
+  if (status.json.connection.state === "invalid" || status.json.connection.state === "mismatched") {
+    console.log(`   ⚠️  ${status.json.connection.reason}`);
+  }
   console.log(`   Codex autostart: ${status.json.codexAutostart ? "enabled" : "disabled"}`);
   console.log(`   Restart safety: ${startupHealthSummary(status.json.startup)}`);
   console.log(`   ${formatStartupRoutingDetail(status.json.startup)}`);

package/src/cli/models-runtime-subcommands.ts

@@ -0,0 +1,34 @@
+/**
+ * The `ocx models` subcommands that live in `models-runtime` and talk to the
+ * management API, rather than editing `config.json` directly.
+ *
+ * This list is shared rather than duplicated on purpose. `handleModels` in
+ * `models.ts` decides which names to hand to the runtime module, and
+ * `handleModelsRuntimeCommand` decides which names it answers. When those two
+ * lists were written out separately, `new-policy` and `new-arrivals` were
+ * implemented and documented but never routed, so both failed with
+ * "Unexpected argument(s)" (#3094).
+ *
+ * It lives in its own leaf module so `models.ts` can read the set without
+ * statically importing `models-runtime` — that import is deliberately dynamic
+ * to keep the management-API client off the `ocx models add` path.
+ */
+export const MODELS_RUNTIME_SUBCOMMANDS = [
+  "live",
+  "edit",
+  "enable",
+  "disable",
+  "provider",
+  "selected",
+  "preset",
+  "new-policy",
+  "new-arrivals",
+  "context",
+  "shadow",
+] as const;
+
+export type ModelsRuntimeSubcommand = (typeof MODELS_RUNTIME_SUBCOMMANDS)[number];
+
+export function isModelsRuntimeSubcommand(value: string | undefined): value is ModelsRuntimeSubcommand {
+  return MODELS_RUNTIME_SUBCOMMANDS.includes(value as ModelsRuntimeSubcommand);
+}

package/src/cli/models-runtime.ts

@@ -12,6 +12,7 @@ import {
   takeOption,
   type RuntimeApiDeps,
 } from "./runtime-api";
+import { isModelsRuntimeSubcommand } from "./models-runtime-subcommands";
 
 const USAGE = `Usage:
   ocx models live [--provider <name>] [--json]
@@ -321,6 +322,9 @@ async function shadow(argv: string[], deps: RuntimeApiDeps): Promise<void> {
 }
 
 export async function handleModelsRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
+  // The dispatch below and MODELS_RUNTIME_SUBCOMMANDS must name the same set;
+  // tests/cli-models-runtime-dispatch.test.ts fails if they drift (#3094).
+  if (!isModelsRuntimeSubcommand(sub)) return null;
   let action: (() => Promise<void>) | undefined;
   if (sub === "live") action = () => live(argv, deps);
   else if (sub === "edit") action = () => edit(argv, deps);

package/src/cli/models.ts

@@ -12,6 +12,7 @@ import {
   modelRecordValue,
 } from "../reasoning-effort";
 import { encodedModelIdCollides, resolveSlugSelection, routedSlug } from "../providers/slug-codec";
+import { isModelsRuntimeSubcommand } from "./models-runtime-subcommands";
 import { knownModelIdsForProvider } from "../router";
 import { findLiveProxy } from "../server/proxy-liveness";
 import { modelInList, type OcxConfig, type OcxCustomModel } from "../types";
@@ -445,7 +446,7 @@ export async function handleModels(args: string[]): Promise<void> {
     handleCustomList(rest);
     return;
   }
-  if (["live", "edit", "enable", "disable", "provider", "selected", "preset", "context", "shadow"].includes(subcommand ?? "")) {
+  if (isModelsRuntimeSubcommand(subcommand)) {
     const { handleModelsRuntimeCommand } = await import("./models-runtime");
     const code = await handleModelsRuntimeCommand(subcommand!, rest);
     if (code !== null) process.exitCode = code;

package/src/cli/opencode.ts

@@ -94,6 +94,7 @@ export interface OpencodeProxyModelRow {
   native?: boolean;
   disabled?: boolean;
   displayName?: string;
+  displayNameSource?: "operator" | "provider" | "fallback";
   contextWindow?: number;
   /** Declared effort ladder from `/api/models`; carried into opencode model variants. */
   reasoningEfforts?: string[];
@@ -387,7 +388,7 @@ export function opencodeCatalogFromProxyRows(
       provider: row.provider,
       id: row.id,
       contextWindow: row.contextWindow,
-      displayName: row.displayName,
+      displayName: row.displayNameSource === "fallback" ? undefined : row.displayName,
       ...(Array.isArray(row.reasoningEfforts) && row.reasoningEfforts.length > 0
         ? { reasoningEfforts: [...row.reasoningEfforts] }
         : {}),

package/src/cli/provider-runtime.ts

@@ -24,12 +24,14 @@ const USAGE = `Usage:
       [--auth-mode <key|forward|oauth|local|->] [--note <text|->]
       [--api-key-transport <x-api-key|bearer|->]
       [--headers <json>] [--enabled <on|off>] [--live-models <on|off>]
+      [--retain-models <id,id|->]
       [--allow-private-network <on|off>] [--json]
   ocx provider test <name> [--json]
   ocx provider quota [--refresh] [--json]
   ocx provider presets [--json]
   ocx provider account-mode <pool|direct> [--json]
-  ocx provider selected <name> [--set <model,model...>] [--clear] [--json]`;
+  ocx provider selected <name> [--set <model,model...>] [--clear] [--json]
+  ocx provider keychain <name> [status|store|restore] [--json]`;
 
 function cleared(value: string | undefined): string | undefined {
   return value === "-" ? "" : value;
@@ -48,6 +50,7 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const note = cleared(takeOption(args, "--note"));
   const apiKeyTransport = cleared(takeOption(args, "--api-key-transport"));
   const headers = takeOption(args, "--headers");
+  const retainModelsRaw = takeOption(args, "--retain-models");
   const enabled = takeBooleanOption(args, "--enabled");
   const liveModels = takeBooleanOption(args, "--live-models");
   const allowPrivateNetwork = takeBooleanOption(args, "--allow-private-network");
@@ -74,6 +77,10 @@ async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
     }
   }
   if (enabled !== undefined) patch.disabled = !enabled;
+  if (retainModelsRaw !== undefined) {
+    // `-` clears, matching the other `edit` scalars; test before csv() or it becomes ["-"].
+    patch.retainModels = retainModelsRaw.trim() === "-" ? null : csv(retainModelsRaw);
+  }
   if (liveModels !== undefined) patch.liveModels = liveModels;
   if (allowPrivateNetwork !== undefined) patch.allowPrivateNetwork = allowPrivateNetwork;
   if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);
@@ -175,6 +182,28 @@ async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   printData(result, wantsJson, [`${name}: ${models.length ? models.join(", ") : "all models"}`]);
 }
 
+async function keychain(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const name = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const action = (args.shift() ?? "status").toLowerCase();
+  if (!name) throw new CliUsageError("provider name is required", USAGE);
+  if (!["status", "store", "restore"].includes(action)) throw new CliUsageError(`unknown keychain action ${action}`, USAGE);
+  rejectArgs(args, USAGE);
+  if (action === "status") {
+    const result = await runtimeRequest<Record<string, unknown>>(`/api/providers/keychain?name=${encodeURIComponent(name)}`, {}, deps);
+    printData(result, wantsJson, summaryLines(result));
+    return;
+  }
+  const result = await runtimeRequest<Record<string, unknown>>("/api/providers/keychain", {
+    method: "POST",
+    body: JSON.stringify({ name, action }),
+  }, deps);
+  printData(result, wantsJson, [action === "store"
+    ? `${name}: API key moved to the OS keychain; config.json now holds a keychain: reference.`
+    : `${name}: API key restored to config.json; keychain entries removed.`]);
+}
+
 export async function handleProviderRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
   const handlers: Record<string, (args: string[], deps: RuntimeApiDeps) => Promise<void>> = {
     edit,
@@ -184,6 +213,7 @@ export async function handleProviderRuntimeCommand(sub: string, argv: string[],
     presets,
     "account-mode": accountMode,
     selected,
+    keychain,
   };
   const handler = handlers[sub];
   if (!handler) return null;

package/src/cli/registry.ts

@@ -86,6 +86,24 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     ],
   },
   { name: "ensure", usage: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
+  {
+    name: "connect",
+    usage: "ocx connect <url> [--management-url <url>] (--pairing-code-stdin | --admin-token-stdin) [--clients codex,claude] [--management-transport direct|relay] [--no-sync]",
+    summary: "Connect this machine to a remote OpenCodex hub without persisting the one-time authority.",
+    details: [
+      "Status: ocx connect status [--json]",
+      "Rotate or recover: ocx connect rotate (--pairing-code-stdin | --admin-token-stdin) [--json]",
+      "Revoke while connected: ocx connect revoke --admin-token-stdin [--json]",
+      "Machine resources: /api/machine/status, /api/machine/shim, /api/machine/clients, /api/machine/sync, /api/machine/disconnect, and the fixed /api/machine/hub-relay namespace.",
+      "Remote browser self-logout uses /api/session/logout from the GUI; it is distinct from client disconnect and key revocation.",
+      "Credentials are accepted only through stdin; argv and environment credential forms are not supported.",
+    ],
+  },
+  {
+    name: "disconnect",
+    usage: "ocx disconnect [--keep-catalog] [--json]",
+    summary: "Restore local client state offline and clear the remote-hub connection.",
+  },
   {
     name: "sync",
     usage: "ocx sync [--restart-codex] [--restart-desktop-app]",
@@ -128,7 +146,15 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
   },
   { name: "login", usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
   { name: "logout", usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
-  { name: "gui", usage: "ocx gui", summary: "Open the opencodex dashboard." },
+  {
+    name: "gui",
+    usage: "ocx gui [pair --origin <browser-origin> [--json]]",
+    summary: "Open the opencodex dashboard or create a secret single-use remote pairing grant.",
+    details: [
+      "Pairing requires an explicit allowed --origin; there is no localhost or config-derived default.",
+      "The printed grant is secret, single-use, short-lived, and must not be persisted.",
+    ],
+  },
   {
     name: "update",
     usage: "ocx update [--tag latest|preview]",
@@ -240,8 +266,12 @@ export const CLI_COMMANDS: CliCommandEntry[] = [
     name: "access",
     usage: "ocx access <key|endpoints|models|test> ...",
     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.",
+    ],
   },
-  { name: "api-key", usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
+  { name: "api-key", usage: "ocx api-key <list|create|rotate|remove> ...", summary: "Alias of ocx access key." },
   {
     name: "export",
     usage: "ocx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae|dsh|mcode|zcode|prime|aside> [--json] [--out <path>] [--force]",

package/src/cli/runtime-api.ts

@@ -182,7 +182,16 @@ export function csv(value: string | undefined): string[] | undefined {
  * `--code=https://…?code=SECRET` that writes the authorization code to stderr,
  * which is the exact exposure the stdin path exists to avoid.
  */
-const SECRET_OPTIONS = ["--code", "--headers"];
+const SECRET_OPTIONS = [
+  "--code",
+  "--headers",
+  "--token",
+  "--admin-token",
+  "--pairing-code",
+  "--credential-env",
+  "--admin-token-env",
+  "--pairing-code-env",
+];
 
 /**
  * Replace credential values before they are reported back.

package/src/cli/status.ts

@@ -18,6 +18,7 @@ import { collectOrcaCodexHomeDiagnostic, type OrcaCodexHomeDiagnostic } from "..
 import { grokFenceEndpointDrift, readGrokStatus } from "../grok/status";
 import { claudeDesktopIntegrationEnabled } from "../codex/desired-state";
 import { claudeDesktopPolicyHealth, probeClaudeDesktopPolicy, type ClaudeDesktopPolicyHealth } from "../claude/desktop-policy";
+import { collectClientConnectionStatus } from "./connect";
 
 type HealthCheck = {
   ok: boolean;
@@ -63,6 +64,18 @@ export type CliStatusJson = {
     source: "default" | "file" | "fallback";
     error: string | null;
   };
+  connection: {
+    state: "disconnected" | "connected" | "invalid" | "mismatched";
+    reason?: string;
+    serverUrl?: string;
+    managementUrl?: string;
+    protocolVersion?: number;
+    apiKeyId?: string;
+    selectedClients?: string[];
+    catalog?: "present" | "missing" | "unsafe";
+    catalogAgeSeconds?: number;
+    credentialFile: "owned" | "missing" | "changed" | "unsafe";
+  };
   service: { summary: string };
   codexShim: { summary: string };
   codexPlugins: CodexPluginsDiagnostic;
@@ -309,6 +322,7 @@ export async function collectStatus(): Promise<CliStatusView> {
     desiredEnabled: claudeDesktopIntegrationEnabled(config),
     policy: claudeDesktopPolicyHealth(probeClaudeDesktopPolicy()),
   };
+  const clientConnection = collectClientConnectionStatus();
   // Prefer identity-verified liveness (runtime-port + /healthz) over ocx.pid alone (#618).
   // Pass the already-resolved diagnostics config so findLiveProxy does not re-load and
   // warn on malformed config.json (status --json must stay stderr-clean).
@@ -491,6 +505,18 @@ export async function collectStatus(): Promise<CliStatusView> {
         source: configDiagnostics.source,
         error: configDiagnostics.error,
       },
+      connection: {
+        state: clientConnection.state,
+        ...(clientConnection.reason ? { reason: clientConnection.reason } : {}),
+        ...(clientConnection.serverUrl ? { serverUrl: clientConnection.serverUrl } : {}),
+        ...(clientConnection.managementUrl ? { managementUrl: clientConnection.managementUrl } : {}),
+        ...(clientConnection.protocolVersion ? { protocolVersion: clientConnection.protocolVersion } : {}),
+        ...(clientConnection.apiKeyId ? { apiKeyId: clientConnection.apiKeyId } : {}),
+        ...(clientConnection.selectedClients ? { selectedClients: [...clientConnection.selectedClients] } : {}),
+        catalog: clientConnection.catalog,
+        ...(clientConnection.catalogAgeSeconds !== undefined ? { catalogAgeSeconds: clientConnection.catalogAgeSeconds } : {}),
+        credentialFile: clientConnection.token,
+      },
       service: { summary: serviceSummary },
       codexShim: { summary: codexShimSummary },
       codexPlugins,

package/src/cli/system-command.ts

@@ -13,7 +13,8 @@ import {
 
 const USAGE = `Usage:
   ocx system [status] [--json]
-  ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>] [--json]
+  ocx system settings [--auto-start <on|off>] [--stream-mode <auto|legacy-tee|eager-relay>]
+      [--desktop-authless <on|off>] [--json]
   ocx system startup <health|install-service|install-shim> [--json]
   ocx system diagnostics [--json]
   ocx system sync [--json]
@@ -42,13 +43,18 @@ async function settings(argv: string[], deps: RuntimeApiDeps): Promise<void> {
   const wantsJson = takeFlag(args, "--json");
   const autoStart = takeBooleanOption(args, "--auto-start");
   const streamMode = takeOption(args, "--stream-mode");
+  const desktopAuthless = takeBooleanOption(args, "--desktop-authless");
   rejectArgs(args, USAGE);
-  if (autoStart === undefined && streamMode === undefined) {
+  if (autoStart === undefined && streamMode === undefined && desktopAuthless === undefined) {
     const result = await runtimeRequest("/api/settings", {}, deps);
     printData(result, wantsJson, summaryLines(result));
     return;
   }
-  const body = { ...(autoStart !== undefined ? { codexAutoStart: autoStart } : {}), ...(streamMode !== undefined ? { streamMode } : {}) };
+  const body = {
+    ...(autoStart !== undefined ? { codexAutoStart: autoStart } : {}),
+    ...(streamMode !== undefined ? { streamMode } : {}),
+    ...(desktopAuthless !== undefined ? { codexDesktopAuthless: desktopAuthless } : {}),
+  };
   const result = await runtimeRequest("/api/settings", { method: "PUT", body: JSON.stringify(body) }, deps);
   printData(result, wantsJson, ["System settings updated."]);
 }