@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/cli/ensure-desktop-cold-start.ts

@@ -0,0 +1,329 @@
+/**
+ * Cold start for `ocx ensure` when OpenCodex Desktop owns or runs the proxy (#6971).
+ *
+ * The Codex launcher shim runs `ocx ensure` before every Codex launch. Without this policy,
+ * ensure spawned a detached CLI proxy whenever nothing answered on the port. That is wrong in two
+ * Desktop situations: during the Desktop supervisor's restart backoff, and after Desktop quit
+ * while its durable ownership claim remains. In both, the CLI proxy took the port and Desktop came
+ * back as a guest without supervision. That is why the dashboard used to disable the shim under
+ * Desktop.
+ *
+ * Rules, in order:
+ * - A running Desktop app is the supervisor. Wait for its proxy; never start a competing one.
+ * - A durable Desktop claim with no running app: start Desktop (hidden, as a login launch would)
+ *   where that is possible, then wait. Elsewhere, fail with guidance. A missing Desktop process
+ *   never authorizes a CLI proxy by itself; handing ownership to the CLI stays an explicit
+ *   `ocx service install` consent step.
+ * - Ownership or the process list that cannot be read is not evidence of absence: refuse.
+ * - No claim and no running app: the ordinary CLI cold start.
+ *
+ * Concurrent shim launches share one Desktop launch through a lease file held by a live process;
+ * every caller then waits on the same readiness probe.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, linkSync, readdirSync, readFileSync, readlinkSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, win32 } from "node:path";
+import { getConfigDir } from "../config/paths";
+import { resolveServiceOwnership } from "../service/state";
+
+export type DesktopProcessState = "running" | "absent" | "unknown";
+export type DesktopOwnershipState = "desktop" | "other" | "unknown";
+
+export type EnsureColdStartPlan =
+  | { kind: "spawn-cli" }
+  | { kind: "wait-desktop" }
+  | { kind: "launch-desktop" }
+  | { kind: "refuse"; reason: "desktop-unlaunchable" | "unverified" };
+
+export function planEnsureColdStart(facts: {
+  ownership: DesktopOwnershipState;
+  desktopProcess: DesktopProcessState;
+  platform: NodeJS.Platform;
+}): EnsureColdStartPlan {
+  if (facts.desktopProcess === "running") return { kind: "wait-desktop" };
+  if (facts.ownership === "unknown" || facts.desktopProcess === "unknown") return { kind: "refuse", reason: "unverified" };
+  if (facts.ownership === "other") return { kind: "spawn-cli" };
+  return facts.platform === "darwin" ? { kind: "launch-desktop" } : { kind: "refuse", reason: "desktop-unlaunchable" };
+}
+
+/** Desktop restart backoff tops out at 30 s; the budget covers it plus a cold sidecar start. */
+export const DESKTOP_COLD_START_TIMEOUT_MS = 40_000;
+
+export type DesktopColdStartResult<T> =
+  | { kind: "cli" }
+  | { kind: "live"; live: T }
+  | { kind: "failed"; message: string };
+
+export interface DesktopColdStartDeps<T> {
+  platform: NodeJS.Platform;
+  ownership: () => DesktopOwnershipState;
+  desktopProcess: () => DesktopProcessState;
+  /** Start the Desktop app hidden. Returns false when the request could not be made. */
+  launchDesktop: () => boolean;
+  /** Returns a release function when this caller should launch, or null when another caller already did. */
+  acquireLaunchLease: () => (() => void) | null;
+  waitForProxy: (timeoutMs: number) => Promise<T | null>;
+  info?: (line: string) => void;
+}
+
+const QUIT_HINT = "To run the proxy from this CLI instead, quit OpenCodex and run `ocx service install` or `ocx start`.";
+
+export async function runDesktopColdStart<T>(deps: DesktopColdStartDeps<T>): Promise<DesktopColdStartResult<T>> {
+  const plan = planEnsureColdStart({
+    ownership: deps.ownership(),
+    desktopProcess: deps.desktopProcess(),
+    platform: deps.platform,
+  });
+  if (plan.kind === "spawn-cli") return { kind: "cli" };
+  if (plan.kind === "refuse") {
+    return { kind: "failed", message: plan.reason === "unverified"
+      ? "Could not verify whether OpenCodex Desktop manages this proxy, so no CLI proxy was started. Run `ocx doctor`, or start the proxy explicitly with `ocx start`."
+      : `OpenCodex Desktop manages this proxy but is not running. Open OpenCodex to start it. ${QUIT_HINT}` };
+  }
+  if (plan.kind === "launch-desktop") {
+    const release = deps.acquireLaunchLease();
+    try {
+      if (release) {
+        deps.info?.("Starting OpenCodex Desktop, which manages this proxy...");
+        if (!deps.launchDesktop()) {
+          return { kind: "failed", message: `OpenCodex Desktop manages this proxy, but it could not be started. Open OpenCodex manually. ${QUIT_HINT}` };
+        }
+      }
+      const live = await deps.waitForProxy(DESKTOP_COLD_START_TIMEOUT_MS);
+      if (live) return { kind: "live", live };
+      return { kind: "failed", message: `OpenCodex Desktop was started, but its proxy did not answer in time. Check the OpenCodex menu. ${QUIT_HINT}` };
+    } finally { release?.(); }
+  }
+  deps.info?.("Waiting for OpenCodex Desktop to restart its proxy...");
+  const live = await deps.waitForProxy(DESKTOP_COLD_START_TIMEOUT_MS);
+  if (live) return { kind: "live", live };
+  return {
+    kind: "failed",
+    message: `OpenCodex Desktop is running but its proxy is not answering. Use Start Proxy in the OpenCodex menu. ${QUIT_HINT}`,
+  };
+}
+
+type Execute = (command: string, args: string[], timeoutMs: number) => string;
+
+function execute(command: string, args: string[], timeoutMs: number): string {
+  return execFileSync(command, args, {
+    encoding: "utf8", timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024, stdio: ["ignore", "pipe", "ignore"], windowsHide: true,
+  });
+}
+
+/** A Desktop app executable: `opencodex-desktop`, inside an app bundle's Contents/MacOS on macOS. */
+export function isDesktopExecutable(path: string, platform: NodeJS.Platform): boolean {
+  if (basename(path) !== "opencodex-desktop") return false;
+  return platform !== "darwin" || (basename(dirname(path)) === "MacOS" && basename(dirname(dirname(path))) === "Contents");
+}
+
+export interface DesktopProcessOptions {
+  platform?: NodeJS.Platform;
+  uid?: number;
+  env?: NodeJS.ProcessEnv;
+  run?: Execute;
+  /** Linux: executable paths of this user's processes, or \`unverified\`. */
+  linuxExecutables?: (uid: number) => string[] | "unverified";
+  /** Linux: whether procfs hides processes (hidepid=2/4). */
+  procfsHidesProcesses?: () => boolean;
+  /** Linux: whether this machine shows evidence of an OpenCodex Desktop install. */
+  desktopInstalled?: () => boolean;
+}
+
+/**
+ * Linux: hidepid=2 (invisible) or 4 (ptraceable) can hide a same-uid process whose credentials
+ * differ from the caller's (for example after newgrp), so an empty scan proves nothing there.
+ * An unreadable mount table is treated as filtering.
+ */
+export function procfsHidesProcesses(mountinfo = "/proc/self/mountinfo"): boolean {
+  let text: string;
+  try { text = readFileSync(mountinfo, "utf8"); } catch { return true; }
+  return text.split("\n").some(line => {
+    const [mount, fs] = line.split(" - ");
+    if (mount?.split(" ")[4] !== "/proc" || !fs) return false;
+    const [type, , options = ""] = fs.split(" ");
+    return type === "proc" && options.split(",").some(option => /^hidepid=(2|4|invisible|ptraceable)$/.test(option));
+  });
+}
+
+function linuxDesktopInstalled(): boolean {
+  return existsSync(join(homedir(), ".opencodex-desktop")) || existsSync("/usr/bin/opencodex-desktop");
+}
+
+/** Linux truncates comm to 15 bytes. */
+const LINUX_DESKTOP_COMM = "opencodex-desktop".slice(0, 15);
+
+/**
+ * Linux: executables of this user's processes. A process that exited mid-scan or belongs to someone
+ * else is skipped. A non-dumpable process (ssh-agent, gpg-agent) hides its executable but not its
+ * comm, so it is ruled out by name; one whose comm could be Desktop makes the answer unverifiable.
+ * The scan must also see this process, or procfs is filtered and absence proves nothing.
+ */
+export function scanLinuxExecutables(uid: number, selfPid: number = process.pid, proc = "/proc"): string[] | "unverified" {
+  const paths: string[] = [];
+  let sawSelf = false;
+  const code = (error: unknown) => (error as { code?: unknown } | null)?.code;
+  for (const entry of readdirSync(proc)) {
+    if (!/^\d+$/.test(entry)) continue;
+    if (Number(entry) === selfPid) sawSelf = true;
+    try {
+      if (statSync(`${proc}/${entry}`).uid !== uid) continue;
+      paths.push(readlinkSync(`${proc}/${entry}/exe`).replace(/ \(deleted\)$/, ""));
+    } catch (error) {
+      if (code(error) === "ENOENT" || code(error) === "ESRCH") continue;
+      try {
+        if (readFileSync(`${proc}/${entry}/comm`, "utf8").trim() !== LINUX_DESKTOP_COMM) continue;
+      } catch (commError) {
+        if (code(commError) === "ENOENT" || code(commError) === "ESRCH") continue;
+      }
+      return "unverified";
+    }
+  }
+  return sawSelf ? paths : "unverified";
+}
+
+/** Whether this user runs an OpenCodex Desktop app, judged by executable identity, never arguments. */
+export function inspectDesktopProcess(options: DesktopProcessOptions = {}): DesktopProcessState {
+  const platform = options.platform ?? process.platform;
+  const run = options.run ?? execute;
+  try {
+    const uid = options.uid ?? process.getuid?.();
+    if (platform === "linux") {
+      if (uid === undefined) return "unknown";
+      const executables = (options.linuxExecutables ?? scanLinuxExecutables)(uid);
+      if (executables === "unverified") return "unknown";
+      if (executables.some(path => isDesktopExecutable(path, platform))) return "running";
+      // A filtered procfs cannot prove absence where Desktop may be installed. Without an install
+      // there is nothing to hide, so hardened hosts keep the plain CLI cold start.
+      return (options.procfsHidesProcesses ?? procfsHidesProcesses)() && (options.desktopInstalled ?? linuxDesktopInstalled)()
+        ? "unknown" : "absent";
+    }
+    if (platform === "darwin") {
+      if (uid === undefined) return "unknown";
+      // macOS reports the full executable path as comm.
+      const output = run("/bin/ps", ["-U", String(uid), "-o", "comm="], 3_000);
+      return output.split("\n").some(line => isDesktopExecutable(line.trim(), platform)) ? "running" : "absent";
+    }
+    if (platform === "win32") {
+      const env = options.env ?? process.env;
+      const root = env.SystemRoot ?? env.windir ?? "C:\\Windows";
+      const user = env.USERNAME?.trim();
+      const args = ["/FI", "IMAGENAME eq opencodex-desktop.exe", ...(user ? ["/FI", `USERNAME eq ${user}`] : []), "/FO", "CSV", "/NH"];
+      const output = run(win32.join(root, "System32", "tasklist.exe"), args, 3_000);
+      return /^"opencodex-desktop\.exe",/im.test(output) ? "running" : "absent";
+    }
+    return "absent";
+  } catch {
+    return "unknown";
+  }
+}
+
+/** Start the macOS app hidden, the same way its login item does. */
+export function launchDesktopApp(options: { platform?: NodeJS.Platform; run?: Execute } = {}): boolean {
+  if ((options.platform ?? process.platform) !== "darwin") return false;
+  try {
+    (options.run ?? execute)("/usr/bin/open", ["-g", "-b", "com.opencodex.desktop", "--args", "--autostart"], 10_000);
+    return true;
+  } catch { return false; }
+}
+
+function processAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return (error as NodeJS.ErrnoException | null)?.code === "EPERM"; }
+}
+
+function readHolder(path: string): number | null {
+  const pid = Number(readFileSync(path, "utf8").trim());
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+const LEASE_FILE = /^desktop-launch\.(\d+)\.lease$/;
+
+/**
+ * One Desktop launch per cold start. Leases are numbered generations, each published whole with
+ * link(2), which fails if the name exists, so exactly one contender can create generation N+1. A
+ * caller launches only after creating the next generation while the newest one belongs to a dead
+ * process (or none exists). A lease stays valid while its holder lives, so a slow launch never
+ * expires under its owner. Nothing ever moves or overwrites another holder's lease.
+ */
+export function acquireDesktopLaunchLease(
+  configDir: string,
+  io: { pid?: number; alive?: (pid: number) => boolean } = {},
+): (() => void) | null {
+  const pid = io.pid ?? process.pid;
+  const alive = io.alive ?? processAlive;
+  const leasePath = (generation: number) => join(configDir, `desktop-launch.${generation}.lease`);
+  for (let attempt = 0; attempt < 4; attempt++) {
+    let generations: number[];
+    try {
+      generations = readdirSync(configDir).flatMap(name => {
+        const match = LEASE_FILE.exec(name);
+        return match ? [Number(match[1])] : [];
+      }).sort((a, b) => b - a);
+    } catch {
+      // An unreadable lease directory must not suppress the launch; it only loses deduplication.
+      return () => {};
+    }
+    const newest = generations[0];
+    if (newest !== undefined) {
+      try {
+        const holder = readHolder(leasePath(newest));
+        if (holder !== null && alive(holder)) return null;
+      } catch (error) {
+        if ((error as { code?: unknown })?.code === "ENOENT") continue;
+        return null;
+      }
+    }
+    const next = (newest ?? 0) + 1;
+    const staged = join(configDir, `desktop-launch.${randomUUID()}.tmp`);
+    try {
+      writeFileSync(staged, String(pid), { flag: "wx", mode: 0o600 });
+      linkSync(staged, leasePath(next));
+    } catch (error) {
+      if ((error as { code?: unknown })?.code === "EEXIST") continue;
+      return () => {};
+    } finally {
+      try { unlinkSync(staged); } catch { /* not created */ }
+    }
+    const withdraw = () => {
+      try { if (readHolder(leasePath(next)) === pid) unlinkSync(leasePath(next)); } catch { /* already gone */ }
+    };
+    // A contender with a stale directory read can publish a generation a winner already cleaned
+    // up. The highest generation is the one launcher; anyone below it stands down.
+    try {
+      if (readdirSync(configDir).some(name => Number(LEASE_FILE.exec(name)?.[1] ?? 0) > next)) {
+        withdraw();
+        return null;
+      }
+    } catch { /* keep the lease: the directory was readable a moment ago */ }
+    // Older generations belong to dead holders: the newest was checked before publishing above it.
+    for (const generation of generations) {
+      try { unlinkSync(leasePath(generation)); } catch { /* already gone */ }
+    }
+    // The newest generation is never deleted on release: removing it would let numbering restart
+    // below a stale contender. It stops counting once this process exits.
+    return () => {};
+  }
+  return null;
+}
+
+/** Production wiring; `waitForProxy` is ensure's identity-checked readiness probe. */
+export function productionDesktopColdStartDeps<T>(waitForProxy: (timeoutMs: number) => Promise<T | null>): DesktopColdStartDeps<T> {
+  return {
+    platform: process.platform,
+    ownership: () => {
+      try {
+        const owner = resolveServiceOwnership();
+        if (owner.kind === "unknown") return "unknown";
+        return owner.kind === "owned" && owner.ownership.owner === "desktop" ? "desktop" : "other";
+      } catch { return "unknown"; }
+    },
+    desktopProcess: () => inspectDesktopProcess(),
+    launchDesktop: () => launchDesktopApp(),
+    acquireLaunchLease: () => acquireDesktopLaunchLease(getConfigDir()),
+    waitForProxy,
+    info: line => console.log(line),
+  };
+}

package/src/cli/export-command.ts

@@ -29,6 +29,7 @@
 import { writeFileSync } from "node:fs";
 import { loadConfig } from "../config";
 import {
+  ClientPathError,
   EXPORT_CLIENTS,
   EXPORT_CLIENT_IDS,
   buildClientConfigText,
@@ -168,7 +169,7 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     const spec = EXPORT_CLIENTS[client];
     const root = await runtimeBaseUrl(deps);
     let built: { document: unknown; text: string };
-    if (client === "raycast" || client === "droid") {
+    if (client === "raycast" || client === "droid" || client === "qoder") {
       // The dial address alone cannot distinguish a wildcard authenticated bind
       // from loopback. Let the live server resolve its admission/listener policy;
       // saved config can differ from the process serving this request.
@@ -193,6 +194,18 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
     const clientConfig = built.document;
     const text = built.text;
 
+    // Resolve the human-facing destination BEFORE writing anything. A client whose
+    // config location cannot be determined (a relative override, or ZCode bootstrap
+    // settings naming an unknown data root) still exports the document: the export
+    // writes nothing into the client and the destination is advisory text.
+    let destination: string;
+    try {
+      destination = spec.destination(process.env);
+    } catch (error) {
+      if (!(error instanceof ClientPathError)) throw error;
+      destination = `unknown (${error.message})`;
+    }
+
     // Every serializer already ends with exactly one newline.
     if (out !== undefined) writeExport(out, text, force);
     // stderr, so `--json` stdout stays a standalone JSON document.
@@ -208,7 +221,7 @@ export async function handleExportCommand(argv: string[], deps: ExportCommandDep
       ...text.trimEnd().split("\n"),
       "",
       ...(out !== undefined ? [`Wrote ${out}`] : []),
-      `Destination: ${spec.destination(process.env)}`,
+      `Destination: ${destination}`,
       "Merge this generated configuration into that file; do not replace it.",
       `Before launching: ${spec.exportHint}`,
       `${modelCount} model${modelCount === 1 ? "" : "s"}; ${modelsWithoutLimits} omit context limits (the client applies its own defaults).`,

package/src/cli/help.ts

@@ -92,11 +92,12 @@ Usage:
   ocx api-key <sub>           Alias of ocx access key
   ocx access <sub>            External API keys and endpoint information
   ocx api <sub>               Protocol paths: vocabulary, request-path preview, and policy
-  ocx export --client <id>    Print a client config wired to the running proxy (18 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (19 clients)
   ocx integration client <sub> Enable, disable, inspect or roll back a client integration
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, OpenCodex updates, and Codex CLI inspection
   ocx config [sub]            Validated configuration show/get/set/import/export
+  ocx advisor <status|on|off|set|consent>  Advisor sidecar settings and context-sharing consent
   ocx companion <show|set|reset>  Menu-bar and widget companion usage settings
   ocx lab <sub>               Inspect Lab evidence and control local automation
   ocx chatgpt <sub>          Experimental app-server shim: launch|restore|status (macOS)

package/src/cli/hub-disable.ts

@@ -0,0 +1,99 @@
+import { mutatePersistedConfig, validateConfigCandidate } from "../config";
+import { deleteConfigTopLevelKey } from "../config/rebase-provenance";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { probeServiceInstallation } from "../service/cli";
+import { redactSecretString } from "../lib/redact";
+import { CliUsageError, printData, runCliAction } from "./runtime-api";
+import type { OcxConfig } from "../types";
+
+export const HUB_DISABLE_USAGE = "ocx hub disable [--revoke-clients --client-key <id> ...] [--json]";
+const HUB_KEYS = ["hub", "unauthenticatedLoopbackListener", "runtimeRole", "hostname"] as const;
+const PUBLISHING_NOTE = "External publishing is unchanged. Check tailscale serve status and any other frontend for mappings to the old hub ports.";
+
+export interface HubDisableOptions { json: boolean; revokeClients: boolean; clientKeys: string[] }
+export interface HubDisableDeps {
+  mutateConfig?: typeof mutatePersistedConfig;
+  restartHint?: () => string;
+}
+interface HubDisableResult {
+  removed: string[];
+  keys: { id: string; name: string; createdAt: string; revoked: boolean }[];
+  revoked: string[];
+}
+
+export function parseHubDisableArgs(args: string[]): HubDisableOptions {
+  const options: HubDisableOptions = { json: false, revokeClients: false, clientKeys: [] };
+  for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === "--json" && !options.json) options.json = true;
+    else if (arg === "--revoke-clients" && !options.revokeClients) options.revokeClients = true;
+    else if (arg === "--client-key") {
+      const id = args[++index];
+      if (!id || id.startsWith("-") || options.clientKeys.includes(id)) throw new CliUsageError("Each --client-key requires a unique exact key ID.", HUB_DISABLE_USAGE);
+      options.clientKeys.push(id);
+    } else throw new CliUsageError("Unknown or repeated hub disable argument.", HUB_DISABLE_USAGE);
+  }
+  if (options.clientKeys.length && !options.revokeClients) throw new CliUsageError("--client-key requires --revoke-clients.", HUB_DISABLE_USAGE);
+  return options;
+}
+
+/** Selection is explicit: legacy keys have editable names but no trustworthy issuance marker. */
+export function disableHubConfig(config: OcxConfig, options: HubDisableOptions): HubDisableResult {
+  if (config.runtimeRole !== "hub") throw new CliUsageError("This machine is not a hub; no settings or keys were changed.");
+  const keys = config.apiKeys ?? [];
+  const secrets = keys.flatMap(key => [key.key, key.pendingRotation?.key]).filter((secret): secret is string => Boolean(secret));
+  const safeMetadata = (value: string) => redactSecretString(secrets.reduce((text, secret) => text.split(secret).join("[REDACTED]"), value));
+  if (options.revokeClients && keys.length && !options.clientKeys.length) {
+    throw new CliUsageError("Keys have no verified client origin. List IDs with 'ocx access key list --json', then repeat --client-key <id> for each client key to revoke.", HUB_DISABLE_USAGE);
+  }
+  const selected = new Set(options.clientKeys);
+  if (options.clientKeys.some(id => !keys.some(key => key.id === id))) {
+    throw new CliUsageError("A selected client key ID is not in the current config; no settings or keys were changed.");
+  }
+  const candidate = structuredClone(config);
+  const removed = HUB_KEYS.filter(key => Object.hasOwn(candidate, key));
+  for (const key of HUB_KEYS) delete candidate[key];
+  if (options.revokeClients) candidate.apiKeys = keys.filter(key => !selected.has(key.id));
+  const validated = validateConfigCandidate(candidate);
+  if (!validated.ok) throw new CliUsageError(validated.error);
+  // Keep deletion intent so a later live save cannot resurrect the hub's old bindings.
+  for (const key of HUB_KEYS) deleteConfigTopLevelKey(config, key);
+  Object.assign(config, validated.config);
+  return {
+    removed,
+    keys: keys.map(key => ({ id: safeMetadata(key.id), name: safeMetadata(key.name), createdAt: safeMetadata(key.createdAt), revoked: selected.has(key.id) })),
+    revoked: options.revokeClients ? [...selected].map(safeMetadata) : [],
+  };
+}
+
+export function hubDisableRestartHint(): string {
+  try {
+    if (inspectDesktopSupervision().kind === "desktop") return "Restart to apply: ocx restart (OpenCodex Desktop supervises the replacement).";
+    const service = probeServiceInstallation();
+    if (service.state === "installed") return "Restart to apply: ocx service restart.";
+  } catch { /* An unavailable probe must not prevent an already validated config change. */ }
+  return "Restart to apply: use your current proxy supervisor; for a manually started proxy, ocx restart.";
+}
+
+export async function runHubDisable(args: string[], deps: HubDisableDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const options = parseHubDisableArgs(args);
+    const outcome = (deps.mutateConfig ?? mutatePersistedConfig)(config => ({
+      changed: true, value: disableHubConfig(config, options),
+    }));
+    if (outcome.status === "unavailable") throw new Error(`Hub disable could not read or commit the config (${outcome.reason}); retry after fixing the config.`);
+    let restart: string;
+    try { restart = (deps.restartHint ?? hubDisableRestartHint)(); }
+    catch { restart = "Restart to apply: use your current proxy supervisor."; }
+    const result = { ok: true, ...outcome.value, restart, note: PUBLISHING_NOTE, keyOrigin: "unverified", effectiveAfterRestart: true };
+    // Explicit field projection excludes secrets and pending rotations; names are arbitrary input.
+    const safe = { ...result, keys: result.keys.map(key => ({ ...key, name: redactSecretString(key.name) })) };
+    printData(safe, options.json, [
+      `Removed hub settings: ${safe.removed.join(", ")}.`,
+      ...safe.keys.map(key => `${key.revoked ? "Revoked" : "Retained"} saved key: ${key.id} (${key.name})`),
+      "Saved keys have no verified client origin; revocation uses only explicitly selected IDs.",
+      restart, PUBLISHING_NOTE,
+      "Restart is required to apply all saved settings; this command does not terminate existing sessions.",
+    ]);
+  });
+}

package/src/cli/hub.ts

@@ -7,9 +7,10 @@ import {
   type GuiPairRequestResult,
 } from "./gui-pair-client";
 import type { RuntimeApiDeps } from "./runtime-api";
+import { HUB_DISABLE_USAGE, runHubDisable, type HubDisableDeps } from "./hub-disable";
 
 export const HUB_USAGE =
-  "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]";
+  "ocx hub invite [--json] [--data-url <origin>] [--management-url <origin>] [--clients codex,claude]\n  " + HUB_DISABLE_USAGE;
 
 const PAIRING_WARNING = "Pairing codes are secret, single-use, and expire quickly. Do not save them.";
 
@@ -23,7 +24,7 @@ const PAIRING_WARNING = "Pairing codes are secret, single-use, and expire quickl
  */
 const DEFAULT_CLIENT_BROWSER_ORIGIN = "http://localhost:10100";
 
-export interface HubCommandDeps extends RuntimeApiDeps {
+export interface HubCommandDeps extends RuntimeApiDeps, HubDisableDeps {
   loadConfig: () => OcxConfig;
   findLiveProxy?: () => Promise<LiveProxy | null>;
   requestPairingGrant?: (
@@ -361,6 +362,7 @@ async function runInvite(args: string[], deps: HubCommandDeps): Promise<number>
 }
 
 export async function runHubCommand(args: string[], deps: HubCommandDeps): Promise<number> {
+  if (args[0] === "disable") return runHubDisable(args.slice(1), deps);
   if (args[0] !== "invite") {
     console.error(`Usage: ${HUB_USAGE}`);
     return 1;

package/src/cli/index.ts

@@ -11,11 +11,11 @@ import { packageVersion } from "../lib/package-version";
 import { codexHomeIsAbsent } from "../codex/codex-home-owner";
 import { getCodexHome } from "../codex/paths";
 import { admitUpdateRestartChild } from "./update-restart-child";
+import { HEALTH_SENTINEL_STANDALONE_ARG, startServiceHealthSentinel } from "../service/health-sentinel-launch";
 import { UpdateRestartRequired } from "./update-restart-candidate";
 import { describeUpdateRestartFailure, restartFromCurrentInstallation } from "./update-restart";
 import { findGuiDist } from "../server/gui-static";
 import { inspectGuiBundleFreshness, staleGuiBundleLines } from "../server/gui-freshness";
-
 // Best-effort recovery for runtime execution and spawned children if launched
 // from an unlinked/deleted working directory (runs after hoisted ESM module imports).
 try {
@@ -155,9 +155,9 @@ import {
   reconcileEnsureDesiredIntegrations,
 } from "./ensure-desired-integrations";
 import { ENSURE_READY_TIMEOUT_MS, ensureKeepWaiting, waitForLiveProxy } from "./ensure-readiness";
+import { productionDesktopColdStartDeps, runDesktopColdStart } from "./ensure-desktop-cold-start";
 import { refreshOwnedCatalogIntegrations } from "../integrations/catalog-refresh";
 import { loadExportModels } from "../server/management/model-rows";
-
 import { removeOwnedConfigAfterDesktopCleanup } from "./uninstall-client-state";
 import { withProcessRuntimeProvenance } from "../lib/bun-runtime";
 import { startArgv } from "../lib/self-launch-argv";
@@ -168,6 +168,7 @@ import { recoverStartStateUnderOwnershipLease } from "./start-owner-fence";
 import { handledSignalExitCode } from "../lib/handled-signal-exit";
 import { createLocalAttestationSecret } from "../lib/local-management-attestation";
 import { MEMORY_DRAIN_RESTART_MS, REPLACEMENT_READY_TIMEOUT_MS } from "../lib/system-restart-contract";
+import { startServiceLogging } from "../service/logging";
 
 /**
  * A failed shell-hook reconcile is not cosmetic: a stale hook keeps sourcing
@@ -207,11 +208,13 @@ async function refreshOwnedRaycastCatalog(
   }
 }
 
+if (process.argv[2] === "start" && process.env.OCX_SERVICE) startServiceLogging(join(getConfigDir(), "service.log"));
 const updateRestartChild = admitUpdateRestartChild(process.argv.slice(2));
 initializeNodeLauncherContext();
 // The compiled executable is also the capture-only MCP server's launcher.
 // Handle this private entrypoint before CLI preflight or command dispatch.
 if (process.argv[2] === "__keyring-load-check") { console.log(JSON.stringify((await import("../lib/keyring-native")).inspectKeyringBinding())); process.exit(0); }
+if (process.argv[2] === HEALTH_SENTINEL_STANDALONE_ARG) process.exit(await (await import("../service/health-sentinel-main")).runHealthSentinelProcess());
 
 // The compiled executable also launches the isolated MCP servers.
 // Handle these private entrypoints before CLI preflight or command dispatch.
@@ -280,6 +283,7 @@ async function chooseListenPort(
       `Port ${preferred} is reserved for unauthenticatedLoopbackListener; choose a different proxy port.`,
     );
   }
+  await (await import("./auxiliary-listener-preflight")).assertAuxiliaryListenerPortsAvailable(config);
   // Soft start: brief prefer-retry then ephemeral hop.
   // Explicit `--port` (service wrappers / update restart): wait for the pinned port
   // to free without killing any listener (healthy ocx / foreign). Never hop.
@@ -623,6 +627,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   // Records are visible now; background work may observe this runtime without a gap.
   scheduleCatalogPrewarm();
   installCrashGuards();
+  let healthSentinel: ReturnType<typeof startServiceHealthSentinel> = null; // opt-in #6671, started once ready
   // No pre-emptive snapshot here. `injectCodexConfig` journals the exact bytes it
   // is about to transform; snapshotting earlier only captured a baseline that could
   // already be stale by the time injection ran (#477).
@@ -646,6 +651,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     try { routingHealer?.stop(); } catch { /* best-effort */ }
     try { guardian.stop(); } catch { /* best-effort */ }
     try { historyGuardian?.stop(); } catch { /* best-effort */ }
+    try { healthSentinel?.stop(); } catch { /* best-effort */ }
     // Dashboard drain-and-restart (#563) must not tear down injection: the replacement
     // process expects Codex/Grok/env fences to still be in place. A sibling owns none of them.
     const teardown = decideStartExitTeardown({ sibling: siblingStart, recycling: isRecyclingForExit(), ocxService: process.env.OCX_SERVICE });
@@ -746,6 +752,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   );
   if (!startupSync.ran) console.log(startupLeftCodexNativeLine(localClientSkipReason(config), server.port ?? port));
   await refreshOwnedRaycastCatalog(config, port);
+  if (!cleaned && !shuttingDown) healthSentinel = startServiceHealthSentinel(config); // after startup reconciliation; never mid-boot or mid-drain
   // #1046: one warning per startup, after BOTH writes. The server's cache
   // invalidation happens first and the catalog sync second, so the mtime is only
   // final here — and neither write site warns on its own, or a boot that hits
@@ -811,9 +818,16 @@ async function handleEnsure(options: { existingIsSuccess?: boolean; forceStart?:
     console.log("Codex autostart is disabled.");
     return false;
   }
-  const live = owner.live;
+  let live = owner.live;
+  if (!live) {
+    // OpenCodex Desktop owns or runs this proxy: wait for it or start it, never a competing CLI proxy (#6971).
+    const desktopStart = await runDesktopColdStart(productionDesktopColdStartDeps(timeoutMs => waitForProxy(timeoutMs)));
+    if (desktopStart.kind === "failed") { console.error(`❌ ${desktopStart.message}`); process.exitCode = 1; return false; }
+    // Also for restart: the proxy was absent and Desktop started it, so the live tail below applies.
+    if (desktopStart.kind === "live") live = desktopStart.live;
+  }
   if (live) {
-    if (options.existingIsSuccess === false) {
+    if (options.existingIsSuccess === false && live === owner.live) {
       console.error("Proxy appeared while restart was confirming absence; no start was attempted.");
       return false;
     }
@@ -1717,7 +1731,7 @@ async function handleStatus() {
   // are tagged `(local)`. A reader who sees neither draws the wrong conclusion from a correct
   // report — an agent read `xai ✗ not logged in` off a client and decided the hub could not
   // serve grok.
-  const remoteHubBanner = remoteHubBannerLine(status.json.remoteHub);
+  const remoteHubBanner = remoteHubBannerLine(status.json.remoteHub, status.json.connection.transport);
   if (remoteHubBanner) console.log(remoteHubBanner);
   // `(local)` only while connected: on a standalone install every line is local, and tagging
   // them all would be noise that trains the reader to skip the tag.
@@ -1798,7 +1812,9 @@ async function handleStatus() {
   if (status.json.hub) {
     for (const line of hubStatusLines(status.json.hub)) console.log(`   ${line}`);
   }
-  console.log(`   Remote hub: ${status.json.connection.state}${status.json.connection.serverUrl ? ` (${status.json.connection.serverUrl})` : ""}`);
+  console.log(status.json.remoteHub.link
+    ? `   Remote Link Home: ${status.json.connection.state} (${status.json.remoteHub.link.homePhrase}, ${status.json.remoteHub.link.linkId})`
+    : `   ${status.json.connection.transport === "link" ? "Remote Link Home" : "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}`);
   }
@@ -1854,10 +1870,12 @@ async function handleStatus() {
   // that decide what a request can route to. The local block still prints — an operator debugging
   // a half-migrated machine needs to see it — but under a heading that says it is not in use, and
   // below the hub's, so the hub's is what a reader (or an agent) encounters first (#4236).
-  for (const line of remoteHubStatusLines(status.json.remoteHub)) console.log(`   ${line}`);
+  for (const line of remoteHubStatusLines(status.json.remoteHub, status.json.connection.transport)) console.log(`   ${line}`);
   if (status.json.remoteHub.connected) {
     console.log(status.json.remoteHub.stateSource === "unavailable"
-      ? "   Local-only credential state (this is NOT the hub's; the hub's state could not be read):"
+      ? status.json.connection.transport === "link"
+        ? "   Local-only credential state (Home state is unavailable over Remote Link):"
+        : "   Local-only credential state (this is NOT the hub's; the hub's state could not be read):"
       : "   Local-only (not used for routing while connected):");
   }
   console.log(`   OAuth logins${local}:`);