@bitkyc08/opencodex 2.80.0 → 2.82.0

package/src/cli/update-restart-home.ts

@@ -2,12 +2,15 @@ import { realpathSync, statSync } from "node:fs";
 import { readClientConnectionState } from "../client/state";
 import { readConfigDiagnostics } from "../config/diagnostics";
 import { getConfigDir } from "../config/paths";
-import { currentCodexHome, resolveServiceOwnership, resolveServiceState } from "../service/state";
+import { currentCodexHome } from "../service/state";
+import { captureUpdateRestartServiceRecord, type UpdateRestartServiceRecord, type UpdateRestartServiceRecordDeps } from "./update-restart-service-record";
+import { probeUpdateRestartSupervision, type UpdateRestartSupervisionDeps } from "./update-restart-supervision";
 
 export interface UpdateRestartHome {
   config: { path: string; dev: number; ino: number };
   codex: { path: string; dev: number; ino: number };
   revision: number;
+  serviceRecord: UpdateRestartServiceRecord;
 }
 
 function physicalDirectory(path: string): UpdateRestartHome["config"] {
@@ -17,17 +20,32 @@ function physicalDirectory(path: string): UpdateRestartHome["config"] {
   return { path: canonical, dev: stat.dev, ino: stat.ino };
 }
 
-/** Only an unclaimed standalone home is eligible for this narrow update path. */
-export function readUpdateRestartHome(): UpdateRestartHome {
-  const state = resolveServiceState();
-  const owner = resolveServiceOwnership();
-  if (state.kind !== "none" || owner.kind !== "none") throw new Error("update_restart_owner_unverified");
-  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision };
+export interface UpdateRestartHomeDeps {
+  record?: UpdateRestartServiceRecordDeps;
+  supervision?: UpdateRestartSupervisionDeps;
 }
 
-export function assertUpdateRestartHome(expected: UpdateRestartHome): void {
-  const current = readUpdateRestartHome();
-  if (JSON.stringify(current) !== JSON.stringify(expected)) throw new Error("update_restart_home_changed");
+/** Capture eligibility from the same bytes that supply the frozen fingerprint. */
+export function readUpdateRestartHome(deps: UpdateRestartHomeDeps = {}): UpdateRestartHome {
+  const { serviceRecord, state, owner } = captureUpdateRestartServiceRecord(deps.record);
+  const platform = deps.record?.platform ?? process.platform;
+  if (owner.kind !== "none" || (state.kind === "state" && platform !== "darwin" && platform !== "linux")) {
+    throw new Error("update_restart_owner_unverified");
+  }
+  return { config: physicalDirectory(getConfigDir()), codex: physicalDirectory(currentCodexHome()), revision: owner.revision, serviceRecord };
+}
+
+export function assertUpdateRestartHome(expected: UpdateRestartHome, deadlineAt = Date.now() + 2000, deps: UpdateRestartHomeDeps = {}): void {
+  try {
+    const current = readUpdateRestartHome(deps);
+    if (JSON.stringify(current) !== JSON.stringify(expected)) throw new Error("changed");
+  } catch { throw new Error("update_restart_home_changed"); }
+  if (probeUpdateRestartSupervision(deadlineAt, deps.supervision) !== "inactive") throw new Error("update_restart_supervision_unverified");
+  // Manager commands may yield to an external writer even though this guard is synchronous.
+  try {
+    if (JSON.stringify(readUpdateRestartHome(deps)) !== JSON.stringify(expected)) throw new Error("changed");
+  } catch { throw new Error("update_restart_home_changed"); }
+  if ((deps.supervision?.now ?? Date.now)() >= deadlineAt) throw new Error("update_restart_deadline_expired");
 }
 
 /** Read-only eligibility shared by parent pre-stop and child admission. */

package/src/cli/update-restart-service-record.ts

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync, type BigIntStats } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { plistPath, resolveServiceOwnership, resolveServiceState, serviceStatePaths, type ServiceStateEvidence } from "../service/state";
+import { unitPath } from "../service/systemd";
+import { inspectInstallStateBytes } from "../service/install-state-contract.mjs";
+
+export interface UpdateRestartServiceRecord { schema: 1; digest: string }
+export interface UpdateRestartServiceRecordDeps {
+  platform?: NodeJS.Platform;
+  paths?: () => readonly string[];
+  definitionPath?: () => string;
+  open?: (path: string, flags: number) => number;
+  fstat?: (fd: number) => BigIntStats;
+  read?: (fd: number, buffer: Buffer, offset: number, length: number, position: number) => number;
+  lstat?: (path: string) => BigIntStats;
+}
+/** Maximum bytes per state candidate or platform definition: 1 MiB, including growth during read. */
+export const UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES = 1024 * 1024;
+const READ_CHUNK_BYTES = 64 * 1024;
+const FAILURE = "update_restart_service_record_unverified";
+const hash = (bytes: string | Buffer) => createHash("sha256").update(bytes).digest("hex");
+const metadata = (stat: BigIntStats) => [stat.dev, stat.ino, stat.size, stat.mtimeNs, stat.ctimeNs, stat.mode, stat.uid, stat.gid].map(String);
+const absent = (error: unknown) => !!error && typeof error === "object" && "code" in error && error.code === "ENOENT";
+
+// Canonicalize directories, never the record itself: a record symlink is a refusal.
+function canonicalPath(path: string): string {
+  const parent = dirname(path);
+  try { return join(realpathSync.native(parent), basename(path)); }
+  catch (error) {
+    if (!absent(error) || parent === path) throw new Error(FAILURE);
+    return join(canonicalPath(parent), basename(path));
+  }
+}
+
+function readBoundedRecord(fd: number, read: NonNullable<UpdateRestartServiceRecordDeps["read"]>): Buffer {
+  const chunk = Buffer.alloc(READ_CHUNK_BYTES);
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for (;;) {
+    // At the limit, a one-byte read distinguishes EOF from concurrent growth.
+    const length = Math.min(chunk.length, UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES - total + 1);
+    const count = read(fd, chunk, 0, length, total);
+    if (!Number.isInteger(count) || count < 0 || count > length) throw new Error(FAILURE);
+    if (count === 0) return Buffer.concat(chunks, total);
+    total += count;
+    if (total > UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES) throw new Error(FAILURE);
+    chunks.push(Buffer.from(chunk.subarray(0, count)));
+  }
+}
+
+/** Read all authority/mirror candidates and the platform definition as one frozen record. */
+export function captureUpdateRestartServiceRecord(deps: UpdateRestartServiceRecordDeps = {}) {
+  try {
+    const platform = deps.platform ?? process.platform;
+    const paths = (deps.paths ?? serviceStatePaths)();
+    const definition = platform === "darwin" ? (deps.definitionPath ?? plistPath)()
+      : platform === "linux" ? (deps.definitionPath ?? unitPath)() : undefined;
+    const statPath = deps.lstat ?? (path => lstatSync(path, { bigint: true }));
+    const captures = [...paths, ...(definition ? [definition] : [])].map((path, index) => {
+      const canonical = canonicalPath(path);
+      let before: BigIntStats;
+      try { before = statPath(path); }
+      catch (error) {
+        if (!absent(error)) throw error;
+        return { path, canonical, index, identity: null, bytes: undefined };
+      }
+      if (!before.isFile() || before.isSymbolicLink()) throw new Error(FAILURE);
+      const fd = (deps.open ?? openSync)(path, constants.O_RDONLY | (platform === "win32" ? 0 : constants.O_NOFOLLOW | constants.O_NONBLOCK));
+      try {
+        const statFd = deps.fstat ?? (handle => fstatSync(handle, { bigint: true }));
+        const opened = statFd(fd);
+        const identity = metadata(before);
+        if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino
+          || opened.size < 0n || opened.size > BigInt(UPDATE_RESTART_SERVICE_RECORD_MAX_BYTES)
+          || JSON.stringify(identity) !== JSON.stringify(metadata(opened))) throw new Error(FAILURE);
+        const bytes = readBoundedRecord(fd, deps.read ?? readSync);
+        const after = statFd(fd);
+        if (!after.isFile() || JSON.stringify(identity) !== JSON.stringify(metadata(after))
+          || BigInt(bytes.length) !== after.size) throw new Error(FAILURE);
+        return { path, canonical, index, identity, bytes };
+      } finally { closeSync(fd); }
+    });
+    // Pin path-to-descriptor identity after every read; also confirm each ENOENT again.
+    for (const entry of captures) {
+      let current: BigIntStats;
+      try { current = statPath(entry.path); }
+      catch (error) { if (entry.identity === null && absent(error)) continue; throw error; }
+      if (!current.isFile() || JSON.stringify(metadata(current)) !== JSON.stringify(entry.identity)
+        || canonicalPath(entry.path) !== entry.canonical) throw new Error(FAILURE);
+    }
+    const evidence: ServiceStateEvidence[] = captures.slice(0, paths.length).map(entry => {
+      if (!entry.bytes) return { path: entry.canonical, kind: "absent" };
+      const parsed = inspectInstallStateBytes(entry.canonical, () => entry.bytes!.toString("utf8"));
+      if (parsed.kind !== "valid") throw new Error(FAILURE);
+      return parsed as ServiceStateEvidence;
+    });
+    const state = resolveServiceState(evidence);
+    const owner = resolveServiceOwnership(evidence);
+    if (state.kind === "unknown" || owner.kind === "unknown") throw new Error(FAILURE);
+    const serviceRecord: UpdateRestartServiceRecord = { schema: 1, digest: hash(JSON.stringify({
+      platform, authority: paths.length - 1,
+      records: captures.map(entry => [entry.canonical, entry.index, entry.identity, entry.bytes ? hash(entry.bytes) : null]),
+    })) };
+    return { serviceRecord, state, owner };
+  } catch { throw new Error(FAILURE); }
+}
+
+/** Drift is terminal; never replace the transaction's original digest. */
+export function assertUpdateRestartServiceRecord(expected: UpdateRestartServiceRecord, deps: UpdateRestartServiceRecordDeps = {}) {
+  try {
+    const current = captureUpdateRestartServiceRecord(deps);
+    if (expected.schema !== 1 || current.serviceRecord.digest !== expected.digest) throw new Error(FAILURE);
+    return current;
+  } catch { throw new Error("update_restart_home_changed"); }
+}

