Harden durable runtime ownership against stale consent and unsafe replacement

bin/ocx.mjs

@@ -15,9 +15,10 @@ import { decidePostStopUpdate } from "../src/update/stop-decision.mjs";
 import { planUpdateRuntimeHandling } from "../src/update/runtime-ownership.mjs";
 import {
   inspectInstallStateBytes,
-  resolveOwnershipFromEvidence,
+  selectAuthoritativeServiceState,
   serviceStateFilesFor,
 } from "../src/service/install-state-contract.mjs";
+import { acquireOwnershipMutationLease } from "../src/service/ownership-mutation-lease.mjs";
 import { randomBytes } from "node:crypto";
 import { createRequire } from "node:module";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
@@ -262,27 +263,40 @@ function runPackageManagerSelfUpdate(manager) {
 
   // Remember whether a background service manages the proxy BEFORE stopping — `ocx stop`
   // unloads it, so a successful update must refresh and restart it afterwards.
-  const serviceStateFiles = serviceStateFilesFor(configDir(), join(homedir(), ".opencodex"));
-  const serviceStatePath = serviceStateFiles[0];
-  const serviceWasInstalled = existsSync(serviceStatePath);
-  /**
-   * What this update may do to the runtime, decided by the SAME contract the Bun updater
-   * uses — every state path, the whole record shape, and absence as the only answer that
-   * means no claim.
-   *
-   * This used to be a local reader that inspected the anchor alone and returned "known
-   * unowned" whenever the `ownership` field was simply missing, including from a record that
-   * fails the contract outright. A takeover the Bun updater refused to disturb was therefore
-   * fair game here, which is an authorization gap rather than a cosmetic divergence.
-   */
+  const allServiceStatePaths = serviceStateFilesFor(configDir(), join(homedir(), ".opencodex"));
+  // The test guard's legacy path is the developer's real home. Production always reads the
+  // same active-home + default-home observations as the Bun resolver.
+  const serviceStatePaths = process.env.OCX_TEST_HOME_GUARD === "1"
+    ? allServiceStatePaths.slice(0, 1)
+    : allServiceStatePaths;
+  const serviceWasInstalled = serviceStatePaths.some(path => existsSync(path));
+  // What this update may do to the runtime. The same rule the Bun updater applies, from the
+  // same module: a desktop takeover vetoes both the stop and the service refresh below.
+  const readServiceState = () => selectAuthoritativeServiceState(
+    serviceStatePaths.map(path => inspectInstallStateBytes(path, at => readFileSync(at, "utf8"))),
+  );
   const readOwnership = () => {
-    const evidence = serviceStateFiles.map(path => inspectInstallStateBytes(path, at => readFileSync(at, "utf8")));
-    const resolution = resolveOwnershipFromEvidence(evidence);
-    if (resolution.kind === "owned") return { ownership: resolution.ownership, ownershipUnknown: false };
-    return { ownership: null, ownershipUnknown: resolution.kind === "unknown" };
+    const selected = readServiceState();
+    if (selected.kind === "unknown") return { ownership: null, ownershipUnknown: true, subjectToken: "unknown" };
+    if (selected.kind === "none") return {
+      ownership: null, ownershipUnknown: false, subjectToken: JSON.stringify(["none", selected.revision]),
+    };
+    const ownership = selected.state.ownership ?? null;
+    return {
+      ownership,
+      ownershipUnknown: false,
+      subjectToken: JSON.stringify(ownership
+        ? ["owned", selected.revision, ownership]
+        : ["none", selected.revision]),
+    };
   };
-  let runtimePlan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled });
+  const initialOwnership = readOwnership();
+  const runtimePlan = planUpdateRuntimeHandling({ ...initialOwnership, serviceInstalled: serviceWasInstalled });
   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.");
+    process.exit(1);
+  }
   const trayBeforeUpdate = planWindowsTrayUpdate(
     process.platform === "win32" ? trayInstallState() : { installed: false, running: false },
   );
