fix(cli): guard standalone update restart with exact replacement verification

devlog/_plan/261004_cli_update_restart/000_plan.md

@@ -0,0 +1,24 @@
+# Guarded update restart
+
+A newer CLI should be able to replace an older standalone proxy while preserving target ownership and confirming the exact launched replacement. This unit refines the public proposal in #6548; supervised cases remain explicit limitations until their replacement identity can be established.
+
+- Archetype: satisfy-spec, one cohesive implementation cycle (wp1).
+- Trigger: next-release replacement of public PR #6548 at fe3cf0aa823afd4144ab240191939ec6145b1c45.
+- Goal: attributed draft PR targeting dev with focused lifecycle tests, independent review and current-head CI evidence.
+- Non-goals: merge, source closure, release, installed-runtime operations, account changes, provider calls, version changes or native stacks.
+- Verifiers: focused Bun tests, typecheck, structure/privacy/layout/ratchet gates; docs build for changed public prose. Full/changed local suites are impractical alongside concurrent release/lane work; hosted CI supplies wider evidence.
+- Stop: publish reviewable focused change, account for source coverage, fix applicable defects or bound missing native/hosted evidence in draft.
+- Evidence: ignored scratch holds investigation, review and test receipts. Public prose records only the already-public feature and published outcomes.
+- Outcomes: DONE means this delivery scope is met, not merged or all native environments validated. Unresolved ownership or required scope expansion remains explicit.
+- Escalation: changes outside CLI orchestration/tests/docs require scope review. No token/cost/time limit was specified; no paid upstream probes are allowed.
+
+Base: dev 0818ea1812a028e1c14cd0b0511b44863407bc52. Source author: agentHits, 140916359+agentHits@users.noreply.github.com. Source consists of one commit and three files, with no native stack membership observed.
+
+Baseline: 44 tests pass across system-restart-client and cli-version-skew after frozen dependency installation. Original public review requests handling failed stop, missing replacement version and behavioral regressions.
+
+Current owner map: CLI index composes system-restart-client and tray-proxy; process-state owns runtime records; ownership-mutation-lease owns cooperative lifecycle serialization; proxy-liveness owns attestation/health; stop-approval owns settlement patterns; structure/runtime.md and public reference/cli/lifecycle.md describe lifecycle behavior.
+
+The no-code alternatives do not deliver the requested newer-install restart. Existing unrestricted stop/start orchestration cannot satisfy the new target contract. Reuse the existing owner primitives and place the narrow orchestration beside the CLI instead of enlarging its index.
+
+Architect consultation: Zeno (01a10493-8767-7422-8098-e28643decd60) proposed D1–D6. Main accepted eligibility, preserved snapshot, confirmed stop and exact replacement requirements; amended stop transport and child admission. Same architect reflected on the concrete scratch plan and returned ALIGNED, with transport/runtime evidence remaining implementation acceptance obligations. Independent audit follows. Family-level model independence is not claimed; the requested leaf model is gpt-6.1-sol.
+The independent plan audit identified two lifecycle gaps; main amended the handoff and terminal result requirements. The architect rechecked D5/D6 and returned ALIGNED. Security analysis and detailed review remain in scratch.

devlog/_plan/261004_cli_update_restart/010_delivery.md

@@ -0,0 +1,7 @@
+# wp1 — Publish the CLI restart replacement
+
+One implementation cycle produces an ordinary draft PR against dev. Preserve the newer-CLI upgrade intent and proxy-newer/incomparable refusal from #6548. Add focused lifecycle regression coverage, keep index composition minimal, and synchronize runtime and user lifecycle documentation.
+
+The scoped implementation and security audit remain in ignored scratch until the patch is public, per repository policy. Public delivery records source coverage, attribution, verification commands and native/live limits. No source PR is closed by this lane.
+
+Expected changed areas: src/cli restart siblings and index wiring; tests/cli lifecycle regressions; both test-layout registries; structure/runtime.md; docs-site lifecycle reference. No integration branch or version file changes.

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

@@ -101,6 +101,19 @@ Missing or unreadable evidence blocks the guarded stop.
 
 ### `ocx restart`
 
+When this CLI is newer than an attested standalone POSIX proxy, restart can stop the old
+installation and launch this one. This guarded update requires an unclaimed physical home,
+a detached proxy whose parent is PID 1, no installed or active service, and a known CLI version.
+The stop uses the same connection that proved the old proxy's identity. The command launches
+once only after confirmed shutdown, then requires the exact child PID, endpoint, fresh identity
+proof and matching version. Missing version, uncertain stop, timeout or an unexpected replacement
+reports failure without another stop or start. If the runtime this CLI would launch is still the
+small placeholder an in-place npm install leaves before its postinstall, restart refuses before
+stopping anything; after a confirmed stop it waits for the runtime within the same deadline and
+launches nothing if it does not arrive. Windows, foreground, desktop-supervised, service,
+connected-client and sibling runtimes do not use this update path; use their owning lifecycle
+controls. A newer proxy or incomparable version still refuses an in-place downgrade.
+
 When a proxy is running, ask that exact attested PID and port to restart in place, wait for its
 normal drain, and verify a different runtime PID on the same port. Managed routing and service
 supervision stay installed throughout; an uncertain request is observed rather than replayed as a
