fix(cli): restart via stop/start when CLI is newer than proxy

docs-site/src/content/docs/reference/cli/lifecycle.md

@@ -117,6 +117,11 @@ If a live listener cannot be attested to a runtime PID (including a pre-update p
 closed without an `ensure` or stop/start fallback. After confirming ownership, use `ocx stop` then
 `ocx start` for a standalone proxy. For a service-managed proxy, use `ocx stop` followed by
 `ocx service start` so supervision is restored.
+When the invoking CLI is newer than the attested proxy, restart does not respawn in place (that
+would keep serving the old build). Instead it carries the attested PID and port through a guarded
+stop validated under the ownership lease — refusing if the target changed — and starts the
+current installation only after the target shows stopped, accepting the replacement only when it
+serves this CLI version on the expected port.
 One invocation re-observes transient discovery races. A failed start is retried only when
 the previous attempt never launched a child or the launched child is known to have exited.
 If a launch may still be running, restart reports the original failure without starting

scripts/test-layout/layout.json

@@ -57,7 +57,7 @@
     "low-quota-protection.test.ts": "codex-integration",
     "responses-compaction-recovery.test.ts": "responses", "responses-canonical-nonstream.test.ts": "responses", "compaction-recovery-settings.test.ts": "config", "responses-compaction-recovery-policy.test.ts": "responses", "plugin-loader.test.ts": "lib", "plugin-upstream-hooks.test.ts": "lib",
     "cli-kiro-auto-selection.test.ts": "cli", "codebuddy-live-models.test.ts": "providers", "kiro-auto-selection.test.ts": "providers/kiro", "kiro-quota-metrics.test.ts": "providers/kiro", "management-provider-request-pacing.test.ts": "server",
-    "desktop-supervised-restart.test.ts": "clients", "cli-restart-handoff.test.ts": "cli",
+    "desktop-supervised-restart.test.ts": "clients", "cli-restart-handoff.test.ts": "cli", "restart-update-coordinator.test.ts": "cli",
     "restart-replacement.test.ts": "server", "deepseek-artifact-tool-schema.test.ts": "providers",
     "client-config-export-output-limit.test.ts": "config", "responses-skills-snapshot.test.ts": "responses", "responses-code-mode-mcp-direct.test.ts": "responses", "local-read-response-proof.test.ts": "server",
     "link-relay-bound-transport.test.ts": "clients", "claude-desktop-system-proxy.test.ts": "claude-integration", "codex-config-drift-heal.test.ts": "codex-integration",

src/cli/index.ts

@@ -89,6 +89,7 @@ import {
   type ProxyRestartStartOutcome,
 } from "./tray-proxy";
 import { requestBoundSystemRestart } from "./system-restart-client";
+import { runRestartUpdate, readResolveJson, type RestartUpdateResult } from "./restart-update-coordinator";
 import { installCrashGuards } from "../lib/crash-guard";
 import { SpendLedgerOwnerError } from "../lib/spend-ledger-owner";
 import { redactUrlForLog } from "../lib/redact";
@@ -911,7 +912,7 @@ function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: false }>
     if (code === "restart_capability_unsupported") {
       console.error("❌ The running proxy predates process-bound restart support; no unsafe fallback was attempted.");
       console.error("   After confirming this home owns the proxy, run `ocx stop` and then `ocx start` once.");
-    } else if (code === "restart_version_skew") {
+    } else if (code === "restart_version_skew" || code === "restart_version_skew_cli_newer") {
       console.error("❌ The running proxy reports a different OpenCodex version than this CLI; restarting in place would respawn the old installation.");
       console.error("   Run `ocx stop` and then `ocx start` from this installation instead.");
     } else if (code === "restart_package_tree_unsettled") {
@@ -925,17 +926,49 @@ function reportRestartFailure(result: Extract<ProxyRestartResult, { ok: false }>
     console.error("❌ Proxy was not running and the fallback start did not become healthy.");
   }
 }
