vexp-cli 3.0.1 → 3.1.1

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";
 // ---------------------------------------------------------------------------
@@ -123,16 +124,26 @@ const AGENT_DETECTORS = [
     {
         agent: "Cursor",
         detectPath: ".cursor",
-        configFile: ".cursor/rules",
+        // Cursor reads a DIRECTORY of rules here (`.cursor/rules/*.mdc`); the
+        // file inside is ours. See `cursorRulesTarget` for the one exception.
+        configFile: ".cursor/rules/vexp.mdc",
         templateName: "cursor",
         mcpConfigFile: ".cursor/mcp.json",
     },
     {
         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",
@@ -293,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;
@@ -341,7 +358,8 @@ export function configureAgents(workspaceRoot, binaryPath, version, agentFilter,
         const filter = agentFilter.map((a) => a.toLowerCase());
         agents = agents.filter((d) => filter.includes(d.agent.toLowerCase()));
     }
-    for (const detector of agents) {
+    for (const detected of agents) {
+        const detector = withCursorTarget(detected, workspaceRoot);
         const configFilePath = path.join(workspaceRoot, detector.configFile);
         const alreadyExists = fs.existsSync(configFilePath);
         // Sweep the location we used to write to. For several releases the
@@ -413,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);
@@ -689,7 +717,8 @@ export function configureSelectedAgents(workspaceRoot, binaryPath, version, sele
     const results = [];
     const mcpConfigs = [];
     const writtenConfigFiles = new Set();
-    for (const detector of AGENT_DETECTORS) {
+    for (const detected of AGENT_DETECTORS) {
+        const detector = withCursorTarget(detected, workspaceRoot);
         if (!selectedAgentNames.includes(detector.agent))
             continue;
         // Create agent directory if it doesn't exist. Skip for file-based
@@ -762,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)
@@ -859,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;
@@ -936,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.
@@ -966,6 +1009,169 @@ export function readJsonConfigSafe(filePath) {
  *   {command: {path, args}}                         Zed
  *   {command: ["node", "…/mcp-server.cjs"]}         Kilo Code
  */
+/**
+ * The interpreter to write into an editor's MCP config for `mcp-server.cjs`.
+ *
+ * A bare `node` is resolved through the PATH of the process that spawns the
+ * server — and a VS Code / Cursor / Windsurf launched from the Dock, the Start
+ * menu or a desktop shortcut carries the login PATH, which on most developer
+ * machines has no nvm, Volta or Homebrew node in it. The server then dies with
+ * `spawn node ENOENT`, the editor lists no vexp tools, and nothing on our side
+ * logged anything (GitHub Copilot field report, 2026-08). Pin the node that is
+ * running us instead; the VS Code extension has done the same
+ * (`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;
+    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 */ }
+    }
+    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 {
+            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 {
+            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 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
+ * path. Such an entry may well work from a terminal and still fail inside a
+ * 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;
+    const e = entry;
+    let command = e.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 && !/[\\/]/.test(command);
+}
+/**
+ * Adopt a foreign entry only when it resolves AND pins its interpreter. Used by
+ * the GUI-editor writers (VS Code/Copilot, Cursor/Windsurf/Kiro/Trae, Zed),
+ * where a bare `node` is exactly the entry that fails; terminal agents
+ * (opencode, Claude Code) keep adopting a bare interpreter — it works there.
+ */
+function adoptableEntry(entry) {
+    return vexpEntryStillResolves(entry) && !isBareInterpreter(entry) && !isEditorExecutable(entry);
+}
 function vexpEntryStillResolves(entry) {
     if (!entry || typeof entry !== "object")
         return false;
@@ -996,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 */ }
 }
@@ -1115,7 +1363,49 @@ export function removeVexpSection(filePath) {
         return "absent";
     }
 }
-function appendOrCreate(filePath, content, version) {
+/**
+ * Where the Cursor rule goes, after clearing the way.
+ *
+ * Cursor reads `.cursor/rules/` as a directory of `.mdc` rules. vexp wrote a
+ * single FILE at `.cursor/rules` for several releases — read by nothing, and
+ * a file where Cursor wants a folder, so Cursor could not create its own
+ * rules either. On a project where the folder already existed, `vexp setup`
+ * then crashed with EISDIR reading the directory (field report, Windows /
+ * Cursor, 2026-08) after indexing and the MCP start had already succeeded.
+ *
+ * Our stale file is removed when it holds only our section. If a user put
+ * their own text in a `.cursor/rules` FILE we keep it and fall back to the
+ * legacy root `.cursorrules`, which Cursor still reads — the folder cannot
+ * exist while that file does.
+ */
+export function cursorRulesTarget(workspaceRoot) {
+    const legacy = path.join(workspaceRoot, ".cursor", "rules");
+    let isFile = false;
+    try {
+        isFile = fs.statSync(legacy).isFile();
+    }
+    catch {
+        /* absent, or a directory */
+    }
+    if (isFile) {
+        removeVexpSection(legacy);
+        if (fs.existsSync(legacy))
+            return ".cursorrules";
+    }
+    return path.join(".cursor", "rules", "vexp.mdc");
+}
+/** The detector with its Cursor target resolved for THIS workspace. */
+function withCursorTarget(d, workspaceRoot) {
+    return d.agent === "Cursor" ? { ...d, configFile: cursorRulesTarget(workspaceRoot) } : d;
+}
+export function appendOrCreate(filePath, content, version) {
+    // A directory where a file was expected. Reading it is EISDIR, and that
+    // aborted the whole setup once (the `.cursor/rules` folder above). The
+    // detectors no longer point at folders; if one ever does again, write a
+    // file inside it rather than crash on the user's machine.
+    if (fs.existsSync(filePath) && fs.statSync(filePath).isDirectory()) {
+        filePath = path.join(filePath, "vexp.md");
+    }
     if (!fs.existsSync(filePath)) {
         fs.mkdirSync(path.dirname(filePath), { recursive: true });
         fs.writeFileSync(filePath, content, "utf-8");
@@ -1213,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 {
@@ -1234,7 +1648,7 @@ approveKey = "alwaysAllow") {
     }
     const existing = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const targetCmd = useNode ? "node" : binaryPath;
+    const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
     const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
     const beforeServers = existing.mcpServers;
@@ -1258,7 +1672,7 @@ approveKey = "alwaysAllow") {
     // Another vexp install already left a working entry here — don't fight it.
     // Only the install path may differ: `envMatches` still gates on the
     // VEXP_WORKSPACE pin, so a moved or renamed project is repinned normally.
-    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+    if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
     const servers = existing.mcpServers ?? {};
     servers["vexp"] = {
@@ -1500,7 +1914,7 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
     }
     const existing = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const targetCmd = useNode ? "node" : binaryPath;
+    const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
     const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
     const beforeServers = existing.servers;
@@ -1520,7 +1934,7 @@ export function writeVsCodeMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot
     // Copilot branch, which is gated only on `.github/` existing. Only the
     // install path may differ — `envMatches` still gates on the VEXP_WORKSPACE
     // pin, so a moved or renamed project is repinned normally.
-    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+    if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
     const servers = existing.servers ?? {};
     servers["vexp"] = {
@@ -1658,7 +2072,7 @@ export function configureOpencodeMcp(workspaceRoot, binaryPath, mcpServerPath) {
     }
     const cfg = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const command = useNode ? ["node", mcpServerPath] : [binaryPath, "mcp"];
+    const command = useNode ? [resolveNodeCommand(), mcpServerPath] : [binaryPath, "mcp"];
     const env = { VEXP_WORKSPACE: workspaceRoot };
     const mcp = cfg.mcp ?? {};
     const prev = mcp["vexp"];
@@ -1699,7 +2113,7 @@ export function configureKiloMcp(workspaceRoot, binaryPath, mcpServerPath) {
     }
     const cfg = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const command = useNode ? ["node", mcpServerPath] : [binaryPath, "mcp"];
+    const command = useNode ? [resolveNodeCommand(), mcpServerPath] : [binaryPath, "mcp"];
     const env = { VEXP_WORKSPACE: workspaceRoot };
     const mcp = cfg.mcp ?? {};
     const prev = mcp["vexp"];
@@ -1733,7 +2147,7 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     }
     const settings = read.data;
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const targetCmd = useNode ? "node" : binaryPath;
+    const targetCmd = useNode ? resolveNodeCommand() : binaryPath;
     const targetArgs = useNode ? [mcpServerPath] : ["mcp"];
     const targetEnv = workspaceRoot ? { VEXP_WORKSPACE: workspaceRoot } : undefined;
     const beforeCs = settings.context_servers;
@@ -1752,7 +2166,7 @@ export function writeZedMcpConfig(p, binaryPath, mcpServerPath, workspaceRoot) {
     // Another vexp install already left a working entry here — don't fight it.
     // Only the install path may differ: `envMatches` still gates on the
     // VEXP_WORKSPACE pin, so a moved or renamed project is repinned normally.
-    if (removed.length === 0 && envMatches && vexpEntryStillResolves(previousVexp))
+    if (removed.length === 0 && envMatches && adoptableEntry(previousVexp))
         return false;
     const cs = settings.context_servers ?? {};
     cs["vexp"] = {
@@ -1795,7 +2209,7 @@ export function configureClaudeCodeGlobal(binaryPath, mcpServerPath, workspaceRo
     const beforeServers = config.mcpServers;
     const existing = beforeServers?.["vexp"];
     const useNode = mcpServerPath && fs.existsSync(mcpServerPath);
-    const desiredCommand = useNode ? "node" : binaryPath;
+    const desiredCommand = useNode ? resolveNodeCommand() : binaryPath;
     const desiredArgs = useNode ? [mcpServerPath] : ["mcp"];
     // Multi-session fix: do NOT pin VEXP_WORKSPACE on this user-scope entry.
     // Claude Code applies ~/.claude.json mcpServers to EVERY project, so a pinned
@@ -2960,7 +3374,17 @@ ${MANDATE_CORE}
 <!-- /vexp -->`;
 }
 function cursorTemplate(vars) {
-    return `## vexp rules for Cursor <!-- vexp v${vars.version} -->
+    // Cursor project rules are `.cursor/rules/*.mdc` with front matter;
+    // `alwaysApply: true` puts the rule in every chat without the agent having
+    // to pick it. A rule file that Cursor reads at all is new: for several
+    // releases vexp wrote a single FILE at `.cursor/rules`, a path Cursor never
+    // reads, and one that stopped Cursor from creating its rules folder.
+    return `---
+description: vexp code-graph orientation for this workspace
+alwaysApply: true
+---
+
+## vexp rules for Cursor <!-- vexp v${vars.version} -->
 
 ${MANDATE_CORE}
 <!-- /vexp -->`;