@@ -122,7 +135,7 @@ the previous attempt never launched a child or the launched child is known to ha
 If a launch may still be running, restart reports the original failure without starting
 a second proxy, even when a health probe finds nothing. When an accepted restart never publishes a replacement, the command re-observes
 once before giving up — a proxy that crashed mid-restart reads absent and is started fresh,
-while a replacement that landed just past the shortened replacement wait still proves success within the overall observation deadline. A live target is
+while a replacement that landed just past the shortened replacement wait still proves success within the overall observation deadline. Outside the guarded newer-CLI update path, a live target is
 never stopped to make room, so a stale-but-listening process can not be replaced by a second
 proxy racing it for the port.
 Every failed start attempt is followed by a beat and a strong re-observation before the

scripts/test-layout/layout.json

@@ -2,6 +2,10 @@
   "version": 1,
   "root": "tests",
   "explicit": {
+    "cli-update-restart.test.ts": "cli",
+    "cli-update-restart-child.test.ts": "cli",
+    "cli-update-restart-transport.test.ts": "cli",
+    "cli-update-restart-home.test.ts": "cli",
     "codex-shim-overlay.test.ts": "codex-integration",
     "codex-shim-migration.test.ts": "codex-integration",
     "codex-shim-overlay-transaction.test.ts": "codex-integration",

src/cli/index.ts

@@ -8,6 +8,9 @@ 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 { admitUpdateRestartChild } from "./update-restart-child";
+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";
 
@@ -201,6 +204,7 @@ async function refreshOwnedRaycastCatalog(
   }
 }
 
+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.
@@ -372,6 +376,7 @@ async function findProxyOwnerBeforeJournalRecovery(
 }
 
 async function handleStart(options: { block?: boolean } = {}) {
+  updateRestartChild?.check();
   // A supervised service child defers to a foreign recorded owner before doing
   // anything else. 'ocx service start' refuses this activation path already, but
   // the process managers below it — the Windows boot wrapper's restart loop and
@@ -467,6 +472,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     },
   });
 
+  updateRestartChild?.check();
   const clientState = readClientConnectionState();
   if (clientState.kind === "invalid" || clientState.kind === "mismatched") {
     throw new Error(`client startup refused: ${clientState.reason}`);
@@ -551,7 +557,17 @@ async function handleStart(options: { block?: boolean } = {}) {
         let server: ReturnType<typeof serverModule.startServer>;
         for (let attempt = 0; ; attempt++) {
           try {
+            if (updateRestartChild && siblingStart) throw new Error("update_restart_sibling_refused");
+            updateRestartChild?.check(port, loadConfig().hostname ?? "");
             server = serverModule.startServer(port, { localAttestationSecret, readinessGate });
+            if (updateRestartChild) {
+              try { updateRestartChild.check(port, server.hostname); }
+              catch (error) {
+                try { await server.stop(true); }
+                catch (rollback) { throw new StartOwnershipRollbackUncertainError([error, rollback]); }
+                throw error;
+              }
+            }
             break;
           } catch (err) {
             try { await serverModule.waitForFailedStartRollback(err); }
@@ -579,14 +595,14 @@ async function handleStart(options: { block?: boolean } = {}) {
         }
         return { server, serverModule, port, readinessGate, localAttestationSecret, config };
       },
-      writePid: () => writePid(process.pid),
-      writeRuntime: bound => writeRuntimePort({
+      writePid: () => { updateRestartChild?.check(); writePid(process.pid); },
+      writeRuntime: bound => { updateRestartChild?.check(bound.port, bound.config.hostname ?? ""); writeRuntimePort({
         pid: process.pid,
         port: bound.port,
         hostname: bound.config.hostname,
         attestationSecret: bound.localAttestationSecret,
         ...siblingRuntimeField(),
-      }),
+      }); updateRestartChild?.complete(); },
       stopBound: bound => bound.server.stop(true),
       removeRuntime: () => removeRuntimePortIfPidIs(process.pid),
       removePid: () => removePidIfValueIs(process.pid),
@@ -947,6 +963,15 @@ async function handleProxyRestart(
       findLive: () => findLiveProxy({ deadlineAt: end, attempts: 2, acceptPackageTreeFenced: true }), expired: () => Date.now() >= end,
     })),
   });