@@ -296,10 +310,11 @@ function runPackageManagerSelfUpdate(manager) {
   }
   /** Register from scratch, preserving the recorded backend. Only for a genuinely absent service. */
   function serviceInstallArgs() {
-    try {
-      const state = JSON.parse(readFileSync(serviceStatePath, "utf8"));
-      if (state.backend === "native") return [postUpdateLauncher, "service", "install", "--native"];
-    } catch { /* missing or corrupt — fall through to default */ }
+    const selected = readServiceState();
+    if (selected.kind === "unknown") throw new Error(`service backend is unknown: ${selected.reason}`);
+    if (selected.kind === "state" && selected.state.backend === "native") {
+      return [postUpdateLauncher, "service", "install", "--native"];
+    }
     return [postUpdateLauncher, "service", "install"];
   }
   /**
@@ -450,7 +465,7 @@ function runPackageManagerSelfUpdate(manager) {
         // 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 });
-        if (!nowOwned.stopRuntime) {
+        if (!nowOwned.mayStopRuntime) {
           console.warn(nowOwned.notice ?? "opencodex: the background runtime is owned elsewhere; not starting a second proxy.");
           return;
         }
@@ -497,12 +512,13 @@ function runPackageManagerSelfUpdate(manager) {
   function recoverStoppedRuntimeAfterFailure() {
     // Nothing was stopped under a foreign owner, so there is nothing to recover — and
     // starting a proxy here would put a second one beside the runtime the app is managing.
-    if (!runtimePlan.stopRuntime) return;
+    const recoveryPlan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled });
+    if (!recoveryPlan.mayStopRuntime) return;
     if (!postUpdateLauncherUsable) {
       console.error("opencodex: no verified active launcher remains for automatic recovery; reinstall opencodex manually.");
       return;
     }
-    if (runtimePlan.refreshService) {
+    if (recoveryPlan.mayRestoreService) {
       console.warn("opencodex: update failed after stopping the proxy — restoring the previous background service.");
       refreshBackgroundServiceOrStartDirect();
     } else if (hasRuntimeState) {
@@ -518,15 +534,7 @@ function runPackageManagerSelfUpdate(manager) {
   // is the whole test here — the launcher cannot parse it, and `ocx stop` is what decides
   // whether the obligation is safe to finish.
   const hasPendingTeardown = hasPendingTeardownIn(readdirSync, configDir());
-  // Re-read at the point of action rather than trusting the plan formed above: the Windows
-  // tray handoff between them spawns children, so a takeover can land in the gap, and
-  // stopping a runtime that just changed hands is the failure this lane exists to prevent.
-  {
-    const atStop = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled });
-    if (atStop.notice && atStop.notice !== runtimePlan.notice) console.log(atStop.notice);
-    runtimePlan = atStop;
-  }
-  if (runtimePlan.stopRuntime && (serviceWasInstalled || hasRuntimeState || hasPendingTeardown)) {
+  if (runtimePlan.mayStopRuntime && (serviceWasInstalled || hasRuntimeState || hasPendingTeardown)) {
     console.log("⏹  Stopping the running proxy before updating...");
     const stopRes = spawnSync(process.execPath, [launcher, "stop"], { stdio: "inherit", windowsHide: true });
     const stillHasRuntimeState =
@@ -578,6 +586,22 @@ function runPackageManagerSelfUpdate(manager) {
     }
   }
 
+  const replacementLease = acquireOwnershipMutationLease(serviceStatePaths);
+  const replacementOwnership = readOwnership();
+  const replacementPlan = planUpdateRuntimeHandling({ ...replacementOwnership, serviceInstalled: serviceWasInstalled });
+  const replacementLiveness = runtimePlan.mayStopRuntime
+    ? probeProxyLiveness(bakePort, bakeHostname)
+    : "dead";
+  if (replacementOwnership.subjectToken !== initialOwnership.subjectToken
+    || !replacementPlan.mayReplacePackage
+    || replacementLiveness !== "dead") {
+    replacementLease.release();
+    if (trayBeforeUpdate.restoreOnFailure) runTrayLifecycle(launcher, "start");
+    console.error(replacementPlan.notice
+      ?? "opencodex: update stopped because runtime ownership or liveness changed after the stop decision; rerun from the beginning.");
+    process.exit(1);
+  }
+
   // npm keeps the existing stage -> verify -> swap -> rollback flow. pnpm owns a
   // content-addressable store and generated global shims, so its path uses pnpm's own
   // global update operation and verifies the active group instead of renaming files.
@@ -666,6 +690,8 @@ function runPackageManagerSelfUpdate(manager) {
       `The live install was not knowingly modified; run 'ocx update' again or reinstall with ${manual}.`);
     res = { status: 1 };
   }
+  replacementLease.release();
+  const postInstallPlan = planUpdateRuntimeHandling({ ...readOwnership(), serviceInstalled: serviceWasInstalled });
   if (res.status === 0) {
     console.log(`\nUpdated${latest ? ` to v${latest}` : ""}.`);
     repairCodexShimIfNeeded(postUpdateLauncher);
@@ -681,10 +707,10 @@ function runPackageManagerSelfUpdate(manager) {
     }
     // The stop above unloaded any managed service; refresh via the freshly-installed
     // launcher so the new files write the baked paths and the service restarts.
-    if (runtimePlan.refreshService) {
+    if (postInstallPlan.mayRestoreService) {
       console.log("Refreshing the background service with the updated files...");
       refreshBackgroundServiceOrStartDirect();
-    } else if (runtimePlan.stopRuntime) {
+    } else if (postInstallPlan.mayStopRuntime) {
       console.log(`Restart the proxy:  ${launcherStartHint(postUpdateLauncher, bakePort)}`);
     }
     process.exit(0);

scripts/test-layout/layout.json

@@ -1373,6 +1373,7 @@
     "server-xai-header-parity.test.ts": "server",
     "server-xai-oauth-401-replay.test.ts": "server",
     "server-xai-responses-streaming.test.ts": "server",
+    "service-ownership-compatibility.test.ts": "service",
     "service-ownership-handover.test.ts": "service",
     "service-ownership-state.test.ts": "service",
     "service-probe-docker.test.ts": "service",

src/cli/index.ts

@@ -94,7 +94,8 @@ import { summarizeStopRun, type StopOutcome, type StopRunRecord } from "./stop-r
 import { runCli } from "./root";
 import { isProcessAlive, ProxyOwnershipRefusedError, refusalNextStep, stopProxy } from "../lib/process-control";
 import { startupDataPlaneToken } from "../lib/service-secrets";
-import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
+import { assertNotAdminToken, diagnoseService, isServiceOwnershipError, proxyStillLiveAfterStop, serviceCommand, serviceEnvironmentOwnedHere, serviceStartableFromTray, serviceStatePaths, serviceStatusSummary, stopServiceIfInstalledDetailed, uninstallServiceIfInstalled, uninstallServiceDetailed } from "../service";
+import { acquireOwnershipMutationLease } from "../service/ownership-mutation-lease.mjs";
 import { formatStartupRoutingDetail, startupHealthSummary } from "../codex/autostart-health";
 import { injectSystemEnv, reconcileShellHook, revertSystemEnv, uninstallShellHook } from "../server/system-env";
 import { buildDesktop3pRegistry } from "../claude/desktop-3p";
@@ -448,6 +449,29 @@ async function handleStart(options: { block?: boolean } = {}) {
   // live daemon holding resources while it overwrites its own binary.
   await maybeShowUpdatePrompt();
 
+  const startLease = acquireOwnershipMutationLease(serviceStatePaths());
+  // The earlier probe owned journal cleanup. This one owns the bind decision: an updater may
+  // have stopped the old runtime and acquired the same lease before package replacement.
+  const fencedLive = await findLiveProxy(START_OWNERSHIP_LIVENESS);
+  if (fencedLive) {
+    const decision = decideStartWithLiveOwner({
+      livePort: fencedLive.port,
+      requestedPort,
+      ocxService: process.env.OCX_SERVICE,
+    });
+    if (decision === "service-stay-out") {
+      startLease.release();
+      console.log(`Proxy already running (PID ${fencedLive.pid ?? "unknown"}, port ${fencedLive.port}); service wrapper staying out of the way.`);
+      process.exit(0);
+    }
+    if (decision === "refuse") {
+      startLease.release();
+      console.error(`⚠️  Proxy appeared before bind (PID ${fencedLive.pid ?? "unknown"}, port ${fencedLive.port}). Use 'ocx stop' first.`);
+      process.exit(1);
+    }
+    siblingStart = true;
+  }
+
   // Port selection is check-then-bind: a concurrent `ocx start`/`ensure` can win the port
   // between the probe and Bun.serve. Soft starts may re-pick; hard-pinned `--port` retries
   // the same port only (never hop — that was the remaining PR #152 gap).
@@ -460,6 +484,7 @@ async function handleStart(options: { block?: boolean } = {}) {
   const readinessGate = createReadinessGate();
   let server: ReturnType<typeof startServer>;
   const localAttestationSecret = createLocalAttestationSecret();
+  try {
   for (let attempt = 0; ; attempt++) {
     try {
       server = startServer(port, { localAttestationSecret, readinessGate });
@@ -471,6 +496,7 @@ async function handleStart(options: { block?: boolean } = {}) {
     } catch (err) {
       if (err instanceof SpendLedgerOwnerError) {
         console.error(`❌ ${err.message}`);
+        startLease.release();
         process.exit(1);
       }
       if (err instanceof AuxiliaryListenerBindError || !isAddrInUse(err) || attempt >= 2) throw err;
@@ -480,6 +506,7 @@ async function handleStart(options: { block?: boolean } = {}) {
         const freed = await waitForPortAvailable(port, hostname, { timeoutMs: 3_000, intervalMs: 50 });
         if (!freed) {
           console.error(`❌ Port ${port} stayed busy; refusing to hop to an ephemeral port.`);
+          startLease.release();
           process.exit(1);
         }
         continue;
@@ -488,6 +515,9 @@ async function handleStart(options: { block?: boolean } = {}) {
       port = await chooseListenPort(requestedPort, { sibling: siblingStart });
     }
   }
+  } finally {
+    startLease.release();
+  }
   // A single request's streaming error must never crash the daemon serving every
   // other Codex session — capture the full stack to crash.log and stay up.
   installCrashGuards();

src/service.ts

@@ -6,8 +6,12 @@
  * restore it via the command.
  */
 
