@algosuite/vo-mcp 0.2.0-beta.7 → 0.2.0-beta.70

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 join3, dirname as dirname2 } from "node:path";
-import { existsSync as existsSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, copyFileSync as copyFileSync2 } 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
@@ -197,54 +197,482 @@ async function runPairing(deps = {}) {
   }
 }
 
+// src/codex-mcp-config.ts
+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 join4(home, ".codex", "config.toml");
+}
+function normalizeKey(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"') || trimmed.startsWith("'") && trimmed.endsWith("'")) {
+    return trimmed.slice(1, -1);
+  }
+  return trimmed;
+}
+function tablePath(line) {
+  const match = /^\s*\[([^\r\n]+)\]\s*(?:#.*)?$/.exec(line);
+  const rawPath = match?.[1];
+  if (!rawPath || rawPath.includes("[") || rawPath.includes("]")) return null;
+  return rawPath.split(".").map(normalizeKey);
+}
+function tableSections(lines) {
+  const starts = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const path = tablePath(lines[index] ?? "");
+    if (path) starts.push({ path, start: index });
+  }
+  return starts.map((section, index) => ({
+    ...section,
+    end: starts[index + 1]?.start ?? lines.length
+  }));
+}
+function isManagedSection(section) {
+  return section.path[0] === "mcp_servers" && MANAGED_SERVER_NAMES.has(section.path[1] ?? "");
+}
+function assignmentKey(line) {
+  const match = /^\s*((?:[A-Za-z0-9_-]+)|(?:"[^"]+")|(?:'[^']+'))\s*=/.exec(line);
+  return match?.[1] ? normalizeKey(match[1]) : null;
+}
+function isStructurallySafeToml(raw) {
+  const lines = raw.split(/\r?\n/);
+  const beginIndexes = lines.flatMap((line, index) => line.trim() === MANAGED_BEGIN ? [index] : []);
+  const endIndexes = lines.flatMap((line, index) => line.trim() === MANAGED_END ? [index] : []);
+  if (beginIndexes.length !== endIndexes.length || beginIndexes.length > 1) return false;
+  if (beginIndexes[0] !== void 0 && (endIndexes[0] ?? -1) <= beginIndexes[0]) return false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (/^\[\[?mcp_servers(?:\.|\s|$)/.test(trimmed) && tablePath(line) === null) return false;
+  }
+  return true;
+}
+function tomlString(value) {
+  return JSON.stringify(value);
+}
+function preservedSectionLines(lines, section, managedKeys) {
+  if (!section) return [];
+  return lines.slice(section.start + 1, section.end).filter((line) => {
+    if (line.trim() === MANAGED_BEGIN || line.trim() === MANAGED_END) return false;
+    const key = assignmentKey(line);
+    return key === null || !managedKeys.has(key);
+  }).filter((line, index, all) => line.trim() !== "" || index > 0 && index < all.length - 1);
+}
+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");
+  }
+  const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+  const lines = raw.split(/\r?\n/);
+  const sections = tableSections(lines);
+  const rootSections = sections.filter((section) => isManagedSection(section) && section.path.length === 2);
+  const preferredRoot = rootSections.find((section) => section.path[1] === "algohq") ?? rootSections[0];
+  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", MCP_FALLBACK_CLI_ENV, ...Object.keys(managedEnv)]));
+  const removed = /* @__PURE__ */ new Set();
+  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);
+  }
+  const base = lines.filter((_line, index) => !removed.has(index)).join(eol).trimEnd();
+  const block = [
+    MANAGED_BEGIN,
+    "[mcp_servers.algohq]",
+    'command = "node"',
+    `args = [${tomlString(cliPath)}]`,
+    "required = true",
+    ...rootExtras,
+    "",
+    "[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, 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, managedEnv);
+  } catch (error) {
+    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 (readMtime !== null && (!existsSync4(configPath) || statSync2(configPath).mtimeMs !== readMtime)) {
+    log(`  \u26A0 Codex config changed while updating \u2014 left untouched this time: ${configPath}`);
+    return;
+  }
+  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/remote-mcp-entry.ts
+var REMOTE_MCP_SERVER_KEY = "vo-mcp-remote";
+var REMOTE_MCP_TOKEN_ENV = "VO_MCP_REMOTE_TOKEN";
+var REMOTE_MCP_ENDPOINT_PATH = "/api/v1/mcp";
+var REMOTE_MCP_AUTH_HEADER = `Bearer \${${REMOTE_MCP_TOKEN_ENV}}`;
+function remoteMcpOptIn(env) {
+  return (env["VO_REMOTE_MCP"] ?? "").trim() === "1";
+}
+function remoteMcpUrl(controlPlaneUrl) {
+  return `${controlPlaneUrl.trim().replace(/\/+$/, "")}${REMOTE_MCP_ENDPOINT_PATH}`;
+}
+function buildRemoteMcpEntry(controlPlaneUrl) {
+  return {
+    type: "http",
+    url: remoteMcpUrl(controlPlaneUrl),
+    headers: { Authorization: REMOTE_MCP_AUTH_HEADER }
+  };
+}
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : null;
+}
+function isManagedRemoteMcpEntry(value) {
+  const entry = asRecord(value);
+  if (!entry) return false;
+  if (entry["type"] !== "http") return false;
+  const url = entry["url"];
+  if (typeof url !== "string" || !url.endsWith(REMOTE_MCP_ENDPOINT_PATH)) return false;
+  const headers = asRecord(entry["headers"]);
+  return headers?.["Authorization"] === REMOTE_MCP_AUTH_HEADER;
+}
+function remoteMcpEntryIsCurrent(value, desired) {
+  const entry = asRecord(value);
+  if (!entry) return false;
+  const headers = asRecord(entry["headers"]);
+  return entry["type"] === desired.type && entry["url"] === desired.url && headers?.["Authorization"] === desired.headers["Authorization"];
+}
+
 // src/autostart.ts
