fix(cli): refuse to compete with a Desktop-supervised runtime in service, update, start and stop

bin/ocx.mjs

@@ -9,6 +9,7 @@
  * src/cli/index.ts — only the published npm/pnpm `bin` routes through here.)
  */
 import { spawn, spawnSync } from "node:child_process";
+import { createSupervisionLatch, inspectDesktopSupervision } from "../src/service/desktop-supervision.mjs";
 import { STOP_HISTORY_INCOMPLETE_EXIT_CODE } from "../src/update/stop-contract.mjs";
 import { probeProxyLiveness } from "../src/update/proxy-liveness-probe.mjs";
 import { decidePostStopUpdate } from "../src/update/stop-decision.mjs";
@@ -333,11 +334,13 @@ function runPackageManagerSelfUpdate(manager) {
     : JSON.stringify(observation.ownership
       ? ["owned", observation.ownership.owner, observation.ownership.installId, observation.ownership.consentGeneration]
       : ["none"]);
+  const supervisionLatch = createSupervisionLatch();
+  const observeSupervision = () => supervisionLatch.observe(inspectDesktopSupervision());
   const initialOwnership = readOwnership();
-  let runtimePlan = planUpdateRuntimeHandling({ ...initialOwnership, serviceInstalled: serviceWasInstalled });
+  let runtimePlan = planUpdateRuntimeHandling({ ...initialOwnership, serviceInstalled: serviceWasInstalled, supervision: observeSupervision() });
   if (runtimePlan.notice) console.log(runtimePlan.notice);
   if (!runtimePlan.mayReplacePackage) {
-    console.error("opencodex: update stopped before tray handoff, runtime stop, or package replacement because runtime ownership is unknown.");
+    console.error("opencodex: update stopped before tray handoff, runtime stop, or package replacement because runtime authority does not permit it.");
     process.exit(1);
   }
   const trayBeforeUpdate = planWindowsTrayUpdate(
@@ -466,6 +469,14 @@ function runPackageManagerSelfUpdate(manager) {
     : unprivilegedOwnershipMutationEnvironment(process.env);
 
   function startProxyDirectly() {
+    const supervision = observeSupervision();
+    const plan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: false, supervision });
+    if (!plan.mayStopRuntime) {
+      console.warn(supervision
+        ? "OpenCodex Desktop supervises the proxy; no CLI runtime was restored."
+        : plan.notice);
+      return false;
+    }
     if (!postUpdateLauncherUsable || !existsSync(postUpdateLauncher)) {
       console.error("opencodex: cannot restart the proxy because the launcher is missing; reinstall opencodex manually.");
       return false;
@@ -498,6 +509,15 @@ function runPackageManagerSelfUpdate(manager) {
   }
 
   function refreshBackgroundServiceOrStartDirect() {
+    const mayRefresh = () => {
+      const supervision = observeSupervision();
+      const plan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: true, supervision });
+      if (!plan.mayRestoreService) console.warn(supervision
+        ? "OpenCodex Desktop supervises the proxy; CLI recovery was skipped. Use the app's updater (tray → Check for Updates)."
+        : plan.notice);
+      return plan.mayRestoreService;
+    };
+    if (!mayRefresh()) return;
     const prevBake = process.env.OCX_BAKE_PORT;
     process.env.OCX_BAKE_PORT = String(bakePort);
     try {
@@ -513,6 +533,7 @@ function runPackageManagerSelfUpdate(manager) {
       // failure would resurrect the elevation prompt this change exists to avoid, and
       // could re-register a service the user just uninstalled.
       if (svc.status !== 0 && readServiceInstalledFromStatus(postUpdateLauncher) === false) {
+        if (!mayRefresh()) return;
         console.log("No registered service found — installing it instead.");
         svc = spawnSync(process.execPath, serviceInstallArgs(), {
           stdio: "inherit", windowsHide: true, env: mutationChildEnvironment(),
@@ -545,9 +566,12 @@ function runPackageManagerSelfUpdate(manager) {
         // Re-read rather than reuse the plan from before the package install: the app can
         // claim the runtime during an update that takes minutes, and the refusal that repair
         // just returned is indistinguishable from any other failure at this layer.
-        const nowOwned = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: true });
+        const supervision = observeSupervision();
+        const nowOwned = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: true, supervision });
         if (!nowOwned.mayStopRuntime) {
-          console.warn(nowOwned.notice ?? "opencodex: the background runtime is owned elsewhere; not starting a second proxy.");
+          console.warn(supervision
+            ? "OpenCodex Desktop supervises the proxy; CLI recovery was skipped. Use the app's updater (tray → Check for Updates)."
+            : nowOwned.notice ?? "opencodex: the background runtime is owned elsewhere; not starting a second proxy.");
           return;
         }
         // Repair normally avoids elevation for a healthy registration, but a stale Windows
@@ -584,7 +608,7 @@ function runPackageManagerSelfUpdate(manager) {
     // Stop authority is decided under the same lease the child joins. A takeover between the
     // earlier preflight and this boundary therefore blocks stop before it is sent.
     const lockedOwnership = readOwnership();
-    const lockedPlan = planUpdateRuntimeHandling({ ...lockedOwnership, serviceInstalled: serviceWasInstalled });
+    const lockedPlan = planUpdateRuntimeHandling({ ...lockedOwnership, serviceInstalled: serviceWasInstalled, supervision: observeSupervision() });
     if (lockedOwnership.subjectToken !== initialOwnership.subjectToken || !lockedPlan.mayReplacePackage) {
       releaseUpdateLease();
       console.error(lockedPlan.notice
@@ -626,6 +650,7 @@ function runPackageManagerSelfUpdate(manager) {
           liveness,
           plan: planStoppedRuntimeRecovery({
             stopAttempted,
+            supervision: observeSupervision(),
             ...recoveryOwnership,
             sameOwner: ownershipIdentity(recoveryOwnership) === stoppedOwnershipIdentity,
             liveness,
@@ -643,7 +668,9 @@ function runPackageManagerSelfUpdate(manager) {
         releaseUpdateLease();
         ({ liveness: recoveryLiveness, plan: recovery } = planRecovery());
       }
-      if (recovery.reason === "ownership-unknown") {
+      if (recovery.reason === "desktop-supervised") {
+        console.log("OpenCodex Desktop supervises the proxy; no CLI runtime was restored.");
+      } else if (recovery.reason === "ownership-unknown") {
         console.error(`opencodex: ${reason}; runtime ownership is unknown, so automatic recovery was refused. Run 'ocx status --json' and repair the service-state record before retrying.`);
       } else if (recovery.reason === "ownership-transferred") {
         console.log("opencodex: runtime ownership moved to another installation; the stopped CLI runtime was not revived.");
@@ -676,6 +703,14 @@ function runPackageManagerSelfUpdate(manager) {
       process.exit(1);
     }
     if (stopNeeded) {
+      const preStopPlan = planUpdateRuntimeHandling({
+        ...readOwnership(), serviceInstalled: serviceWasInstalled, supervision: observeSupervision(),
+      });
+      if (!preStopPlan.mayStopRuntime) {
+        console.error(preStopPlan.notice);
+        releaseUpdateLease();
+        process.exit(1);
+      }
       stopAttempted = true;
       console.log("⏹  Stopping the running proxy before updating...");
       const stopRes = spawnSync(process.execPath, [launcher, "stop"], {
@@ -732,7 +767,7 @@ function runPackageManagerSelfUpdate(manager) {
     }
 
     const replacementOwnership = readOwnership();
-    const replacementPlan = planUpdateRuntimeHandling({ ...replacementOwnership, serviceInstalled: serviceWasInstalled });
+    const replacementPlan = planUpdateRuntimeHandling({ ...replacementOwnership, serviceInstalled: serviceWasInstalled, supervision: observeSupervision() });
     const replacementLiveness = currentPackageRuntimeLiveness();
     if (replacementOwnership.subjectToken !== initialOwnership.subjectToken
       || !replacementPlan.mayReplacePackage
@@ -839,9 +874,10 @@ function runPackageManagerSelfUpdate(manager) {
     // path and keeps token restoration coupled to the lease itself.
     releaseUpdateLease();
   }
-  const postInstallPlan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled });
+  const postInstallPlan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled, supervision: observeSupervision() });
   if (res.status === 0) {
     console.log(`\nUpdated${latest ? ` to v${latest}` : ""}.`);
+    if (!postInstallPlan.mayStopRuntime) console.warn("Runtime authority does not permit CLI recovery; no service was refreshed or proxy started.");
     repairCodexShimIfNeeded(postUpdateLauncher);
     if (trayBeforeUpdate.refreshAfterReplacement) {
       const tray = spawnSync(process.execPath, [postUpdateLauncher, ...trayBeforeUpdate.installArgs], {

docs-site/src/content/docs/guides/desktop-app.md

@@ -83,6 +83,28 @@ The bundled CLI is `/Applications/OpenCodex.app/Contents/MacOS/ocx` on macOS and
 `/usr/bin/ocx` for the Linux deb package. Run that executable with `status` to check
 the app's proxy. Windows supervision detection is unsupported.
 
+While the CLI detects Desktop supervising the proxy, `ocx service install`, `repair`,
+`start`, and `restart` refuse before changing the service, even without recorded ownership
+or verified login registration. Quit OpenCodex, then run `ocx service install` to move
+startup management to the CLI. A duplicate `ocx start` names the Desktop supervisor.
+
+Use **Check for Updates…** in the tray to update the app's bundle. `ocx update` refuses
+package replacement while Desktop supervises the proxy, even for a separate npm/Bun install;
+quit OpenCodex first to update that install. An accepted `ocx restart` reports that Desktop
+starts the replacement and waits for it to become healthy. A newer PATH CLI cannot use
+`ocx restart` to replace the app's proxy with its own runtime.
+
+Terminal `ocx stop` still stops the proxy, but Desktop may start it again after a short
+backoff. Use **Stop proxy** or **Quit** in the tray to keep it stopped. Ordinary stop prints
+this reminder on stderr; `ocx stop --json` skips the supervision probe and reminder.
+
+These guards are early warnings in current CLIs and runtimes; older versions can lack them,
+and Windows does not support the supervision probe. A probe that saw Desktop but could not
+finish verification also blocks the operation. Once blocked, a later inconclusive probe
+does not clear it; a check must positively show no Desktop supervision. With no prior
+Desktop evidence, an inconclusive or unsupported probe keeps the existing command behavior.
+Recorded-ownership guards still apply independently.
+
 ## Startup safety on macOS and Linux
 
 Startup safety reports **Desktop app** protection when fresh diagnostics verify

docs-site/src/content/docs/ko/guides/desktop-app.md

@@ -59,6 +59,28 @@ status에 표시되는 데스크톱 안내를 따르세요. 실행 관계 확인
 Linux deb 패키지에서 `/usr/bin/ocx`입니다. 해당 실행 파일에 `status`를 붙여
 앱의 프록시 상태를 확인할 수 있습니다. Windows에서는 supervision 감지를 지원하지 않습니다.
 
+CLI가 Desktop의 프록시 감독을 감지하면 `ocx service install`, `repair`, `start`,
+`restart`는 서비스를 변경하기 전에 중단됩니다. 기록된 소유권이나 확인된 로그인
+등록이 없어도 적용됩니다. CLI로 시작 관리를 옮기려면 OpenCodex를 종료한 뒤
+`ocx service install`을 실행하세요. 중복 `ocx start`는 Desktop 감독자를 표시합니다.
+
+앱 번들은 트레이의 **Check for Updates…**로 업데이트하세요. Desktop이 프록시를
+감독하는 동안 `ocx update`는 별도로 설치한 npm/Bun 패키지도 교체하지 않습니다.
+해당 설치를 업데이트하려면 OpenCodex를 먼저 종료하세요. 수락된 `ocx restart`는
+Desktop이 교체 프록시를 시작한다고 알리고 정상 작동 확인을 기다립니다. 더 최신인
+PATH CLI도 `ocx restart`로 앱의 프록시를 자기 설치의 런타임으로 교체할 수 없습니다.
+
+터미널의 `ocx stop`은 프록시를 중지하지만 Desktop이 짧은 대기 후 다시 시작할 수
+있습니다. 계속 중지하려면 트레이의 **Stop proxy** 또는 **Quit**을 사용하세요.
+일반 stop은 이 안내를 stderr에 표시하고, `ocx stop --json`은 감독 검사와 안내를 생략합니다.
+
+이 가드는 현재 CLI와 런타임이 제공하는 조기 경고입니다. 이전 버전에는 없을 수 있으며
+Windows에서는 감독 검사를 지원하지 않습니다. 검사 중 Desktop을 발견했지만 확인을
+완료하지 못한 경우에도 작업을 차단합니다. 한 번 차단되면 이후의 불확실한 검사로는
+해제되지 않으며, Desktop 감독이 없다는 사실이 확인되어야 합니다. 앞서 Desktop을
+발견하지 않았다면 불확실하거나 지원되지 않는 검사는 기존 명령 동작을 유지합니다.
+기록된 소유권에 따른 기존 거부 검사는 별도로 적용됩니다.
+
 ## 트레이에서 사용량 보기
 
 macOS와 Windows에서는 트레이 아이콘을 클릭하면 작은 사용량 창이 열립니다. 트레이의 **Show usage**로도 열 수 있으며, 트레이 클릭 이벤트를 전달하지 않는 Linux 데스크톱에서도 사용할 수 있습니다. Linux에서는 트레이 아이콘이 표시되지 않는 환경을 포함해 시작할 때 대시보드가 열립니다.

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);
+    },
+  });
+}

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);