-export type { ServiceBackend, ServiceInstallState, ServiceStateEvidence, ServiceOwner, ServiceOwnership, ServiceOwnershipResolution, ServiceStateSwapDeps } from "./service/state";
-export { SERVICE_MANAGED_ENV, stableLauncherEntry, serviceLogPath, serviceStatePathsForOpenCodexHome, parseServiceInstallState, parseServiceOwnership, inspectServiceStateEvidence, currentServiceHomes, serviceHomeMatches, readServiceBackend, serviceReinstallArgs, serviceInstallArgs, ServiceStateConflictError, swapServiceInstallState, serviceOwnership, resolveServiceOwnership, desktopOwnsService, ownershipGrantedTo, recordServiceOwner, releaseServiceOwner } from "./service/state";
+export type { ServiceBackend, ServiceInstallState, ServiceStateEvidence, ServiceStateResolution, ServiceOwner, ServiceOwnership, ServiceOwnershipSubject, ServiceOwnershipResolution, ServiceStateSwapDeps, RecordServiceOwnerRequest, RecordServiceOwnerDeps, ReleaseServiceOwnerDeps, RemoveServiceStateDeps } from "./service/state";
+export { SERVICE_MANAGED_ENV, SERVICE_OWNERSHIP_PROTOCOL_VERSION, SERVICE_OWNERSHIP_MINIMUM_CLI_VERSION, stableLauncherEntry, serviceLogPath, serviceStatePaths, serviceStatePathsForOpenCodexHome, parseServiceInstallState, parseServiceOwnership, inspectServiceStateEvidence, resolveServiceState, currentServiceHomes, serviceHomeMatches, readServiceBackend, serviceReinstallArgs, serviceInstallArgs, ServiceStateConflictError, ServiceOwnershipSubjectMismatchError, ServiceOwnershipSubjectUnknownError, ServiceTakeoverCompatibilityChangedError, swapServiceInstallState, removeServiceInstallStateRecords, serviceOwnership, resolveServiceOwnership, sameServiceOwnershipSubject, desktopOwnsService, ownershipGrantedTo, recordServiceOwner, releaseServiceOwner } from "./service/state";
+export type { OwnershipMutationLeaseOptions, OwnershipMutationLease } from "./service/ownership-mutation-lease.mjs";
+export { acquireOwnershipMutationLease, withOwnershipMutationLease } from "./service/ownership-mutation-lease.mjs";
+export type { ManagingCliRole, ManagingCliObservation, RegisteredManagingCliInvocation, ServiceTakeoverCompatibilityInput, ServiceTakeoverCompatibility } from "./service/ownership-compatibility";
+export { registeredManagingCliInvocation, assessServiceTakeoverCompatibility, sameServiceTakeoverCompatibility } from "./service/ownership-compatibility";
 export type { ServiceApiTokenOrigin, ProvisionedServiceApiToken } from "./service/guards";
 export { ServiceOwnershipError, isServiceOwnershipError, serviceEnvironmentOwnedHere, assertServiceEnvironmentMatchesInstall, serviceRetryCommand, assertNotAdminToken, assertServiceAuthEnvironment, writeServiceApiTokenFile, assertLiveServiceManagerAllowed } from "./service/guards";
 export { resolveServiceListenPort, installedServiceListenPort, SERVICE_INSTALL_HEALTH_MS, SERVICE_INSTALL_HEALTH_WINDOWS_MS, serviceInstallHealthMs, confirmServiceServing, reportServiceServing, resolvedProxyEnv } from "./service/health";

src/service/cli.ts

@@ -234,6 +234,15 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
     case "install":
       assertServiceEnvironmentMatchesInstall();
       assertServiceAuthEnvironment();
+      // The install may advance provenance, but it may take back only the owner it observed
+      // before touching the registration. A desktop successor that claims ownership while
+      // the install is running must survive the late release below.
+      const ownershipBeforeInstall = resolveServiceOwnership();
+      if (ownershipBeforeInstall.kind === "unknown") {
+        console.error(`❌ ${unknownServiceOwnerRefusal(ownershipBeforeInstall.reason, "install")}`);
+        process.exitCode = 1;
+        break;
+      }
       // A manually started proxy can still own the configured port while the service
       // registration is absent or unloaded. Stop both the registered manager and any
       // tracked standalone listener before loading the freshly written service assets.
@@ -268,7 +277,7 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       // incidentally — from a tray helper, from `ocx update`, from a doctor suggestion — and
       // undoing a takeover the user consented to must be something the user asked for.
       {
-        const released = releaseServiceOwner();
+        const released = releaseServiceOwner(ownershipBeforeInstall, { allowRevisionAdvance: true });
         if (released) {
           console.log(
             `ℹ️  The desktop app owned the background runtime (install ${released.installId}, `