-import { homedir as homedir2, platform as platform2 } from "node:os";
-import { join as join2 } from "node:path";
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, readFileSync as readFileSync2, unlinkSync, copyFileSync } 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;
 function resolveRunnerCommand(override) {
   return override ?? "vo-mcp runner";
 }
+function quotePosixShellArgument(value) {
+  if (value.includes("\0") || value.includes("\r") || value.includes("\n")) {
+    throw new Error("Runner command must not contain NUL, carriage return, or newline characters.");
+  }
+  return `'${value.replace(/'/gu, `'"'"'`)}'`;
+}
+function resolveLinuxConfigHome(home, env) {
+  const configured = env["XDG_CONFIG_HOME"]?.trim();
+  return configured && isAbsolute2(configured) ? configured : join5(home, ".config");
+}
+function launcherIsCurrent(path, desiredContent, label, log) {
+  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"] ?? join2(homedir2(), "AppData", "Roaming");
-  const startupDir = join2(appData, "Microsoft", "Windows", "Start Menu", "Programs", "Startup");
-  mkdirSync2(startupDir, { recursive: true });
-  const launcherPath = join2(startupDir, "vo-runner.cmd");
-  if (existsSync2(launcherPath)) {
-    const existing = readFileSync2(launcherPath, "utf8");
-    if (existing.includes("vo-mcp runner")) {
-      log(`\u2713 Auto-start is already configured (Windows Startup folder)`);
-      log(`  Path: ${launcherPath}`);
-      return;
+  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 {
+      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`);
     }
-    const backupPath = `${launcherPath}.backup-${Date.now()}`;
-    copyFileSync(launcherPath, backupPath);
-    log(`  Backed up existing launcher to: ${backupPath}`);
-  }
-  const launcherContent = `@echo off
-REM Auto-start launcher for vo-mcp runner
-REM Created by vo-mcp autostart installer
-start /min cmd /c "${runnerCommand}"
+  }
+  const runnerConsoleCommand = `cmd /c ${runnerCommand} >> "%USERPROFILE%\\.claude\\vo-runner.log" 2>&1`.replace(/"/g, '""');
+  const launcherContent = `' Auto-start launcher for vo-mcp runner
+' Created by vo-mcp autostart installer
+' Keepalive supervisor: restarts the runner if it exits (parity with launchd
+' KeepAlive on macOS and systemd Restart=on-failure on Linux).
+' Runs the runner in a MINIMIZED (style 7), never a hidden (style 0) window:
+' hidden script-host exec trips Defender's PowhidSubExec.B heuristic and gets
+' blocked at logon. To stop: create %USERPROFILE%\\.claude\\vo-runner.stop, or
+' end wscript.exe.
+Dim sh, fso, stopFile, backoff, startedAt, ranMs
+Set sh = CreateObject("WScript.Shell")
+Set fso = CreateObject("Scripting.FileSystemObject")
+sh.CurrentDirectory = sh.ExpandEnvironmentStrings("%USERPROFILE%")
+sh.Environment("Process")("VO_CODE_RUNNER_CLONES_ROOT") = sh.ExpandEnvironmentStrings("%APPDATA%\\ai.algosuite.vo-runner\\clones")
+stopFile = sh.ExpandEnvironmentStrings("%USERPROFILE%\\.claude\\vo-runner.stop")
+backoff = ${WINDOWS_RESTART_BACKOFF_MS}
+Do
+  If fso.FileExists(stopFile) Then
+    fso.DeleteFile stopFile
+    WScript.Quit 0
+  End If
+  startedAt = Timer
+  sh.Run "${runnerConsoleCommand}", 7, True
+  ranMs = (Timer - startedAt) * 1000
+  If ranMs < 0 Then ranMs = ${WINDOWS_HEALTHY_RUN_MS}
+  If ranMs >= ${WINDOWS_HEALTHY_RUN_MS} Then
+    backoff = ${WINDOWS_RESTART_BACKOFF_MS}
+  ElseIf backoff < ${WINDOWS_MAX_BACKOFF_MS} Then
+    backoff = backoff * 2
+  End If
+  WScript.Sleep backoff
+Loop
 `;
-  writeFileSync2(launcherPath, launcherContent, "utf8");
+  if (launcherIsCurrent(launcherPath, launcherContent, "launcher", log)) {
+    log(`\u2713 Auto-start is already configured (Windows Startup folder)`);
+    log(`  Path: ${launcherPath}`);
+    return;
+  }
+  writeFileSync4(launcherPath, launcherContent, "utf8");
   log(`\u2713 Installed Windows auto-start launcher`);
   log(`  Path: ${launcherPath}`);
-  log(`  The runner will start minimized at next login.`);
-}
-async function installMacAutostart(runnerCommand, log) {
-  const launchAgentsDir = join2(homedir2(), "Library", "LaunchAgents");
-  mkdirSync2(launchAgentsDir, { recursive: true });
-  const plistPath = join2(launchAgentsDir, "ai.algosuite.vo-runner.plist");
-  if (existsSync2(plistPath)) {
-    const existing = readFileSync2(plistPath, "utf8");
-    if (existing.includes("vo-mcp runner")) {
-      log(`\u2713 Auto-start is already configured (launchd)`);
-      log(`  Path: ${plistPath}`);
-      return;
-    }
-    const backupPath = `${plistPath}.backup-${Date.now()}`;
-    copyFileSync(plistPath, backupPath);
-    log(`  Backed up existing plist to: ${backupPath}`);
-  }
+  log(`  The runner will start hidden at next login.`);
+}
+async function installMacAutostart(runnerCommand, log, env) {
+  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"];
@@ -263,53 +691,58 @@ ${args.map((a) => `    <string>${a}</string>`).join("\n")}
   <true/>
   <key>KeepAlive</key>
   <true/>
+  <key>WorkingDirectory</key>
+  <string>${home}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>VO_CODE_RUNNER_CLONES_ROOT</key>
+    <string>${join5(home, "Library", "Application Support", "ai.algosuite.vo-runner", "clones")}</string>
+  </dict>
   <key>StandardOutPath</key>
-  <string>${join2(homedir2(), ".claude", "vo-runner.log")}</string>
+  <string>${join5(home, ".claude", "vo-runner.log")}</string>
   <key>StandardErrorPath</key>
-  <string>${join2(homedir2(), ".claude", "vo-runner-error.log")}</string>
+  <string>${join5(home, ".claude", "vo-runner-error.log")}</string>
 </dict>
 </plist>
 `;
-  writeFileSync2(plistPath, plistContent, "utf8");
+  if (launcherIsCurrent(plistPath, plistContent, "plist", log)) {
+    log(`\u2713 Auto-start is already configured (launchd)`);
+    log(`  Path: ${plistPath}`);
+    return;
+  }
+  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: ${join2(homedir2(), ".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 unitDir = join2(home, ".config", "systemd", "user");
-  mkdirSync2(unitDir, { recursive: true });
-  const unitPath = join2(unitDir, "vo-runner.service");
-  if (existsSync2(unitPath)) {
-    const existing = readFileSync2(unitPath, "utf8");
-    if (existing.includes(runnerCommand) || existing.includes("vo-mcp runner")) {
-      log(`\u2713 Auto-start is already configured (systemd user unit)`);
-      log(`  Path: ${unitPath}`);
-      return;
-    }
-    const backupPath = `${unitPath}.backup-${Date.now()}`;
-    copyFileSync(unitPath, backupPath);
-    log(`  Backed up existing unit to: ${backupPath}`);
-  }
-  const logFile = join2(home, ".claude", "vo-runner.log");
-  const errFile = join2(home, ".claude", "vo-runner-error.log");
-  mkdirSync2(join2(home, ".claude"), { recursive: true });
+  const home = env["HOME"]?.trim() || homedir3();
+  const configHome = resolveLinuxConfigHome(home, env);
+  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);
+  mkdirSync4(join5(home, ".claude"), { recursive: true });
   const unit = `[Unit]
-Description=VO Code Runner (vo-mcp)
+Description=AlgoHQ Code Runner (vo-mcp)
 After=network-online.target
 Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=/bin/sh -lc '${runnerCommand}'
+WorkingDirectory=${home}
+Environment="VO_CODE_RUNNER_CLONES_ROOT=${join5(configHome, "ai.algosuite.vo-runner", "clones")}"
+ExecStart=/bin/sh -lc ${quotedRunnerCommand}
 Restart=on-failure
 RestartSec=10
 StandardOutput=append:${logFile}
@@ -318,7 +751,12 @@ StandardError=append:${errFile}
 [Install]
 WantedBy=default.target
 `;
-  writeFileSync2(unitPath, unit, "utf8");
+  if (launcherIsCurrent(unitPath, unit, "unit", log)) {
+    log(`\u2713 Auto-start is already configured (systemd user unit)`);
+    log(`  Path: ${unitPath}`);
+    return;
+  }
+  writeFileSync4(unitPath, unit, "utf8");
   log(`\u2713 Installed systemd user unit`);
   log(`  Path: ${unitPath}`);
   if (process.env["VITEST"]) {
@@ -340,11 +778,11 @@ async function installAutostart(opts = {}) {
   const log = opts.log ?? ((m) => console.error(m));
   const env = opts.env ?? process.env;
   const runnerCommand = resolveRunnerCommand(opts.runnerCommand);
-  const plat = platform2();
+  const plat = opts.platform ?? platform2();
   if (plat === "win32") {
     installWindowsAutostart(runnerCommand, log, env);
   } else if (plat === "darwin") {
-    await installMacAutostart(runnerCommand, log);
+    await installMacAutostart(runnerCommand, log, env);
   } else if (plat === "linux") {
     await installLinuxAutostart(runnerCommand, log, env);
   } else {
@@ -356,75 +794,170 @@ 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 join3(home, ".claude.json");
+  return join6(home, ".claude.json");
 }
 function resolveDesktopConfigPath(home, plat, appData) {
   if (plat === "win32") {
-    return join3(appData ?? join3(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    return join6(appData ?? join6(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
   }
   if (plat === "darwin") {
-    return join3(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    return join6(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
   }
-  return join3(home, ".config", "Claude", "claude_desktop_config.json");
+  return join6(home, ".config", "Claude", "claude_desktop_config.json");
 }
 function readClaudeConfig(path) {
-  try {
-    if (!existsSync3(path)) return {};
-    const raw = readFileSync3(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) {
-  mkdirSync3(dirname2(path), { recursive: true });
-  writeFileSync3(path, `${JSON.stringify(config, null, 2)}
-`, "utf8");
+  mkdirSync5(dirname4(path), { recursive: true });
+  writeFileAtomic(path, `${JSON.stringify(config, null, 2)}
+`);
+}
+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 preferredNodeCommand(existing) {
+  const current = String(existing ?? "").trim();
+  return current && /(^|[\\/])node(\.exe)?$/iu.test(current) ? current : "node";
 }
 function resolveVoMcpCliPath() {
-  return join3(dirname2(fileURLToPath(import.meta.url)), "cli.js");
+  return join6(dirname4(fileURLToPath(import.meta.url)), "cli.js");
 }
-function installMcpConfigAt(configPath, cliPath, controlPlaneUrl, log, label) {
-  const existing = readClaudeConfig(configPath);
+var INSTALL_LAUNCHER = { sticky: false, onlyExisting: false };
+var HEAL_LAUNCHER = { sticky: true, onlyExisting: true };
+function reconcileRemoteEntry(mcpServers, remote) {
+  const existing = mcpServers[REMOTE_MCP_SERVER_KEY];
+  if (remote) {
+    return {
+      fragment: { [REMOTE_MCP_SERVER_KEY]: remote },
+      current: remoteMcpEntryIsCurrent(existing, remote)
+    };
+  }
+  if (existing !== void 0 && isManagedRemoteMcpEntry(existing)) {
+    return { fragment: { [REMOTE_MCP_SERVER_KEY]: void 0 }, current: false };
+  }
+  return { fragment: {}, current: true };
+}
+function installMcpConfigAt(configPath, cliPath, controlPlaneUrl, log, label, launcher = { launcherPath: null, ...INSTALL_LAUNCHER }, remote = null) {
+  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 localCurrent = launcherPath ? !isStaleVoMcpEntry(voEntry, launcherPath, fallbackCli) : Boolean(voEntry?.args?.some((a) => a.includes(cliPath)));
+  const remoteState = reconcileRemoteEntry(mcpServers, remote);
+  if (localCurrent && remoteState.current) {
     log(`  ${label} already current: ${configPath}`);
     return;
   }
-  if (existsSync3(configPath)) {
-    const backupPath = `${configPath}.backup-${Date.now()}`;
-    copyFileSync2(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 } : {}
+        }
+      },
+      // Additive remote entry (11.3 slice A) — or the removal of one we wrote,
+      // when the operator has opted back out. Spread LAST so it can delete its
+      // own key; it never names 'vo-mcp', so the stdio entry above is safe.
+      ...remoteState.fragment
     }
   };
+  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}`);
+  if (remote) {
+    log(`  + remote MCP entry '${REMOTE_MCP_SERVER_KEY}' \u2192 ${remote.url} (serves vo_skill_list; every other tool stays on the local vo-mcp entry)`);
+    log(`    Set ${REMOTE_MCP_TOKEN_ENV} in your environment to authenticate it \u2014 no token is written to this file.`);
+  } else if (!remoteState.current) {
+    log(`  - removed the remote MCP entry '${REMOTE_MCP_SERVER_KEY}' (VO_REMOTE_MCP is not set to 1)`);
+  }
 }
-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");
+  const remote = remoteMcpOptIn(env) ? buildRemoteMcpEntry(controlPlaneUrl) : null;
+  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, remote));
+  leg("Claude Desktop", () => installMcpConfigAt(resolveDesktopConfigPath(home, plat, appData), cliPath, controlPlaneUrl, log, "Claude Desktop", launcher, remote));
+  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 VO account (device code) \u2501\u2501\u2501");
+  log("\n\u2501\u2501\u2501 Step 2: Link your AlgoHQ account (device code) \u2501\u2501\u2501");
   log("A short code appears below \u2014 open the URL it prints and enter the code.");
   log("Your raw token never persists; a scoped credential is stored in your OS keychain.\n");
   try {
@@ -437,27 +970,33 @@ async function runPairFlow(log, env) {
     log("  No problem \u2014 the rest will finish; pair anytime with: vo-mcp pair");
   }
 }