package/src/cli/update-restart-supervision.ts

@@ -0,0 +1,96 @@
+import { execFileSync } from "node:child_process";
+import { statSync, type Stats } from "node:fs";
+import { systemdUserBusEnvironment } from "../service/systemd";
+import { assertLiveServiceManagerAllowed } from "../service/guards";
+import { LABEL, TASK } from "../service/state";
+
+export type UpdateRestartSupervision = "inactive" | "active" | "unknown";
+export interface UpdateRestartSupervisorReply { status: number | null; stdout: string; stderr: string }
+export interface UpdateRestartSupervisionDeps {
+  platform?: NodeJS.Platform;
+  now?: () => number;
+  uid?: number;
+  stat?: (path: string) => Pick<Stats, "isFile" | "mode">;
+  environment?: NodeJS.ProcessEnv;
+  exists?: (path: string) => boolean;
+  run?: (command: string, args: string[], timeoutMs: number, environment: NodeJS.ProcessEnv) => UpdateRestartSupervisorReply;
+}
+const PROBE_TIMEOUT_MS = 2000;
+export const UPDATE_RESTART_SYSTEMD_ARGS = ["--user", "show", "-p", "LoadState", "-p", "ActiveState", "-p", "MainPID", "-p", "FragmentPath", "-p", "NeedDaemonReload", TASK];
+
+function run(command: string, args: string[], timeout: number, env: NodeJS.ProcessEnv): UpdateRestartSupervisorReply {
+  assertLiveServiceManagerAllowed("update restart supervision");
+  try {
+    return { status: 0, stdout: execFileSync(command, args, { encoding: "utf8", timeout, env,
+      killSignal: "SIGKILL", maxBuffer: 64 * 1024, stdio: ["ignore", "pipe", "pipe"] }), stderr: "" };
+  } catch (error) {
+    const failure = error as { status?: number | null; signal?: string; code?: string; stdout?: Buffer; stderr?: Buffer };
+    if (failure.signal || failure.code || !Number.isInteger(failure.status)) throw new Error("update_restart_supervision_unverified");
+    return { status: failure.status!, stdout: failure.stdout?.toString() ?? "", stderr: failure.stderr?.toString() ?? "" };
+  }
+}
+
+/** Ignore PATH; usr-merged systemctl symlinks may resolve to a regular trusted-location target. */
+export function resolveUpdateRestartSupervisor(deps: UpdateRestartSupervisionDeps = {}): string | null {
+  const platform = deps.platform ?? process.platform;
+  const paths = platform === "linux" ? ["/usr/bin/systemctl", "/bin/systemctl"] : platform === "darwin" ? ["/bin/launchctl"] : [];
+  for (const path of paths) {
+    try {
+      const stat = (deps.stat ?? statSync)(path);
+      if (stat.isFile() && (stat.mode & 0o002) === 0 && (stat.mode & 0o111) !== 0) return path;
+    } catch { /* Try the next trusted location; no PATH fallback. */ }
+  }
+  return null;
+}
+
+/** All manager evidence shares the transaction deadline, including the retained PID-bound probe. */
+export function runBoundedUpdateRestartSupervisor(command: string, args: string[], deadlineAt: number, deps: UpdateRestartSupervisionDeps = {}) {
+  const now = deps.now ?? Date.now;
+  const remaining = deadlineAt - now();
+  if (!Number.isFinite(remaining) || remaining <= 0) throw new Error("update_restart_supervision_unverified");
+  const environment = (deps.platform ?? process.platform) === "linux"
+    ? systemdUserBusEnvironment(deps.environment ?? process.env, { uid: deps.uid, exists: deps.exists })
+    : { ...(deps.environment ?? process.env) };
+  const result = (deps.run ?? run)(command, args, Math.min(PROBE_TIMEOUT_MS, remaining), environment);
+  if (now() >= deadlineAt) throw new Error("update_restart_supervision_unverified");
+  return result;
+}
+
+/** Registration presence is independent of liveness; only positive inactivity admits. */
+export function probeUpdateRestartSupervision(deadlineAt: number, deps: UpdateRestartSupervisionDeps = {}, command = resolveUpdateRestartSupervisor(deps)): UpdateRestartSupervision {
+  const platform = deps.platform ?? process.platform;
+  if (!command) return "unknown";
+  if (platform === "darwin") {
+    const uid = deps.uid ?? process.getuid?.() ?? 0;
+    const states = [`gui/${uid}/${LABEL}`, `user/${uid}/${LABEL}`].map(target => {
+      try {
+        const result = runBoundedUpdateRestartSupervisor(command, ["print", target], deadlineAt, deps);
+        return result.status === 112 || result.status === 113 ? "inactive" : result.status === 0 ? "active" : "unknown";
+      } catch { return "unknown"; }
+    });
+    return states.includes("unknown") ? "unknown" : states.includes("active") ? "active" : "inactive";
+  }
+  if (platform === "linux") {
+    try {
+      const result = runBoundedUpdateRestartSupervisor(command, UPDATE_RESTART_SYSTEMD_ARGS, deadlineAt, deps);
+      return classifyUpdateRestartSystemdSupervision(result);
+    } catch { return "unknown"; }
+  }
+  return "unknown";
+}
+
+/** The retained manager observation must satisfy the same positive-inactivity contract. */
+export function classifyUpdateRestartSystemdSupervision(result: UpdateRestartSupervisorReply): UpdateRestartSupervision {
+  if (result.status !== 0) return "unknown";
+  const fields = new Map<string, string>();
+  for (const line of result.stdout.trim().split(/\r?\n/)) {
+    const match = /^([A-Za-z]+)=(.*)$/.exec(line);
+    if (!match || fields.has(match[1]!)) return "unknown";
+    fields.set(match[1]!, match[2]!);
+  }
+  const pid = fields.get("MainPID");
+  if (!pid || !/^\d+$/.test(pid) || !Number.isSafeInteger(Number(pid))) return "unknown";
+  if (!["loaded", "not-found"].includes(fields.get("LoadState") ?? "")) return "unknown";
+  if (fields.get("ActiveState") === "inactive" && pid === "0") return "inactive";
+  return fields.get("ActiveState") === "active" || Number(pid) > 0 ? "active" : "unknown";
+}