+  if (!result.ok && result.phase === "request" && result.error instanceof UpdateRestartRequired) {
+    const candidate = result.error.candidate();
+    console.log(`🔄 Running proxy ${candidate.target.version} is older than this CLI (${candidate.cliVersion}); restarting it from the current installation...`);
+    const update = await restartFromCurrentInstallation(candidate, deadlineAt, detachedStartEnvironment());
+    if (update.ok) console.log(`✅ Proxy updated to ${update.live.version} (PID ${update.live.pid}).`);
+    else console.error(`❌ ${describeUpdateRestartFailure(update.code)} (${update.code})`);
+    process.exitCode = update.ok ? 0 : 1;
+    return update.ok;
+  }
   if (!result.ok) reportRestartFailure(result);
   process.exitCode = result.ok ? 0 : 1;
   return result.ok;

src/cli/system-restart-client.ts

@@ -26,6 +26,8 @@ import {
 import type { ProxyRestartRequestOutcome } from "./tray-proxy";
 import { packageVersion } from "./help";
 import { computeVersionSkew } from "./version-skew";
+import { readUpdateRestartHome } from "./update-restart-home";
+import { UpdateRestartRequired } from "./update-restart-candidate";
 
 export const SYSTEM_RESTART_REQUEST_TIMEOUT_MS = 5_000;
 export const SYSTEM_RESTART_ATTESTATION_TIMEOUT_MS = 4_000;
@@ -38,6 +40,7 @@ export interface BoundSystemRestartDeps {
   now?: () => number;
   /** Invoking CLI version for the skew guard; defaults to this bundle's package version. */
   cliVersion?: string;
+  readUpdateHome?: typeof readUpdateRestartHome;
 }
 
 function rejected(code: string): ProxyRestartRequestOutcome {
@@ -90,6 +93,8 @@ export async function requestBoundSystemRestart(
     return rejected("restart_target_runtime_mismatch");
   }
 
+  let updateHome: ReturnType<typeof readUpdateRestartHome> | undefined;
+  try { updateHome = (deps.readUpdateHome ?? readUpdateRestartHome)(); } catch { /* normal in-place restart remains available */ }
   const attestationBudget = remaining(deadlineAt, now, SYSTEM_RESTART_ATTESTATION_TIMEOUT_MS);
   if (attestationBudget <= 0) return rejected("restart_deadline_expired");
 
@@ -143,9 +148,9 @@ 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 cliVersion = deps.cliVersion ?? ownCliVersion();
+  const skew = computeVersionSkew(cliVersion, proxyVersion);
+  if (skew.skewed && skew.relation !== "cli-newer") return rejected("restart_version_skew");
 
   let observed: LiveProxy | null;
   try {
@@ -154,6 +159,18 @@ export async function requestBoundSystemRestart(
     return rejected("restart_target_recheck_failed");
   }
   if (!sameRestartTarget(target, observed)) return rejected("restart_target_changed");
+  if (skew.relation === "cli-newer") {
+    if (!updateHome) return rejected("update_restart_home_unverified");
+    const current = readRuntime(target.pid);
+    if (!current || current.pid !== runtime.pid || current.port !== runtime.port
+      || current.hostname !== runtime.hostname || current.attestationSecret !== runtime.attestationSecret) {
+      return rejected("restart_target_changed");
+    }
+    return { accepted: false, uncertain: false, error: new UpdateRestartRequired({
+      target: { ...target, pid: target.pid, version: proxyVersion },
+      runtime: { ...runtime, attestationSecret: runtime.attestationSecret }, cliVersion, home: updateHome,
+    }) };
+  }
 
   const capability = createSystemRestartCapability(
     runtime.attestationSecret,

src/cli/update-restart-candidate.ts

@@ -0,0 +1,21 @@
+import type { RuntimePortState } from "../config/process-state";
+import type { LiveProxy } from "../server/proxy-liveness";
+
+import type { UpdateRestartHome } from "./update-restart-home";
+
+export interface UpdateRestartCandidate {
+  home: UpdateRestartHome;
+  target: LiveProxy & { pid: number };
+  runtime: RuntimePortState & { attestationSecret: string };
+  cliVersion: string;
+}
+
+/** Private in-process evidence; diagnostics and JSON never expose the proof key. */
+export class UpdateRestartRequired extends Error {
+  #candidate: UpdateRestartCandidate;
+  constructor(candidate: UpdateRestartCandidate) {
+    super("restart_version_skew_cli_newer");
+    this.#candidate = candidate;
+  }
+  candidate(): UpdateRestartCandidate { return this.#candidate; }
+}

src/cli/update-restart-child.ts

@@ -0,0 +1,81 @@
+import { existsSync } from "node:fs";
+import { getRuntimePortPath, readRuntimePort } from "../config/process-state";
+import { packageVersion } from "../lib/package-version";
+import { parseStrictSemver } from "../lib/strict-semver";
+import { acquireOwnershipMutationLease, OWNERSHIP_MUTATION_LEASE_TOKEN_ENV } from "../service/ownership-mutation-lease.mjs";
+import { serviceStatePaths } from "../service/state";
+import { assertUpdateRestartConfiguration, assertUpdateRestartHome, type UpdateRestartHome } from "./update-restart-home";
+
+export const UPDATE_RESTART_CHILD_ENV = "OCX_UPDATE_RESTART_CHILD";
+export interface UpdateRestartChildMarker { home: UpdateRestartHome; version: string; port: number; hostname: string; deadlineAt: number }
+export interface UpdateRestartChildGuard { check(port?: number, hostname?: string): void; complete(): void }
+
+function parseMarker(raw: string): UpdateRestartChildMarker {
+  if (raw.length > 8192) throw new Error("update_restart_child_marker_invalid");
+  const value = JSON.parse(raw) as UpdateRestartChildMarker;
+  if (!value || !Number.isSafeInteger(value.deadlineAt) || !Number.isInteger(value.port)
+    || typeof value.hostname !== "string" || value.port < 1 || value.port > 65535 || typeof value.version !== "string"
+    || value.version === "0.0.0" || !parseStrictSemver(value.version) || !value.home
+    || !Number.isSafeInteger(value.home.revision)) throw new Error("update_restart_child_marker_invalid");
+  for (const directory of [value.home.config, value.home.codex]) {
+    if (!directory || typeof directory.path !== "string" || !directory.path
+      || !Number.isSafeInteger(directory.dev) || !Number.isSafeInteger(directory.ino)) {
+      throw new Error("update_restart_child_marker_invalid");
+    }
+  }
+  return value;
+}
+
+export interface UpdateRestartChildIo {
+  env?: NodeJS.ProcessEnv;
+  now?: () => number;
+  version?: () => string;
+  checkHome?: (home: UpdateRestartHome) => void;
+  acquire?: (waitMs: number) => { release(): void };
+  onExit?: (release: () => void) => void;
+  checkState?: (marker: UpdateRestartChildMarker) => void;
+  armDeadline?: (remainingMs: number) => () => void;
+}
+
+/** Admit the replacement before CLI preflight; custody belongs to this child PID. */
+export function admitUpdateRestartChild(argv: string[], io: UpdateRestartChildIo = {}): UpdateRestartChildGuard | undefined {
+  const env = io.env ?? process.env;
+  const raw = env[UPDATE_RESTART_CHILD_ENV];
+  if (raw === undefined) return undefined;
+  delete env[UPDATE_RESTART_CHILD_ENV];
+  delete env[OWNERSHIP_MUTATION_LEASE_TOKEN_ENV];
+  const marker = parseMarker(raw);
+  if (argv.length !== 3 || argv[0] !== "start" || argv[1] !== "--port" || argv[2] !== String(marker.port)) {
+    throw new Error("update_restart_child_command_changed");
+  }
+  const now = io.now ?? Date.now;
+  const check = (port = marker.port, hostname = marker.hostname) => {
+    if (now() >= marker.deadlineAt) throw new Error("update_restart_deadline_expired");
+    const bindHost = (host: string) => !host.trim() || /^localhost\.?$/i.test(host.trim()) ? "127.0.0.1" : host.trim();
+    if (port !== marker.port || bindHost(hostname) !== bindHost(marker.hostname) || (io.version ?? packageVersion)() !== marker.version) throw new Error("update_restart_child_identity_changed");
+    (io.checkHome ?? assertUpdateRestartHome)(marker.home);
+    (io.checkState ?? (expected => {
+      assertUpdateRestartConfiguration(expected.hostname);
+      const current = readRuntimePort();
+      if (existsSync(getRuntimePortPath()) && (!current || current.pid !== process.pid
+        || current.port !== expected.port || current.siblingOfPort !== undefined)) {
+        throw new Error("update_restart_competing_runtime");
+      }
+    }))(marker);
+  };
+  check();
+  const lease = (io.acquire ?? (waitMs => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs })))(Math.min(2000, marker.deadlineAt - now()));
+  let released = false;
+  let cancelDeadline: (() => void) | undefined;
+  const release = () => { if (!released) { released = true; cancelDeadline?.(); lease.release(); } };
+  try {
+    check();
+    cancelDeadline = (io.armDeadline ?? (remainingMs => {
+      const timer = setTimeout(() => process.exit(1), remainingMs);
+      timer.unref();
+      return () => clearTimeout(timer);
+    }))(marker.deadlineAt - now());
+    (io.onExit ?? (callback => { process.once("exit", callback); }))(release);
+    return { check, complete: () => { check(); release(); } };
+  } catch (error) { release(); throw error; }
+}