-function printNextSteps(log, autostartInstalled) {
+function printNextSteps(log, autostartInstalled, configOnly) {
   log("\n\u2501\u2501\u2501 Installation complete! \u2501\u2501\u2501\n");
   log("What's configured:");
-  log("  \u2713 Claude Desktop / Claude Code will load vo-mcp on next restart");
-  log("  \u2713 Your scoped credential is stored (revocable via the dashboard)");
+  log("  \u2713 Claude Desktop, Claude Code, and Codex will load AlgoHQ MCP on next restart");
+  if (configOnly) {
+    log("  \u2713 Existing pairing and runner auto-start settings were left unchanged");
+  } else {
+    log("  \u2713 Your scoped credential is stored (revocable via the dashboard)");
+  }
   if (autostartInstalled) {
     log("  \u2713 Runner daemon will start automatically at login\n");
   } else {
     log("\n");
   }
   log("Next steps:");
-  log("  1. Restart Claude Desktop / Claude Code (if running).");
-  if (autostartInstalled) {
+  log("  1. Restart Claude Desktop / Claude Code / Codex (if running).");
+  if (configOnly) {
+    log("  2. Restart the existing AlgoHQ runner service or runner terminal.");
+  } else if (autostartInstalled) {
     log("  2. Log out and back in (or start the runner manually now: vo-mcp runner)");
   } else {
     log("  2. Start the agent runner in a terminal (keep it running):");
     log("       vo-mcp runner");
     log("     (To set up auto-start at login: vo-mcp runner --install-autostart)");
   }
-  log("  3. Visit the VO Command Center to dispatch your first agent:");
-  log("       https://algosuite.ai/virtualoffice\n");
+  log("  3. Visit AlgoHQ to dispatch your first agent:");
+  log("       https://algosuite.ai/algohq\n");
   log("The runner watches for tasks you dispatch and spins up agents in fresh worktrees.");
   log("Agents only run while the runner is connected. Ctrl+C to stop it anytime.\n");
 }
@@ -465,11 +1004,13 @@ async function install(opts = {}) {
   const log = opts.log ?? ((m) => console.error(m));
   const env = opts.env ?? process.env;
   log("\u2501\u2501\u2501 vo-mcp installer \u2501\u2501\u2501");
-  log("This will set up your machine to dispatch VO agents from anywhere.\n");
-  log("\u2501\u2501\u2501 Step 1: Configure Claude Desktop / Claude Code \u2501\u2501\u2501");
+  log("This will set up your machine to dispatch AlgoHQ agents from anywhere.\n");
+  log("\u2501\u2501\u2501 Step 1: Configure Claude Desktop / Claude Code / Codex \u2501\u2501\u2501");
   installMcpConfig(log, env);
   if (!opts.skipLogin) {
     await runPairFlow(log, env);
+  } else if (opts.configOnly) {
+    log("\n(Config-only refresh \u2014 existing pairing left unchanged.)");
   } else {
     log("\n(Pairing skipped \u2014 run `vo-mcp pair` when ready.)");
   }
@@ -484,11 +1025,15 @@ async function install(opts = {}) {
       autostartInstalled = true;
     }
   }
-  printNextSteps(log, autostartInstalled);
+  printNextSteps(log, autostartInstalled, opts.configOnly === true);
+}
+function installOptionsFromArgs(args) {
+  const configOnly = args.includes("--config-only");
+  return configOnly ? { configOnly: true, skipLogin: true, skipAutostart: true } : {};
 }
 
 // src/install-cli.ts
-install().catch((err) => {
+install(installOptionsFromArgs(process.argv.slice(2))).catch((err) => {
   console.error("[vo-mcp install] fatal:", err);
   process.exit(1);
 });