package/src/cli/update-restart.ts

@@ -7,21 +7,23 @@ import { isRealBunBinary } from "../lib/bun-binary-validator.mjs";
 import { isProcessAlive } from "../lib/process-control";
 import { parseStrictSemver } from "../lib/strict-semver";
 import { startArgv } from "../lib/self-launch-argv";
-import { diagnoseService } from "../service/diagnostics";
-import { inspectGuardedManagerTarget } from "../service/guarded-manager-target";
+import { inspectGuardedManagerTarget, type GuardedManagerDeps } from "../service/guarded-manager-target";
 import { acquireOwnershipMutationLease, unprivilegedOwnershipMutationEnvironment } from "../service/ownership-mutation-lease.mjs";
 import { serviceStatePaths } from "../service/state";
 import { findLiveProxy, probeEndpointLiveness, probeHostname, type LiveProxy } from "../server/proxy-liveness";
 import { waitForPortAvailable } from "../server/ports";
 import { UPDATE_RESTART_CHILD_ENV, type UpdateRestartChildMarker } from "./update-restart-child";
-import { assertUpdateRestartConfiguration, assertUpdateRestartHome, readUpdateRestartHome, type UpdateRestartHome } from "./update-restart-home";
+import { assertUpdateRestartConfiguration, assertUpdateRestartHome, readUpdateRestartHome, type UpdateRestartHome, type UpdateRestartHomeDeps } from "./update-restart-home";
 import { observeAttestedUpdateReplacement, stopAttestedUpdateTarget } from "./update-restart-transport";
 import type { UpdateRestartCandidate } from "./update-restart-candidate";
 import { INCOMPLETE_INSTALL_RECOVERY } from "./restart-failure";
 import { computeVersionSkew } from "./version-skew";
