@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/cli/capabilities-base.ts

@@ -571,11 +571,11 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["claude","config"],
     summary: "Read or update Claude Code settings, including independent CLI first-party routing.",
     routes: [{"method":"GET","path":"/api/claude-code"},{"method":"PUT","path":"/api/claude-code"}],
-    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
+    flags: [{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--auth-mode","value":"string","summary":"auto, proxy or subscription."},{"name":"--system-env","value":"string","summary":"on or off."},{"name":"--fast-mode","value":"string","summary":"on or off."},{"name":"--auto-context","value":"string","summary":"on or off."},{"name":"--compact-window","value":"string","summary":"Positive token count or default to clear."},{"name":"--context-accounting","value":"string","summary":"1m (default) or 200k."},{"name":"--inject-agents","value":"string","summary":"on or off."},{"name":"--small-fast-model","value":"string","summary":"Model ID; - clears."},{"name":"--model-map","value":"string","summary":"Comma-separated from=to mappings; - clears."},{"name":"--blocked-skills","value":"string","summary":"Comma-separated names; - clears."},{"name":"--web-model","value":"string","summary":"Model ID; - clears."},{"name":"--web-backend","value":"string","summary":"openai, anthropic, xai, gemini, exa or -."},{"name":"--vision-model","value":"string","summary":"Model ID; - clears."},{"name":"--vision-backend","value":"string","summary":"openai, anthropic or -."},{"name":"--first-party","value":"string","summary":"on or off; must be the only setting."},{"name":"--json","value":"boolean","summary":"Emit the result as JSON."}],
     mutates: true,
     json: "payload",
     details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.","Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],
-    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    usage: "ocx claude config status [--json]; ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
   },
   {
     command: ["claude","intercept","start"],
@@ -714,11 +714,11 @@ export const CAPABILITIES: readonly Capability[] = [
     command: ["agent","roles"],
     summary: "omo (Codex / LazyCodex): show each Codex agent role's model pin, set one role's model in its TOML and in omo.jsonc, or suggest a model for every role.",
     routes: [{"method":"GET","path":"/api/codex-agent-roles"},{"method":"PUT","path":"/api/codex-agent-roles/{role}"},{"method":"POST","path":"/api/codex-agent-roles/auto-assign"}],
-    flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
+    flags: [{"name":"--json","value":"boolean","summary":"Emit the role list, the write result or the proposals as JSON."},{"name":"--effort","value":"string","summary":"set: also write the role's reasoning effort."},{"name":"--model","value":"string","summary":"suggest: size the roles with this model instead of the Codex default model."},{"name":"--apply","value":"boolean","summary":"suggest: write every proposal through the role model write."}],
     mutates: true,
     json: "payload",
-    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml; omo.jsonc is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
-    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
+    details: ["A bare invocation reads and never writes.","Requires Codex-based omo (LazyCodex): the omo@sisyphuslabs Codex plugin enabled in config.toml and installed; otherwise status lists no roles, and set and suggest are refused.","set rewrites only the root model value of $CODEX_HOME/agents/<role>.toml, plus model_reasoning_effort with --effort; omo.jsonc gets the same model and, when LazyCodex has that level, the effort as reasoning; it is skipped when absent or when it contains comments.","suggest sizes every role with one model call and prints proposals without writing; --apply writes each proposed model, and its effort when the role file already sets model_reasoning_effort."],
+    usage: "ocx agent roles [status] [--json]; ocx agent roles set <role> <model> [--effort <level>] [--json]; ocx agent roles suggest [--model <id>] [--apply] [--json]",
   },
   {
     command: ["agent","injection"],

package/src/cli/capabilities-integrations.ts

@@ -111,6 +111,22 @@ export const INTEGRATION_CAPABILITIES: readonly Capability[] = [
     json: "payload",
     details: ["With --client, restore requires --profile; only Aside profiles accept that selector. No automatic drift confirmation or retry.","Preview preserves exact opId/profile/confirm-drift intent. Generic restore derives the client on the server; the returned plan does not embed opId or complete command input.","A refused or no-op preview is completed inspection, not applied work. A stale bound mutation exits5 with a fixed re-preview hint; no replacement token is automatically adopted."],
   },
+  {
+    command: ["commandcode", "restore"],
+    usage: "ocx commandcode restore --op <opId> [--confirm-drift] [--preview | --plan-fingerprint <token>] [--json]",
+    summary: "Restore a Command Code rollback operation, retaining client ownership and drift checks.",
+    routes: [{ method: "POST", path: "/api/client-integrations/commandcode/restore" }, { method: "POST", path: "/api/client-integrations/commandcode/restore/preview" }],
+    flags: [
+      { name: "--op", value: "string", summary: "Command Code operation ID; --op-id is an alias.", required: true },
+      { name: "--confirm-drift", value: "boolean", summary: "Explicitly allow replacing edits made after the snapshot." },
+      { name: "--preview", value: "boolean", summary: "Inspect restoration without mutating; exclusive with a commit fingerprint." },
+      { name: "--plan-fingerprint", value: "string", summary: "Optional versioned token from a matching preview; stale intent is refused without retry." },
+      { name: "--json", value: "boolean", summary: "Emit the result as JSON." },
+    ],
+    mutates: true,
+    json: "payload",
+    details: ["cmd restore is an alias. --client and --profile are rejected; the dedicated route binds the operation to Command Code.", "Older proxies without the dedicated route fail without a generic restore fallback. Redirects are refused.", "Preview preserves the operation and drift intent. A stale bound mutation requires a new explicit preview."],
+  },
   {
     command: ["claude", "config", "status"],
     usage: "ocx claude config status [--json]",
@@ -123,10 +139,10 @@ export const INTEGRATION_CAPABILITIES: readonly Capability[] = [
   },
   {
     command: ["claude", "config", "set"],
-    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
+    usage: "ocx claude config set [--enabled <on|off>] [--auth-mode <auto|proxy|subscription>] [--system-env <on|off>] [--fast-mode <on|off>] [--auto-context <on|off>] [--compact-window <tokens|default>] [--context-accounting <1m|200k>] [--inject-agents <on|off>] [--small-fast-model <id|->] [--model-map <from=to,...|->] [--blocked-skills <name,name|->] [--web-model <id|->] [--web-backend <openai|anthropic|xai|gemini|exa|->] [--vision-model <id|->] [--vision-backend <openai|anthropic|->] [--json]; or ocx claude config set --first-party <on|off> [--json]",
     summary: "Change Claude Code settings through the runtime owner.",
     routes: [{"method": "PUT", "path": "/api/claude-code"}],
-    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
+    flags: [{"name": "--enabled", "value": "string", "summary": "on or off."}, {"name": "--auth-mode", "value": "string", "summary": "auto, proxy or subscription."}, {"name": "--system-env", "value": "string", "summary": "on or off."}, {"name": "--fast-mode", "value": "string", "summary": "on or off."}, {"name": "--auto-context", "value": "string", "summary": "on or off."}, {"name": "--compact-window", "value": "string", "summary": "Positive token count or default to clear."}, {"name": "--context-accounting", "value": "string", "summary": "1m (default) or 200k."}, {"name": "--inject-agents", "value": "string", "summary": "on or off."}, {"name": "--small-fast-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--model-map", "value": "string", "summary": "Comma-separated from=to mappings; - clears."}, {"name": "--blocked-skills", "value": "string", "summary": "Comma-separated names; - clears."}, {"name": "--web-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--web-backend", "value": "string", "summary": "openai, anthropic, xai, gemini, exa or -."}, {"name": "--vision-model", "value": "string", "summary": "Model ID; - clears."}, {"name": "--vision-backend", "value": "string", "summary": "openai, anthropic or -."}, {"name": "--first-party", "value": "string", "summary": "on or off; must be the only setting."}, {"name": "--json", "value": "boolean", "summary": "Emit the result as JSON."}],
     mutates: true,
     json: "payload",
     details: ["At least one setting is required. --first-party must be set alone and writes Claude settings immediately.", "Clear both helper model and backend with - to restore inheritance. Preserve shared_proxy_retained warnings."],

package/src/cli/cli-path-diagnostics.ts

@@ -0,0 +1,132 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+import { readDesktopCliRecord, type DesktopCliRecordRead, desktopCliRecordPath, DESKTOP_CLI_RECORD_MAX_BYTES } from "../lib/desktop-cli-record.mjs";
+import { redactUserPath } from "../lib/redact";
+
+export type CliCommandIssue = Extract<DesktopCliRecordRead, { issue: string }>["issue"]
+  | "cleanup-pending"
+  | "desktop-target-missing" | "desktop-target-unusable"
+  | "expected-command-missing" | "expected-command-unusable"
+  | "path-missing" | "path-first-not-desktop" | "path-unreadable"
+  | "path-scan-truncated" | "windows-current-directory-shadow";
+export type CliPathCandidate = {
+  path: string; realpath: string; pathIndex: number; extension: string;
+};
+export type CliPathDiagnostics = {
+  configured: boolean;
+  recordPath: string;
+  packageHandoff: "enabled" | "disabled-on-windows";
+  recordState: DesktopCliRecordRead["state"];
+  expectedExecutable: string | null;
+  handoffTarget: string | null;
+  candidates: CliPathCandidate[];
+  pathFirst: CliPathCandidate | null;
+  desktopFirstOnPath: boolean | null;
+  currentDirectoryCandidate: CliPathCandidate | null;
+  shellResolution: "unobserved";
+  issues: CliCommandIssue[];
+};
+export type CliPathObservation =
+  | { kind: "usable"; realpath: string }
+  | { kind: "missing" | "unusable" | "unreadable" };
+export type CliPathDiagnosticOptions = {
+  platform?: NodeJS.Platform; env?: NodeJS.ProcessEnv; cwd?: string; home?: string;
+  recordRead?: DesktopCliRecordRead;
+  observe?: (path: string) => CliPathObservation;
+};
+
+export function collectCliPathDiagnostics(options: CliPathDiagnosticOptions = {}): CliPathDiagnostics {
+  const platform = options.platform ?? process.platform;
+  const env = options.env ?? process.env;
+  const api = platform === "win32" ? win32 : posix;
+  const cwd = options.cwd ?? process.cwd();
+  const home = options.home ?? (platform === "win32" ? env.USERPROFILE || homedir() : homedir());
+  const read = options.recordRead ?? readDesktopCliRecord({ platform, env, home, recordPath: desktopCliRecordPath({ platform, env, home }) });
+  const configured = read.state === "ready";
+  const target = configured && read.state === "ready" ? read.record.cliExecutable : null;
+  const expected = configured ? (platform === "win32" ? target : api.join(home, ".opencodex-desktop", "bin", "ocx")) : null;
+  const issues: CliCommandIssue[] = [];
+  const add = (issue: CliCommandIssue): void => { if (!issues.includes(issue)) issues.push(issue); };
+  if (read.state === "invalid" || read.state === "unreadable") add(read.issue);
+  if (read.state === "disabled" && read.cleanupPending) add("cleanup-pending");
+  const observe = options.observe ?? ((path: string): CliPathObservation => {
+    try {
+      if (!statSync(path).isFile()) return { kind: "unusable" };
+      accessSync(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+      return { kind: "usable", realpath: realpathSync(path) };
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      return { kind: code === "ENOENT" || code === "ENOTDIR" ? "missing" : code === "EACCES" ? "unusable" : "unreadable" };
+    }
+  });
+  const key = (path: string): string => platform === "win32" ? path.toLowerCase() : path;
+  const same = (a: string, b: string): boolean => key(a) === key(b);
+  const envValue = (name: string): string | undefined => platform === "win32"
+    ? env[Object.keys(env).find(key => key.toLowerCase() === name.toLowerCase()) ?? name] : env[name];
+  const path = envValue("PATH");
+  const rawExtensions = platform === "win32"
+    ? (envValue("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(ext => /^\.[A-Za-z0-9]+$/.test(ext)) : [];
+  const uniqueExtensions = [...new Set(rawExtensions.map(ext => ext.toLowerCase()))];
+  const extensions = platform === "win32" ? [...uniqueExtensions.slice(0, 32), ""] : [""];
+  if (uniqueExtensions.length > 32) add("path-scan-truncated");
+  const directories = path === undefined ? [] : path.split(platform === "win32" ? ";" : ":");
+  if (directories.length > 256) add("path-scan-truncated");
+  const candidates: CliPathCandidate[] = [];
+  const scan = (directory: string, pathIndex: number): CliPathCandidate[] => {
+    const result: CliPathCandidate[] = [];
+    const unquoted = platform === "win32" && directory.startsWith('"') && directory.endsWith('"') ? directory.slice(1, -1) : directory;
+    for (const extension of extensions) {
+      const candidate = api.resolve(cwd, unquoted || ".", `ocx${extension}`);
+      const found = observe(candidate);
+      if (found.kind === "unreadable") add("path-unreadable");
+      if (found.kind === "usable") result.push({ path: candidate, realpath: found.realpath, pathIndex, extension });
+    }
+    return result;
+  };
+  for (const [index, directory] of directories.slice(0, 256).entries()) candidates.push(...scan(directory, index));
+  const pathFirst = candidates[0] ?? null;
+  const currentDirectoryCandidate = platform === "win32" ? scan(cwd, -1)[0] ?? null : null;
+  let expectedRealpath: string | null = null;
+  if (target) {
+    const found = observe(target);
+    if (found.kind === "missing") add("desktop-target-missing");
+    else if (found.kind !== "usable") add("desktop-target-unusable");
+  }
+  if (expected) {
+    const found = observe(expected);
+    if (found.kind === "missing") add("expected-command-missing");
+    else if (found.kind !== "usable") add("expected-command-unusable");
+    else expectedRealpath = found.realpath;
+    if (!pathFirst) add("path-missing");
+    else if (!same(pathFirst.path, expected) && (!expectedRealpath || !same(pathFirst.realpath, expectedRealpath))) add("path-first-not-desktop");
+    if (currentDirectoryCandidate && !same(currentDirectoryCandidate.path, expected)
+      && (!expectedRealpath || !same(currentDirectoryCandidate.realpath, expectedRealpath))) add("windows-current-directory-shadow");
+  }
+  return {
+    configured, recordPath: read.path, packageHandoff: platform === "win32" ? "disabled-on-windows" : "enabled",
+    recordState: read.state, expectedExecutable: expected, handoffTarget: platform === "win32" ? null : target,
+    candidates, pathFirst,
+    desktopFirstOnPath: configured && !issues.includes("path-unreadable") && !issues.includes("path-scan-truncated")
+      ? Boolean(pathFirst && expected && expectedRealpath
+        && (same(pathFirst.path, expected) || same(pathFirst.realpath, expectedRealpath))) : null,
+    currentDirectoryCandidate, shellResolution: "unobserved", issues,
+  };
+}
+
+export function formatCliCommandLine(value: CliPathDiagnostics): string {
+  const first = value.pathFirst ? redactUserPath(value.pathFirst.path).replace(/[\x00-\x1f\x7f]/g, "?") : "none observed";
+  return `ocx command: PATH first=${first}; Desktop=${!value.configured ? "not configured" : value.desktopFirstOnPath === null ? "unobserved" : value.desktopFirstOnPath ? "first" : "not first"}; ${value.packageHandoff === "disabled-on-windows" ? "package handoff=disabled on Windows (user Path selects Desktop); " : ""}shell=unobserved${value.issues.length ? `; issues=${value.issues.join(",")}` : ""}`;
+}
+
+export function formatCliStatusHealthLabel(health: string, value: CliPathDiagnostics, local: boolean): string {
+  return `${health}${local ? " (local)" : ""}\n   ${formatCliCommandLine(value)}`;
+}
+
+export function cliCommandDoctorChecks(value: CliPathDiagnostics): { level: "OK" | "WARN" | "FAIL"; message: string }[] {
+  const hard = value.issues.some(issue => issue.startsWith("record-") || issue.startsWith("desktop-target-") || issue.startsWith("expected-command-"));
+  const recovery = value.issues.some(issue => issue.startsWith("record-"))
+    ? ` The terminal-command record at ${redactUserPath(value.recordPath).replace(/[\x00-\x1f\x7f]/g, "?")} could not be used. Open OpenCodex Desktop to repair the terminal command.${value.packageHandoff === "disabled-on-windows" ? "" : " Or run with OCX_NO_DESKTOP_HANDOFF=1."}${value.issues.includes("record-too-large") ? ` The record limit is ${DESKTOP_CLI_RECORD_MAX_BYTES} bytes.` : ""}`
+    : value.issues.includes("cleanup-pending") ? " Open OpenCodex Desktop to finish terminal-command cleanup." : "";
+  return [{ level: hard ? "FAIL" : value.issues.length ? "WARN" : "OK", message: formatCliCommandLine(value) + recovery }];
+}

package/src/cli/codex-shim-autorestore.ts

@@ -15,11 +15,14 @@ const DEFAULT_DEPS: CodexShimAutoRestoreCliDeps = {
   readConfig: readConfigDiagnostics,
 };
 
+/** Identify command namespaces whose execution must not trigger automatic shim repair. */
 export function skipsCodexShimAutoRestore(command: string | undefined, args: string[]): boolean {
   if (command === "uninstall" || command === "remove") return true;
   if (command === "status" || command === "doctor") return true;
   // `lab` is read-only inspection; it must not trigger shim side effects.
   if (command === "lab") return true;
+  // Local messaging owns its helpers; even malformed usage must not repair/start anything.
+  if (command === "message") return true;
   // `resolve` is read-only inspection for embedding shells: a lookup made to populate
   // a consent surface must not trigger a shim repair side effect first.
   if (command === "resolve") return true;

package/src/cli/desktop-runtime-guidance.ts

@@ -0,0 +1,65 @@
+import { createSupervisionLatch, inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import type { DesktopSupervision, SupervisionInspector } from "../service/desktop-command-guard";
+import { UpdateRestartRequired } from "./update-restart-candidate";
+import { runProxyRestart, type ProxyRestartIo } from "./tray-proxy";
+
+function evidenceForTarget(evidence: DesktopSupervision, pid: number | null | undefined): DesktopSupervision {
+  // Injected inspectors must obey the same target binding as the production inspector.
+  return evidence.kind === "desktop" && pid != null && evidence.runtimePid !== pid
+    ? { kind: "unknown", reason: "unrelated-target", desktopSeen: false } : evidence;
+}
+
+export function duplicateRuntimeMessage(
+  pid: number | null | undefined,
+  port: number,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+): string {
+  const latch = createSupervisionLatch();
+  const evidence = evidenceForTarget(inspect({ targetPid: pid ?? undefined }), pid);
+  if (pid != null && latch.observe(evidence)) {
+    const supervisor = evidence.kind === "desktop" ? `, ${evidence.app}` : "";
+    return `OpenCodex Desktop supervises the running proxy (pid ${pid}${supervisor}, port ${port}). `
+      + "Use the running proxy, or quit OpenCodex before starting it from this CLI.";
+  }
+  return `⚠️  Proxy already running (PID ${pid ?? "unknown"}, port ${port}). Use 'ocx stop' first.`;
+}
+
+export function desktopStopNotice(evidence: DesktopSupervision): string | null {
+  const latch = createSupervisionLatch();
+  return latch.observe(evidence)
+    ? "OpenCodex Desktop may start this proxy again after a short backoff. Use Stop Proxy or Quit in the OpenCodex menu to keep it stopped."
+    : null;
+}
+
+export function runDesktopAwareProxyRestart(
+  io: ProxyRestartIo,
+  inspect: SupervisionInspector = inspectDesktopSupervision,
+  info: (line: string) => void = console.log,
+) {
+  const latch = createSupervisionLatch();
+  let targetPid: number | undefined;
+  let supervisedRequest = false;
+  return runProxyRestart({
+    ...io,
+    requestInPlaceRestart: async previous => {
+      targetPid = previous.pid ?? undefined;
+      const evidence = evidenceForTarget(inspect({ targetPid }), targetPid);
+      supervisedRequest = latch.observe(evidence);
+      const result = await io.requestInPlaceRestart(previous);
+      if (evidence.kind === "desktop" && result.accepted) {
+        info("Restart requested; OpenCodex Desktop starts the replacement.");
+      }
+      if (supervisedRequest && !result.accepted && !result.uncertain && result.error instanceof UpdateRestartRequired) {
+        info("OpenCodex Desktop supervises this proxy. Use the app's updater (tray → Check for Updates), or quit OpenCodex before updating and restarting from this CLI.");
+        return { accepted: false as const, uncertain: false, error: new Error("restart_desktop_update_required") };
+      }
+      return result;
+    },
+    startWhenStopped: async recovering => {
+      const blocked = latch.observe(evidenceForTarget(inspect({ targetPid }), targetPid));
+      // An accepted supervised handoff keeps its replacement intent through temporary absence.
+      if (supervisedRequest || blocked) return { status: "skipped" as const };
+      return io.startWhenStopped(recovering);
+    },
+  });
+}

package/src/cli/dispatch.ts

@@ -37,6 +37,8 @@ import { parseStopApproval, type StopApproval } from "./stop-approval";
 import type { ResolveArgs } from "./resolve";
 import type { ClientConnectionState } from "../client/state";
 import { OCX_NATIVE_REPLAY_RECOVERY_NOTE } from "../responses/compaction";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { desktopStopNotice } from "./desktop-runtime-guidance";
 
 export interface CliDispatchDeps {
   args: string[];
@@ -51,6 +53,7 @@ export interface CliDispatchDeps {
   spawnDetached: (argv: readonly string[]) => void;
   handleStart: () => Promise<void>;
   handleStop: (approval?: StopApproval) => Promise<StopOutcome>;
+  inspectDesktopSupervision?: typeof inspectDesktopSupervision;
   handleEnsure: (options?: { existingIsSuccess?: boolean }) => Promise<boolean>;
   handleResolve: (args: ResolveArgs) => Promise<number>;
   handleTrayProxyStart: (existingIsSuccess?: boolean) => Promise<boolean>;
@@ -112,6 +115,8 @@ const commandRunners: Record<string, CommandRunner> = {
     // re-start the proxy immediately, so warning there would contradict the next line.
     const warning = "⚠️  Codex/Claude requests through the proxy will fail until it is restarted ('ocx start' or 'ocx service start').";
     if (!parsed.json) {
+      const notice = desktopStopNotice((deps.inspectDesktopSupervision ?? inspectDesktopSupervision)());
+      if (notice) console.error(notice);
       // handleStop returns the structured outcome now; an object is always truthy, so
       // the warning must key on .ok — otherwise a failed stop would still claim downtime.
       if ((await deps.handleStop()).ok) console.log(warning);
@@ -145,6 +150,7 @@ const commandRunners: Record<string, CommandRunner> = {
     if (!deps.head.resolveArgs) return 64;
     return await deps.handleResolve(deps.head.resolveArgs);
   },
+  message: async deps => (await import("./message-command")).runMessageCommand(deps.args.slice(1)),
   restore: async deps => {
     const restoreArgs = deps.args.slice(1);
     const restoreJson = takeFlag(restoreArgs, "--json");
@@ -465,7 +471,7 @@ const commandRunners: Record<string, CommandRunner> = {
             },
             config,
             port: live.port,
-          }, ["mcode", "pi", "raycast", "omo", "cline", "droid", "opencode", "kilo"]));
+          }, ["mcode", "pi", "raycast", "omo", "cline", "commandcode", "droid", "opencode", "kilo"]));
         } catch (error) {
           console.warn(`Client integrations were not refreshed: ${error instanceof Error ? error.message : String(error)}`);
         }
@@ -961,6 +967,14 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleZcodeCommand } = await import("./integrations");
     return await handleZcodeCommand(deps.args.slice(1));
   },
+  commandcode: async deps => {
+    const { handleCommandcodeCommand } = await import("./integrations");
+    return await handleCommandcodeCommand(deps.args.slice(1));
+  },
+  cmd: async deps => {
+    const { handleCommandcodeCommand } = await import("./integrations");
+    return await handleCommandcodeCommand(deps.args.slice(1));
+  },
   help: async () => {
     printUsage();
     return 0;

package/src/cli/doctor.ts

@@ -7,11 +7,13 @@
  * it never sets proxy env, relocates state dirs, mutates quota, or changes
  * networking. See devlog/_plan/260630_wsl-account-autoswitch/30_*.
  */
+import { cliCommandDoctorChecks, collectCliPathDiagnostics } from "./cli-path-diagnostics";
 import { accessSync, constants, existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 import { getConfigDir, getConfigPath, readConfigDiagnostics } from "../config";
 import { readPid } from "../config/process-state";
+import { inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
 import { fetchLiveStartupHealth, probeUncleanExitState, selectStatusStartupHealth } from "./status";
 import { findLiveProxy, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { directLocalHttpFetch } from "../server/direct-local-http";
@@ -1324,6 +1326,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     console.log(`  ${row.exists ? "ok " : "-- "} ${row.label}: ${row.path}${flags ? `  (${flags})` : ""}`);
   }
 
+  console.log("\nocx command selection");
+  for (const check of cliCommandDoctorChecks(collectCliPathDiagnostics())) {
+    console.log(`  ${check.level === "OK" ? "ok " : "!! "} ${check.message}`);
+    if (check.level === "FAIL") recordDoctorFailure();
+  }
+
   // Runs without the proxy on purpose: the worst accumulation happens when the proxy will
   // not start, which is exactly when the in-process periodic reclaim never ticks.
   const reclaimTemps = args.includes(RECLAIM_RESPONSE_TEMPS_FLAG);
@@ -1379,7 +1387,8 @@ export async function runDoctor(args: string[] = []): Promise<void> {
     configFn: () => ({ port: doctorConfig.port, hostname: doctorConfig.hostname }),
   });
   const liveStartup = live ? await fetchLiveStartupHealth(live) : null;
-  const startup = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig));
+  const { startup } = selectStatusStartupHealth(liveStartup, () => collectStartupHealth(doctorConfig),
+    live?.pid != null ? () => inspectDesktopSupervision({ targetPid: live.pid! }) : undefined, live?.pid);
   console.log("\nCodex restart safety");
   console.log(`  ${startup.rebootSafe ? "ok " : "!! "} ${startupHealthSummary(startup)}`);
   console.log(`       ${formatStartupRoutingDetail(startup)}`);
@@ -1685,8 +1694,12 @@ export async function runDoctor(args: string[] = []): Promise<void> {
   const anyDrvfs = paths.some(p => detectFsType(p.path, mounts).isDrvfs || detectFsType(p.path, mounts).isMntDrive);
   const noProxy = currentProxyEnv.every(p => !p.present) && !configuredProxy.present;
   if (!startup.rebootSafe) {
-    const command = startup.recommendedCommand ?? startup.commands.restoreNative;
-    hints.push(`Codex is pinned to the local proxy without persistent startup protection. After restart, requests can reconnect indefinitely. Run '${command}'.`);
+    if (startup.recommendedAction || startup.desktop?.supervisor) {
+      hints.push(`Codex is pinned to the local proxy without persistent startup protection. ${startup.recommendedAction ?? "Reopen OpenCodex and check Start at Login."}`);
+    } else {
+      const command = startup.recommendedCommand ?? startup.commands.restoreNative;
+      hints.push(`Codex is pinned to the local proxy without persistent startup protection. After restart, requests can reconnect indefinitely. Run '${command}'.`);
+    }
   }
   if (anyDrvfs) {
     hints.push("State dir is on a Windows-mounted (/mnt) drive. Prefer the Linux home (~) under WSL for token/lock reliability.");

package/src/cli/help.ts

@@ -79,6 +79,7 @@ Usage:
   ocx alias <sub>             Short names for providers and models (list, set, rm, defaults)
   ocx combo <sub>             Combo routing strategies and failover
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
+  ocx message <sub>           Loaded local Codex sessions and queued peer messages (sessions|send)
   ocx effort [sub]            Inspect and configure reasoning effort caps and defaults
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx inspect <sub>           Effective config, catalog, analytics, pacing, client-config
@@ -91,7 +92,7 @@ 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 (17 clients)
+  ocx export --client <id>    Print a client config wired to the running proxy (18 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
@@ -105,6 +106,8 @@ Usage:
   ocx mcode [args...]         Launch MiniMax Code through its managed provider
   ocx mmx text <sub> [args]   Launch MiniMax CLI text through the proxy
   ocx zcode [sub]             Connect ZCode to the proxy (managed provider)
+  ocx commandcode [sub]       Connect Command Code CLI to the proxy (managed provider)
+  ocx cmd [sub]               Alias of ocx commandcode
   ocx help [command]          Show help
   ocx --version | -v          Print version
 

package/src/cli/index.ts

@@ -8,6 +8,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { currentServingCommand, deferServiceChildToNewerRuntime, markDelegatedServiceReady, recordServingRuntime } from "../config/serving-runtimes";
 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 { UpdateRestartRequired } from "./update-restart-candidate";
 import { describeUpdateRestartFailure, restartFromCurrentInstallation } from "./update-restart";
@@ -75,7 +77,7 @@ import {
   pendingTeardownsAreExactly,
   quarantinePendingTeardown,
 } from "../config/pending-teardown";
-import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, unusedProxyWarningLines } from "./status";
+import { collectStatus, deadProxyRoutingAdviceLines, detectMissingCodexCatalogPath, hubStatusLines, missingCodexCatalogLines, remoteHubBannerLine, remoteHubStatusLines, runtimeSupervisorLine, unusedProxyWarningLines } from "./status";
 import { endpointsToProve, everyEndpointProvenDownAsync, sharedTeardownAuthorized, type UninstallObservation } from "./uninstall-plan";
 import { takeFlag } from "./runtime-api";
 import { parseStartOptions, StartArgsError } from "./start-args";
@@ -85,11 +87,11 @@ import {
   recheckRestartFailedStart, reobserveRestartReplacement,
   restartStartOutcome,
   waitForProxyReplacement,
-  runProxyRestart,
   runTrayProxyStart,
   type ProxyRestartLive,
   type ProxyRestartStartOutcome,
 } from "./tray-proxy";
+import { duplicateRuntimeMessage, runDesktopAwareProxyRestart } from "./desktop-runtime-guidance";
 import { reportRestartFailure } from "./restart-failure";
 import { requestBoundSystemRestart } from "./system-restart-client";
 import { installCrashGuards } from "../lib/crash-guard";
@@ -210,11 +212,17 @@ 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] === "__codebuddy-mcp") {
-  const { runCodeBuddyMcpServer } = await import("../adapters/codebuddy/mcp-server");
-  await runCodeBuddyMcpServer(process.argv[3] ?? "");
-  // The MCP stdio loop owns this process until stdin closes; do not fall through
-  // to ordinary CLI dispatch or exit after the handshake completes.
+
+// The compiled executable also launches the isolated MCP servers.
+// Handle these private entrypoints before CLI preflight or command dispatch.
+if (process.argv[2] === "__codebuddy-mcp" || process.argv[2] === "__qoder-mcp") {
+  if (process.argv[2] === "__codebuddy-mcp") {
+    const { runCodeBuddyMcpServer } = await import("../adapters/codebuddy/mcp-server");
+    await runCodeBuddyMcpServer(process.argv[3] ?? "");
+  } else {
+    const { runCodingAgentMcpServer } = await import("../adapters/coding-agent/mcp-server");
+    await runCodingAgentMcpServer(process.argv[3] ?? "");
+  }
   await new Promise<never>(() => {});
 }
 
@@ -323,7 +331,7 @@ async function chooseListenPort(
         throw new StartCommandExit(serviceStayOutExitCode());
       }
       if (decision === "refuse-live-proxy") {
-        console.error(`⚠️  Proxy already running (PID ${holder?.pid ?? "unknown"}, port ${preferred}). Use 'ocx stop' first.`);
+        console.error(duplicateRuntimeMessage(holder?.pid, preferred));
         throw new StartCommandExit(1);
       }
       if (decision === "refuse-unidentified-holder") {
@@ -438,7 +446,7 @@ async function handleStart(options: { block?: boolean } = {}) {
       process.exit(serviceStayOutExitCode());
     }
     if (decision === "refuse" || decision === "await-parent") {
-      console.error(`⚠️  Proxy already running (PID ${owner.live.pid ?? owner.pidSnapshot ?? "unknown"}, port ${owner.live.port}). Use 'ocx stop' first.`);
+      console.error(duplicateRuntimeMessage(owner.live.pid ?? owner.pidSnapshot, owner.live.port));
       process.exit(1);
     }
     // Sibling path. The new instance takes over this home's ocx.pid / runtime-port.json while
@@ -648,10 +656,12 @@ async function handleStart(options: { block?: boolean } = {}) {
     removeRuntimePort(process.pid);
     if (teardown.restoreNativeCodex && !currentExternalCodexModelProvider()) {
       try {
-        const restored = restoreNativeCodex();
-        if (!restored.success) {
-          cleanupSucceeded = false;
-          console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+        if (!codexHomeIsAbsent(getCodexHome())) {
+          const restored = restoreNativeCodex();
+          if (!restored.success) {
+            cleanupSucceeded = false;
+            console.error(`⚠️  Native Codex restore failed during shutdown: ${restored.message}`);
+          }
         }
       } catch (error) {
         cleanupSucceeded = false;
@@ -922,7 +932,7 @@ async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {
   const deadlineAt = Date.now() + PROXY_RESTART_OBSERVE_MS;
-  const result = await runProxyRestart({
+  const result = await runDesktopAwareProxyRestart({
     findLive: () => discoverStableProxyForRestart({
       findLive: () => findLiveProxy({ deadlineAt, attempts: 2, acceptPackageTreeFenced: true }),
       expired: () => Date.now() >= deadlineAt,
@@ -1779,6 +1789,7 @@ async function handleStatus() {
   console.log(`   Config: ${status.json.paths.config}${local}`);
   console.log(`   PID file: ${status.json.paths.pid}${local}`);
   console.log(`   Runtime: ${status.json.paths.runtime}${local}`);
+  if (runtimeSupervisorLine(status.json.startup)) console.log(`   ${runtimeSupervisorLine(status.json.startup)}`);
   console.log(`   Runtime source: ${status.json.runtime.source}${status.json.runtime.overrideEnv ? ` (${status.json.runtime.overrideEnv})` : ""}${local}`);
   // On a client this is the local default, which routing does not use — the hub applies its own.
   console.log(`   Default provider: ${status.json.defaultProvider}${local}`);

package/src/cli/integration-aside-sync.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { redactUserPath } from "../lib/redact";
 import type { RefusalReason } from "../integrations/mutation-plan";
+import { ASIDE_SYNC_EMPTY_LINES } from "./aside-profile-recovery";
 import { refreshAsideProfilesThroughServer } from "./aside-profiles";
 import { runCatalogAction } from "./catalog-command-result";
 import { CliUsageError, RuntimeApiError, printData, takeFlag, takeOption, type RuntimeApiDeps } from "./runtime-api";
@@ -56,7 +57,7 @@ export function handleIntegrationAsideSync(argv: string[], deps: AsideSyncCliDep
     const parsed = resultsSchema.safeParse(outcomes);
     if (!parsed.success) throw new Error("Invalid Aside synchronization outcome");
     const results = parsed.data;
-    const lines = results.length === 0 ? ["No eligible Aside profiles to synchronize. Check integration status and profile sync preferences."]
+    const lines = results.length === 0 ? [...ASIDE_SYNC_EMPTY_LINES]
       : results.flatMap(row => [
         `Aside profile ${row.profileId}: ${row.ok ? row.changed ? "updated" : "unchanged" : "failed"}.`,
         ...(row.reason ? [row.reason] : []),

package/src/cli/integration-plan-dto.ts

@@ -23,6 +23,7 @@ export const FILE_INTEGRATION_CLIENTS = [
   "raycast",
   "omo",
   "cline",
+  "commandcode",
   "kilo",
   "droid",
 ] as const;

package/src/cli/integration-preview.ts

@@ -1,5 +1,6 @@
 /** Preview and explicitly bound mutations use the existing management authority. */
 import type { IntegrationMutationPlan, IntegrationPlanOperation } from "../integrations/mutation-plan";
+import type { IntegrationClientId } from "../integrations/registry";
 import { redactSecretString, redactUserPath } from "../lib/redact";
 import {
   CliUsageError, RuntimeApiError, printData, runtimeRequest, terminalSafeText,
@@ -186,9 +187,15 @@ function reportError(error: unknown): number {
   return 1;
 }
 
-export async function handleIntegrationPreviewCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+export async function handleIntegrationPreviewCommand(argv: string[], deps: RuntimeApiDeps = {}, expectedClientId?: IntegrationClientId): Promise<number> {
   try {
     const intent = parseIntent(argv);
+    if (expectedClientId !== undefined && intent.operation === "restore") {
+      if (intent.client !== undefined || intent.profile !== undefined) throw new CliUsageError("client-specific restore does not accept --client or --profile", USAGE);
+      intent.client = expectedClientId;
+      intent.path = `${clientIntegrationPath(expectedClientId)}/restore${intent.preview ? "/preview" : ""}`;
+      intent.body.expectedClientId = expectedClientId;
+    }
     const result = await runtimeRequest(intent.path, {
       method: intent.preview || intent.operation === "restore" ? "POST" : "PUT",
       redirect: "error", body: JSON.stringify(intent.body),