@algosuite/vo-mcp 0.2.0-beta.46 → 0.2.0-beta.49

package/dist/install-cli.js

@@ -2,9 +2,9 @@
 import { createRequire as __cr } from 'module'; const require = __cr(import.meta.url);
 
 // src/install.ts
-import { homedir as homedir3, platform as platform3 } from "node:os";
-import { join as join4, dirname as dirname3 } from "node:path";
-import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4, copyFileSync as copyFileSync3 } from "node:fs";
+import { homedir as homedir4, platform as platform3 } from "node:os";
+import { join as join6, dirname as dirname4 } from "node:path";
+import { existsSync as existsSync6, readFileSync as readFileSync6, mkdirSync as mkdirSync5, statSync as statSync3 } from "node:fs";
 import { fileURLToPath } from "node:url";
 
 // src/cloud/pairing.ts
@@ -198,13 +198,215 @@ async function runPairing(deps = {}) {
 }
 
 // src/codex-mcp-config.ts
-import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join2 } from "node:path";
+import { existsSync as existsSync4, mkdirSync as mkdirSync3, readFileSync as readFileSync4, statSync as statSync2 } from "node:fs";
+import { dirname as dirname3, join as join4 } from "node:path";
+
+// src/config-backup.ts
+import { chmodSync as chmodSync2, copyFileSync, existsSync as existsSync2, readdirSync, readFileSync as readFileSync2, renameSync, statSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { basename, dirname as dirname2, join as join2 } from "node:path";
+var BACKUP_SUFFIX_RE = /^\.backup-\d+$/u;
+var TEMP_SUFFIX_RE = /^\.vo-mcp-tmp-\d+-\d+$/u;
+var RENAME_RETRIES = 5;
+var RENAME_RETRY_MS = 50;
+function sweepStaleTempFiles(configPath) {
+  const dir = dirname2(configPath);
+  const name = basename(configPath);
+  if (!existsSync2(dir)) return 0;
+  let removed = 0;
+  for (const entry of readdirSync(dir)) {
+    if (!entry.startsWith(name) || !TEMP_SUFFIX_RE.test(entry.slice(name.length))) continue;
+    try {
+      unlinkSync(join2(dir, entry));
+      removed += 1;
+    } catch {
+    }
+  }
+  return removed;
+}
+function sleepSync(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function hasIdenticalBackup(configPath, content) {
+  const dir = dirname2(configPath);
+  const name = basename(configPath);
+  if (!existsSync2(dir)) return false;
+  const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, "utf8");
+  for (const entry of readdirSync(dir)) {
+    if (!entry.startsWith(name) || !BACKUP_SUFFIX_RE.test(entry.slice(name.length))) continue;
+    const candidate = join2(dir, entry);
+    try {
+      if (statSync(candidate).size !== buffer.length) continue;
+      if (readFileSync2(candidate).equals(buffer)) return true;
+    } catch {
+    }
+  }
+  return false;
+}
+function backupConfigOnce(configPath) {
+  if (!existsSync2(configPath)) return null;
+  const current = readFileSync2(configPath);
+  if (hasIdenticalBackup(configPath, current)) return null;
+  const backupPath = `${configPath}.backup-${Date.now()}`;
+  copyFileSync(configPath, backupPath);
+  return backupPath;
+}
+function writeFileAtomic(path, content) {
+  sweepStaleTempFiles(path);
+  const temp = `${path}.vo-mcp-tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync2(temp, content, { encoding: "utf8", mode: 384 });
+    if (existsSync2(path)) {
+      try {
+        chmodSync2(temp, statSync(path).mode & 511);
+      } catch {
+      }
+    }
+    let lastErr = null;
+    for (let attempt = 0; attempt < RENAME_RETRIES; attempt += 1) {
+      try {
+        renameSync(temp, path);
+        return;
+      } catch (err) {
+        lastErr = err;
+        const code = err.code;
+        if (code !== "EPERM" && code !== "EBUSY" && code !== "EACCES") throw err;
+        sleepSync(RENAME_RETRY_MS);
+      }
+    }
+    writeFileSync2(path, content, "utf8");
+    try {
+      unlinkSync(temp);
+    } catch {
+    }
+    void lastErr;
+  } catch (err) {
+    try {
+      unlinkSync(temp);
+    } catch {
+    }
+    throw err;
+  }
+}
+
+// src/mcp-launcher.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { homedir as homedir2, platform as osPlatform } from "node:os";
+import { isAbsolute, join as join3, normalize, resolve, sep, posix as pathPosix, win32 as pathWin32 } from "node:path";
+var MCP_LAUNCHER_FILE = "vo-mcp-launcher.mjs";
+var MCP_FALLBACK_CLI_ENV = "VO_MCP_FALLBACK_CLI";
+var APP_IDENTIFIER = "ai.algosuite.vo-runner";
+var RUNNER_RUNTIME_DIR = "runner-runtime";
+function defaultRunnerRuntimeRoot(env = process.env, { platform: platform4 = osPlatform(), home = homedir2() } = {}) {
+  const explicit = String(env["VO_RUNNER_RUNTIME_ROOT"] || "").trim();
+  if (explicit) return isAbsolute(explicit) ? resolve(explicit) : null;
+  if (platform4 === "win32") {
+    const appData = String(env["APPDATA"] || "").trim();
+    return appData && isAbsolute(appData) ? resolve(join3(appData, APP_IDENTIFIER, RUNNER_RUNTIME_DIR)) : null;
+  }
+  if (!home) return null;
+  if (platform4 === "darwin") return resolve(join3(home, "Library", "Application Support", APP_IDENTIFIER, RUNNER_RUNTIME_DIR));
+  const xdg = String(env["XDG_CONFIG_HOME"] || "").trim();
+  return resolve(join3(xdg && isAbsolute(xdg) ? xdg : join3(home, ".config"), APP_IDENTIFIER, RUNNER_RUNTIME_DIR));
+}
+function mcpLauncherPath(runtimeRoot) {
+  return join3(runtimeRoot, MCP_LAUNCHER_FILE);
+}
+function renderMcpLauncher() {
+  return `#!/usr/bin/env node
+// Written by \`vo-mcp install\` / the runner daemon (F24, 2026-08-16). Claude's and Codex's vo-mcp MCP
+// server entries point here so every MCP spawn runs the ACTIVE runner runtime slot \u2014 the fleet-approved
+// vo-mcp \u2014 instead of whatever copy \`install\` happened to run from. Resolution: this file's directory,
+// then an ABSOLUTE VO_RUNNER_RUNTIME_ROOT -> current.json (schema 1) active slot -> previous slot ->
+// ${MCP_FALLBACK_CLI_ENV} (a non-slot package cli.js) -> exit 2.
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+const SLOT_ID_RE = /^vo-mcp-[0-9A-Za-z._-]{1,96}$/u;
+const here = dirname(fileURLToPath(import.meta.url));
+const envRoot = String(process.env.VO_RUNNER_RUNTIME_ROOT || '').trim();
+const ROOTS = [here, ...(envRoot && isAbsolute(envRoot) && envRoot !== here ? [envRoot] : [])];
+const FALLBACK_CLI = process.env.${MCP_FALLBACK_CLI_ENV} || '';
+function slotCli(root, slotId) {
+  if (typeof slotId !== 'string' || !SLOT_ID_RE.test(slotId)) return null;
+  const cli = join(root, 'slots', slotId, 'node_modules', '@algosuite', 'vo-mcp', 'dist', 'cli.js');
+  return existsSync(cli) ? cli : null;
+}
+function rootCli(root) {
+  try {
+    const cur = JSON.parse(readFileSync(join(root, 'current.json'), 'utf8'));
+    if (!cur || cur.schema_version !== 1) return null;
+    return slotCli(root, cur.active && cur.active.slot_id) || slotCli(root, cur.previous && cur.previous.slot_id);
+  } catch { return null; }
+}
+// Floor: no usable pointer (quarantined by a bootstrap rollback, corrupt, or a
+// future schema) must not leave every agent without MCP \u2014 run the NEWEST slot
+// on disk that carries a cli.js, and say so on stderr.
+function newestSlotCli(root) {
+  try {
+    const dir = join(root, 'slots');
+    const found = readdirSync(dir).filter((id) => SLOT_ID_RE.test(id) && slotCli(root, id))
+      .map((id) => ({ id, mtime: statSync(join(dir, id)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+    return found.length ? slotCli(root, found[0].id) : null;
+  } catch { return null; }
+}
+let target = null;
+for (const root of ROOTS) { target = rootCli(root); if (target) break; }
+if (!target) {
+  for (const root of ROOTS) { target = newestSlotCli(root); if (target) { process.stderr.write('[vo-mcp-launcher] no usable runtime pointer \u2014 using the newest slot on disk\\n'); break; } }
+}
+if (!target && FALLBACK_CLI && existsSync(FALLBACK_CLI)) target = FALLBACK_CLI;
+if (!target) { process.stderr.write('[vo-mcp-launcher] no runner runtime slot and no fallback cli\\n'); process.exit(2); }
+process.stderr.write(\`[vo-mcp-launcher] \${target}\\n\`);
+await import(pathToFileURL(target).href);
+`;
+}
+function writeMcpLauncher(runtimeRoot) {
+  mkdirSync2(runtimeRoot, { recursive: true });
+  const target = mcpLauncherPath(runtimeRoot);
+  const content = renderMcpLauncher();
+  if (!existsSync3(target) || readFileSync3(target, "utf8") !== content) writeFileSync3(target, content, "utf8");
+  return target;
+}
+function samePath(a, b, platform4 = osPlatform()) {
+  const pathModule = platform4 === "win32" ? pathWin32 : pathPosix;
+  const norm = (p) => {
+    const slashed = pathModule.normalize(p).replace(/\\/g, "/").replace(/\/+$/u, "");
+    return platform4 === "win32" || platform4 === "darwin" ? slashed.toLowerCase() : slashed;
+  };
+  return norm(a) === norm(b);
+}
+function isNotLauncherEntry(entry, launcherPath, platform4) {
+  const first = entry?.args && entry.args.length > 0 ? String(entry.args[0]) : "";
+  return !first || !samePath(first, launcherPath, platform4);
+}
+function isStaleVoMcpEntry(entry, launcherPath, fallbackCli, platform4) {
+  if (!entry || isNotLauncherEntry(entry, launcherPath, platform4)) return true;
+  const recorded = String(entry.env?.[MCP_FALLBACK_CLI_ENV] ?? "").trim();
+  if (!fallbackCli) return recorded !== "";
+  return !recorded || !samePath(recorded, fallbackCli, platform4);
+}
+function isSlotCli(cliPath, runtimeRoot = null) {
+  if (runtimeRoot) {
+    const prefix = normalize(join3(runtimeRoot, "slots")) + sep;
+    const candidate = normalize(cliPath);
+    const under = process.platform === "win32" ? candidate.toLowerCase().startsWith(prefix.toLowerCase()) : candidate.startsWith(prefix);
+    return under && /^vo-mcp-[0-9A-Za-z._-]{1,96}$/u.test(candidate.slice(prefix.length).split(/[\\/]/u)[0] ?? "");
+  }
+  return /[\\/]slots[\\/]vo-mcp-[0-9A-Za-z._-]{1,96}[\\/]/iu.test(cliPath);
+}
+function chooseFallbackCli(existing, cliPath, sticky, runtimeRoot = null) {
+  const current = String(existing ?? "").trim();
+  if (sticky && current && !isSlotCli(current, runtimeRoot) && existsSync3(current)) return current;
+  return isSlotCli(cliPath, runtimeRoot) ? null : cliPath;
+}
+
+// src/codex-mcp-config.ts
 var MANAGED_BEGIN = "# BEGIN AlgoHQ MCP (managed by vo-mcp install)";
 var MANAGED_END = "# END AlgoHQ MCP (managed by vo-mcp install)";
 var MANAGED_SERVER_NAMES = /* @__PURE__ */ new Set(["algohq", "vo", "vo-mcp", "vo_mcp"]);
 function resolveCodexConfigPath(home) {
-  return join2(home, ".codex", "config.toml");
+  return join4(home, ".codex", "config.toml");
 }
 function normalizeKey(value) {
   const trimmed = value.trim();
@@ -260,7 +462,27 @@ function preservedSectionLines(lines, section, managedKeys) {
     return key === null || !managedKeys.has(key);
   }).filter((line, index, all) => line.trim() !== "" || index > 0 && index < all.length - 1);
 }
-function renderCodexMcpConfig(raw, cliPath, controlPlaneUrl) {
+function readCodexManagedEnv(configPath, key) {
+  if (!existsSync4(configPath)) return void 0;
+  const raw = readFileSync4(configPath, "utf8");
+  const lines = raw.split(/\r?\n/);
+  const sections = tableSections(lines);
+  const envSection = sections.find((section) => isManagedSection(section) && section.path[2] === "env");
+  if (!envSection) return void 0;
+  for (const line of lines.slice(envSection.start + 1, envSection.end)) {
+    if (assignmentKey(line) !== key) continue;
+    const match = /=\s*("(?:[^"\\]|\\.)*")\s*(?:#.*)?$/.exec(line);
+    if (!match?.[1]) return void 0;
+    try {
+      const value = JSON.parse(match[1]);
+      return typeof value === "string" ? value : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+function renderCodexMcpConfig(raw, cliPath, controlPlaneUrl, managedEnv = {}) {
   if (!isStructurallySafeToml(raw)) {
     throw new Error("Codex config is malformed; refusing to overwrite it");
   }
@@ -272,12 +494,10 @@ function renderCodexMcpConfig(raw, cliPath, controlPlaneUrl) {
   const preferredName = preferredRoot?.path[1];
   const envSection = sections.find((section) => isManagedSection(section) && section.path[1] === preferredName && section.path[2] === "env");
   const rootExtras = preservedSectionLines(lines, preferredRoot, /* @__PURE__ */ new Set(["command", "args", "required"]));
-  const envExtras = preservedSectionLines(lines, envSection, /* @__PURE__ */ new Set(["VO_CONTROL_PLANE_URL"]));
+  const envExtras = preservedSectionLines(lines, envSection, /* @__PURE__ */ new Set(["VO_CONTROL_PLANE_URL", MCP_FALLBACK_CLI_ENV, ...Object.keys(managedEnv)]));
   const removed = /* @__PURE__ */ new Set();
-  const managedBegin = lines.findIndex((line) => line.trim() === MANAGED_BEGIN);
-  const managedEnd = lines.findIndex((line) => line.trim() === MANAGED_END);
-  if (managedBegin >= 0 && managedEnd >= managedBegin) {
-    for (let index = managedBegin; index <= managedEnd; index += 1) removed.add(index);
+  for (const [index, line] of lines.entries()) {
+    if (line.trim() === MANAGED_BEGIN || line.trim() === MANAGED_END) removed.add(index);
   }
   for (const section of sections.filter(isManagedSection)) {
     for (let index = section.start; index < section.end; index += 1) removed.add(index);
@@ -293,43 +513,43 @@ function renderCodexMcpConfig(raw, cliPath, controlPlaneUrl) {
     "",
     "[mcp_servers.algohq.env]",
     `VO_CONTROL_PLANE_URL = ${tomlString(controlPlaneUrl)}`,
+    ...Object.entries(managedEnv).map(([key, value]) => `${key} = ${tomlString(value)}`),
     ...envExtras,
     MANAGED_END
   ].join(eol);
   return `${base}${base ? `${eol}${eol}` : ""}${block}${eol}`;
 }
-function installCodexMcpConfigAt(configPath, cliPath, controlPlaneUrl, log) {
-  const exists = existsSync2(configPath);
-  const raw = exists ? readFileSync2(configPath, "utf8") : "";
+function installCodexMcpConfigAt(configPath, cliPath, controlPlaneUrl, log, managedEnv = {}) {
+  const exists = existsSync4(configPath);
+  const readMtime = exists ? statSync2(configPath).mtimeMs : null;
+  const raw = exists ? readFileSync4(configPath, "utf8") : "";
   let rendered;
   try {
-    rendered = renderCodexMcpConfig(raw, cliPath, controlPlaneUrl);
+    rendered = renderCodexMcpConfig(raw, cliPath, controlPlaneUrl, managedEnv);
   } catch (error) {
-    if (exists) {
-      const backupPath = `${configPath}.backup-${Date.now()}`;
-      copyFileSync(configPath, backupPath);
-      log(`  Backed up malformed Codex config \u2192 ${backupPath}`);
-    }
+    const backupPath2 = backupConfigOnce(configPath);
+    if (backupPath2) log(`  Backed up malformed Codex config \u2192 ${backupPath2}`);
     throw error;
   }
   if (rendered === raw) {
     log(`  Codex already current: ${configPath}`);
     return;
   }
-  if (exists) {
-    const backupPath = `${configPath}.backup-${Date.now()}`;
-    copyFileSync(configPath, backupPath);
-    log(`  Backed up Codex config \u2192 ${backupPath}`);
+  if (readMtime !== null && (!existsSync4(configPath) || statSync2(configPath).mtimeMs !== readMtime)) {
+    log(`  \u26A0 Codex config changed while updating \u2014 left untouched this time: ${configPath}`);
+    return;
   }
-  mkdirSync2(dirname2(configPath), { recursive: true });
-  writeFileSync2(configPath, rendered, "utf8");
+  const backupPath = backupConfigOnce(configPath);
+  if (backupPath) log(`  Backed up Codex config \u2192 ${backupPath}`);
+  mkdirSync3(dirname3(configPath), { recursive: true });
+  writeFileAtomic(configPath, rendered);
   log(`\u2713 Wrote AlgoHQ MCP to Codex: ${configPath}`);
 }
 
 // src/autostart.ts
-import { homedir as homedir2, platform as platform2 } from "node:os";
-import { isAbsolute, join as join3 } from "node:path";
-import { existsSync as existsSync3, mkdirSync as mkdirSync3, writeFileSync as writeFileSync3, readFileSync as readFileSync3, unlinkSync, copyFileSync as copyFileSync2 } from "node:fs";
+import { homedir as homedir3, platform as platform2 } from "node:os";
+import { isAbsolute as isAbsolute2, join as join5 } from "node:path";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, writeFileSync as writeFileSync4, readFileSync as readFileSync5, unlinkSync as unlinkSync2, copyFileSync as copyFileSync2 } from "node:fs";
 var WINDOWS_RESTART_BACKOFF_MS = 1e4;
 var WINDOWS_HEALTHY_RUN_MS = 6e4;
 var WINDOWS_MAX_BACKOFF_MS = 3e5;
@@ -344,25 +564,25 @@ function quotePosixShellArgument(value) {
 }
 function resolveLinuxConfigHome(home, env) {
   const configured = env["XDG_CONFIG_HOME"]?.trim();
-  return configured && isAbsolute(configured) ? configured : join3(home, ".config");
+  return configured && isAbsolute2(configured) ? configured : join5(home, ".config");
 }
 function launcherIsCurrent(path, desiredContent, label, log) {
-  if (!existsSync3(path)) return false;
-  if (readFileSync3(path, "utf8") === desiredContent) return true;
+  if (!existsSync5(path)) return false;
+  if (readFileSync5(path, "utf8") === desiredContent) return true;
   const backupPath = `${path}.backup-${Date.now()}`;
   copyFileSync2(path, backupPath);
   log(`  Backed up existing ${label} to: ${backupPath}`);
   return false;
 }
 function installWindowsAutostart(runnerCommand, log, env) {
-  const appData = env["APPDATA"] ?? join3(homedir2(), "AppData", "Roaming");
-  const startupDir = join3(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
-  mkdirSync3(startupDir, { recursive: true });
-  const launcherPath = join3(startupDir, "vo-runner.vbs");
-  const legacyCmdPath = join3(startupDir, "vo-runner.cmd");
-  if (existsSync3(legacyCmdPath)) {
+  const appData = env["APPDATA"] ?? join5(homedir3(), "AppData", "Roaming");
+  const startupDir = join5(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
+  mkdirSync4(startupDir, { recursive: true });
+  const launcherPath = join5(startupDir, "vo-runner.vbs");
+  const legacyCmdPath = join5(startupDir, "vo-runner.cmd");
+  if (existsSync5(legacyCmdPath)) {
     try {
-      unlinkSync(legacyCmdPath);
+      unlinkSync2(legacyCmdPath);
       log(`  Removed legacy minimized .cmd launcher: ${legacyCmdPath}`);
     } catch (error) {
       log(`\u26A0 Could not remove legacy launcher ${legacyCmdPath} (${error instanceof Error ? error.message : String(error)}); remove it manually to avoid a double start`);
@@ -403,16 +623,16 @@ Loop
     log(`  Path: ${launcherPath}`);
     return;
   }
-  writeFileSync3(launcherPath, launcherContent, "utf8");
+  writeFileSync4(launcherPath, launcherContent, "utf8");
   log(`\u2713 Installed Windows auto-start launcher`);
   log(`  Path: ${launcherPath}`);
   log(`  The runner will start hidden at next login.`);
 }
 async function installMacAutostart(runnerCommand, log, env) {
-  const home = env["HOME"]?.trim() || homedir2();
-  const launchAgentsDir = join3(home, "Library", "LaunchAgents");
-  mkdirSync3(launchAgentsDir, { recursive: true });
-  const plistPath = join3(launchAgentsDir, "ai.algosuite.vo-runner.plist");
+  const home = env["HOME"]?.trim() || homedir3();
+  const launchAgentsDir = join5(home, "Library", "LaunchAgents");
+  mkdirSync4(launchAgentsDir, { recursive: true });
+  const plistPath = join5(launchAgentsDir, "ai.algosuite.vo-runner.plist");
   const parts = runnerCommand.split(/\s+/);
   const program = parts[0] ?? "vo-mcp";
   const args = parts.length > 1 ? parts.slice(1) : ["runner"];
@@ -436,12 +656,12 @@ ${args.map((a) => `    <string>${a}</string>`).join("\n")}
   <key>EnvironmentVariables</key>
   <dict>
     <key>VO_CODE_RUNNER_CLONES_ROOT</key>
-    <string>${join3(home, "Library", "Application Support", "ai.algosuite.vo-runner", "clones")}</string>
+    <string>${join5(home, "Library", "Application Support", "ai.algosuite.vo-runner", "clones")}</string>
   </dict>
   <key>StandardOutPath</key>
-  <string>${join3(home, ".claude", "vo-runner.log")}</string>
+  <string>${join5(home, ".claude", "vo-runner.log")}</string>
   <key>StandardErrorPath</key>
-  <string>${join3(home, ".claude", "vo-runner-error.log")}</string>
+  <string>${join5(home, ".claude", "vo-runner-error.log")}</string>
 </dict>
 </plist>
 `;
@@ -450,29 +670,29 @@ ${args.map((a) => `    <string>${a}</string>`).join("\n")}
     log(`  Path: ${plistPath}`);
     return;
   }
-  writeFileSync3(plistPath, plistContent, "utf8");
+  writeFileSync4(plistPath, plistContent, "utf8");
   log(`\u2713 Installed launchd plist`);
   log(`  Path: ${plistPath}`);
   try {
     const { execSync } = await import("node:child_process");
     execSync(`launchctl load "${plistPath}"`, { stdio: "ignore" });
     log(`\u2713 Loaded plist with launchctl (runner will start at next login)`);
-    log(`  Logs: ${join3(home, ".claude", "vo-runner.log")}`);
+    log(`  Logs: ${join5(home, ".claude", "vo-runner.log")}`);
   } catch {
     log(`\u26A0 Failed to load plist with launchctl (you may need to load it manually)`);
     log(`  Run: launchctl load "${plistPath}"`);
   }
 }
 async function installLinuxAutostart(runnerCommand, log, env) {
-  const home = env["HOME"]?.trim() || homedir2();
+  const home = env["HOME"]?.trim() || homedir3();
   const configHome = resolveLinuxConfigHome(home, env);
-  const unitDir = join3(configHome, "systemd", "user");
-  mkdirSync3(unitDir, { recursive: true });
-  const unitPath = join3(unitDir, "vo-runner.service");
-  const logFile = join3(home, ".claude", "vo-runner.log");
-  const errFile = join3(home, ".claude", "vo-runner-error.log");
+  const unitDir = join5(configHome, "systemd", "user");
+  mkdirSync4(unitDir, { recursive: true });
+  const unitPath = join5(unitDir, "vo-runner.service");
+  const logFile = join5(home, ".claude", "vo-runner.log");
+  const errFile = join5(home, ".claude", "vo-runner-error.log");
   const quotedRunnerCommand = quotePosixShellArgument(runnerCommand);
-  mkdirSync3(join3(home, ".claude"), { recursive: true });
+  mkdirSync4(join5(home, ".claude"), { recursive: true });
   const unit = `[Unit]
 Description=AlgoHQ Code Runner (vo-mcp)
 After=network-online.target
@@ -481,7 +701,7 @@ Wants=network-online.target
 [Service]
 Type=simple
 WorkingDirectory=${home}
-Environment="VO_CODE_RUNNER_CLONES_ROOT=${join3(configHome, "ai.algosuite.vo-runner", "clones")}"
+Environment="VO_CODE_RUNNER_CLONES_ROOT=${join5(configHome, "ai.algosuite.vo-runner", "clones")}"
 ExecStart=/bin/sh -lc ${quotedRunnerCommand}
 Restart=on-failure
 RestartSec=10
@@ -496,7 +716,7 @@ WantedBy=default.target
     log(`  Path: ${unitPath}`);
     return;
   }
-  writeFileSync3(unitPath, unit, "utf8");
+  writeFileSync4(unitPath, unit, "utf8");
   log(`\u2713 Installed systemd user unit`);
   log(`  Path: ${unitPath}`);
   if (process.env["VITEST"]) {
@@ -534,73 +754,142 @@ async function installAutostart(opts = {}) {
 // src/install.ts
 var DEFAULT_CONTROL_PLANE_URL2 = "https://vo-control-plane-bzjphrajaq-uc.a.run.app";
 function resolveCodeConfigPath(home) {
-  return join4(home, ".claude.json");
+  return join6(home, ".claude.json");
 }
 function resolveDesktopConfigPath(home, plat, appData) {
   if (plat === "win32") {
-    return join4(appData ?? join4(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    return join6(appData ?? join6(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
   }
   if (plat === "darwin") {
-    return join4(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    return join6(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
-  return join4(home, ".config", "Claude", "claude_desktop_config.json");
+  return join6(home, ".config", "Claude", "claude_desktop_config.json");
 }
 function readClaudeConfig(path) {
-  try {
-    if (!existsSync4(path)) return {};
-    const raw = readFileSync4(path, "utf8");
-    const parsed = JSON.parse(raw);
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
-  } catch {
-    return {};
+  if (!existsSync6(path)) return { kind: "absent", config: {}, mtimeMs: null };
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const before = statSync3(path).mtimeMs;
+    let raw;
+    try {
+      raw = readFileSync6(path, "utf8");
+    } catch {
+      return { kind: "invalid", config: {}, mtimeMs: before };
+    }
+    if (!existsSync6(path) || statSync3(path).mtimeMs !== before) continue;
+    const text = raw.replace(/^\uFEFF/u, "");
+    if (!text.trim()) return { kind: "empty", config: {}, mtimeMs: before };
+    try {
+      const parsed = JSON.parse(text);
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? { kind: "ok", config: parsed, mtimeMs: before } : { kind: "invalid", config: {}, mtimeMs: before };
+    } catch {
+      return { kind: "invalid", config: {}, mtimeMs: before };
+    }
   }
+  return { kind: "invalid", config: {}, mtimeMs: null };
 }
 function writeClaudeConfig(path, config) {
-  mkdirSync4(dirname3(path), { recursive: true });
-  writeFileSync4(path, `${JSON.stringify(config, null, 2)}
-`, "utf8");
+  mkdirSync5(dirname4(path), { recursive: true });
+  writeFileAtomic(path, `${JSON.stringify(config, null, 2)}
+`);
 }
-function resolveVoMcpCliPath() {
-  return join4(dirname3(fileURLToPath(import.meta.url)), "cli.js");
+function carriedEntryKeys(entry) {
+  if (!entry) return {};
+  const { command: _c, args: _a, env: _e, type, url: _u, headers: _h, ...rest } = entry;
+  const stdio = type === void 0 || type === "stdio";
+  return { ...stdio ? rest : {}, ...type === "stdio" ? { type } : {} };
 }
-function installMcpConfigAt(configPath, cliPath, controlPlaneUrl, log, label) {
-  const existing = readClaudeConfig(configPath);
+function preferredNodeCommand(existing) {
+  const current = String(existing ?? "").trim();
+  return current && /(^|[\\/])node(\.exe)?$/iu.test(current) ? current : "node";
+}
+function resolveVoMcpCliPath() {
+  return join6(dirname4(fileURLToPath(import.meta.url)), "cli.js");
+}
+var INSTALL_LAUNCHER = { sticky: false, onlyExisting: false };
+var HEAL_LAUNCHER = { sticky: true, onlyExisting: true };
+function installMcpConfigAt(configPath, cliPath, controlPlaneUrl, log, label, launcher = { launcherPath: null, ...INSTALL_LAUNCHER }) {
+  if (launcher.onlyExisting && !existsSync6(configPath)) return;
+  const read = readClaudeConfig(configPath);
+  if (read.kind === "invalid" || read.kind === "empty" && launcher.onlyExisting) {
+    log(`  \u26A0 ${label} config is ${read.kind === "empty" ? "empty" : "not valid JSON"} \u2014 left untouched: ${configPath}${read.kind === "empty" ? "" : " (fix or remove it, then re-run vo-mcp install)"}`);
+    return;
+  }
+  const existing = read.config;
+  const readMtime = read.mtimeMs;
   const mcpServers = existing["mcpServers"] && typeof existing["mcpServers"] === "object" ? existing["mcpServers"] : {};
-  const voEntry = mcpServers["vo"] ?? mcpServers["vo-mcp"];
-  if (voEntry?.args?.some((a) => a.includes(cliPath))) {
+  const managedEntry = mcpServers["vo-mcp"];
+  const voEntry = managedEntry ?? mcpServers["vo"];
+  const { launcherPath } = launcher;
+  const fallbackCli = chooseFallbackCli(voEntry?.env?.[MCP_FALLBACK_CLI_ENV], cliPath, launcher.sticky, launcherPath ? dirname4(launcherPath) : null);
+  const current = launcherPath ? !isStaleVoMcpEntry(voEntry, launcherPath, fallbackCli) : Boolean(voEntry?.args?.some((a) => a.includes(cliPath)));
+  if (current) {
     log(`  ${label} already current: ${configPath}`);
     return;
   }
-  if (existsSync4(configPath)) {
-    const backupPath = `${configPath}.backup-${Date.now()}`;
-    copyFileSync3(configPath, backupPath);
-    log(`  Backed up ${label} config \u2192 ${backupPath}`);
-  }
+  const backupPath = backupConfigOnce(configPath);
+  if (backupPath) log(`  Backed up ${label} config \u2192 ${backupPath}`);
+  const { [MCP_FALLBACK_CLI_ENV]: _previousFallback, ...preservedEnv } = voEntry?.env ?? {};
   const merged = {
     ...existing,
     mcpServers: {
       ...mcpServers,
       "vo-mcp": {
-        command: "node",
-        args: [cliPath],
-        // Preserve any existing env the user added (e.g. model API keys) — only
-        // ensure VO_CONTROL_PLANE_URL is present. NEVER drop the user's env keys.
-        env: { VO_CONTROL_PLANE_URL: controlPlaneUrl, ...voEntry?.env ?? {} }
+        ...carriedEntryKeys(managedEntry),
+        command: preferredNodeCommand(managedEntry?.command),
+        args: [launcherPath ?? cliPath],
+        env: {
+          VO_CONTROL_PLANE_URL: controlPlaneUrl,
+          ...preservedEnv,
+          ...launcherPath && fallbackCli ? { [MCP_FALLBACK_CLI_ENV]: fallbackCli } : {}
+        }
       }
     }
   };
+  if (readMtime !== null && (!existsSync6(configPath) || statSync3(configPath).mtimeMs !== readMtime)) {
+    log(`  \u26A0 ${label} config changed while updating \u2014 left untouched this time: ${configPath}`);
+    return;
+  }
   writeClaudeConfig(configPath, merged);
   log(`\u2713 Wrote vo-mcp to ${label}: ${configPath}`);
 }
-function installMcpConfig(log, env) {
-  const home = env["HOME"]?.trim() || env["USERPROFILE"]?.trim() || homedir3();
+function installMcpConfig(log, env, mode = "install") {
+  const home = env["HOME"]?.trim() || env["USERPROFILE"]?.trim() || homedir4();
   const appData = env["APPDATA"]?.trim();
   const plat = platform3();
   const cliPath = resolveVoMcpCliPath();
   const controlPlaneUrl = env["VO_CONTROL_PLANE_URL"]?.trim() || DEFAULT_CONTROL_PLANE_URL2;
-  installMcpConfigAt(resolveCodeConfigPath(home), cliPath, controlPlaneUrl, log, "Claude Code CLI");
-  installMcpConfigAt(resolveDesktopConfigPath(home, plat, appData), cliPath, controlPlaneUrl, log, "Claude Desktop");
-  installCodexMcpConfigAt(resolveCodexConfigPath(home), cliPath, controlPlaneUrl, log);
+  const launcherPath = writeMcpLauncherForEnv(env, log, { platform: plat, home });
+  const launcher = { launcherPath, ...mode === "heal" ? HEAL_LAUNCHER : INSTALL_LAUNCHER };
+  const leg = (label, run) => {
+    try {
+      run();
+    } catch (err) {
+      if (mode !== "heal") throw err;
+      log(`  \u26A0 ${label}: could not update the MCP registration \u2014 ${err instanceof Error ? err.message : String(err)}`);
+    }
+  };
+  leg("Claude Code CLI", () => installMcpConfigAt(resolveCodeConfigPath(home), cliPath, controlPlaneUrl, log, "Claude Code CLI", launcher));
+  leg("Claude Desktop", () => installMcpConfigAt(resolveDesktopConfigPath(home, plat, appData), cliPath, controlPlaneUrl, log, "Claude Desktop", launcher));
+  const codexPath = resolveCodexConfigPath(home);
+  if (launcher.onlyExisting && !existsSync6(codexPath)) return;
+  leg("Codex", () => {
+    if (launcherPath) {
+      const fallbackCli = chooseFallbackCli(readCodexManagedEnv(codexPath, MCP_FALLBACK_CLI_ENV), cliPath, launcher.sticky, dirname4(launcherPath));
+      installCodexMcpConfigAt(codexPath, launcherPath, controlPlaneUrl, log, fallbackCli ? { [MCP_FALLBACK_CLI_ENV]: fallbackCli } : {});
+    } else {
+      installCodexMcpConfigAt(codexPath, cliPath, controlPlaneUrl, log);
+    }
+  });
+}
+function writeMcpLauncherForEnv(env, log, hint) {
+  try {
+    const root = defaultRunnerRuntimeRoot(env, hint);
+    if (!root) return null;
+    return writeMcpLauncher(root);
+  } catch (err) {
+    log(`  \u26A0 could not write the vo-mcp launcher (registering cli.js directly): ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
 }
 async function runPairFlow(log, env) {
   log("\n\u2501\u2501\u2501 Step 2: Link your AlgoHQ account (device code) \u2501\u2501\u2501");