+import { createSupervisionLatch, inspectDesktopSupervision } from "../service/desktop-supervision.mjs";
+import { classifyUpdateRestartSystemdSupervision, probeUpdateRestartSupervision, resolveUpdateRestartSupervisor, runBoundedUpdateRestartSupervisor, UPDATE_RESTART_SYSTEMD_ARGS, type UpdateRestartSupervisionDeps } from "./update-restart-supervision";
 
 export interface UpdateRestartChild { pid?: number; exitCode: number | null; signalCode: string | null }
 export interface UpdateRestartIo {
+  inspectSupervision?: typeof inspectDesktopSupervision;
   now(): number;
   acquire(): { release(): void };
   home(): UpdateRestartHome;
@@ -37,7 +39,7 @@ export interface UpdateRestartIo {
   wait(ms: number): Promise<void>;
 }
 const ELIGIBILITY_REASONS = ["windows", "unsupported_platform", "foreground", "service", "shared_or_client",
-  "package_tree_fenced", "unverifiable_ancestry", "target_changed", "configuration_changed"] as const;
+  "package_tree_fenced", "unverifiable_ancestry", "target_changed", "configuration_changed", "desktop"] as const;
 export type UpdateRestartEligibilityReason = (typeof ELIGIBILITY_REASONS)[number];
 
 /** Carries only a closed reason code across the eligibility/transport boundary. */
