vexp-cli 3.1.0 → 3.1.2

package/dist/agent-config.js

@@ -9,6 +9,7 @@
 import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
+import { spawnSync } from "child_process";
 import * as crypto from "crypto";
 import { VEXP_GUARD_HOOK, VEXP_OPENCODE_GUARD, VEXP_CURSOR_GUARD, vexpHintHookScript, vexpSearchHookScript, vexpHintHookCmdScript, vexpStopGateHookScript, vexpSessionContextHookScript, vexpOpencodeHintPlugin, vexpOpencodeCompressPlugin, bakeEditHintHook, bakeReadHintHook, bakeBashCapHook } from "./hook-template.js";
 // ---------------------------------------------------------------------------
@@ -132,9 +133,17 @@ const AGENT_DETECTORS = [
     {
         agent: "Windsurf",
         detectPath: ".windsurf",
+        // Windsurf became Devin Desktop (2026-06-02); a project set up for the new
+        // agent carries `.devin/` instead of `.windsurf/`.
+        detectPaths: [".devin"],
         configFile: ".windsurf/rules/vexp.md",
         templateName: "windsurf",
-        mcpConfigFile: ".windsurf/mcp.json",
+        // MCP is NOT project-level here: Cascade reads only the machine-global
+        // ~/.codeium/windsurf/mcp_config.json, and Devin Local reads
+        // .devin/mcp_config.json. Both are written by the Windsurf block in the
+        // writers (configureWindsurfGlobal). The `.windsurf/mcp.json` older
+        // versions wrote is read by neither — a WSL user found out by building
+        // the Windows-side entry by hand (field report, 2026-09-01).
     },
     {
         agent: "Continue.dev",
@@ -295,6 +304,12 @@ export function plannedWrites(agent, guard = guardMode(), interventions = interv
         case "Antigravity":
             out.push("~/.gemini/antigravity MCP config  (user scope)");
             break;
+        case "Windsurf":
+            out.push("~/.codeium/windsurf/mcp_config.json  (MCP server entry, user scope — Cascade)");
+            if (windsurfNextInstalled())
+                out.push("~/.codeium/windsurf-next/mcp_config.json  (MCP server entry, user scope — Cascade in Devin Desktop Next)");
+            out.push(".devin/mcp_config.json  (MCP server entry — Devin Local)");
+            break;
         case "Zed":
             out.push(".zed/settings.json `context_servers`  (MCP server entry)");
             break;
@@ -416,6 +431,16 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
                 mcpConfigs.push(detector.mcpConfigFile);
             }
         }
+        // Windsurf / Devin Desktop: the two files the agent actually reads.
+        if (detector.agent === "Windsurf") {
+            if (configureWindsurfGlobal(binaryPath, mcpServerPath, workspaceRoot))
+                mcpConfigs.push("~/.codeium/windsurf/mcp_config.json");
+            if (configureWindsurfNextGlobal(binaryPath, mcpServerPath, workspaceRoot))
+                mcpConfigs.push("~/.codeium/windsurf-next/mcp_config.json");
+            if (writeMcpConfig(path.join(workspaceRoot, ".devin", "mcp_config.json"), binaryPath, undefined, mcpServerPath, workspaceRoot))
+                mcpConfigs.push(".devin/mcp_config.json");
+            removeDeadWindsurfMcpJson(workspaceRoot);
+        }
         // Claude Code: configure MCP in ~/.claude.json (user-scope, stdio)
         if (detector.agent === "Claude Code") {
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
@@ -766,6 +791,16 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
             if (writeMcpConfig(mcpConfigPath, binaryPath, alwaysAllow, mcpSrv, workspaceRoot, approveKey))
                 mcpConfigs.push(detector.mcpConfigFile);
         }
+        // Windsurf / Devin Desktop: see configureAgents().
+        if (detector.agent === "Windsurf") {
+            if (configureWindsurfGlobal(binaryPath, mcpServerPath, workspaceRoot))
+                mcpConfigs.push("~/.codeium/windsurf/mcp_config.json");
+            if (configureWindsurfNextGlobal(binaryPath, mcpServerPath, workspaceRoot))
+                mcpConfigs.push("~/.codeium/windsurf-next/mcp_config.json");
+            if (writeMcpConfig(path.join(workspaceRoot, ".devin", "mcp_config.json"), binaryPath, undefined, mcpServerPath, workspaceRoot))
+                mcpConfigs.push(".devin/mcp_config.json");
+            removeDeadWindsurfMcpJson(workspaceRoot);
+        }
         if (detector.agent === "Claude Code") {
             const wrote = configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRoot);
             if (wrote)
@@ -863,6 +898,11 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
  * commas (preserving string contents) before parsing.
  */
 export function parseJsonc(text) {
+    // A UTF-8 BOM (PowerShell's default when a user hand-edits on Windows)
+    // made the file "unparseable" here and unreadable to Cursor itself; our
+    // next rewrite drops it, so tolerating it on read self-heals the file.
+    if (text.charCodeAt(0) === 0xfeff)
+        text = text.slice(1);
     let out = "";
     let inString = false;
     let inLineComment = false;
@@ -940,7 +980,6 @@ export function readJsonConfigSafe(filePath) {
     catch { /* fall through to ok:false */ }
     return { data: {}, ok: false, existed: true };
 }
-/** Copy an existing config to <file>.vexp-bak before overwriting it. */
 /**
  * True when the vexp entry already in a config still resolves to something
  * runnable — even if it points at a DIFFERENT vexp install than ours.
@@ -983,30 +1022,101 @@ export function readJsonConfigSafe(filePath) {
  * (`resolveNodePath`) since 2.x. Same search order, bare `node` as last resort.
  */
 export function resolveNodeCommand() {
+    // POSITIVE check: accept process.execPath only when it IS a node binary.
+    // The old denylist (/Code|Electron/) let every renamed Electron fork
+    // through — Cursor.exe, Windsurf.exe, Trae.exe — and a Windows setup wrote
+    // `command: ...\Cursor.exe` into mcp.json: the editor opens instead of a
+    // stdio server, "MCP error -32000: Connection closed" (field report,
+    // 2026-09-02). A VS Code remote/WSL extension host runs under a real
+    // `node` binary and still passes.
     const execPath = process.execPath;
-    if (execPath && !/Code|Electron/i.test(execPath)) {
+    const execBase = execPath ? path.basename(execPath).toLowerCase() : "";
+    if (execPath && (execBase === "node" || execBase === "node.exe")) {
         try {
             fs.accessSync(execPath, fs.constants.X_OK);
             return execPath;
         }
         catch { /* not executable */ }
     }
-    if (process.platform !== "win32" && fs.existsSync("/usr/local/bin/node"))
-        return "/usr/local/bin/node";
-    const home = os.homedir();
-    const nvmDir = path.join(home, ".nvm", "versions", "node");
-    if (fs.existsSync(nvmDir)) {
+    for (const candidate of nodeCandidates(process.platform, os.homedir(), process.env)) {
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    const fromShell = nodeFromLoginShell();
+    if (fromShell)
+        return fromShell;
+    return "node";
+}
+/**
+ * Absolute locations a node binary is commonly installed at, newest version
+ * manager entries first. A GUI-launched editor (Dock, Start menu) has the
+ * login PATH of nothing but the system — `/usr/bin:/bin:/usr/sbin:/sbin` on
+ * macOS — so a bare `node` in an MCP entry spawns only when the editor was
+ * started from a terminal, and "works from `code .`, disconnects from the
+ * Dock" is what a user sees. The chain used to know `/usr/local/bin` and nvm
+ * only: Homebrew on Apple Silicon (`/opt/homebrew`), Volta, fnm and the
+ * Windows installers were all "node" (field report, Mac Silicon + Windows,
+ * VS Code + Copilot). Pure, so the list itself is testable.
+ */
+export function nodeCandidates(platform, home, env) {
+    const out = [];
+    const newestUnder = (dir, rel) => {
         try {
-            const versions = fs.readdirSync(nvmDir).filter((d) => d.startsWith("v")).sort().reverse();
-            for (const v of versions) {
-                const candidate = path.join(nvmDir, v, "bin", "node");
-                if (fs.existsSync(candidate))
-                    return candidate;
-            }
+            return fs.readdirSync(dir)
+                .filter((d) => /^v?\d/.test(d))
+                .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))
+                .map((v) => path.join(dir, v, ...rel));
         }
-        catch { /* ignore */ }
+        catch {
+            return [];
+        }
+    };
+    if (platform === "win32") {
+        for (const base of [env.ProgramFiles, env["ProgramFiles(x86)"]]) {
+            if (base)
+                out.push(path.join(base, "nodejs", "node.exe"));
+        }
+        if (env.LOCALAPPDATA) {
+            out.push(path.join(env.LOCALAPPDATA, "Programs", "nodejs", "node.exe"));
+            out.push(path.join(env.LOCALAPPDATA, "Volta", "bin", "node.exe"));
+            out.push(...newestUnder(path.join(env.LOCALAPPDATA, "fnm_multishells"), ["node.exe"]));
+        }
+        if (env.APPDATA)
+            out.push(...newestUnder(path.join(env.APPDATA, "nvm"), ["node.exe"]));
+        return out;
+    }
+    if (platform === "darwin")
+        out.push("/opt/homebrew/bin/node");
+    out.push("/usr/local/bin/node", "/usr/bin/node");
+    if (home) {
+        out.push(...newestUnder(path.join(home, ".nvm", "versions", "node"), ["bin", "node"]));
+        out.push(path.join(home, ".volta", "bin", "node"));
+        out.push(path.join(home, ".local", "share", "fnm", "aliases", "default", "bin", "node"));
+        if (platform === "darwin")
+            out.push(path.join(home, "Library", "Application Support", "fnm", "aliases", "default", "bin", "node"));
+        out.push(path.join(home, ".asdf", "shims", "node"));
     }
-    return "node";
+    return out;
+}
+/**
+ * Last resort before a bare `node`: ask the user's LOGIN shell where node
+ * is. Version managers that live only in shell init (nvm via .zshrc, fnm,
+ * asdf) are invisible to every static candidate above but resolve here.
+ * Bounded (3 s) and validated: the answer must be an absolute path that
+ * exists, or it is discarded.
+ */
+function nodeFromLoginShell() {
+    if (process.platform === "win32")
+        return undefined;
+    try {
+        const shell = process.env.SHELL && fs.existsSync(process.env.SHELL) ? process.env.SHELL : "/bin/sh";
+        const r = spawnSync(shell, ["-lc", "command -v node"], { encoding: "utf-8", timeout: 2_500 });
+        const line = String(r.stdout ?? "").trim().split(/\r?\n/).filter((l) => l.startsWith("/")).pop();
+        if (line && fs.existsSync(line))
+            return line;
+    }
+    catch { /* no shell, no answer */ }
+    return undefined;
 }
 /**
  * An entry whose interpreter is a bare name (`node`, `node.exe`) rather than a
@@ -1014,6 +1124,34 @@ export function resolveNodeCommand() {
  * GUI editor, so it is never adopted as "already working" — the writer replaces
  * it with the pinned interpreter on the next setup.
  */
+/** The command string of an MCP entry, wherever the shape hides it. */
+function entryCommand(entry) {
+    if (!entry || typeof entry !== "object")
+        return undefined;
+    let command = entry.command;
+    if (Array.isArray(command))
+        command = command[0];
+    else if (command !== null && typeof command === "object")
+        command = command.path;
+    return typeof command === "string" && command.length > 0 ? command : undefined;
+}
+/**
+ * An MCP entry whose command is the EDITOR's own executable. Written by the
+ * pre-3.1.1 node resolver on Windows (Cursor.exe passed the old denylist):
+ * the path exists, so `vexpEntryStillResolves` adopted it forever while every
+ * connection died with "MCP error -32000". Such an entry is broken by
+ * construction and must be repaired, never adopted.
+ */
+export function isEditorExecutable(entry) {
+    const command = entryCommand(entry);
+    if (!command)
+        return false;
+    // Both separators, whatever the host: a config written on Windows must be
+    // recognised when read from WSL/CI too (path.basename splits only on the
+    // host's separator).
+    const base = (command.split(/[\\/]/).pop() ?? "").toLowerCase().replace(/\.exe$/, "");
+    return ["code", "code-insiders", "code-oss", "cursor", "windsurf", "windsurf-next", "trae", "kiro", "zed", "antigravity", "electron", "devin"].includes(base);
+}
 export function isBareInterpreter(entry) {
     if (!entry || typeof entry !== "object")
         return false;
@@ -1032,7 +1170,7 @@ export function isBareInterpreter(entry) {
  * (opencode, Claude Code) keep adopting a bare interpreter — it works there.
  */
 function adoptableEntry(entry) {
-    return vexpEntryStillResolves(entry) && !isBareInterpreter(entry);
+    return vexpEntryStillResolves(entry) && !isBareInterpreter(entry) && !isEditorExecutable(entry);
 }
 function vexpEntryStillResolves(entry) {
     if (!entry || typeof entry !== "object")
@@ -1064,10 +1202,52 @@ function vexpEntryStillResolves(entry) {
     const script = (Array.isArray(rawArgs) ? rawArgs : []).find((a) => typeof a === "string" && path.isAbsolute(a) && /\.[cm]?js$/.test(a));
     return script === undefined || fs.existsSync(script);
 }
+/**
+ * Where a pre-overwrite backup of `filePath` goes. Inside a vexp workspace —
+ * an ancestor directory holding `.vexp/`, the user's home excepted — the copy
+ * lands in `<root>/.vexp/backups/<path relative to the root, separators →
+ * "__">.vexp-bak`, which the generated `.vexp/.gitignore` covers. It used to
+ * be a `.vexp-bak` sibling of the file, and `.vscode/mcp.json.vexp-bak` sat as
+ * an untracked file in a user's Changes view (field report, 2026-09-01).
+ * Outside a workspace (`~/.claude.json`, `~/.codex/config.toml`, the Windsurf
+ * global file) the sibling stays: nothing there is under version control.
+ */
+export function backupPathFor(filePath) {
+    const abs = path.resolve(filePath);
+    const home = path.resolve(os.homedir());
+    let dir = path.dirname(abs);
+    for (;;) {
+        const marker = path.join(dir, ".vexp");
+        let isWorkspace = false;
+        try {
+            isWorkspace = dir !== home && fs.statSync(marker).isDirectory();
+        }
+        catch { /* no marker here */ }
+        if (isWorkspace) {
+            const rel = path.relative(dir, abs).split(path.sep).join("__");
+            return path.join(dir, ".vexp", "backups", `${rel}.vexp-bak`);
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return `${abs}.vexp-bak`;
+}
+/** Copy an existing config to its backup location before overwriting it. */
 function backupConfig(filePath) {
     try {
-        if (fs.existsSync(filePath))
-            fs.copyFileSync(filePath, `${filePath}.vexp-bak`);
+        if (!fs.existsSync(filePath))
+            return;
+        const dest = backupPathFor(filePath);
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(filePath, dest);
+        // Older versions left the copy next to the file; inside a workspace that
+        // sibling is exactly what git shows as untracked. Retire it now that the
+        // fresh copy lives in .vexp/backups/.
+        const legacy = path.resolve(`${filePath}.vexp-bak`);
+        if (legacy !== dest && fs.existsSync(legacy))
+            fs.unlinkSync(legacy);
     }
     catch { /* non-fatal */ }
 }
@@ -1323,6 +1503,130 @@ export function mergeJsonConfig(filePath, mergePayload, version) {
  * one workspace breaks every other project (the 2.0.32 multi-session
  * lesson). `vexp-core mcp` resolves the workspace from its spawn cwd.
  */
+/** Cascade's one and only MCP config, on the side of the boundary vexp runs on. */
+export function windsurfGlobalMcpPath() {
+    return path.join(os.homedir(), ".codeium", "windsurf", "mcp_config.json");
+}
+/**
+ * Devin Desktop Next — the beta channel, formerly Windsurf Next — is a separate
+ * install with its own Cascade config under `~/.codeium/windsurf-next/`
+ * (field report, 2026-09-01: a user ran the stable build on one project and
+ * Next on another; the entry written for stable was invisible to Next). We
+ * write it only when that directory exists: it is the build's own footprint,
+ * never ours to create.
+ */
+export function windsurfNextGlobalMcpPath() {
+    return path.join(os.homedir(), ".codeium", "windsurf-next", "mcp_config.json");
+}
+export function windsurfNextInstalled() {
+    return fs.existsSync(path.dirname(windsurfNextGlobalMcpPath()));
+}
+export function configureWindsurfNextGlobal(binaryPath, mcpServerPath, workspaceRoot) {
+    if (!windsurfNextInstalled())
+        return false;
+    return writeMcpConfig(windsurfNextGlobalMcpPath(), binaryPath, VEXP_TOOLS, mcpServerPath, workspaceRoot);
+}
+/**
+ * Windsurf (Cascade) reads MCP servers from ~/.codeium/windsurf/mcp_config.json
+ * and nowhere else — the documentation names no project-level file, and the
+ * `.windsurf/mcp.json` vexp wrote for several releases was read by nothing.
+ * Machine-global, so the entry is pinned to the workspace being set up and the
+ * last setup wins, exactly like the Codex desktop entry: a global file cannot
+ * follow whichever project happens to be open. Under WSL this lands in the WSL
+ * home while Cascade on Windows reads the Windows profile; the setup prints the
+ * Windows-side entry to paste (`windsurfWslBridgeNote`).
+ */
+export function configureWindsurfGlobal(binaryPath, mcpServerPath, workspaceRoot) {
+    const p = windsurfGlobalMcpPath();
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+    }
+    catch {
+        return false;
+    }
+    return writeMcpConfig(p, binaryPath, VEXP_TOOLS, mcpServerPath, workspaceRoot);
+}
+/**
+ * Drop our entry from the `.windsurf/mcp.json` older versions wrote (a file
+ * Cascade never read), deleting the file when nothing of the user's is left.
+ */
+export function removeDeadWindsurfMcpJson(workspaceRoot) {
+    const p = path.join(workspaceRoot, ".windsurf", "mcp.json");
+    const read = readJsonConfigSafe(p);
+    if (!read.existed || !read.ok)
+        return "absent";
+    const servers = read.data.mcpServers;
+    if (!servers || !("vexp" in servers))
+        return "absent";
+    delete servers["vexp"];
+    const otherKeys = Object.keys(read.data).filter((k) => k !== "mcpServers");
+    if (Object.keys(servers).length === 0 && otherKeys.length === 0) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch { /* best effort */ }
+        return "deleted";
+    }
+    try {
+        fs.writeFileSync(p, JSON.stringify(read.data, null, 2), "utf-8");
+    }
+    catch { /* best effort */ }
+    return "stripped";
+}
+/**
+ * True inside WSL. `procVersion` is injectable for tests; when given, it is
+ * the only thing consulted.
+ */
+export function isWsl(procVersion) {
+    if (procVersion !== undefined)
+        return /microsoft/i.test(procVersion);
+    if (process.platform !== "linux")
+        return false;
+    if (process.env.WSL_DISTRO_NAME)
+        return true;
+    try {
+        return /microsoft/i.test(fs.readFileSync("/proc/version", "utf-8"));
+    }
+    catch {
+        return false;
+    }
+}
+function shellQuote(s) {
+    return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+/**
+ * The Windows-side Cascade entry for a project that lives in WSL, filled in
+ * with the real paths, ready to paste. Cascade launches MCP servers on the
+ * Windows side even when the workspace is a WSL folder, and reads
+ * %USERPROFILE%\.codeium\windsurf\mcp_config.json there — never the WSL home
+ * `vexp setup` can write to. Environment variables in the entry do not cross
+ * wsl.exe, so VEXP_WORKSPACE is set on the command line inside WSL; `bash -lc`
+ * puts a version-managed node on PATH. We do not write Windows files from WSL
+ * (see the Windows + WSL2 docs) — we hand the user the exact entry instead.
+ */
+export function windsurfWslBridgeNote(workspaceRoot, binaryPath, mcpServerPath, distro = process.env.WSL_DISTRO_NAME ?? "<your distro>") {
+    const inner = mcpServerPath && fs.existsSync(mcpServerPath)
+        ? `VEXP_WORKSPACE=${shellQuote(workspaceRoot)} exec ${shellQuote(resolveNodeCommand())} ${shellQuote(mcpServerPath)}`
+        : `VEXP_WORKSPACE=${shellQuote(workspaceRoot)} exec ${shellQuote(binaryPath)} mcp`;
+    const entry = {
+        mcpServers: {
+            vexp: {
+                command: "wsl.exe",
+                args: ["-d", distro, "--", "bash", "-lc", inner],
+                alwaysAllow: VEXP_TOOLS,
+            },
+        },
+    };
+    return [
+        "Windsurf on Windows, project in WSL: Cascade starts MCP servers on the WINDOWS side and reads",
+        "%USERPROFILE%\\.codeium\\windsurf\\mcp_config.json there — the entry vexp just wrote in your WSL home is not the one it reads.",
+        "(Devin Desktop Next, the beta build, keeps its own copy: %USERPROFILE%\\.codeium\\windsurf-next\\mcp_config.json — same entry.)",
+        "Paste this on the Windows side (Windsurf: Settings → Cascade → MCP → view raw config), then quit and reopen Windsurf:",
+        JSON.stringify(entry, null, 2),
+        "Devin Local reads .devin/mcp_config.json from the project (written). If it runs on the Windows side as well, the same entry goes in %APPDATA%\\devin\\mcp_config.json.",
+        "Docs: https://vexp.dev/docs#windows-wsl",
+    ].join("\n");
+}
 export function configureAntigravityGlobal(binaryPath, mcpServerPath) {
     const cfgDir = path.join(os.homedir(), ".gemini", "antigravity");
     try {
@@ -2614,7 +2918,11 @@ export function installCodexHintHook(workspaceRoot, binaryPath) {
     let root = {};
     if (fs.existsSync(hooksJsonPath)) {
         try {
-            root = JSON.parse(fs.readFileSync(hooksJsonPath, "utf-8"));
+            // parseJsonc, not JSON.parse: every other config reader here is
+            // BOM-tolerant and this one was missed. Windows PowerShell 5.1 writes
+            // JSON with a UTF-8 BOM, and a user who edits .codex/hooks.json by hand
+            // there would have the hook silently left unregistered.
+            root = parseJsonc(fs.readFileSync(hooksJsonPath, "utf-8"));
         }
         catch {
             warnUnparseable(hooksJsonPath);

package/dist/cli.js

@@ -14,6 +14,7 @@ import { activateLicense, deactivateLicense, readLicenseLimits, readDeviceBlocke
 import { checkForUpdate } from "./update-check.js";
 import { ensureMcpHttpServer, mcpHttpStatus } from "./mcp-supervisor.js";
 import { installAutostart, uninstallAutostart, autostartStatus, migrateClaudeUnpinIfNeeded } from "./autostart.js";
+import { isWsl, windsurfWslBridgeNote } from "./agent-config.js";
 import { runServe } from "./serve.js";
 import { runDoctor } from "./doctor.js";
 import { socketPathFor } from "./socket-path.js";
@@ -65,13 +66,24 @@ program.hook("preAction", async (_thisCmd, actionCmd) => {
     // the parent, so we boot (or reuse) the parent daemon instead of spawning
     // a conflicting one for the child.
     const eff = findEffectiveWorkspace();
-    if (!eff)
+    // Say so. Bootstrapping is what replaces a stale daemon and takes over a
+    // stale MCP server on :7821, and it is silently skipped outside a
+    // configured workspace: a tester ran the command doctor had suggested from
+    // a package subdirectory of a monorepo, got no error and no takeover, and
+    // reasonably concluded the server had been replaced (tier-4 field report,
+    // 2026-09-05). Doing nothing quietly is the one outcome that cannot be
+    // told apart from success.
+    if (!eff) {
+        console.error(chalk.yellow(`  ⚠ no vexp workspace found from ${process.cwd()} — the daemon and the MCP server were NOT started or updated.`));
+        console.error(chalk.dim(`     vexp walks up for .vexp/manifest.json; run 'vexp setup' in the workspace root.`));
         return;
+    }
     let binaryPath;
     try {
         binaryPath = getBinaryPath();
     }
-    catch {
+    catch (err) {
+        console.error(chalk.yellow(`  ⚠ vexp-core binary not resolved (${err instanceof Error ? err.message : err}) — nothing was started or updated.`));
         return;
     }
     // Full bootstrap: daemon + MCP + autostart-if-needed. All three steps are
@@ -273,7 +285,12 @@ async function ensureBootstrap(workspaceRoot, binaryPath) {
     try {
         await ensureMcpHttpServer({ owner: "cli" });
     }
-    catch { /* non-fatal */ }
+    catch (err) {
+        // Non-fatal, but never silent: this is the step that replaces an MCP
+        // server left behind by an older install, and skipping it leaves every
+        // MCP client on the old build.
+        console.error(chalk.dim(`  ⚠ MCP HTTP server not started or taken over: ${err instanceof Error ? err.message : err}`));
+    }
 }
 /**
  * Start the vexp daemon and MCP HTTP server in the background.
@@ -724,6 +741,21 @@ program
             selectedNames = requested.map((n) => resolveAgentName(n));
             console.log(chalk.dim(`  Agents (from flag): ${selectedNames.join(", ")}`));
         }
+        else if (!process.stdin.isTTY) {
+            // No one is at the keyboard. This command is named as a remediation
+            // in doctor's own output, and an agent — or a CI step, or a script
+            // reading that line — cannot answer a prompt: it hangs until it is
+            // killed, which is worse than failing (field report, 2026-09-07: a
+            // tester followed doctor's advice and had to abandon the command).
+            // Configure what is detected, and say that is what happened.
+            selectedNames = allAgents.filter((a) => detectedNames.has(a.agent)).map((a) => a.agent);
+            if (selectedNames.length === 0) {
+                console.error(chalk.yellow("  No AI agent detected here and stdin is not a terminal — nothing to configure."));
+                console.error(chalk.dim("  Name them explicitly: vexp setup --agents \"Claude Code,Codex\""));
+                process.exit(1);
+            }
+            console.log(chalk.dim(`  Agents (detected, non-interactive): ${selectedNames.join(", ")}`));
+        }
         else {
             // Interactive selection
             console.log(chalk.bold("\n  Select AI agents to configure:\n"));
@@ -801,6 +833,16 @@ program
                         console.log(chalk.dim(`    ${mcpFile}`));
                     }
                 }
+                // Windsurf/Devin Desktop on Windows with the project in WSL: Cascade
+                // starts its MCP servers on the Windows side and reads the Windows
+                // profile, which nothing in WSL can write. Hand over the exact entry
+                // instead of letting the user discover the boundary the hard way.
+                if (isWsl() && result.agents.some((a) => a.agent === "Windsurf")) {
+                    console.log("");
+                    for (const l of windsurfWslBridgeNote(workspaceRoot, binaryPath, mcpServerPath).split("\n")) {
+                        console.log(chalk.yellow(`  ${l}`));
+                    }
+                }
                 // Files we refused to touch because they would not parse. This
                 // used to be a stderr line mid-spinner: it scrolled away, and a
                 // skipped settings.json silently cost the whole hook (field