@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/service/desktop-supervision.mjs

@@ -0,0 +1,140 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+
+// Node >=18 also imports this module from bin/ocx.mjs; do not import TS or Bun APIs.
+function run(command, args) {
+  return execFileSync(command, args, {
+    encoding: "utf8", timeout: 750, maxBuffer: 128 * 1024, stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+// Mirror src/config/paths.ts getConfigDir/expandUserPath and process-state.ts paths.
+// Keep this Node-safe copy in sync; the focused startup test pins both implementations.
+export function desktopSupervisionPaths() {
+  const raw = process.env.OPENCODEX_HOME?.trim();
+  const expanded = raw === "~" ? homedir()
+    : raw?.startsWith("~/") || raw?.startsWith("~\\") ? join(homedir(), raw.slice(2)) : raw;
+  const home = expanded ? resolve(expanded) : join(homedir(), ".opencodex");
+  return { pid: join(home, "ocx.pid"), runtimePort: join(home, "runtime-port.json") };
+}
+
+function validPid(pid) {
+  return Number.isSafeInteger(pid) && pid > 0;
+}
+
+function readState(path, parse) {
+  try { return parse(readFileSync(path, "utf8")); }
+  catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function readPidFile() {
+  return readState(desktopSupervisionPaths().pid, raw => {
+    const text = raw.trim();
+    if (!/^\d+$/.test(text) || !validPid(Number(text))) throw new Error("invalid pid");
+    return Number(text);
+  });
+}
+
+function readRuntimePortPid() {
+  return readState(desktopSupervisionPaths().runtimePort, raw => {
+    // Only project pid: no credential validation, serialization or returned port state.
+    const pid = JSON.parse(raw)?.pid;
+    if (!validPid(pid)) throw new Error("invalid runtime pid");
+    return pid;
+  });
+}
+
+/** Linux identity fields count from the end of comm, which may contain spaces or ')'. */
+export const procfs = {
+  exe: pid => readlinkSync(`/proc/${pid}/exe`),
+  parent: pid => {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    return Number(stat.slice(stat.lastIndexOf(")") + 2).split(" ")[1]);
+  },
+};
+
+export function processIdentity(pid, execute = run, onExecutable) {
+  const text = execute("/bin/ps", ["-p", String(pid), "-o", "ppid=,comm="]).trim();
+  const row = /^(\d+)\s+(.+)$/.exec(text);
+  if (!row) {
+    if (text) throw new Error("invalid process identity");
+    return null;
+  }
+  onExecutable?.(row[2]);
+  return { parent: Number(row[1]), executable: realpathSync(row[2]) };
+}
+
+/** Live supervision is evidence, never a durable ownership claim. */
+export function inspectDesktopSupervision(deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  if (platform !== "darwin" && platform !== "linux") return { kind: "unsupported" };
+  let desktopSeen = false;
+  const unknown = reason => ({ kind: "unknown", reason, desktopSeen });
+  const seen = executable => { if (basename(executable) === "opencodex-desktop") desktopSeen = true; };
+  const readPid = deps.readPid ?? readPidFile;
+  const readPortPid = deps.readRuntimePortPid ?? readRuntimePortPid;
+  const proc = deps.proc ?? procfs;
+  const execute = deps.run ?? run;
+  function identity(pid, parent = false) {
+    if (platform === "darwin") return processIdentity(pid, execute, parent ? seen : undefined);
+    const executable = proc.exe(pid);
+    if (parent) seen(executable);
+    const parentPid = proc.parent(pid);
+    if (!Number.isSafeInteger(parentPid) || parentPid < 0) throw new Error("invalid parent pid");
+    return { parent: parentPid, executable: realpathSync(executable) };
+  }
+  function capture() {
+    const pidFile = readPid();
+    const portPid = readPortPid();
+    const pids = [deps.targetPid, pidFile, portPid].filter(pid => pid !== undefined && pid !== null);
+    if (pids.some(pid => !validPid(pid))) return { error: "invalid-pid" };
+    if (pids.some(pid => pid !== pids[0])) return { error: "pid-mismatch" };
+    const runtimePid = pids[0] ?? null;
+    const child = runtimePid !== null ? identity(runtimePid) : null;
+    const parent = child && child.parent > 1 ? identity(child.parent, true) : null;
+    const snapshot = { pidFile, portPid, runtimePid, child, parent };
+    if (!runtimePid || !child || !parent || basename(parent.executable) !== "opencodex-desktop") {
+      return { ...snapshot, kind: "none" };
+    }
+    seen(parent.executable);
+    const app = parent.executable;
+    if (platform === "darwin" && (basename(dirname(app)) !== "MacOS"
+      || basename(dirname(dirname(app))) !== "Contents")) return { error: "app-mismatch" };
+    const proxy = realpathSync(join(dirname(app), "ocx"));
+    if (child.executable !== proxy || (platform === "linux"
+      && (dirname(proxy) !== dirname(app) || basename(proxy) !== "ocx"))) return { error: "proxy-mismatch" };
+    accessSync(app, constants.X_OK);
+    accessSync(proxy, constants.X_OK);
+    return { ...snapshot, kind: "desktop", app, proxy };
+  }
+  try {
+    const first = capture();
+    if (first.error) return unknown(first.error);
+    const final = capture();
+    if (final.error) return unknown(final.error);
+    if (JSON.stringify(first) !== JSON.stringify(final)) return unknown("snapshot-changed");
+    return final.kind === "desktop"
+      ? { kind: "desktop", runtimePid: final.runtimePid, supervisorPid: final.child.parent, app: final.app, proxy: final.proxy }
+      : { kind: "none" };
+  } catch {
+    // Error messages can contain paths or file contents; expose only the bounded reason.
+    return unknown("probe-failed");
+  }
+}
+
+/** One operation retains its Desktop veto through inconclusive later probes. */
+export function createSupervisionLatch() {
+  let blocked = false;
+  return {
+    observe(evidence) {
+      if (evidence.kind === "none") blocked = false;
+      else if (evidence.kind === "desktop" || (evidence.kind === "unknown" && evidence.desktopSeen)) blocked = true;
+      return blocked;
+    },
+  };
+}

package/src/service/managing-cli.ts

@@ -81,6 +81,7 @@ function probeVersionOnce(
       windowsShim ? ["/c", shimCommand] : [...args, "--version"],
       {
         timeout: VERSION_PROBE_TIMEOUT_MS, encoding: "utf8", stdio: "pipe",
+        env: { ...deps.env, OCX_NO_DESKTOP_HANDOFF: "1" },
         windowsHide: true, ...(windowsShim ? { windowsVerbatimArguments: true } : {}),
       },
     ) as SpawnSyncReturns<string>;

package/src/service/orchestration.ts

@@ -1,5 +1,7 @@
 import { findLiveProxy, SERVICE_STOP_LIVENESS } from "../server/proxy-liveness";
 import { existsSync, unlinkSync } from "node:fs";
+import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
+import { assertSelectedRuntimeWritable, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
 import { getConfigDir } from "../config";
 import { readPid, removePid, removeRuntimePort, verifyPidIdentity } from "../config/process-state";
 import { isWslRuntime } from "../codex/home";
@@ -14,16 +16,17 @@ import { assertSchedulerRegistrationBeforeStart } from "./repair";
 import { SERVICE_MANAGED_ENV, TASK, plistPath, removeServiceInstallStateRecords, writeServiceInstallState } from "./state";
 import type { ServiceBackend } from "./state";
 import { unitPath, isSystemd, installSystemd, startSystemd, stopSystemd, statusSystemd, uninstallSystemd, systemdServiceInstallCleanupOps } from "./systemd";
-import { writeWindowsSchedulerAssets, stageWindowsSchedulerRegistrationXml, removeWindowsSchedulerRegistrationStage, registerFreshWindowsSchedulerTask, recordWindowsSchedulerOwnership, removeNativeWindowsServiceForScheduler, installWindows, installWindowsNative, startWindows, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, statusWindows, statusWindowsXml, killWindowsServiceWrapperProcesses, uninstallWindows, classifyWindowsServiceStop } from "./windows-ops";
+import { writeWindowsSchedulerAssets, stageWindowsSchedulerRegistrationXml, removeWindowsSchedulerRegistrationStage, registerFreshWindowsSchedulerTask, recordWindowsSchedulerOwnership, removeNativeWindowsServiceForScheduler, commitWindowsInstall, commitWindowsNativeInstall, type WindowsServiceInstallDeps, startWindows, isWindowsSchedulerEndBenign, stopWindows, stopWindowsChecked, statusWindows, statusWindowsXml, killWindowsServiceWrapperProcesses, uninstallWindows, classifyWindowsServiceStop } from "./windows-ops";
 import { schtasks, probeWindowsSchedulerTask, rollbackWindowsSchedulerTaskOwnedByAttempt, settleDelay } from "./windows-scheduler";
 import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
 import { windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
 import { win32 } from "node:path";
 import { launchdGuiDomain } from "./launchd";
 import { LABEL } from "./state";
+import { assertNoDesktopSupervision, createSupervisionLatch, type SupervisionInspector, type SupervisionLatch } from "./desktop-command-guard";
 
 type ServiceOps = {
-  install: () => void | Promise<void>; start: () => void; stop: () => void;
+  install: (runtime: DurableBunRuntime) => void | Promise<void>; start: () => void; stop: () => void;
   status: () => string; uninstall: () => void;
 };
 
@@ -32,18 +35,19 @@ export type ServiceInstallCleanupOps = {
   stop: () => void;
 };
 
-export function platformOps(backend: ServiceBackend = "scheduler"): ServiceOps | null {
-  if (process.platform === "darwin")
+export function platformOps(backend: ServiceBackend = "scheduler", deps: { platform?: NodeJS.Platform; windowsInstall?: WindowsServiceInstallDeps } = {}): ServiceOps | null {
+  const platform = deps.platform ?? process.platform;
+  if (platform === "darwin")
     // Wrapped, not passed: `installLaunchd` reports whether it reloaded launchd, and only
     // `repairService` (for the `restart` verb) has any use for that. `ServiceOps.install` is
     // the generic install seam and deliberately promises nothing about a return value.
     return { install: () => { installLaunchd(); }, start: startLaunchd, stop: stopLaunchd, status: statusLaunchd, uninstall: uninstallLaunchd };
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     if (backend === "native")
-      return { install: installWindowsNative, start: startWinswService, stop: stopWinswService, status: winswStatusSummary, uninstall: uninstallWinswService };
-    return { install: installWindows, start: startWindows, stop: stopWindows, status: statusWindows, uninstall: uninstallWindows };
+      return { install: runtime => commitWindowsNativeInstall(runtime, deps.windowsInstall), start: startWinswService, stop: stopWinswService, status: winswStatusSummary, uninstall: uninstallWinswService };
+    return { install: runtime => commitWindowsInstall(runtime, deps.windowsInstall), start: startWindows, stop: stopWindows, status: statusWindows, uninstall: uninstallWindows };
   }
-  if (process.platform === "linux") {
+  if (platform === "linux") {
     if (existsSync("/.dockerenv")) {
       console.error("Docker detected. Run 'ocx start' directly instead of using the service manager.");
       process.exit(1);
@@ -229,7 +233,9 @@ export async function stopTrackedProxyForServiceCommand(): Promise<TrackedProxyC
   }
 }
 
-export interface ServiceInstallPreparationDeps {
+export interface ServiceInstallPreparationDeps extends RuntimePreflightDeps {
+  inspectSupervision?: SupervisionInspector;
+  supervisionLatch?: SupervisionLatch;
   diagnose?: () => ServiceDiagnostic;
   managerOps?: (backend: ServiceBackend) => ServiceInstallCleanupOps | null;
   stopTrackedProxy?: () => Promise<unknown>;
@@ -245,6 +251,8 @@ export async function prepareServiceInstall(
   requestedBackend: ServiceBackend,
   deps: ServiceInstallPreparationDeps = {},
 ): Promise<void> {
+  const latch = deps.supervisionLatch ?? createSupervisionLatch();
+  assertNoDesktopSupervision(deps.inspectSupervision, latch);
   const diagnostic = (deps.diagnose ?? diagnoseService)();
   const platform = deps.platform ?? process.platform;
   const resolveOps = deps.managerOps ?? platformServiceInstallCleanupOps;
@@ -276,27 +284,35 @@ export async function prepareServiceInstall(
 
 export async function installServiceSafely(
   requestedBackend: ServiceBackend,
-  install: () => void | Promise<void>,
+  install: (runtime: DurableBunRuntime) => void | Promise<void>,
   deps: ServiceInstallPreparationDeps = {},
 ): Promise<void> {
-  await prepareServiceInstall(requestedBackend, deps);
-  await install();
+  const latch = deps.supervisionLatch ?? createSupervisionLatch();
+  assertNoDesktopSupervision(deps.inspectSupervision, latch);
+  const runtime = Object.freeze({ ...(deps.selectRuntime ?? durableBunRuntime)() });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform: deps.platform, rootWasAbsent: !existsSync(configDir) });
+  await prepareServiceInstall(requestedBackend, { ...deps, supervisionLatch: latch });
+  assertNoDesktopSupervision(deps.inspectSupervision, latch);
+  await install(runtime);
 }
 
-export interface FreshWindowsSchedulerInstallDeps {
+export interface FreshWindowsSchedulerInstallDeps extends RuntimePreflightDeps {
+  inspectSupervision?: SupervisionInspector;
+  supervisionLatch?: SupervisionLatch;
   stageRegistrationXml?: (attemptNonce: string) => string;
   register?: (xmlPath: string, attemptNonce: string) => Promise<void>;
   recordOwnership?: () => boolean;
   prepare?: () => Promise<void>;
   removeNativeService?: () => void;
-  publishAssets?: () => void;
+  publishAssets?: (runtime: DurableBunRuntime) => void;
   verifyBeforeRun?: (attemptNonce: string) => void | Promise<void>;
   /** Reads the newly registered task; empty or throwing reads are retried before rollback. */
   readSchedulerXml?: () => string;
   /** Bounded wait before retrying an unreadable fresh-install registration. */
   settleSchedulerRead?: (delayMs: number) => void | Promise<void>;
   runTask?: () => void;
-  writeState?: () => void;
+  writeState?: (runtime: DurableBunRuntime) => void;
   rollbackTask?: (attemptNonce: string) => Promise<string | null>;
   removeStagedXml?: (xmlPath: string) => void;
 }
@@ -312,10 +328,14 @@ export interface FreshWindowsSchedulerInstallDeps {
 export async function installFreshWindowsSchedulerSafely(
   deps: FreshWindowsSchedulerInstallDeps = {},
 ): Promise<void> {
+  const latch = deps.supervisionLatch ?? createSupervisionLatch();
+  assertNoDesktopSupervision(deps.inspectSupervision, latch);
   const stage = deps.stageRegistrationXml ?? stageWindowsSchedulerRegistrationXml;
   const register = deps.register ?? registerFreshWindowsSchedulerTask;
   const recordOwnership = deps.recordOwnership ?? recordWindowsSchedulerOwnership;
-  const prepare = deps.prepare ?? (() => prepareServiceInstall("scheduler"));
+  const prepare = deps.prepare ?? (() => prepareServiceInstall("scheduler", {
+    inspectSupervision: deps.inspectSupervision, supervisionLatch: latch,
+  }));
   const removeNativeService = deps.removeNativeService ?? removeNativeWindowsServiceForScheduler;
   const publishAssets = deps.publishAssets ?? writeWindowsSchedulerAssets;
   const verifyBeforeRun = deps.verifyBeforeRun ?? ((nonce: string) => (
@@ -331,7 +351,7 @@ export async function installFreshWindowsSchedulerSafely(
     )
   ));
   const runTask = deps.runTask ?? startWindows;
-  const writeState = deps.writeState ?? (() => writeServiceInstallState("scheduler"));
+  const writeState = deps.writeState ?? ((runtime: DurableBunRuntime) => writeServiceInstallState("scheduler", undefined, {}, runtime));
   const rollbackTask = deps.rollbackTask ?? ((attemptNonce: string) => (
     rollbackWindowsSchedulerTaskOwnedByAttempt(attemptNonce, TASK)
   ));
@@ -341,13 +361,16 @@ export async function installFreshWindowsSchedulerSafely(
 
   let stagedXml: string | null = null;
   const attemptNonce = randomUUID();
-  const configRootWasAbsent = !existsSync(getConfigDir());
+  const configDir = (deps.configDir ?? getConfigDir)();
+  const configRootWasAbsent = !existsSync(configDir);
+  const runtime = Object.freeze({ ...(deps.selectRuntime ?? durableBunRuntime)() });
   let registered = false;
   let started = false;
   try {
     stagedXml = stage(attemptNonce);
     await register(stagedXml, attemptNonce);
     registered = true;
+    assertNoDesktopSupervision(deps.inspectSupervision, latch);
 
     // The destructive boundary begins only after Task Scheduler accepted the definition.
     // The registration has consumed its temporary XML. Remove it before claiming a newly
@@ -361,13 +384,16 @@ export async function installFreshWindowsSchedulerSafely(
         + "aborting before service-manager cleanup or asset publication.",
       );
     }
+    (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform: deps.platform, rootWasAbsent: false });
     await prepare();
+    assertNoDesktopSupervision(deps.inspectSupervision, latch);
     removeNativeService();
-    publishAssets();
+    publishAssets(runtime);
     await verifyBeforeRun(attemptNonce);
+    assertNoDesktopSupervision(deps.inspectSupervision, latch);
     runTask();
     started = true;
-    writeState();
+    writeState(runtime);
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     if (registered && !started) {

package/src/service/repair.ts

@@ -1,3 +1,7 @@
+import { existsSync } from "node:fs";
+import { getConfigDir } from "../config";
+import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
+import { assertSelectedRuntimeWritable, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
 import { randomUUID } from "node:crypto";
 import { defaultWinswEntry, installWinswService } from "../lib/winsw";
 import { resolveWindowsTaskDiagnosticUserId, diagnoseService } from "./diagnostics";
@@ -14,6 +18,7 @@ import type { WindowsSchedulerTaskProbe } from "./windows-scheduler";
 import { taskXmlSection, taskXmlWithoutCommentsAndCdata, taskXmlElementCount, taskXmlOptionalValueEquals, windowsTaskRegistrationOwnedByAttempt, windowsTaskHasSessionRecoveryTriggers, windowsTaskRegistrationHealthy, windowsTaskRegistrationRefreshableLegacy } from "./windows-taskxml";
 import type { ExpectedWindowsTaskUserId } from "./windows-taskxml";
 import { win32 } from "node:path";
+import { assertNoDesktopSupervision, createSupervisionLatch, type SupervisionInspector, type SupervisionLatch } from "./desktop-command-guard";
 
 /**
  * The two CLI verbs `repairService` serves. They differ on ONE platform and ONE case: a
@@ -22,16 +27,18 @@ import { win32 } from "node:path";
  */
 export type ServiceRepairVerb = "repair" | "restart";
 
-export interface RepairServiceDeps {
+export interface RepairServiceDeps extends RuntimePreflightDeps {
+  inspectSupervision?: SupervisionInspector;
+  supervisionLatch?: SupervisionLatch;
   diagnose?: () => ServiceDiagnostic;
   assertEnv?: () => void;
   assertAuth?: () => void;
-  writeSchedulerAssets?: () => void;
+  writeSchedulerAssets?: (runtime: DurableBunRuntime) => void;
   stopScheduler?: () => void;
   startScheduler?: () => void;
-  writeSchedulerState?: () => void;
-  writeNativeState?: () => void;
-  repairNative?: () => void | Promise<void>;
+  writeSchedulerState?: (runtime: DurableBunRuntime) => void;
+  writeNativeState?: (runtime: DurableBunRuntime) => void;
+  repairNative?: (runtime: DurableBunRuntime) => void | Promise<void>;
   repairLaunchd?: () => LaunchdInstallOutcome | void;
   repairSystemd?: () => void;
   /** Restarts a launchd job the install path deliberately left alone. `restart` only. */
@@ -148,6 +155,8 @@ export async function assertSchedulerRegistrationBeforeStart(
  * macOS/Linux: re-run the user-level install/reload path.
  */
 export async function repairService(deps: RepairServiceDeps = {}): Promise<void> {
+  const latch = deps.supervisionLatch ?? createSupervisionLatch();
+  assertNoDesktopSupervision(deps.inspectSupervision, latch);
   const diagnose = deps.diagnose ?? diagnoseService;
   const platform = deps.platform ?? process.platform;
   const diag = diagnose();
@@ -176,14 +185,18 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
 
   (deps.assertEnv ?? assertServiceEnvironmentMatchesInstall)();
   (deps.assertAuth ?? assertServiceAuthEnvironment)();
+  const runtime = Object.freeze({ ...(deps.selectRuntime ?? durableBunRuntime)() });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform, rootWasAbsent: !existsSync(configDir) });
 
   const temporaryLauncher = (deps.launcherPathDiagnostic ?? (() => serviceLauncherPathDiagnostic(undefined, platform, true)))();
   if (temporaryLauncher) console.warn(`⚠️ ${temporaryLauncher}`);
 
   if (platform === "win32") {
     if (diag.backend === "native") {
-      await (deps.repairNative ?? (() => installWinswService(defaultWinswEntry(serviceSourceDir))))();
-      (deps.writeNativeState ?? (() => writeServiceInstallState("native")))();
+      await (deps.repairNative ?? ((selected: DurableBunRuntime) => installWinswService(defaultWinswEntry(serviceSourceDir, selected))))(runtime);
+      assertNoDesktopSupervision(deps.inspectSupervision, latch);
+      (deps.writeNativeState ?? ((selected: DurableBunRuntime) => writeServiceInstallState("native", undefined, {}, selected)))(runtime);
       return;
     }
     const readSchedulerXml = deps.readSchedulerXml ?? statusWindowsXml;
@@ -243,7 +256,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
       );
     }
     try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
-    (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)();
+    (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)(runtime);
     // Rewriting the on-disk assets does not touch the definition Task Scheduler holds, so a
     // task registered by an older version keeps its old triggers forever: status reports it
     // stale, tells the user to run repair, and repair changes nothing it complains about.
@@ -311,6 +324,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
             }
             if (probe.status === "absent") {
               try {
+                assertNoDesktopSupervision(deps.inspectSupervision, latch);
                 await (deps.restoreSchedulerIfAbsent ?? restoreWindowsSchedulerTaskIfAbsent)(registeredXml);
                 restartExpectedXml = registeredXml;
               } catch (error) {
@@ -333,6 +347,7 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
               "The Task Scheduler registration changed again before restart; the newer definition was preserved and not started.",
               "Task Scheduler state remained unreadable before restart; the registration was preserved and not started.",
             );
+            assertNoDesktopSupervision(deps.inspectSupervision, latch);
             (deps.startScheduler ?? startWindows)();
           } catch (error) {
             recoveryErrors.push(error);
@@ -358,8 +373,9 @@ export async function repairService(deps: RepairServiceDeps = {}): Promise<void>
       "Task Scheduler registration changed before restart; the current definition was preserved and not started.",
       "Task Scheduler registration became unreadable before restart; it was preserved and not started.",
     );
+    assertNoDesktopSupervision(deps.inspectSupervision, latch);
     (deps.startScheduler ?? startWindows)();
-    (deps.writeSchedulerState ?? (() => writeServiceInstallState("scheduler")))();
+    (deps.writeSchedulerState ?? ((selected: DurableBunRuntime) => writeServiceInstallState("scheduler", undefined, {}, selected)))(runtime);
     return;
   }
   if (platform === "darwin") {

package/src/service/state.ts

@@ -360,8 +360,8 @@ export function parseServiceInstallState(value: unknown): ServiceInstallState |
  * it describes the install that just ran. {@link ServiceInstallState.ownership} deliberately
  * is not part of it.
  */
-function installProvenanceRecord(backend: ServiceBackend, launcherPath?: string | null): ServiceInstallState {
-  const { bun, cli } = cliEntry();
+function installProvenanceRecord(backend: ServiceBackend, launcherPath: string | null | undefined, runtime: DurableBunRuntime): ServiceInstallState {
+  const { bun, cli } = cliEntry(runtime);
   const codexHome = currentCodexHome();
   return {
     version: 2,
@@ -391,9 +391,10 @@ export function writeServiceInstallState(
   backend: ServiceBackend = "scheduler",
   launcherPath?: string | null,
   deps: ServiceStateSwapDeps = {},
+  runtime: DurableBunRuntime = durableBunRuntime(),
 ): void {
   swapServiceInstallState(current => ({
-    ...installProvenanceRecord(backend, launcherPath),
+    ...installProvenanceRecord(backend, launcherPath, runtime),
     ...preservedConsent(current),
   }), deps);
 }

package/src/service/systemd.ts

@@ -102,13 +102,22 @@ WantedBy=default.target
 
 /** The per-user runtime dir systemd creates (holds the user-bus socket), or null. */
 function userRuntimeDir(): string | null {
-  const fromEnv = process.env.XDG_RUNTIME_DIR;
-  if (fromEnv && existsSync(fromEnv)) return fromEnv;
-  if (typeof process.getuid === "function") {
-    const candidate = `/run/user/${process.getuid()}`;
-    if (existsSync(candidate)) return candidate;
+  const env = { ...process.env };
+  if (env.XDG_RUNTIME_DIR && !existsSync(env.XDG_RUNTIME_DIR)) delete env.XDG_RUNTIME_DIR;
+  return systemdUserBusEnvironment(env).XDG_RUNTIME_DIR || null;
+}
+
+/** Return explicit SSH user-bus discovery without changing the caller's environment. */
+export function systemdUserBusEnvironment(environment: NodeJS.ProcessEnv = process.env, deps: {
+  uid?: number; exists?: (path: string) => boolean;
+} = {}): NodeJS.ProcessEnv {
+  const env = { ...environment };
+  if (!env.XDG_RUNTIME_DIR) {
+    const uid = deps.uid ?? process.getuid?.();
+    const candidate = uid === undefined ? null : `/run/user/${uid}`;
+    if (candidate && (deps.exists ?? existsSync)(candidate)) env.XDG_RUNTIME_DIR = candidate;
   }
-  return null;
+  return env;
 }
 
 /**
@@ -119,8 +128,8 @@ function userRuntimeDir(): string | null {
  */
 function ensureUserBusEnv(): void {
   if (process.env.XDG_RUNTIME_DIR) return;
-  const dir = userRuntimeDir();
-  if (dir) process.env.XDG_RUNTIME_DIR = dir;
+  const env = systemdUserBusEnvironment();
+  if (env.XDG_RUNTIME_DIR) process.env.XDG_RUNTIME_DIR = env.XDG_RUNTIME_DIR;
 }
 
 export function isSystemd(): boolean {

package/src/service/windows-ops.ts

@@ -3,6 +3,8 @@ import { createHash } from "node:crypto";
 import { win32 } from "node:path";
 import { winswXmlPath } from "../lib/winsw";
 import { hardenSecretPath } from "../lib/windows-secret-acl";
+import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
+import { assertSelectedRuntimeWritable, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
 import { parseBakedListenPort } from "./health";
 import { windowsServiceScriptPath } from "./state";
 import { execFileSync } from "node:child_process";
@@ -18,7 +20,7 @@ import { killWindowsSchedulerWrappers } from "../lib/windows-service-wrappers";
 import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 import { writeServiceApiTokenFile } from "./guards";
 import type { ServiceStopOutcome } from "./orchestration";
-import { TASK, windowsLauncherVbsPath, windowsTaskXmlPath, serviceStatePath, writeServiceInstallState, serviceSourceDir } from "./state";
+import { TASK, windowsLauncherVbsPath, windowsTaskXmlPath, serviceStatePath, writeServiceInstallState, serviceSourceDir, cliEntry } from "./state";
 import { decodeSchtasksOutput, querySchtasks, schtasks, type WindowsSchedulerTaskProbe, schtasksErrorDetail, probeWindowsSchedulerTask, rollbackWindowsSchedulerTaskOwnedByAttempt } from "./windows-scheduler";
 import { buildWindowsServiceScript, buildWindowsSchtasksCreateArgs, buildWindowsSchtasksCreateArgsForXml, buildWindowsLauncherVbs, resolvedWindowsTaskSid, buildWindowsTaskXmlDocument, windowsTaskRegistrationOwnedByAttempt, windowsTaskRegistrationHealthy } from "./windows-taskxml";
 
@@ -108,11 +110,11 @@ function writeServiceAssetWithRetry(path: string, content: string, encoding: "ut
  * Rewrite on-disk scheduler assets (script/VBS/XML) without itself registering the task.
  * Fresh install creates it afterwards; repair does so only when the live definition is stale.
  */
-export function writeWindowsSchedulerAssets(): void {
+export function writeWindowsSchedulerAssets(runtime: DurableBunRuntime = durableBunRuntime()): void {
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   writeServiceApiTokenFile();
   const script = windowsServiceScriptPath();
-  writeServiceAssetWithRetry(script, buildWindowsServiceScript(), "utf8");
+  writeServiceAssetWithRetry(script, buildWindowsServiceScript(cliEntry(runtime)), "utf8");
   // UTF-16LE + BOM: a BOM-less UTF-8 VBS mis-decodes non-ASCII (e.g. Korean) profile
   // paths on some WSH/codepage combinations — same contract as the task XML below.
   writeServiceAssetWithRetry(windowsLauncherVbsPath(), `\uFEFF${buildWindowsLauncherVbs(script)}`, "utf16le");
@@ -597,16 +599,40 @@ export function removeNativeWindowsServiceForScheduler(
   }
 }
 
-export function installWindows(): void {
-  recordWindowsSchedulerOwnership();
-  removeNativeWindowsServiceForScheduler();
+/** External Windows effects shared by the gated entrypoints and admitted commit paths. */
+export interface WindowsServiceInstallDeps extends RuntimePreflightDeps {
+  recordSchedulerOwnership?: () => boolean;
+  removeNativeService?: () => void;
+  stopScheduler?: () => void;
+  writeSchedulerAssets?: (runtime: DurableBunRuntime) => void;
+  schedulerCommand?: typeof schtasks;
+  writeState?: (backend: "scheduler" | "native", runtime: DurableBunRuntime) => void;
+  assertNativeAccount?: () => void;
+  prepareNativeConfig?: () => void;
+  uninstallScheduler?: () => void;
+  installNativeService?: typeof installWinswService;
+}
+
+export function installWindows(selected?: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): void {
+  const runtime = Object.freeze({ ...(selected ?? (deps.selectRuntime ?? durableBunRuntime)()) });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform: deps.platform, rootWasAbsent: !existsSync(configDir) });
+  commitWindowsInstall(runtime, deps);
+}
+
+/** Internal commit boundary: the caller has admitted this frozen runtime before cleanup. */
+export function commitWindowsInstall(runtime: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): void {
+  (deps.recordSchedulerOwnership ?? recordWindowsSchedulerOwnership)();
+  (deps.removeNativeService ?? removeNativeWindowsServiceForScheduler)();
   // End a running task BEFORE rewriting the assets it is executing — cmd.exe reading the
   // script mid-rewrite runs a torn batch file, and its open handle can fail the write.
-  try { stopWindows(); } catch { /* not running */ }
-  writeWindowsSchedulerAssets();
-  schtasks(buildWindowsSchtasksCreateArgs(windowsServiceScriptPath()));
-  schtasks(["/run", "/tn", TASK]);
-  writeServiceInstallState("scheduler");
+  try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
+  (deps.writeSchedulerAssets ?? writeWindowsSchedulerAssets)(runtime);
+  const command = deps.schedulerCommand ?? schtasks;
+  command(buildWindowsSchtasksCreateArgs(windowsServiceScriptPath()));
+  command(["/run", "/tn", TASK]);
+  if (deps.writeState) deps.writeState("scheduler", runtime);
+  else writeServiceInstallState("scheduler", undefined, {}, runtime);
 }
 
 /**
@@ -748,26 +774,38 @@ function readWindowsPrincipalSource(): string | null {
   }
 }
 
-export async function installWindowsNative(): Promise<void> {
-  assertWindowsNativeServiceAccountSupported();
-  recordOwnedConfigPath(getConfigDir(), serviceStatePath());
-  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
-  writeServiceApiTokenFile();
+export async function installWindowsNative(selected?: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): Promise<void> {
+  const runtime = Object.freeze({ ...(selected ?? (deps.selectRuntime ?? durableBunRuntime)()) });
+  const configDir = (deps.configDir ?? getConfigDir)();
+  (deps.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { platform: deps.platform, rootWasAbsent: !existsSync(configDir) });
+  await commitWindowsNativeInstall(runtime, deps);
+}
+
+/** Internal commit boundary; direct native installs go through the public admission gate. */
+export async function commitWindowsNativeInstall(runtime: DurableBunRuntime, deps: WindowsServiceInstallDeps = {}): Promise<void> {
+  (deps.assertNativeAccount ?? assertWindowsNativeServiceAccountSupported)();
+  if (deps.prepareNativeConfig) deps.prepareNativeConfig();
+  else {
+    recordOwnedConfigPath(getConfigDir(), serviceStatePath());
+    if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+    writeServiceApiTokenFile();
+  }
+  const command = deps.schedulerCommand ?? schtasks;
   let hadScheduler = false;
   try {
-    hadScheduler = schtasks(["/query", "/tn", TASK]).includes(TASK);
+    hadScheduler = command(["/query", "/tn", TASK]).includes(TASK);
   } catch { /* task absent */ }
   if (hadScheduler) {
     console.log("🔁 Removing the Task Scheduler backend before installing the native (WinSW) service...");
-    try { stopWindows(); } catch { /* not running */ }
+    try { (deps.stopScheduler ?? stopWindows)(); } catch { /* not running */ }
     try {
-      uninstallWindows();
+      (deps.uninstallScheduler ?? uninstallWindows)();
     } catch (err) {
       throw new Error(`Cannot remove the Task Scheduler backend before switching to native: ${err instanceof Error ? err.message : String(err)}`);
     }
     // Verify removal — schtasks /delete can silently fail if UAC or policy blocks it.
     try {
-      if (schtasks(["/query", "/tn", TASK]).includes(TASK)) {
+      if (command(["/query", "/tn", TASK]).includes(TASK)) {
         throw new Error("Task Scheduler backend still present after removal — aborting switch.");
       }
     } catch (e) {
@@ -776,12 +814,13 @@ export async function installWindowsNative(): Promise<void> {
     }
   }
   try {
-    await installWinswService(defaultWinswEntry(serviceSourceDir));
+    await (deps.installNativeService ?? installWinswService)(defaultWinswEntry(serviceSourceDir, runtime));
   } catch (err) {
     if (hadScheduler) console.error("⚠️  Native install failed AFTER removing the Task Scheduler backend — no service is installed now. Run `ocx service install` to restore the scheduler backend, or retry `--native`.");
     throw err;
   }
-  writeServiceInstallState("native");
+  if (deps.writeState) deps.writeState("native", runtime);
+  else writeServiceInstallState("native", undefined, {}, runtime);
 }
 
 export function startWindows(): void { schtasks(["/run", "/tn", TASK]); }