@@ -56,6 +58,7 @@ function sameRuntime(candidate: UpdateRestartCandidate, current: RuntimePortStat
 
 /** A terminal update transaction: it never enters generic restart recovery. */
 export async function runUpdateRestart(candidate: UpdateRestartCandidate, deadlineAt: number, io: UpdateRestartIo): Promise<UpdateRestartResult> {
+  const latch = createSupervisionLatch();
   let phase = "eligibility";
   let lease: { release(): void } | undefined;
   // Recorded here because the stop transport sanitizes anything thrown by beforeStop.
@@ -79,6 +82,13 @@ export async function runUpdateRestart(candidate: UpdateRestartCandidate, deadli
         eligibilityReason = currentRuntime?.siblingOfPort !== undefined ? "shared_or_client" : "target_changed";
         throw new Error("target");
       }
+      const supervision = (io.inspectSupervision ?? inspectDesktopSupervision)({ targetPid: candidate.target.pid });
+      const evidence = supervision.kind === "desktop" && supervision.runtimePid !== candidate.target.pid
+        ? { kind: "unknown" as const, reason: "unrelated-target", desktopSeen: false } : supervision;
+      if (latch.observe(evidence)) {
+        eligibilityReason = "desktop";
+        throw new UpdateRestartEligibilityError("desktop");
+      }
       try {
         if (!io.standalone(candidate.target)) throw new Error("target");
       } catch (error) {
@@ -147,6 +157,7 @@ export function describeUpdateRestartFailure(code: string, reason?: UpdateRestar
       switch (reason) {
         case "windows": return "Restart from a newer CLI is unavailable on Windows. Run `ocx status`, then restart through the owning service or desktop app.";
         case "unsupported_platform": return "Restart from a newer CLI requires macOS or Linux. Run `ocx status`, then use the owning lifecycle manager.";
+        case "desktop": return "OpenCodex Desktop supervises this proxy. Use the app's updater (tray → Check for Updates), or quit OpenCodex before updating and restarting from this CLI.";
         case "service": return "An installed or active service owns lifecycle control. Run `ocx status`, then use the owning installation's `ocx service restart`.";
         case "foreground": return "The proxy is attached to a parent process. Run `ocx status`; if it runs in a terminal, restart it in that terminal, otherwise use its owning app or supervisor.";
         case "shared_or_client": return "This is a shared or connected-client runtime. Run `ocx status` and restart through its owning Hub, service or desktop app.";
@@ -180,29 +191,64 @@ export function describeUpdateRestartFailure(code: string, reason?: UpdateRestar
   }
 }
 
-function standalone(target: UpdateRestartCandidate["target"]): boolean {
-  try { assertUpdateRestartConfiguration(target.hostname ?? ""); }
+export interface UpdateRestartStandaloneDeps {
+  platform?: NodeJS.Platform;
+  expectedHome?: UpdateRestartHome;
+  checkConfiguration?: typeof assertUpdateRestartConfiguration;
+  command?: typeof readProcessCommandLine;
+  parent?: (pid: number) => string;
+  home?: UpdateRestartHomeDeps;
+  supervision?: UpdateRestartSupervisionDeps;
+  manager?: GuardedManagerDeps;
+}
+
+export function standalone(target: UpdateRestartCandidate["target"], deadlineAt: number, deps: UpdateRestartStandaloneDeps = {}): boolean {
+  const platform = deps.platform ?? process.platform;
+  try { (deps.checkConfiguration ?? assertUpdateRestartConfiguration)(target.hostname ?? ""); }
   catch { throw new UpdateRestartEligibilityError("configuration_changed"); }
-  if (process.platform !== "darwin" && process.platform !== "linux") {
-    throw new UpdateRestartEligibilityError(process.platform === "win32" ? "windows" : "unsupported_platform");
+  if (platform !== "darwin" && platform !== "linux") {
+    throw new UpdateRestartEligibilityError(platform === "win32" ? "windows" : "unsupported_platform");
   }
   const host = probeHostname(target.hostname).replace(/^\[|\]$/g, "");
   if (target.role === "client") throw new UpdateRestartEligibilityError("shared_or_client");
   if (target.packageTreeFenced) throw new UpdateRestartEligibilityError("package_tree_fenced");
   if (!isIP(host) || target.source !== "runtime") throw new UpdateRestartEligibilityError("unverifiable_ancestry");
-  const command = readProcessCommandLine(target.pid);
+  const command = (deps.command ?? readProcessCommandLine)(target.pid);
   if (!command || !isOcxStartCommandLine(command)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
-  if (diagnoseService().installed) throw new UpdateRestartEligibilityError("service");
-  const manager = inspectGuardedManagerTarget(target.pid, target.port);
+  let home: UpdateRestartHome;
+  try {
+    home = readUpdateRestartHome(deps.home);
+    if (deps.expectedHome && JSON.stringify(home) !== JSON.stringify(deps.expectedHome)) throw new Error("changed");
+  }
+  catch { throw new UpdateRestartEligibilityError("service"); }
+  const supervision = { ...deps.supervision, platform };
+  const managerCommand = resolveUpdateRestartSupervisor(supervision);
+  if (!managerCommand) throw new UpdateRestartEligibilityError("service");
+  if (probeUpdateRestartSupervision(deadlineAt, supervision, managerCommand) !== "inactive") throw new UpdateRestartEligibilityError("service");
+  const manager = inspectGuardedManagerTarget(target.pid, target.port, {
+    ...deps.manager, platform,
+    launchctl: args => {
+      const result = runBoundedUpdateRestartSupervisor(managerCommand, args, deadlineAt, supervision);
+      return { ...result, ok: result.status === 0 };
+    },
+    systemdShow: () => {
+      const result = runBoundedUpdateRestartSupervisor(managerCommand, UPDATE_RESTART_SYSTEMD_ARGS, deadlineAt, supervision);
+      if (classifyUpdateRestartSystemdSupervision(result) !== "inactive") throw new Error("update_restart_supervision_unverified");
+      return result.stdout;
+    },
+  });
   if (manager.kind !== "absent") throw new UpdateRestartEligibilityError(manager.kind === "bound" ? "service" : "unverifiable_ancestry");
   let parent: string;
   try {
-    parent = execFileSync("ps", ["-o", "ppid=", "-p", String(target.pid)], {
+    parent = deps.parent ? deps.parent(target.pid) : execFileSync("ps", ["-o", "ppid=", "-p", String(target.pid)], {
       encoding: "utf8", timeout: 1000, stdio: ["ignore", "pipe", "ignore"],
     }).trim();
   } catch { throw new UpdateRestartEligibilityError("unverifiable_ancestry"); }
   if (!/^[1-9]\d*$/.test(parent)) throw new UpdateRestartEligibilityError("unverifiable_ancestry");
   if (parent !== "1") throw new UpdateRestartEligibilityError("foreground");
+  try {
+    if (JSON.stringify(readUpdateRestartHome(deps.home)) !== JSON.stringify(home)) throw new Error("changed");
+  } catch { throw new UpdateRestartEligibilityError("service"); }
   return true;
 }
 
@@ -213,7 +259,7 @@ export function restartFromCurrentInstallation(candidate: UpdateRestartCandidate
   return runUpdateRestart(candidate, deadlineAt, {
     now: Date.now,
     acquire: () => acquireOwnershipMutationLease(serviceStatePaths(), { waitMs: Math.max(0, Math.min(2000, deadlineAt - Date.now())) }),
-    home: readUpdateRestartHome, checkHome: assertUpdateRestartHome, runtime: readRuntimePort, standalone,
+    home: readUpdateRestartHome, checkHome: home => assertUpdateRestartHome(home, deadlineAt), runtime: readRuntimePort, standalone: target => standalone(target, deadlineAt, { expectedHome: candidate.home }),
     runtimeReady: () => isRealBunBinary(executable),
     stop: async (target, deadline, beforeStop) => {
       const token = configuredAdminToken();

package/src/cli/v2.ts

@@ -15,15 +15,14 @@ import { parseV2Command, V2_USAGE, type V2ParsedCommand } from "./v2-input";
 import { handleV2RuntimeCommand } from "./v2-runtime";
 import { localV2State, v2LocalSyncResult, type V2LocalSync } from "./v2-local-output";
 import { execFileSync } from "node:child_process";
-import { dirname } from "node:path";
-import { activeCodexConfigPath, getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
+import { getAgentsEnabled, getAgentsMaxDepth, getLogicalMaxThreads, getMultiAgentModeHintText, getSubagentDeveloperInstructions, hasAgentsMaxThreads, isMultiAgentV2Enabled, setMultiAgentModeHintText, transitionMultiAgentV2 } from "../codex/features";
 
 import { commandInvocation, type SpawnInvocation } from "../lib/win-exec";
 import { deleteConfigTopLevelKey, loadConfig, saveConfig } from "../config";
 import { resolveAndPersistCodexRuntime, type ResolveCodexRuntimeDeps } from "../codex/runtime";
 
 export interface V2CliDeps {
-  execFile?: (file: string, args: string[], options?: SpawnInvocation["options"]) => void;
+  execFile?: (file: string, args: string[], options?: SpawnInvocation["options"] & { env?: NodeJS.ProcessEnv }) => void;
   isEnabled?: typeof isMultiAgentV2Enabled;
   hasMaxThreads?: typeof hasAgentsMaxThreads;
   sync?: (port?: number) => Promise<unknown>;
@@ -35,7 +34,8 @@ export interface V2CliDeps {
 
 export type CodexFeaturesInvocationDeps =
   & Parameters<typeof commandInvocation>[3]
-  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">;
+  & Pick<ResolveCodexRuntimeDeps, "existsSync" | "execFileSync" | "configDir" | "readFileSync">
+  & { requireAvailable?: boolean };
 
 /**
  * Shared invocation for `codex features enable|disable <feature>` — the single
@@ -51,14 +51,18 @@ export function codexFeaturesInvocation(
   platform: NodeJS.Platform = process.platform,
   deps: CodexFeaturesInvocationDeps = {},
 ): SpawnInvocation {
-  const command = resolveAndPersistCodexRuntime({
+  const resolved = resolveAndPersistCodexRuntime({
     env: deps.env ?? process.env,
     platform,
     existsSync: deps.existsSync,
     execFileSync: deps.execFileSync,
     configDir: deps.configDir,
     readFileSync: deps.readFileSync,
-  }).runtime.command || "codex";
+  });
+  if (deps.requireAvailable && resolved.runtime.source === "fallback" && resolved.runtime.version === null) {
+    throw Object.assign(new Error("spawn codex ENOENT"), { code: "ENOENT" });
+  }
+  const command = resolved.runtime.command || "codex";
   return commandInvocation(command, ["features", action, feature], platform, deps);
 }
 
@@ -70,27 +74,30 @@ export function codexFeaturesInvocation(
  */
 export function runCodexFeaturesCommand(
   action: "enable" | "disable",
-  feature: string = "multi_agent_v2",
+  feature: string,
+  env: NodeJS.ProcessEnv,
+  validateBeforeSpawn: () => void,
+  preparedInvocation?: SpawnInvocation,
 ): void {
-  const inv = codexFeaturesInvocation(action, feature);
+  const inv = preparedInvocation ?? codexFeaturesInvocation(action, feature, process.platform, { env });
+  validateBeforeSpawn();
   execFileSync(inv.file, inv.args,
     {
       stdio: ["ignore", "pipe", "pipe"], timeout: 15_000, windowsHide: true, encoding: "utf8",
-      // The reader resolves $CODEX_HOME at call time (including the WSL Windows-home
-      // detection); force the same home on the child so it never toggles a different
-      // config than the one the postcondition re-reads.
-      env: { ...process.env, CODEX_HOME: dirname(activeCodexConfigPath()) },
       ...inv.options,
+      env,
     });
 }
 
-function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps): void {
+function runCodexFeatures(action: "enable" | "disable", deps: V2CliDeps, env: NodeJS.ProcessEnv, validateBeforeSpawn: () => void): void {
   if (deps.execFile) {
-    const inv = (deps.featuresInvocation ?? codexFeaturesInvocation)(action);
-    deps.execFile(inv.file, inv.args, inv.options);
+    const inv = deps.featuresInvocation ? deps.featuresInvocation(action)
+      : codexFeaturesInvocation(action, "multi_agent_v2", process.platform, { env });
+    validateBeforeSpawn();
+    deps.execFile(inv.file, inv.args, { ...inv.options, env });
     return;
   }
-  runCodexFeaturesCommand(action);
+  runCodexFeaturesCommand(action, "multi_agent_v2", env, validateBeforeSpawn);
 }
 
 export function v2StatusLine(enabled: boolean): string {
@@ -182,7 +189,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
     }
     if (parsed.verb === "threads") {
       const enabled = (deps.isEnabled ?? isMultiAgentV2Enabled)();
-      const result = transitionMultiAgentV2(enabled, next => runCodexFeatures(next ? "enable" : "disable", deps), { threadLimit: parsed.value });
+      const result = transitionMultiAgentV2(enabled, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate), { threadLimit: parsed.value });
       if (!result.ok) return emit(false, ["Unable to update the native thread limit. Read ocx v2 status before retrying."]);
       changed = result.changed;
       return emit(true, [changed ? `max_threads = ${parsed.value} (${enabled ? "v2" : "v1"}) — applies to new sessions.` : `max_threads already ${parsed.value} — nothing to do.`]);
@@ -194,7 +201,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       changed = (config.multiAgentMode ?? "default") !== parsed.value;
       if (parsed.value !== "default") {
         const target = parsed.value === "v2" && config.keepNativeChatGptOnV1 !== true;
-        const transition = transitionMultiAgentV2(target, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        const transition = transitionMultiAgentV2(target, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate));
         if (!transition.ok) { changed = false; return emit(false, ["Native mode transition failed. Read ocx v2 status before retrying."]); }
         changed ||= transition.changed;
       }
@@ -207,7 +214,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       unchangedKeep = (config.keepNativeChatGptOnV1 === true) === parsed.value;
       changed = !unchangedKeep;
       if (parsed.value && requiresGlobalV2Disabled(config.multiAgentMode, true)) {
-        const transition = transitionMultiAgentV2(false, next => runCodexFeatures(next ? "enable" : "disable", deps));
+        const transition = transitionMultiAgentV2(false, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate));
         if (!transition.ok) { changed = false; return emit(false, ["Native hybrid-mode transition failed. Read ocx v2 status before retrying."]); }
         changed ||= transition.changed;
       }
@@ -222,7 +229,7 @@ export async function cmdV2(args: string[], deps: V2CliDeps = {}, findPort?: ()
       if (want && requiresGlobalV2Disabled(config.multiAgentMode, config.keepNativeChatGptOnV1 === true)) {
         return emit(false, ["v2 on: incompatible with keep-native-v1 while mode is v2 — Codex's global multi_agent_v2 overrides the native v1 catalog pin. Run 'ocx v2 keep-native-v1 off' first."]);
       }
-      const transition = transitionMultiAgentV2(want, next => runCodexFeatures(next ? "enable" : "disable", deps));
+      const transition = transitionMultiAgentV2(want, (next, env, validate) => runCodexFeatures(next ? "enable" : "disable", deps, env, validate));
       if (!transition.ok) return emit(false, ["Native feature transition failed. Read ocx v2 status before retrying."]);
       changed = transition.changed;
       if (!changed) return emit(true, [`multi_agent_v2 already ${want ? "ON" : "OFF"} — nothing to do.`]);

package/src/cli/version-skew-notice.ts

@@ -0,0 +1,77 @@
+import { readConfigDiagnostics } from "../config/diagnostics";
+import { readRuntimePort } from "../config/process-state";
+import { packageVersion } from "./help";
+import { proxyIdentityAt } from "../server/proxy-liveness";
+import { computeVersionSkew } from "./version-skew";
+
+const LIFECYCLE = new Set(["start", "stop", "restart", "update", "service"]);
+const NOTICE_DEADLINE_MS = 200;
+let printed = false;
+
+export function shouldNoticeVersionSkew(command: string | undefined, args: string[]): boolean {
+  const boundary = args.indexOf("--");
+  const prefix = boundary < 0 ? args : args.slice(0, boundary);
+  return LIFECYCLE.has(command ?? "")
+    && !prefix.some(arg => arg === "--json" || arg === "--help" || arg === "-h")
+    && prefix[1] !== "help";
+}
+
+export interface VersionSkewNoticeIo {
+  readRuntime?: typeof readRuntimePort;
+  readConfig?: typeof readConfigDiagnostics;
+  probe?: typeof proxyIdentityAt;
+  cliVersion?: () => string;
+  now?: () => number;
+  warn?: (message: string) => void;
+}
+
+/**
+ * One proxyIdentityAt (src/server/proxy-liveness.ts) call validates /healthz identity,
+ * expected PID and terminal-safe version within the total diagnostic budget.
+ */
+export async function maybeNoticeVersionSkew(
+  command: string | undefined, args: string[], io: VersionSkewNoticeIo = {},
+): Promise<void> {
+  if (printed || !shouldNoticeVersionSkew(command, args)) return;
+  const now = io.now ?? Date.now;
+  const deadlineAt = now() + NOTICE_DEADLINE_MS;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const runtime = (io.readRuntime ?? readRuntimePort)();
+    let port: number;
+    let hostname: string | undefined;
+    let expectedPid: number | undefined;
+    if (runtime) {
+      ({ port, hostname } = runtime);
+      expectedPid = runtime.pid;
+    } else {
+      const diagnostics = (io.readConfig ?? readConfigDiagnostics)();
+      if (diagnostics.error) return;
+      port = diagnostics.config.port ?? 10100;
+      hostname = diagnostics.config.hostname;
+    }
+    const remaining = Math.floor(deadlineAt - now());
+    if (remaining <= 0) return;
+    const cliVersion = (io.cliVersion ?? packageVersion)();
+    if (now() >= deadlineAt) return;
+    const identity = await Promise.race([
+      (io.probe ?? proxyIdentityAt)(port, { hostname, expectedPid }, {
+        timeoutMs: Math.max(1, Math.floor(deadlineAt - now())),
+        attempts: 1, deadlineAt, nowFn: now,
+      }),
+      new Promise<null>(resolve => {
+        timer = setTimeout(() => resolve(null), Math.max(1, deadlineAt - now()));
+      }),
+    ]);
+    if (printed || !identity || now() >= deadlineAt) return;
+    const skew = computeVersionSkew(cliVersion, identity.version);
+    if (!skew.skewed) return;
+    printed = true;
+    (io.warn ?? console.error)(`ocx ${cliVersion} does not match the running proxy ${identity.version}. `
+      + "Check which opencodex installation you meant to use (`ocx status` shows both).");
+  } catch {
+    // Best-effort diagnostics must not fail a lifecycle command or change its exit code.
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}