+/** Update restart: the CLI is newer than the attested proxy, so stop the old build
+ * and start the current installation instead of respawning the old one in place.
+ * The attested PID/port travels into runRestartUpdate, which revalidates it under
+ * the ownership lease through the guarded-stop mechanism and refuses on any
+ * owner change instead of stopping blindly. Other skew directions keep refusing
+ * in reportRestartFailure. */
+function reportRestartUpdateRefusal(result: Extract<RestartUpdateResult, { ok: false }>): void {
+  switch (result.reason) {
+    case "target-changed":
+      console.error(`❌ Refusing the update restart: the attested proxy changed before the stop (${result.detail ?? "identity mismatch"}); nothing was stopped.`);
+      break;
+    case "stop-refused":
+      console.error(`❌ Refusing the update restart: the guarded stop declined (${result.detail ?? "ownership changed"}); nothing was stopped.`);
+      break;
+    case "stop-failed":
+      console.error(`❌ Update restart failed while stopping the old proxy (${result.detail ?? "unknown error"}).`);
+      break;
+    case "target-not-confirmed-stopped":
+      console.error("❌ Refusing the update restart: the old proxy did not confirm stopped; not starting a second proxy over it.");
+      break;
+    case "start-failed":
+      console.error("❌ Update restart stopped the old proxy but the new proxy did not start. Run `ocx start` to recover.");
+      break;
+    case "replacement-unverified":
+      console.error(`❌ Update restart could not verify a replacement serving this CLI (${result.detail ?? "unhealthy"}). Check ocx status before retrying.`);
+      break;
+  }
+}
 async function handleProxyRestart(
   startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>,
 ): Promise<boolean> {
   const deadlineAt = Date.now() + PROXY_RESTART_OBSERVE_MS;
+  const stashed: { previous: ProxyRestartLive | null } = { previous: null };
   const result = await runProxyRestart({
     findLive: () => discoverStableProxyForRestart({
       findLive: () => findLiveProxy({ deadlineAt, attempts: 2, acceptPackageTreeFenced: true }),
       expired: () => Date.now() >= deadlineAt,
     }),
     startWhenStopped,
-    requestInPlaceRestart: previous => requestBoundSystemRestart(previous, deadlineAt),
+    requestInPlaceRestart: previous => {
+      stashed.previous = previous;
+      return requestBoundSystemRestart(previous, deadlineAt);
+    },
     waitForReplacement: previous => waitForProxyReplacement(previous, deadlineAt - RESTART_REOBSERVE_RESERVE_MS, end => findLiveProxy({ deadlineAt: end })),
     reobserveAfterReplacement: previous => reobserveRestartReplacement(previous, deadlineAt, end =>
       discoverStableProxyForRestart({
@@ -947,7 +980,34 @@ async function handleProxyRestart(
       findLive: () => findLiveProxy({ deadlineAt: end, attempts: 2, acceptPackageTreeFenced: true }), expired: () => Date.now() >= end,
     })),
   });
-  if (!result.ok) reportRestartFailure(result);
+  if (!result.ok) {
+    const code = result.phase === "request" && result.error instanceof Error ? result.error.message : "";
+    const previous = stashed.previous;
+    if (result.phase === "request" && code === "restart_version_skew_cli_newer"
+      && previous !== null && previous.pid !== null) {
+      console.log(`🔄 Running proxy is older than this CLI (${packageVersion()}); restarting via guarded stop/start from the current installation...`);
+      const updated = await runRestartUpdate(
+        { pid: previous.pid, port: previous.port },
+        deadlineAt,
+        {
+          findLive: () => findLiveProxy({ deadlineAt, attempts: 2 }),
+          resolve: readResolveJson,
+          stopGuarded: approval => handleStop(approval),
+          startWhenStopped,
+          cliVersion: packageVersion(),
+        },
+      );
+      if (updated.ok) {
+        console.log(`✅ Proxy updated and running on ${updated.live.version ?? packageVersion()} (PID ${updated.live.pid ?? "unknown"}).`);
+        process.exitCode = 0;
+        return true;
+      }
+      reportRestartUpdateRefusal(updated);
+      process.exitCode = 1;
+      return false;
+    }
+    reportRestartFailure(result);
+  }
   process.exitCode = result.ok ? 0 : 1;
   return result.ok;
 }

src/cli/restart-update-coordinator.ts

@@ -0,0 +1,137 @@
+/**
+ * Identity-carrying coordinator for the CLI-newer update restart.
+ *
+ * An in-place restart respawns the live process from its own installation, so a
+ * restart accepted from a newer CLI would keep serving the old build. Instead of
+ * refusing (or stopping whatever happens to be live), this coordinator carries
+ * the attested restart identity (PID/port) through every step and revalidates it
+ * under the ownership lease through the existing guarded-stop mechanism
+ * (runApprovedStop): a changed, unknown, or non-runtime owner refuses before any
+ * stop is attempted, the start runs only after the intended target shows
+ * stopped, and the replacement is accepted only when it serves this exact CLI
+ * version on the expected port. Every boundary is injected for tests; no real
+ * service is touched by the regression suite.
+ */
+import type { LiveProxy } from "../server/proxy-liveness";
+import { runResolve, type ResolveJson } from "./resolve";
+import type { StopApproval } from "./stop-approval";
+import type { StopOutcome } from "./stop-report";
+import type { ProxyRestartStartOutcome } from "./tray-proxy";
+
+/** Attested restart identity observed before the CLI-newer refusal. */
+export interface RestartUpdateTarget {
+  pid: number;
+  port: number;
+}
+
+export type RestartUpdateRefusal =
+  | "target-changed"
+  | "stop-refused"
+  | "stop-failed"
+  | "target-not-confirmed-stopped"
+  | "start-failed"
+  | "replacement-unverified";
+
+export type RestartUpdateResult =
+  | { ok: true; live: LiveProxy }
+  | { ok: false; reason: RestartUpdateRefusal; detail?: string };
+
+export interface RestartUpdateIo {
+  findLive: () => Promise<LiveProxy | null>;
+  resolve: () => Promise<ResolveJson | null>;
+  stopGuarded: (approval: StopApproval) => Promise<StopOutcome>;
+  startWhenStopped: (recoveringLiveRestart: boolean) => Promise<ProxyRestartStartOutcome>;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  cliVersion: string;
+}
+
+/** Bounded re-observation shared by the stopped and replacement waits. */
+async function pollLive(
+  findLive: () => Promise<LiveProxy | null>,
+  deadlineAt: number,
+  now: () => number,
+  sleep: (ms: number) => Promise<void>,
+  accept: (live: LiveProxy | null) => boolean,
+): Promise<LiveProxy | null> {
+  for (;;) {
+    const live = await findLive();
+    if (accept(live)) return live;
+    const remaining = deadlineAt - now();
+    if (remaining <= 0) return null;
+    await sleep(Math.min(250, remaining));
+  }
+}
+
+/** Production resolve reader: one JSON document, null on any other outcome. */
+export async function readResolveJson(): Promise<ResolveJson | null> {
+  const lines: string[] = [];
+  const code = await runResolve({ json: true }, {
+    stdout: { log: (line: string) => { lines.push(line); } },
+    stderr: { error: () => {} },
+  });
+  if (code !== 0 || lines.length !== 1) return null;
+  try {
+    return JSON.parse(lines[0] as string) as ResolveJson;
+  } catch {
+    return null;
+  }
+}
+
+const STOPPED_CONFIRM_BUDGET_MS = 10_000;
+
+export async function runRestartUpdate(
+  target: RestartUpdateTarget,
+  deadlineAt: number,
+  io: RestartUpdateIo,
+): Promise<RestartUpdateResult> {
+  const now = io.now ?? Date.now;
+  const sleep = io.sleep ?? Bun.sleep;
+  const fail = (reason: RestartUpdateRefusal, detail?: string): RestartUpdateResult =>
+    ({ ok: false, reason, ...(detail === undefined ? {} : { detail }) });
+  const resolved = await io.resolve();
+  if (resolved === null) return fail("target-changed", "the runtime could not be re-resolved");
+  const liveness = resolved.liveness;
+  if (liveness.status !== "live" || liveness.pid === null || liveness.port === null) {
+    return fail("target-changed", "the approved runtime is no longer live");
+  }
+  if (liveness.pid !== target.pid || liveness.port !== target.port) {
+    return fail("target-changed", "the live PID/port no longer match the attested restart target");
+  }
+  if (liveness.source !== "runtime") {
+    return fail("target-changed", "the live runtime is no longer attested");
+  }
+  if (liveness.role === "client") {
+    return fail("target-changed", "the runtime now routes as a client");
+  }
+  const approval: StopApproval = {
+    pid: target.pid,
+    port: target.port,
+    hostname: liveness.hostname ?? "",
+    configHome: resolved.configHome,
+    cliVersion: io.cliVersion,
+    compatibilityToken: resolved.takeover.kind === "supported" ? resolved.takeover.token : "",
+  };
+  const stopped = await io.stopGuarded(approval);
+  if (!stopped.ok) {
+    const refused = stopped.summary.outcome === "approval-changed";
+    return fail(refused ? "stop-refused" : "stop-failed", stopped.summary.message);
+  }
+  const stoppedDeadline = Math.min(deadlineAt, now() + STOPPED_CONFIRM_BUDGET_MS);
+  const gone = await pollLive(io.findLive, stoppedDeadline, now, sleep,
+    live => live === null || live.port !== target.port);
+  if (gone === null && now() >= stoppedDeadline) {
+    return fail("target-not-confirmed-stopped", "the expected port still answers after the stop");
+  }
+  const started = await io.startWhenStopped(true);
+  if (started.status !== "started") {
+    return fail("start-failed", "the replacement proxy did not start");
+  }
+  const replacement = await pollLive(io.findLive, deadlineAt, now, sleep,
+    live => live !== null && live.source === "runtime" && live.port === target.port
+      && live.pid !== null && live.version === io.cliVersion);
+  if (replacement === null) {
+    return fail("replacement-unverified", "no healthy replacement serving this CLI version appeared in time");
+  }
+  return { ok: true, live: replacement };
+}

src/cli/system-restart-client.ts

@@ -143,8 +143,15 @@ export async function requestBoundSystemRestart(
   const proxyVersion = fenced
     ? body.installedVersion as string
     : typeof body.version === "string" ? body.version : undefined;
-  if (computeVersionSkew(deps.cliVersion ?? ownCliVersion(), proxyVersion).skewed) {
-    return rejected("restart_version_skew");
+  const skew = computeVersionSkew(deps.cliVersion ?? ownCliVersion(), proxyVersion);
+  if (skew.skewed) {
+    // cli-newer means this installation already holds the update the running proxy
+    // lacks: an in-place respawn would keep serving the old build (#4522). The
+    // caller carries the attested identity into runRestartUpdate
+    // (restart-update-coordinator.ts), which revalidates it under the ownership
+    // lease through the guarded-stop mechanism instead of refusing. Other skew
+    // directions (proxy-newer, incomparable) still refuse.
+    return rejected(skew.relation === "cli-newer" ? "restart_version_skew_cli_newer" : "restart_version_skew");
   }
 
   let observed: LiveProxy | null;